copass-langchain 0.1.0__tar.gz

copass_langchain-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+coverage/
+
+# Lerna
+lerna-debug.log
+.nx/cache
+.nx/workspace-data
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+venv/
+.olane

copass_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: copass-langchain
+Version: 0.1.0
+Summary: LangChain tool adapters for Copass — drop-in discover/interpret/search tools for LangChain agents
+Project-URL: Homepage, https://github.com/olane-labs/copass-harness
+Project-URL: Repository, https://github.com/olane-labs/copass-harness.git
+Author: Olane Inc.
+License: MIT
+Keywords: agent,copass,knowledge-graph,langchain,langgraph,rag,tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: copass-config>=0.1.0
+Requires-Dist: copass-core>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: pydantic>=2.7
+Provides-Extra: agent
+Requires-Dist: langgraph>=0.2; extra == 'agent'
+Provides-Extra: dev
+Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copass-langchain
+
+LangChain tool adapters for Copass. Python mirror of [`@copass/langchain`](../../typescript/packages/langchain). Pulls `discover` / `interpret` / `search` into any LangChain agent, and (optionally) wires them into LangGraph's ReAct prebuilt.
+
+## Install
+
+```bash
+pip install copass-langchain
+# or, with the create_copass_agent convenience wrapper:
+pip install copass-langchain[agent]
+```
+
+Depends on `copass-core` + `copass-config` + `langchain-core`. `langgraph` is optional — only needed for `create_copass_agent`.
+
+## Drop-in tools
+
+```python
+from copass_core import ApiKeyAuth, CopassClient
+from copass_langchain import copass_tools
+
+client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+
+tools = copass_tools(client=client, sandbox_id="sb_...")
+# Pass `tools.all()` (a list of three StructuredTool instances) to your
+# agent framework, or pull them individually:
+# tools.discover, tools.interpret, tools.search
+```
+
+Tool descriptions and parameter descriptions come from `copass-config` — identical to the strings used across every other Copass adapter.
+
+## Window-aware retrieval (when a Context Window exists)
+
+`copass-core` v0.1 does not yet ship a `ContextWindow` class (deferred to v0.2). Until then, `copass_tools` and `CopassWindowCallback` accept any object satisfying `ContextWindowLike`:
+
+```python
+class ContextWindowLike(Protocol):
+    def get_turns(self) -> list[ChatMessage]: ...
+    def add_turn(self, turn: ChatMessage) -> Awaitable[None]: ...
+```
+
+When `copass-core` ships `ContextWindow`, it will satisfy this protocol and window-aware retrieval will light up without any consumer changes.
+
+## Full agent in one call
+
+```python
+from copass_langchain import create_copass_agent
+from langchain_anthropic import ChatAnthropic
+
+agent = create_copass_agent(
+    client=client,
+    sandbox_id="sb_...",
+    llm=ChatAnthropic(model="claude-opus-4-7"),
+    # window=my_window,  # optional — enables window-aware retrieval + auto-mirroring
+)
+
+result = await agent.ainvoke({
+    "messages": [("user", "why is checkout flaky?")]
+})
+```
+
+## Status
+
+- `copass_tools` — shipped.
+- `CopassWindowCallback` — shipped (generic on `ContextWindowLike`).
+- `create_copass_agent` — shipped (lazy-imports `langgraph`).
+- First-class `ContextWindow` integration — lands when `copass-core` v0.2 ships the primitive.
+
+## License
+
+MIT.

copass_langchain-0.1.0/README.md

@@ -0,0 +1,70 @@
+# copass-langchain
+
+LangChain tool adapters for Copass. Python mirror of [`@copass/langchain`](../../typescript/packages/langchain). Pulls `discover` / `interpret` / `search` into any LangChain agent, and (optionally) wires them into LangGraph's ReAct prebuilt.
+
+## Install
+
+```bash
+pip install copass-langchain
+# or, with the create_copass_agent convenience wrapper:
+pip install copass-langchain[agent]
+```
+
+Depends on `copass-core` + `copass-config` + `langchain-core`. `langgraph` is optional — only needed for `create_copass_agent`.
+
+## Drop-in tools
+
+```python
+from copass_core import ApiKeyAuth, CopassClient
+from copass_langchain import copass_tools
+
+client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+
+tools = copass_tools(client=client, sandbox_id="sb_...")
+# Pass `tools.all()` (a list of three StructuredTool instances) to your
+# agent framework, or pull them individually:
+# tools.discover, tools.interpret, tools.search
+```
+
+Tool descriptions and parameter descriptions come from `copass-config` — identical to the strings used across every other Copass adapter.
+
+## Window-aware retrieval (when a Context Window exists)
+
+`copass-core` v0.1 does not yet ship a `ContextWindow` class (deferred to v0.2). Until then, `copass_tools` and `CopassWindowCallback` accept any object satisfying `ContextWindowLike`:
+
+```python
+class ContextWindowLike(Protocol):
+    def get_turns(self) -> list[ChatMessage]: ...
+    def add_turn(self, turn: ChatMessage) -> Awaitable[None]: ...
+```
+
+When `copass-core` ships `ContextWindow`, it will satisfy this protocol and window-aware retrieval will light up without any consumer changes.
+
+## Full agent in one call
+
+```python
+from copass_langchain import create_copass_agent
+from langchain_anthropic import ChatAnthropic
+
+agent = create_copass_agent(
+    client=client,
+    sandbox_id="sb_...",
+    llm=ChatAnthropic(model="claude-opus-4-7"),
+    # window=my_window,  # optional — enables window-aware retrieval + auto-mirroring
+)
+
+result = await agent.ainvoke({
+    "messages": [("user", "why is checkout flaky?")]
+})
+```
+
+## Status
+
+- `copass_tools` — shipped.
+- `CopassWindowCallback` — shipped (generic on `ContextWindowLike`).
+- `create_copass_agent` — shipped (lazy-imports `langgraph`).
+- First-class `ContextWindow` integration — lands when `copass-core` v0.2 ships the primitive.
+
+## License
+
+MIT.

copass_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-langchain"
+version = "0.1.0"
+description = "LangChain tool adapters for Copass — drop-in discover/interpret/search tools for LangChain agents"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = ["copass", "knowledge-graph", "langchain", "langgraph", "agent", "tools", "rag"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "copass-core>=0.1.0",
+    "copass-config>=0.1.0",
+    "langchain-core>=0.3",
+    "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+agent = [
+    "langgraph>=0.2",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.5",
+    "langgraph>=0.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/olane-labs/copass-harness"
+Repository = "https://github.com/olane-labs/copass-harness.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copass_langchain"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["copass_langchain"]

copass_langchain-0.1.0/src/copass_langchain/__init__.py

@@ -0,0 +1,47 @@
+"""LangChain adapters for Copass.
+
+Python mirror of ``@copass/langchain``. Three entry points:
+
+- :func:`copass_tools` — bundle of LangChain ``StructuredTool``
+  instances for the three Copass retrieval endpoints
+  (``discover`` / ``interpret`` / ``search``).
+- :class:`CopassWindowCallback` — a
+  ``langchain_core.callbacks.BaseCallbackHandler`` that auto-mirrors
+  a chat model's conversation into a Copass Context Window.
+- :func:`create_copass_agent` — convenience factory wiring tools +
+  callback into ``langgraph.prebuilt.create_react_agent``. Requires
+  the ``[agent]`` extra.
+
+The ``ContextWindow`` primitive is deferred in ``copass-core`` v0.1 —
+until then, :class:`CopassWindowCallback` and :func:`create_copass_agent`
+accept any object satisfying :class:`ContextWindowLike` (``get_turns()``
++ async ``add_turn()``). When ``copass-core`` v0.2 lands
+``ContextWindow``, it will satisfy the protocol without changes here.
+"""
+
+from copass_langchain.callback import CopassWindowCallback
+from copass_langchain.tools import CopassTools, copass_tools
+from copass_langchain.types import ContextWindowLike
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> object:
+    """Lazy-import :func:`create_copass_agent` so importing the
+    package does not pull ``langgraph`` unless the caller actually
+    uses the helper."""
+    if name == "create_copass_agent":
+        from copass_langchain.agent import create_copass_agent
+
+        return create_copass_agent
+    raise AttributeError(f"module 'copass_langchain' has no attribute {name!r}")
+
+
+__all__ = [
+    "__version__",
+    "copass_tools",
+    "CopassTools",
+    "CopassWindowCallback",
+    "ContextWindowLike",
+    "create_copass_agent",
+]

copass_langchain-0.1.0/src/copass_langchain/agent.py

@@ -0,0 +1,110 @@
+"""Convenience factory for a Copass-wired LangGraph ReAct agent.
+
+Python mirror of ``typescript/packages/langchain/src/agent.ts`` — wires
+:func:`copass_tools` + :class:`CopassWindowCallback` (when a window is
+supplied) into ``langgraph.prebuilt.create_react_agent``. Returns the
+agent with the callback pre-bound via ``agent.with_config(...)``.
+
+``langgraph`` is an **optional** dependency — install with
+``pip install copass-langchain[agent]`` to use :func:`create_copass_agent`.
+The core :func:`copass_tools` + :class:`CopassWindowCallback` exports
+work without it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from copass_core import CopassClient, SearchPreset
+
+from copass_langchain.callback import CopassWindowCallback
+from copass_langchain.tools import copass_tools
+from copass_langchain.types import ContextWindowLike
+
+
+def create_copass_agent(
+    *,
+    client: CopassClient,
+    sandbox_id: str,
+    llm: Any,
+    window: Optional[ContextWindowLike] = None,
+    tools: Optional[List[Any]] = None,
+    project_id: Optional[str] = None,
+    preset: SearchPreset = "auto",
+    include_tool_messages: bool = False,
+    **react_agent_options: Any,
+) -> Any:
+    """Build a LangGraph ReAct agent pre-wired with Copass retrieval.
+
+    Args:
+        client: Authenticated :class:`CopassClient`.
+        sandbox_id: Sandbox every retrieval call runs against.
+        llm: A LangChain chat model instance (``ChatAnthropic(...)``,
+            ``ChatOpenAI(...)``, etc.).
+        window: Optional :class:`ContextWindowLike`. When supplied, a
+            :class:`CopassWindowCallback` is bound so conversation
+            history auto-mirrors into the window and retrieval
+            becomes window-aware.
+        tools: Additional tools to mix in alongside the three Copass
+            retrieval tools.
+        project_id: Optional project narrowing for retrieval.
+        preset: Preset for ``interpret`` / ``search``.
+        include_tool_messages: Whether :class:`CopassWindowCallback`
+            mirrors tool-result messages. Default ``False``.
+        **react_agent_options: Forwarded to
+            ``langgraph.prebuilt.create_react_agent`` (e.g.,
+            ``checkpointer``, ``state_schema``, ``prompt``).
+
+    Returns:
+        A LangChain ``Runnable`` — call ``.ainvoke({"messages": [...]})``.
+
+    Raises:
+        ImportError: If ``langgraph`` isn't installed. Install with
+            ``pip install copass-langchain[agent]``.
+
+    Example::
+
+        from copass_core import ApiKeyAuth, CopassClient
+        from copass_langchain import create_copass_agent
+        from langchain_anthropic import ChatAnthropic
+
+        client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+        agent = create_copass_agent(
+            client=client,
+            sandbox_id="sb_...",
+            llm=ChatAnthropic(model="claude-opus-4-7"),
+        )
+        result = await agent.ainvoke(
+            {"messages": [("user", "why is checkout flaky?")]},
+        )
+    """
+    try:
+        from langgraph.prebuilt import create_react_agent
+    except ImportError as e:
+        raise ImportError(
+            "create_copass_agent requires `langgraph`. Install with "
+            "`pip install copass-langchain[agent]`."
+        ) from e
+
+    copass = copass_tools(
+        client=client,
+        sandbox_id=sandbox_id,
+        project_id=project_id,
+        window=window,
+        preset=preset,
+    )
+
+    all_tools: List[Any] = copass.all() + list(tools or [])
+    agent = create_react_agent(model=llm, tools=all_tools, **react_agent_options)
+
+    if window is not None:
+        callback = CopassWindowCallback(
+            window=window,
+            include_tool_messages=include_tool_messages,
+        )
+        return agent.with_config({"callbacks": [callback]})
+
+    return agent
+
+
+__all__ = ["create_copass_agent"]

copass_langchain-0.1.0/src/copass_langchain/callback.py

@@ -0,0 +1,158 @@
+"""LangChain callback that mirrors chat-model messages into a Copass
+Context Window.
+
+Python mirror of
+``typescript/packages/langchain/src/callback.ts``. Hooks
+``on_chat_model_start`` (fired by every chat-model invocation with
+the full message history) and walks messages, calling ``add_turn`` on
+the window for any message we haven't seen before. Retrieval tools
+invoked inside the same agent step then see a window that reflects
+the actual conversation, not an empty buffer.
+
+Works against any object satisfying :class:`ContextWindowLike` — the
+v0.2 ``copass-core.ContextWindow`` will slot in without changes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional, Set
+from uuid import UUID
+
+from copass_core import ChatMessage, ChatRole
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+
+from copass_langchain.types import ContextWindowLike
+
+
+class CopassWindowCallback(BaseCallbackHandler):
+    """Auto-mirror a chat model's conversation into a Copass
+    :class:`ContextWindowLike`.
+
+    Usage::
+
+        from copass_langchain import CopassWindowCallback
+        agent = create_react_agent(llm=..., tools=...)
+        await agent.ainvoke(
+            {"messages": [...]},
+            config={"callbacks": [CopassWindowCallback(window=window)]},
+        )
+
+    ``include_tool_messages`` defaults to ``False``. Tool results tend
+    to be noisy; enable only if your agent's tool outputs carry
+    conceptual content you want retrieval to dedupe against.
+    """
+
+    name = "copass-window"
+
+    def __init__(
+        self,
+        *,
+        window: ContextWindowLike,
+        include_tool_messages: bool = False,
+    ) -> None:
+        super().__init__()
+        self._window = window
+        self._include_tool_messages = include_tool_messages
+        self._seen: Set[str] = {
+            _hash_turn(turn) for turn in window.get_turns()
+        }
+
+    async def on_chat_model_start(
+        self,
+        serialized: Dict[str, Any],
+        messages: List[List[BaseMessage]],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Fires before every chat model call. ``messages`` is
+        ``List[List[BaseMessage]]`` for batched-call support; in
+        single-agent loops it's always one conversation."""
+        flat: List[BaseMessage] = []
+        for conversation in messages:
+            flat.extend(conversation)
+
+        for msg in flat:
+            turn = _to_turn(msg, self._include_tool_messages)
+            if turn is None:
+                continue
+
+            key = _hash_turn(turn)
+            if key in self._seen:
+                continue
+            self._seen.add(key)
+
+            # Fire-and-forget. We don't block the model call on
+            # ingestion latency; missing a turn is recoverable
+            # (retrieval still sees already-added turns).
+            asyncio.create_task(_safe_add_turn(self._window, turn))
+
+
+async def _safe_add_turn(window: ContextWindowLike, turn: ChatMessage) -> None:
+    try:
+        await window.add_turn(turn)
+    except Exception:  # noqa: BLE001 — swallowed intentionally.
+        # Ingestion is best-effort. Future releases may surface via
+        # an optional ``on_error`` callback.
+        pass
+
+
+def _to_turn(msg: BaseMessage, include_tool_messages: bool) -> Optional[ChatMessage]:
+    role = _role_from_message(msg, include_tool_messages)
+    if role is None:
+        return None
+    content = _content_to_string(msg.content)
+    if not content.strip():
+        return None
+    return ChatMessage(role=role, content=content)
+
+
+def _role_from_message(msg: BaseMessage, include_tool_messages: bool) -> Optional[ChatRole]:
+    if isinstance(msg, HumanMessage):
+        return "user"
+    if isinstance(msg, AIMessage):
+        return "assistant"
+    if isinstance(msg, SystemMessage):
+        return "system"
+    if isinstance(msg, ToolMessage):
+        return "system" if include_tool_messages else None
+    return None
+
+
+def _content_to_string(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: List[str] = []
+        for part in content:
+            if isinstance(part, str):
+                parts.append(part)
+            elif isinstance(part, dict):
+                text = part.get("text")
+                if text:
+                    parts.append(str(text))
+        return "\n".join(p for p in parts if p)
+    if content is None:
+        return ""
+    return str(content)
+
+
+def _hash_turn(turn: ChatMessage) -> str:
+    # Stable-ish hash: role + first 500 chars of content. Same policy
+    # as the TS sibling — collisions across different long messages
+    # starting identically are accepted as benign.
+    return f"{turn.role}:{turn.content[:500]}"
+
+
+__all__ = ["CopassWindowCallback"]

copass_langchain-0.1.0/src/copass_langchain/tools.py

@@ -0,0 +1,162 @@
+"""LangChain tool adapters for Copass retrieval.
+
+Python mirror of ``typescript/packages/langchain/src/tools.ts`` — uses
+``StructuredTool.from_function`` (the LangChain-python equivalent of
+the TS ``tool()`` factory) so tool names + descriptions come
+programmatically from ``copass-config``.
+
+The three returned tools — ``discover``, ``interpret``, ``search`` —
+are window-aware when a ``window`` is supplied: the server will
+exclude items already surfaced earlier in the conversation. Keeps
+repeated ``discover`` calls cheap and productive.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from copass_config import (
+    DISCOVER_DESCRIPTION,
+    DISCOVER_QUERY_PARAM,
+    INTERPRET_DESCRIPTION,
+    INTERPRET_ITEMS_PARAM,
+    INTERPRET_QUERY_PARAM,
+    SEARCH_DESCRIPTION,
+    SEARCH_QUERY_PARAM,
+)
+from copass_core import CopassClient, SearchPreset
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+
+from copass_langchain.types import ContextWindowLike
+
+
+@dataclass(frozen=True)
+class CopassTools:
+    """Bundle of the three Copass retrieval tools as
+    ``StructuredTool`` instances. Pass ``tools.discover``,
+    ``tools.interpret``, ``tools.search`` (or ``tools.all()``) to the
+    agent framework."""
+
+    discover: StructuredTool
+    interpret: StructuredTool
+    search: StructuredTool
+
+    def all(self) -> List[StructuredTool]:
+        return [self.discover, self.interpret, self.search]
+
+
+class _DiscoverArgs(BaseModel):
+    query: str = Field(..., description=DISCOVER_QUERY_PARAM)
+
+
+class _InterpretArgs(BaseModel):
+    query: str = Field(..., description=INTERPRET_QUERY_PARAM)
+    items: List[List[str]] = Field(
+        ...,
+        min_length=1,
+        description=INTERPRET_ITEMS_PARAM,
+    )
+
+
+class _SearchArgs(BaseModel):
+    query: str = Field(..., description=SEARCH_QUERY_PARAM)
+
+
+def copass_tools(
+    *,
+    client: CopassClient,
+    sandbox_id: str,
+    project_id: Optional[str] = None,
+    window: Optional[ContextWindowLike] = None,
+    preset: SearchPreset = "auto",
+) -> CopassTools:
+    """Return a :class:`CopassTools` bundle wired to ``client``.
+
+    Args:
+        client: Authenticated :class:`CopassClient`.
+        sandbox_id: Sandbox every retrieval call runs against.
+        project_id: Optional project narrowing.
+        window: Optional :class:`ContextWindowLike` — when provided,
+            every retrieval call is window-aware.
+        preset: Retrieval preset for ``interpret`` / ``search``.
+            Ignored by ``discover``. Defaults to ``"auto"`` —
+            ``interpret`` requires ``auto`` in the current server
+            release (``fast`` silently returns
+            "No supporting context could be retrieved").
+
+    Example::
+
+        from copass_core import CopassClient, ApiKeyAuth
+        from copass_langchain import copass_tools
+
+        client = CopassClient(auth=ApiKeyAuth(key="olk_..."))
+        tools = copass_tools(client=client, sandbox_id="sb_...")
+        # Hand `tools.all()` to LangGraph's create_react_agent.
+    """
+
+    async def _discover(query: str) -> Dict[str, Any]:
+        response = await client.retrieval.discover(
+            sandbox_id=sandbox_id,
+            query=query,
+            project_id=project_id,
+            window=window,
+        )
+        return {
+            "header": response.get("header", ""),
+            "items": [
+                {
+                    "score": item.get("score"),
+                    "summary": item.get("summary"),
+                    "canonical_ids": item.get("canonical_ids", []),
+                }
+                for item in response.get("items", [])
+            ],
+            "next_steps": response.get("next_steps", ""),
+        }
+
+    async def _interpret(query: str, items: List[List[str]]) -> Dict[str, Any]:
+        response = await client.retrieval.interpret(
+            sandbox_id=sandbox_id,
+            query=query,
+            items=items,
+            project_id=project_id,
+            window=window,
+            preset=preset,
+        )
+        return {"brief": response.get("brief", "")}
+
+    async def _search(query: str) -> Dict[str, Any]:
+        response = await client.retrieval.search(
+            sandbox_id=sandbox_id,
+            query=query,
+            project_id=project_id,
+            window=window,
+            preset=preset,
+        )
+        return {"answer": response.get("answer", "")}
+
+    return CopassTools(
+        discover=StructuredTool.from_function(
+            coroutine=_discover,
+            name="discover",
+            description=DISCOVER_DESCRIPTION,
+            args_schema=_DiscoverArgs,
+        ),
+        interpret=StructuredTool.from_function(
+            coroutine=_interpret,
+            name="interpret",
+            description=INTERPRET_DESCRIPTION,
+            args_schema=_InterpretArgs,
+        ),
+        search=StructuredTool.from_function(
+            coroutine=_search,
+            name="search",
+            description=SEARCH_DESCRIPTION,
+            args_schema=_SearchArgs,
+        ),
+    )
+
+
+__all__ = ["CopassTools", "copass_tools"]

copass_langchain-0.1.0/src/copass_langchain/types.py

@@ -0,0 +1,32 @@
+"""Structural types local to ``copass-langchain``.
+
+Kept here (rather than in ``copass-core``) because they shim a
+behavior ``copass-core`` v0.1.0 hasn't shipped yet —
+``ContextWindow.add_turn(...)``. Once ``copass-core`` v0.2 ports the
+``ContextWindow`` primitive from TS, the real class will satisfy this
+protocol and this shim disappears.
+"""
+
+from __future__ import annotations
+
+from typing import Awaitable, List, Protocol, runtime_checkable
+
+from copass_core import ChatMessage
+
+
+@runtime_checkable
+class ContextWindowLike(Protocol):
+    """Minimum surface ``CopassWindowCallback`` + ``copass_tools``
+    need from a "window" object.
+
+    A future ``copass-core.ContextWindow`` will satisfy this directly.
+    Callers holding any other turn-log structure can supply an adapter
+    that exposes these two methods.
+    """
+
+    def get_turns(self) -> List[ChatMessage]: ...
+
+    def add_turn(self, turn: ChatMessage) -> Awaitable[None]: ...
+
+
+__all__ = ["ContextWindowLike"]

copass_langchain-0.1.0/tests/test_callback.py

@@ -0,0 +1,150 @@
+"""CopassWindowCallback — message → turn translation + dedup."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import List
+
+import pytest
+from copass_core import ChatMessage
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+from uuid import uuid4
+
+from copass_langchain import CopassWindowCallback
+
+
+class _Window:
+    """Minimal ContextWindowLike stub — captures add_turn calls."""
+
+    def __init__(self, initial: List[ChatMessage] = None) -> None:
+        self._turns = list(initial or [])
+        self.added: List[ChatMessage] = []
+
+    def get_turns(self) -> List[ChatMessage]:
+        return list(self._turns)
+
+    async def add_turn(self, turn: ChatMessage) -> None:
+        self.added.append(turn)
+        self._turns.append(turn)
+
+
+async def _trigger(cb: CopassWindowCallback, messages: List[List]) -> None:
+    await cb.on_chat_model_start(
+        serialized={},
+        messages=messages,
+        run_id=uuid4(),
+    )
+    # Callback schedules fire-and-forget tasks; yield so they run.
+    await asyncio.sleep(0)
+    await asyncio.sleep(0)
+
+
+async def test_mirrors_human_and_ai_messages() -> None:
+    w = _Window()
+    cb = CopassWindowCallback(window=w)
+    await _trigger(
+        cb,
+        [
+            [
+                HumanMessage(content="hello"),
+                AIMessage(content="hi there"),
+            ]
+        ],
+    )
+    roles = [t.role for t in w.added]
+    contents = [t.content for t in w.added]
+    assert roles == ["user", "assistant"]
+    assert contents == ["hello", "hi there"]
+
+
+async def test_deduplicates_previously_seen_turns() -> None:
+    existing = [ChatMessage(role="user", content="hello")]
+    w = _Window(initial=existing)
+    cb = CopassWindowCallback(window=w)
+    await _trigger(
+        cb,
+        [
+            [
+                HumanMessage(content="hello"),  # already in window → skip
+                AIMessage(content="hi there"),  # new
+            ]
+        ],
+    )
+    assert [t.role for t in w.added] == ["assistant"]
+
+
+async def test_skips_tool_messages_by_default() -> None:
+    w = _Window()
+    cb = CopassWindowCallback(window=w)
+    await _trigger(
+        cb,
+        [
+            [
+                HumanMessage(content="query"),
+                ToolMessage(content="tool output", tool_call_id="t1"),
+            ]
+        ],
+    )
+    assert [t.role for t in w.added] == ["user"]
+
+
+async def test_includes_tool_messages_when_opted_in() -> None:
+    w = _Window()
+    cb = CopassWindowCallback(window=w, include_tool_messages=True)
+    await _trigger(
+        cb,
+        [
+            [
+                HumanMessage(content="query"),
+                ToolMessage(content="tool output", tool_call_id="t1"),
+            ]
+        ],
+    )
+    assert [t.role for t in w.added] == ["user", "system"]
+
+
+async def test_skips_empty_content() -> None:
+    w = _Window()
+    cb = CopassWindowCallback(window=w)
+    await _trigger(
+        cb,
+        [
+            [
+                HumanMessage(content=""),
+                HumanMessage(content="   "),
+                SystemMessage(content="you are helpful"),
+            ]
+        ],
+    )
+    assert [t.role for t in w.added] == ["system"]
+
+
+async def test_content_parts_list_concatenated() -> None:
+    w = _Window()
+    cb = CopassWindowCallback(window=w)
+    multi = HumanMessage(
+        content=[
+            {"type": "text", "text": "first line"},
+            {"type": "text", "text": "second line"},
+        ]
+    )
+    await _trigger(cb, [[multi]])
+    assert len(w.added) == 1
+    assert "first line" in w.added[0].content
+    assert "second line" in w.added[0].content
+
+
+async def test_swallows_add_turn_errors() -> None:
+    class _FailingWindow:
+        def get_turns(self) -> List[ChatMessage]:
+            return []
+
+        async def add_turn(self, turn: ChatMessage) -> None:
+            raise RuntimeError("graph write failed")
+
+    cb = CopassWindowCallback(window=_FailingWindow())
+    # Should NOT raise even though add_turn raises internally.
+    await _trigger(
+        cb,
+        [[HumanMessage(content="hello")]],
+    )

copass_langchain-0.1.0/tests/test_tools.py

@@ -0,0 +1,155 @@
+"""copass_tools — tool shape, argument schema, live-call wiring via
+mocked ``CopassClient``."""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+import httpx
+import pytest
+import respx
+from copass_config import (
+    DISCOVER_DESCRIPTION,
+    INTERPRET_DESCRIPTION,
+    SEARCH_DESCRIPTION,
+)
+from copass_core import ApiKeyAuth, ChatMessage, CopassClient
+
+from copass_langchain import CopassTools, copass_tools
+
+
+@pytest.fixture
+def client() -> CopassClient:
+    return CopassClient(
+        auth=ApiKeyAuth(key="olk_test"),
+        api_url="http://test",
+    )
+
+
+def test_returns_copass_tools_bundle(client: CopassClient) -> None:
+    tools = copass_tools(client=client, sandbox_id="sb-1")
+    assert isinstance(tools, CopassTools)
+    assert tools.discover.name == "discover"
+    assert tools.interpret.name == "interpret"
+    assert tools.search.name == "search"
+
+
+def test_descriptions_match_copass_config(client: CopassClient) -> None:
+    tools = copass_tools(client=client, sandbox_id="sb-1")
+    assert tools.discover.description == DISCOVER_DESCRIPTION
+    assert tools.interpret.description == INTERPRET_DESCRIPTION
+    assert tools.search.description == SEARCH_DESCRIPTION
+
+
+def test_tools_all_returns_three(client: CopassClient) -> None:
+    tools = copass_tools(client=client, sandbox_id="sb-1")
+    assert len(tools.all()) == 3
+
+
+@respx.mock
+async def test_discover_hits_correct_endpoint(client: CopassClient) -> None:
+    route = respx.post("http://test/api/v1/query/sandboxes/sb-1/discover").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "header": "hits",
+                "items": [
+                    {"score": 0.9, "summary": "summary-1", "canonical_ids": ["a", "b"]},
+                ],
+                "count": 1,
+                "sandbox_id": "sb-1",
+                "query": "auth",
+                "next_steps": "interpret one",
+            },
+        )
+    )
+    tools = copass_tools(client=client, sandbox_id="sb-1")
+    result = await tools.discover.ainvoke({"query": "auth"})
+    assert route.called
+    assert result["header"] == "hits"
+    assert len(result["items"]) == 1
+    assert result["items"][0]["canonical_ids"] == ["a", "b"]
+
+
+@respx.mock
+async def test_interpret_forwards_items_and_preset(client: CopassClient) -> None:
+    route = respx.post("http://test/api/v1/query/sandboxes/sb-1/interpret").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "brief": "synthesized answer",
+                "citations": [],
+                "items": [["a"]],
+                "sandbox_id": "sb-1",
+                "query": "q",
+            },
+        )
+    )
+    tools = copass_tools(client=client, sandbox_id="sb-1", preset="fast")
+    result = await tools.interpret.ainvoke(
+        {"query": "q", "items": [["a", "b"]]},
+    )
+    assert result == {"brief": "synthesized answer"}
+    import json as _json
+
+    body = _json.loads(route.calls.last.request.content)
+    assert body["items"] == [["a", "b"]]
+    assert body["preset"] == "fast"
+
+
+@respx.mock
+async def test_search_wraps_response(client: CopassClient) -> None:
+    respx.post("http://test/api/v1/query/sandboxes/sb-1/search").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "answer": "Because the /checkout worker was pinned to 1 replica.",
+                "preset": "auto",
+                "execution_time_ms": 200,
+                "sandbox_id": "sb-1",
+                "query": "checkout flaky",
+            },
+        )
+    )
+    tools = copass_tools(client=client, sandbox_id="sb-1")
+    result = await tools.search.ainvoke({"query": "checkout flaky"})
+    assert "checkout worker" in result["answer"]
+
+
+@respx.mock
+async def test_window_turns_sent_as_history(client: CopassClient) -> None:
+    class _Window:
+        def __init__(self) -> None:
+            self._turns: List[ChatMessage] = [
+                ChatMessage(role="user", content="earlier user message"),
+                ChatMessage(role="assistant", content="earlier assistant reply"),
+            ]
+
+        def get_turns(self) -> List[ChatMessage]:
+            return list(self._turns)
+
+        async def add_turn(self, turn: ChatMessage) -> None:  # pragma: no cover
+            self._turns.append(turn)
+
+    route = respx.post("http://test/api/v1/query/sandboxes/sb-1/discover").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "header": "",
+                "items": [],
+                "count": 0,
+                "sandbox_id": "sb-1",
+                "query": "q",
+                "next_steps": "",
+            },
+        )
+    )
+    tools = copass_tools(client=client, sandbox_id="sb-1", window=_Window())
+    await tools.discover.ainvoke({"query": "q"})
+    import json as _json
+
+    body = _json.loads(route.calls.last.request.content)
+    assert body["history"] == [
+        {"role": "user", "content": "earlier user message"},
+        {"role": "assistant", "content": "earlier assistant reply"},
+    ]