cantus-agent 0.4.2__py3-none-any.whl

cantus/__init__.py

@@ -0,0 +1,131 @@
+"""cantus — Polyphonic LLM agent framework with a dual-tier teaching API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from cantus.model.loader import ModelHandle
+
+__version__ = "0.4.2"
+
+from cantus.core.action import (
+    Action,
+    CallSkillAction,
+    FinalAnswerAction,
+)
+from cantus.core.agent import Agent, AgentState
+from cantus.core.event_stream import EventStream
+from cantus.core.event_stream_persistence import JsonLinesPersistence
+from cantus.core.observation import (
+    MaxIterationsObservation,
+    Observation,
+    SkillObservation,
+    ToolErrorObservation,
+    ValidationErrorObservation,
+)
+from cantus.core.registry import Registry, get_registry
+from cantus.core.result import Result
+from cantus.env import CloudOnlyEnvironment, ColabEnvironment, LocalEnvironment
+from cantus.identity import Soul, SoulParseError
+from cantus.inspect import Inspector
+from cantus.model.bridge import ChatModelAsHandle
+from cantus.model.chat import ChatModel, ChatResponse, Message, ToolCall
+from cantus.model.factory import load_chat_model
+from cantus.protocols.debug import debug
+from cantus.protocols.memory import (
+    AutoMemory,
+    BM25Memory,
+    EmbeddingMemory,
+    MarkdownMemory,
+    Memory,
+    ShortTermMemory,
+)
+from cantus.protocols.skill import Skill, register_skill, skill
+
+__all__ = [
+    # Decorator entries (v0.3.0: Skill + debug only at top level;
+    # analyzer/validator are now imported from cantus.hooks)
+    "skill",
+    "debug",
+    # Function-pass entries
+    "register_skill",
+    # Class-first base classes (top level: Skill + Memory only;
+    # Analyzer/Validator are imported from cantus.hooks)
+    "Skill",
+    "Memory",
+    # Memory implementations (v0.3.1: MarkdownMemory + AutoMemory join)
+    "ShortTermMemory",
+    "BM25Memory",
+    "EmbeddingMemory",
+    "MarkdownMemory",
+    "AutoMemory",
+    # Identity (v0.3.1)
+    "Soul",
+    "SoulParseError",
+    # EventStream persistence plug (v0.3.1)
+    "JsonLinesPersistence",
+    # Runtime
+    "Action",
+    "CallSkillAction",
+    "FinalAnswerAction",
+    "Observation",
+    "SkillObservation",
+    "ToolErrorObservation",
+    "ValidationErrorObservation",
+    "MaxIterationsObservation",
+    "EventStream",
+    "Agent",
+    "AgentState",
+    "Inspector",
+    # Registry
+    "Registry",
+    "get_registry",
+    # Result type
+    "Result",
+    # Tier 2 ChatModel
+    "ChatModel",
+    "Message",
+    "ToolCall",
+    "ChatResponse",
+    "ChatModelAsHandle",
+    "load_chat_model",
+    # Environment profiles
+    "ColabEnvironment",
+    "LocalEnvironment",
+    "CloudOnlyEnvironment",
+    # Serve layer (v0.4.0, lazy-loaded; require `pip install cantus[serve]`)
+    "serve",
+    "config",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 lazy loader for the v0.4.0 serve layer.
+
+    `cantus.serve` and `cantus.config` are exposed at the top level but
+    imported on first attribute access so that a base ``import cantus``
+    does not require ``fastapi`` / ``uvicorn`` / ``pydantic-settings``.
+    Missing extras still surface as ``ImportError`` with the literal
+    substring ``"pip install cantus[serve]"`` from the gate inside the
+    target module.
+    """
+    if name in {"serve", "config"}:
+        import importlib
+
+        module = importlib.import_module(f"cantus.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module 'cantus' has no attribute {name!r}")
+
+
+def mount_drive_and_load(*args: object, **kwargs: object) -> ModelHandle:
+    """Mount Google Drive and load Gemma 4 weights — see model.loader."""
+    from cantus.model.loader import mount_drive_and_load as _impl
+
+    return _impl(*args, **kwargs)  # type: ignore[arg-type]
+
+
+def load_gemma(*args: object, **kwargs: object) -> ModelHandle:
+    """Alias of mount_drive_and_load for direct hub loading scenarios."""
+    return mount_drive_and_load(*args, **kwargs)

cantus/adapters/__init__.py

@@ -0,0 +1,135 @@
+"""cantus.adapters — bridges to MCP, Anthropic Memory, and four
+cross-framework targets (LangChain / DSPy / HuggingFace / OpenHands).
+
+The adapter layer is a pure conversion utility: it does NOT alter Skill
+or Memory runtime behaviour and does NOT register a new protocol kind.
+The package exposes ten top-level callables (3 from v0.3.2 + 6 from
+v0.3.3 + 1 from v0.3.4):
+
+v0.3.2 (MCP + Anthropic Memory):
+- ``export_as_mcp_server(skills, *, name, version)`` — wrap a list of
+  cantus Skills as an MCP server (requires ``cantus[mcp]``).
+- ``import_mcp_server(*, transport, command_or_url)`` — connect to a
+  remote MCP server and return a list of cantus Skills.
+- ``expose_as_anthropic_memory_tool(memory)`` — JSON-serialisable dict
+  matching the Anthropic Memory tool spec (no SDK dependency).
+
+v0.3.3 (cross-framework batch2):
+- ``expose_as_langchain_tool(skill)`` / ``import_langchain_tool(tool)`` —
+  cantus Skill <-> ``langchain_core.tools.BaseTool``
+  (requires ``cantus[langchain]``).
+- ``expose_as_dspy_tool(skill)`` / ``import_dspy_tool(tool)`` —
+  cantus Skill <-> ``dspy.Tool``
+  (requires ``cantus[dspy]``).
+- ``expose_as_hf_tool(skill)`` — cantus Skill -> ``transformers.Tool``
+  (requires ``cantus[huggingface]``).
+- ``expose_as_openhands_action(skill)`` — cantus Skill ->
+  ``openhands.events.Action`` (requires ``cantus[openhands]``;
+  export-only — the import direction is permanently not applicable
+  because ``Action`` is a declarative event record dispatched by the
+  OpenHands host runtime, with no ``__call__`` for ``Skill.run`` to
+  delegate to).
+
+v0.3.4 (cross-framework batch3a — HF bidirectional close-out):
+- ``import_hf_tool(tool)`` — cantus Skill <- ``transformers.Tool``
+  (requires ``cantus[huggingface]``). Completes the HuggingFace
+  bidirectional matrix; the OpenHands import direction is intentionally
+  omitted, see ``expose_as_openhands_action`` above.
+
+Every batch2/batch3 entry lazy-imports its SDK only when called; the core
+``pip install cantus`` install still resolves ``import cantus.adapters``
+without pulling any framework SDK.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def export_as_mcp_server(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.mcp_server."""
+    from cantus.adapters.mcp_server import export_as_mcp_server as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def import_mcp_server(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.mcp_client."""
+    from cantus.adapters.mcp_client import import_mcp_server as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def expose_as_anthropic_memory_tool(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.anthropic_memory."""
+    from cantus.adapters.anthropic_memory import (
+        expose_as_anthropic_memory_tool as _impl,
+    )
+
+    return _impl(*args, **kwargs)
+
+
+def expose_as_langchain_tool(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.langchain (requires cantus[langchain])."""
+    from cantus.adapters.langchain import expose_as_langchain_tool as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def import_langchain_tool(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.langchain (requires cantus[langchain])."""
+    from cantus.adapters.langchain import import_langchain_tool as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def expose_as_dspy_tool(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.dspy (requires cantus[dspy])."""
+    from cantus.adapters.dspy import expose_as_dspy_tool as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def import_dspy_tool(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.dspy (requires cantus[dspy])."""
+    from cantus.adapters.dspy import import_dspy_tool as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def expose_as_hf_tool(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.huggingface (requires cantus[huggingface])."""
+    from cantus.adapters.huggingface import expose_as_hf_tool as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def import_hf_tool(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.huggingface (requires cantus[huggingface])."""
+    from cantus.adapters.huggingface import import_hf_tool as _impl
+
+    return _impl(*args, **kwargs)
+
+
+def expose_as_openhands_action(*args: Any, **kwargs: Any) -> Any:
+    """Stub. Implemented in cantus.adapters.openhands (requires cantus[openhands])."""
+    from cantus.adapters.openhands import expose_as_openhands_action as _impl
+
+    return _impl(*args, **kwargs)
+
+
+__all__ = [
+    # v0.3.2 — MCP + Anthropic Memory
+    "export_as_mcp_server",
+    "import_mcp_server",
+    "expose_as_anthropic_memory_tool",
+    # v0.3.3 — cross-framework batch2
+    "expose_as_langchain_tool",
+    "import_langchain_tool",
+    "expose_as_dspy_tool",
+    "import_dspy_tool",
+    "expose_as_hf_tool",
+    "expose_as_openhands_action",
+    # v0.3.4 — cross-framework batch3a (HF bidirectional close-out)
+    "import_hf_tool",
+]

cantus/adapters/_remote_skill.py

@@ -0,0 +1,72 @@
+"""Shared base class for all `cantus.adapters.import_*` adapters.
+
+`_RemoteSkillBase` lifts the three load-bearing patterns from v0.3.2
+`cantus.adapters.mcp_client._RemoteSkill` into a private, framework-internal
+base so that LangChain / DSPy / future cross-framework import adapters
+inherit the same v0.3.0 `Skill.spec_for_llm()` shape contract instead of
+duplicating it per adapter:
+
+1. ``__init__`` bypasses :class:`Skill`'s signature-introspection path —
+   the remote framework's schema is authoritative.
+2. ``spec_for_llm()`` returns the canonical three-key dict directly from
+   the remote schema dict; ``is_remote = True`` is NOT leaked into it.
+3. ``validate_args()`` trusts the remote framework's schema and only
+   enforces dict shape at the protocol layer.
+
+This module is private (leading underscore in module name) and SHALL NOT
+be re-exported from ``cantus.adapters.__init__``; the adapter-layer-batch2
+spec explicitly forbids exposing an ``Adapter`` ABC as public surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cantus.protocols.skill import Skill
+
+
+class _RemoteSkillBase(Skill):
+    """Internal base for cantus Skills that proxy a remote framework tool."""
+
+    is_remote = True
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        args_schema_dict: dict[str, Any],
+    ) -> None:
+        # Intentionally bypass Skill.__init__: remote frameworks (MCP,
+        # LangChain, DSPy, OpenHands) supply their own authoritative
+        # schema, so signature introspection of `run` is both useless
+        # (the body just dispatches kwargs) and wrong (it would invent
+        # an empty Pydantic model with no fields).
+        self.name = name
+        self.description = description
+        self._args_schema_dict = args_schema_dict
+        self._pre_hook = None
+        self._post_hook = None
+
+    def spec_for_llm(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "args_schema": self._args_schema_dict,
+        }
+
+    def validate_args(self, args: dict[str, Any]) -> dict[str, Any]:
+        if not isinstance(args, dict):
+            raise TypeError(
+                f"remote adapter tool args must be a dict, "
+                f"got {type(args).__name__}"
+            )
+        return dict(args)
+
+    def run(self, **kwargs: Any) -> Any:
+        raise NotImplementedError(
+            "subclass must implement run() with framework-specific dispatch"
+        )
+
+
+__all__ = ["_RemoteSkillBase"]

cantus/adapters/anthropic_memory.py

@@ -0,0 +1,107 @@
+"""expose_as_anthropic_memory_tool — cantus Memory → Anthropic Memory tool dict.
+
+Returns a pure Python `dict` (no callables, no Memory instance references)
+matching the Anthropic Memory tool spec: a 4-action surface (`view`,
+`create`, `str_replace`, `delete`) over a Skill-shaped command schema. The
+returned dict round-trips through `json.dumps` so host code can feed it
+straight into `client.messages.create(tools=[...])`.
+
+The adapter does NOT wire the LLM's tool_use callbacks back into the
+Memory backend — that's host code's responsibility. The returned dict is
+opaque to the Memory instance; the host pattern is:
+
+    1. send `tool_dict` to Anthropic via `tools=[...]`
+    2. when Claude emits `tool_use` with `name="memory"`, dispatch the
+       `command` argument back into the appropriate `memory.recall` /
+       `memory.remember` call
+
+Foot-gun warning carry-over (v0.3.1 audit Trap-10): under this tool_use
+loop, the LLM has full CRUD access to the memory backend with no built-in
+filter. For production, wrap individual commands with validation in the
+host dispatch layer.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cantus.protocols.memory import AutoMemory, Memory
+
+_VIEW_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "query": {
+            "type": "string",
+            "description": "Substring to match against stored turn content (case-insensitive).",
+        }
+    },
+    "required": ["query"],
+}
+
+_CREATE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "user": {"type": "string", "description": "User-side content of the turn."},
+        "assistant": {"type": "string", "description": "Assistant-side content of the turn."},
+    },
+    "required": ["user", "assistant"],
+}
+
+_STR_REPLACE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "query": {"type": "string", "description": "Substring filter selecting turns to modify."},
+        "old": {"type": "string", "description": "Old substring to replace within matched turns."},
+        "new": {"type": "string", "description": "Replacement substring."},
+    },
+    "required": ["query", "old", "new"],
+}
+
+_DELETE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "query": {"type": "string", "description": "Substring filter selecting turns to delete."},
+    },
+    "required": ["query"],
+}
+
+
+def expose_as_anthropic_memory_tool(memory: Memory | AutoMemory) -> dict[str, Any]:
+    """Return a JSON-serialisable Anthropic Memory tool dict for the given Memory."""
+    if not isinstance(memory, (Memory, AutoMemory)):
+        raise TypeError(
+            f"expose_as_anthropic_memory_tool expects Memory or AutoMemory, "
+            f"got {type(memory).__name__}"
+        )
+
+    backend_name = type(memory).__name__
+    description = f"Cantus {backend_name} exposed as Anthropic Memory tool"
+
+    commands: dict[str, dict[str, Any]] = {
+        "view": {
+            "description": "Recall stored turns whose user or assistant field matches the query.",
+            "args_schema": _VIEW_SCHEMA,
+        },
+        "create": {
+            "description": "Remember a new (user, assistant) turn.",
+            "args_schema": _CREATE_SCHEMA,
+        },
+        "str_replace": {
+            "description": "Find matching turns and replace `old` with `new` in their fields.",
+            "args_schema": _STR_REPLACE_SCHEMA,
+        },
+        "delete": {
+            "description": "Mark stored turns matching the query as deleted (backend-dependent).",
+            "args_schema": _DELETE_SCHEMA,
+        },
+    }
+
+    return {
+        "type": "memory",
+        "name": "memory",
+        "description": description,
+        "commands": commands,
+    }
+
+
+__all__ = ["expose_as_anthropic_memory_tool"]

cantus/adapters/dspy.py

@@ -0,0 +1,149 @@
+"""DSPy adapter — bidirectional cantus <-> dspy.Tool.
+
+Schema conversion follows the v0.3.3 design.md "LangChain / DSPy import_*
+schema 轉換策略" decision: types are mapped via a fixed JSON Schema
+``{str, int, float, bool}`` <-> Python type table, with other types
+falling back to ``str`` / ``"string"``. The framework does NOT attempt
+universal coverage of complex generics (``list[str]``, ``Optional[X]``,
+unions); that complexity is intentionally pushed to a future revision
+when real student demand surfaces.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:  # SDK gate — fail loud the moment this module is imported.
+    import dspy
+except ImportError as exc:
+    raise ImportError(
+        "cantus.adapters.dspy requires the dspy-ai SDK. "
+        "Run: pip install cantus[dspy]"
+    ) from exc
+
+from cantus.adapters._remote_skill import _RemoteSkillBase
+from cantus.protocols.skill import Skill
+
+_JSON_TYPE_TO_PY: dict[str, type] = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+}
+
+_PY_TYPE_TO_JSON: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+}
+
+
+def _py_type_to_json_type(py_type: Any) -> str:
+    return _PY_TYPE_TO_JSON.get(py_type, "string")
+
+
+class _CantusDspyInputField:
+    """Shape that mirrors a dspy input-field descriptor for exposed Skills."""
+
+    def __init__(self, py_type: type, *, optional: bool = False) -> None:
+        self.py_type = py_type
+        self.optional = optional
+
+
+class _CantusDspySignature:
+    """Minimal signature shape with an ``input_fields`` dict."""
+
+    def __init__(self, input_fields: dict[str, _CantusDspyInputField]) -> None:
+        self.input_fields = input_fields
+
+
+def expose_as_dspy_tool(skill: Skill) -> "dspy.Tool":
+    """Wrap a cantus Skill as a dspy.Tool instance."""
+    if not isinstance(skill, Skill):
+        raise TypeError(
+            f"expose_as_dspy_tool expects Skill, got {type(skill).__name__}"
+        )
+
+    spec = skill.spec_for_llm()
+    properties = (spec["args_schema"].get("properties") or {})
+    required = set(spec["args_schema"].get("required") or [])
+
+    input_fields: dict[str, Any] = {}
+    for prop_name, prop_schema in properties.items():
+        json_type = prop_schema.get("type", "string")
+        py_type = _JSON_TYPE_TO_PY.get(json_type, str)
+        optional = prop_name not in required
+        input_fields[prop_name] = _CantusDspyInputField(py_type, optional=optional)
+
+    signature = _CantusDspySignature(input_fields)
+
+    def _impl(**kwargs: Any) -> Any:
+        return skill(**kwargs)
+
+    return dspy.Tool(
+        name=spec["name"],
+        desc=spec["description"],
+        signature=signature,
+        impl=_impl,
+    )
+
+
+class _DspyRemoteSkill(_RemoteSkillBase):
+    """cantus Skill that proxies a dspy.Tool."""
+
+    def __init__(self, *, tool: "dspy.Tool") -> None:
+        signature = getattr(tool, "signature", None)
+        try:
+            input_fields = signature.input_fields  # type: ignore[union-attr]
+            if not isinstance(input_fields, dict):
+                raise TypeError(
+                    f"input_fields must be a dict, got {type(input_fields).__name__}"
+                )
+        except Exception as exc:
+            raise RuntimeError(
+                f"dspy_handshake_failed: cannot read signature.input_fields: "
+                f"{type(exc).__name__}: {exc}"
+            ) from exc
+
+        properties: dict[str, dict[str, Any]] = {}
+        required: list[str] = []
+        for field_name, field in input_fields.items():
+            py_type = getattr(field, "py_type", str)
+            properties[field_name] = {"type": _py_type_to_json_type(py_type)}
+            if not getattr(field, "optional", False):
+                required.append(field_name)
+
+        args_schema_dict: dict[str, Any] = {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+        }
+
+        super().__init__(
+            name=tool.name,
+            description=getattr(tool, "desc", "") or "",
+            args_schema_dict=args_schema_dict,
+        )
+        self._tool = tool
+
+    def run(self, **kwargs: Any) -> Any:
+        try:
+            return self._tool(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(
+                f"dspy_remote_error: tool {self.name!r} failed: "
+                f"{type(exc).__name__}: {exc}"
+            ) from exc
+
+
+def import_dspy_tool(tool: "dspy.Tool") -> Skill:
+    """Wrap a dspy.Tool as a cantus Skill instance."""
+    if not isinstance(tool, dspy.Tool):
+        raise TypeError(
+            f"import_dspy_tool expects dspy.Tool, got {type(tool).__name__}"
+        )
+    return _DspyRemoteSkill(tool=tool)
+
+
+__all__ = ["expose_as_dspy_tool", "import_dspy_tool"]