agent-coherence 0.1.0__tar.gz

agent_coherence-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: agent-coherence
+Version: 0.1.0
+Summary: MESI-style artifact coherence for multi-agent AI systems
+Author: Arbiter contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hipvlady/agent-coherence
+Project-URL: Repository, https://github.com/hipvlady/agent-coherence
+Project-URL: Issues, https://github.com/hipvlady/agent-coherence/issues
+Keywords: multi-agent,llm,cache-coherence,mesi,token-efficiency,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# agent-coherence — The Coherence Protocol for AI Agents
+
+[![CI](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml/badge.svg)](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml)
+
+`agent-coherence` implements MESI-style cache coherence for shared artifacts in multi-agent LLM systems, reducing synchronization token overhead and preventing stale-context coordination failures.
+
+## Install
+
+```bash
+pip install agent-coherence
+```
+
+## Quick start
+
+```python
+from ccs.simulation.engine import run_strategy_comparison
+from ccs.simulation.scenarios import load_scenario
+
+scenario = load_scenario("benchmarks/scenarios/planning_canonical.yaml")
+report = run_strategy_comparison(scenario, strategies=["eager", "lazy"], runs=5, seed_start=20260305)
+print(report.to_dict()["aggregated"])
+```
+
+## Reproduce benchmark artifacts
+
+```bash
+bash reproduce.sh
+```
+
+See [REPRODUCE.md](REPRODUCE.md) for full output mapping and baseline verification details.
+
+## Paper
+
+Token Coherence: MESI-Style Cache Coherence for Shared Artifacts in Multi-Agent LLM Systems
+
+## License
+
+Apache-2.0 (`LICENSE`)

agent_coherence-0.1.0/README.md

@@ -0,0 +1,38 @@
+# agent-coherence — The Coherence Protocol for AI Agents
+
+[![CI](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml/badge.svg)](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml)
+
+`agent-coherence` implements MESI-style cache coherence for shared artifacts in multi-agent LLM systems, reducing synchronization token overhead and preventing stale-context coordination failures.
+
+## Install
+
+```bash
+pip install agent-coherence
+```
+
+## Quick start
+
+```python
+from ccs.simulation.engine import run_strategy_comparison
+from ccs.simulation.scenarios import load_scenario
+
+scenario = load_scenario("benchmarks/scenarios/planning_canonical.yaml")
+report = run_strategy_comparison(scenario, strategies=["eager", "lazy"], runs=5, seed_start=20260305)
+print(report.to_dict()["aggregated"])
+```
+
+## Reproduce benchmark artifacts
+
+```bash
+bash reproduce.sh
+```
+
+See [REPRODUCE.md](REPRODUCE.md) for full output mapping and baseline verification details.
+
+## Paper
+
+Token Coherence: MESI-Style Cache Coherence for Shared Artifacts in Multi-Agent LLM Systems
+
+## License
+
+Apache-2.0 (`LICENSE`)

agent_coherence-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-coherence"
+version = "0.1.0"
+description = "MESI-style artifact coherence for multi-agent AI systems"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Arbiter contributors" }]
+keywords = ["multi-agent", "llm", "cache-coherence", "mesi", "token-efficiency", "agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+]
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0"]
+
+[project.scripts]
+ccs-simulate = "ccs.cli.simulate:main"
+ccs-compare = "ccs.cli.compare:main"
+ccs-check-architecture = "ccs.hardening.architecture:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+license-files = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/hipvlady/agent-coherence"
+Repository = "https://github.com/hipvlady/agent-coherence"
+Issues = "https://github.com/hipvlady/agent-coherence/issues"

agent_coherence-0.1.0/setup.cfg

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

agent_coherence-0.1.0/src/agent_coherence.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: agent-coherence
+Version: 0.1.0
+Summary: MESI-style artifact coherence for multi-agent AI systems
+Author: Arbiter contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hipvlady/agent-coherence
+Project-URL: Repository, https://github.com/hipvlady/agent-coherence
+Project-URL: Issues, https://github.com/hipvlady/agent-coherence/issues
+Keywords: multi-agent,llm,cache-coherence,mesi,token-efficiency,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# agent-coherence — The Coherence Protocol for AI Agents
+
+[![CI](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml/badge.svg)](https://github.com/hipvlady/agent-coherence/actions/workflows/ci.yml)
+
+`agent-coherence` implements MESI-style cache coherence for shared artifacts in multi-agent LLM systems, reducing synchronization token overhead and preventing stale-context coordination failures.
+
+## Install
+
+```bash
+pip install agent-coherence
+```
+
+## Quick start
+
+```python
+from ccs.simulation.engine import run_strategy_comparison
+from ccs.simulation.scenarios import load_scenario
+
+scenario = load_scenario("benchmarks/scenarios/planning_canonical.yaml")
+report = run_strategy_comparison(scenario, strategies=["eager", "lazy"], runs=5, seed_start=20260305)
+print(report.to_dict()["aggregated"])
+```
+
+## Reproduce benchmark artifacts
+
+```bash
+bash reproduce.sh
+```
+
+See [REPRODUCE.md](REPRODUCE.md) for full output mapping and baseline verification details.
+
+## Paper
+
+Token Coherence: MESI-Style Cache Coherence for Shared Artifacts in Multi-Agent LLM Systems
+
+## License
+
+Apache-2.0 (`LICENSE`)

agent_coherence-0.1.0/src/agent_coherence.egg-info/SOURCES.txt

@@ -0,0 +1,80 @@
+README.md
+pyproject.toml
+src/agent_coherence.egg-info/PKG-INFO
+src/agent_coherence.egg-info/SOURCES.txt
+src/agent_coherence.egg-info/dependency_links.txt
+src/agent_coherence.egg-info/entry_points.txt
+src/agent_coherence.egg-info/requires.txt
+src/agent_coherence.egg-info/top_level.txt
+src/ccs/__init__.py
+src/ccs/adapters/__init__.py
+src/ccs/adapters/autogen.py
+src/ccs/adapters/base.py
+src/ccs/adapters/crewai.py
+src/ccs/adapters/langgraph.py
+src/ccs/agent/__init__.py
+src/ccs/agent/cache.py
+src/ccs/agent/runtime.py
+src/ccs/artifacts/__init__.py
+src/ccs/artifacts/diff_engine.py
+src/ccs/bus/__init__.py
+src/ccs/bus/event_bus.py
+src/ccs/cli/__init__.py
+src/ccs/cli/compare.py
+src/ccs/cli/simulate.py
+src/ccs/coordinator/__init__.py
+src/ccs/coordinator/registry.py
+src/ccs/coordinator/service.py
+src/ccs/core/__init__.py
+src/ccs/core/clock.py
+src/ccs/core/exceptions.py
+src/ccs/core/granularity.py
+src/ccs/core/invariants.py
+src/ccs/core/states.py
+src/ccs/core/types.py
+src/ccs/hardening/__init__.py
+src/ccs/hardening/architecture.py
+src/ccs/output/__init__.py
+src/ccs/output/report.py
+src/ccs/simulation/__init__.py
+src/ccs/simulation/aggregation.py
+src/ccs/simulation/bounds.py
+src/ccs/simulation/consistency.py
+src/ccs/simulation/engine.py
+src/ccs/simulation/metrics.py
+src/ccs/simulation/scenarios.py
+src/ccs/strategies/__init__.py
+src/ccs/strategies/access_count.py
+src/ccs/strategies/base.py
+src/ccs/strategies/broadcast.py
+src/ccs/strategies/eager.py
+src/ccs/strategies/lazy.py
+src/ccs/strategies/lease.py
+src/ccs/strategies/selector.py
+src/ccs/transport/__init__.py
+src/ccs/transport/network_sim.py
+tests/test_adapters.py
+tests/test_agent_cache.py
+tests/test_agent_runtime.py
+tests/test_aggregation.py
+tests/test_architecture.py
+tests/test_benchmark_fixtures.py
+tests/test_bounds.py
+tests/test_cli.py
+tests/test_clock.py
+tests/test_consistency.py
+tests/test_coordinator.py
+tests/test_demo_script.py
+tests/test_diff_engine.py
+tests/test_engine.py
+tests/test_event_bus.py
+tests/test_granularity.py
+tests/test_invariants.py
+tests/test_network_sim.py
+tests/test_property_invariants.py
+tests/test_report.py
+tests/test_scenarios.py
+tests/test_states.py
+tests/test_strategies.py
+tests/test_transient_timeout.py
+tests/test_types.py

agent_coherence-0.1.0/src/agent_coherence.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_coherence-0.1.0/src/agent_coherence.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+ccs-check-architecture = ccs.hardening.architecture:main
+ccs-compare = ccs.cli.compare:main
+ccs-simulate = ccs.cli.simulate:main

agent_coherence-0.1.0/src/agent_coherence.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyyaml>=6.0
+
+[dev]
+pytest>=7.0

agent_coherence-0.1.0/src/agent_coherence.egg-info/top_level.txt

@@ -0,0 +1 @@
+ccs

agent_coherence-0.1.0/src/ccs/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""agent-coherence core package."""
+
+__version__ = "0.1.0"

agent_coherence-0.1.0/src/ccs/adapters/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""Framework-facing integration adapters for CCS runtime."""
+
+from .autogen import AutoGenAdapter
+from .base import CoherenceAdapterCore
+from .crewai import CrewAIAdapter
+from .langgraph import LangGraphAdapter
+
+__all__ = [
+    "CoherenceAdapterCore",
+    "LangGraphAdapter",
+    "CrewAIAdapter",
+    "AutoGenAdapter",
+]

agent_coherence-0.1.0/src/ccs/adapters/autogen.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""AutoGen-oriented coherence adapter utilities."""
+
+from __future__ import annotations
+
+from typing import Mapping
+from uuid import UUID
+
+from ccs.core.types import Artifact
+
+from .base import CoherenceAdapterCore
+
+
+class AutoGenAdapter:
+    """Adapter exposing per-turn hooks for AutoGen-like conversations."""
+
+    def __init__(self, *, strategy_name: str = "lazy", core: CoherenceAdapterCore | None = None) -> None:
+        self.core = core if core is not None else CoherenceAdapterCore(strategy_name=strategy_name)
+
+    def register_agent(self, name: str) -> UUID:
+        """Register one conversational agent identity."""
+        return self.core.register_agent(name)
+
+    def register_artifact(self, *, name: str, content: str, size_tokens: int | None = None) -> Artifact:
+        """Register shared artifact for conversation context."""
+        return self.core.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def pre_turn_context(
+        self,
+        *,
+        agent_name: str,
+        artifact_ids: list[UUID],
+        now_tick: int,
+    ) -> dict[UUID, str]:
+        """Fetch current context before an agent turn."""
+        return {
+            artifact_id: self.core.read(agent_name=agent_name, artifact_id=artifact_id, now_tick=now_tick).content
+            for artifact_id in artifact_ids
+        }
+
+    def post_turn_commit(
+        self,
+        *,
+        agent_name: str,
+        updates: Mapping[UUID, str],
+        now_tick: int,
+    ) -> dict[UUID, int]:
+        """Commit turn updates and return updated versions."""
+        versions: dict[UUID, int] = {}
+        for artifact_id, content in updates.items():
+            artifact = self.core.write(
+                agent_name=agent_name,
+                artifact_id=artifact_id,
+                content=content,
+                now_tick=now_tick,
+            )
+            versions[artifact_id] = artifact.version
+        return versions

agent_coherence-0.1.0/src/ccs/adapters/base.py

@@ -0,0 +1,136 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""Common adapter runtime that wires coordinator, agents, and event bus."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import NAMESPACE_URL, UUID, uuid5
+
+from ccs.agent.runtime import AgentRuntime
+from ccs.bus.event_bus import ArtifactUpdateEvent, InMemoryEventBus
+from ccs.coordinator.registry import ArtifactRegistry
+from ccs.coordinator.service import CoordinatorService
+from ccs.core.types import Artifact, FetchResponse
+from ccs.strategies.base import SyncStrategy
+from ccs.strategies.selector import build_strategy
+
+
+@dataclass(frozen=True)
+class AgentBinding:
+    """Resolved identity/runtime tuple for an adapter-managed agent."""
+
+    name: str
+    agent_id: UUID
+    runtime: AgentRuntime
+
+
+class CoherenceAdapterCore:
+    """Reusable cluster abstraction for framework adapters."""
+
+    def __init__(
+        self,
+        *,
+        strategy_name: str = "lazy",
+        lease_ttl_ticks: int = 300,
+        access_count_max_accesses: int = 100,
+        event_bus: InMemoryEventBus | None = None,
+    ) -> None:
+        self.registry = ArtifactRegistry()
+        self.coordinator = CoordinatorService(self.registry)
+        self.strategy: SyncStrategy = build_strategy(
+            strategy_name,
+            lease_ttl_ticks=lease_ttl_ticks,
+            access_count_max_accesses=access_count_max_accesses,
+        )
+        self.event_bus = event_bus if event_bus is not None else InMemoryEventBus()
+        self._agents_by_name: dict[str, AgentBinding] = {}
+
+    def register_agent(self, name: str) -> UUID:
+        """Register one agent runtime and subscribe it to bus events."""
+        existing = self._agents_by_name.get(name)
+        if existing is not None:
+            return existing.agent_id
+
+        agent_id = uuid5(NAMESPACE_URL, f"ccs-agent:{name}")
+        runtime = AgentRuntime(agent_id=agent_id, coordinator=self.coordinator, strategy=self.strategy)
+        self.event_bus.subscribe(
+            agent_id=agent_id,
+            on_invalidation=runtime.handle_invalidation,
+            on_update=lambda event, runtime=runtime: runtime.handle_update(
+                artifact_id=event.artifact_id,
+                version=event.version,
+                content=event.content,
+                now_tick=event.issued_at_tick,
+                writer_agent_id=event.issuer_agent_id,
+            ),
+        )
+        self._agents_by_name[name] = AgentBinding(name=name, agent_id=agent_id, runtime=runtime)
+        return agent_id
+
+    def register_artifact(
+        self,
+        *,
+        name: str,
+        content: str,
+        size_tokens: int | None = None,
+    ) -> Artifact:
+        """Register a shared artifact in the coordinator directory."""
+        return self.coordinator.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def read(self, *, agent_name: str, artifact_id: UUID, now_tick: int) -> FetchResponse:
+        """Read artifact through one registered runtime."""
+        return self._binding(agent_name).runtime.read(artifact_id, now_tick=now_tick)
+
+    def write(
+        self,
+        *,
+        agent_name: str,
+        artifact_id: UUID,
+        content: str,
+        now_tick: int,
+    ) -> Artifact:
+        """Write artifact through one runtime and dispatch peer events."""
+        writer = self._binding(agent_name)
+        updated, invalidation_signals = writer.runtime.write(
+            artifact_id=artifact_id,
+            content=content,
+            now_tick=now_tick,
+        )
+        peers = [binding.agent_id for binding in self._agents_by_name.values() if binding.agent_id != writer.agent_id]
+
+        for signal in invalidation_signals:
+            self.event_bus.publish_invalidation(signal, recipients=peers)
+
+        if self.strategy.broadcasts_content_on_commit():
+            self.event_bus.publish_update(
+                ArtifactUpdateEvent(
+                    artifact_id=artifact_id,
+                    version=updated.version,
+                    content=content,
+                    issued_at_tick=now_tick,
+                    issuer_agent_id=writer.agent_id,
+                ),
+                recipients=peers,
+            )
+
+        return updated
+
+    def content(self, *, agent_name: str, artifact_id: UUID) -> str | None:
+        """Return local content cached by one agent runtime."""
+        return self._binding(agent_name).runtime.content(artifact_id)
+
+    def runtime(self, agent_name: str) -> AgentRuntime:
+        """Return concrete runtime for adapter extensions/testing."""
+        return self._binding(agent_name).runtime
+
+    def agent_names(self) -> list[str]:
+        """Return registered adapter agent names."""
+        return sorted(self._agents_by_name.keys())
+
+    def _binding(self, agent_name: str) -> AgentBinding:
+        binding = self._agents_by_name.get(agent_name)
+        if binding is None:
+            raise KeyError(f"unknown_agent '{agent_name}'")
+        return binding

agent_coherence-0.1.0/src/ccs/adapters/crewai.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""CrewAI-oriented coherence adapter utilities."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from ccs.core.types import Artifact
+
+from .base import CoherenceAdapterCore
+
+
+class CrewAIAdapter:
+    """Adapter exposing task lifecycle helpers for CrewAI-style flows."""
+
+    def __init__(self, *, strategy_name: str = "lazy", core: CoherenceAdapterCore | None = None) -> None:
+        self.core = core if core is not None else CoherenceAdapterCore(strategy_name=strategy_name)
+
+    def register_agent(self, name: str) -> UUID:
+        """Register one crew member identity."""
+        return self.core.register_agent(name)
+
+    def register_artifact(self, *, name: str, content: str, size_tokens: int | None = None) -> Artifact:
+        """Register shared artifact accessible to the crew."""
+        return self.core.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def prepare_task_context(
+        self,
+        *,
+        agent_name: str,
+        artifact_ids: list[UUID],
+        now_tick: int,
+    ) -> dict[UUID, str]:
+        """Materialize artifact content for one task execution."""
+        content_by_artifact: dict[UUID, str] = {}
+        for artifact_id in artifact_ids:
+            response = self.core.read(agent_name=agent_name, artifact_id=artifact_id, now_tick=now_tick)
+            content_by_artifact[artifact_id] = response.content
+        return content_by_artifact
+
+    def commit_task_artifact(
+        self,
+        *,
+        agent_name: str,
+        artifact_id: UUID,
+        content: str,
+        now_tick: int,
+    ) -> int:
+        """Commit task output for one artifact and return resulting version."""
+        artifact = self.core.write(
+            agent_name=agent_name,
+            artifact_id=artifact_id,
+            content=content,
+            now_tick=now_tick,
+        )
+        return artifact.version

agent_coherence-0.1.0/src/ccs/adapters/langgraph.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""LangGraph-oriented coherence adapter utilities."""
+
+from __future__ import annotations
+
+from typing import Mapping
+from uuid import UUID
+
+from ccs.core.types import Artifact
+
+from .base import CoherenceAdapterCore
+
+
+class LangGraphAdapter:
+    """Adapter exposing pre/post node hooks backed by CCS runtime."""
+
+    def __init__(self, *, strategy_name: str = "lazy", core: CoherenceAdapterCore | None = None) -> None:
+        self.core = core if core is not None else CoherenceAdapterCore(strategy_name=strategy_name)
+
+    def register_agent(self, name: str) -> UUID:
+        """Register node runtime identity."""
+        return self.core.register_agent(name)
+
+    def register_artifact(self, *, name: str, content: str, size_tokens: int | None = None) -> Artifact:
+        """Register shared artifact used by LangGraph nodes."""
+        return self.core.register_artifact(name=name, content=content, size_tokens=size_tokens)
+
+    def before_node(
+        self,
+        *,
+        agent_name: str,
+        artifact_ids: list[UUID],
+        now_tick: int,
+    ) -> dict[UUID, dict[str, object]]:
+        """Read artifacts before node execution and return context payload."""
+        context: dict[UUID, dict[str, object]] = {}
+        for artifact_id in artifact_ids:
+            response = self.core.read(agent_name=agent_name, artifact_id=artifact_id, now_tick=now_tick)
+            context[artifact_id] = {
+                "version": response.version,
+                "content": response.content,
+                "state": response.state_grant.value,
+            }
+        return context
+
+    def commit_outputs(
+        self,
+        *,
+        agent_name: str,
+        writes: Mapping[UUID, str],
+        now_tick: int,
+    ) -> dict[UUID, int]:
+        """Commit node outputs and return artifact versions."""
+        versions: dict[UUID, int] = {}
+        for artifact_id, content in writes.items():
+            artifact = self.core.write(
+                agent_name=agent_name,
+                artifact_id=artifact_id,
+                content=content,
+                now_tick=now_tick,
+            )
+            versions[artifact_id] = artifact.version
+        return versions

agent_coherence-0.1.0/src/ccs/agent/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2026 Arbiter contributors.
+# The Coherence Protocol for AI Agents
+
+"""Agent-side cache and runtime components."""
+
+from .cache import ArtifactCache
+from .runtime import AgentRuntime
+
+__all__ = ["ArtifactCache", "AgentRuntime"]