ACEL — Agent Capability Expression Language

A small declarative language for defining AI agents, built on the trued five-aspect basis of the Rectified Pentachoron Framework (RPF).

An agent is exactly five aspects plus a global autonomy modal:

Aspect	Corners	Neglect pathology
telos	the objective pursued	aimless reactivity
world_model	present apprehension of environment state	ungrounded action (hallucination)
memory	state retained across time	amnesia (re-solving)
deliberation	mapping situation → action	thrashing (myopia)
actuation	effecting change on the environment	paralysis (all talk)

autonomy is not an aspect. It qualifies every aspect uniformly (supervised perception, supervised deliberation, …), so it is carried as a scalar on the agent, not as a sixth block. This is the central correction that distinguishes ACEL from flat "list the agent's parts" schemas — see CHANGELOG.md for the full true-up.

Install

pip install -e .
# or run without installing:
PYTHONPATH=src python -m acel.cli check examples/research_assistant.acel

Example

agent research_assistant {
  autonomy: SUPERVISED

  telos {
    goal: ACHIEVE "comprehensive_report" AND MAINTAIN "factual_accuracy"
    priority: HIGH
  }

  world_model {
    grounding: REQUIRED
    percept web_search { type: RETRIEVE protocol: MCP freshness: 1h }
  }

  memory {
    type: HYBRID
    store short_term { capacity: 10000 ttl: 1h retrieval: RECENCY }
    store long_term  { capacity: 1000000 retrieval: RELEVANCE }
  }

  deliberation {
    mode: HYBRID
    plan   { strategy: HIERARCHICAL depth: 4 replan_on_failure: true }
    decide { strategy: MONTE_CARLO_TREE_SEARCH risk: 0.4 explore: 0.2 }
    reflect { trigger: ON_ERROR over: long_term }   ; deliberation over memory
  }

  actuation {
    effect document_store { type: MODIFY protocol: REST permissions: READ, WRITE }
  }

  oversight high_stakes { trigger: UNCERTAINTY_ABOVE 0.3 action: ASK_APPROVAL escalate_to: lead }
}

CLI

acel parse FILE     parse and print the AST
acel lint  FILE     validate only; non-zero exit on errors
acel check FILE     validate + RPF conformance report (default)

check prints, for a valid document:

RPF conformance — trued AI-agent basis

  telos         present  neglect: aimless reactivity (answers, pursues nothing)
  world_model   present  neglect: ungrounded action (confident hallucination)
  memory        present  neglect: amnesia (Sisyphean re-solving)
  deliberation  present  neglect: thrashing (myopic stimulus-response)
  actuation     present  neglect: paralysis (reasons but cannot act)

  basis complete: True

Validation rules

Hard errors:

• E1 — direction split: percepts must be RETRIEVE/OBSERVE; effects must be EXECUTE/MODIFY. Mixing input and output on one surface is the conflation the trued basis removes.
• E2 — reflect.over must name a declared memory store (reflection is deliberation over memory, not free-standing).
• E3 — enum membership and numeric ranges.
• E4 — identifiers unique within their kind.

Warnings:

• W1 — grounding: NONE under a MAINTAIN-accuracy telos: the weak vertex (world_model) is left unbound.
• W2 — oversight escalate_to under autonomy: FULL_AUTONOMOUS: no supervisor exists to receive the escalation.

Layout

src/acel/       lexer, parser, ast, validator, conformance, cli
grammar/        acel.abnf         (the corrected grammar)
examples/       *.acel            (incl. a deliberately invalid file)
tests/          unittest suite    (25 tests)

Run the suite:

PYTHONPATH=src python -m unittest discover -s tests

Deploying in an agent platform

ACEL is a declarative contract and a policy gate, not a runtime. In a typical enterprise agent stack (clients and surfaces on top; an agent loop with tools, MCP, and memory; an edge and control plane; an API gateway or router; models; back-end systems) ACEL is not a new layer — it is the spec that binds the layers you already run, and it enters at two seams.

flowchart TB
  subgraph stack["Enterprise agent stack"]
    direction TB
    C["Clients and surfaces<br/>chat · web · IDE · agents"]
    L["Agent loop · tools/MCP · memory<br/>think · act · observe"]
    CP["Edge + control plane<br/>WAF · mTLS · portal · policies"]
    G["Gateway / router<br/>task · policy · security · finops · audit"]
    M["Models<br/>frontier · open-weight"]
    B["Back-end systems<br/>core services · data platform"]
    C --> L --> CP --> G --> M --> B
  end
  A["ACEL manifest<br/>telos · world_model · memory<br/>deliberation · actuation<br/>+ autonomy modal"]
  A -. "author-time: acel lint + conformance (CI gate)" .-> CP
  A -. "run-time: compile autonomy + oversight to policy" .-> G
  A -. "binds runtime" .-> L
  classDef acel fill:#0F6E56,stroke:#04342C,color:#ffffff;
  classDef seam fill:#FAEEDA,stroke:#854F0B,color:#412402;
  class A acel;
  class CP,G seam;

Loading

The five aspects plus the autonomy modal map almost one-to-one onto that stack:

ACEL clause	Binds to
telos	business intent → gateway task routing
world_model.percept (RETRIEVE/OBSERVE) + grounding	tools/MCP (read) + memory (RAG); grounding level becomes a control-plane policy
memory	memory tier (RAG, vectors, persistent)
deliberation (mode/plan/decide)	the agent loop; mode/decide may also hint the router (frontier vs open-weight)
actuation.effect (EXECUTE/MODIFY) + permissions	tools/MCP (write) → gateway → back-end
autonomy modal + oversight	edge/control plane (policies) and gateway (policy, security, cost, audit)

Author-time (shift-left). The .acel file is the source-of-truth contract for a registered agent. Run acel lint (and the conformance check) in CI; an agent that mislabels a read tool as a write (E1), leaves reflection unbound (E2), or omits a grounding level does not ship. One valid manifest per catalog entry — versioned, diffable, reviewable. Governance as code.

Run-time (enforce). The control plane compiles the manifest's autonomy modal and oversight triggers into gateway rules. The mapping is close to verbatim: COST_ABOVE → budget/FinOps, IRREVERSIBLE_ACTION → approval, UNCERTAINTY_ABOVE → halt or escalate, effect permissions → write-scopes enforced by the gateway (e.g. mTLS/WAF), and every action keyed to the manifest version for audit. The percept/effect split hands the gateway a clean read-versus-write allow-list for free.

The reason this is a fit rather than a bolt-on: ACEL already carries the three primitives a control plane needs — read (percept), write (effect), approve (autonomy/oversight) — as first-class syntax, so the spec and the policy are the same artifact.

Out of scope: threshold calibration

ACEL expresses that an oversight threshold exists and what happens when it trips (UNCERTAINTY_ABOVE 0.3 → ASK_APPROVAL). It deliberately says nothing about what the number should be for a given action or context. Choosing and moving those thresholds — a risk/confidence calibration layer — is a separate concern that plugs into the oversight seam as a policy input. No such calibration model is included in this repository, and none is covered by this project's licence (see below). ACEL is the open contract and the gate; any scorer that makes the gate context-aware is a distinct component under its own terms.

Licence and scope

This project — the ACEL language, its grammar (grammar/acel.abnf), and the reference toolchain (lexer, parser, validator, conformance checker, CLI) — is released under the MIT Licence; see LICENSE. Use it, embed it, compile ACEL into your own control plane, ship products on top of it.

Two clarifications, since ACEL is meant to be given back cleanly while sitting next to proprietary work:

• What MIT covers here: the language definition and the code in this repository. The grammar and the trued five-aspect basis are open by design.
• What it does not cover: any threshold-calibration or risk-scoring model that attaches to the oversight seam (see above) is a separate work, is not part of this repository, and is not licensed under these terms. MIT grants no patent licence and no trademark rights; names and marks associated with downstream products are reserved to their owners.

Contributions are accepted under the same MIT terms as the rest of the project.

Patent non-assertion

MIT grants no patent rights. For implementers who want more certainty, a narrow, irrevocable patent non-assertion covenant covering the ACEL language only is provided in PATENTS.md. It is a promise not to assert patents necessarily infringed by implementing the specification; it is not a patent licence. It explicitly does not cover the threshold-calibration / risk-scoring layer described above, which is reserved. The file is a reviewed-before-use draft with bracketed fields to complete.

Provenance

The five-aspect basis is the RPF true-up of the AI-agent domain: the original ten-section sketch reduced to five vertices plus one modal parameter and one derived capability. world_model is the vertex the sketch omitted and the basis's weak vertex — consistent with the regularity that the weak vertex lands on the domain's live controversy (here, grounding and hallucination).

A.M.D.G.