Metadata-Version: 2.4
Name: metaspn-ops
Version: 0.1.0
Summary: Standard inbox/outbox worker runtime for MetaSPN agent systems
Author: MetaSPN Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/metaspn/metaspn-ops
Project-URL: Repository, https://github.com/metaspn/metaspn-ops
Project-URL: Issues, https://github.com/metaspn/metaspn-ops/issues
Keywords: metaspn,agents,worker,queue,scheduler
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Dynamic: license-file

# metaspn-ops

Standard inbox/outbox worker runtime for MetaSPN agent systems.

## Features

- Filesystem queue backend with inbox/outbox semantics
- Task leasing with lock files and lease expiration
- Retries with exponential backoff and dead-letter queue
- Worker runner with polling and parallel execution
- CLI for worker runs and queue operations

## Installation

```bash
pip install metaspn-ops
```

## Quickstart

### 1) Define a worker

```python
# example_worker.py
from metaspn_ops import Result, Task


class EnrichWorker:
    name = "enrich"

    def handle(self, task: Task) -> Result:
        payload = {"seen": task.payload}
        return Result(task_id=task.task_id, status="ok", payload=payload)
```

### 2) Run a worker once

```bash
metaspn worker run example_worker:EnrichWorker --workspace . --once --max-tasks 10
```

### 3) Queue inspection

```bash
metaspn queue stats enrich --workspace .
metaspn queue deadletter list enrich --workspace .
metaspn queue retry enrich --workspace .
```

## Queue layout

```text
workspace/
  inbox/{worker_name}/
  outbox/{worker_name}/
  runs/{worker_name}/
  deadletter/{worker_name}/
  locks/{worker_name}/
```

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
PYTHONPATH=src python -m unittest discover -s tests -v
python -m build
python -m twine check dist/*
```

## Release

- Tag a release in GitHub (for example `v0.1.0`).
- GitHub Actions builds and publishes to PyPI using trusted publishing.
- Configure a PyPI Trusted Publisher for this repository before the first release.
- See `/Users/leoguinan/MetaSPN/metaspn-ops/PUBLISHING.md` for the full flow.

## License

MIT
