contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/adapters/langchain/retriever.py

@@ -0,0 +1,158 @@
+"""
+LangChain Retriever backed by AIContextDB graph data.
+
+Converts graph nodes into LangChain Documents for use in RAG chains.
+
+Usage:
+    from contextsynapse.adapters.langchain import AIContextDBRetriever
+
+    retriever = AIContextDBRetriever(namespace="knowledge")
+    docs = retriever.invoke("Alice")
+    # Or in a chain:
+    chain = retriever | llm | output_parser
+"""
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import Field
+
+from .._base import AIContextDBConnection
+
+logger = logging.getLogger(__name__)
+
+
+class AIContextDBRetriever(BaseRetriever):
+    """
+    Retrieve LangChain Documents from AIContextDB graph nodes.
+
+    Supports:
+    - Text search across node properties
+    - Label filtering
+    - AIQL query-based retrieval
+    - Optional daemon context merging
+    """
+
+    connection: Any = Field(default=None, exclude=True)
+    namespace: str = "default"
+    node_labels: Optional[List[str]] = None
+    max_results: int = 20
+    search_properties: List[str] = Field(default_factory=lambda: ["name", "content", "description", "title", "text"])
+    include_daemon_context: bool = False
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.connection is None:
+            self.connection = AIContextDBConnection(namespace=self.namespace)
+
+    def _get_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: Optional[CallbackManagerForRetrieverRun] = None,
+    ) -> List[Document]:
+        """Retrieve documents matching the query."""
+        nodes = self.connection.get_nodes()
+        query_lower = query.lower()
+
+        scored: List[tuple] = []
+        for node in nodes:
+            # Filter by label if specified
+            if self.node_labels and node.label not in self.node_labels:
+                continue
+
+            # Score by matching against searchable properties
+            score = self._score_node(node, query_lower)
+            if score > 0:
+                scored.append((score, node))
+
+        # Sort by score descending, take top results
+        scored.sort(key=lambda x: x[0], reverse=True)
+        top_nodes = [node for _, node in scored[:self.max_results]]
+
+        # If no matches found, return all nodes (up to limit) as fallback
+        if not top_nodes:
+            if self.node_labels:
+                top_nodes = [n for n in nodes if n.label in self.node_labels][:self.max_results]
+            else:
+                top_nodes = nodes[:self.max_results]
+
+        documents = [self._node_to_document(node) for node in top_nodes]
+
+        # Optionally append daemon context as a document
+        if self.include_daemon_context and self.connection.daemon_url:
+            daemon_doc = self._get_daemon_document()
+            if daemon_doc:
+                documents.append(daemon_doc)
+
+        return documents
+
+    def _score_node(self, node, query_lower: str) -> float:
+        """Score a node against a search query. Higher = better match."""
+        score = 0.0
+        props = node.properties or {}
+
+        for prop_name in self.search_properties:
+            val = props.get(prop_name)
+            if isinstance(val, str):
+                val_lower = val.lower()
+                if query_lower == val_lower:
+                    score += 10.0  # exact match
+                elif query_lower in val_lower:
+                    score += 5.0   # substring match
+                else:
+                    # Word-level overlap
+                    query_words = set(query_lower.split())
+                    val_words = set(val_lower.split())
+                    overlap = query_words & val_words
+                    if overlap:
+                        score += len(overlap) * 2.0
+
+        # Bonus for label match
+        if query_lower in node.label.lower():
+            score += 3.0
+
+        return score
+
+    @staticmethod
+    def _node_to_document(node) -> Document:
+        """Convert a GraphNode to a LangChain Document."""
+        props = node.properties or {}
+
+        # Build page_content from meaningful properties
+        content_parts = [f"[{node.label}]"]
+        for key in ["name", "title", "content", "description", "text"]:
+            val = props.get(key)
+            if val:
+                content_parts.append(f"{key}: {val}")
+
+        # Add remaining properties
+        for key, val in props.items():
+            if key not in ("name", "title", "content", "description", "text", "domain"):
+                content_parts.append(f"{key}: {val}")
+
+        return Document(
+            page_content="\n".join(content_parts),
+            metadata={
+                "node_id": node.id,
+                "label": node.label,
+                **{k: v for k, v in props.items() if isinstance(v, (str, int, float, bool))},
+            },
+        )
+
+    def _get_daemon_document(self) -> Optional[Document]:
+        """Fetch daemon context as a single document."""
+        try:
+            hub = self.connection.build_context(include_daemon=True)
+            prompt = hub.to_prompt()
+            if prompt.strip():
+                return Document(
+                    page_content=prompt,
+                    metadata={"source": "daemon", "label": "DaemonContext"},
+                )
+        except Exception as exc:
+            logger.debug(f"Could not fetch daemon context: {exc}")
+        return None

contextsynapse/adapters/langchain/tools.py

@@ -0,0 +1,43 @@
+"""
+LangChain adapter — thin wrapper over Universal Tool Layer.
+
+Usage:
+    from contextsynapse.adapters.langchain.tools import create_langchain_tools
+    tools = create_langchain_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_langchain_tools(
+    namespace: str = "default",
+    connection: Optional[AIContextDBConnection] = None,
+    categories: Optional[List[str]] = None,
+) -> list:
+    """Create LangChain Tool objects 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="langchain", agent_name="langchain")
+
+    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/langgraph/__init__.py

@@ -0,0 +1,21 @@
+"""
+AIContextDB LangGraph Adapter
+=========================
+Provides graph-backed checkpoint saving, message history, and tools
+for LangGraph workflows.
+
+Requirements:
+    pip install langgraph langchain-core
+"""
+
+from .checkpoint import AIContextDBCheckpointSaver
+from .message_history import AIContextDBChatMessageHistory
+from .tools import create_graph_tools
+from .context_tools import create_context_tools
+
+__all__ = [
+    "AIContextDBCheckpointSaver",
+    "AIContextDBChatMessageHistory",
+    "create_graph_tools",
+    "create_context_tools",
+]

contextsynapse/adapters/langgraph/checkpoint.py

@@ -0,0 +1,223 @@
+"""
+LangGraph Checkpoint Saver backed by AIContextDB.
+
+Stores workflow checkpoints as graph nodes (label: LangGraphCheckpoint)
+with edges linking parent → child checkpoints. This means checkpoint
+lineage is queryable with AIQL — a unique advantage over SQLite/Postgres savers.
+
+Usage:
+    from contextsynapse.adapters.langgraph import AIContextDBCheckpointSaver
+
+    saver = AIContextDBCheckpointSaver(namespace="my_workflow")
+    graph = StateGraph(...)
+    compiled = graph.compile(checkpointer=saver)
+"""
+
+import json
+import uuid
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterator, Optional, Sequence, Tuple
+
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+)
+from langchain_core.runnables import RunnableConfig
+
+from .._base import AIContextDBConnection
+
+logger = logging.getLogger(__name__)
+
+# Node/edge labels used in the graph
+CHECKPOINT_LABEL = "LangGraphCheckpoint"
+CHECKPOINT_EDGE = "NEXT_CHECKPOINT"
+
+
+class AIContextDBCheckpointSaver(BaseCheckpointSaver):
+    """
+    Persist LangGraph checkpoints as nodes in AIContextDB.
+
+    Each checkpoint becomes a node with:
+        - label: "LangGraphCheckpoint"
+        - properties: thread_id, checkpoint_id, parent_id, state (JSON),
+                      metadata (JSON), timestamp
+
+    Parent → child relationships are stored as NEXT_CHECKPOINT edges,
+    making workflow lineage visible in graph queries.
+    """
+
+    def __init__(
+        self,
+        namespace: str = "langgraph_checkpoints",
+        connection: Optional[AIContextDBConnection] = None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.conn = connection or AIContextDBConnection(namespace=namespace)
+
+    # ------------------------------------------------------------------
+    # Required interface
+    # ------------------------------------------------------------------
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: Optional[dict] = None,
+    ) -> RunnableConfig:
+        """Save a checkpoint to the graph."""
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_id = checkpoint["id"]
+        parent_id = config["configurable"].get("checkpoint_id")
+
+        # Serialize state and metadata to JSON strings
+        node_props = {
+            "thread_id": thread_id,
+            "checkpoint_id": checkpoint_id,
+            "parent_id": parent_id or "",
+            "state": json.dumps(checkpoint, default=str),
+            "metadata": json.dumps(metadata, default=str) if metadata else "{}",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        if new_versions:
+            node_props["channel_versions"] = json.dumps(new_versions, default=str)
+
+        node = self.conn.add_node(CHECKPOINT_LABEL, node_props)
+
+        # Link to parent checkpoint if one exists
+        if parent_id:
+            parent_nodes = self.conn.get_nodes(
+                label=CHECKPOINT_LABEL,
+                where={"thread_id": thread_id, "checkpoint_id": parent_id},
+            )
+            if parent_nodes:
+                self.conn.add_edge(
+                    source=parent_nodes[0].id,
+                    target=node.id,
+                    label=CHECKPOINT_EDGE,
+                    properties={"thread_id": thread_id},
+                )
+
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_id": checkpoint_id,
+            }
+        }
+
+    def get_tuple(self, config: RunnableConfig) -> Optional[CheckpointTuple]:
+        """Retrieve the latest (or specific) checkpoint for a thread."""
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_id = config["configurable"].get("checkpoint_id")
+
+        nodes = self.conn.get_nodes(label=CHECKPOINT_LABEL, where={"thread_id": thread_id})
+        if not nodes:
+            return None
+
+        if checkpoint_id:
+            # Find specific checkpoint
+            matches = [n for n in nodes if n.properties.get("checkpoint_id") == checkpoint_id]
+            if not matches:
+                return None
+            node = matches[0]
+        else:
+            # Find latest by timestamp
+            nodes.sort(key=lambda n: n.properties.get("timestamp", ""), reverse=True)
+            node = nodes[0]
+
+        return self._node_to_tuple(node)
+
+    def list(
+        self,
+        config: Optional[RunnableConfig] = None,
+        *,
+        filter: Optional[Dict[str, Any]] = None,
+        before: Optional[RunnableConfig] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints for a thread, newest first."""
+        if config is None:
+            return
+
+        thread_id = config["configurable"]["thread_id"]
+        nodes = self.conn.get_nodes(label=CHECKPOINT_LABEL, where={"thread_id": thread_id})
+
+        # Sort by timestamp descending
+        nodes.sort(key=lambda n: n.properties.get("timestamp", ""), reverse=True)
+
+        # Apply 'before' filter
+        if before:
+            before_id = before["configurable"].get("checkpoint_id")
+            if before_id:
+                before_ts = None
+                for n in nodes:
+                    if n.properties.get("checkpoint_id") == before_id:
+                        before_ts = n.properties.get("timestamp")
+                        break
+                if before_ts:
+                    nodes = [n for n in nodes if n.properties.get("timestamp", "") < before_ts]
+
+        # Apply limit
+        if limit:
+            nodes = nodes[:limit]
+
+        for node in nodes:
+            tup = self._node_to_tuple(node)
+            if tup:
+                yield tup
+
+    # ------------------------------------------------------------------
+    # Async variants (delegate to sync for now)
+    # ------------------------------------------------------------------
+
+    async def aput(self, config, checkpoint, metadata, new_versions=None):
+        return self.put(config, checkpoint, metadata, new_versions)
+
+    async def aget_tuple(self, config):
+        return self.get_tuple(config)
+
+    async def alist(self, config=None, *, filter=None, before=None, limit=None):
+        for item in self.list(config, filter=filter, before=before, limit=limit):
+            yield item
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _node_to_tuple(self, node) -> Optional[CheckpointTuple]:
+        """Convert a graph node back to a CheckpointTuple."""
+        try:
+            props = node.properties
+            checkpoint = json.loads(props.get("state", "{}"))
+            metadata = json.loads(props.get("metadata", "{}"))
+            parent_id = props.get("parent_id", "")
+            thread_id = props.get("thread_id", "")
+
+            config = {
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_id": props.get("checkpoint_id", ""),
+                }
+            }
+            parent_config = None
+            if parent_id:
+                parent_config = {
+                    "configurable": {
+                        "thread_id": thread_id,
+                        "checkpoint_id": parent_id,
+                    }
+                }
+
+            return CheckpointTuple(
+                config=config,
+                checkpoint=checkpoint,
+                metadata=metadata,
+                parent_config=parent_config,
+            )
+        except Exception as exc:
+            logger.warning(f"Failed to deserialize checkpoint node {node.id}: {exc}")
+            return None