aiel-runtime 0.5.2

AIEL Runtime adapter used by the Execution Plane to load and execute user projects.

AI Execution Layer Runtime (aiel-runtime)

aiel-runtime is the execution adapter used by the Execution Plane (EP) to load and run user projects from immutable snapshots. It provides a stable, versioned runtime entrypoint that:

1. loads a project snapshot (downloaded by EP from the Data Plane),
2. imports entry_point.py (registering exports via aiel-sdk decorators),
3. validates contracts (signatures, export consistency),
4. executes exported handlers (tools / agents / flows / routers / HTTP / MCP).

This repository is intentionally focused on runtime orchestration and invocation, not on developer ergonomics. Developer-facing contracts live in aiel-sdk.

---

Why this exists

A production Execution Plane needs a deterministic way to execute user code that is:

• versioned (reproducible across time),
• contract-driven (predictable invocation shape),
• isolated (sandboxed by EP),
• observable (structured outputs and error taxonomy),
• portable (runs as a subprocess or container entrypoint).

aiel-runtime is that adapter.

---

Key features

• Single runner entrypoint: python -m aiel_runtime.runner
• Contract validation via aiel-sdk
• Deterministic execution with lockstep runtime/SDK versioning
• Describe + Invoke protocol (stdin JSON → stdout JSON)
• Snapshot-first execution model (EP controls downloads/caching)
• Designed for EP sandbox enforcement (CPU/memory/timeouts/network/secrets)

---

Repository layout (src-layout)

This repo uses a src/ layout to prevent accidental import shadowing and to support editable installs reliably.

---

Installation

Local development (editable)

python -m pip install -U pip
python -m pip install -e .

Production (pinned)

Pin versions for deterministic behavior:

python -m pip install "aiel-runtime==X.Y.Z"

Optional curated bundles (if your runtime image includes these):

python -m pip install "aiel-runtime[ai]==X.Y.Z"

Recommended policy: lockstep versions aiel-runtime==X.Y.Z depends on aiel-sdk==X.Y.Z.

Runtime entrypoint

The Execution Plane runs:

python -m aiel_runtime.runner

EP must provide:

• EP_FILES_ROOT: absolute path to a snapshot folder containing entry_point.py.

Example:

export EP_FILES_ROOT=/tmp/ep/snapshots/<tenant>/<project>/<release>/files

Snapshot expectations At minimum, the snapshot must contain:

• entry_point.py (required)
• any local modules imported by entry_point.py (e.g., tools/, agents/, mcp_server/)

A typical snapshot layout:

files/
  entry_point.py
  tools/
    core.py
  agents/
    main.py
  mcp_server/
    core.py
  requirements.txt   # optional (runtime images should be pre-baked)

Dependency installation at runtime is intentionally not supported. Runtime images must include curated dependencies up-front.

Runner protocol (stdin → stdout)

aiel-runtime is a small JSON protocol engine.

Describe exports

stdin

{ "schema_version": "v1", "action": "describe" }

stdout

{
  "schema_version": "v1",
  "ok": true,
  "result": {
    "sdk_version": "X.Y.Z",
    "runtime_version": "X.Y.Z",
    "tools": ["normalize_email"],
    "agents": ["collect_personal_data"],
    "flows": ["driver_onboarding"],
    "routers": ["route_driver_flow"],
    "http_handlers": [{"method":"POST","path":"/driver/onboard"}],
    "mcp_servers": [{"name":"driver_support","tools":["lookup_existing_driver"]}]
  }
}

Invoke an export

stdin

{
  "schema_version": "v1",
  "action": "invoke",
  "kind": "tool",
  "name": "normalize_email",
  "payload": {
    "email": "[e-mail]",
    "name": "Test",
    "ctx": {
      "request_id": "req_123",
      "tenant_id": "t_1",
      "workspace_id": "w_1",
      "project_id": "p_1"
    }
  }
}

stdout

{ "schema_version": "v1", "ok": true, "result": { "email": "[e-mail]" } }

Error response

stdout

{
  "schema_version": "v1",
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found: normalize_email"
  }
}

Execution model

Runtime load sequence:

• Reset registry (defensive against warm process reuse)
• Add EP_FILES_ROOT to sys.path
• Import entry_point (registers exports via decorators)
• Validate contracts (signatures and export invariants)
• Execute describe or invoke

Export kinds

Supported kind values (current):

• tool — callable signature: tool(ctx, payload)
• agent — callable signature: agent(ctx, state)
• flow — callable signature: flow(ctx, input) OR graph_builder() returning a compiled graph with ainvoke
• router — callable signature: router(ctx, state)
• (http, mcp are typically served by EP; runtime can expose metadata via describe)

EP is responsible for mapping HTTP/MCP requests into invoke payloads.

Execute a handler (Lambda-style)

You can execute a module handler using the AWS Lambda-style signature (event, context):

def aiel_handler(event, context):
    ...

stdin:

{ "schema_version": "v1", "action": "execute", "handler": "app.aiel_handler", "event": {} }

CLI:

python -m aiel_runtime.runner --action execute --handler app.aiel_handler --event '{}'

Default handler:

python -m aiel_runtime.runner --action execute --event '{}'  # uses entry_point.aiel_handler

Invocation Context Injection

The control plane (e.g., CLI) should inject identity and workspace metadata into ctx: Local credential discovery is disabled by default; enable it with --auto-ctx or AIEL_AUTO_CTX=1. Pretty JSON output is optional; enable it with --pretty or AIEL_PRETTY_JSON=1.

{
  "schema_version": "v1",
  "action": "execute",
  "handler": "entry_point.aiel_handler",
  "event": {},
  "ctx": {
    "workspace_id": "w_123",
    "project_id": "p_123",
    "user_id": "u_123",
    "trace_id": "trace_123"
  }
}

Versioning and compatibility

Runtime version runtime_version identifies the runner behavior and dependency bundle.

SDK version

sdk_version identifies the contract surface expected by the user project.

Recommended compatibility policy:

• aiel-runtime==X.Y.Z depends on aiel-sdk==X.Y.Z
• Data Plane manifest includes both runtime and sdk_version
• EP allowlists runtime values and uses (runtime, sdk_version, file hashes) for cache keys.

Security model

aiel-runtime assumes EP enforces isolation. At minimum, EP should provide:

• process/container isolation
• read-only snapshot filesystem
• strict CPU/memory/timeouts
• deny-by-default network egress (unless explicitly enabled)
• controlled secret injection via context (do not expose host env to user code)

Runtime performs defense-in-depth checks where practical (contract validation, error normalization). Hard security boundaries belong in EP.

Production note (Cloud Run / Images)

If your entrypoint imports aiel, bake aiel-cli into the runtime image/venv so imports succeed during cold start.

Development

Run the runtime directly (fast local iteration)

This runs the same execution engine used by EP, but without auth and without the Data Plane. You point the runtime at a local folder that already contains the files.

1) Prerequisites

Your local folder must contain at least:

• entry_point.py (required)
• any modules imported by entry_point.py (e.g. tools/, agents/, mcp_server/)

my-project/
  entry_point.py
  tools/
    core.py
  agents/
    main.py

2) Install runtime + SDK

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

python -m pip install -U aiel-runtime aiel-sdk

If your entry_point.py imports aiel, install it in the same environment:

python -m pip install -U aiel-cli

If you use optional facades locally (LangGraph/LangChain/LangSmith), install extras. Important (zsh): quote extras:

python -m pip install -U "aiel-sdk[all]"

3) Run describe locally

From the project folder (where entry_point.py exists):

echo '{"schema_version":"v1","action":"describe"}' | python -m aiel_runtime.runner --files-root "$PWD" --no-traceback

Or with flags (defaults to $PWD if entry_point.py exists):

python -m aiel_runtime.runner --action describe --no-traceback

You should get something like: { "ok": true, "result": { "tools": ["..."], "agents": ["..."], "flows": ["..."], "routers": ["..."], "http_handlers": [...], "mcp_servers": [...] } }

4) Invoke a tool locally

Create a request inline:

cat > req.json <<'JSON'
{"schema_version":"v1","action":"invoke","kind":"tool","name":"persist_driver_profile","payload":{"email":"[e-mail]","name":"Aldenir"}}
JSON

python -m aiel_runtime.runner --files-root "$PWD" < req.json

Or with flags:

python -m aiel_runtime.runner \
  --action invoke \
  --kind tool \
  --name persist_driver_profile \
  --payload '{"email":"[e-mail]","name":"Aldenir"}'

To include sanitized tracebacks for debugging:

python -m aiel_runtime.runner --files-root "$PWD" --debug < req.json

Common troubleshooting

zsh: no matches found: aiel-sdk[all]

Use quotes: python -m pip install "aiel-sdk[all]"

entry_point.py not found Make sure you run from the folder that contains entry_point.py, or pass the correct path:

python -m aiel_runtime.runner --files-root /path/to/project

Import errors (e.g. No module named ...)

Install the required packages in the same venv, or use an EP runtime bundle that includes them.

ModuleNotFoundError: aiel_sdk

• Ensure your runtime environment has aiel-sdk installed.
• Prefer installing aiel-runtime (which should depend on the correct aiel-sdk).

Missing integrations (LangGraph / LangChain / LangSmith)

• Ensure runtime image includes the curated dependency bundle (aiel-runtime[ai]) or explicit deps.

Registry leakage between invocations

• Ensure registry is reset per load (runtime does this by default).
• EP should avoid reusing a single Python process across unrelated tenants/projects unless explicitly designed.

Registry leakage between invocations

• Ensure registry is reset per load (runtime does this by default).
• EP should avoid reusing a single Python process across unrelated tenants/projects unless explicitly designed.

Testing

Recommended minimal tests:

• load snapshot → describe exports
• invoke tool/flow happy path
• contract violation errors are clear
• missing dependency errors are clear
• registry resets properly

Example (pytest):

python -m pip install -U pytest
pytest -q