MirrorNeuron Python SDK

mn-python-sdk provides the Python gRPC client and workflow-bundle helpers used by the CLI, API, and Python-defined workflows.

Quick Start

Install locally and run tests:

python3.11 -m venv .venv
. .venv/bin/activate
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check .

Minimal client example:

from mn_sdk import Client

client = Client(target="localhost:55051")
print(client.list_jobs(limit=5))

Details

• MirrorNeuron Component Guide
• Python SDK
• Job Bundle Format
• Environment Variables

Source Manifests

Blueprints may use apiVersion: mn.workflow.source/v1 for a compact, CSS-like manifest.json that declares intent and overrides while SDK profiles provide common defaults. Generate the executable runtime manifest with:

mn-manifest-converter expand manifest.json --output build/manifest.executable.json
mn-manifest-converter check manifest.json --against build/manifest.executable.json

The CLI/API expand source manifests automatically before validation and submission. Existing mn.workflow/v1 executable manifests continue to work.

Configuration

Configuration is loaded by mn_sdk.config in this order:

real environment variables
> .env.${MN_ENV}
> .env
> built-in safe defaults

MN_ENV defaults to dev when unset. MN_ENV=development loads .env.dev; MN_ENV=test loads .env.test; MN_ENV=prod or MN_ENV=production loads .env.prod when present. Production does not require any .env file.

Development example:

export MN_ENV=dev
cp .env.example .env.dev
mn-cli ...

Test example:

export MN_ENV=test
mn-cli ...

Production example:

export MN_ENV=production
export MN_HOME=/var/lib/mirrorneuron
export MN_LOG_LEVEL=info
export MN_API_HOST=0.0.0.0
export MN_API_PORT=8080
mn-api ...

Model catalog overrides

The SDK uses the packaged mn_sdk/model_catalog.json as its baseline catalog. If present, $MN_HOME/models/catalog.json is loaded next; $MN_HOME defaults to ~/.mn. Entries are deep-merged by model ID, so an external entry can override selected fields while unmentioned built-in models remain available.

Set MN_MODEL_CATALOG_PATH to load a final, highest-priority catalog file. The file may be a model list, an object with a models list, or an object keyed by model ID. Paths support ~, $MN_HOME, and normal environment-variable expansion.

For example, this changes the bundled Gemma model endpoint and adds a new catalog entry without copying the entire packaged catalog:

mkdir -p "$MN_HOME/models"
cat > "$MN_HOME/models/catalog.json" <<'JSON'
{
  "models": [
    {
      "id": "gemma4:e2b",
      "model": "local/gemma4:E2B",
      "requirements": {"min_vram_gb": 4}
    },
    {
      "id": "my-local-model",
      "model": "local/my-model",
      "aliases": ["my-model"]
    }
  ]
}
JSON

Catalog precedence is:

1. Packaged mn_sdk/model_catalog.json.
2. $MN_HOME/models/catalog.json, when present.
3. MN_MODEL_CATALOG_PATH, when configured.

Matching entries are merged by id. Nested objects are merged recursively; scalar values and lists from the higher-priority catalog replace lower-priority values. A malformed existing catalog raises a validation error rather than being silently ignored.

Do not commit real .env files. Use .env.example for placeholders only, and put secrets in real environment variables or token files.

Notes

• A running MirrorNeuron core is required for live client calls.
• Constructor arguments take precedence over environment variables.
• Generated protocol modules are included with the package.