car-runtime 0.6.1

Common Agent Runtime — Python bindings for deterministic AI agent execution

car-runtime (Python)

Python bindings for Common Agent Runtime (CAR) — a deterministic execution layer for AI agents. Models propose; the runtime validates and executes.

Pre-built wheels (abi3, Python 3.9+) for:

• macosx_15_0_arm64, macosx_15_0_x86_64 — macOS 15+ required
• manylinux_2_17_x86_64, manylinux_2_28_aarch64

Building from source on macOS: set MACOSX_DEPLOYMENT_TARGET=15.0 when invoking maturin build. MLX's bundled Metal shaders don't compile against the default 11.0 target, and our release wheels target 15.0 because the compiled extension pulls in libc++ symbols (notably std::exception_ptr::__from_native_exception_pointer) that only exist on macOS 15+. A lower target produces a wheel whose tag doesn't match what the binary actually requires at dlopen time.

Install

From a release wheel (substitute the current version for X.Y.Z):

pip install https://github.com/Parslee-ai/car/releases/download/vX.Y.Z/car_runtime-X.Y.Z-cp39-abi3-macosx_15_0_arm64.whl

Or build from source:

pip install maturin
cd car-rs/crates/car-ffi-pyo3
maturin develop --release

The import name is car_runtime (matching the PyPI package name).

Quickstart

import json
from car_runtime import CarRuntime, verify, execute

rt = CarRuntime()

# Tools + policies.
rt.register_tool("shell")
rt.register_policy(
    "no_rm",
    "deny_tool_param",
    target="shell",
    key="command",
    pattern="rm -rf",
)

# Ground with facts.
rt.add_fact("project_language", "Python", "pattern")

# Verify before executing.
proposal = json.dumps({
    "actions": [{
        "id": "a1",
        "type": "tool_call",
        "tool": "shell",
        "parameters": {"command": "ls"},
        "dependencies": [],
    }],
})

check = json.loads(rt.verify_proposal(proposal))
if not check["valid"]:
    raise RuntimeError(f"invalid proposal: {check['issues']}")

# Execute with a Python-side tool callback.
def tool_fn(tool: str, params_json: str) -> str:
    params = json.loads(params_json)
    # Dispatch to your actual implementation.
    return json.dumps({"stdout": "ok", "stderr": ""})

result_json = rt.execute_proposal(proposal, tool_fn)

Streaming inference

from car_runtime import CarRuntime

rt = CarRuntime()

def on_event(event_json: str) -> None:
    e = json.loads(event_json)
    if e["type"] == "text":
        print(e["data"], end="", flush=True)

rt.infer_stream(
    "Explain CAR in one sentence.",
    on_event,
    max_tokens=256,
)

Multi-agent coordination

import json
from car_runtime import register_agent_runner, run_swarm

def agent_fn(spec_json: str, task: str) -> str:
    spec = json.loads(spec_json)
    # Call your LLM of choice, returning an AgentOutput JSON.
    return json.dumps({"name": spec["name"], "response": "...", "tool_calls": []})

# Option A: register once, then call run_* without passing agent_fn each time.
register_agent_runner(agent_fn)
result = run_swarm(
    "parallel",
    json.dumps([
        {"name": "researcher", "role": "gather facts", "model": "gpt-5"},
        {"name": "writer",     "role": "compose summary", "model": "claude-opus-4-7"},
    ]),
    "summarize the CAR paper",
)

# Option B: pass agent_fn per call.
result = run_swarm("parallel", agents_json, task, agent_fn=agent_fn)

API surface

The runtime (CarRuntime) exposes:

• State: state_set, state_get, state_exists, state_snapshot, state_keys
• Memory: add_fact, query_facts, fact_count, build_context, build_context_fast, persist_memory, load_memory, consolidate
• Skills: ingest_skill, find_skill, report_outcome, distill_skills, ingest_distilled_skills, list_skills, domains_needing_evolution, repair_skill, evolve_skills
• Tools + policies: register_tool, register_agent_basics, register_policy, set_replan_config
• Inference: infer, infer_tracked, infer_with_context, infer_with_context_tracked, embed, rerank, classify, prepare_speech_runtime, transcribe, synthesize, infer_stream
• Models: list_models, pull_model, remove_model, list_models_unified, register_model, route_model, model_stats
• Execution: event_count, verify_proposal, execute_proposal

Module-level standalone functions:

• Verification: verify, simulate, optimize, equivalent
• Stateless execute: execute (creates a fresh Runtime; for long-lived use, prefer CarRuntime.execute_proposal)
• Multi-agent: register_agent_runner, run_swarm, run_pipeline, run_supervisor, run_map_reduce, run_vote
• Scheduler: create_task, run_task, run_task_loop, ensure_dream_task
• Planner: rank_proposals

Structured returns are JSON-encoded strings — json.loads them on the Python side. This keeps the FFI surface stable across binding and protocol changes.

Type stubs

The wheel ships car_runtime.pyi alongside the compiled extension and a py.typed marker (PEP 561). mypy, pyright, Pylance, and similar tools pick up the full method signatures, parameter docstrings, and return-shape descriptions automatically — no extra install needed.

If you're editing the source tree (not the published wheel), the same files live at crates/car-ffi-pyo3/car_runtime.pyi and must be kept in sync with src/lib.rs. See CLAUDE.md for the FFI-bindings parity rule.

Development

# Install dev deps.
pip install maturin pytest

# Build and install in editable mode.
cd car-rs/crates/car-ffi-pyo3
maturin develop

# Run the smoke tests.
pytest tests/ -v

Architecture

This package is a thin PyO3 wrapper over the Rust car-engine + car-memgine crates. Tool execution uses a callback pattern: the runtime doesn't own tools, you provide a Python function that dispatches them. See the repo README for the bigger picture.

License

Free for any use including commercial; free to redistribute unmodified. Modification, reverse engineering, and derivative works are not permitted. See LICENSE for the full text. Copyright © 2026 Parslee AI.