OuterSpace Apizr

Apizr is an open-source capability compiler for Python codebases.

It discovers executable capabilities, builds deterministic contracts and relationships, exposes eligible capabilities through REST or MCP, and supports governed execution. Python 3.11–3.14 · GPL-3.0-or-later · Release 0.2.0

What Apizr does

• Discover: inventory a Python repository without importing or executing its source.
• Understand: inspect typed capabilities, relationships and static readiness.
• Expose: generate REST or MCP interfaces from the same eligible contracts.
• Govern: execute trusted code under explicit local-process or OCI policies.

Scripts and notebooks are inputs for individual inspection and generation. Repository scanning discovers Python files. The historical notebook-to-API workflow remains supported.

Install

python -m pip install outerspace-apizr

For a uv-managed project: uv add outerspace-apizr. These instructions describe 0.2.0; check the installed release with apizr --version.

A 30-second example

Save this as example.py in an empty project directory:

def subtotal(prices: list[float]) -> float:
    return sum(prices)


def total(prices: list[float], tax: float = 0.2) -> float:
    return subtotal(prices) * (1 + tax)

Discover the functions, their call relationship and their contracts:

apizr scan .
apizr graph .
apizr inspect example.py
apizr readiness .

Generate both interfaces from the same capability:

apizr generate rest example.py --select total --output-dir .output/rest
apizr generate mcp example.py --select total --output-dir .output/mcp

No Docker is needed. The REST bundle includes app.py, openapi.json and an artifact manifest; the MCP bundle includes server.py and mcp-tools.json. Each bundle includes its runtime requirements. To serve the REST interface:

python -m pip install -r .output/rest/requirements.txt
uvicorn app:app --app-dir .output/rest --host 127.0.0.1 --port 8000

Starting a generated server imports trusted source. See the REST guide and MCP guide for invocation, stdio/HTTP transport setup and generated bundle integrity checks.

From source to an interface

Python repository → Scanner → Capability Catalog → Capability Graph
Scripts / notebooks ──────────────→ Capability IR + static readiness
Catalog + Graph ─────────────────→ Repository Readiness (policy evidence)
Capability IR + static readiness → Interface Contract → REST / MCP
                                                          ↓
                                      direct or governed execution
                                             local-process / OCI

REST and MCP consume shared contracts. Readiness policies assess static evidence; execution policies control explicit invocation. Neither discovery nor a READY assessment grants trust or proves runtime safety. Unknown effects remain unknown. See the architecture overview.

Governed execution

apizr execute SOURCE CAPABILITY --arguments args.json --policy policy.json runs one trusted capability under an explicit policy. Generated REST/MCP servers can opt in with --execution-policy policy.json; their default is direct execution.

The execution backends remain experimental: policy contracts and refusal behavior are tested, but they are not a general untrusted-code service. A local process provides bounded execution, not filesystem or network isolation. OCI adds Linux container controls and requires a trusted Docker host and worker image; it is not a VM boundary. Absolute subprocess prohibition remains unsupported. See the execution guide.

Legacy generation pipeline

The notebook/script → FastAPI → container workflow remains supported:

apizr --script example.py --output-dir .output/legacy --force
apizr --notebook your-notebook.ipynb --output-dir .output/notebook --force

Use a fresh output directory. This independent pipeline is retained for compatibility; it is not a prerequisite for the compiler commands. See the legacy guide and compatibility notes.

Limits and trust boundary

Static scanning, inspection and generation do not execute source. Direct servers import and execute it; governed invocation still requires trusted source and dependencies. Capabilities currently represent top-level functions, not class methods. Dynamic bindings, imports and effects can remain unresolved. Generated artifacts are hashable evidence, not signed attestations. No enterprise control plane is included. The legacy pipeline's duplicate-definition/overload issue remains tracked in #28.

Documentation and contributing

• Start here
• Repository scan, graph and readiness
• 0.2.0 release notes
• Development and checks
• Report an issue

Licensed under GPL-3.0-or-later.