Import a GT file and generate a strategy

Start with the instance name, handle, and committed recipe. Then introduce the vector definitions with --vectors:

--name My Project
--handle my_project
--committed_recipe Project allocation

--vectors

--name sets the display name. --handle sets the short name used in commands. --committed_recipe names the vector used to derive the instance allocation.

A vector definition starts with a name. Lines indented below the name define that vector.

The examples below cover components, ingredients, contest values, aliases, and executability.

Components

Use --> to add an outgoing contribution from the vector:

Delivery plan
  -->Research 0.4
  -->Implementation 0.6

This records a contribution of 0.4 from Delivery plan to Research and 0.6 from Delivery plan to Implementation.

Ingredients

Use ^-- to add a base ingredient. Each ingredient has a weight:

Release recipe
  ^--Engineering 0.7
  ^--Documentation 0.2
  ^--Coordination 0.1

Contest values

A bare indented line declares a subcontest. Its trailing number is that subcontest's value:

Priority contest
  Reliability 0.4
  Performance 0.3
  Usability 0.3

This declares three subcontests: Reliability, Performance, and Usability. Their values are 0.4, 0.3, and 0.3.

Omitting ingredient weights or contest values

The ingredient weights and contest values together describe the recipe. If you omit some ingredient weights or contest values, the system attempts to fill them in evenly to target a total of 1.0.

Allocation
  ^--Fixed input 0.2
  Option A 0.3
  Option B
  Option C

Fixed input and Option A account for 0.5 between them. The remaining 0.5 is divided equally between Option B and Option C, giving each a value of 0.25.

Aliases

Use *-- to give a vector another name:

Customer retention
  *--retention
  *--keepers

Executability

Executability sets the efficiency of work directed at a vector itself, rather than at one of its tasks. It defaults to 1.0; set it explicitly with --executability:

Reliability
  --executability 0.6

With an executability of 0.6, an hour spent working directly toward Reliability produces 0.6 hours of progress.

The following is an example of a complete GT file. Only the sections discussed above are strictly required by the parser.

--name Hello World

--handle hello_world

--imports
some_other_doc
another_reference_doc

--coordinates
hello world

--philosophy
hello world
  b
    this is my first gt file

--committed_recipe hello world committed recipe

--vectors

hello world committed recipe
  ^--recipe one 0.2
  ^--ingredient two 0.1
  contest one 0.3
  contest two 0.2
  contest three 0.2

vector one
  ===some_other_doc__vector one
  --> contest two 0.3
  --> ingredient two 0.2
  --> vector two 0.5

vector two
  *--my second vector
  -->vector one 0.15
  -->hello world committed recipe 0.3

recipe one
  ^--contest one 0.8
  ^--vector two 0.2
  --> contest one 0.1

contest one
  subcontest one
  subcontest two
  --> vector two 0.2
  ^--my ingredient 0.1
  subcontest three
  subcontest four

contest two
  *--super cool contest
  ===another_reference_doc__super cool contest


--tasks
  - instantiate this file 1
    o--direct instance import 1
      - gt instance create name="Hello World" 1
      - gt instance import-gt <instance id> materialization=patch text=@/path/to/this/file 1
    o--instantiate a document object 1::1
      - gt document create text=@/path/to/this/file 1
      - gt document instantiate <document-id> 1

Importing requires an instance ID. If you are starting from a new instance, create it first and copy the returned id:

gt instance create name="Your Instance Name Here"

Import the GT file into the instance. The default replace mode updates the vectors named in the file without modifying vectors omitted from it.

gt instance import-gt <instance-id> text=@<path-to-file.gt>

The import runs as a background job. Use gt status <job-id> to confirm it finished successfully.

To check the syntax first, run gt document lint-gt text=@<path-to-file.gt>. Import when the returned warnings list is empty.

After the import succeeds, retrieve the instance and copy its committed_recipe value:

gt instance get <instance-id>

Generate a strategy for the committed recipe:

gt contest generate <committed-recipe-uuid> asynchronous=false new_quantiles=true

Strategy generation updates the recipe vector. Copy the generated recipe into the instance allocation, then inspect the allocation:

gt vector commit-to-instance <committed-recipe-uuid>
gt instance get-allocation <instance-id>