Metadata-Version: 2.4
Name: macp-sdk-python
Version: 0.2.3
Summary: Python SDK for the MACP Rust runtime
Author-email: OpenAI <support@openai.com>
License: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.74.0
Requires-Dist: protobuf>=5.27.0
Requires-Dist: macp-proto<0.2.0,>=0.1.2
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: grpc-stubs>=1.53; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Dynamic: license-file

# macp-sdk-python

Python SDK for the [MACP](https://github.com/multiagentcoordinationprotocol/multiagentcoordinationprotocol) Rust runtime.

## What this package does

- Connects to the Rust runtime over gRPC
- Provides typed session helpers for all 5 standard coordination modes
- Maintains in-process projections for local state tracking
- Supports envelope builders, retry helpers, and structured logging

## Important runtime boundary

This SDK **calls** the Rust runtime. The runtime does not call into this Python package.
If you need runtime-driven business logic, run a Python agent/orchestrator as a separate process and let it communicate with the runtime over MACP transport.

## Install

```bash
pip install macp-sdk-python
```

## Quick start

### Production (Bearer + TLS)

```python
from macp_sdk import AuthConfig, DecisionSession, MacpClient

# TLS is the default; Bearer + expected_sender binds the session to this identity.
client = MacpClient(
    target="runtime.example.com:50051",
    auth=AuthConfig.for_bearer("tok-coord", expected_sender="coordinator"),
)
```

### Local dev (runtime started with `MACP_ALLOW_INSECURE=1`)

```python
client = MacpClient(
    target="127.0.0.1:50051",
    allow_insecure=True,                                # dev only
    auth=AuthConfig.for_dev_agent("coordinator"),
)
```

### Driving a decision

```python
session = DecisionSession(client)
session.start(
    intent="pick a deployment plan",
    participants=["coordinator", "alice", "bob"],
    ttl_ms=60_000,
)
session.propose("p1", "deploy v2.1", rationale="tests passed")
session.evaluate(
    "p1", "approve", confidence=0.94, reason="low risk",
    sender="alice", auth=AuthConfig.for_dev_agent("alice"),
)
session.vote(
    "p1", "approve", reason="ship it",
    sender="bob", auth=AuthConfig.for_dev_agent("bob"),
)

winner = session.decision_projection.majority_winner()
if winner and not session.decision_projection.has_blocking_objection(winner):
    session.commit(
        action="deployment.approved",
        authority_scope="release-management",
        reason=f"winner={winner}",
    )
```

## Supported modes

| Mode | Session Helper | Projection | Example |
|------|---------------|------------|---------|
| Decision | `DecisionSession` | `DecisionProjection` | `examples/decision_smoke.py` |
| Proposal | `ProposalSession` | `ProposalProjection` | `examples/proposal_negotiation.py` |
| Task | `TaskSession` | `TaskProjection` | `examples/task_delegation.py` |
| Handoff | `HandoffSession` | `HandoffProjection` | `examples/handoff_escalation.py` |
| Quorum | `QuorumSession` | `QuorumProjection` | `examples/quorum_approval.py` |

## Development

```bash
# Setup
make setup              # pip install -e ".[dev,docs]"

# Quality
make lint               # ruff check
make fmt                # ruff format
make typecheck          # mypy strict
make test               # unit tests
make test-all           # lint + typecheck + all tests
make coverage           # coverage report

# Build
make build              # sdist + wheel

# Proto definitions (provided by macp-proto package)
make dev-link-protos    # link local proto package for development
```

For local development against the runtime:

```bash
export MACP_ALLOW_INSECURE=1
export MACP_ALLOW_DEV_SENDER_HEADER=1
cargo run   # in the runtime repo
```

## Documentation

Full docs available in `docs/` — build with `mkdocs serve` after `make setup`.

## Architecture boundary

This SDK is a **thin typed client library**. It provides:
- Typed state models and action builders
- Session helpers (`propose()`, `vote()`, `commit()`)
- Local state projections (because `GetSession` returns metadata only)

Business logic — voting rules, AI decision heuristics, policy enforcement — belongs in the orchestrator/agent layer **above** the SDK.

## Known runtime limitations

- `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern
- `StreamSession` is scoped to one session per stream; use `MacpStream.send_subscribe(session_id)` (RFC-MACP-0006-A1, since SDK 0.2.3 / `macp-proto 0.1.2`) to replay accepted history before live broadcast
- Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer
