crewcontext 0.1.0__py3-none-any.whl

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/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/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/demos/__init__.py

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

crewcontext/demos/vendor_discrepancy.py

@@ -0,0 +1,205 @@
+"""Vendor discrepancy demo — showcases the full CrewContext pipeline.
+
+Scenario: An invoice arrives with a vendor mismatch. Three agents handle
+it in sequence — receiver, validator, reconciler. CrewContext preserves
+full context, causal chains, and routing decisions across handoffs.
+"""
+from crewcontext.context import ProcessContext
+from crewcontext.models import Entity, Relation, generate_id
+from crewcontext.router import all_of, data_field_gt, data_fields_differ
+
+
+def run_demo():
+    process_id = f"demo-{generate_id()[:8]}"
+    invoice_id = f"inv-{generate_id()[:8]}"
+
+    print(f"{'=' * 60}")
+    print(f"  CrewContext Demo: Vendor Discrepancy Resolution")
+    print(f"  Process: {process_id}")
+    print(f"  Invoice: {invoice_id}")
+    print(f"{'=' * 60}\n")
+
+    # ── Agent 1: Invoice Receiver ─────────────────────────────
+
+    print("[Agent: invoice-receiver]")
+    with ProcessContext(
+        process_id=process_id,
+        agent_id="agent-invoice-receiver",
+        enable_neo4j=True,
+    ) as ctx:
+
+        # Set up routing rules
+        ctx.router.add_rule(
+            name="high-value-review",
+            condition=data_field_gt("amount", 1000),
+            action="route-to-senior-auditor",
+            priority=10,
+            metadata={"sla_hours": 4},
+        )
+        ctx.router.add_rule(
+            name="vendor-mismatch",
+            condition=data_fields_differ("vendor_id", "expected_vendor_id"),
+            action="flag-for-reconciliation",
+            priority=5,
+            metadata={"requires_manual_review": True},
+        )
+
+        # Emit: invoice received
+        e1 = ctx.emit(
+            "invoice.received",
+            {
+                "invoice_id": invoice_id,
+                "vendor_id": "V-1001",
+                "expected_vendor_id": "V-1002",
+                "amount": 15000,
+                "currency": "USD",
+            },
+            entity_id=invoice_id,
+        )
+        print(f"  Emitted: invoice.received (amount=15000 USD)")
+        print(f"  Event ID: {e1.id[:12]}...")
+
+        # Save entity snapshot
+        ctx.save_entity(Entity(
+            id=invoice_id, type="Invoice",
+            attributes={
+                "amount": 15000, "currency": "USD",
+                "vendor_id": "V-1001", "status": "received",
+            },
+            provenance={"agent": "agent-invoice-receiver"},
+        ))
+        print(f"  Entity snapshot saved: {invoice_id} v1")
+
+        # Check routing decisions
+        decisions = ctx.query(event_type="routing.decision")
+        for d in decisions:
+            data = d.get("data", {})
+            print(f"  Routing: {data.get('rule_name')} -> {data.get('action')}")
+
+    # ── Agent 2: Validator ────────────────────────────────────
+
+    print(f"\n[Agent: invoice-validator]")
+    with ProcessContext(
+        process_id=process_id,
+        agent_id="agent-invoice-validator",
+        enable_neo4j=True,
+    ) as ctx:
+
+        # Query what happened before (context handoff!)
+        history = ctx.timeline(invoice_id)
+        print(f"  Context received: {len(history)} prior events")
+
+        # Emit: validation result (caused by e1)
+        e2 = ctx.emit(
+            "invoice.validated",
+            {
+                "invoice_id": invoice_id,
+                "validation_status": "discrepancy_found",
+                "discrepancy_type": "vendor_mismatch",
+                "vendor_on_invoice": "V-1001",
+                "vendor_expected": "V-1002",
+            },
+            entity_id=invoice_id,
+            caused_by=[e1],
+        )
+        print(f"  Emitted: invoice.validated (discrepancy_found)")
+        print(f"  Causal parent: {e1.id[:12]}...")
+
+        # Update entity snapshot
+        ctx.save_entity(Entity(
+            id=invoice_id, type="Invoice", version=2,
+            attributes={
+                "amount": 15000, "currency": "USD",
+                "vendor_id": "V-1001", "status": "discrepancy_found",
+            },
+            provenance={"agent": "agent-invoice-validator"},
+        ))
+        print(f"  Entity snapshot saved: {invoice_id} v2")
+
+    # ── Agent 3: Reconciler ───────────────────────────────────
+
+    print(f"\n[Agent: reconciler]")
+    with ProcessContext(
+        process_id=process_id,
+        agent_id="agent-reconciler",
+        enable_neo4j=True,
+    ) as ctx:
+
+        # Full context available
+        history = ctx.timeline(invoice_id)
+        print(f"  Context received: {len(history)} prior events")
+
+        # Emit: reconciliation
+        e3 = ctx.emit(
+            "reconciliation.completed",
+            {
+                "invoice_id": invoice_id,
+                "resolution": "vendor_corrected",
+                "original_vendor": "V-1001",
+                "corrected_vendor": "V-1002",
+            },
+            entity_id=invoice_id,
+            caused_by=[e2],
+        )
+        print(f"  Emitted: reconciliation.completed")
+
+        # Save relation
+        ctx.save_relation(Relation(
+            id=generate_id(), type="RECONCILED_BY",
+            from_entity_id=invoice_id, to_entity_id="agent-reconciler",
+        ))
+
+        # Final entity snapshot
+        ctx.save_entity(Entity(
+            id=invoice_id, type="Invoice", version=3,
+            attributes={
+                "amount": 15000, "currency": "USD",
+                "vendor_id": "V-1002", "status": "reconciled",
+            },
+            provenance={"agent": "agent-reconciler"},
+        ))
+        print(f"  Entity snapshot saved: {invoice_id} v3 (reconciled)")
+
+        # ── Summary ──────────────────────────────────────────
+
+        print(f"\n{'=' * 60}")
+        print(f"  SUMMARY")
+        print(f"{'=' * 60}")
+
+        full_timeline = ctx.timeline(invoice_id)
+        print(f"\n  Timeline ({len(full_timeline)} events):")
+        for evt in full_timeline:
+            agent = evt.get("agent_id", "?")
+            etype = evt.get("type", "?")
+            ts = evt.get("timestamp", "?")
+            print(f"    {ts}  [{agent}]  {etype}")
+
+        # Causal chain
+        parents = ctx.causal_parents(e3.id)
+        print(f"\n  Causal parents of reconciliation: {len(parents)}")
+        children = ctx.causal_children(e1.id)
+        print(f"  Causal children of initial receipt: {len(children)}")
+
+        # Entity state
+        entity = ctx.get_entity(invoice_id)
+        if entity:
+            print(f"\n  Final entity state:")
+            print(f"    Version: {entity.get('version')}")
+            print(f"    Status:  {entity.get('attributes', {}).get('status', 'unknown') if isinstance(entity.get('attributes'), dict) else 'see attributes'}")
+
+        # Neo4j lineage
+        lineage = ctx.lineage(invoice_id)
+        if lineage:
+            print(f"\n  Neo4j Lineage ({len(lineage)} events):")
+            for rec in lineage:
+                print(f"    {rec.get('type')} by {rec.get('agent_id')}")
+        else:
+            print(f"\n  (Neo4j lineage not available)")
+
+    print(f"\n{'=' * 60}")
+    print(f"  Demo completed successfully!")
+    print(f"{'=' * 60}")
+
+
+if __name__ == "__main__":
+    run_demo()