relay-middleware 0.1.0__tar.gz

relay_middleware-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kriday Dave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

relay_middleware-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: relay-middleware
+Version: 0.1.0
+Summary: A context-driven data pipeline and snapshotting library
+Author: Kriday Dave
+License: MIT License
+        
+        Copyright (c) 2026 Kriday Dave
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/kridaydave/relay
+Project-URL: Bug Tracker, https://github.com/kridaydave/relay/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest
+Requires-Dist: mypy
+Requires-Dist: pydantic
+Dynamic: license-file
+
+# Relay
+
+**Agent-agent context passing, done right.**
+
+Relay is a lightweight, open source Python middleware library for passing context reliably between AI agents in a multi-agent pipeline. Works with any LLM provider or framework — LangChain, OpenAI, Anthropic, LiteLLM, or your own agents.
+
+---
+
+## The Problem
+
+One hallucinating agent silently corrupts the shared context, and every downstream agent inherits the damage. Existing orchestration tools treat the context window as a mutable blob with no version control.
+
+## The Solution
+
+Relay treats context like a ledger: append-only, signed at every step, and reversible.
+
+---
+
+## Features
+
+- **Context Broker** — Normalizes, timestamps, and cryptographically signs context envelopes
+- **Handoff Validator** — Detects contradictions and triggers rollback on corruption
+- **Snapshot Store** — Persists immutable checkpoints for automatic rollback
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/kridaydave/Relay.git
+cd Relay
+pip install -e .
+```
+
+---
+
+## The Aha Moment
+
+**Without Relay** (manual, error-prone):
+
+```python
+# Agent 1 produces output
+agent1_output = {"entities": ["Apple", "2024 revenue"], "summary": "Apple grew"}
+
+# Manual serialization — easy to lose data, corrupt context
+context = json.dumps(agent1_output)
+
+# Agent 2 receives corrupted context
+agent2_input = f"Given: {context}\nAnalyze this."
+```
+
+**With Relay** (automatic, verified):
+
+```python
+from relay.pipeline import RelayPipeline
+
+pipeline = RelayPipeline(
+    signing_secret="your-secret-key",
+    token_budget=8000
+)
+
+# Agent 1 — creates signed envelope
+result = pipeline.execute_step({"entities": ["Apple"], "revenue": "2024"})
+envelope1 = result.value  # signed, immutable
+
+# Agent 2 — validator detects contradiction
+# If Agent 2 accidentally drops "entities", rollback triggers automatically
+result = pipeline.execute_step({"summary": "growth"})  # contradiction!
+```
+
+**What happens on contradiction:**
+
+```python
+# Validator detects: critical key "entities" disappeared
+# Relay automatically rolls back to last clean snapshot
+
+result = pipeline.rollback()
+restored_envelope = result.value
+# Now you have the clean envelope from step 1
+```
+
+---
+
+## How It Works
+
+```
+Agent 1 → [Sign Envelope] → Agent 2 → [Validate] → Agent 3
+                              ↓
+                         [Snapshot]
+                              ↓
+                    [Rollback if dirty]
+```
+
+Every handoff is signed and validated. If corruption is detected, Relay silently rolls back to the last clean checkpoint.
+
+---
+
+## Context Envelope
+
+Every context move between agents is wrapped in a signed, immutable envelope:
+
+```python
+{
+  "relay_version": "0.1.0",
+  "pipeline_id": "uuid-v4",
+  "step": 2,
+  "timestamp": "2026-05-04T10:22:00Z",
+  "token_budget_used": 1840,
+  "token_budget_total": 8000,
+  "payload": {...},
+  "signature": "sha256:abc123..."
+}
+```
+
+---
+
+## Error Handling
+
+Relay uses Result types instead of exceptions:
+
+```python
+from relay.types import Success, Failure, Result
+
+result = pipeline.execute_step({"task": "work"})
+if isinstance(result, Success):
+    envelope = result.value
+elif isinstance(result, Failure):
+    print(f"Error: {result.reason} (code: {result.code})")
+```
+
+---
+
+## Testing
+
+```bash
+pytest tests/unit -v
+```
+
+Quality gates:
+- mypy --strict passes
+- >80% test coverage
+- Every public function has a test
+
+---
+
+## License
+
+MIT License - see LICENSE file
+
+---
+
+## Resources
+
+- [Design Document](docs/Relay%20Design%20Document.txt)
+- [Coding Rules](docs/Relay%20Coding%20Rules.txt)

relay_middleware-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Relay
+
+**Agent-agent context passing, done right.**
+
+Relay is a lightweight, open source Python middleware library for passing context reliably between AI agents in a multi-agent pipeline. Works with any LLM provider or framework — LangChain, OpenAI, Anthropic, LiteLLM, or your own agents.
+
+---
+
+## The Problem
+
+One hallucinating agent silently corrupts the shared context, and every downstream agent inherits the damage. Existing orchestration tools treat the context window as a mutable blob with no version control.
+
+## The Solution
+
+Relay treats context like a ledger: append-only, signed at every step, and reversible.
+
+---
+
+## Features
+
+- **Context Broker** — Normalizes, timestamps, and cryptographically signs context envelopes
+- **Handoff Validator** — Detects contradictions and triggers rollback on corruption
+- **Snapshot Store** — Persists immutable checkpoints for automatic rollback
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/kridaydave/Relay.git
+cd Relay
+pip install -e .
+```
+
+---
+
+## The Aha Moment
+
+**Without Relay** (manual, error-prone):
+
+```python
+# Agent 1 produces output
+agent1_output = {"entities": ["Apple", "2024 revenue"], "summary": "Apple grew"}
+
+# Manual serialization — easy to lose data, corrupt context
+context = json.dumps(agent1_output)
+
+# Agent 2 receives corrupted context
+agent2_input = f"Given: {context}\nAnalyze this."
+```
+
+**With Relay** (automatic, verified):
+
+```python
+from relay.pipeline import RelayPipeline
+
+pipeline = RelayPipeline(
+    signing_secret="your-secret-key",
+    token_budget=8000
+)
+
+# Agent 1 — creates signed envelope
+result = pipeline.execute_step({"entities": ["Apple"], "revenue": "2024"})
+envelope1 = result.value  # signed, immutable
+
+# Agent 2 — validator detects contradiction
+# If Agent 2 accidentally drops "entities", rollback triggers automatically
+result = pipeline.execute_step({"summary": "growth"})  # contradiction!
+```
+
+**What happens on contradiction:**
+
+```python
+# Validator detects: critical key "entities" disappeared
+# Relay automatically rolls back to last clean snapshot
+
+result = pipeline.rollback()
+restored_envelope = result.value
+# Now you have the clean envelope from step 1
+```
+
+---
+
+## How It Works
+
+```
+Agent 1 → [Sign Envelope] → Agent 2 → [Validate] → Agent 3
+                              ↓
+                         [Snapshot]
+                              ↓
+                    [Rollback if dirty]
+```
+
+Every handoff is signed and validated. If corruption is detected, Relay silently rolls back to the last clean checkpoint.
+
+---
+
+## Context Envelope
+
+Every context move between agents is wrapped in a signed, immutable envelope:
+
+```python
+{
+  "relay_version": "0.1.0",
+  "pipeline_id": "uuid-v4",
+  "step": 2,
+  "timestamp": "2026-05-04T10:22:00Z",
+  "token_budget_used": 1840,
+  "token_budget_total": 8000,
+  "payload": {...},
+  "signature": "sha256:abc123..."
+}
+```
+
+---
+
+## Error Handling
+
+Relay uses Result types instead of exceptions:
+
+```python
+from relay.types import Success, Failure, Result
+
+result = pipeline.execute_step({"task": "work"})
+if isinstance(result, Success):
+    envelope = result.value
+elif isinstance(result, Failure):
+    print(f"Error: {result.reason} (code: {result.code})")
+```
+
+---
+
+## Testing
+
+```bash
+pytest tests/unit -v
+```
+
+Quality gates:
+- mypy --strict passes
+- >80% test coverage
+- Every public function has a test
+
+---
+
+## License
+
+MIT License - see LICENSE file
+
+---
+
+## Resources
+
+- [Design Document](docs/Relay%20Design%20Document.txt)
+- [Coding Rules](docs/Relay%20Coding%20Rules.txt)

relay_middleware-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "relay-middleware"
+version = "0.1.0"
+description = "A context-driven data pipeline and snapshotting library"
+readme = "README.md"
+authors = [
+  { name="Kriday Dave" }
+]
+license = { file="LICENSE" }
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pytest",
+    "mypy",
+    "pydantic",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/kridaydave/relay"
+"Bug Tracker" = "https://github.com/kridaydave/relay/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["."]
+omit = ["tests/*", "*/tests/*"]
+branch = true
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false

relay_middleware-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

relay_middleware-0.1.0/src/relay/__init__.py

@@ -0,0 +1 @@
+"""Relay - A Python project."""

relay_middleware-0.1.0/src/relay/context_broker.py

@@ -0,0 +1,55 @@
+"""Context envelope creation, signing, and lifecycle management for Relay.
+
+Owns: envelope lifecycle, cryptographic signing.
+Does NOT: validate agent output, persist snapshots, execute agents.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from relay.envelope import ContextEnvelope, create_initial_envelope, create_next_envelope
+from relay.types import Result, Success, Failure
+
+
+@dataclass(frozen=True)
+class ContextBroker:
+    """Manages context envelope creation and signing.
+
+    Owns: envelope lifecycle, cryptographic signing.
+    Does NOT: validate agent output, persist snapshots, execute agents.
+    """
+    signing_secret: str
+    token_budget_total: int
+
+    def create_initial_envelope(
+        self,
+        pipeline_id: str,
+        initial_payload: dict[str, Any]
+    ) -> Result[ContextEnvelope]:
+        """Create the first envelope for a pipeline."""
+        if not pipeline_id:
+            return Failure(reason="pipeline_id cannot be empty", code="INVALID_PIPELINE_ID")
+        if not initial_payload:
+            return Failure(reason="initial_payload cannot be empty", code="INVALID_PAYLOAD")
+
+        return create_initial_envelope(
+            pipeline_id=pipeline_id,
+            initial_payload=initial_payload,
+            token_budget_total=self.token_budget_total,
+            secret=self.signing_secret
+        )
+
+    def create_next_envelope(
+        self,
+        previous_envelope: ContextEnvelope,
+        agent_output: dict[str, Any]
+    ) -> Result[ContextEnvelope]:
+        """Create a subsequent envelope for the next step."""
+        if not agent_output:
+            return Failure(reason="agent_output cannot be empty", code="INVALID_PAYLOAD")
+
+        return create_next_envelope(
+            previous_envelope=previous_envelope,
+            agent_output=agent_output,
+            secret=self.signing_secret
+        )

relay_middleware-0.1.0/src/relay/core_pipeline.py

@@ -0,0 +1,152 @@
+"""Core pipeline orchestration for Relay v0.1.
+
+Owns: pipeline lifecycle, component coordination.
+Does NOT: define agent behavior, manage prompts.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+import uuid
+
+from relay.context_broker import ContextBroker
+from relay.envelope import ContextEnvelope
+from relay.snapshot import SnapshotStore
+from relay.types import Failure, Result, Success, RollbackSuccess
+from relay.validator import HandoffValidator, ValidationResult
+
+
+@dataclass
+class CoreRelayPipeline:
+    """Base class for pipeline orchestration.
+
+    Owns: pipeline lifecycle, component coordination.
+    Does NOT: define agent behavior, manage prompts.
+    """
+    signing_secret: str
+    token_budget: int = 8000
+    storage_path: str = "./relay_data/snapshots"
+
+    _pipeline_id: str = field(init=False, repr=False)
+    _context_broker: ContextBroker = field(init=False, repr=False)
+    _handoff_validator: HandoffValidator = field(init=False, repr=False)
+    _snapshot_store: SnapshotStore = field(init=False, repr=False)
+    _current_envelope: ContextEnvelope | None = field(default=None, init=False, repr=False)
+    _previous_envelopes: list[ContextEnvelope] = field(default_factory=list, init=False, repr=False)
+    _snapshot_ids: dict[str, str] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._pipeline_id = uuid.uuid4().hex
+        self._context_broker = ContextBroker(
+            signing_secret=self.signing_secret,
+            token_budget_total=self.token_budget
+        )
+        self._handoff_validator = HandoffValidator()
+        self._snapshot_store = SnapshotStore(storage_path=self.storage_path)
+
+    def execute_step(self, agent_output: dict[str, Any]) -> Result[ContextEnvelope]:
+        """Execute a pipeline step with agent output."""
+        if self._current_envelope is None:
+            envelope_result = self._context_broker.create_initial_envelope(
+                pipeline_id=self._pipeline_id,
+                initial_payload=agent_output
+            )
+            if isinstance(envelope_result, Failure):
+                return envelope_result
+
+            new_envelope = envelope_result.value
+            self._current_envelope = new_envelope
+            return Success(new_envelope)
+
+        envelope_result = self._context_broker.create_next_envelope(
+            previous_envelope=self._current_envelope,
+            agent_output=agent_output
+        )
+        if isinstance(envelope_result, Failure):
+            return envelope_result
+
+        new_envelope = envelope_result.value
+
+        self._previous_envelopes.append(self._current_envelope)
+
+        current_snapshot_result = self._snapshot_store.save_snapshot(self._current_envelope)
+        if isinstance(current_snapshot_result, Failure):
+            return current_snapshot_result
+        self._snapshot_ids[self._current_envelope.step] = current_snapshot_result.value
+
+        validation_result = self._handoff_validator.validate_handoff(
+            previous_envelope=self._current_envelope,
+            current_envelope=new_envelope
+        )
+        if isinstance(validation_result, Failure):
+            return validation_result
+
+        validation = validation_result.value
+        if self._handoff_validator.should_rollback(validation):
+            return self._rollback_to_previous(new_envelope, validation)
+
+        snapshot_result = self._snapshot_store.save_snapshot(new_envelope)
+        if isinstance(snapshot_result, Failure):
+            return snapshot_result
+
+        snapshot_id = snapshot_result.value
+        self._snapshot_ids[new_envelope.step] = snapshot_id
+        if self._previous_envelopes:
+            oldest_step = self._previous_envelopes[0].step
+            self._snapshot_ids.pop(oldest_step, None)
+
+        self._current_envelope = new_envelope
+        return Success(new_envelope)
+
+    def _rollback_to_previous(
+        self,
+        proposed_envelope: ContextEnvelope,
+        validation: ValidationResult
+    ) -> Result[ContextEnvelope]:
+        """Rollback to previous envelope on contradiction."""
+        reason = validation.contradiction_details or "Contradiction detected"
+        return self._rollback_to_previous_with_reason(proposed_envelope, reason)
+
+    def _rollback_to_previous_with_reason(
+        self,
+        proposed_envelope: ContextEnvelope,
+        reason: str
+    ) -> Result[ContextEnvelope]:
+        """Rollback to previous envelope with explicit reason."""
+        if not self._previous_envelopes:
+            return Failure(reason="No previous envelope to rollback to", code="NO_ROLLBACK_AVAILABLE")
+
+        previous_envelope = self._previous_envelopes[-1]
+        snapshot_id = self._snapshot_ids.get(previous_envelope.step)
+        if snapshot_id is None:
+            return Failure(reason="No snapshot registered for step", code="NO_SNAPSHOT_REGISTERED")
+
+        restore_result = self._snapshot_store.load_snapshot(snapshot_id)
+        if isinstance(restore_result, Failure):
+            return restore_result
+
+        restored_envelope = restore_result.value
+        self._current_envelope = restored_envelope
+        return RollbackSuccess(value=restored_envelope, reason=reason)
+
+    def rollback(self) -> Result[ContextEnvelope]:
+        """Rollback to the last clean state."""
+        if not self._previous_envelopes:
+            return Failure(reason="No previous envelope to rollback to", code="NO_ROLLBACK_AVAILABLE")
+
+        previous_envelope = self._previous_envelopes[-1]
+        snapshot_id = self._snapshot_ids.get(previous_envelope.step)
+        if snapshot_id is None:
+            return Failure(reason="No snapshot registered for step", code="NO_SNAPSHOT_REGISTERED")
+
+        restore_result = self._snapshot_store.load_snapshot(snapshot_id)
+        if isinstance(restore_result, Failure):
+            return restore_result
+
+        self._previous_envelopes.pop()
+        restored_envelope = restore_result.value
+        self._current_envelope = restored_envelope
+        return RollbackSuccess(value=restored_envelope, reason="Manual rollback")
+
+    def get_current_envelope(self) -> ContextEnvelope | None:
+        """Get the current envelope."""
+        return self._current_envelope