Metadata-Version: 2.4
Name: pleroma-client
Version: 1.0.0
Summary: Production-grade MCP client SDK for Pleroma Core — send SemanticIntent to the Pleroma Guardian
Author: Pleroma Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/pleroma-mcp/pleroma
Project-URL: Repository, https://github.com/pleroma-mcp/pleroma.git
Project-URL: Issues, https://github.com/pleroma-mcp/pleroma/issues
Classifier: Development Status :: 5 - Production/Stable
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 :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# Pleroma MCP Client SDK — v1.0.0 (Production-Ready)

Python client for [Pleroma Core](../) — send `SemanticIntent` to the Pleroma Guardian and receive structured, formally verified `ExecutionReceipt` responses.

Designed for robust agentic workflows, Pleroma Client manages network framing, connection tracking, real-time rate limiting, and standard authentication out-of-the-box.

---

## Features

- **Documented & Safe Handshakes**: Connects via plain TCP or secure TLS with automatic API key authentication.
- **Formal Guarantee integration**: Passes `SemanticIntent` to the Pleroma Cedar Guardian for constitutional compliance checking (SAT/UNSAT evaluation).
- **Execution Engine Interfacing**: Executes secure WASM modules within Pleroma's Saga Engine sandbox with rollbacks on failure.
- **Granular WASI Capability Negotiation**: Pass sandboxed system capability requests (`FsRead`, `FsWrite`, etc.) directly to the runtime.
- **Strict Error Handling**: Differentiates gracefully between `SUCCESS`, `BLOCKED` (constitutional rejection), `ROLLED_BACK` (WASM trap/non-zero exit), `RATE_LIMITED`, and `AUTH_FAILED`.

---

## Installation

Install the package in your Python environment:

```bash
# Setup virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install package in editable mode with development dependencies
pip install -e ".[dev]"
```

---

## Quick Start

```python
import asyncio
from pleroma_client import PleromaClient, execute_forensic_tool

async def main():
    # Establishes framed TCP connection and performs handshake
    async with PleromaClient(host="localhost", port=9090, api_key="your-api-key") as client:
        # Construct and send a semantic forensic intent
        intent = execute_forensic_tool("descompilador_ast", "abc123")
        
        # Execute securely under constitutional authorization
        receipt = await client.send_intent(intent)
        
        if receipt.is_success:
            print(f"Success: {receipt.message}")
        elif receipt.is_blocked:
            print(f"Blocked by constitution: {receipt.reason}")
        else:
            print(f"Error ({receipt.status}): {receipt.reason}")

if __name__ == "__main__":
    asyncio.run(main())
```

---

## Protocol & Architecture

Pleroma Client communicates with Pleroma Core using a framed TCP/TLS protocol:

1. **TCP Connection**: Client establishes connection to the Pleroma socket (default: `localhost:9090`).
2. **Auth Handshake**: If `PLEROMA_API_KEY` is set in the environment or client configuration, the client immediately sends `{"type": "auth", "token": "<key>"}` as framed bytes and receives `{"status": "AUTH_OK"}`.
3. **Intent Execution**:
   - Client frames `SemanticIntent` JSON and sends it.
   - Pleroma Core verifies compliance using **Cedar Policies**.
   - If permitted (SAT), Pleroma Core's **Saga Engine** runs the target WASM module.
   - If execution fails or traps, the transaction is **rolled back**.
   - Client receives a structured `ExecutionReceipt`.

---

## Data Models

### `SemanticIntent`

| Field | Type | Description |
|---|---|---|
| `id` | `str` | Unique transaction ID (UUIDv4) |
| `action` | `str` | Action namespace / tool to execute (e.g. `ejecutar_herramienta_forense`) |
| `target` | `str` | Resource path URI (e.g. `plexor://fs/tmp/analisis.wasm`) |
| `payload` | `bytes` | Optional raw binary WASM or data payload |
| `wasi_capabilities` | `list[str]` | Optional list of required WASI sandbox permissions (e.g. `["read", "write"]`) |

---

## Standard API Tools

Use the built-in helper functions to quickly instantiate standard semantic intents:

```python
from pleroma_client import read_file_semantic, execute_forensic_tool, emit_alert

# 1. Read episodic memory
intent = read_file_semantic("recent security incidents")

# 2. Run a forensic tool
intent = execute_forensic_tool("descompilador_ast", "hash_value")

# 3. Emit system operator alert
intent = emit_alert("warning", "Unauthorized kernel action blocked")
```

---

## Troubleshooting & Verification

To run unit and integration tests:

```bash
# Run existing tests suite
pytest

# Run the strict E2E tests against a compiled Rust binary
pytest tests/test_e2e.py
```

---

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.
