Files and roles — AEL documentation

In AEL, the Agent Engineering Language, a file's name will say what it holds. Agents, nodes, edges, configuration and hooks will each be a component in its own named file, so a project's structure will read at a glance from its file list.

Status

Planned for AEL Beta 0.0.1. AEL is not available yet.

Package names on this page are preview naming and may change before launch.

One component per file

Every source file except the root files and extension files will be named <name>.<role>.ael:

<name> will be an AEL name: letters, digits and _, not starting with a digit, and not a reserved keyword; see Syntax basics.
<role> will be one of the roles below, in lower case.
The file will declare exactly one component of that role, its primary, and the primary will carry the file's name.

File	Must declare	Refused
`summarize.node.ael`	`node summarize(…)`	`node billing(…)`, a second node, or none
`support.agent.ael`	`agent support(…)`	`fn support(…)` in place of the agent
`auth.hook.ael`	`hook auth(…)`	`hook authorize(…)`

Names will be case-sensitive, and the check will refuse two files whose names differ only in letter case, so a project will mean the same thing on every operating system.

The roles

Role	Declares	Holds
`agent`	`agent <name>(…)`	A workflow: its nodes and edges, where work starts, what completes it.
`node`	`node <name>(…)`	One business step: deterministic logic, or a model call with its tools.
`edge`	`edge <name>(…)`	A typed connection from one node's output to another node's input.
`config`	`config <name>(…)`	Typed, reusable configuration with defaults. See Configuration.
`hook`	`hook <name>(…)`	Authorization, auditing or cleanup around other code. See Hooks.
`global`	`global <name>(…)`	A shared function visible in its folder and below.
`reuse`	`reuse <name>(…)`	A shared function that a file imports by path.
`routes`	`routes <name>(…)`	HTTP routes, a role that the `server/http` package adds.

Functions and visibility explains global and reusable functions. A package will be able to add a role only when a manifest selects that package directly, and no package will be able to replace a built-in role or a root file.

The root files

Three files will sit at the root of every project, and only there:

main.ael will declare main main(), the program's only entry point. main will call your agents and functions and, in a service, mount its routes. A package project will keep a main.ael even when main does nothing.
pack.ael will be the manifest: a record of the packages the project uses, never code. A folder will be able to add its own pack.ael for its own packages; see Folder scopes.
metadata.ael will be a record of the project's name, description and settings.

Nothing will start on its own. Declaring an agent, a node or a set of routes will start no model call, timer or server: main will start what your program runs.

Inside a component file

A component file will hold an optional header, which will always come first, then the primary, any supporting types and any number of private helper functions.

Preview syntax — may change before launch

# src/nodes/summarize.node.ael
import "../validation.reuse.ael";

struct Summary {
    text: Str<1000>,
    urgent: bool,
}

node summarize(request: Str<4000>) -> Summary {
    let checked: Str<4000> = validation(request);
    return write_summary(checked);
}

fn write_summary(request: Str<4000>) -> Summary {
    # A private helper: only this component can call it.
}

The header will come before the first declaration. import "<relative path>"; will make a reusable function available, here validation. A header will also be able to name the exports of a package that the file uses, such as refer server/http select get;; every selected export will have to be used.
Helper functions (fn) will be private to the component. There will be no pub fn: to share a function, give it a file of its own as a global or reusable function. The body of write_summary above is a placeholder, as A first agent explains.

Extension files

When a component needs more private helpers than fit in its file, you will move them into extension files beside it:

Preview syntax — may change before launch

src/agents/
  support.agent.ael
  support.agent.extended.ael
  support.agent.extended.2.ael
  support.agent.extended.3.ael

An extension file will hold only private fn helpers and comments: no header, no primary, no types.
Its helpers will belong to that one component and will be able to call the component's other helpers; no other file will be able to call them.
It will have to sit in the same folder as its component. main.ael will use main.extended.ael, then main.extended.2.ael and up.
pack.ael and metadata.ael will take no extension files.

Limits gives the size limit that every file, including each extension file, will stay within.

Names that will fail the check

A file without a role, such as util.ael or global.ael.
An extra dot or an unknown role, such as billing.v2.node.ael or billing.service.ael.
A second entry point, such as app.main.ael, or a main.ael below the project root.
An extension numbered 1 or with a leading zero, such as support.agent.extended.1.ael.
An extension file with no component beside it, or in another folder.
A primary whose name differs from the file's, even only in letter case.

Generated files

Two generated items will appear beside a manifest, and you will never edit either:

pack.lock, the lock file, will record the exact packages a build used.
.package/ will hold the installed packages. It will not be source.