aiel-runtime 0.0.0

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 / 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

{ "action": "describe" }

stdout

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

Invoke an export

stdin

{
  "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

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

Error response

stdout

{
  "ok": false,
  "error": {
    "message": "Tool not found: normalize_email",
    "traceback": "..."
  }
}

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
• (http, mcp are typically served by EP; runtime can expose metadata via describe)

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

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.

Development

EP_FILES_ROOT=/absolute/path/to/your/project \
python -m aiel_runtime.runner <<'JSON'
{ "action": "describe" }
JSON

Common troubleshooting

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