rrcp 0.1.0a0__tar.gz

rrcp-0.1.0a0/.gitignore

@@ -0,0 +1,10 @@
+.venv
+venv
+__pycache__
+.claude
+.ruff_cache
+.pytest_cache
+.mypy_cache
+dist
+*.egg-info
+/docs/plans

rrcp-0.1.0a0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0a0
+
+First version.

rrcp-0.1.0a0/CLAUDE.md

@@ -0,0 +1,142 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Philosophy (READ FIRST)
+
+rrcp is a **Communication Protocol** for assistant-driven threads where multiple
+users and multiple assistants can interact. It is NOT an AI framework, NOT an LLM
+wrapper, and NOT a chat application — it is the wire and the storage underneath them.
+
+### Core principles
+
+1. **Business agnostic.** The SDK never inspects credentials, never decides who can
+   do what, and never owns user/assistant/tool data shapes beyond `{ id, name }`.
+   Authentication, authorization, and tenancy semantics are consumer territory,
+   exposed through callbacks (`authenticate`, `authorize`) and opaque scope keys.
+
+2. **Communication-first.** The SDK ships exactly four primitives: identities,
+   threads, events, runs. Everything else is composition by the consumer.
+
+3. **REST for state, WebSocket for delivery.** Anything that can be a request/response
+   IS a request/response. Socket.IO carries subscriptions and live event push.
+   Action operations exist in both transports as thin shells over one handler.
+
+4. **Plug and play.** A consumer should be able to mount the SDK on their existing
+   FastAPI/Hono app in <30 lines and have a working multi-assistant chat backend.
+   No forced microservices, no forced migrations of existing user/auth tables.
+
+5. **Drop everything else.** No streaming, no MCP client, no A2A, no settings
+   broadcaster, no knowledge sources, no built-in form rendering, no built-in
+   blob storage. If a consumer needs these, they bring them.
+
+### What goes where
+
+- **Wire/storage primitive?** → in the SDK
+- **Real-time push to subscribers?** → Socket.IO event
+- **Request/response, no live push?** → REST endpoint
+- **Decision the SDK shouldn't be making?** → consumer callback
+- **Reasonable in 80% of cases?** → SDK default with opt-out
+- **UI/render concern?** → docs example, not SDK code
+
+### When in doubt, follow
+
+> "Could the consumer build this themselves with the primitives we already ship?"
+> If yes, do not add it to the SDK.
+
+### CHANGELOG discipline
+
+- Every PR touching `src/` updates `CHANGELOG.md` under `## [Unreleased]`.
+- Breaking changes get a `BREAKING:` prefix and bump major (in lockstep with the
+  other two repos: `rrcp-client-ts` and `rrcp-ts`).
+- Breaking changes ship side-by-side migration notes in the changelog entry.
+- The `changelog.yml` GitHub Action blocks PRs that touch `src/` without
+  updating `CHANGELOG.md`.
+
+## Repo role
+
+`rrcp` (PyPI name) is the **Python server SDK** for the rrcp protocol.
+It is the consumer-facing Python library that ships REST + Socket.IO endpoints
+mountable onto FastAPI (or any ASGI app), backed by Postgres.
+
+Built on:
+
+- **Python 3.11+**
+- **Pydantic** for protocol models
+- **python-socketio (ASGI)** for the live transport
+- **asyncpg** for the Postgres reference `ThreadStore`
+- **FastAPI compatible** — mounts as a router on existing FastAPI apps
+
+It is part of a three-repo family. Major versions are in lockstep:
+
+| Repo | Publishes to | Package name |
+|---|---|---|
+| `rrcp-client-ts` | npm | `@0x0064/rrcp-react` |
+| `rrcp-py` (this repo) | PyPI | `rrcp` |
+| `rrcp-ts` | npm | `@0x0064/rrcp` |
+
+
+## Commands
+
+```bash
+uv sync --all-extras         # Install all dependencies
+uv run poe dev               # Full sanity check: lint + typecheck + test
+uv run poe build             # Build wheel + sdist (python -m build)
+uv run poe format            # Format code (ruff format)
+uv run poe format:imports    # Sort imports
+uv run poe check             # Lint only (ruff check)
+uv run poe check:fix         # Auto-fix lint issues
+uv run poe typecheck         # Type check only (mypy src/)
+uv run poe test              # Run tests
+uv run poe test:cov          # Tests with coverage
+```
+
+Run a single test: `uv run pytest tests/path/to/test.py::test_name -v`
+
+### Tests require a Postgres connection
+
+Two options. **Either** spin up the bundled docker-compose (zero config):
+
+```bash
+docker compose -f docker-compose.test.yml up -d
+uv run poe test
+```
+
+**Or** point at your own Postgres via `DATABASE_URL` (use a dedicated test database
+— tests truncate tables between runs, never point at dev or prod):
+
+```bash
+createdb rrcp_test
+DATABASE_URL=postgresql://localhost/rrcp_test uv run poe test
+```
+
+The schema in `src/rrcp/store/postgres/schema.sql` is auto-applied on the first
+test run via `CREATE TABLE IF NOT EXISTS`. No migrations to manage manually.
+
+Default `DATABASE_URL` (when unset) points at the docker-compose service:
+`postgresql://rrcp:rrcp@localhost:55432/rrcp_test`
+
+## Architecture
+
+See `docs/plans/2026-04-09-rrcp-v2-design.md` for the full architecture.
+
+Source layout (target):
+
+```
+src/rrcp/
+  server/        # ThreadServer entrypoint, lifecycle
+  protocol/      # Pydantic frame types, parser, mappers
+  store/         # ThreadStore protocol + PostgresThreadStore
+  handler/       # HandlerContext, HandlerSend, run executor
+  socketio/      # Socket.IO event handlers
+  rest/          # FastAPI router (/threads, /events, /runs, ...)
+  analytics/     # AnalyticsCollector (consumer-callback sink)
+```
+
+## Code Style
+
+- Python 3.11+, ruff for linting/formatting, line length 120
+- Quote style: double quotes
+- Ruff rules: E, F, I (isort), UP (pyupgrade)
+- `pytest-asyncio` with `asyncio_mode = "auto"` (no need for `@pytest.mark.asyncio`)
+- Pydantic for all models; dataclasses for config objects

rrcp-0.1.0a0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: rrcp
+Version: 0.1.0a0
+Summary: rrcp - agent communication protocol
+Project-URL: Repository, https://github.com/0x0064/rrcp
+Author-email: 0x0064 <user.frndvrgs@gmail.com>
+License-Expression: MIT
+Keywords: acp,agent,ai,assistant,python,rrcp,sdk
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-socketio[asgi]<6,>=5.13.0
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.11.0; extra == 'dev'
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: fastapi>=0.117.0; extra == 'dev'
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: poethepoet>=0.42.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.15.7; extra == 'dev'
+Requires-Dist: uvicorn>=0.32.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rrcp
+
+rrcp - agent communication protocol
+
+## License
+
+## License
+
+MIT — see [`LICENSE`](../../LICENSE).

rrcp-0.1.0a0/README.md

@@ -0,0 +1,9 @@
+# rrcp
+
+rrcp - agent communication protocol
+
+## License
+
+## License
+
+MIT — see [`LICENSE`](../../LICENSE).

rrcp-0.1.0a0/docker-compose.test.yml

@@ -0,0 +1,14 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: rrcp
+      POSTGRES_PASSWORD: rrcp
+      POSTGRES_DB: rrcp_test
+    ports:
+      - "55432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U rrcp -d rrcp_test"]
+      interval: 1s
+      timeout: 5s
+      retries: 10

rrcp-0.1.0a0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "rrcp"
+version = "0.1.0a0"
+description = "rrcp - agent communication protocol"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    {name = "0x0064", email = "user.frndvrgs@gmail.com"},
+]
+keywords = [
+    "rrcp",
+    "acp",
+    "assistant",
+    "agent",
+    "sdk",
+    "ai",
+    "python"
+]
+
+dependencies = [
+    "pydantic>=2.12.5",
+    "asyncpg>=0.31.0",
+    "python-socketio[asgi]>=5.13.0,<6",
+]
+
+[project.urls]
+Repository = "https://github.com/0x0064/rrcp"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rrcp"]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.19.1",
+    "poethepoet>=0.42.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.15.7",
+    "fastapi>=0.117.0",
+    "httpx>=0.28.1",
+    "uvicorn>=0.32.0",
+    "aiohttp>=3.11.0",
+    "build>=1.2.2",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[[tool.mypy.overrides]]
+module = ["asyncpg", "asyncpg.*", "socketio", "socketio.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"
+
+[tool.poe.tasks]
+format = "ruff format ."
+"format:imports" = "ruff check --select I --fix ."
+check = "ruff check ."
+"check:fix" = "ruff check --fix ."
+typecheck = "mypy src/rrcp"
+test = "pytest"
+"test:cov" = "pytest --cov=src --cov-report=term-missing"
+dev = ["check", "typecheck", "test"]
+build = "python -m build"

rrcp-0.1.0a0/src/rrcp/__init__.py

@@ -0,0 +1,129 @@
+from importlib.metadata import version as _pkg_version
+
+__version__ = _pkg_version("rrcp")
+
+from rrcp.analytics.collector import (
+    AnalyticsEvent,
+    AssistantAnalytics,
+    OnAnalyticsCallback,
+)
+from rrcp.broadcast.protocol import Broadcaster
+from rrcp.broadcast.recording import RecordingBroadcaster
+from rrcp.broadcast.socketio import SocketIOBroadcaster
+from rrcp.handler.context import HandlerContext
+from rrcp.handler.send import HandlerSend
+from rrcp.handler.types import HandlerCallable
+from rrcp.protocol.content import (
+    AudioPart,
+    ContentPart,
+    DocumentPart,
+    FormPart,
+    FormStatus,
+    ImagePart,
+    TextPart,
+    parse_content_part,
+)
+from rrcp.protocol.event import (
+    Event,
+    EventDraft,
+    MessageEvent,
+    ReasoningEvent,
+    RunCancelledEvent,
+    RunCompletedEvent,
+    RunFailedEvent,
+    RunStartedEvent,
+    ThreadCreatedEvent,
+    ThreadMemberAddedEvent,
+    ThreadMemberRemovedEvent,
+    ThreadTenantChangedEvent,
+    ToolCall,
+    ToolCallEvent,
+    ToolResult,
+    ToolResultEvent,
+    parse_event,
+)
+from rrcp.protocol.identity import (
+    AssistantIdentity,
+    Identity,
+    SystemIdentity,
+    UserIdentity,
+    parse_identity,
+)
+from rrcp.protocol.run import Run, RunError, RunStatus
+from rrcp.protocol.tenant import TenantScope, matches
+from rrcp.protocol.thread import Thread, ThreadMember, ThreadPatch
+from rrcp.server.auth import AuthenticateCallback, AuthorizeCallback, HandshakeData
+from rrcp.server.namespace import (
+    NamespaceViolation,
+    derive_namespace_path,
+    parse_namespace_path,
+    validate_namespace_value,
+)
+from rrcp.server.thread_server import ThreadServer
+from rrcp.store.postgres.store import PostgresThreadStore
+from rrcp.store.protocol import ThreadStore
+from rrcp.store.types import EventCursor, Page, ThreadCursor
+
+__all__ = [
+    "ThreadServer",
+    "AnalyticsEvent",
+    "AssistantAnalytics",
+    "AssistantIdentity",
+    "AudioPart",
+    "AuthenticateCallback",
+    "AuthorizeCallback",
+    "Broadcaster",
+    "ContentPart",
+    "DocumentPart",
+    "Event",
+    "EventCursor",
+    "EventDraft",
+    "FormPart",
+    "FormStatus",
+    "HandlerCallable",
+    "HandlerContext",
+    "HandlerSend",
+    "HandshakeData",
+    "Identity",
+    "ImagePart",
+    "MessageEvent",
+    "NamespaceViolation",
+    "OnAnalyticsCallback",
+    "Page",
+    "PostgresThreadStore",
+    "ReasoningEvent",
+    "RecordingBroadcaster",
+    "Run",
+    "RunCancelledEvent",
+    "RunCompletedEvent",
+    "RunError",
+    "RunFailedEvent",
+    "RunStartedEvent",
+    "RunStatus",
+    "SocketIOBroadcaster",
+    "SystemIdentity",
+    "TenantScope",
+    "TextPart",
+    "Thread",
+    "ThreadCreatedEvent",
+    "ThreadCursor",
+    "ThreadMember",
+    "ThreadMemberAddedEvent",
+    "ThreadMemberRemovedEvent",
+    "ThreadPatch",
+    "ThreadStore",
+    "ThreadTenantChangedEvent",
+    "ToolCall",
+    "ToolCallEvent",
+    "ToolResult",
+    "ToolResultEvent",
+    "UserIdentity",
+    "__version__",
+    "derive_namespace_path",
+    "matches",
+    "parse_content_part",
+    "parse_event",
+    "parse_identity",
+    "parse_namespace_path",
+    "validate_namespace_value",
+]

rrcp-0.1.0a0/src/rrcp/analytics/__init__.py

@@ -0,0 +1,3 @@
+from rrcp.analytics.collector import AnalyticsEvent, AssistantAnalytics, OnAnalyticsCallback
+
+__all__ = ["AnalyticsEvent", "AssistantAnalytics", "OnAnalyticsCallback"]

rrcp-0.1.0a0/src/rrcp/analytics/collector.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AnalyticsEvent(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str
+    properties: dict[str, Any] = Field(default_factory=dict)
+    thread_id: str | None = None
+    run_id: str | None = None
+    assistant_id: str | None = None
+    timestamp: datetime
+
+
+OnAnalyticsCallback = Callable[[list[AnalyticsEvent]], Awaitable[None]]
+
+
+class AssistantAnalytics:
+    def __init__(
+        self,
+        on_analytics: OnAnalyticsCallback | None,
+        thread_id: str,
+        run_id: str,
+        assistant_id: str,
+    ) -> None:
+        self._on_analytics = on_analytics
+        self._thread_id = thread_id
+        self._run_id = run_id
+        self._assistant_id = assistant_id
+        self._buffer: list[AnalyticsEvent] = []
+
+    def track(self, name: str, properties: dict[str, Any] | None = None) -> None:
+        self._buffer.append(
+            AnalyticsEvent(
+                name=name,
+                properties=properties or {},
+                thread_id=self._thread_id,
+                run_id=self._run_id,
+                assistant_id=self._assistant_id,
+                timestamp=datetime.now(UTC),
+            )
+        )
+
+    async def flush(self) -> None:
+        if not self._buffer or self._on_analytics is None:
+            self._buffer = []
+            return
+        events = self._buffer
+        self._buffer = []
+        await self._on_analytics(events)

rrcp-0.1.0a0/src/rrcp/broadcast/__init__.py

@@ -0,0 +1,5 @@
+from rrcp.broadcast.protocol import Broadcaster
+from rrcp.broadcast.recording import RecordingBroadcaster
+from rrcp.broadcast.socketio import SocketIOBroadcaster
+
+__all__ = ["Broadcaster", "RecordingBroadcaster", "SocketIOBroadcaster"]

rrcp-0.1.0a0/src/rrcp/broadcast/protocol.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from rrcp.protocol.event import Event
+from rrcp.protocol.identity import Identity
+from rrcp.protocol.run import Run
+from rrcp.protocol.thread import Thread
+
+
+class Broadcaster(Protocol):
+    async def broadcast_event(self, event: Event, *, namespace: str | None = None) -> None: ...
+    async def broadcast_thread_updated(self, thread: Thread, *, namespace: str | None = None) -> None: ...
+    async def broadcast_members_updated(
+        self,
+        thread_id: str,
+        members: list[Identity],
+        *,
+        namespace: str | None = None,
+    ) -> None: ...
+    async def broadcast_run_updated(self, run: Run, *, namespace: str | None = None) -> None: ...

rrcp-0.1.0a0/src/rrcp/broadcast/recording.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from rrcp.protocol.event import Event
+from rrcp.protocol.identity import Identity
+from rrcp.protocol.run import Run
+from rrcp.protocol.thread import Thread
+
+
+class RecordingBroadcaster:
+    def __init__(self) -> None:
+        self.events: list[Event] = []
+        self.threads_updated: list[Thread] = []
+        self.members_updated: list[tuple[str, list[Identity]]] = []
+        self.runs_updated: list[Run] = []
+        self.events_with_namespace: list[tuple[Event, str | None]] = []
+        self.threads_updated_with_namespace: list[tuple[Thread, str | None]] = []
+        self.members_updated_with_namespace: list[tuple[str, list[Identity], str | None]] = []
+        self.runs_updated_with_namespace: list[tuple[Run, str | None]] = []
+
+    async def broadcast_event(self, event: Event, *, namespace: str | None = None) -> None:
+        self.events.append(event)
+        self.events_with_namespace.append((event, namespace))
+
+    async def broadcast_thread_updated(self, thread: Thread, *, namespace: str | None = None) -> None:
+        self.threads_updated.append(thread)
+        self.threads_updated_with_namespace.append((thread, namespace))
+
+    async def broadcast_members_updated(
+        self,
+        thread_id: str,
+        members: list[Identity],
+        *,
+        namespace: str | None = None,
+    ) -> None:
+        self.members_updated.append((thread_id, members))
+        self.members_updated_with_namespace.append((thread_id, members, namespace))
+
+    async def broadcast_run_updated(self, run: Run, *, namespace: str | None = None) -> None:
+        self.runs_updated.append(run)
+        self.runs_updated_with_namespace.append((run, namespace))

rrcp-0.1.0a0/src/rrcp/broadcast/socketio.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import socketio
+
+from rrcp.protocol.event import Event
+from rrcp.protocol.identity import Identity
+from rrcp.protocol.run import Run
+from rrcp.protocol.thread import Thread
+
+
+def _thread_room(thread_id: str) -> str:
+    return f"thread:{thread_id}"
+
+
+class SocketIOBroadcaster:
+    def __init__(self, sio: socketio.AsyncServer) -> None:
+        self._sio = sio
+
+    async def broadcast_event(self, event: Event, *, namespace: str | None = None) -> None:
+        await self._sio.emit(
+            "event",
+            event.model_dump(mode="json", by_alias=True),
+            room=_thread_room(event.thread_id),
+            namespace=namespace or "/",
+        )
+
+    async def broadcast_thread_updated(self, thread: Thread, *, namespace: str | None = None) -> None:
+        await self._sio.emit(
+            "thread:updated",
+            thread.model_dump(mode="json", by_alias=True),
+            room=_thread_room(thread.id),
+            namespace=namespace or "/",
+        )
+
+    async def broadcast_members_updated(
+        self,
+        thread_id: str,
+        members: list[Identity],
+        *,
+        namespace: str | None = None,
+    ) -> None:
+        await self._sio.emit(
+            "members:updated",
+            {
+                "thread_id": thread_id,
+                "members": [m.model_dump(mode="json") for m in members],
+            },
+            room=_thread_room(thread_id),
+            namespace=namespace or "/",
+        )
+
+    async def broadcast_run_updated(self, run: Run, *, namespace: str | None = None) -> None:
+        await self._sio.emit(
+            "run:updated",
+            run.model_dump(mode="json", by_alias=True),
+            room=_thread_room(run.thread_id),
+            namespace=namespace or "/",
+        )

rrcp-0.1.0a0/src/rrcp/handler/__init__.py

@@ -0,0 +1,6 @@
+from rrcp.handler.context import HandlerContext
+from rrcp.handler.executor import RunExecutor
+from rrcp.handler.send import HandlerSend
+from rrcp.handler.types import HandlerCallable
+
+__all__ = ["HandlerCallable", "HandlerContext", "HandlerSend", "RunExecutor"]

rrcp-0.1.0a0/src/rrcp/handler/context.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from rrcp.analytics.collector import AssistantAnalytics
+from rrcp.protocol.event import Event
+from rrcp.protocol.identity import AssistantIdentity, Identity
+from rrcp.protocol.run import Run
+from rrcp.protocol.thread import Thread
+from rrcp.store.protocol import ThreadStore
+
+InvokeAssistantCallable = Callable[[str], Awaitable[Run]]
+
+
+class HandlerContext:
+    def __init__(
+        self,
+        store: ThreadStore,
+        thread: Thread,
+        run: Run,
+        assistant: AssistantIdentity,
+        analytics: AssistantAnalytics,
+        invoke_assistant: InvokeAssistantCallable | None = None,
+    ) -> None:
+        self._store = store
+        self._invoke_assistant = invoke_assistant
+        self.thread = thread
+        self.run = run
+        self.assistant = assistant
+        self.analytics = analytics
+
+    async def events(self, limit: int | None = None) -> list[Event]:
+        page = await self._store.list_events(self.thread.id, limit=limit or 100)
+        return page.items
+
+    async def members(self) -> list[Identity]:
+        rows = await self._store.list_members(self.thread.id)
+        return [m.identity for m in rows]
+
+    async def invoke(self, assistant_id: str) -> Run:
+        if self._invoke_assistant is None:
+            raise RuntimeError("ctx.invoke is not available: no handler_resolver configured")
+        return await self._invoke_assistant(assistant_id)