Skip to main content

car-runtime (Python)

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

As of v0.8, this package is a thin daemon client: every method proxies to a singleton car-server daemon over WebSocket. Inference, the per-session memory graph, and tool dispatch all live on the daemon side. Start car-server once per host before using the bindings (car-server ships in the same wheel; see "Start the daemon" below).

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

  • macosx_15_0_arm64 — macOS 15+ on Apple Silicon (Intel Macs dropped — see CHANGELOG)
  • 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/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).

Call the daemon

The same five-line Node example appears in every package landing page and in the Node scaffold so it cannot drift from the agent-facing skill:

async function daemonCallExample() {
// BEGIN CALL_DAEMON_FIVE_LINES
  const { CarRuntime } = (await import('car-runtime')).default;
  const car = new CarRuntime();
  car.registerDaemonHandler('tools.execute', async () => JSON.stringify({ ok: true }));
  const methods = JSON.parse(await car.daemonCall('capabilities.list', '{}'));
  return { car, methods, agents: JSON.parse(await car.agentsList('{}')) };
// END CALL_DAEMON_FIVE_LINES
}

Python uses the equivalent daemon_call, agents_list, and register_daemon_handler names; the complete runnable Python block is in the car-capabilities skill.

Start the daemon

# The wheel does not contain car-server, and `python -m car_runtime.server`
# never existed. Use the one from the npm package, the platform tarball, or
# CAR Host.app. Default port 9100; auth on by default. Foreground (Ctrl-C to
# stop); needs Node.js 18+ and works from any directory:
npx --package=car-runtime car-server --port 9100

# Or background:
npx --package=car-runtime car-server --port 9100 &

# Override the URL the bindings use:
export CAR_DAEMON_URL=ws://127.0.0.1:9100

On macOS the SwiftUI menubar host (CAR Host.app) launches the daemon for you. Install it once from the .pkg installer on the latest GitHub release; from then on it supervises car-server and keeps itself up to date via Sparkle.

Quickstart

import json
from car_runtime import CarRuntime, verify

rt = CarRuntime()   # lazy-connects to ws://127.0.0.1:9100/

# Tools + policies — proxied to the daemon's per-session runtime
# and persist for the lifetime of this CarRuntime's WS connection.
rt.register_tool("shell")
rt.register_policy(
    "no_rm",
    "deny_tool_param",
    target="shell",
    key="command",
    pattern="rm -rf",
)

# Ground with facts (proxied to the daemon's per-session memgine).
rt.add_fact("project_language", "Python", "pattern")

# Static verification — runs on the daemon side, no model needed.
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']}")

rt.close()  # disconnect() is an alias; a later call reconnects lazily

# For a complete agent cycle, use the packaged helper shown below. It wires
# register_tool_handler + submit_proposal for you.

Packaged agent loop

Do not copy a harness into each agent. Import the versioned loop and keep the project entry file declarative:

from car_runtime.agent_loop import main

main({
    "agent_name": "Lookup Agent",
    "identity": "Use lookup before answering; never guess.",
    "tool_schemas": [{
        "name": "lookup", "description": "Look up one key",
        "parameters": {"type": "object", "properties": {"key": {"type": "string"}},
                       "required": ["key"]},
    }],
    "tools": {"lookup": lambda p: {"key": p["key"], "value": lookup(p["key"])}},
    "policies": [],
    "max_turns": 8,
})

run_agent(config, goal) is also exported for embedding and tests. Put one long-lived runtime in config["runtime"] to reuse its daemon connection across runs; otherwise the loop creates and closes a runtime for each call. The loop registers its tools and policies once per daemon session: when that runtime is closed and reused, or reconnects after a daemon restart (connection_epoch() changes), the next run or serve_chat chat turn registers them again on the new session. serve_chat(config) uses the same option and returns the runtime it serves on. Its AgentOutcome["run_id"] is the durable key accepted by runs_get_trace; it is None when an older daemon has no runs.* surface or did not acknowledge the start. run_chat_turn keeps returning bare text by default; pass include_run_id=True to receive {"text": str, "run_id": str | None}. It registers its tool schemas and config["policies"] on the runtime, so tool-using turns need no earlier register_tool_handler or serve_chat call. The helpers pass their own tool handler to each execute_proposal call, so a handler you registered with register_tool_handler stays in place. main(config) provides --task, --json, and --serve. The loop adds finish, statically verifies every proposal before submit_proposal, preserves tool-call/result IDs, honors per-schema timeoutMs, traces task and chat runs, and uses request-shaped inference with prompt-cache breakpoints. Each inference is recorded before its requested actions with assistant text, normalized call IDs, model id, token usage, and duration; runs_get_trace returns those model turns interleaved with action turns. Recording is best-effort, so an older daemon without the method still runs the agent. Importing car_runtime.agent_loop has no daemon side effect; running it requires car-server. The wheel includes car_runtime/agent_loop.pyi, while the top-level car_runtime.pyi advertises the submodule.

Streaming inference

Streaming is WebSocket-only. Connect to car-server, call the infer_stream JSON-RPC method, and consume inference.stream.event notifications. CarRuntime.infer_stream remains only as an ABI-compatibility stub; it always raises RuntimeError and never invokes its callback. See the streaming cookbook.

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_tracked_with_request (request-shaped GenerateRequest, including params.strict_model), infer_with_context, infer_with_context_tracked, embed, rerank, classify, prepare_speech_runtime, transcribe, synthesize
  • 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

Compatibility-only method: infer_stream (always raises; use WebSocket).

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 the canonical car_runtime.pyi plus a byte-identical package mirror (car_runtime/__init__.pyi) and package-local py.typed marker (PEP 561). mypy, pyright, Pylance, and similar tools pick up the full native method signatures and the typed agent_loop submodule — no extra install needed.

If you're editing the source tree, update crates/car-ffi-pyo3/car_runtime.pyi and copy it to car_runtime/__init__.pyi. scripts/check-ffi-parity.sh rejects drift between them and continues to check the canonical stub against src/lib.rs. See CLAUDE.md for the FFI-bindings parity rule.

Offline reference docs

The wheel also ships a car_runtime_docs/ directory alongside the compiled extension (find it with python3 -c "import car_runtime, pathlib; print(pathlib.Path(car_runtime.__file__).parent / 'car_runtime_docs')" if your install layout differs) — SPEC.md, GUIDE.md, CLI.md, ASSISTANT.md, MCP.md, agent-ir-spec.md. So an agent with pip install car-runtime and no network access can still read how the car CLI, the flagship assistant's tools, and car-mcp actually work, not just the typed surface above. car_runtime_docs/websocket-protocol.md is a short pointer, not the full reference (~510KB, deliberately not bundled) — read the real thing at https://car.parslee.ai/websocket-protocol.md.

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 client to the singleton car-server daemon over WebSocket — CarRuntime() lazy-connects, every method proxies through the JSON-RPC dispatcher, and the daemon owns inference / memory / tool dispatch / per-session state.

Pre-v0.8 (the RuntimeMode::Embedded path) the wheel hosted an in-process car-engine + car-memgine and ran inference under py.allow_threads(...). That path was retired to close the multi-tenant overcommit hazard CAR-issue #139 was opened for — two FFI consumers in different processes each spawned a fresh admission semaphore + model cache, and concurrent runs could overwhelm the host. v0.8 takes the harder path: one daemon per host, every client attaches.

See the car-releases README for the broader CAR architecture.

Long-running packaged task loops

openai-codex/gpt-6.1-sol:high and openai-codex/gpt-6.1-sol:medium run on CAR's ChatGPT subscription sign-in (car auth login --provider openai-codex), without an OpenAI API key. Both catalog rows have a 500,000-token context window; the suffix selects high or medium reasoning effort.

runAgent (Node) / run_agent (Python) supports these task-only settings:

Node Python Meaning
terminalTools terminal_tools Array of tool schemas (name, description, parameters) plus a host validate(arguments) function. Exactly true/True accepts; all other results refuse. Nonempty strings give the reason; empty strings/other values use a default. Async validators are awaited; exceptions use their message, or the default if empty.
requireTerminal require_terminal Require a terminal call even with the default finish tool. Defaults off; declared terminal tools imply it. One text-only turn receives a reminder; a second ends as no_terminal.
noProgressGuard no_progress_guard Defaults on. Set false for intentional polling. Cumulative repeated signatures earn one nudge at repeat 3 and stop at repeat 6 as stalled; eight turns without mutation earn the same single nudge. A new successful mutating signature resets the guard.
priorMessages prior_messages Resume a JSON transcript. Prior system messages are removed in favor of the current identity. Unanswered calls are closed with an explanatory tool result without executing them. The new goal follows the prior messages. The guard starts fresh.
maxTurns max_turns Task default 8. Node: 0 or Infinity removes the cap. Python: 0 or float('inf') removes the cap. A positive finite cap ends as timeout when reached.
maxTokens max_tokens Defaults to 4096, also for chat turns.

Declared terminal tools replace finish in both the offered schemas and the system instruction. A refusal becomes a tool result for the model to repair. Two terminal calls in one turn are both refused. Ordinary tools execute first; a terminal call alongside them is accepted only when all succeeded. In runs with terminal tools, independent ordinary tools continue after a sibling fails so terminal eligibility can be evaluated. Without terminal tools, the runtime's normal abort behavior stops the rest of the turn. A successful ending returns status: "success" and terminal_tool: {name, arguments}.

Every returned task outcome includes transcript, an ordered JSON message array with assistant tool calls and their results. Store it and pass it as prior messages on the next invocation, including across Node and Python. Transcript and run_id are return metadata added after runs.complete; the daemon run record does not contain the transcript. Terminal identity is also in outcome evidence. stalled and no_terminal are real daemon outcome statuses and both cause the task CLI's main to exit with code 1, like failure. Other endings remain done, timeout, success, partial_success, and give_up.

A successful tool whose schema declares mutating: true, or whose name is write_file or edit_file, resets the guard only for a new signature. Failed mutations and identical writes do not reset it. Distinct read calls never hit the repeat stop. With no custom terminal tools, the legacy finish and done paths remain. Chat retains its existing finish behavior and has no guard.

Terminal tools: complete runnable configurations

Use the released package entry shown here (Node: save as an .mjs file; Python: save as .py). A daemon must be available.

import { runAgent } from 'car-runtime/agent-loop';
const validate = args => args.reason.trim() ? true : 'Give a concrete reason.';
const terminalTools = ['retry_commit', 'request_recut', 'hand_off'].map(name => ({
  name, description: 'End this investigation.',
  parameters: { type: 'object', properties: { reason: { type: 'string' } }, required: ['reason'] },
  validate,
}));
const outcome = await runAgent({ agentName: 'incident-owner', identity: 'Investigate; end with a terminal tool.',
  terminalTools, maxTokens: 4096, maxTurns: 0, noProgressGuard: true }, 'Investigate the failing check.');
console.log(JSON.stringify(outcome));
from car_runtime.agent_loop import run_agent

def validate(args):
    return True if args['reason'].strip() else 'Give a concrete reason.'

terminal_tools = [dict(name=name, description='End this investigation.',
    parameters={'type': 'object', 'properties': {'reason': {'type': 'string'}}, 'required': ['reason']},
    validate=validate) for name in ['retry_commit', 'request_recut', 'hand_off']]
outcome = run_agent(dict(agent_name='incident-owner', identity='Investigate; end with a terminal tool.',
    terminal_tools=terminal_tools, max_tokens=4096, max_turns=0, no_progress_guard=True),
    'Investigate the failing check.')
print(outcome)

The runtime checks the declared argument schema before invoking the host validator. The validator receives only the decoded argument object. Exactly true (True in Python) accepts; every other result refuses. A string supplies the refusal reason; an empty string or other value uses a default reason. Async validators are awaited. A thrown error's message is the refusal reason (the default if empty). A validator which never returns hangs the run, just as a hung tool does; supply your own bounded validator when it performs I/O.

Terminal tools replace finish; declaring finish beside them, duplicate names, malformed prior messages, or a negative/NaN cap is an error before runs.start. With no terminal tools, requireTerminal (require_terminal) makes the built-in finish the required terminal. Without that option, a text answer still ends as done.

terminal_tool: {name, arguments} appears only on success. main exits with code 1 for failure, stalled, and no_terminal, and 0 for other returned statuses (success, partial_success, give_up, timeout, done). The no-progress guard counts a repeat whenever a whole turn's sorted tool-name/argument signature has occurred earlier since the last reset, not only on consecutive turns. The third repeat nudges and the sixth stops; eight turns without a new successful state-changing signature only nudges. Python schemas support mutating: True, matching Node's mutating: true; write_file and edit_file are also state-changing. Failed calls do not reset the guard. noProgressGuard: false / no_progress_guard=False disables it for one run.

For task runs, the per-call maxTurns option / Python max_turns argument overrides the config value when non-null. Null or omission uses the config; a null/omitted config uses 8. Zero or positive infinity lifts the task cap. Chat retains its existing cap semantics. maxTokens / max_tokens defaults to 4096.

Resume with priorMessages / prior_messages, a JSON list of messages shaped as: {role: "user" | "assistant" | "system", content: "text"}; assistant messages may carry tool_calls: [{id: "call-id", name: "tool-name", arguments: {...}}]. A tool result is {role: "tool_result", tool_use_id: "call-id", content: "JSON text"}. tool_calls cannot be null, and each call needs its id and an arguments JSON object. Absent arguments, null, arrays, and strings are refused before runs.start. Node validates the JSON round trip, so values that serialize to strings are also refused. Old system messages are replaced by the current one. Do not trim a transcript ending on a terminal call: answered calls are retained; unanswered calls are closed with an explanatory tool result without rerunning handlers. Every ending returns transcript; it is never sent to runs.complete.

Task cap lifting (0 or positive infinity) applies to runAgent / run_agent. In chat, maxTurns: 0 / max_turns=0 performs zero model turns; it does not remove the chat budget. Python chat rejects infinity before runs.start. A refused task configuration throws an Error in Node or raises ValueError in Python, rather than returning an outcome. A terminal name cannot collide with an ordinary tool name. Node keeps main's missing-identity and numeric-string cap behavior.

Python async validators are awaited with asyncio.run when no event loop is running on the callback thread. If that thread already has an event loop, a separate thread runs and awaits the coroutine; the synchronous caller waits for its result. A validator that never returns therefore still hangs its run. The validator receives a deep copy: mutations cannot rewrite the transcript or the arguments checked and recorded by CAR. The daemon's full parameter check runs before dispatch to that validator, including enum, nested, array and additional-property constraints. Schema refusals count as failed tool calls. Each task run restores its declared terminal schemas, including A/B/A reuse.

The initial occurrence is not a repeat: for one identical signature, the third repeat is its fourth occurrence and the sixth repeat is its seventh occurrence. Repeats of any previously seen whole-turn signature accumulate between resets; for example A, B, A, B, A reaches the third repeat on turn five. A typed success also includes an evidence entry shaped as {kind: "tool_result", description: "terminal_name", data: { /* original arguments */ }}.

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.

Metadata

Release files for car-runtime 0.64.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for car-runtime 0.64.0
File Interpreter ABI Platform Actions
car_runtime-0.64.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for car_runtime-0.64.0-cp39-abi3-win_amd64.whl
car_runtime-0.64.0-cp39-abi3-manylinux_2_28_x86_64.whl CPython 3.9 abi3 Linux glibc 2.28+ x86-64 Details for car_runtime-0.64.0-cp39-abi3-manylinux_2_28_x86_64.whl
car_runtime-0.64.0-cp39-abi3-macosx_15_0_arm64.whl CPython 3.9 abi3 macOS 15.0+ ARM64 Details for car_runtime-0.64.0-cp39-abi3-macosx_15_0_arm64.whl

Total release size: 121.8 MB

Release files / car_runtime-0.64.0-cp39-abi3-win_amd64.whl

Download URL car_runtime-0.64.0-cp39-abi3-win_amd64.whl
Size 38.1 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
65110277d0b3e5197c2a38981d801c57c921a035538c1b335ddeaef4718f4842
BLAKE2b-256 checksum
How to use checksums
e06fd1841714203efb38e69ab62c9bd97e536c19b74eda07f5daeaad395dc9ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / car_runtime-0.64.0-cp39-abi3-manylinux_2_28_x86_64.whl

Download URL car_runtime-0.64.0-cp39-abi3-manylinux_2_28_x86_64.whl
Size 48.3 MB
Tags CPython 3.9 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
143ff8a99fca096af90b46ccae97846fe254d282ca2c3ff733270b18a41e35cf
BLAKE2b-256 checksum
How to use checksums
41488de41f42a639e0984966a0f3522c94e1740e0265e6142d30af5b6038aee8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / car_runtime-0.64.0-cp39-abi3-macosx_15_0_arm64.whl

Download URL car_runtime-0.64.0-cp39-abi3-macosx_15_0_arm64.whl
Size 35.4 MB
Tags CPython 3.9 abi3 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
06a058a6942b6c463ac6469af89e7bd3d8abf8981298bcd5f5546d69747d47be
BLAKE2b-256 checksum
How to use checksums
f7c0b7062491ef8f35ef9f014bc9dd51a5e9110f6905c3bd706796a091786209
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for car-runtime 0.64.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Select from 3 files

Attestation for car_runtime-0.64.0-cp39-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.64.0 This release

3 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page