Skip to content

The full journey

Prefer a guided learning path? Apizr Academy orders the existing tutorials and explains capabilities, readiness, selection and execution.

Start with an experiment

With Apizr installed, inspect a script without running it:

printf 'learning_rate = 0.05\n' > example.py
apizr experiment inspect example.py

The report finds learning_rate = 0.05 under Parameters. Runtime facts remain unknown. See experiment inspection for notebooks and JSON output.

Start with functions to expose

This example shares two Python functions through REST and MCP: calculate a price and check stock. Helper functions stay private.

For the shortest path to a working server, follow the Quickstart. For a research project with unfinished experiments, see exposing an independent serving function in Apizr 0.4.6.

Install

Follow Install Apizr, then check apizr --version in that environment. This guide uses version 0.4.6. You will install the generated server's dependencies when you are ready to run it.

Walk through a small repository

Create these three files in an empty directory. pricing.py calculates a price, inventory.py checks stock, and api.py provides the price operation you will make public. You can also find them in examples/repository-shop.

pricing.py

def total(unit_price: float, quantity: int = 1) -> float:
    return unit_price * quantity

inventory.py

def available(stock: int, requested: int = 1) -> bool:
    return stock >= requested

api.py

def quote(unit_price: float, quantity: int = 1) -> float:
    return _price(unit_price, quantity)


def _price(unit_price: float, quantity: int) -> float:
    from pricing import total

    return total(unit_price, quantity)

Create two small configuration files. The first tells Apizr that this example will run in the server's Python process. Save it as readiness-direct.json:

{"execution":{"modes":["direct"]}}

The second chooses the two public functions and requests REST and MCP. Save it as exposure-direct.json:

{"selection":{"include":["python:api:quote","python:inventory:available"]},"interfaces":["rest","mcp"],"execution":{"allowed":["direct"]}}

Apizr also needs permission to read your project. Run this command in the same directory to create operator.json for that directory:

python - <<'PYTHON'
import json
from pathlib import Path
root = str(Path.cwd().resolve())
Path("operator.json").write_text(json.dumps({
    "schema": "apizr.operator-policy/v1",
    "grants": [{"adapter": "repository", "operation": "analyze",
                "target": {"kind": "local", "root": root},
                "permissions": ["source.analyze"]}],
}))
PYTHON

You can now create the service. If you want to see what Apizr finds first, the following checks are optional:

Inspect the project before generating the service 
apizr scan . --operator-policy operator.json --exclude-dir .output
apizr graph . --operator-policy operator.json --exclude-dir .output
apizr readiness . --operator-policy operator.json --exclude-dir .output --policy readiness-direct.json
apizr expose plan . --operator-policy operator.json --exclude-dir .output --readiness-policy readiness-direct.json --policy exposure-direct.json

Create the REST and MCP servers:

apizr expose build rest . --operator-policy operator.json --exclude-dir .output --readiness-policy readiness-direct.json --policy exposure-direct.json --output-dir .output/rest
apizr expose build mcp . --operator-policy operator.json --exclude-dir .output --readiness-policy readiness-direct.json --policy exposure-direct.json --output-dir .output/mcp

--exclude-dir .output keeps generated files out of your project's analysis. Only api.quote and inventory.available are public. The generated service includes the pricing helper so it can calculate the result, but clients cannot call that helper directly.

Serve the direct REST bundle:

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

POST {"unit_price":12.5,"quantity":2} to /capabilities/api.quote → 25.0. POST {"stock":10,"requested":3} to /capabilities/inventory.available → true. For MCP, the generated server offers the same two operations. Follow the MCP client steps with .output/mcp as your server directory.

Understand the decisions

Apizr checks your code before generating a server. A function marked READY can still stay private: your selection determines what clients can call.

Repository readiness resolves the local pricing helper. See readiness diagnostics if your own code cannot be built.

Running the generated server executes your Python code with your user permissions. Use code you trust. This example runs calls in the server process; if you need a fresh process or container for each call, see execution options.

Choose your next step

Task Guide
Try a working service Quickstart
Choose functions from your own project Selection and private helpers
Work with one Python file REST / MCP
Understand a refused function Repository readiness
Work with notebooks Notebook guide

Compatibility and limits

This workflow exposes top-level Python functions. If your application needs extra libraries or data files, prepare those in the server environment yourself. Apizr does not deploy the service for you. Use a fresh output directory when generating it again.