agentic-embedded-lab

Agent-native experimentation, modeling, and validation for embedded systems

Why AEL · Quick start · Architecture · Plugins · Continuous simulation · Controlled evolution · MCP · Vision

English | 简体中文

[!IMPORTANT]
AEL is currently a 0.2.0.dev0 Development Preview. The software and
simulation gates have passed in a qualified environment, but no current
five-board differential or instrument-calibration evidence exists. A
simulator pass is never promoted into a hardware-equivalence claim.

Why AEL

Embedded engineering does not live inside one codebase or one simulator. A
single failure can cross firmware, RTOS scheduling, peripheral protocols,
power integrity, thermal behavior, wireless networks, RF, and electromagnetic
geometry. Agents need more than shell access: they need a lab that knows what
can be executed, what was observed, and what the result is allowed to prove.

Agentic Embedded Lab (AEL) is that control plane. It turns agent intent into
typed experiments, routes each part to explicit execution backends, coordinates
multi-rate simulation, and stores replayable evidence with fidelity boundaries.

Design mantra: Everything is a plugin. Every run is evidence. Every
promotion is gated.

What works today

• Strict versioned contracts for problems, systems, experiments, models,
  validation envelopes, events, claims, and evidence.
• Capability-aware routing across Zephyr builds, Renode, ngspice,
  OpenModelica/OMSimulator, ns-3, openEMS, local control-plane tests, and
  hardware-validation workers.
• Deterministic multi-rate scheduling, checkpointing, safe-stop behavior, FMI
  2.0 Co-Simulation proxies, SSP export, and event-driven openEMS caching.
• SQLite/local CAS and PostgreSQL/S3-compatible storage with consistent Run,
  Model, Claim, Worker lease, and Evidence semantics.
• CMSIS-SVD and SystemRDL import plus grounded OpenAI/Anthropic structured model
  generation, typed Hardware Behavior IR, Renode C# emission, and an offline OCI
  sandbox boundary.
• Twenty-four faulty/fixed benchmark pairs spanning build, firmware/RTOS,
  digital protocols, power, analog, thermal, network, RF, and EM mechanisms.
• An OIDC/mTLS/Envoy/Worker server topology with lease recovery, cancellation,
  storage outage, migration, and restart acceptance.
• Five reference Lab Worker board definitions and allow-listed instrument
  drivers, intentionally marked unverified until physical evidence exists.

Architecture

flowchart TB
    A["Codex · Claude · other agents"] --> I["MCP · CLI · HTTP · SDK"]
    I --> C["AEL control plane"]
    C --> R["Capability + problem router"]
    C --> P["Experiment planner"]
    C --> M["Model registry + governed lifecycle"]
    R --> O["FMI 2.0 / SSP orchestrator"]
    P --> O
    M --> O

    O --> Z["Zephyr build"]
    O --> RE["Renode"]
    O --> NG["ngspice"]
    O --> OM["OpenModelica / OMSimulator"]
    O --> NS["ns-3"]
    O --> OE["openEMS"]
    O -. claim-scoped validation .-> HW["Lab Workers / real hardware"]

    Z --> E["Events + Evidence Bundle"]
    RE --> E
    NG --> E
    OM --> E
    NS --> E
    OE --> E
    HW --> E
    E --> L["Compare · replay · explain · learn"]
    L --> C

The CLI is the behavior source. HTTP and MCP are thin adapters to the same
AelService; neither exposes an arbitrary shell, Renode Monitor, raw SCPI, or
paths outside the workspace. See Architecture,
Contracts, and Security.

Everything is a plugin

AEL treats the lab as a graph of replaceable capabilities instead of a single
simulator. The current code exposes explicit extension seams; stable out-of-tree
package discovery is a planned public API, not a claim about 0.2.0.dev0.

Backends communicate through the versioned ael.dev/backend/v1 JSON-lines
protocol. An adapter command or OCI image is administrator-configured; an agent
cannot supply an executable. See the plugin and evolution vision.

Continuous simulation-in-the-loop

AEL is designed for a lab that keeps running after a single chat turn. A
campaign repeatedly converts observations into experiments, executes the
smallest sufficient fidelity, compares candidates, records regressions, and
queues the next hypothesis.

flowchart LR
    O["Observe"] --> H["Hypothesize"] --> P["Plan"] --> X["Execute"]
    X --> A["Analyze"] --> E["Store evidence"] --> C["Compare / replay"]
    C --> O
    A -->|failure| F["Modify firmware, experiment, or model"] --> P
    A -->|candidate passes| G["Promotion gate"] --> O

0.2.0.dev0 already provides deterministic runs, asynchronous workers,
checkpoint/replay, comparison, evidence storage, and scheduled/nightly
reproduction. The always-on campaign controller, experiment-budget policy,
and fleet-scale scheduling are the next layer. They will reuse the same
contracts; they will not bypass fidelity or release gates.

Controlled learning and self-evolution

“Self-evolving” must not mean “the agent edits a model and declares itself
correct.” AEL uses an evidence-driven, reversible path:

1. Ground a candidate in hashed SVD, SystemRDL, datasheet, errata, driver,
   HAL, or reference traces.
2. Generate strict Hardware Behavior IR and a receipt without storing API
   keys or untrusted host commands.
3. Sandbox generated code with networking off, read-only inputs, and CPU,
   memory, and time limits.
4. Conformance-test with independent layout, compile, property, driver, and
   reference-trace checks.
5. Shadow-run the candidate against recorded experiments and detect
   regressions before it becomes selectable.
6. Promote or roll back through signed model states. An agent may reach only
   conformance_validated; hardware and production states require independent
   evidence and a human actor.

This creates continual learning from evidence while preventing self-approval,
silent model substitution, and unbounded production mutation.

Quick start

Python 3.12 is required.

git clone https://github.com/eust-w/agentic-embedded-lab.git
cd agentic-embedded-lab

python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev,mcp,server,worker,modeling]'

ael doctor
ael inspect
ael classify examples/problems/uart-ring-buffer.yaml
ael validate examples/experiments/synthetic-smoke.yaml
ael run examples/experiments/synthetic-smoke.yaml

The smoke experiment intentionally uses the test-only synthetic backend. Its
Evidence Bundle is marked synthetic / unverified; it cannot become a simulator
or hardware Claim.

Run the complete local software acceptance on a qualified Linux/container
environment:

scripts/run-local-software-acceptance.sh

This builds the pinned Zephyr and backend environments, runs all 24 faulty/fixed
pairs, the FMI/SSP five-domain experiment, 20-run determinism, the Compose
recovery topology, and the simulation and software gates. Missing tools block
the run; no mock replacement is allowed.

Connect an agent with MCP

python -m pip install -e '.[mcp]'
AEL_WORKSPACE=/absolute/path/to/agentic-embedded-lab ael-mcp

{
  "mcpServers": {
    "agentic-embedded-lab": {
      "command": "/absolute/path/to/.venv/bin/ael-mcp",
      "env": {
        "AEL_WORKSPACE": "/absolute/path/to/agentic-embedded-lab"
      }
    }
  }
}

The nine domain tools let an agent inspect, classify, plan, start, query,
compare, generate a missing model, and validate that model. Large event streams
are paged instead of being injected into the agent context. See
MCP configuration.

Experimental Aether Native companion

The repository also contains Aether Native, an experimental
local desktop shell and plugin-runtime prototype. It is useful for exploring
agent UI, plugin registry, memory, streamed events, and review flows, but it is
not part of the production gate. Provider keys are environment-only, arbitrary
HTTP/Agent shell execution is disabled, and in-process evolution is off by
default.

Executable benchmark

Every case includes faulty and fixed assets, an oracle, a deterministic seed,
raw mechanism evidence, a structured causal chain, and an explicit “not proven”
boundary. Digital cases 4–17 currently use a functional firmware mechanism
dispatcher and bridge; they do not establish complete peripheral-register,
RTOS-scheduling, electrical, or silicon equivalence.

Evidence and release gates

Claims are scoped to a model version, hardware revision, evidence set, fidelity,
and Validation Envelope. Outside that envelope, the status is unverified.
See Production readiness.

Roadmap

• Strict experiment, evidence, model, and Claim contracts
• Five simulation domains plus Zephyr build and FMI/SSP orchestration
• Agent-facing MCP, server/Worker topology, and governed model generation
• Stable out-of-tree plugin SDK and signed community registry
• Always-on simulation campaign controller with budgets and stop policies
• Regression-driven model selection and evidence-aware experiment curriculum
• Hardware differential calibration for the five reference platforms
• Signed Validation Envelopes and production-approved capability packages

Robotics, automotive, IoT, industrial control, medical devices, and other
verticals belong in optional adapters and examples. The core contracts stay
general to embedded systems.

Contributing and security

Contributions are welcome for adapters, model packages, benchmark mechanisms,
oracles, evidence tooling, and documentation. Start with
CONTRIBUTING.md. Please report vulnerabilities privately as
described in SECURITY.md; do not include credentials or sensitive
lab details in public issues.

License

The AEL core is licensed under Apache-2.0. GPL and other third-party
simulators are not bundled into the core Python distribution; backend images
and adapters retain their upstream license obligations. See
Third-party notices.