pleroma-client 1.0.0

Production-grade MCP client SDK for Pleroma Core — send SemanticIntent to the Pleroma Guardian

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:

# 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

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:

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:

# 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 file for details.