contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/api/errors.py

@@ -0,0 +1,183 @@
+"""
+Standardized Error Responses
+=============================
+Provides a consistent error envelope for all API responses and a global
+exception handler that catches unhandled errors.
+
+Response format::
+
+    {
+        "error_code": "DUPLICATE_NODE",
+        "message": "A node with name 'Alice' already exists",
+        "detail": "...",          # only when AICONTEXTDB_DEBUG=true
+        "request_id": "abc123"    # when request-id middleware is active
+    }
+"""
+
+import logging
+import os
+import traceback
+import uuid
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+logger = logging.getLogger(__name__)
+
+_DEBUG = os.environ.get("CONTEXTSYNAPSE_DEBUG") or os.environ.get("AICONTEXTDB_DEBUG", "false").lower() in ("true", "1", "yes")
+
+
+# ── Standard error codes ────────────────────────────────────────────────
+
+class ErrorCode:
+    # Client errors
+    BAD_REQUEST = "BAD_REQUEST"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN = "FORBIDDEN"
+    NOT_FOUND = "NOT_FOUND"
+    CONFLICT = "CONFLICT"
+    DUPLICATE_NODE = "DUPLICATE_NODE"
+    DUPLICATE_EDGE = "DUPLICATE_EDGE"
+    RATE_LIMITED = "RATE_LIMITED"
+
+    # Server errors
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+    QUERY_ERROR = "QUERY_ERROR"
+
+
+class APIErrorResponse(BaseModel):
+    error_code: str
+    message: str
+    detail: Optional[str] = None
+    request_id: Optional[str] = None
+
+
+def _get_request_id(request: Request) -> str:
+    """Extract or generate a request ID."""
+    return getattr(request.state, "request_id", None) or request.headers.get("X-Request-ID") or uuid.uuid4().hex[:12]
+
+
+# ── Global exception handlers ───────────────────────────────────────────
+
+def install_error_handlers(app: FastAPI):
+    """Install global exception handlers on a FastAPI app."""
+
+    @app.middleware("http")
+    async def add_request_id(request: Request, call_next):
+        request.state.request_id = request.headers.get("X-Request-ID") or uuid.uuid4().hex[:12]
+        # Bind request context for structured logging
+        try:
+            import structlog
+            structlog.contextvars.clear_contextvars()
+            structlog.contextvars.bind_contextvars(request_id=request.state.request_id)
+        except ImportError:
+            pass
+        # Set provenance write context for this request
+        from contextsynapse.core.write_context import set_write_context, clear_write_context
+        set_write_context(agent_id="", origin="api", verified=True)
+        try:
+            response = await call_next(request)
+        finally:
+            clear_write_context()
+        response.headers["X-Request-ID"] = request.state.request_id
+        return response
+
+    def _handle_http_exc(request: Request, exc):
+        """Wrap HTTPExceptions in standard envelope."""
+        request_id = _get_request_id(request)
+        code_map = {
+            400: ErrorCode.BAD_REQUEST,
+            401: ErrorCode.UNAUTHORIZED,
+            403: ErrorCode.FORBIDDEN,
+            404: ErrorCode.NOT_FOUND,
+            409: ErrorCode.CONFLICT,
+            429: ErrorCode.RATE_LIMITED,
+            503: ErrorCode.SERVICE_UNAVAILABLE,
+        }
+        error_code = code_map.get(exc.status_code, ErrorCode.INTERNAL_ERROR)
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error_code": error_code,
+                "message": exc.detail if isinstance(exc.detail, str) else str(exc.detail),
+                "request_id": request_id,
+            },
+        )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def starlette_http_handler(request: Request, exc: StarletteHTTPException):
+        return _handle_http_exc(request, exc)
+
+    @app.exception_handler(HTTPException)
+    async def fastapi_http_handler(request: Request, exc: HTTPException):
+        return _handle_http_exc(request, exc)
+
+    # Import custom exceptions lazily to avoid circular imports
+    from .api import DuplicateNodeError, DuplicateEdgeError
+
+    @app.exception_handler(DuplicateNodeError)
+    async def duplicate_node_handler(request: Request, exc: DuplicateNodeError):
+        request_id = _get_request_id(request)
+        return JSONResponse(
+            status_code=409,
+            content={
+                "error_code": ErrorCode.DUPLICATE_NODE,
+                "message": exc.message,
+                "request_id": request_id,
+            },
+        )
+
+    @app.exception_handler(DuplicateEdgeError)
+    async def duplicate_edge_handler(request: Request, exc: DuplicateEdgeError):
+        request_id = _get_request_id(request)
+        return JSONResponse(
+            status_code=409,
+            content={
+                "error_code": ErrorCode.DUPLICATE_EDGE,
+                "message": exc.message,
+                "request_id": request_id,
+            },
+        )
+
+    # QueueFullError -> 503 Service Unavailable
+    try:
+        from ..jobs.queue import QueueFullError
+
+        @app.exception_handler(QueueFullError)
+        async def queue_full_handler(request: Request, exc: QueueFullError):
+            request_id = _get_request_id(request)
+            return JSONResponse(
+                status_code=503,
+                content={
+                    "error_code": ErrorCode.SERVICE_UNAVAILABLE,
+                    "message": str(exc),
+                    "request_id": request_id,
+                },
+            )
+    except ImportError:
+        pass
+
+    @app.exception_handler(Exception)
+    async def unhandled_exception_handler(request: Request, exc: Exception):
+        """Catch-all for unhandled exceptions — log full trace, return sanitized response."""
+        request_id = _get_request_id(request)
+        logger.error(
+            "Unhandled exception [request_id=%s] %s: %s\n%s",
+            request_id,
+            type(exc).__name__,
+            exc,
+            traceback.format_exc(),
+        )
+        body = {
+            "error_code": ErrorCode.INTERNAL_ERROR,
+            "message": "An internal error occurred",
+            "request_id": request_id,
+        }
+        if _DEBUG:
+            body["detail"] = traceback.format_exc()
+        return JSONResponse(status_code=500, content=body)

contextsynapse/api/events.py

@@ -0,0 +1,88 @@
+"""
+Event Bus
+=========
+Simple in-process event bus for broadcasting events to connected WebSocket clients.
+Events are stored in a bounded deque so clients can fetch recent history.
+
+Usage::
+
+    from contextsynapse.api.events import event_bus
+    event_bus.emit("graph_created", {"name": "mydb"})
+"""
+
+import asyncio
+import json
+import logging
+import time
+from collections import deque
+from typing import Any, Dict, List, Set
+
+logger = logging.getLogger(__name__)
+
+
+class EventBus:
+    """Broadcast events to WebSocket subscribers, sync listeners, and keep recent history."""
+
+    def __init__(self, max_history: int = 100):
+        self._subscribers: Set[asyncio.Queue] = set()
+        self._listeners: Dict[str, List] = {}  # event_type → [callback, ...]
+        self._history: deque = deque(maxlen=max_history)
+
+    def on(self, event_type: str, callback):
+        """Register a sync callback for an event type.
+
+        Usage:
+            event_bus.on("graph_deleted", lambda data: registry.cleanup(data["name"]))
+        """
+        if event_type not in self._listeners:
+            self._listeners[event_type] = []
+        self._listeners[event_type].append(callback)
+
+    def emit(self, event_type: str, data: Dict[str, Any] | None = None):
+        """Emit an event to all subscribers and listeners."""
+        event = {
+            "type": event_type,
+            "data": data or {},
+            "timestamp": time.time(),
+        }
+        self._history.append(event)
+
+        # Sync listeners (metadata handler, cleanup, etc.)
+        for cb in self._listeners.get(event_type, []):
+            try:
+                cb(event["data"])
+            except Exception as e:
+                logger.debug("Event listener failed for %s: %s", event_type, e)
+
+        # Wildcard listeners
+        for cb in self._listeners.get("*", []):
+            try:
+                cb(event)
+            except Exception:
+                pass
+
+        # Async WebSocket subscribers
+        for q in list(self._subscribers):
+            try:
+                q.put_nowait(event)
+            except asyncio.QueueFull:
+                pass
+
+    def subscribe(self) -> asyncio.Queue:
+        """Create a new subscription queue."""
+        q: asyncio.Queue = asyncio.Queue(maxsize=50)
+        self._subscribers.add(q)
+        return q
+
+    def unsubscribe(self, q: asyncio.Queue):
+        """Remove a subscription queue."""
+        self._subscribers.discard(q)
+
+    def recent(self, limit: int = 20) -> List[Dict[str, Any]]:
+        """Return recent events."""
+        items = list(self._history)
+        return items[-limit:]
+
+
+# Global singleton
+event_bus = EventBus()

contextsynapse/api/experiment_bootstrap.py

@@ -0,0 +1,321 @@
+"""
+Experiment Bootstrap Generator — generates runnable code for each framework.
+
+Given an agent's config (framework, API key, session, prompt), generates
+the actual code the user can run to connect that agent to AIContextDB.
+
+Supports: LangGraph, CrewAI, AutoGen, OpenAI, LlamaIndex, Pydantic AI, Swarm, Raw MCP
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+def generate_bootstrap(
+    agent: Dict[str, Any],
+    experiment: Dict[str, Any],
+    api_url: str = "http://localhost:8000",
+) -> Dict[str, str]:
+    """Generate bootstrap code + config for an agent.
+
+    Returns:
+        {
+            "code": "python code string",
+            "env": "env vars to set",
+            "instructions": "human-readable steps",
+            "framework": "langgraph",
+        }
+    """
+    fw = (agent.get("framework") or "").lower()
+    name = agent.get("name", "Agent")
+    role = agent.get("role", "agent")
+    prompt = agent.get("prompt", "Do your task.")
+    full_key = agent.get("full_key", "")
+    agent_id = agent.get("agent_id", "")
+    api_key = agent.get("api_key", "")
+    session_id = agent.get("session_id", "")
+    graph = experiment.get("graph", "default")
+
+    # Common env block
+    env = f"""# Environment variables
+CONTEXTSYNAPSE_API_URL={api_url}
+CONTEXTSYNAPSE_AGENT_KEY={full_key}
+CONTEXTSYNAPSE_SESSION_ID={session_id}
+CONTEXTSYNAPSE_GRAPH={graph}"""
+
+    generators = {
+        "langgraph": _gen_langgraph,
+        "crewai": _gen_crewai,
+        "autogen": _gen_autogen,
+        "openai": _gen_openai,
+        "llamaindex": _gen_llamaindex,
+        "pydantic_ai": _gen_pydantic_ai,
+        "swarm": _gen_swarm,
+    }
+
+    gen = generators.get(fw, _gen_mcp_raw)
+    code = gen(name, role, prompt, full_key, session_id, graph, api_url)
+
+    instructions = f"""## How to run {name} ({fw or 'MCP'})
+
+1. Install dependencies:
+   pip install contextcore-sdk {_pip_extra(fw)}
+
+2. Set environment variables (or paste into .env):
+{env}
+
+3. Run the agent:
+   python {name.lower().replace(' ', '_')}_agent.py
+
+The agent will:
+- Connect to AIContextDB at {api_url}
+- Authenticate with API key {full_key[:12]}...
+- Join session {session_id or '(auto-created)'}
+- Execute: "{prompt[:80]}..."
+- Use MCP tools to search, write, and query the graph"""
+
+    return {
+        "code": code,
+        "env": env,
+        "instructions": instructions,
+        "framework": fw or "mcp",
+        "filename": f"{name.lower().replace(' ', '_')}_agent.py",
+    }
+
+
+def _pip_extra(fw: str) -> str:
+    extras = {
+        "langgraph": "langgraph langchain-core",
+        "crewai": "crewai",
+        "autogen": "pyautogen",
+        "openai": "openai",
+        "llamaindex": "llama-index",
+        "pydantic_ai": "pydantic-ai",
+        "swarm": "openai",
+    }
+    return extras.get(fw, "")
+
+
+def _gen_langgraph(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — LangGraph agent connected to AIContextDB.
+Auto-generated by Experiment Builder.
+"""
+from contextsynapse import AIContextDB
+from contextsynapse.adapters.langgraph import create_langgraph_tools
+
+# Connect to AIContextDB
+db = AIContextDB.connect(
+    api_url="{url}",
+    api_key="{key}",
+    graph="{graph}",
+    session_id="{session}" or None,
+)
+
+# Create LangGraph-compatible tools
+tools = create_langgraph_tools(db)
+
+# Build the agent
+from langgraph.prebuilt import create_react_agent
+from langchain_core.messages import HumanMessage
+
+agent = create_react_agent(
+    model="gpt-4o-mini",  # or your preferred model
+    tools=tools,
+    state_modifier="""You are {name}, a {role} agent.
+Your task: {prompt}
+Use the provided tools to accomplish your task.""",
+)
+
+# Run
+result = agent.invoke({{"messages": [HumanMessage(content="{prompt}")]}})
+for msg in result["messages"]:
+    print(msg.content if hasattr(msg, "content") else msg)
+'''
+
+
+def _gen_crewai(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — CrewAI agent connected to AIContextDB.
+"""
+from contextsynapse import AIContextDB
+from contextsynapse.adapters.crewai import create_crewai_tools
+from crewai import Agent, Task, Crew
+
+db = AIContextDB.connect(api_url="{url}", api_key="{key}", graph="{graph}")
+tools = create_crewai_tools(db)
+
+agent = Agent(
+    role="{role}",
+    goal="{prompt}",
+    backstory="You are {name}, an expert {role}.",
+    tools=tools,
+    verbose=True,
+)
+
+task = Task(
+    description="{prompt}",
+    agent=agent,
+    expected_output="A detailed analysis based on the graph data.",
+)
+
+crew = Crew(agents=[agent], tasks=[task], verbose=True)
+result = crew.kickoff()
+print(result)
+'''
+
+
+def _gen_autogen(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — AutoGen agent connected to AIContextDB.
+"""
+from contextsynapse import AIContextDB
+from contextsynapse.adapters.autogen import create_autogen_tools
+import autogen
+
+db = AIContextDB.connect(api_url="{url}", api_key="{key}", graph="{graph}")
+tools = create_autogen_tools(db)
+
+config_list = [{{"model": "gpt-4o-mini", "api_key": "YOUR_OPENAI_KEY"}}]
+
+assistant = autogen.AssistantAgent(
+    name="{name}",
+    system_message="You are {name}, a {role}. {prompt}",
+    llm_config={{"config_list": config_list, "functions": tools}},
+)
+
+user = autogen.UserProxyAgent(
+    name="user",
+    human_input_mode="NEVER",
+    max_consecutive_auto_reply=5,
+)
+
+user.initiate_chat(assistant, message="{prompt}")
+'''
+
+
+def _gen_openai(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — OpenAI Agents SDK connected to AIContextDB.
+"""
+from contextsynapse import AIContextDB
+from contextsynapse.adapters.openai import create_openai_tools
+from openai import OpenAI
+
+db = AIContextDB.connect(api_url="{url}", api_key="{key}", graph="{graph}")
+tools = create_openai_tools(db)
+
+client = OpenAI()
+messages = [
+    {{"role": "system", "content": "You are {name}, a {role}. Use tools to accomplish your task."}},
+    {{"role": "user", "content": "{prompt}"}},
+]
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=messages,
+    tools=tools,
+    tool_choice="auto",
+)
+
+print(response.choices[0].message.content)
+'''
+
+
+def _gen_llamaindex(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — LlamaIndex agent connected to AIContextDB.
+"""
+from contextsynapse import AIContextDB
+from contextsynapse.adapters.llamaindex import create_llamaindex_tools
+from llama_index.agent.openai import OpenAIAgent
+
+db = AIContextDB.connect(api_url="{url}", api_key="{key}", graph="{graph}")
+tools = create_llamaindex_tools(db)
+
+agent = OpenAIAgent.from_tools(
+    tools,
+    system_prompt="You are {name}, a {role}. {prompt}",
+    verbose=True,
+)
+
+response = agent.chat("{prompt}")
+print(response)
+'''
+
+
+def _gen_pydantic_ai(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — Pydantic AI agent connected to AIContextDB.
+"""
+from contextsynapse import AIContextDB
+from contextsynapse.adapters.pydantic_ai import create_pydantic_ai_tools
+from pydantic_ai import Agent
+
+db = AIContextDB.connect(api_url="{url}", api_key="{key}", graph="{graph}")
+tools = create_pydantic_ai_tools(db)
+
+agent = Agent(
+    "openai:gpt-4o-mini",
+    system_prompt="You are {name}, a {role}. {prompt}",
+    tools=tools,
+)
+
+result = agent.run_sync("{prompt}")
+print(result.data)
+'''
+
+
+def _gen_swarm(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — OpenAI Swarm agent connected to AIContextDB.
+"""
+from contextsynapse import AIContextDB
+from contextsynapse.adapters.swarm import create_swarm_tools
+from swarm import Swarm, Agent
+
+db = AIContextDB.connect(api_url="{url}", api_key="{key}", graph="{graph}")
+tools = create_swarm_tools(db)
+
+agent = Agent(
+    name="{name}",
+    instructions="You are {name}, a {role}. {prompt}",
+    functions=tools,
+)
+
+client = Swarm()
+response = client.run(agent=agent, messages=[{{"role": "user", "content": "{prompt}"}}])
+print(response.messages[-1]["content"])
+'''
+
+
+def _gen_mcp_raw(name, role, prompt, key, session, graph, url):
+    return f'''"""
+{name} — Raw MCP client connected to AIContextDB.
+No framework needed — uses AIContextDB SDK directly.
+"""
+from contextsynapse import AIContextDB, ContextHub
+
+# Connect
+db = AIContextDB.connect(
+    api_url="{url}",
+    api_key="{key}",
+    graph="{graph}",
+    session_id="{session}" or None,
+)
+
+# Search the graph
+results = db.search("{prompt[:50]}")
+print(f"Found {{len(results)}} results")
+
+# Build context for LLM
+hub = ContextHub(db)
+context = hub.build(system_prompt="You are {name}, a {role}.")
+messages = context.to_messages()
+messages.append({{"role": "user", "content": "{prompt}"}})
+
+# Call any LLM with the context
+print("Context ready with", len(messages), "messages")
+print("System prompt:", messages[0]["content"][:200])
+'''