rototo 0.1.0-alpha.2

Control plane for runtime configuration in application code.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

# Example: Control Structured LLM Agent Config Safely

This example models a structured LLM configuration that application code can
load at runtime while the workspace owns validation, selection rules, external
value files, and local policy.

Use this pattern when the value is not a scalar knob. LLM configuration usually
has a model, gateway, prompt, token limit, temperature, and local policy rules.
That should be schema-validated and reviewable as configuration.

## Production problem

An incident summary agent has three configurations:

- `local` for development;
- `standard` for most production accounts;
- `enterprise` for enterprise accounts.

The application resolves:

```text
llm-agent-config
```

and receives one structured object.

## Workspace shape

```text
config/
  rototo-workspace.toml
  schemas/
    context.schema.json
    llm-config.schema.json
  qualifiers/
    enterprise-accounts.toml
  variables/
    llm-agent-config.toml
    llm-agent-config-values/
      local.toml
      standard.toml
      enterprise.toml
  lint/
    llm-agent-config.lua
```

## Value schema

Create `schemas/llm-config.schema.json`:

```json
{
  "type": "object",
  "required": ["model", "gateway", "prompt", "max_output_tokens", "temperature"],
  "properties": {
    "model": { "type": "string" },
    "gateway": { "type": "string" },
    "prompt": { "type": "string" },
    "max_output_tokens": { "type": "integer", "minimum": 1 },
    "temperature": { "type": "number", "minimum": 0, "maximum": 2 }
  },
  "additionalProperties": false
}
```

The schema is the contract application code can rely on.

## Variable

Create `variables/llm-agent-config.toml`:

```toml
schema_version = 1

[variable]
description = "LLM settings for the incident summary agent"
schema = "../schemas/llm-config.schema.json"

[variable.lint]
path = "../lint/llm-agent-config.lua"

[variable.env._]
value = "standard"

[variable.env.dev]
value = "local"

[variable.env.prod]
value = "standard"

[[variable.env.prod.rule]]
description = "Enterprise accounts get the larger agent configuration"
qualifier = "enterprise-accounts"
value = "enterprise"
```

The variable file stays focused on the application contract and selection
rules. The large values live in separate files.

## External values

Create `variables/llm-agent-config-values/enterprise.toml`:

```toml
[value]
model = "gpt-5"
gateway = "openai"
prompt = "Summarize the incident for an enterprise support workflow."
max_output_tokens = 5000
temperature = 0.2
```

Create similar files for `local` and `standard`.

## Policy lint

Create `lint/llm-agent-config.lua`:

```lua
function lint_value(value)
  if value.value.max_output_tokens > 5000 then
    return {
      {
        message = "value " .. value.name .. " exceeds the token budget",
        help = "Use 5000 or fewer output tokens."
      }
    }
  end
  return {}
end
```

The schema validates shape. Custom lint enforces local policy.

## Verify the behavior

```sh
rototo resolve config/ -v llm-agent-config \
  --env prod \
  --context '{"account":{"plan":"enterprise","seats":250}}' \
  --json
```

Expected selected key:

```text
enterprise
```

## Tests to keep

Test the default production path, enterprise production path, and development
path. Also include one lint fixture or test change that proves policy catches a
value above the token ceiling.

## Fit

Use this when application code needs a structured object and the structure
should be validated before release.

Do not use this pattern for a single scalar setting. A primitive variable is
clearer for small knobs.

## Related docs

- [How to Move Large Values Out of TOML](how-to-move-large-values-out-of-toml.html)
- [How to Enforce a Config Policy](how-to-enforce-a-config-policy.html)
- [Variable File Reference](variable-reference.html)
- [Value Types Reference](value-types-reference.html)