polytrax 0.1.0__tar.gz

polytrax-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PolyTrax Contributors
+
+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.

polytrax-0.1.0/MANIFEST.in

@@ -0,0 +1,20 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+graft polytrax/src/polytrax
+exclude polytrax/src/polytrax/.DS_Store
+
+prune apps
+prune build
+prune demo
+prune dist
+prune evaluation
+prune polytrax/tests
+prune polytrax/src/polytrax.egg-info
+prune polytrax_lecacy_poc
+prune tests
+
+global-exclude .DS_Store
+global-exclude __pycache__
+global-exclude *.py[cod]

polytrax-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: polytrax
+Version: 0.1.0
+Summary: Communication-level observability framework for trust integrity in multi-agent systems
+Author: Mindula Jayasinghe
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Mindulaaa/polytrax
+Project-URL: Documentation, https://github.com/Mindulaaa/polytrax/tree/main/docs
+Project-URL: Repository, https://github.com/Mindulaaa/polytrax
+Project-URL: Issues, https://github.com/Mindulaaa/polytrax/issues
+Keywords: multi-agent,ai,observability,trust,evaluation,langgraph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
+Provides-Extra: semantic
+Requires-Dist: numpy>=1.24; extra == "semantic"
+Requires-Dist: sentence-transformers>=2.2.2; extra == "semantic"
+Provides-Extra: full
+Requires-Dist: langgraph>=0.2.0; extra == "full"
+Requires-Dist: numpy>=1.24; extra == "full"
+Requires-Dist: openai>=1.0.0; extra == "full"
+Requires-Dist: sentence-transformers>=2.2.2; extra == "full"
+Dynamic: license-file
+
+# PolyTrax
+
+PolyTrax is a Python library for communication-level observability, runtime trust control, and post-run analysis in multi-agent systems.
+
+It provides:
+
+- Universal Structured Log (USL) schema and validation
+- Event instrumentation utilities and sinks
+- Runtime Trust Perturbation Score (R-TPS) monitoring and intervention policies
+- Offline propagation and containment analysis
+- Evaluation tooling (deterministic and LLM-based judges)
+
+## Install
+
+Core library:
+
+```bash
+pip install polytrax
+```
+
+With optional integrations:
+
+```bash
+pip install "polytrax[openai]"      # LLM judge via OpenAI-compatible APIs
+pip install "polytrax[langgraph]"   # LangGraph adapter
+pip install "polytrax[semantic]"    # Semantic drift/localization extras
+pip install "polytrax[full]"        # All optional dependencies
+```
+
+## Quick Example
+
+```python
+from polytrax.instrumentation import Instrumentor, EventBuilder
+from polytrax.sinks import MemorySink
+
+sink = MemorySink()
+instr = Instrumentor(run_id="demo_run", sinks=[sink])
+builder = EventBuilder(run_id="demo_run")
+
+event = (
+    builder
+    .with_sender("collector_1")
+    .with_receiver("analyst_1")
+    .with_payload({"message": "hello"})
+    .build()
+)
+
+instr.emit(event)
+print(len(sink.events))
+```
+
+## CLI
+
+Evaluation runner:
+
+```bash
+polytrax-eval --runs-dir ./runs --output-filename eval.json
+```
+
+## Project Layout
+
+- Publishable library package: `polytrax/src/polytrax`
+- Demo frontend/backend app (not packaged): `apps/polytrax_demo`
+- Evaluation protocols and scripts: `evaluation`
+
+## License
+
+MIT

polytrax-0.1.0/README.md

@@ -0,0 +1,68 @@
+# PolyTrax
+
+PolyTrax is a Python library for communication-level observability, runtime trust control, and post-run analysis in multi-agent systems.
+
+It provides:
+
+- Universal Structured Log (USL) schema and validation
+- Event instrumentation utilities and sinks
+- Runtime Trust Perturbation Score (R-TPS) monitoring and intervention policies
+- Offline propagation and containment analysis
+- Evaluation tooling (deterministic and LLM-based judges)
+
+## Install
+
+Core library:
+
+```bash
+pip install polytrax
+```
+
+With optional integrations:
+
+```bash
+pip install "polytrax[openai]"      # LLM judge via OpenAI-compatible APIs
+pip install "polytrax[langgraph]"   # LangGraph adapter
+pip install "polytrax[semantic]"    # Semantic drift/localization extras
+pip install "polytrax[full]"        # All optional dependencies
+```
+
+## Quick Example
+
+```python
+from polytrax.instrumentation import Instrumentor, EventBuilder
+from polytrax.sinks import MemorySink
+
+sink = MemorySink()
+instr = Instrumentor(run_id="demo_run", sinks=[sink])
+builder = EventBuilder(run_id="demo_run")
+
+event = (
+    builder
+    .with_sender("collector_1")
+    .with_receiver("analyst_1")
+    .with_payload({"message": "hello"})
+    .build()
+)
+
+instr.emit(event)
+print(len(sink.events))
+```
+
+## CLI
+
+Evaluation runner:
+
+```bash
+polytrax-eval --runs-dir ./runs --output-filename eval.json
+```
+
+## Project Layout
+
+- Publishable library package: `polytrax/src/polytrax`
+- Demo frontend/backend app (not packaged): `apps/polytrax_demo`
+- Evaluation protocols and scripts: `evaluation`
+
+## License
+
+MIT

polytrax-0.1.0/polytrax/src/polytrax/__init__.py

@@ -0,0 +1,7 @@
+"""PolyTrax — multi-agent communication framework."""
+
+from .usl import USL_VERSION
+
+__version__ = "0.1.0"
+
+__all__ = ["USL_VERSION", "__version__"]

polytrax-0.1.0/polytrax/src/polytrax/adapters/__init__.py

@@ -0,0 +1,27 @@
+# polytrax/src/polytrax/adapters/__init__.py
+"""
+polytrax.adapters — runtime adapter contracts and integrations.
+
+- RuntimeAdapter: abstract contract for runtime integrations.
+- GenericAdapter: in-process adapter for tests/demos (no runtime dependencies).
+- LangGraphAdapter: optional adapter for LangGraph workflows (requires langgraph).
+"""
+
+from .base import RuntimeAdapter
+from .generic import GenericAdapter
+from .exceptions import AdapterError, AdapterNotAttachedError, AdapterControlError
+
+# LangGraphAdapter is optional; langgraph may not be installed.
+try:
+    from .langgraph import LangGraphAdapter
+except Exception:  # pragma: no cover
+    LangGraphAdapter = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "RuntimeAdapter",
+    "GenericAdapter",
+    "LangGraphAdapter",
+    "AdapterError",
+    "AdapterNotAttachedError",
+    "AdapterControlError",
+]

polytrax-0.1.0/polytrax/src/polytrax/adapters/base.py

@@ -0,0 +1,54 @@
+# polytrax/src/polytrax/adapters/base.py
+"""
+RuntimeAdapter contract.
+
+Adapters translate runtime-specific signals (messages, tool calls, state changes)
+into USL events emitted via polytrax.instrumentation.Instrumentor.
+
+This module intentionally contains no runtime-specific imports.
+"""
+
+from __future__ import annotations
+
+import abc
+from typing import Any
+
+from polytrax.instrumentation import EventBuilder, Instrumentor
+
+
+class RuntimeAdapter(abc.ABC):
+    """
+    Abstract base class for runtime adapters.
+
+    Concrete adapters should:
+    - attach/detach to a runtime lifecycle
+    - optionally support controls (halt run, gate a message edge)
+    - emit USL events via the provided Instrumentor
+    """
+
+    def __init__(self, instrumentor: Instrumentor) -> None:
+        self._instrumentor = instrumentor
+
+    @abc.abstractmethod
+    def attach(self) -> None:
+        """Attach adapter to runtime lifecycle (or mark as attached)."""
+
+    @abc.abstractmethod
+    def detach(self) -> None:
+        """Detach adapter from runtime lifecycle (or mark as detached)."""
+
+    @abc.abstractmethod
+    def halt_run(self, reason: str) -> None:
+        """Request that the runtime halts the current run for the given reason."""
+
+    @abc.abstractmethod
+    def gate_message(self, sender: str, receiver: str, *, reason: str) -> None:
+        """Request that messages from sender->receiver are gated/blocked with the given reason."""
+
+    def emit_event(self, event: dict) -> None:
+        """Emit an already-built USL event dict."""
+        self._instrumentor.emit(event)
+
+    def emit_built(self, builder: EventBuilder, **kwargs: Any) -> dict:
+        """Build via EventBuilder, emit, and return the built event."""
+        return self._instrumentor.emit_built(builder, **kwargs)

polytrax-0.1.0/polytrax/src/polytrax/adapters/exceptions.py

@@ -0,0 +1,19 @@
+# polytrax/src/polytrax/adapters/exceptions.py
+"""
+Adapter exceptions.
+
+Adapters are runtime integration layers. These exceptions provide a small,
+stable surface for control/attachment errors without depending on any runtime.
+"""
+
+
+class AdapterError(Exception):
+    """Base class for all adapter-related errors."""
+
+
+class AdapterNotAttachedError(AdapterError):
+    """Raised when an adapter operation requires attach() but the adapter is not attached."""
+
+
+class AdapterControlError(AdapterError):
+    """Raised when an adapter cannot complete a requested control action (halt/gate/etc.)."""

polytrax-0.1.0/polytrax/src/polytrax/adapters/generic.py

@@ -0,0 +1,228 @@
+# polytrax/src/polytrax/adapters/generic.py
+"""
+GenericAdapter: lightweight in-process adapter for demos/tests.
+
+This simulates a multi-agent "run" deterministically without any external runtime.
+Useful for validating end-to-end plumbing:
+USL builder/validator -> Instrumentor -> sinks.
+
+Supported architectures:
+- pipeline: A->B->C->... (wrap around)
+- peer: round-robin edges among agents (every ordered pair excluding self)
+- supervisor: Supervisor<->AgentX alternating
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List, Optional, Set, Tuple
+
+from polytrax.instrumentation import EventBuilder, Instrumentor
+
+from .base import RuntimeAdapter
+from .exceptions import AdapterNotAttachedError, AdapterControlError
+
+
+class GenericAdapter(RuntimeAdapter):
+    """
+    In-process adapter that emits USL events for a simulated multi-agent run.
+
+    Notes:
+    - Deterministic: same (agents, architecture, steps) -> same event sequence.
+    - Trust is optional and never required; you may include it via payload_factory if desired.
+    """
+
+    def __init__(
+        self,
+        instrumentor: Instrumentor,
+        *,
+        run_id: str,
+        agents: Optional[List[str]] = None,
+        architecture: str = "pipeline",  # "pipeline", "peer", "supervisor"
+    ) -> None:
+        super().__init__(instrumentor)
+        self._run_id = run_id
+        self._architecture = architecture
+
+        # Default agent set if none provided.
+        self._agents: List[str] = list(agents) if agents is not None else ["A", "B", "C"]
+
+        if not self._agents:
+            raise ValueError("agents must contain at least one agent name")
+
+        if self._architecture not in {"pipeline", "peer", "supervisor"}:
+            raise ValueError('architecture must be one of: "pipeline", "peer", "supervisor"')
+
+        # Ensure Supervisor exists for supervisor architecture.
+        if self._architecture == "supervisor" and "Supervisor" not in self._agents:
+            self._agents = ["Supervisor"] + self._agents
+
+        # Provide defaults so non-message lifecycle events can emit without sender/receiver.
+        self._builder = EventBuilder(
+            run_id=self._run_id,
+            default_sender="polytrax",
+            default_receiver="polytrax",
+        )
+
+        self._attached: bool = False
+        self._halted: bool = False
+        self._gated_edges: Set[Tuple[str, str]] = set()
+
+    def attach(self) -> None:
+        self._attached = True
+        self.emit_built(
+            self._builder,
+            event_type="adapter_attached",
+            payload={
+                "adapter": "generic",
+                "architecture": self._architecture,
+                "agents": list(self._agents),
+            },
+        )
+
+    def detach(self) -> None:
+        # Detach is allowed even if already detached; keep deterministic and simple.
+        self._attached = False
+        self.emit_built(
+            self._builder,
+            event_type="adapter_detached",
+            payload={"adapter": "generic"},
+        )
+
+    def gate_message(self, sender: str, receiver: str, *, reason: str) -> None:
+        if not self._attached:
+            raise AdapterNotAttachedError("gate_message requires adapter to be attached")
+        self._gated_edges.add((sender, receiver))
+        self.emit_built(
+            self._builder,
+            sender=sender,
+            receiver=receiver,
+            event_type="gate_applied",
+            payload={"sender": sender, "receiver": receiver, "reason": reason},
+        )
+
+    def halt_run(self, reason: str) -> None:
+        if not self._attached:
+            raise AdapterNotAttachedError("halt_run requires adapter to be attached")
+        self._halted = True
+        self.emit_built(
+            self._builder,
+            event_type="run_halted",
+            payload={"reason": reason},
+        )
+
+    def run(
+        self,
+        *,
+        steps: int = 5,
+        payload_factory: Optional[Callable[[int, str, str], Dict]] = None,
+    ) -> None:
+        """
+        Simulate a run and emit message events.
+
+        For each step i:
+        - choose (sender, receiver) based on architecture
+        - if the edge is gated: emit message_blocked (and do not emit message_sent)
+        - else emit message_sent
+
+        payload_factory (optional):
+          Callable(step_i, sender, receiver) -> dict payload
+          Trust is not required; if you want, you can return {"trust": {...}, ...}
+          and it will be included in payload only. USL trust field is not touched by default.
+        """
+        if not self._attached:
+            raise AdapterNotAttachedError("run requires adapter to be attached")
+        if self._halted:
+            raise AdapterControlError("run cannot start: adapter is halted")
+        if steps < 0:
+            raise ValueError("steps must be >= 0")
+
+        # Precompute deterministic edge sequences for each architecture.
+        if self._architecture == "pipeline":
+            edges = self._pipeline_edges()
+        elif self._architecture == "peer":
+            edges = self._peer_edges()
+        else:  # supervisor
+            edges = self._supervisor_edges()
+
+        if not edges:
+            # Should not happen, but keep behavior explicit.
+            raise AdapterControlError("no valid edges available to simulate run")
+
+        for i in range(steps):
+            if self._halted:
+                break
+
+            sender, receiver = edges[i % len(edges)]
+
+            # Default payload (deterministic)
+            if payload_factory is None:
+                payload: Dict = {
+                    "step": i,
+                    "content": f"msg-{i} {sender}->{receiver}",
+                    "meta": {
+                        "architecture": self._architecture,
+                    },
+                }
+            else:
+                payload = payload_factory(i, sender, receiver)
+                if not isinstance(payload, dict):
+                    raise TypeError("payload_factory must return a dict")
+
+            if (sender, receiver) in self._gated_edges:
+                self.emit_built(
+                    self._builder,
+                    sender=sender,
+                    receiver=receiver,
+                    event_type="message_blocked",
+                    payload={
+                        "step": i,
+                        "sender": sender,
+                        "receiver": receiver,
+                        "reason": "gated_edge",
+                        "intended": payload,
+                    },
+                )
+                continue
+
+            self.emit_built(
+                self._builder,
+                sender=sender,
+                receiver=receiver,
+                event_type="message_sent",
+                payload=payload,
+            )
+
+    def _pipeline_edges(self) -> List[Tuple[str, str]]:
+        # A->B->C->... wrap
+        agents = list(self._agents)
+        if len(agents) == 1:
+            # Self-loop only.
+            return [(agents[0], agents[0])]
+        edges: List[Tuple[str, str]] = []
+        for idx, a in enumerate(agents):
+            b = agents[(idx + 1) % len(agents)]
+            edges.append((a, b))
+        return edges
+
+    def _peer_edges(self) -> List[Tuple[str, str]]:
+        # Deterministic ordered pairs, excluding self.
+        agents = list(self._agents)
+        edges: List[Tuple[str, str]] = []
+        for s in agents:
+            for r in agents:
+                if s != r:
+                    edges.append((s, r))
+        return edges
+
+    def _supervisor_edges(self) -> List[Tuple[str, str]]:
+        # Supervisor<->AgentX alternating: Sup->A0, A0->Sup, Sup->A1, A1->Sup, ...
+        agents = [a for a in self._agents if a != "Supervisor"]
+        if not agents:
+            # Only Supervisor exists -> self-loop.
+            return [("Supervisor", "Supervisor")]
+
+        edges: List[Tuple[str, str]] = []
+        for a in agents:
+            edges.append(("Supervisor", a))
+            edges.append((a, "Supervisor"))
+        return edges