Metadata-Version: 2.4
Name: mirrorneuron-python-sdk
Version: 1.2.23
Summary: MirrorNeuron Python SDK
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.50.0
Requires-Dist: protobuf>=4.21.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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:

```bash
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:

```python
from mn_sdk import Client

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

## Details

- [MirrorNeuron Component Guide](../mn-docs/component-guide.md#python-sdk)
- [Python SDK](../mn-docs/SDK.md)
- [Job Bundle Format](../mn-docs/bundle.md)
- [Environment Variables](../mn-docs/env_variables.md)

## 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:

```bash
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:

```text
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:

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

Test example:

```bash
export MN_ENV=test
mn-cli ...
```

Production example:

```bash
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:

```bash
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.
