Metadata-Version: 2.4
Name: aiel-runtime
Version: 0.5.3
Summary: AIEL Runtime adapter used by the Execution Plane to load and execute user projects.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiel-cli>=1.2.3
Requires-Dist: aiel-sdk>=1.1.6
Requires-Dist: anyio>=4.0
Requires-Dist: pydantic>=2.8
Provides-Extra: ai
Requires-Dist: langchain-core>=0.3.0; extra == 'ai'
Requires-Dist: langgraph>=0.2.0; extra == 'ai'
Provides-Extra: mcp
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# AIEL Runtime — Governed Execution Runtime for AI Workloads

[![PyPI](https://img.shields.io/pypi/v/aiel-runtime.svg)](https://pypi.org/project/aiel-runtime/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

`aiel-runtime` is the execution runtime used by the AIEL Execution Plane to load, validate, and execute customer AI workloads from immutable deployment snapshots.

It is the runtime boundary between:
- customer-defined execution contracts
- platform-governed execution infrastructure

The runtime is intentionally focused on:
- deterministic execution
- snapshot loading
- contract validation
- export invocation
- runtime normalization
- execution isolation compatibility
- observability integration

Developer-facing ergonomics belong to `aiel-sdk`.

Deployment and operational workflows belong to `aiel-cli`.

`aiel-runtime` exists to execute workloads consistently and safely inside the Execution Plane.

---

# Why the Runtime Exists

Most AI orchestration frameworks stop at workflow composition.

Production systems require significantly more:

- deterministic execution
- version-aware runtime loading
- immutable deployment artifacts
- governed integration access
- execution traceability
- runtime isolation
- execution contracts
- timeout enforcement
- normalized invocation protocols
- reproducible runtime environments

The Execution Plane requires a stable runtime adapter capable of loading customer workloads from immutable snapshots and executing them under platform governance.

`aiel-runtime` is that execution adapter.

---

# Position in the Platform

The AI Execution Layer is composed of multiple coordinated systems.

| Component | Responsibility |
|---|---|
| `aiel-sdk` | Defines executable contracts locally |
| `aiel-cli` | Packages and deploys snapshots |
| `aiel-runtime` | Loads and executes snapshots |
| `Control Plane` | Governs releases, workspaces, policies, and promotion |
| `Data Plane` | Stores snapshots, traces, memory, manifests, and rollout state |
| `Execution Plane` | Orchestrates governed runtime execution |

The runtime is the execution boundary of the platform.

It does not decide:
- release eligibility
- rollout policy
- promotion logic
- deployment governance

Those responsibilities belong to the Control Plane.

The runtime focuses exclusively on execution behavior.

---

# Runtime Responsibilities

The runtime is responsible for:

- loading immutable snapshots
- importing `entry_point.py`
- hydrating the SDK registry
- validating export contracts
- invoking tools, agents, flows, routers, HTTP handlers, and MCP metadata
- normalizing execution responses
- collecting execution metadata
- supporting timeout enforcement
- supporting runtime isolation boundaries
- returning deterministic execution envelopes

The runtime is intentionally narrow in scope.

It is not:
- a deployment system
- a package manager
- a CI platform
- an orchestration authoring framework
- a sandbox implementation
- a policy engine

Those concerns belong to surrounding platform layers.

---

# Execution Model

The runtime executes workloads from immutable deployment snapshots.

A snapshot is a versioned filesystem artifact containing:
- `entry_point.py`
- local modules
- workflow code
- dependency metadata
- runtime manifest metadata

The runtime imports `entry_point.py`.

Decorators from `aiel-sdk` register executable exports into the in-memory registry.

The runtime then validates and invokes those exports through a normalized execution protocol.

---

# Architecture Flow

```text
┌─────────────────────────────┐
│ Developer Code              │
│ entry_point.py              │
└────────────┬────────────────┘
             │
             │ aiel push
             ▼
┌─────────────────────────────┐
│ Immutable Snapshot          │
│ (versioned artifact)        │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ Execution Plane             │
├─────────────────────────────┤
│ Snapshot Download           │
│ Runtime Provisioning        │
│ Runtime Isolation           │
│ Policy Enforcement          │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ aiel-runtime                │
├─────────────────────────────┤
│ Load snapshot               │
│ Import entry_point.py       │
│ Hydrate registry            │
│ Validate contracts          │
│ Resolve invocation          │
│ Execute export              │
│ Collect logs + traces       │
│ Normalize response          │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ Structured Runtime Response │
└─────────────────────────────┘
```

---

# Runtime Lifecycle

The runtime follows a deterministic execution lifecycle.

## 1. Request Intake

The runtime receives a JSON request through:
- stdin
- CLI arguments
- Execution Plane orchestration

The request is parsed into a normalized internal protocol structure.

---

## 2. Snapshot Resolution

The runtime resolves the snapshot root from:

```text
EP_FILES_ROOT
```

Example:

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

The snapshot must contain:

```text
entry_point.py
```

---

## 3. Registry Reset

The runtime resets the SDK registry before loading the snapshot.

This prevents registry leakage across warm process reuse.

---

## 4. Snapshot Import

The runtime:
- adds the snapshot root to `sys.path`
- imports `entry_point.py`
- allows decorators to register exports

---

## 5. Contract Validation

The runtime validates:
- export signatures
- registry consistency
- supported export shapes
- invocation compatibility

Validation is delegated to `aiel-sdk`.

---

## 6. Context Hydration

The runtime builds a normalized execution context.

The context may contain:
- request ID
- trace ID
- tenant ID
- workspace ID
- project ID
- user ID
- runtime version
- SDK version
- snapshot ID
- deadline metadata

The runtime also exposes:
- structured logging
- remaining time helpers
- execution metadata

---

## 7. Invocation

The runtime dispatches execution based on:
- action
- kind
- handler name
- protocol payload

Supported execution actions:
- `describe`
- `invoke`
- `execute`

---

## 8. Timeout Enforcement

Async functions are awaited with timeout enforcement.

Sync functions are executed through controlled worker execution paths to support timeout handling.

---

## 9. Response Normalization

All runtime responses are normalized into a stable envelope.

Responses include:
- success status
- HTTP status
- result payload
- error metadata
- execution metadata
- timing information
- trace information
- runtime logs

---

# Snapshot Model

The runtime is snapshot-first.

Snapshots are immutable deployment artifacts controlled by the platform.

Typical snapshot layout:

```text
files/
  entry_point.py
  tools/
    core.py
  agents/
    main.py
  flows/
    onboarding.py
  mcp_server/
    core.py
  requirements.txt
```

The runtime does not install dependencies dynamically.

Runtime environments must be pre-baked and curated by the platform.

This avoids:
- dependency drift
- runtime mutation
- unpredictable cold starts
- unreviewed dependency execution

---

# Snapshot Identification

The runtime computes a deterministic snapshot identifier using:
- file paths
- file contents
- snapshot hashing

Ignored paths typically include:
- `.git/`
- `.venv/`
- `__pycache__/`

Snapshot identifiers support:
- runtime cache keys
- rollout correlation
- deployment traceability
- version-aware execution
- reproducibility

---

# Runtime Protocol

The runtime exposes a normalized stdin → stdout protocol.

This allows:
- subprocess execution
- container execution
- platform orchestration
- language-neutral invocation
- deterministic response parsing

---

# Describe Action

The `describe` action returns the registry execution surface.

## Request

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

## Response

```json
{
  "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"]
      }
    ]
  }
}
```

The `describe` action is used by the Execution Plane for:
- capability discovery
- runtime introspection
- deployment validation
- MCP metadata exposure
- execution routing

---

# Invoke Action

The `invoke` action executes a registered export.

## Request

```json
{
  "schema_version": "v1",
  "action": "invoke",
  "kind": "tool",
  "name": "normalize_email",
  "payload": {
    "email": "Test@Example.com",
    "ctx": {
      "request_id": "req_123",
      "workspace_id": "w_1",
      "project_id": "p_1"
    }
  }
}
```

## Response

```json
{
  "schema_version": "v1",
  "ok": true,
  "result": {
    "email": "test@example.com"
  }
}
```

---

# Execute Action

The `execute` action bypasses the SDK registry and invokes a Python handler directly.

This model is similar to AWS Lambda-style invocation.

Example handler:

```python
def aiel_handler(event, context):
    return {"ok": True}
```

Example request:

```json
{
  "schema_version": "v1",
  "action": "execute",
  "handler": "entry_point.aiel_handler",
  "event": {}
}
```

This execution model is useful for:
- lightweight runtime handlers
- compatibility scenarios
- custom execution entrypoints
- direct runtime invocation

---

# Supported Export Types

| Export Type | Runtime Behavior |
|---|---|
| Tool | Executes callable action |
| Agent | Executes stateful orchestration step |
| Flow | Executes workflow entry point |
| Router | Executes routing decision |
| HTTP Handler | Exposed through platform-managed HTTP routing |
| MCP Metadata | Exposed through platform-managed MCP surfaces |

The Execution Plane is responsible for mapping:
- HTTP requests
- MCP requests
- external triggers

into runtime invocation payloads.

---

# Runtime Context

Exports receive a normalized runtime context.

The context provides:
- execution metadata
- structured logging
- trace metadata
- timing helpers
- workspace/project identity

Example:

```python
@tool("normalize_email")
def normalize_email(ctx, payload):
    ctx.log("normalize_email.completed")
    return {"email": payload["email"].lower()}
```

Available fields may include:
- `ctx.request_id`
- `ctx.trace_id`
- `ctx.workspace_id`
- `ctx.project_id`
- `ctx.snapshot_id`
- `ctx.runtime_version`
- `ctx.sdk_version`

---

# Structured Logging

Runtime logs are emitted through:

```python
ctx.log(...)
```

Example:

```python
ctx.log(
    "normalize_email.completed",
    level="INFO",
    email="test@example.com",
)
```

Structured logs are attached to the runtime response envelope and may later be persisted by platform telemetry systems.

---

# Runtime Response Envelope

All runtime responses follow a normalized structure.

Example:

```json
{
  "schema_version": "v1",
  "ok": true,
  "http_status": 200,
  "result": {},
  "error": null,
  "meta": {
    "request_id": "uuid",
    "trace_id": "trace_123",
    "duration_ms": 12,
    "snapshot_id": "sha256...",
    "runtime_version": "x.y.z",
    "sdk_version": "x.y.z",
    "logs": []
  }
}
```

The normalized response model simplifies:
- orchestration
- telemetry
- retries
- debugging
- execution replay
- rollout analysis

---

# Error Model

Errors are normalized into a stable taxonomy.

Example:

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

Supported error categories may include:

| Error Code | Purpose |
|---|---|
| `VALIDATION_ERROR` | Invalid request or contract |
| `NOT_FOUND` | Missing export or handler |
| `SECURITY_VIOLATION` | Restricted operation detected |
| `TIMEOUT` | Execution exceeded deadline |
| `USER_CODE_ERROR` | Exception thrown by customer code |
| `INTERNAL` | Runtime or snapshot failure |

This stable error taxonomy allows the Execution Plane to reason about runtime outcomes consistently.

---

# Runtime Isolation Model

The runtime assumes that hard isolation boundaries are enforced by the Execution Plane.

Typical platform responsibilities include:
- process isolation
- container isolation
- read-only snapshots
- CPU limits
- memory limits
- timeout enforcement
- network restrictions
- secret injection
- tenant separation

The runtime performs defense-in-depth checks where practical.

Hard security boundaries belong to the platform infrastructure layer.

---

# Import Policy Enforcement

The runtime may perform static import inspection before execution.

This is intended as defense-in-depth validation.

Restricted import roots may include:
- `subprocess`
- `ctypes`
- low-level system access modules

Import policies may depend on runtime capabilities.

Example capabilities:

```json
{
  "network": false,
  "subprocess": false,
  "ctypes": false
}
```

The platform should remain the primary enforcement boundary.

---

# Runtime Bundles

The Execution Plane may expose curated runtime bundles.

---

## Minimal Runtime

```text
aiel-runtime==X.Y.Z
aiel-sdk==X.Y.Z
```

Used for:
- core workflows
- tools
- routers
- HTTP handlers

---

## AI Runtime

```text
aiel-runtime[ai]==X.Y.Z
```

May include curated AI dependencies:
- LangGraph
- LangChain Core
- LangSmith

The platform should pin and allowlist runtime bundles.

---

# Version Compatibility

The runtime and SDK are designed for lockstep compatibility.

Recommended policy:

```text
aiel-runtime==X.Y.Z
aiel-sdk==X.Y.Z
```

The Data Plane manifest should include:
- runtime identifier
- SDK version
- snapshot hashes

This supports:
- deterministic execution
- cache stability
- reproducibility
- rollback safety

---

# Runtime Entrypoint

The Execution Plane invokes:

```bash
python -m aiel_runtime.runner
```

The runtime may receive:
- stdin protocol requests
- CLI arguments
- environment metadata

---

# Local Development

The runtime can be executed locally for:
- snapshot validation
- protocol testing
- export inspection
- smoke testing

---

## Install Runtime

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

Optional AI bundle:

```bash
python -m pip install "aiel-runtime[ai]"
```

---

## Describe Exports

```bash
aiel-runtime --files-root "$PWD" --action describe --pretty
```

Or:

```bash
echo '{"schema_version":"v1","action":"describe"}' | \
aiel-runtime --files-root "$PWD" --pretty
```

---

## Invoke a Tool

```bash
aiel-runtime \
  --files-root "$PWD" \
  --action invoke \
  --kind tool \
  --handler normalize_email \
  --event '{"email":"Test@Example.com"}' \
  --pretty
```

---

## Execute a Handler

```bash
aiel-runtime \
  --files-root "$PWD" \
  --action execute \
  --handler entry_point.aiel_handler \
  --event '{"hello":"world"}' \
  --pretty
```

---

# Environment Variables

| Variable | Purpose |
|---|---|
| `EP_FILES_ROOT` | Snapshot root |
| `AIEL_PRETTY_JSON` | Pretty-print runtime responses |
| `AIEL_AUTO_CTX` | Auto-discover local context |

---

# Recommended Snapshot Structure

```text
my-project/
├── entry_point.py
├── tools/
│   └── core.py
├── agents/
│   └── onboarding.py
├── flows/
│   └── driver_flow.py
├── mcp_server/
│   └── support.py
└── requirements.txt
```

The runtime requires:

```text
entry_point.py
```

All executable exports should be registered during import time.

---

# Operational Guarantees

When used inside the AIEL Execution Plane, the runtime supports:

- deterministic execution
- immutable deployment loading
- normalized invocation behavior
- contract validation
- structured runtime telemetry
- timeout-aware execution
- stable response envelopes
- export introspection
- runtime reproducibility
- governed execution integration

---

# Troubleshooting

## `entry_point.py` Not Found

The snapshot root must contain:

```text
entry_point.py
```

Fix:

```bash
aiel-runtime --files-root /path/to/project
```

---

## Missing SDK

Example:

```text
ModuleNotFoundError: aiel_sdk
```

Fix:

```bash
python -m pip install aiel-sdk
```

Prefer installing through the runtime package:

```bash
python -m pip install aiel-runtime
```

---

## Missing Optional AI Dependencies

Example:

```text
ImportError: aiel_core.langgraph is not available
```

Fix:

```bash
python -m pip install "aiel-runtime[ai]"
```

Or install required dependencies explicitly.

---

## Registry Leakage

The runtime resets the registry before snapshot loading.

The Execution Plane should avoid reusing the same process across unrelated tenants or projects unless explicitly designed for isolation reuse.

---

## Contract Validation Failure

Typical causes:
- invalid export signatures
- unsupported return shapes
- decorator misuse
- registry inconsistencies

Validate locally:

```bash
aiel-runtime --files-root "$PWD" --action describe
```

---

## Timeout Failures

Example:

```json
{
  "ok": false,
  "error": {
    "code": "TIMEOUT"
  }
}
```

Potential causes:
- long-running synchronous execution
- blocked I/O
- unbounded loops
- network waits

The platform should enforce appropriate timeout policies.

---

# Relationship to the SDK

The SDK defines executable contracts.

The runtime executes those contracts.

Typical flow:

```text
Developer Code
    ↓
aiel-sdk decorators
    ↓
Registry exports
    ↓
aiel-cli packages snapshot
    ↓
Execution Plane loads snapshot
    ↓
aiel-runtime imports entry_point.py
    ↓
Runtime executes exports
```

---

# Relationship to the Execution Plane

The runtime is intentionally designed to be orchestrated by the Execution Plane.

The Execution Plane provides:
- isolation
- governance
- rollout orchestration
- deployment control
- policy enforcement
- observability infrastructure
- snapshot distribution
- runtime provisioning

The runtime provides:
- deterministic execution
- export loading
- invocation handling
- response normalization
- execution telemetry

---

# Testing

Recommended runtime validation tests:

- snapshot load succeeds
- `describe` returns exports
- tool invocation succeeds
- flow invocation succeeds
- contract violations fail predictably
- registry resets correctly
- timeout handling works
- error normalization remains stable

Example:

```bash
python -m pip install pytest
pytest -q
```

---

# Summary

`aiel-runtime` is the governed execution runtime of the AI Execution Layer.

It loads immutable snapshots, hydrates execution contracts, validates exports, invokes workloads, and normalizes execution behavior for the Execution Plane.

The runtime is intentionally narrow in scope:
- deterministic
- version-aware
- contract-driven
- execution-focused

The platform surrounding the runtime provides governance, orchestration, rollout control, and operational infrastructure required for production AI systems.
