copass-core-agents 0.1.0__tar.gz

copass_core_agents-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_core_agents-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: copass-core-agents
+Version: 0.1.0
+Summary: Provider-neutral agent primitives shared by every Copass agent SDK
+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: abc,agents,copass,knowledge-graph,primitives
+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-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# copass-core-agents
+
+Provider-neutral agent primitives shared by every Copass agent SDK.
+
+This package owns the ABCs, value types, and registries that each
+provider-specific SDK (`copass-anthropic-agents`, future
+`copass-openai-agents`, `copass-google-agents`, etc.) implements
+against. It carries zero vendor dependencies.
+
+## What's in here
+
+- `BaseAgent` — identity + prompt + tool surface + backend
+- `AgentScope`, `AgentInvocationContext` — tenancy + per-call context
+- `AgentTool`, `AgentToolRegistry`, `AgentToolResolver`, `ToolSpec`,
+  `ToolCall` — tool abstractions
+- `AgentEvent` (plus `AgentTextDelta`, `AgentToolCall`,
+  `AgentToolResult`, `AgentFinish`) — streaming event union
+- `AgentBackend` ABC + `AgentRunResult`
+- `register_agent` / `register_agent_tool` registries
+
+## Which package should I install?
+
+| I want to… | Install |
+|---|---|
+| Run a Claude Managed Agent (Anthropic) | `copass-anthropic-agents` (pulls this in transitively) |
+| Build my own backend / extend the ABCs | `copass-core-agents` directly |
+
+If you're end-user code invoking an agent, you almost never install
+this package directly — you install a provider SDK and it re-exports
+what you need.
+
+## Dependencies
+
+Zero runtime dependencies. Python ≥ 3.10.
+
+## License
+
+MIT.

copass_core_agents-0.1.0/README.md

@@ -0,0 +1,38 @@
+# copass-core-agents
+
+Provider-neutral agent primitives shared by every Copass agent SDK.
+
+This package owns the ABCs, value types, and registries that each
+provider-specific SDK (`copass-anthropic-agents`, future
+`copass-openai-agents`, `copass-google-agents`, etc.) implements
+against. It carries zero vendor dependencies.
+
+## What's in here
+
+- `BaseAgent` — identity + prompt + tool surface + backend
+- `AgentScope`, `AgentInvocationContext` — tenancy + per-call context
+- `AgentTool`, `AgentToolRegistry`, `AgentToolResolver`, `ToolSpec`,
+  `ToolCall` — tool abstractions
+- `AgentEvent` (plus `AgentTextDelta`, `AgentToolCall`,
+  `AgentToolResult`, `AgentFinish`) — streaming event union
+- `AgentBackend` ABC + `AgentRunResult`
+- `register_agent` / `register_agent_tool` registries
+
+## Which package should I install?
+
+| I want to… | Install |
+|---|---|
+| Run a Claude Managed Agent (Anthropic) | `copass-anthropic-agents` (pulls this in transitively) |
+| Build my own backend / extend the ABCs | `copass-core-agents` directly |
+
+If you're end-user code invoking an agent, you almost never install
+this package directly — you install a provider SDK and it re-exports
+what you need.
+
+## Dependencies
+
+Zero runtime dependencies. Python ≥ 3.10.
+
+## License
+
+MIT.

copass_core_agents-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copass-core-agents"
+version = "0.1.0"
+description = "Provider-neutral agent primitives shared by every Copass agent SDK"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Olane Inc." }]
+requires-python = ">=3.10"
+keywords = [
+    "copass",
+    "knowledge-graph",
+    "agents",
+    "abc",
+    "primitives",
+]
+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",
+    "pytest-asyncio>=0.23",
+    "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_core_agents"]
+
+[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_core_agents"]

copass_core_agents-0.1.0/src/copass_core_agents/__init__.py

@@ -0,0 +1,99 @@
+"""Copass Core Agents — provider-neutral agent primitives.
+
+Shared ABCs and value types used by every provider-specific Copass
+agent SDK (``copass-anthropic-agents``, future ``copass-openai-agents``,
+``copass-google-agents``, etc.). Concrete backends, convenience
+subclasses, and vendor-specific wiring live in those per-provider
+packages; this package owns nothing vendor-specific.
+
+Public surface:
+
+    Core
+        BaseAgent               — identity + prompt + tools + backend
+        AgentScope              — tenancy payload
+        AgentInvocationContext  — per-call runtime context
+        AgentTool               — ABC for a tool an agent can invoke
+        AgentToolRegistry       — per-agent collection of tools
+        AgentToolResolver       — scope-aware dynamic tool producer
+        ToolSpec, ToolCall      — tool catalog shapes
+        ToolConflictPolicy      — "error" | "dynamic_wins" | "static_wins"
+        ToolConflictError
+
+    Events (emitted by AgentBackend.stream)
+        AgentEvent              — tagged union
+        AgentTextDelta
+        AgentToolCall
+        AgentToolResult
+        AgentFinish
+
+    Backends
+        AgentBackend            — ABC (concrete impls live per-provider)
+        AgentRunResult          — reduced run() output
+
+    Registries (optional lookup-by-name)
+        register_agent, get_agent_class, list_agents
+        register_agent_tool, get_agent_tool, try_get_agent_tool,
+        list_agent_tools
+"""
+
+from copass_core_agents.backends import AgentBackend, AgentRunResult
+from copass_core_agents.base_agent import BaseAgent
+from copass_core_agents.base_tool import AgentTool, ToolCall, ToolSpec
+from copass_core_agents.events import (
+    AgentEvent,
+    AgentFinish,
+    AgentTextDelta,
+    AgentToolCall,
+    AgentToolResult,
+)
+from copass_core_agents.invocation_context import AgentInvocationContext
+from copass_core_agents.registry import (
+    get_agent_class,
+    get_agent_tool,
+    list_agent_tools,
+    list_agents,
+    register_agent,
+    register_agent_tool,
+    try_get_agent_tool,
+)
+from copass_core_agents.scope import AgentScope
+from copass_core_agents.tool_registry import AgentToolRegistry
+from copass_core_agents.tool_resolver import (
+    AgentToolResolver,
+    ToolConflictError,
+    ToolConflictPolicy,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Core
+    "BaseAgent",
+    "AgentScope",
+    "AgentInvocationContext",
+    "AgentTool",
+    "AgentToolRegistry",
+    "AgentToolResolver",
+    "ToolSpec",
+    "ToolCall",
+    "ToolConflictError",
+    "ToolConflictPolicy",
+    # Events
+    "AgentEvent",
+    "AgentTextDelta",
+    "AgentToolCall",
+    "AgentToolResult",
+    "AgentFinish",
+    # Backends
+    "AgentBackend",
+    "AgentRunResult",
+    # Registries
+    "register_agent",
+    "get_agent_class",
+    "list_agents",
+    "register_agent_tool",
+    "get_agent_tool",
+    "try_get_agent_tool",
+    "list_agent_tools",
+]

copass_core_agents-0.1.0/src/copass_core_agents/backends/__init__.py

@@ -0,0 +1,10 @@
+"""Agent backend ABCs — concrete backends live in per-provider
+packages (``copass-anthropic-agents``, future ``copass-openai-agents``,
+``copass-google-agents``)."""
+
+from copass_core_agents.backends.base_backend import (
+    AgentBackend,
+    AgentRunResult,
+)
+
+__all__ = ["AgentBackend", "AgentRunResult"]

copass_core_agents-0.1.0/src/copass_core_agents/backends/base_backend.py

@@ -0,0 +1,87 @@
+"""AgentBackend — runtime ABC for executing an agent turn.
+
+A backend is the seam between the provider-neutral agent surface
+(``BaseAgent``, ``AgentTool``, ``AgentEvent``) and a concrete
+SDK/provider.
+
+Design rules:
+
+- Base classes must NOT import any vendor SDK. This file only depends
+  on plain data types and the SDK's own ABCs.
+- Backends translate between the provider's tool-use format and the
+  agent's ``AgentToolRegistry`` + ``AgentEvent`` stream.
+- A single backend instance may be shared across agents and requests.
+  Per-request state lives on ``AgentInvocationContext``, not on the
+  backend.
+
+Concrete backends live in per-provider packages
+(``copass-anthropic-agents``, future ``copass-openai-agents``,
+``copass-google-agents``). This file and ``AgentRunResult`` are the
+only ABC surface they implement against.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, AsyncIterator, List, Optional
+
+from copass_core_agents.events import AgentEvent
+from copass_core_agents.invocation_context import AgentInvocationContext
+
+if TYPE_CHECKING:
+    from copass_core_agents.base_agent import BaseAgent
+
+
+@dataclass(frozen=True)
+class AgentRunResult:
+    """Reduced output of a non-streaming ``AgentBackend.run``."""
+
+    final_text: str
+    tool_calls: List[dict] = field(default_factory=list)
+    stop_reason: str = "end_turn"
+    usage: dict = field(default_factory=dict)
+    session_id: Optional[str] = None
+
+
+class AgentBackend(ABC):
+    """Runtime adapter between the agent surface and a provider SDK.
+
+    Construction takes an optional ``config`` dict. Backend-specific
+    knobs (API keys, model allow-lists, timeout overrides) live there
+    rather than as strong fields so the ABC signature stays stable as
+    providers evolve.
+    """
+
+    def __init__(self, *, config: Optional[dict] = None) -> None:
+        self._config = dict(config or {})
+
+    @property
+    def config(self) -> dict:
+        """Backend-specific configuration. Read-only view."""
+        return dict(self._config)
+
+    @abstractmethod
+    async def run(
+        self,
+        agent: "BaseAgent",
+        messages: List[dict],
+        context: AgentInvocationContext,
+    ) -> AgentRunResult:
+        """Drive the conversation to a stop condition, return a
+        reduced result."""
+        ...
+
+    @abstractmethod
+    def stream(
+        self,
+        agent: "BaseAgent",
+        messages: List[dict],
+        context: AgentInvocationContext,
+    ) -> AsyncIterator[AgentEvent]:
+        """Drive the conversation and yield ``AgentEvent`` as they
+        occur."""
+        ...
+
+
+__all__ = ["AgentBackend", "AgentRunResult"]

copass_core_agents-0.1.0/src/copass_core_agents/base_agent.py

@@ -0,0 +1,167 @@
+"""BaseAgent — ABC for an identity-bound, tool-equipped agent.
+
+An agent is the composition of:
+
+- an **identity** (stable string used in logs, prompts, and registry
+  lookups)
+- a **model** (provider/SDK-specific model name — the backend
+  validates it)
+- a **system prompt** (role + instructions fed on every turn)
+- an **AgentToolRegistry** holding the *static* tools
+- an optional **AgentToolResolver** producing *dynamic* tools per
+  invocation
+- an **AgentBackend** (the runtime that actually drives turns)
+
+``BaseAgent`` itself has no turn-execution logic — both ``run`` and
+``stream`` compute the effective tool registry for the invocation
+(via :meth:`build_tools`) and delegate to the backend.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC
+from typing import AsyncIterator, List, Optional
+
+from copass_core_agents.backends.base_backend import (
+    AgentBackend,
+    AgentRunResult,
+)
+from copass_core_agents.base_tool import AgentTool
+from copass_core_agents.events import AgentEvent
+from copass_core_agents.invocation_context import AgentInvocationContext
+from copass_core_agents.tool_registry import AgentToolRegistry
+from copass_core_agents.tool_resolver import (
+    AgentToolResolver,
+    ToolConflictError,
+    ToolConflictPolicy,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent(ABC):
+    """Identity + prompt + tools + resolver + backend bundle.
+
+    Not abstract in the Python sense (no ``@abstractmethod``) — the
+    ``ABC`` inheritance is a signal to subclassers that this is a
+    base type to extend, not to instantiate directly. Instantiating
+    ``BaseAgent`` is valid for quick scripts/tests but production
+    callers should subclass with concrete identity and prompt.
+
+    Either ``tools`` or ``tool_resolver`` (or both) must be provided.
+    """
+
+    def __init__(
+        self,
+        *,
+        identity: str,
+        model: str,
+        system_prompt: str,
+        backend: AgentBackend,
+        tools: Optional[AgentToolRegistry] = None,
+        tool_resolver: Optional[AgentToolResolver] = None,
+        on_conflict: ToolConflictPolicy = "dynamic_wins",
+    ) -> None:
+        if tools is None and tool_resolver is None:
+            raise ValueError(
+                "BaseAgent requires at least one of `tools` or "
+                "`tool_resolver` — an agent with no capabilities has "
+                "no reason to exist."
+            )
+        if on_conflict not in ("error", "dynamic_wins", "static_wins"):
+            raise ValueError(
+                f"BaseAgent: invalid on_conflict policy {on_conflict!r}. "
+                f"Expected 'error', 'dynamic_wins', or 'static_wins'."
+            )
+        self.identity = identity
+        self.model = model
+        self.system_prompt = system_prompt
+        self.backend = backend
+        self.tools = tools if tools is not None else AgentToolRegistry()
+        self.tool_resolver = tool_resolver
+        self.on_conflict: ToolConflictPolicy = on_conflict
+
+    async def run(
+        self,
+        messages: List[dict],
+        *,
+        context: AgentInvocationContext,
+    ) -> AgentRunResult:
+        """Drive a turn to completion and return the reduced result."""
+        return await self.backend.run(self, messages, context)
+
+    async def stream(
+        self,
+        messages: List[dict],
+        *,
+        context: AgentInvocationContext,
+    ) -> AsyncIterator[AgentEvent]:
+        """Drive a turn and yield ``AgentEvent`` as they occur."""
+        async for evt in self.backend.stream(self, messages, context):
+            yield evt
+
+    async def build_tools(
+        self, context: AgentInvocationContext
+    ) -> AgentToolRegistry:
+        """Compute the effective tool registry for this invocation."""
+        if self.tool_resolver is None:
+            return self.tools
+
+        dynamic_tools: List[AgentTool] = await self.tool_resolver.resolve(context)
+
+        merged = AgentToolRegistry()
+        static_names = {tool.spec.name for tool in self.tools}
+        dynamic_names = {tool.spec.name for tool in dynamic_tools}
+        collisions = static_names & dynamic_names
+
+        if collisions and self.on_conflict == "error":
+            raise ToolConflictError(
+                f"BaseAgent {self.identity!r}: static and dynamic tools "
+                f"collide on names: {sorted(collisions)}. Set "
+                f"on_conflict='dynamic_wins' or 'static_wins' to pick "
+                f"a resolution policy, or fix the duplicated name."
+            )
+
+        if self.on_conflict == "static_wins":
+            for tool in dynamic_tools:
+                if tool.spec.name not in static_names:
+                    merged.add(tool)
+            for tool in self.tools:
+                merged.add(tool)
+        else:
+            for tool in self.tools:
+                if tool.spec.name not in dynamic_names:
+                    merged.add(tool)
+            for tool in dynamic_tools:
+                merged.add(tool)
+
+        if collisions:
+            logger.info(
+                "BaseAgent.build_tools: resolved tool name collisions",
+                extra={
+                    "identity": self.identity,
+                    "policy": self.on_conflict,
+                    "collisions": sorted(collisions),
+                },
+            )
+        return merged
+
+    def __repr__(self) -> str:
+        resolver = (
+            self.tool_resolver.__class__.__name__
+            if self.tool_resolver is not None
+            else "None"
+        )
+        return (
+            f"{self.__class__.__name__}("
+            f"identity={self.identity!r}, "
+            f"model={self.model!r}, "
+            f"static_tools={len(self.tools)}, "
+            f"resolver={resolver}, "
+            f"backend={self.backend.__class__.__name__}"
+            f")"
+        )
+
+
+__all__ = ["BaseAgent"]

copass_core_agents-0.1.0/src/copass_core_agents/base_tool.py

@@ -0,0 +1,104 @@
+"""AgentTool — tool ABC callable by an agent during a turn.
+
+``ToolSpec`` / ``ToolCall`` are the provider-neutral catalog shapes.
+Defined here in the core package; provider adapters (Anthropic,
+OpenAI, Google) translate them into provider-specific tool-use
+catalog payloads.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional
+
+from copass_core_agents.invocation_context import AgentInvocationContext
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """Catalog entry for one tool — what the model sees.
+
+    Shape matches the JSON-schema-based tool-use conventions across
+    providers so a single ``ToolSpec`` can be passed to any backend's
+    ``tools=[]`` parameter after trivial adaptation.
+    """
+
+    name: str
+    description: str
+    input_schema: dict
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """Audit record of one tool invocation within a turn.
+
+    Not used by the agent runtime's hot path (events carry the
+    canonical structure); this type is the shape backends / consumers
+    serialize when they want to persist a turn's tool history.
+    """
+
+    name: str
+    arguments: dict
+    result: dict
+    error: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+
+
+class AgentTool(ABC):
+    """One capability an agent can invoke during a turn.
+
+    Implementations must be:
+
+    - Stateless across calls (no per-invocation mutable state on the
+      instance). Concurrency is driven by the backend and multiple
+      ``invoke`` calls may run in parallel.
+    - JSON-result-returning. The returned dict is fed back to the
+      model verbatim; it must be serializable and should stay small
+      enough to fit in the model's context window.
+    - Schema-honoring. ``arguments`` always matches
+      ``spec.input_schema`` — the backend is responsible for
+      validating before calling ``invoke``.
+
+    Implementations must NOT:
+
+    - Raise arbitrary exceptions on recoverable errors. Convert
+      tool-internal failures into a dict result with an ``error``
+      field the model can read and retry against. Reserve raising
+      for programmer errors (schema drift, unreachable branches).
+    """
+
+    @property
+    @abstractmethod
+    def spec(self) -> ToolSpec:
+        """Return the catalog entry. Must be stable across calls."""
+        ...
+
+    @abstractmethod
+    async def invoke(
+        self,
+        arguments: dict,
+        *,
+        context: Optional[AgentInvocationContext] = None,
+    ) -> dict:
+        """Execute the tool.
+
+        Args:
+            arguments: JSON-decoded tool arguments. Matches
+                ``spec.input_schema``.
+            context: Per-invocation context (scope, dek, handles).
+                Optional — tools that don't need runtime handles
+                should tolerate ``None``.
+
+        Returns:
+            JSON-serializable dict. Goes straight back to the model.
+
+        Raises:
+            Exception: Only for programmer errors / unrecoverable
+                failures. Recoverable issues belong in the return
+                dict.
+        """
+        ...
+
+
+__all__ = ["AgentTool", "ToolCall", "ToolSpec"]