Metadata-Version: 2.4
Name: car-runtime
Version: 0.4.9
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: pytest>=7.0 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: Common Agent Runtime — Python bindings for deterministic AI agent execution
Keywords: ai,agent,runtime,llm,inference
Author-email: Parslee AI <hello@parslee.ai>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Parslee-ai/car
Project-URL: Issues, https://github.com/Parslee-ai/car/issues
Project-URL: Repository, https://github.com/Parslee-ai/car

# 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`):

```bash
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:

```bash
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

```python
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

```python
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

```python
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.

## Development

```bash
# 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](https://github.com/Parslee-ai/car) 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`](./LICENSE) for the full text. Copyright © 2026 Parslee AI.

