copass-config 0.1.0__tar.gz

copass_config-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_config-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: copass-config
+Version: 0.1.0
+Summary: Canonical tool descriptions, parameter descriptions, and system prompts shared across every Copass Python adapter
+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: config,copass,knowledge-graph,system-prompts,tool-descriptions
+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
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copass-config
+
+Canonical strings shared across every Python Copass adapter. Python mirror of [`@copass/config`](../../typescript/packages/config).
+
+This package owns the **single source of truth** (for Python) for:
+
+- Tool descriptions the LLM sees (`DISCOVER_DESCRIPTION`, `INTERPRET_DESCRIPTION`, `SEARCH_DESCRIPTION`, `MCP_DISCOVER_DESCRIPTION`)
+- Parameter descriptions (`DISCOVER_QUERY_PARAM`, `INTERPRET_ITEMS_PARAM`, etc.)
+- System prompts (`COPASS_AGENT_MCP_SYSTEM_PROMPT`, `COPASS_AGENT_SDK_SYSTEM_PROMPT`)
+
+Every Python Copass adapter (`copass-pydantic-ai`, `copass-langchain`, `copass-anthropic-agents`, etc.) imports from here so the LLM sees identical tool semantics regardless of framework wrapping.
+
+## Install
+
+```bash
+pip install copass-config
+```
+
+Zero runtime dependencies.
+
+## Usage
+
+```python
+from copass_config import DISCOVER_DESCRIPTION, COPASS_AGENT_SDK_SYSTEM_PROMPT
+
+# Register a tool whose LLM-facing description matches every other
+# Copass adapter:
+my_tool = Tool(
+    name="discover",
+    description=DISCOVER_DESCRIPTION,
+    ...
+)
+
+# Seed an agent with the canonical Copass system prompt:
+agent = BaseAgent(
+    identity="copass-agent",
+    system_prompt=COPASS_AGENT_SDK_SYSTEM_PROMPT,
+    ...
+)
+```
+
+## Keeping in sync with `@copass/config`
+
+This package is hand-ported from the TS source. When the TS side changes:
+
+1. Update the matching constant in `src/copass_config/`.
+2. Bump the minor version in `pyproject.toml` and `__init__.py`.
+3. Republish.
+
+A future release may auto-generate these constants from the TS package's build artifacts.
+
+## License
+
+MIT.

copass_config-0.1.0/README.md

@@ -0,0 +1,54 @@
+# copass-config
+
+Canonical strings shared across every Python Copass adapter. Python mirror of [`@copass/config`](../../typescript/packages/config).
+
+This package owns the **single source of truth** (for Python) for:
+
+- Tool descriptions the LLM sees (`DISCOVER_DESCRIPTION`, `INTERPRET_DESCRIPTION`, `SEARCH_DESCRIPTION`, `MCP_DISCOVER_DESCRIPTION`)
+- Parameter descriptions (`DISCOVER_QUERY_PARAM`, `INTERPRET_ITEMS_PARAM`, etc.)
+- System prompts (`COPASS_AGENT_MCP_SYSTEM_PROMPT`, `COPASS_AGENT_SDK_SYSTEM_PROMPT`)
+
+Every Python Copass adapter (`copass-pydantic-ai`, `copass-langchain`, `copass-anthropic-agents`, etc.) imports from here so the LLM sees identical tool semantics regardless of framework wrapping.
+
+## Install
+
+```bash
+pip install copass-config
+```
+
+Zero runtime dependencies.
+
+## Usage
+
+```python
+from copass_config import DISCOVER_DESCRIPTION, COPASS_AGENT_SDK_SYSTEM_PROMPT
+
+# Register a tool whose LLM-facing description matches every other
+# Copass adapter:
+my_tool = Tool(
+    name="discover",
+    description=DISCOVER_DESCRIPTION,
+    ...
+)
+
+# Seed an agent with the canonical Copass system prompt:
+agent = BaseAgent(
+    identity="copass-agent",
+    system_prompt=COPASS_AGENT_SDK_SYSTEM_PROMPT,
+    ...
+)
+```
+
+## Keeping in sync with `@copass/config`
+
+This package is hand-ported from the TS source. When the TS side changes:
+
+1. Update the matching constant in `src/copass_config/`.
+2. Bump the minor version in `pyproject.toml` and `__init__.py`.
+3. Republish.
+
+A future release may auto-generate these constants from the TS package's build artifacts.
+
+## License
+
+MIT.

copass_config-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-config"
+version = "0.1.0"
+description = "Canonical tool descriptions, parameter descriptions, and system prompts shared across every Copass Python adapter"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = ["copass", "knowledge-graph", "config", "tool-descriptions", "system-prompts"]
+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 = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[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_config"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["copass_config"]

copass_config-0.1.0/src/copass_config/__init__.py

@@ -0,0 +1,52 @@
+"""Canonical strings shared across every Copass agent adapter.
+
+Python mirror of ``@copass/config``. Single source of truth for tool
+descriptions, parameter descriptions, and system prompts used by every
+Python Copass adapter (``copass-pydantic-ai``, ``copass-langchain``,
+``copass-anthropic-agents``, future MCP server, etc.). Editing here
+and rebuilding the adapters keeps the LLM surface identical regardless
+of framework wrapping.
+
+If the TS ``@copass/config`` package changes, update the Python
+constants to match and bump this package's minor version.
+"""
+
+from copass_config.param_descriptions import (
+    DISCOVER_QUERY_PARAM,
+    INTERPRET_ITEMS_PARAM,
+    INTERPRET_QUERY_PARAM,
+    PRESET_PARAM,
+    PROJECT_ID_PARAM,
+    SEARCH_QUERY_PARAM,
+)
+from copass_config.system_prompts import (
+    COPASS_AGENT_MCP_SYSTEM_PROMPT,
+    COPASS_AGENT_SDK_SYSTEM_PROMPT,
+)
+from copass_config.tool_descriptions import (
+    DISCOVER_DESCRIPTION,
+    INTERPRET_DESCRIPTION,
+    MCP_DISCOVER_DESCRIPTION,
+    SEARCH_DESCRIPTION,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Tool descriptions
+    "DISCOVER_DESCRIPTION",
+    "MCP_DISCOVER_DESCRIPTION",
+    "INTERPRET_DESCRIPTION",
+    "SEARCH_DESCRIPTION",
+    # Param descriptions
+    "DISCOVER_QUERY_PARAM",
+    "INTERPRET_QUERY_PARAM",
+    "SEARCH_QUERY_PARAM",
+    "INTERPRET_ITEMS_PARAM",
+    "PROJECT_ID_PARAM",
+    "PRESET_PARAM",
+    # System prompts
+    "COPASS_AGENT_MCP_SYSTEM_PROMPT",
+    "COPASS_AGENT_SDK_SYSTEM_PROMPT",
+]

copass_config-0.1.0/src/copass_config/param_descriptions.py

@@ -0,0 +1,46 @@
+"""Parameter descriptions for Copass retrieval tools.
+
+Hand-ported from
+``typescript/packages/config/src/param-descriptions.ts``.
+"""
+
+from __future__ import annotations
+
+
+DISCOVER_QUERY_PARAM = "Natural-language query to surface relevant context for."
+"""``query`` param — discover."""
+
+
+INTERPRET_QUERY_PARAM = "The question the brief should answer."
+"""``query`` param — interpret."""
+
+
+SEARCH_QUERY_PARAM = "The question to answer."
+"""``query`` param — search."""
+
+
+INTERPRET_ITEMS_PARAM = " ".join(
+    [
+        "List of canonical_ids tuples — each tuple is the `canonical_ids` field",
+        "from one discover item. Pass several to synthesize across items.",
+    ]
+)
+"""``items`` param — interpret."""
+
+
+PROJECT_ID_PARAM = "Override the server default project_id."
+"""``project_id`` param — used by all three retrieval tools."""
+
+
+PRESET_PARAM = "Override the server default preset."
+"""``preset`` param — interpret and search."""
+
+
+__all__ = [
+    "DISCOVER_QUERY_PARAM",
+    "INTERPRET_QUERY_PARAM",
+    "SEARCH_QUERY_PARAM",
+    "INTERPRET_ITEMS_PARAM",
+    "PROJECT_ID_PARAM",
+    "PRESET_PARAM",
+]

copass_config-0.1.0/src/copass_config/system_prompts.py

@@ -0,0 +1,73 @@
+"""System prompts for Copass-backed agents.
+
+Hand-ported from
+``typescript/packages/config/src/system-prompts.ts``.
+"""
+
+from __future__ import annotations
+
+
+COPASS_AGENT_MCP_SYSTEM_PROMPT = """You are a knowledgeable assistant grounded in the user's Copass knowledge graph.
+
+The retrieval tools are context-window aware: the server automatically
+excludes items already surfaced earlier in this conversation. In particular,
+`mcp__copass__discover` returns ONLY new items on each call — repeated
+calls never return duplicates. This makes cumulative context-loading cheap.
+
+Approach every user turn this way:
+1. Call `mcp__copass__discover` to see what's relevant. Cheap, fast,
+   and guaranteed fresh signal each call.
+2. For items that look valuable, call `mcp__copass__interpret` on their
+   canonical_ids tuples for a drill-in brief.
+3. For broad, self-contained questions that don't need staged exploration,
+   use `mcp__copass__search` directly.
+
+Don't hesitate to call `discover` multiple times in a single turn —
+after an interpret brief, mid-reasoning, or whenever you realize you need
+more context. Every call returns genuinely new items, so progressive
+context loading is cheap and productive.
+
+Keep answers concise. Cite canonical_ids where it helps the user verify.
+
+Turn history is tracked for you automatically — do NOT call
+`mcp__copass__context_window_*` tools; they're managed by the hosting
+server."""
+"""Default system prompt for Copass agents backed by ``@copass/mcp``.
+
+Uses the MCP fully-qualified tool names (``mcp__copass__*``) — the
+scheme Claude Code, Claude Desktop, and the Claude Agent SDK all
+expose."""
+
+
+COPASS_AGENT_SDK_SYSTEM_PROMPT = """You are a knowledgeable assistant grounded in the user's Copass knowledge graph.
+
+The retrieval tools are context-window aware: the server automatically
+excludes items already surfaced earlier in this conversation. In particular,
+`discover` returns ONLY new items on each call — repeated calls never
+return duplicates. This makes cumulative context-loading cheap.
+
+Approach every user turn this way:
+1. Call `discover` to see what's relevant. Cheap, fast, and guaranteed
+   fresh signal each call.
+2. For items that look valuable, call `interpret` on their canonical_ids
+   tuples for a drill-in brief.
+3. For broad, self-contained questions that don't need staged exploration,
+   use `search` directly.
+
+Don't hesitate to call `discover` multiple times in a single turn —
+after an interpret brief, mid-reasoning, or whenever you realize you need
+more context. Every call returns genuinely new items, so progressive
+context loading is cheap and productive.
+
+Keep answers concise. Cite canonical_ids where it helps the user verify."""
+"""Default system prompt for Copass agents using the direct-SDK adapters
+(``copass-pydantic-ai``, ``copass-langchain``, future
+``copass-anthropic-agents`` convenience wrappers). Tool names are
+unprefixed because these frameworks don't use the MCP fully-qualified
+naming convention."""
+
+
+__all__ = [
+    "COPASS_AGENT_MCP_SYSTEM_PROMPT",
+    "COPASS_AGENT_SDK_SYSTEM_PROMPT",
+]

copass_config-0.1.0/src/copass_config/tool_descriptions.py

@@ -0,0 +1,93 @@
+"""Tool descriptions presented to the LLM.
+
+Hand-ported from ``typescript/packages/config/src/tool-descriptions.ts``.
+The single source of truth lives in the TS package; this module
+mirrors it verbatim so Python Copass adapters (``copass-pydantic-ai``,
+future ``copass-langchain``, ``copass-anthropic-agents``) show the LLM
+the same tool semantics regardless of framework wrapping.
+
+If the TS side changes, update this file to match and bump the
+package's minor version.
+"""
+
+from __future__ import annotations
+
+DISCOVER_DESCRIPTION = "\n".join(
+    [
+        "Return a ranked menu of context items relevant to a query. Each item is a",
+        "pointer (canonical_ids + short summary), not prose.",
+        "",
+        "Window-aware by construction: results automatically exclude items already",
+        "surfaced earlier in this conversation, so every call returns genuinely NEW",
+        "signal — never duplicates. This makes `discover` the primary context-",
+        "engineering primitive: call it freely whenever you need more context. Repeated",
+        "calls progressively map the relevant slice of the knowledge graph, and because",
+        "results skip what's already been seen, you never waste tokens re-consuming",
+        "known material.",
+        "",
+        "After calling, pass an item's canonical_ids tuple to `interpret` for a deeper",
+        "brief, or call `discover` again for more items.",
+    ]
+)
+"""Description for the ``discover`` retrieval tool.
+
+Leads with what the tool does, then emphasises the window-awareness /
+fresh-signal property that makes repeated calls cheap and productive.
+LLMs reading this should understand: call ``discover`` any time more
+context is needed, not just as the first step."""
+
+
+MCP_DISCOVER_DESCRIPTION = "\n".join(
+    [
+        "Return a ranked menu of context items relevant to a query. Each item is a",
+        "pointer (canonical_ids + short summary), not prose.",
+        "",
+        "Window-aware by construction: when a Context Window is active (pre-attached via",
+        "COPASS_CONTEXT_WINDOW_ID or created via `context_window_create`), results",
+        "automatically exclude items already surfaced earlier in this conversation.",
+        "Every call returns genuinely NEW signal — never duplicates.",
+        "",
+        "This makes `discover` the primary context-engineering primitive: call it",
+        "freely whenever you need more context. Repeated calls progressively map the",
+        "relevant slice of the knowledge graph, and because results skip what's",
+        "already been seen, you never waste tokens re-consuming known material.",
+        "",
+        "After calling, pass an item's canonical_ids tuple to `interpret` for a deeper",
+        "brief, or call `discover` again for more items.",
+    ]
+)
+"""MCP-specific variant of :data:`DISCOVER_DESCRIPTION`.
+
+Identical content plus one clarifying clause about how the server's
+Context Window is bound — MCP consumers don't construct a
+``ContextWindow`` object themselves, they inherit one via
+``COPASS_CONTEXT_WINDOW_ID`` env var or the ``context_window_create``
+tool."""
+
+
+INTERPRET_DESCRIPTION = "\n".join(
+    [
+        "Return a 1–2 paragraph synthesized brief pinned to specific items picked from",
+        "`discover`. Pass one or more canonical_ids tuples (one per item you want to",
+        "include). Use this AFTER `discover` when you know which items matter.",
+    ]
+)
+"""Description for the ``interpret`` retrieval tool."""
+
+
+SEARCH_DESCRIPTION = "\n".join(
+    [
+        "Return a full synthesized natural-language answer in one call. Use for",
+        "self-contained questions that do NOT benefit from a staged discover→interpret flow.",
+        "Heaviest of the three tools.",
+    ]
+)
+"""Description for the ``search`` retrieval tool."""
+
+
+__all__ = [
+    "DISCOVER_DESCRIPTION",
+    "MCP_DISCOVER_DESCRIPTION",
+    "INTERPRET_DESCRIPTION",
+    "SEARCH_DESCRIPTION",
+]

copass_config-0.1.0/tests/test_constants.py

@@ -0,0 +1,56 @@
+"""Smoke tests: constants are non-empty strings and importable from the
+public surface."""
+
+from __future__ import annotations
+
+import copass_config as cfg
+
+
+def test_version_present() -> None:
+    assert isinstance(cfg.__version__, str)
+    assert cfg.__version__ == "0.1.0"
+
+
+def test_tool_descriptions_non_empty() -> None:
+    for name in (
+        "DISCOVER_DESCRIPTION",
+        "MCP_DISCOVER_DESCRIPTION",
+        "INTERPRET_DESCRIPTION",
+        "SEARCH_DESCRIPTION",
+    ):
+        value = getattr(cfg, name)
+        assert isinstance(value, str), name
+        assert value.strip(), name
+
+
+def test_param_descriptions_non_empty() -> None:
+    for name in (
+        "DISCOVER_QUERY_PARAM",
+        "INTERPRET_QUERY_PARAM",
+        "SEARCH_QUERY_PARAM",
+        "INTERPRET_ITEMS_PARAM",
+        "PROJECT_ID_PARAM",
+        "PRESET_PARAM",
+    ):
+        value = getattr(cfg, name)
+        assert isinstance(value, str), name
+        assert value.strip(), name
+
+
+def test_system_prompts_mention_discover_and_interpret() -> None:
+    for name in ("COPASS_AGENT_MCP_SYSTEM_PROMPT", "COPASS_AGENT_SDK_SYSTEM_PROMPT"):
+        prompt = getattr(cfg, name)
+        assert "discover" in prompt
+        assert "interpret" in prompt
+        assert "search" in prompt
+
+
+def test_mcp_prompt_uses_mcp_tool_names() -> None:
+    prompt = cfg.COPASS_AGENT_MCP_SYSTEM_PROMPT
+    assert "mcp__copass__discover" in prompt
+    assert "mcp__copass__interpret" in prompt
+
+
+def test_sdk_prompt_uses_bare_tool_names() -> None:
+    prompt = cfg.COPASS_AGENT_SDK_SYSTEM_PROMPT
+    assert "mcp__copass__" not in prompt