crewcontext 0.1.0__tar.gz

crewcontext-0.1.0/LICENSE

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

crewcontext-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: crewcontext
+Version: 0.1.0
+Summary: Auditable shared memory for AI agent systems
+License: MIT
+Project-URL: Homepage, https://github.com/crewcontext/crewcontext
+Project-URL: Documentation, https://github.com/crewcontext/crewcontext/tree/main/docs
+Project-URL: Repository, https://github.com/crewcontext/crewcontext
+Project-URL: Changelog, https://github.com/crewcontext/crewcontext/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/crewcontext/crewcontext/issues
+Keywords: agents,multi-agent,context,event-sourcing,audit,orchestration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: psycopg_pool>=3.1
+Requires-Dist: neo4j>=5.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img width="128" height="128" alt="crewcontext_logo_128" src="https://github.com/user-attachments/assets/db17d668-adca-401d-ab4e-901c05f60af4" />
+</p>
+<p align="center">
+  <h1 align="center">CrewContext</h1>
+  <p align="center"><strong>Auditable shared memory for AI agent systems.</strong></p>
+</p>
+
+
+## The Problem
+
+Multi-agent AI systems break at handoffs. Agent 1 processes an invoice. Agent 2 validates it. Agent 3 reconciles discrepancies. But Agent 3 has no idea what Agent 1 found. Context is lost. Decisions are invisible. Nothing is auditable.
+
+Existing agent frameworks give you orchestration — **but not memory**. Chat history is personal. RAG is read-only. Neither gives you a shared, structured, temporal record of what happened, who did it, and why.
+
+In regulated industries — finance, insurance, compliance — this isn't just inconvenient. It's a liability.
+
+## What CrewContext Does
+
+CrewContext is a **context coordination layer** that sits underneath your agent framework and provides:
+
+- **Shared event store** — Every agent action is recorded. Nothing is lost at handoffs.
+- **Causal DAG** — Every event tracks what caused it. You can answer "why did this happen?" by walking the chain backwards.
+- **Temporal queries** — Reconstruct the exact state of any entity at any point in time. "What did we know at 2pm yesterday?"
+- **Versioned entities** — Business objects (invoices, customers, claims) are snapshotted at each stage, never overwritten.
+- **Policy router** — Deterministic, auditable routing rules with composable conditions. No black boxes.
+- **Provenance tracking** — Every event records which agent, what scope, and when. Built for auditors.
+
+## Architecture
+
+```
+                    ┌──────────────────────────────────┐
+                    │        ProcessContext API        │
+                    │  emit · query · timeline · causal│
+                    └──────────┬───────────────────────┘
+                               │
+              ┌────────────────┼────────────────┐
+              │                │                │
+    ┌─────────▼──────┐   ┌─────▼──────┐  ┌──────▼──────┐
+    │  PostgreSQL    │   │   Neo4j    │  │   Policy    │
+    │  Event Store   │   │   Graph    │  │   Router    │
+    │                │   │            │  │             │
+    │  Append-only   │   │  Lineage   │  │  Rules      │
+    │  Temporal      │   │  Causal    │  │  Pub/Sub    │
+    │  Causal links  │   │  DAG       │  │  Routing    │
+    │  Versioned     │   │  Typed     │  │  decisions  │
+    │  entities      │   │  relations │  │             │
+    └────────────────┘   └────────────┘  └─────────────┘
+         (truth)          (optional)      (in-process)
+```
+
+**PostgreSQL** is the source of truth — append-only event log, versioned entity snapshots, causal link table. **Neo4j** is an optional projection for graph queries and lineage visualization. **Policy Router** evaluates events against composable rules in-process.
+
+## Who It's For
+
+CrewContext is for teams building multi-agent systems where **trust, auditability, and context preservation** matter:
+
+- **Financial operations** — Payment processing, reconciliation, dispute resolution
+- **KYC/AML compliance** — Auditable decision trails for regulators
+- **Insurance claims** — Multi-stage pipelines where context loss means money lost
+- **Supply chain** — Order-to-delivery orchestration across multiple agents
+- **Any regulated workflow** where "the AI decided" isn't a good enough answer
+
+## Framework-Agnostic
+
+CrewContext is not a replacement for your agent framework. It's the **memory layer underneath it**. It works with:
+
+- [CrewAI](https://github.com/joaomdmoura/crewAI)
+- [LangGraph](https://github.com/langchain-ai/langgraph)
+- [AutoGen](https://github.com/microsoft/autogen)
+- [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)
+- Custom agent systems
+
+## Getting Started
+
+```bash
+pip install crewcontext
+docker compose up -d
+crewcontext init-db
+crewcontext demo vendor-discrepancy
+```
+
+Full API documentation and examples are available in the [docs](docs/) directory.
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `CREWCONTEXT_DB_URL` | `postgresql://crew:crew@localhost:5432/crewcontext` | PostgreSQL connection |
+| `CREWCONTEXT_NEO4J_URI` | `bolt://localhost:7687` | Neo4j Bolt endpoint |
+| `CREWCONTEXT_NEO4J_USER` | `neo4j` | Neo4j username |
+| `CREWCONTEXT_NEO4J_PASSWORD` | `crewcontext123` | Neo4j password |
+
+Neo4j is optional. Pass `enable_neo4j=False` for Postgres-only mode.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+[MIT](LICENSE)

crewcontext-0.1.0/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img width="128" height="128" alt="crewcontext_logo_128" src="https://github.com/user-attachments/assets/db17d668-adca-401d-ab4e-901c05f60af4" />
+</p>
+<p align="center">
+  <h1 align="center">CrewContext</h1>
+  <p align="center"><strong>Auditable shared memory for AI agent systems.</strong></p>
+</p>
+
+
+## The Problem
+
+Multi-agent AI systems break at handoffs. Agent 1 processes an invoice. Agent 2 validates it. Agent 3 reconciles discrepancies. But Agent 3 has no idea what Agent 1 found. Context is lost. Decisions are invisible. Nothing is auditable.
+
+Existing agent frameworks give you orchestration — **but not memory**. Chat history is personal. RAG is read-only. Neither gives you a shared, structured, temporal record of what happened, who did it, and why.
+
+In regulated industries — finance, insurance, compliance — this isn't just inconvenient. It's a liability.
+
+## What CrewContext Does
+
+CrewContext is a **context coordination layer** that sits underneath your agent framework and provides:
+
+- **Shared event store** — Every agent action is recorded. Nothing is lost at handoffs.
+- **Causal DAG** — Every event tracks what caused it. You can answer "why did this happen?" by walking the chain backwards.
+- **Temporal queries** — Reconstruct the exact state of any entity at any point in time. "What did we know at 2pm yesterday?"
+- **Versioned entities** — Business objects (invoices, customers, claims) are snapshotted at each stage, never overwritten.
+- **Policy router** — Deterministic, auditable routing rules with composable conditions. No black boxes.
+- **Provenance tracking** — Every event records which agent, what scope, and when. Built for auditors.
+
+## Architecture
+
+```
+                    ┌──────────────────────────────────┐
+                    │        ProcessContext API        │
+                    │  emit · query · timeline · causal│
+                    └──────────┬───────────────────────┘
+                               │
+              ┌────────────────┼────────────────┐
+              │                │                │
+    ┌─────────▼──────┐   ┌─────▼──────┐  ┌──────▼──────┐
+    │  PostgreSQL    │   │   Neo4j    │  │   Policy    │
+    │  Event Store   │   │   Graph    │  │   Router    │
+    │                │   │            │  │             │
+    │  Append-only   │   │  Lineage   │  │  Rules      │
+    │  Temporal      │   │  Causal    │  │  Pub/Sub    │
+    │  Causal links  │   │  DAG       │  │  Routing    │
+    │  Versioned     │   │  Typed     │  │  decisions  │
+    │  entities      │   │  relations │  │             │
+    └────────────────┘   └────────────┘  └─────────────┘
+         (truth)          (optional)      (in-process)
+```
+
+**PostgreSQL** is the source of truth — append-only event log, versioned entity snapshots, causal link table. **Neo4j** is an optional projection for graph queries and lineage visualization. **Policy Router** evaluates events against composable rules in-process.
+
+## Who It's For
+
+CrewContext is for teams building multi-agent systems where **trust, auditability, and context preservation** matter:
+
+- **Financial operations** — Payment processing, reconciliation, dispute resolution
+- **KYC/AML compliance** — Auditable decision trails for regulators
+- **Insurance claims** — Multi-stage pipelines where context loss means money lost
+- **Supply chain** — Order-to-delivery orchestration across multiple agents
+- **Any regulated workflow** where "the AI decided" isn't a good enough answer
+
+## Framework-Agnostic
+
+CrewContext is not a replacement for your agent framework. It's the **memory layer underneath it**. It works with:
+
+- [CrewAI](https://github.com/joaomdmoura/crewAI)
+- [LangGraph](https://github.com/langchain-ai/langgraph)
+- [AutoGen](https://github.com/microsoft/autogen)
+- [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)
+- Custom agent systems
+
+## Getting Started
+
+```bash
+pip install crewcontext
+docker compose up -d
+crewcontext init-db
+crewcontext demo vendor-discrepancy
+```
+
+Full API documentation and examples are available in the [docs](docs/) directory.
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `CREWCONTEXT_DB_URL` | `postgresql://crew:crew@localhost:5432/crewcontext` | PostgreSQL connection |
+| `CREWCONTEXT_NEO4J_URI` | `bolt://localhost:7687` | Neo4j Bolt endpoint |
+| `CREWCONTEXT_NEO4J_USER` | `neo4j` | Neo4j username |
+| `CREWCONTEXT_NEO4J_PASSWORD` | `crewcontext123` | Neo4j password |
+
+Neo4j is optional. Pass `enable_neo4j=False` for Postgres-only mode.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+[MIT](LICENSE)

crewcontext-0.1.0/crewcontext/__init__.py

@@ -0,0 +1,40 @@
+"""CrewContext — Context coordination layer for multi-agent workflows.
+
+Usage:
+    from crewcontext import ProcessContext, Entity, Event, Relation
+
+    with ProcessContext(process_id="p1", agent_id="agent-1") as ctx:
+        event = ctx.emit("invoice.received", {"amount": 5000}, entity_id="inv-1")
+"""
+from .context import ProcessContext
+from .models import Entity, Event, Relation, RoutingDecision, generate_id
+from .router import (
+    PolicyRouter,
+    all_of,
+    any_of,
+    none_of,
+    data_field_eq,
+    data_field_gt,
+    data_field_ne,
+    data_fields_differ,
+    event_type_is,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "ProcessContext",
+    "Entity",
+    "Event",
+    "Relation",
+    "RoutingDecision",
+    "generate_id",
+    "PolicyRouter",
+    "all_of",
+    "any_of",
+    "none_of",
+    "data_field_eq",
+    "data_field_gt",
+    "data_field_ne",
+    "data_fields_differ",
+    "event_type_is",
+]

crewcontext-0.1.0/crewcontext/cli.py

@@ -0,0 +1,39 @@
+"""CLI for CrewContext."""
+import click
+from .utils import load_env
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def main():
+    """CrewContext - Context coordination for multi-agent workflows."""
+    load_env()
+
+
+@main.group()
+def demo():
+    """Run demo scenarios."""
+    pass
+
+
+@demo.command("vendor-discrepancy")
+def vendor_discrepancy():
+    """Run the vendor discrepancy demo."""
+    from .demos.vendor_discrepancy import run_demo
+    run_demo()
+
+
+@main.command("init-db")
+@click.option("--db-url", envvar="CREWCONTEXT_DB_URL", default=None)
+def init_db(db_url):
+    """Initialise the database schema."""
+    from .store.postgres import PostgresStore
+    store = PostgresStore(db_url)
+    store.connect()
+    store.init_schema()
+    store.close()
+    click.echo("Database schema initialised.")
+
+
+if __name__ == "__main__":
+    main()

crewcontext-0.1.0/crewcontext/context.py

@@ -0,0 +1,281 @@
+"""ProcessContext — the main API agents interact with.
+
+This is the public interface. Agents emit events, query history,
+build entity snapshots, and trace causal chains through this class.
+
+Usage:
+    with ProcessContext(process_id="proc-1", agent_id="agent-a") as ctx:
+        e1 = ctx.emit("invoice.received", {"amount": 5000}, entity_id="inv-1")
+        e2 = ctx.emit("invoice.validated", {"ok": True}, entity_id="inv-1", caused_by=[e1])
+        history = ctx.timeline("inv-1")
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, Sequence
+
+from .models import Entity, Event, Relation, RoutingDecision, generate_id
+from .projection.projector import Neo4jProjector
+from .router import PolicyRouter
+from .store.postgres import PostgresStore
+
+log = logging.getLogger(__name__)
+
+
+class ProcessContext:
+    """Scoped, temporal, causal context for a business process.
+
+    Features:
+    - **emit()**: Record events with optional causal parents.
+    - **query()**: Retrieve events with temporal/scope/type filtering.
+    - **timeline()**: Ordered event history for an entity.
+    - **snapshot()**: Save/retrieve versioned entity state.
+    - **causal_chain()**: Walk the causal DAG.
+    - **subscribe()**: React to event types in real-time.
+    - **batch_emit()**: Atomic multi-event writes.
+    """
+
+    def __init__(
+        self,
+        process_id: str,
+        agent_id: str,
+        scope: str = "default",
+        db_url: Optional[str] = None,
+        enable_neo4j: bool = True,
+    ):
+        self.process_id = process_id
+        self.agent_id = agent_id
+        self.scope = scope
+
+        self._store = PostgresStore(db_url)
+        self._projector = Neo4jProjector() if enable_neo4j else None
+        self._router = PolicyRouter()
+        self._connected = False
+
+    # -- context manager ----------------------------------------------------
+
+    def __enter__(self) -> ProcessContext:
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def connect(self) -> None:
+        self._store.connect()
+        self._store.init_schema()
+        self._connected = True
+        if self._projector:
+            self._projector.connect()  # best-effort, logs on failure
+        log.info(
+            "ProcessContext ready: process=%s agent=%s scope=%s",
+            self.process_id, self.agent_id, self.scope,
+        )
+
+    def close(self) -> None:
+        self._store.close()
+        if self._projector:
+            self._projector.close()
+        self._connected = False
+
+    # -- router access ------------------------------------------------------
+
+    @property
+    def router(self) -> PolicyRouter:
+        return self._router
+
+    # -- emit events --------------------------------------------------------
+
+    def emit(
+        self,
+        event_type: str,
+        data: Dict[str, Any],
+        entity_id: Optional[str] = None,
+        relation_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        caused_by: Optional[Sequence[Event]] = None,
+    ) -> Event:
+        """Emit an event into the process context.
+
+        Args:
+            event_type: Dotted event name (e.g. "invoice.received").
+            data: Event payload.
+            entity_id: Optional entity this event affects.
+            relation_id: Optional relation this event affects.
+            metadata: Arbitrary metadata.
+            caused_by: Parent events that caused this one (builds the DAG).
+
+        Returns:
+            The persisted Event object.
+        """
+        parent_ids = tuple(e.id for e in caused_by) if caused_by else ()
+
+        event = Event(
+            id=generate_id(),
+            type=event_type,
+            process_id=self.process_id,
+            data=data,
+            agent_id=self.agent_id,
+            entity_id=entity_id,
+            relation_id=relation_id,
+            scope=self.scope,
+            metadata=metadata or {},
+            parent_ids=parent_ids,
+        )
+
+        # 1. Persist to source of truth
+        self._store.save_event(event)
+
+        # 2. Project to graph (best-effort)
+        if self._projector:
+            self._projector.project_event(event)
+
+        # 3. Notify subscribers
+        self._router.notify_subscribers(event)
+
+        # 4. Evaluate routing rules
+        decision = self._router.evaluate(event)
+        if decision:
+            self._persist_routing_decision(decision, parent_event=event)
+
+        log.debug("Emitted: %s (type=%s, entity=%s)", event.id[:8], event_type, entity_id)
+        return event
+
+    def batch_emit(
+        self, events_spec: List[Dict[str, Any]]
+    ) -> List[Event]:
+        """Atomically emit multiple events in a single transaction.
+
+        Each spec is a dict with keys: event_type, data, and optionally
+        entity_id, relation_id, metadata.
+        """
+        events = []
+        for spec in events_spec:
+            event = Event(
+                id=generate_id(),
+                type=spec["event_type"],
+                process_id=self.process_id,
+                data=spec["data"],
+                agent_id=self.agent_id,
+                entity_id=spec.get("entity_id"),
+                relation_id=spec.get("relation_id"),
+                scope=self.scope,
+                metadata=spec.get("metadata", {}),
+            )
+            events.append(event)
+
+        self._store.save_events(events)
+
+        # Best-effort graph projection
+        if self._projector:
+            for ev in events:
+                self._projector.project_event(ev)
+
+        return events
+
+    def _persist_routing_decision(
+        self, decision: RoutingDecision, parent_event: Event
+    ) -> None:
+        """Save a routing decision as a child event (no re-evaluation)."""
+        decision_event = Event(
+            id=generate_id(),
+            type="routing.decision",
+            process_id=self.process_id,
+            data=decision.to_dict(),
+            agent_id="system.router",
+            entity_id=parent_event.entity_id,
+            scope=self.scope,
+            parent_ids=(parent_event.id,),
+        )
+        self._store.save_event(decision_event)
+        if self._projector:
+            self._projector.project_event(decision_event)
+
+    # -- query events -------------------------------------------------------
+
+    def query(
+        self,
+        entity_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        scope: Optional[str] = None,
+        as_of: Optional[datetime] = None,
+        limit: int = 1000,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """Query events in this process with optional filters."""
+        return self._store.query_events(
+            self.process_id,
+            entity_id=entity_id,
+            event_type=event_type,
+            scope=scope or self.scope,
+            as_of=as_of,
+            limit=limit,
+            offset=offset,
+        )
+
+    def timeline(self, entity_id: str, as_of: Optional[datetime] = None) -> List[Dict[str, Any]]:
+        """Get the full ordered event history for an entity."""
+        return self._store.query_events(
+            self.process_id,
+            entity_id=entity_id,
+            as_of=as_of,
+        )
+
+    # -- entity snapshots ---------------------------------------------------
+
+    def save_entity(self, entity: Entity) -> None:
+        """Save a versioned entity snapshot."""
+        self._store.save_entity(entity)
+        if self._projector:
+            self._projector.project_entity(entity)
+
+    def get_entity(
+        self, entity_id: str, as_of: Optional[datetime] = None
+    ) -> Optional[Dict[str, Any]]:
+        """Retrieve the latest entity state (or state at a point in time)."""
+        return self._store.get_entity(entity_id, as_of=as_of)
+
+    # -- relations ----------------------------------------------------------
+
+    def save_relation(self, relation: Relation) -> None:
+        """Persist a typed relation between entities."""
+        self._store.save_relation(relation)
+        if self._projector:
+            self._projector.project_relation(relation)
+
+    # -- causal DAG ---------------------------------------------------------
+
+    def causal_parents(self, event_id: str) -> List[str]:
+        """Get the events that caused this event."""
+        return self._store.get_causal_parents(event_id)
+
+    def causal_children(self, event_id: str) -> List[str]:
+        """Get the events caused by this event."""
+        return self._store.get_causal_children(event_id)
+
+    def causal_chain(self, event_id: str, max_depth: int = 10) -> List[Dict[str, Any]]:
+        """Walk the full causal DAG via Neo4j (if available)."""
+        if self._projector:
+            return self._projector.get_causal_chain(event_id, max_depth=max_depth)
+        return []
+
+    # -- graph queries ------------------------------------------------------
+
+    def lineage(self, entity_id: str, max_depth: int = 20) -> List[Dict[str, Any]]:
+        """Get Neo4j lineage for an entity (if available)."""
+        if self._projector:
+            return self._projector.get_lineage(entity_id, max_depth=max_depth)
+        return []
+
+    def cypher(self, query: str, params: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        """Execute a raw Cypher query against Neo4j."""
+        if self._projector:
+            return self._projector.run_cypher(query, params)
+        return []
+
+    # -- pub/sub convenience ------------------------------------------------
+
+    def subscribe(self, event_type: str, callback: Callable[[Event], None]) -> None:
+        """Subscribe to events of a given type."""
+        self._router.subscribe(event_type, callback)

crewcontext-0.1.0/crewcontext/demos/__init__.py

@@ -0,0 +1 @@
+"""Demo scenarios."""