contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/adapters/langgraph/context_tools.py

@@ -0,0 +1,341 @@
+"""
+LangGraph CAS Context Tools
+============================
+LangGraph-compatible tools for interacting with Context-as-a-Service sessions.
+
+These tools give myECHO / AgenticTwin agents the ability to:
+- Ingest data into context sessions
+- Search context semantically
+- Contribute insights back to shared context
+- Export context for LLM consumption
+- View session state and provenance
+
+Usage::
+
+    from contextsynapse.adapters.langgraph import create_context_tools
+
+    tools = create_context_tools(
+        session_name="research-project",
+        agent_name="myecho-analyst",
+    )
+    # Pass to LangGraph agent or ToolNode
+"""
+
+import json
+import logging
+import uuid
+from typing import Any, Dict, List, Optional
+
+from langchain_core.tools import tool
+
+logger = logging.getLogger(__name__)
+
+
+def create_context_tools(
+    session_name: str = "default",
+    agent_name: str = "langgraph-agent",
+    agent_role: str = "agent",
+    agent_platform: str = "app",
+) -> list:
+    """
+    Create LangGraph-compatible tools for CAS context operations.
+
+    These tools operate on a shared context session, allowing agents in
+    a myECHO / LangGraph workflow to read, write, and search context.
+
+    Args:
+        session_name: Name of the context session to operate on.
+        agent_name:   Name to register this agent as.
+        agent_role:   Role of the agent (agent, researcher, summarizer, etc.)
+
+    Returns:
+        List of @tool-decorated functions.
+    """
+    # Lazy-initialise CAS components
+    _state = {}
+
+    def _init():
+        if _state:
+            return
+        from ...context.agents import AgentRegistry
+        from ...context.session import ContextSessionManager
+        from ...context.hub import ContextHub
+        from ...context.vector_integration import SessionVectorStore
+        from ...context.dedup import ContextDedup
+
+        try:
+            from ...core.registry import GraphRegistry
+            graph_registry = GraphRegistry()
+        except Exception:
+            graph_registry = None
+
+        agent_registry = AgentRegistry()
+        session_manager = ContextSessionManager(graph_registry=graph_registry)
+        vector_store = SessionVectorStore()
+        dedup_engine = ContextDedup(vector_store=vector_store)
+
+        # Register this agent
+        agent, api_key = agent_registry.register(
+            name=agent_name,
+            role=agent_role,
+            platform=agent_platform,
+            capabilities=["read", "write", "search"],
+        )
+
+        # Get or create the session
+        session = session_manager.get_session_by_name(session_name)
+        if not session:
+            session = session_manager.create_session(
+                name=session_name,
+                owner_agent_id=agent.agent_id,
+            )
+
+        # Hub for in-memory context
+        from ...context.cli import _load_hub
+        hub = _load_hub(session.session_id)
+
+        _state.update({
+            "agent": agent,
+            "session": session,
+            "session_manager": session_manager,
+            "agent_registry": agent_registry,
+            "vector_store": vector_store,
+            "dedup": dedup_engine,
+            "graph_registry": graph_registry,
+            "hub": hub,
+        })
+
+    def _save_hub():
+        from ...context.cli import _save_hub as save_fn
+        save_fn(_state["session"].session_id, _state["hub"])
+
+    # ------------------------------------------------------------------
+    # Tools
+    # ------------------------------------------------------------------
+
+    @tool
+    def ingest_context(text: str, source: str = "agent", label: str = "") -> str:
+        """Add text to the shared context session. Use this to store information,
+        observations, document excerpts, or any data that should be available
+        to other agents in the workflow.
+
+        Args:
+            text: The text content to ingest into context.
+            source: Where this data came from (e.g., "web_search", "user_input", "document").
+            label: Optional short label/heading for this context item.
+
+        Returns: JSON with success status and dedup info.
+        """
+        _init()
+        session_id = _state["session"].session_id
+        agent_id = _state["agent"].agent_id
+
+        # Dedup check
+        dup = _state["dedup"].check(session_id, text)
+        if dup.is_duplicate:
+            return json.dumps({
+                "success": False,
+                "duplicate": True,
+                "match_type": dup.match_type,
+                "score": dup.score,
+                "message": f"Already in context ({dup.match_type})",
+            })
+
+        # Add to hub
+        hub = _state["hub"]
+        hub.add_text(text, role="retrieved", label=label or None, source=source)
+
+        # Embed into vector store
+        node_id = str(uuid.uuid4())
+        vs = _state["vector_store"]
+        if vs.available:
+            vs.add_text(
+                session_id=session_id,
+                text=text,
+                node_id=node_id,
+                metadata={"agent_id": agent_id, "source": source, "label": label},
+            )
+
+        # Register hash
+        _state["dedup"].register(session_id, node_id, text)
+        _save_hub()
+
+        return json.dumps({
+            "success": True,
+            "item_count": len(hub),
+            "node_id": node_id,
+        })
+
+    @tool
+    def search_context(query: str, k: int = 5) -> str:
+        """Semantic search across the shared context session. Use this to find
+        relevant information that has been ingested by any agent.
+
+        Args:
+            query: Natural language search query.
+            k: Number of results to return (default 5).
+
+        Returns: JSON list of matching context items with scores.
+        """
+        _init()
+        session_id = _state["session"].session_id
+        vs = _state["vector_store"]
+
+        if not vs.available:
+            return json.dumps({"error": "Vector search not available"})
+
+        results = vs.search(session_id=session_id, query=query, k=k)
+        return json.dumps(results, indent=2, default=str)
+
+    @tool
+    def contribute_insight(
+        content: str,
+        insight_type: str = "synthesis",
+        label: str = "",
+        source_ids: str = "",
+    ) -> str:
+        """Write an agent's output (summary, analysis, decision) back into the
+        shared context. Other agents can see and build on this.
+
+        Args:
+            content: The insight text (summary, analysis, decision, etc.)
+            insight_type: Type of contribution: "synthesis", "decision", or "generated".
+            label: Optional heading for this insight.
+            source_ids: Comma-separated IDs of items this was derived from.
+
+        Returns: JSON with insight details.
+        """
+        _init()
+        session_id = _state["session"].session_id
+        agent_id = _state["agent"].agent_id
+
+        # Dedup
+        dup = _state["dedup"].check(session_id, content)
+        if dup.is_duplicate:
+            return json.dumps({
+                "success": False,
+                "duplicate": True,
+                "message": f"Duplicate insight ({dup.match_type})",
+            })
+
+        hub = _state["hub"]
+        src_ids = [s.strip() for s in source_ids.split(",") if s.strip()]
+
+        hub.contribute(
+            content=content,
+            agent_id=agent_id,
+            role=insight_type,
+            label=label or None,
+            source_ids=src_ids,
+        )
+
+        # Persist as graph node if possible
+        insight_node_id = str(uuid.uuid4())
+        graph_registry = _state["graph_registry"]
+        session = _state["session"]
+        if graph_registry:
+            graph = graph_registry.get_graph(session.graph_namespace, load_if_missing=True)
+            if graph:
+                from ...core.graph_structures import GraphNode, GraphEdge
+                node = GraphNode(
+                    id=insight_node_id,
+                    label="Insight",
+                    properties={
+                        "content": content,
+                        "insight_type": insight_type,
+                        "agent_id": agent_id,
+                        "_ctx_session_id": session.session_id,
+                    },
+                )
+                graph.add_node(node)
+
+                for src_id in src_ids:
+                    try:
+                        edge = GraphEdge(
+                            id=str(uuid.uuid4()),
+                            source=insight_node_id,
+                            target=src_id,
+                            label="DERIVED_FROM",
+                            properties={"agent_id": agent_id},
+                        )
+                        graph.add_edge(edge)
+                    except Exception:
+                        pass
+
+        # Embed
+        vs = _state["vector_store"]
+        if vs.available:
+            vs.add_text(
+                session_id=session_id,
+                text=content,
+                node_id=insight_node_id,
+                metadata={"agent_id": agent_id, "role": insight_type, "source": "contribute"},
+            )
+
+        _state["dedup"].register(session_id, insight_node_id, content)
+        _save_hub()
+
+        return json.dumps({
+            "success": True,
+            "insight_node_id": insight_node_id,
+            "item_count": len(hub),
+        })
+
+    @tool
+    def get_context(format: str = "prompt", max_items: int = 50) -> str:
+        """Export the current shared context for use in LLM prompts.
+        Use this to get all accumulated context before making a decision.
+
+        Args:
+            format: Output format - "prompt" (string), "messages" (chat format), or "markdown".
+            max_items: Maximum number of context items to include.
+
+        Returns: The context in the requested format.
+        """
+        _init()
+        hub = _state["hub"]
+
+        if format == "messages":
+            return json.dumps(hub.to_messages(), indent=2)
+        elif format == "markdown":
+            return hub.to_markdown()
+        else:
+            return hub.to_prompt()
+
+    @tool
+    def context_stats() -> str:
+        """Get statistics about the current context session.
+        Shows item count, token estimate, vector count, and agent access.
+
+        Returns: JSON with session statistics.
+        """
+        _init()
+        session = _state["session"]
+        hub = _state["hub"]
+        vs = _state["vector_store"]
+
+        stats = {
+            "session_name": session.name,
+            "session_id": session.session_id,
+            "items": len(hub),
+            "estimated_tokens": hub.estimate_tokens(),
+            "within_limit": hub.is_within_limit(),
+        }
+
+        if vs:
+            vs_stats = vs.get_stats(session.session_id)
+            stats["vectors"] = vs_stats.get("vector_count", 0)
+            stats["vector_backend"] = vs_stats.get("backend", "none")
+
+        dedup_engine = _state["dedup"]
+        stats["unique_hashes"] = dedup_engine.get_hash_count(session.session_id)
+
+        return json.dumps(stats, indent=2)
+
+    return [
+        ingest_context,
+        search_context,
+        contribute_insight,
+        get_context,
+        context_stats,
+    ]

contextsynapse/adapters/langgraph/message_history.py

@@ -0,0 +1,138 @@
+"""
+LangGraph / LangChain Chat Message History backed by AIContextDB.
+
+Stores conversation messages as graph nodes (label: ChatMessage) with
+FOLLOWED_BY edges forming a linked-list per session.
+
+Usage:
+    from contextsynapse.adapters.langgraph import AIContextDBChatMessageHistory
+
+    history = AIContextDBChatMessageHistory(session_id="conv-123")
+    history.add_user_message("Hello")
+    history.add_ai_message("Hi there!")
+    print(history.messages)
+"""
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from langchain_core.chat_history import BaseChatMessageHistory
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+    messages_from_dict,
+    message_to_dict,
+)
+
+from .._base import AIContextDBConnection
+
+logger = logging.getLogger(__name__)
+
+MESSAGE_LABEL = "ChatMessage"
+MESSAGE_EDGE = "FOLLOWED_BY"
+
+
+class AIContextDBChatMessageHistory(BaseChatMessageHistory):
+    """
+    Chat message history stored as a linked list of graph nodes.
+
+    Each message becomes a ChatMessage node with:
+        - session_id, role, content, timestamp, sequence
+
+    Edges (FOLLOWED_BY) link messages in order, making conversation
+    flow visible in graph queries.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        namespace: str = "chat_history",
+        connection: Optional[AIContextDBConnection] = None,
+    ):
+        self.session_id = session_id
+        self.conn = connection or AIContextDBConnection(namespace=namespace)
+
+    @property
+    def messages(self) -> List[BaseMessage]:
+        """Retrieve all messages for this session, ordered by sequence."""
+        nodes = self.conn.get_nodes(
+            label=MESSAGE_LABEL,
+            where={"session_id": self.session_id},
+        )
+        # Sort by sequence number
+        nodes.sort(key=lambda n: n.properties.get("sequence", 0))
+
+        messages = []
+        for node in nodes:
+            msg_data = json.loads(node.properties.get("message_data", "{}"))
+            if msg_data:
+                try:
+                    restored = messages_from_dict([msg_data])
+                    messages.extend(restored)
+                except Exception:
+                    # Fallback: reconstruct from role/content
+                    messages.append(self._reconstruct_message(node.properties))
+            else:
+                messages.append(self._reconstruct_message(node.properties))
+
+        return messages
+
+    def add_message(self, message: BaseMessage) -> None:
+        """Add a message to the history."""
+        # Get current sequence number
+        existing = self.conn.get_nodes(
+            label=MESSAGE_LABEL,
+            where={"session_id": self.session_id},
+        )
+        sequence = len(existing)
+
+        # Find the last message node for edge linking
+        last_node_id = None
+        if existing:
+            existing.sort(key=lambda n: n.properties.get("sequence", 0))
+            last_node_id = existing[-1].id
+
+        # Serialize the full message
+        msg_dict = message_to_dict(message)
+
+        props = {
+            "session_id": self.session_id,
+            "role": message.type,  # "human", "ai", "system"
+            "content": message.content[:500] if message.content else "",  # preview
+            "message_data": json.dumps(msg_dict, default=str),
+            "sequence": sequence,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+
+        node = self.conn.add_node(MESSAGE_LABEL, props)
+
+        # Link to previous message
+        if last_node_id:
+            self.conn.add_edge(
+                source=last_node_id,
+                target=node.id,
+                label=MESSAGE_EDGE,
+                properties={"session_id": self.session_id},
+            )
+
+    def clear(self) -> None:
+        """Delete all messages for this session."""
+        self.conn.query(
+            f'DELETE NODES WHERE label = "{MESSAGE_LABEL}" '
+            f'AND session_id = "{self.session_id}"'
+        )
+
+    @staticmethod
+    def _reconstruct_message(props: dict) -> BaseMessage:
+        """Reconstruct a message from node properties when deserialization fails."""
+        role = props.get("role", "human")
+        content = props.get("content", "")
+        if role == "ai":
+            return AIMessage(content=content)
+        elif role == "system":
+            return SystemMessage(content=content)
+        return HumanMessage(content=content)

contextsynapse/adapters/langgraph/tools.py

@@ -0,0 +1,43 @@
+"""
+LangGraph adapter — thin wrapper over Universal Tool Layer.
+
+Usage:
+    from contextsynapse.adapters.langgraph.tools import create_langgraph_tools
+    tools = create_langgraph_tools(namespace="my-project")
+"""
+
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+from contextsynapse.tools import ToolRegistry, ToolContext
+from contextsynapse.adapters._base import AIContextDBConnection
+
+
+def create_langgraph_tools(
+    namespace: str = "default",
+    connection: Optional[AIContextDBConnection] = None,
+    categories: Optional[List[str]] = None,
+) -> list:
+    """Create LangGraph-compatible tools from the Universal Tool Registry."""
+    try:
+        from langchain_core.tools import Tool
+    except ImportError:
+        from langchain.tools import Tool
+
+    conn = connection or AIContextDBConnection(namespace=namespace)
+    ctx = ToolContext(conn=conn, agent_id="langgraph", agent_name="langgraph")
+
+    cats = categories or ["graph", "context", "task"]
+    tools = []
+    for td in ToolRegistry.by_category(*cats):
+        def _handler(input_str, _td=td, _ctx=ctx):
+            try:
+                args = json.loads(input_str) if input_str.startswith("{") else {}
+            except (json.JSONDecodeError, AttributeError):
+                args = {td.params[0].name: input_str} if td.params else {}
+            return _td.handler(_ctx, **args)
+
+        tools.append(Tool(name=td.name, func=_handler, description=td.description))
+    return tools

contextsynapse/adapters/llamaindex/__init__.py

@@ -0,0 +1,4 @@
+"""LlamaIndex adapter for AIContextDB."""
+from .tools import create_llamaindex_tools, AIContextDBQueryTool
+
+__all__ = ["create_llamaindex_tools", "AIContextDBQueryTool"]

contextsynapse/adapters/llamaindex/tools.py

@@ -0,0 +1,64 @@
+"""
+LlamaIndex adapter — thin wrapper over Universal Tool Layer.
+
+Usage:
+    from contextsynapse.adapters.llamaindex.tools import create_llamaindex_tools
+    tools = create_llamaindex_tools(namespace="my-project")
+"""
+
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+from contextsynapse.tools import ToolRegistry, ToolContext
+from contextsynapse.adapters._base import AIContextDBConnection
+
+
+def create_llamaindex_tools(
+    namespace: str = "default",
+    connection: Optional[AIContextDBConnection] = None,
+    categories: Optional[List[str]] = None,
+) -> list:
+    """Create LlamaIndex-compatible tools from the Universal Tool Registry."""
+    try:
+        from llama_index.core.tools import FunctionTool
+    except ImportError:
+        # Fallback: return callables
+        return _create_callable_tools(namespace, connection, categories)
+
+    conn = connection or AIContextDBConnection(namespace=namespace)
+    ctx = ToolContext(conn=conn, agent_id="llamaindex", agent_name="llamaindex")
+
+    cats = categories or ["graph", "context", "task"]
+    tools = []
+    for td in ToolRegistry.by_category(*cats):
+        def _fn(input_str="", _td=td, _ctx=ctx, **kwargs):
+            if kwargs:
+                return _td.handler(_ctx, **kwargs)
+            try:
+                args = json.loads(input_str) if input_str else {}
+            except (json.JSONDecodeError, AttributeError):
+                args = {_td.params[0].name: input_str} if _td.params else {}
+            return _td.handler(_ctx, **args)
+
+        _fn.__name__ = td.name
+        _fn.__doc__ = td.description
+        tools.append(FunctionTool.from_defaults(fn=_fn, name=td.name, description=td.description))
+    return tools
+
+
+def _create_callable_tools(namespace, connection, categories):
+    """Fallback when llama_index is not installed."""
+    conn = connection or AIContextDBConnection(namespace=namespace)
+    ctx = ToolContext(conn=conn, agent_id="llamaindex", agent_name="llamaindex")
+    cats = categories or ["graph", "context", "task"]
+
+    tools = []
+    for td in ToolRegistry.by_category(*cats):
+        def _fn(_td=td, _ctx=ctx, **kwargs):
+            return _td.handler(_ctx, **kwargs)
+        _fn.__name__ = td.name
+        _fn.__doc__ = td.description
+        tools.append(_fn)
+    return tools

contextsynapse/adapters/openai/__init__.py

@@ -0,0 +1,24 @@
+"""
+AIContextDB OpenAI / Codex Adapter
+===================================
+Provides OpenAI function-calling tool schemas and a dispatcher so any
+OpenAI-powered agent (Codex, GPT-4, Assistants API) can read/write
+the same shared graph that Claude accesses via MCP.
+
+Requirements:
+    pip install openai  # optional — only needed for the bridge runner
+"""
+
+from .tools import (
+    configure,
+    create_openai_tools,
+    dispatch_tool_call,
+    init_project,
+)
+
+__all__ = [
+    "configure",
+    "create_openai_tools",
+    "dispatch_tool_call",
+    "init_project",
+]