Metadata-Version: 2.4
Name: mirrorneuron-python-sdk
Version: 1.1.0
Summary: MirrorNeuron Python SDK
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.50.0
Requires-Dist: protobuf>=4.21.0
Dynamic: license-file

# MirrorNeuron Python SDK

Python client and workflow-bundle helpers for MirrorNeuron.

The SDK provides the gRPC client used by the CLI and API, plus decorators and bundle generation utilities for Python-defined workflows.

## Features

- gRPC `Client` wrapper for job and runtime operations.
- Decorators for defining workflow and agent functions in Python.
- Bundle generation from decorated workflow classes.
- Runner, retry, and backpressure configuration helpers.
- Environment-based client configuration for local tools and services.

## Tech Stack

| Area | Tooling |
| --- | --- |
| Runtime | Python 3.9+ |
| Transport | gRPC |
| Protocol | Protobuf |
| Packaging | setuptools with setuptools-scm |

## Prerequisites

- Python 3.9 or newer.
- A running MirrorNeuron core for client calls.
- Generated protocol modules included with the package.

## Installation

The released-package installer installs this package automatically.

Standalone install:

```bash
pip install mirrorneuron-python-sdk
```

Developer install:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Configuration

Constructor arguments take precedence over environment variables.

| Variable | Default | Description |
| --- | --- | --- |
| `MN_GRPC_TARGET` | `localhost:50051` | Core gRPC target when `Client(target=...)` is omitted. |
| `MN_CORE_GRPC_TARGET` | unset | Fallback core gRPC target. |
| `MN_GRPC_TIMEOUT_SECONDS` | `10` | Per-RPC timeout. Use `0` or `none` to disable. |
| `MN_GRPC_AUTH_TOKEN` | unset | Optional bearer metadata. |
| `MN_SDK_LOG_PATH` | `~/.mn/logs/sdk.log` | SDK log file path. |
| `MN_LOG_LEVEL` | package default | Log level used by shared logging setup. |
| `MN_LOG_MAX_BYTES` | package default | Rotating log size limit. |
| `MN_LOG_BACKUP_COUNT` | package default | Rotating log backup count. |

## Client Usage

```python
from mn_sdk import Client

client = Client(target="localhost:50051")
job_id = client.submit_job(manifest_json="...", payloads={})

print(client.get_job(job_id))
```

Common client methods:

| Method | Description |
| --- | --- |
| `submit_job(manifest_json, payloads)` | Submit a job from a manifest string and payload map. |
| `get_job(job_id)` | Fetch one job. |
| `list_jobs(limit=0, include_terminal=True)` | List jobs. |
| `cancel_job(job_id)` | Cancel a job. |
| `pause_job(job_id)` | Pause a job. |
| `resume_job(job_id)` | Resume a job. |
| `clear_jobs()` | Clear job history. |
| `get_system_summary()` | Fetch runtime summary. |
| `remove_node(node_name)` | Remove a node from the runtime view. |
| `stream_events(job_id)` | Stream job events. |

## Python Workflow Example

```python
from pathlib import Path

from mn_sdk import RunnerConfig, agent, build_bundle, workflow


@agent.defn(type="map", runner=RunnerConfig.host_local())
def normalize_text(value: str) -> str:
    return value.strip().lower()


@workflow.defn(name="TextWorkflow")
class TextWorkflow:
    @workflow.run
    def run(self):
        normalize_text("  Example  ")


bundle_dir = build_bundle(TextWorkflow, Path("/tmp/text-workflow"))
print(bundle_dir)
```

The generated bundle can be submitted with the CLI:

```bash
mn run /tmp/text-workflow
```

## Public API

The package exports:

- `Client`
- `agent`
- `workflow`
- `build_bundle`
- `BundleCompileError`
- `RunnerConfig`
- `RetryPolicy`
- `BackpressurePolicy`

## Testing

```bash
python3 -m pytest -q
```

## Deployment

Applications can depend on `mirrorneuron-python-sdk` directly when they need to submit jobs or generate bundles programmatically. Runtime deployment still requires the MirrorNeuron core and its backing services.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| gRPC connection fails | Confirm the core is running and `MN_GRPC_TARGET` points to it. |
| Calls hang longer than expected | Set `MN_GRPC_TIMEOUT_SECONDS`. |
| Authenticated gateway rejects calls | Set `MN_GRPC_AUTH_TOKEN`. |
| Bundle generation fails | Check that the workflow class is decorated and that referenced agent calls are statically discoverable. |

## Contributing

Keep SDK changes backward-compatible with the CLI and API. Add focused tests for client calls, bundle generation, and configuration behavior.

## License

MIT.
