# MFP — Python Implementation

**Production-ready Python implementation of the Mirror Frame Protocol**

This is the reference Python implementation of [MFP](https://github.com/Madahub-dev/mfp-spec), a protocol for secure, peer-to-peer communication between autonomous agents. It provides end-to-end encrypted channels, federated message transport, and a minimal API for agent lifecycle management.

> **Protocol Specification:** For the complete MFP protocol design and specification, see [mfp-spec](https://github.com/Madahub-dev/mfp-spec)

## Features

- **Symmetric design** — no client/server distinction, all agents are peers
- **End-to-end encryption** — AES-256-GCM AEAD with HMAC-SHA-256 key derivation
- **Federation-ready** — bilateral channels, recovery protocols, TCP transport
- **Production hardening** — circuit breakers, timeouts, health checks, metrics
- **High performance** — Merkle tree for O(log N) global state updates
- **Library-first** — runtime embeds in any Python process
- **Standalone server** — YAML-configured process for managing agents
- **Type-safe** — full type annotations with `py.typed` marker

## Installation

```bash
pip install pymfp
```

Or install from source:

```bash
git clone https://github.com/Madahub-dev/MFP.git
cd MFP
pip install -e .
```

## Quickstart

**5-minute hello world between two agents:**

```python
from mfp import Runtime, RuntimeConfig, bind, mfp_send, mfp_channels

# Create a runtime
config = RuntimeConfig()
runtime = Runtime(config)

# Define two simple agent callables
# Each receives a DeliveredMessage and returns None
def alice(msg):
    print(f"Alice received: {msg.payload.decode()}")

def bob(msg):
    print(f"Bob received: {msg.payload.decode()}")

# Bind agents to the runtime
alice_handle = bind(runtime, alice)
bob_handle = bind(runtime, bob)

# Establish a channel between them (Layer 2 / admin operation)
channel_id = runtime.establish_channel(alice_handle.agent_id, bob_handle.agent_id)

# Send a message from Alice to Bob
receipt = mfp_send(
    alice_handle,
    channel_id=channel_id,
    payload=b"Hello from Alice!",
)

print(f"Message sent, receipt step: {receipt.step}")

# Shutdown
runtime.shutdown()
```

Run this script to see agents communicate through MFP channels.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Application                          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Public API: Runtime, bind/unbind, mfp_send/channels/status │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
   ┌─────────┐         ┌─────────┐        ┌──────────┐
   │ Runtime │◄────────┤  Agent  │◄───────┤ Storage  │
   │ Pipeline│         │Lifecycle│        │  Engine  │
   └─────────┘         └─────────┘        └──────────┘
        │                                       │
        ▼                                       ▼
   ┌─────────┐                            ┌──────────┐
   │  Core:  │                            │Federation│
   │ Crypto, │                            │Transport │
   │ Frames  │                            └──────────┘
   └─────────┘
```

**Layers:**
- **Core** — cryptographic primitives, frame construction/validation
- **Runtime** — agent callable pipeline, hooks, error handling
- **Agent** — lifecycle management (bind/unbind), tool interface
- **Storage** — persistent state, message queues, channel records
- **Federation** — bilateral channels, recovery, wire protocol, TCP server

## Documentation

**Python Implementation:**
- [Quickstart Guide](docs/quickstart.md) — step-by-step tutorial
- [Production Guide](docs/production-guide.md) — deployment and operations
- [API Reference](docs/api-reference.md) — library interface documentation
- [Server Guide](docs/server-guide.md) — standalone server configuration
- [Architecture](docs/architecture.md) — implementation design deep-dive
- [Security Model](docs/security.md) — threat model and guarantees
- [Contributing](docs/contributing.md) — development setup and guidelines

**Protocol Specification:**
- [MFP Spec Repository](https://github.com/Madahub-dev/mfp-spec) — complete protocol design and specification

## CLI Usage

Launch the standalone server:

```bash
mfp-server --config runtime.yaml
```

Or using Python module syntax:

```bash
python -m mfp --config runtime.yaml
```

## Development

Set up development environment:

```bash
# Clone and install with dev dependencies
git clone https://github.com/Madahub-dev/MFP.git
cd MFP
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=mfp --cov-report=term-missing
```

## Project Status

**Version:** 1.0.0 (Stable)

All 7 implementation phases complete. Full single-runtime pipeline, persistence (SQLite), federation (TCP bilateral channels), async support, per-channel message ordering, audit events with redaction, and sliding window rate limiting. See [IMPLEMENTATION.md](IMPLEMENTATION.md) for the full changelog.

**Test Coverage:** 813 tests passing (591 unit, 191 integration, 27 E2E, 4 benchmark)

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.

## Related Repositories

- [mfp-spec](https://github.com/Madahub-dev/mfp-spec) — MFP protocol specification and design documentation

## Credits

**MFP Python Implementation** — authored by Akil Abderrahim and Claude Sonnet 4.5
