Configuration

A configuration file

A configuration will live in <name>.config.ael and declare exactly one config <name>(). It will return a struct whose fields are the settings, filled with their defaults.

# src/application.config.ael
struct Application {
    port: u16,
    team: Str<24>,
    escalation_email: Option<Str<64>>,
}

config application() -> Application {
    return Application(8080, "support", Option::None);
}

• Defaults will be checked values. A configuration will build its defaults from literal values, struct values and Option values, and it will be able to use its own private helper functions to do so, within strict limits.
• Reading configuration will do nothing else. Loading a configuration will read no file, environment variable or secret, open no connection and call no model. External values will be resolved later, when a run starts (see below).
• One definition, many uses. The same configuration will be able to serve main, several agents, nodes and edges, and the packages that accept it, and each instance will be able to receive its own values.

The exact form of a configuration file, including how its settings and defaults are written, will be confirmed when the syntax is final.

Settings inside a component

A component will also be able to carry its own settings, in a config { … } block of key: value; entries:

# src/nodes/summarize.node.ael
node summarize(input: Request) -> Summary {
    config {
        prompt: file("prompts/summarize.md");
        model: binding("primary_model");
        max_attempts: 2;
    }
    return write_summary(input);
}

The block will be a checked record of settings, not code, and it will be able to refer to a named configuration. Agents, nodes and edges describes the settings of nodes, edges and agents. How a component names a configuration file, and the full list of setting names, will be confirmed when the syntax is final.

Where values come from

A setting's value will be able to come from several layers. A higher layer will override a lower one, field by field:

• The order will always be the declared one. The order in which files are found will never decide a value.
• Two values for the same field at the same layer will be a conflict, and will be reported rather than resolved by chance.
• Environment variables, files and secrets will be references. The running program will resolve them when a run starts, within its own permissions, and will never read the environment as a whole. Secret values will never appear in your source, in compiled files or in routine logs.
• A missing optional value, a malformed value and a missing required value will be reported differently, so you can tell them apart.

What the check will refuse

• A field that the configuration does not declare.
• A required field that no layer sets.
• A value of the wrong type, or text longer than its field allows.
• Two layers of the same rank that set one field.
• Configurations that refer to each other in a cycle.

One snapshot per run

Before a run is admitted, its configuration will be resolved, validated and pinned. The run will keep that snapshot to the end, even if a file, a variable or a deployment setting changes while it runs.

• A change will apply to runs that start afterwards.
• If a new configuration fails validation, the last accepted one will stay in force.
• A field that can change during a long-running agent will say so, and the change will happen at a checked point, such as a restart.

What configuration will never do

• Raise a limit: CPU, memory, token and permission ceilings set by the deployment will stay as they are.
• Grant a permission: see Effects and capabilities.
• Change packages or project settings: packages will belong to pack.ael, and the project's name and settings to metadata.ael.
• Start work: configuration will have no side effects, and main will stay the program's only entry point.

Explaining configuration describes how you will see where each value of a configuration comes from.