contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/__init__.py

@@ -0,0 +1,107 @@
+"""
+ContextSynapse — The Shared Brain for AI Agents
+=================================================
+Open-source context engine — ingest knowledge, build connections,
+and deliver the right context to any LLM. Shared memory, Graph RAG,
+AIQL query language, and enterprise security for multi-agent systems.
+
+Quick start:
+    from contextsynapse import ContextSynapse, ContextHub
+    from contextsynapse.sdk import connect, ContextSynapseAgent
+
+    # Direct graph access (in-process)
+    db = ContextSynapse()
+    db.add_node(GraphNode(id="1", label="Person", properties={"name": "Alice"}))
+
+    # SDK client (REST API)
+    ctx = connect("http://localhost:8000", agent_name="my-bot")
+    agent = ContextSynapseAgent("my-bot", server="http://localhost:8000")
+"""
+
+__version__ = "1.0.0"
+__author__ = "ContextSynapse Contributors"
+
+# ── Core (always needed, lightweight) ────────────────────────────
+from .core.hybrid_graph_storage import ContextSynapse, AIContextDB
+from .core.graph_structures import GraphNode, GraphEdge
+from .core.registry import GraphRegistry
+
+# Backward compat aliases
+AINatDB = AIContextDB
+
+# ── AIQL ─────────────────────────────────────────────────────────
+try:
+    from .aiql.parser import AIQLParser
+    from .aiql.engine import AIQLExecutor
+except ImportError:
+    AIQLParser = None
+    AIQLExecutor = None
+
+# ── ContextHub ───────────────────────────────────────────────────
+try:
+    from .context import ContextHub, ContextItem, ContextRole, ContextFormat
+except ImportError:
+    ContextHub = None
+    ContextItem = None
+    ContextRole = None
+    ContextFormat = None
+
+
+def __getattr__(name):
+    """Lazy import for heavy optional modules."""
+    _lazy = {
+        # SDK
+        "connect": (".sdk", "connect"),
+        "ContextSynapseAgent": (".sdk", "ContextSynapseAgent"),
+        "AIContextDBAgent": (".sdk", "ContextSynapseAgent"),
+        # Search
+        "EnhancedSearch": (".search.enhanced_search", "EnhancedSearch"),
+        # Vector
+        "VectorDatabase": (".vector.vector_db", "VectorDatabase"),
+        # Storage
+        "NamespaceStore": (".storage.namespace_store", "NamespaceStore"),
+        "WALConfig": (".storage.wal", "WALConfig"),
+        # Adapters
+        "AIContextDBConnection": (".adapters", "AIContextDBConnection"),
+        # LLM
+        "LLMClient": (".llm", "LLMClient"),
+        "get_llm_client": (".llm", "get_llm_client"),
+        # Extraction
+        "EntityExtractor": (".extraction.llm_entity_extractor", "EntityExtractor"),
+        "FactExtractor": (".extraction.fact_extractor", "FactExtractor"),
+        "load_schema": (".extraction.schema_loader", "load_schema"),
+    }
+    if name in _lazy:
+        module_path, attr = _lazy[name]
+        import importlib
+        try:
+            module = importlib.import_module(module_path, __package__)
+            return getattr(module, attr)
+        except (ImportError, AttributeError):
+            return None
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Core (new canonical names)
+    "ContextSynapse", "GraphNode", "GraphEdge", "GraphRegistry",
+    # Core (backward compat)
+    "AIContextDB", "AINatDB",
+    # AIQL
+    "AIQLParser", "AIQLExecutor",
+    # Context
+    "ContextHub", "ContextItem", "ContextRole", "ContextFormat",
+    # SDK (new canonical names)
+    "connect", "ContextSynapseAgent",
+    # SDK (backward compat)
+    "AIContextDBAgent",
+    # Search & Vector
+    "EnhancedSearch", "VectorDatabase",
+    # Storage
+    "NamespaceStore", "WALConfig",
+    # Adapters
+    "AIContextDBConnection",
+    # LLM & Extraction
+    "LLMClient", "get_llm_client",
+    "EntityExtractor", "FactExtractor", "load_schema",
+]

contextsynapse/__main__.py

@@ -0,0 +1,9 @@
+"""
+AIContextDB Package Entry Point
+Allows running CLI via: python -m contextcore
+"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

contextsynapse/a2a/__init__.py

@@ -0,0 +1,28 @@
+"""
+A2A (Agent-to-Agent) Protocol Support
+=======================================
+Implements Google's A2A protocol for agent interoperability.
+
+- models.py      — Core dataclasses (Task, Message, Part, Artifact)
+- task_manager.py — Task state machine + persistence
+- handlers.py    — Server-side request handlers
+- client.py      — Outbound HTTP client for calling external A2A agents
+- discovery.py   — Remote agent card registry
+- streaming.py   — SSE transport for real-time task events
+"""
+
+from .models import (
+    TaskState,
+    TextPart,
+    FilePart,
+    DataPart,
+    Message,
+    Artifact,
+    TaskStatus,
+    Task,
+)
+
+__all__ = [
+    "TaskState", "TextPart", "FilePart", "DataPart",
+    "Message", "Artifact", "TaskStatus", "Task",
+]

contextsynapse/a2a/client.py

@@ -0,0 +1,120 @@
+"""
+A2A Client
+===========
+Outbound HTTP client for calling external A2A agents.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, AsyncGenerator, Dict, Optional
+
+from .models import Artifact, Message, Task
+
+logger = logging.getLogger(__name__)
+
+
+class A2AClient:
+    """HTTP client for interacting with an external A2A agent server."""
+
+    def __init__(self, base_url: str, auth_token: Optional[str] = None, timeout: float = 60.0):
+        self.base_url = base_url.rstrip("/")
+        self.auth_token = auth_token
+        self.timeout = timeout
+
+    def _headers(self) -> Dict[str, str]:
+        h = {"Content-Type": "application/json"}
+        if self.auth_token:
+            h["Authorization"] = f"Bearer {self.auth_token}"
+        return h
+
+    def _rpc_payload(self, method: str, params: Dict[str, Any], req_id: str = "1") -> Dict:
+        return {"jsonrpc": "2.0", "id": req_id, "method": method, "params": params}
+
+    # ── Discovery ─────────────────────────────────────────────────────
+
+    def discover(self) -> Dict[str, Any]:
+        """Fetch the remote agent's Agent Card."""
+        import requests
+        resp = requests.get(
+            f"{self.base_url}/.well-known/agent.json",
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # ── Task Lifecycle ────────────────────────────────────────────────
+
+    def send_task(self, message: Message, session_id: str = "", metadata: Optional[Dict] = None) -> Task:
+        """Send a task to the remote agent."""
+        import requests
+        params: Dict[str, Any] = {"message": message.to_dict()}
+        if session_id:
+            params["sessionId"] = session_id
+        if metadata:
+            params["metadata"] = metadata
+
+        resp = requests.post(
+            f"{self.base_url}/a2a",
+            json=self._rpc_payload("tasks/send", params),
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if "error" in data:
+            raise RuntimeError(f"A2A error: {data['error'].get('message', data['error'])}")
+        return Task.from_dict(data.get("result", {}))
+
+    def get_task(self, task_id: str) -> Task:
+        """Get task status from the remote agent."""
+        import requests
+        resp = requests.post(
+            f"{self.base_url}/a2a",
+            json=self._rpc_payload("tasks/get", {"id": task_id}),
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if "error" in data:
+            raise RuntimeError(f"A2A error: {data['error'].get('message', data['error'])}")
+        return Task.from_dict(data.get("result", {}))
+
+    def cancel_task(self, task_id: str) -> Task:
+        """Cancel a task on the remote agent."""
+        import requests
+        resp = requests.post(
+            f"{self.base_url}/a2a",
+            json=self._rpc_payload("tasks/cancel", {"id": task_id}),
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if "error" in data:
+            raise RuntimeError(f"A2A error: {data['error'].get('message', data['error'])}")
+        return Task.from_dict(data.get("result", {}))
+
+    def send_subscribe(self, message: Message, session_id: str = "") -> str:
+        """Send a task with SSE streaming — returns the full streamed response."""
+        import requests
+        params: Dict[str, Any] = {"message": message.to_dict()}
+        if session_id:
+            params["sessionId"] = session_id
+
+        resp = requests.post(
+            f"{self.base_url}/a2a",
+            json=self._rpc_payload("tasks/sendSubscribe", params),
+            headers=self._headers(),
+            timeout=self.timeout,
+            stream=True,
+        )
+        resp.raise_for_status()
+        chunks = []
+        for line in resp.iter_lines(decode_unicode=True):
+            if line and line.startswith("data:"):
+                chunks.append(line[5:].strip())
+        return "\n".join(chunks)

contextsynapse/a2a/discovery.py

@@ -0,0 +1,128 @@
+"""
+A2A Discovery Registry
+=======================
+Cache and query remote A2A agent cards.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from contextsynapse.core.db import IS_POSTGRES, PH, connect, dict_cursor, run_ddl, row_to_dict
+
+from .client import A2AClient
+
+logger = logging.getLogger(__name__)
+
+
+class A2ADiscoveryRegistry:
+    """Registry for discovered remote A2A agents."""
+
+    _SCHEMA = """
+    CREATE TABLE IF NOT EXISTS a2a_remotes (
+        url TEXT PRIMARY KEY,
+        name TEXT,
+        card_json TEXT,
+        status TEXT DEFAULT 'active',
+        last_fetched TEXT,
+        created_at TEXT NOT NULL
+    );
+    """
+
+    def __init__(self, db_path: str = "contextcore_data/context.db"):
+        self._db_path = Path(db_path)
+        if not IS_POSTGRES:
+            self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = connect(str(self._db_path))
+        run_ddl(self._conn, self._SCHEMA)
+
+    def _exec(self, sql: str, params: tuple = ()):
+        cur = dict_cursor(self._conn)
+        cur.execute(sql, params)
+        return cur
+
+    def _commit(self):
+        self._conn.commit()
+
+    def register_remote(self, url: str, auth_token: str = "") -> Dict[str, Any]:
+        """Discover and register a remote A2A agent."""
+        client = A2AClient(url, auth_token=auth_token)
+        card = client.discover()
+        now = datetime.now(timezone.utc).isoformat()
+        if IS_POSTGRES:
+            self._exec(
+                f"INSERT INTO a2a_remotes (url, name, card_json, status, last_fetched, created_at) "
+                f"VALUES ({PH}, {PH}, {PH}, 'active', {PH}, {PH}) "
+                f"ON CONFLICT (url) DO UPDATE SET name = EXCLUDED.name, card_json = EXCLUDED.card_json, "
+                f"status = 'active', last_fetched = EXCLUDED.last_fetched",
+                (url, card.get("name", url), json.dumps(card), now, now),
+            )
+        else:
+            self._exec(
+                f"INSERT OR REPLACE INTO a2a_remotes (url, name, card_json, status, last_fetched, created_at) "
+                f"VALUES ({PH}, {PH}, {PH}, 'active', {PH}, COALESCE((SELECT created_at FROM a2a_remotes WHERE url = {PH}), {PH}))",
+                (url, card.get("name", url), json.dumps(card), now, url, now),
+            )
+        self._commit()
+        return card
+
+    def list_remotes(self) -> List[Dict[str, Any]]:
+        """List all registered remote agents."""
+        rows = self._exec(
+            "SELECT * FROM a2a_remotes WHERE status = 'active' ORDER BY name"
+        ).fetchall()
+        result = []
+        for r in [row_to_dict(r) for r in rows]:
+            entry = {
+                "url": r["url"],
+                "name": r["name"],
+                "status": r["status"],
+                "last_fetched": r["last_fetched"],
+            }
+            try:
+                entry["card"] = json.loads(r["card_json"])
+            except Exception:
+                entry["card"] = {}
+            result.append(entry)
+        return result
+
+    def get_card(self, url: str) -> Optional[Dict[str, Any]]:
+        """Get a cached agent card by URL."""
+        row = row_to_dict(self._exec(
+            f"SELECT card_json FROM a2a_remotes WHERE url = {PH}", (url,)
+        ).fetchone())
+        if row:
+            return json.loads(row["card_json"])
+        return None
+
+    def find_by_skill(self, skill_tag: str) -> List[Dict[str, Any]]:
+        """Find remote agents that have a skill matching the given tag."""
+        remotes = self.list_remotes()
+        matches = []
+        tag_lower = skill_tag.lower()
+        for remote in remotes:
+            card = remote.get("card", {})
+            for skill in card.get("skills", []):
+                tags = [t.lower() for t in skill.get("tags", [])]
+                name = skill.get("name", "").lower()
+                if tag_lower in tags or tag_lower in name:
+                    matches.append(remote)
+                    break
+        return matches
+
+    def refresh(self, url: str, auth_token: str = "") -> Optional[Dict[str, Any]]:
+        """Re-fetch and update a remote agent's card."""
+        try:
+            return self.register_remote(url, auth_token)
+        except Exception as e:
+            logger.warning("Failed to refresh remote %s: %s", url, e)
+            return None
+
+    def remove(self, url: str):
+        """Remove a remote agent."""
+        self._exec(f"DELETE FROM a2a_remotes WHERE url = {PH}", (url,))
+        self._commit()

contextsynapse/a2a/handlers.py

@@ -0,0 +1,164 @@
+"""
+A2A Server Handlers
+====================
+Business logic for processing inbound A2A requests.
+Separates HTTP concerns (router) from task execution logic.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from .models import (
+    Artifact,
+    DataPart,
+    Message,
+    Task,
+    TaskState,
+    TextPart,
+)
+from .task_manager import A2ATaskManager
+
+logger = logging.getLogger(__name__)
+
+
+def handle_task_send(
+    task_manager: A2ATaskManager,
+    params: Dict[str, Any],
+    caller_agent_id: str = "",
+    tool_registry=None,
+    tool_gateway=None,
+    graph_registry=None,
+) -> Task:
+    """Handle tasks/send — create a task and begin execution."""
+
+    # Parse message from params
+    msg_data = params.get("message", {})
+    message = Message.from_dict(msg_data) if msg_data else Message.text(str(params.get("text", "")))
+
+    task = task_manager.create_task(
+        message=message,
+        initiator_agent_id=caller_agent_id,
+        target_agent_id=params.get("target_agent_id", ""),
+        session_id=params.get("sessionId", ""),
+        metadata=params.get("metadata", {}),
+    )
+
+    # Transition to WORKING
+    task_manager.transition(task.id, TaskState.WORKING)
+
+    # Try to execute: map message to tool calls
+    try:
+        text = message.get_text()
+        results = _execute_message(
+            text, task, tool_registry, tool_gateway, graph_registry
+        )
+
+        # Add results as artifacts
+        if results:
+            artifact = Artifact(
+                name="result",
+                description="Task execution result",
+                parts=[TextPart(text=r) for r in results],
+            )
+            task_manager.add_artifact(task.id, artifact)
+
+        # Complete the task
+        result_text = "\n".join(results) if results else "Task completed"
+        task = task_manager.complete_task(
+            task.id, Message.text(result_text, role="agent")
+        )
+
+    except Exception as e:
+        logger.warning("A2A task %s failed: %s", task.id, e)
+        task = task_manager.fail_task(task.id, str(e))
+
+    return task
+
+
+def handle_task_get(task_manager: A2ATaskManager, task_id: str) -> Optional[Task]:
+    """Handle tasks/get — return current task state."""
+    return task_manager.get_task(task_id)
+
+
+def handle_task_cancel(task_manager: A2ATaskManager, task_id: str) -> Task:
+    """Handle tasks/cancel."""
+    return task_manager.cancel_task(task_id)
+
+
+def _execute_message(
+    text: str,
+    task: Task,
+    tool_registry=None,
+    tool_gateway=None,
+    graph_registry=None,
+) -> List[str]:
+    """Map an A2A message to tool calls and execute them."""
+    results = []
+
+    if not tool_registry:
+        results.append(f"Received: {text}")
+        return results
+
+    # Try to match message to a tool call
+    tool_calls = map_message_to_tools(text, tool_registry)
+
+    if not tool_calls:
+        # No specific tool match — use the "ask" tool for general queries
+        tool_calls = [("ask", {"question": text})]
+
+    for tool_name, kwargs in tool_calls:
+        try:
+            if tool_gateway:
+                from ..tools.registry import ToolContext
+                # Build minimal ToolContext
+                ctx = ToolContext(
+                    conn=None,
+                    agent_id=task.metadata.get("target_agent_id", ""),
+                    agent_name="a2a",
+                )
+                result = tool_gateway.execute(tool_name, ctx, kwargs)
+            else:
+                result = tool_registry.dispatch(tool_name, None, kwargs)
+            results.append(str(result))
+        except Exception as e:
+            results.append(f"Error executing {tool_name}: {e}")
+
+    return results
+
+
+def map_message_to_tools(text: str, tool_registry) -> List[Tuple[str, dict]]:
+    """Map natural language message to tool calls.
+
+    Uses simple keyword matching. For production, this would use an LLM
+    to parse intent → tool mapping.
+    """
+    text_lower = text.lower().strip()
+    calls = []
+
+    # Direct tool invocation: "tool:search_nodes label=Person"
+    if text_lower.startswith("tool:"):
+        parts = text[5:].strip().split(" ", 1)
+        tool_name = parts[0]
+        kwargs = {}
+        if len(parts) > 1:
+            # Parse key=value pairs
+            for pair in parts[1].split(" "):
+                if "=" in pair:
+                    k, v = pair.split("=", 1)
+                    kwargs[k] = v
+        calls.append((tool_name, kwargs))
+        return calls
+
+    # Keyword-based routing
+    if any(w in text_lower for w in ["search", "find", "look for", "query"]):
+        calls.append(("search_nodes", {"query": text}))
+    elif any(w in text_lower for w in ["status", "progress", "overview"]):
+        calls.append(("project_status", {}))
+    elif any(w in text_lower for w in ["brief", "context", "summary"]):
+        calls.append(("briefing", {}))
+    elif any(w in text_lower for w in ["task", "todo", "work item"]):
+        calls.append(("list_tasks", {}))
+
+    return calls