Python SDK & CLI

ELI5

The Python SDK is like a toolkit for working with IRIS. It has a screwdriver (client) for talking to the API, a measuring tape (schema validation) for checking if your sprites are correct, a stamp (fingerprint engine) for creating identity proofs, and a command centre (CLI) where you can run everything from your terminal with pretty coloured output.

Technical Deep Dive

Package Structure

iris-sdk-python/
├── src/iris/
│   ├── __init__.py
│   ├── sprite.py          # Sprite model + validation
│   ├── council.py         # Council orchestration
│   ├── chain.py           # Chain execution engine
│   ├── fingerprint.py     # Blake3 5-stage pipeline
│   ├── client.py          # REST client for iris-service
│   ├── schema.py          # Schema loading + caching
│   ├── config.py          # Configuration management
│   ├── exceptions.py      # Custom exceptions
│   ├── migrate.py         # Migration utilities
│   └── cli/
│       ├── main.py        # Entry point (Click group)
│       ├── output.py      # Rich formatting utilities
│       └── commands/
│           ├── sprite.py  # Sprite subcommands
│           ├── council.py # Council subcommands
│           ├── chain.py   # Chain subcommands
│           └── system.py  # System subcommands

REST Client (IrisServiceClient)

from iris.client import IrisServiceClient

with IrisServiceClient(base_url="http://localhost:8000") as client:
    # Sprite operations
    sprite = client.create_sprite({
        "name": "SOL-FORGE-01",
        "version": "1.0.0",
        "role": "architect",
        "capabilities": [{"name": "generate_code", "description": "..."}],
        "system_prompt": "You are a senior software architect..."
    })

    # Council operations
    council = client.create_council({
        "domain": "engineering",
        "sprites": [sprite["id"]],
        "gate_agents": [sprite["id"]]
    })

    # Chain execution
    result = client.run_chain({
        "council_id": council["id"],
        "chain_id": chain["id"],
        "input": {"task": "Generate a REST API"}
    })

Features:

• Synchronous requests.Session-based client
• Context manager support (with statement)
• Configurable timeout (default 30s) and SSL verification
• Automatic JSON parsing and error handling

CLI Commands

flowchart TD
    A["iris <command>"] --> B["sprite"]
    A --> C["council"]
    A --> D["chain"]
    A --> E["system"]

    B --> B1["validate PATH"]
    B --> B2["fingerprint PATH"]
    B --> B3["create --name --version --prompt"]
    B --> B4["list"]
    B --> B5["delete SPRITE_ID"]
    B --> B6["import-sprite SOURCE_PATH"]

    C --> C1["create --name --domain"]
    C --> C2["list"]
    C --> C3["run COUNCIL_PATH"]

    D --> D1["run CHAIN_PATH"]
    D --> D2["status CHAIN_PATH"]
    D --> D3["history CHAIN_PATH"]

    E --> E1["health [--url]"]
    E --> E2["version"]
    E --> E3["config"]

Output Formatting (Rich)

The CLI uses rich.console.Console and rich.table.Table for beautiful terminal output:

Fingerprinting from CLI

# Compute Blake3 fingerprint
$ iris sprite fingerprint examples/sol-forge.sprite.yaml
blake3:a1b2c3d4e5f6...

# Validate and show fingerprint preview
$ iris sprite validate examples/sol-forge.sprite.yaml --format yaml
valid: true
errors: []
fingerprint_preview: a1b2c3d4...

Dependencies

PyPI Distribution

Published as iris-sdk on PyPI:

pip install iris-sdk

Key Terms

• IrisServiceClient → Synchronous HTTP client for iris-service REST API
• Click → Python library for building command-line interfaces with subcommands and options
• Rich → Python library for beautiful terminal output (tables, colours, progress bars)
• Context manager → The with statement ensures the HTTP session is properly closed
• Schema loader → Caches IRIS JSON schemas from package directory or development paths
• Sprite.from_file() → Class method loading sprites from YAML or JSON files

Q&A

Q: Can I use the SDK asynchronously? A: The Python SDK client is synchronous. For async usage, use httpx directly or the TypeScript SDK. The iris-meridian-adapter uses httpx.AsyncClient for async operations.

Q: How does the CLI find example sprites? A: iris sprite list searches the current directory and ../iris-specs/examples/ for *.sprite.yaml, *.sprite.yml, and *.sprite.json files.

Q: Can I output in multiple formats simultaneously? A: No. The --format flag selects one output format per command. Use shell redirection for multiple formats: iris sprite list --format json > sprites.json.

Q: What Python versions are supported? A: Python 3.11, 3.12, and 3.13. The pyproject.toml specifies requires-python = ">=3.11".

Q: How do I configure the CLI? A: Use the --config flag or set environment variables. The system config command shows the current configuration including Python version, platform, schema availability, and working directory.

Examples

The Python SDK is like a carpenter’s workshop:

• IrisServiceClient = The phone on the wall for calling the lumber yard (iris-service)
• Sprite model = The blueprint for every piece of furniture you build
• Fingerprint engine = The brand you burn into each piece to prove you made it
• CLI = The control panel where you press buttons to cut, measure, stamp, and inspect
• Rich output = The clean, colour-coded labels on every storage bin so you can find things instantly