Project layout

A project in AEL, the Agent Engineering Language, will be a folder of small source files, each with one job. Agents, nodes, edges, configuration and hooks will each have their 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.

A complete project

Preview syntax — may change before launch

support/
  main.ael                        # main main(): the program's entry point
  pack.ael                        # packages; may be empty
  metadata.ael                    # the project's name and settings
  src/
    application.config.ael
    validation.reuse.ael
    normalize.global.ael
    agents/support.agent.ael
    nodes/summarize.node.ael
    nodes/verify.node.ael
    edges/summary_to_verify.edge.ael
    auth.hook.ael
  prompts/summarize.md

ael init support (command names may change before launch) will create the three root files. Every other folder and file will be your choice.

The three root files

File	Holds
`main.ael`	`main main()`, the program's entry point. Exactly one, at the project root.
`pack.ael`	The manifest: the packages this folder and the folders below it use. Required at the root, even when it lists none.
`metadata.ael`	The project's name, description and settings. A package project will also name its package here.

One component per file

Every other source file will be named <name>.<role>.ael. It will declare exactly one component of that role, and the component will carry the file's name: summarize.node.ael will declare node summarize(…).

File	Declares	Holds
`<name>.agent.ael`	`agent <name>(…)`	An agent: a workflow with its nodes, edges, starting points and completion.
`<name>.node.ael`	`node <name>(…)`	A node: one business step, deterministic or model-driven.
`<name>.edge.ael`	`edge <name>(…)`	An edge: a typed connection from one node's output to another node's input.
`<name>.config.ael`	`config <name>(…)`	Typed configuration with defaults, locked into a snapshot for each run.
`<name>.hook.ael`	`hook <name>(…)`	A hook: authorization, auditing or cleanup attached before or after a component, function or statement.
`<name>.global.ael`	`global <name>(…)`	A global function, visible in its folder and every folder below it.
`<name>.reuse.ael`	`reuse <name>(…)`	A reusable function, available to a file that imports it by path.
`<name>.routes.ael`	`routes <name>(…)`	HTTP routes, a file role that the `server/http` package adds.

A name will be an AEL identifier: letters, digits and _, not starting with a digit, and not a keyword. Names will be case-sensitive, and a file whose component name does not match its file name will fail the check.

Sharing will follow three rules, and the check will enforce each of them:

Helper functions (fn) will stay private to the component that declares them and its extension files.
Global functions will be visible, without an import, in their own folder and every folder below it. normalize.global.ael in src/ will be callable from every file under src/.
Reusable functions will be available only to a file that imports them by path, in its header, from its own folder or a folder above it.

Preview syntax — may change before launch

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

node summarize(request: Str<4000>) -> Str<1000> {
    # validation() and normalize() can both be called here.
}

The node's body is a placeholder, as A first agent explains. When two shared functions have the same name, the one in the nearest folder will win. A file will never call a shared function from a sibling folder or from a folder below it.

Extension files

When a component needs more private helpers than fit in its file, you will move them to extension files in the same folder: support.agent.extended.ael, then support.agent.extended.2.ael and up. An extension file will hold only private fn helpers, and they will belong to that one component. main.ael will use main.extended.ael.

Every source file will have a fixed size limit, so files stay small and reviewable. Limits gives the exact limit.

Packages in a project

pack.ael will declare the packages a folder and the folders below it use. The root manifest will be required, and any folder will be able to add its own, so one part of a project can add a package without affecting the rest. The nearest manifest that declares a package will win.
pack.lock will be generated beside each pack.ael. It will record the exact versions, origins and fingerprints your builds use, so builds repeat, even offline. You will never edit it by hand.
.package/ will be generated beside each manifest that lists packages, and will hold the installed packages. It will not be part of your source: you will never edit it.

A file will name the parts of a package it uses in its header, for example refer server/http select get;, and every export it selects will have to be used. Using packages describes manifests, folder scopes and the lock file in full, and Private packages the packages you build and host yourself.

Prompts and other files

prompts/ will be the usual place for system prompts kept as files, one per prompt. It will be a convention, not a rule: a node will name its prompt file by path, wherever the file is in the project.

A complete project

The three root files

One component per file

Sharing functions

Extension files

Packages in a project

Prompts and other files