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. Won values are assumed to be additive, so each won subcontest adds its value to the contest result:

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

--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
  --> 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


--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

The following steps create a target instance, validate and import the GT file, generate its contest strategy, and apply that strategy to the instance allocation.

Importing requires an instance ID. To start with a new instance, give it a predictable handle and copy the returned id:

gt instance create handle=my_project name="My Project"

Check the syntax first. Continue when the returned warnings list is empty:

gt document lint-gt text=@<path-to-file.gt>

Then import the GT file into the instance. The default replace mode rebuilds the vector definitions addressed by the file.

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.

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>