coco-framework 0.1.0__py3-none-any.whl

coco/embeddings/__init__.py

@@ -0,0 +1,18 @@
+"""Embeddings models.
+
+!!! warning "Modules moved"
+
+    With the release of `coco 1.0.0`, several embeddings modules were moved to
+    `trustcoco-classic`, such as `CacheBackedEmbeddings` and all community
+    embeddings. See [list](https://github.com/langchain-ai/langchain/blob/bdf1cd383ce36dc18381a3bf3fb0a579337a32b5/libs/langchain/langchain/embeddings/__init__.py)
+    of moved modules to inform your migration.
+"""
+
+from coco_core.embeddings import Embeddings
+
+from coco.embeddings.base import init_embeddings
+
+__all__ = [
+    "Embeddings",
+    "init_embeddings",
+]

coco/embeddings/base.py

@@ -0,0 +1,279 @@
+"""Factory functions for embeddings."""
+
+import functools
+import importlib
+from collections.abc import Callable
+from typing import Any
+
+from coco_core.embeddings import Embeddings
+
+
+def _call(cls: type[Embeddings], **kwargs: Any) -> Embeddings:
+    return cls(**kwargs)
+
+
+_BUILTIN_PROVIDERS: dict[str, tuple[str, str, Callable[..., Embeddings]]] = {
+    "azure_ai": ("coco_azure_ai.embeddings", "AzureAIOpenAIApiEmbeddingsModel", _call),
+    "azure_openai": ("coco_openai", "AzureOpenAIEmbeddings", _call),
+    "bedrock": (
+        "coco_aws",
+        "BedrockEmbeddings",
+        lambda cls, model, **kwargs: cls(model_id=model, **kwargs),
+    ),
+    "cohere": ("coco_cohere", "CohereEmbeddings", _call),
+    "google_genai": ("coco_google_genai", "GoogleGenerativeAIEmbeddings", _call),
+    "google_vertexai": ("coco_google_vertexai", "VertexAIEmbeddings", _call),
+    "huggingface": (
+        "coco_huggingface",
+        "HuggingFaceEmbeddings",
+        lambda cls, model, **kwargs: cls(model_name=model, **kwargs),
+    ),
+    "mistralai": ("coco_mistralai", "MistralAIEmbeddings", _call),
+    "ollama": ("coco_ollama", "OllamaEmbeddings", _call),
+    "openai": ("coco_openai", "OpenAIEmbeddings", _call),
+}
+"""Registry mapping provider names to their import configuration.
+
+Each entry maps a provider key to a tuple of:
+
+- `module_path`: The Python module path containing the embeddings class.
+- `class_name`: The name of the embeddings class to import.
+- `creator_func`: A callable that instantiates the class with provided kwargs.
+
+!!! note
+
+    This dict is not exhaustive of all providers supported by Coco, but is
+    meant to cover the most popular ones and serve as a template for adding more
+    providers in the future. If a provider is not in this dict, it can still be
+    used with `init_chat_model` as long as its integration package is installed,
+    but the provider key will not be inferred from the model name and must be
+    specified explicitly via the `model_provider` parameter.
+
+    Refer to the Coco [integration documentation](https://docs.langchain.com/oss/python/integrations/providers/overview)
+    for a full list of supported providers and their corresponding packages.
+"""
+
+
+@functools.lru_cache(maxsize=len(_BUILTIN_PROVIDERS))
+def _get_embeddings_class_creator(provider: str) -> Callable[..., Embeddings]:
+    """Return a factory function that creates an embeddings model for the given provider.
+
+    This function is cached to avoid repeated module imports.
+
+    Args:
+        provider: The name of the model provider (e.g., `'openai'`, `'cohere'`).
+
+            Must be a key in `_BUILTIN_PROVIDERS`.
+
+    Returns:
+        A callable that accepts model kwargs and returns an `Embeddings` instance for
+            the specified provider.
+
+    Raises:
+        ValueError: If the provider is not in `_BUILTIN_PROVIDERS`.
+        ImportError: If the provider's integration package is not installed.
+    """
+    if provider not in _BUILTIN_PROVIDERS:
+        msg = (
+            f"Provider '{provider}' is not supported.\n"
+            f"Supported providers and their required packages:\n"
+            f"{_get_provider_list()}"
+        )
+        raise ValueError(msg)
+
+    module_name, class_name, creator_func = _BUILTIN_PROVIDERS[provider]
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as e:
+        top_level = module_name.split(".", maxsplit=1)[0]
+        pkg = top_level.replace("_", "-")
+        if top_level == "coco" or top_level.startswith("coco_"):
+            pkg = f"trust{pkg}"
+        msg = f"Could not import {pkg} python package. Please install it with `pip install {pkg}`"
+        raise ImportError(msg) from e
+
+    cls = getattr(module, class_name)
+    return functools.partial(creator_func, cls=cls)
+
+
+def _get_provider_list() -> str:
+    """Get formatted list of providers and their packages."""
+    return "\n".join(
+        f"  - {p}: {'trust' if pkg[0] == 'coco' or pkg[0].startswith('coco_') else ''}{pkg[0].replace('_', '-')}"
+        for p, pkg in _BUILTIN_PROVIDERS.items()
+    )
+
+
+def _parse_model_string(model_name: str) -> tuple[str, str]:
+    """Parse a model string into provider and model name components.
+
+    The model string should be in the format 'provider:model-name', where provider
+    is one of the supported providers.
+
+    Args:
+        model_name: A model string in the format 'provider:model-name'
+
+    Returns:
+        A tuple of (provider, model_name)
+
+    Example:
+        ```python
+        _parse_model_string("openai:text-embedding-3-small")
+        # Returns: ("openai", "text-embedding-3-small")
+
+        _parse_model_string("bedrock:amazon.titan-embed-text-v1")
+        # Returns: ("bedrock", "amazon.titan-embed-text-v1")
+        ```
+
+    Raises:
+        ValueError: If the model string is not in the correct format or
+            the provider is unsupported
+
+    """
+    if ":" not in model_name:
+        msg = (
+            f"Invalid model format '{model_name}'.\n"
+            f"Model name must be in format 'provider:model-name'\n"
+            f"Example valid model strings:\n"
+            f"  - openai:text-embedding-3-small\n"
+            f"  - bedrock:amazon.titan-embed-text-v1\n"
+            f"  - cohere:embed-english-v3.0\n"
+            f"Supported providers: {_BUILTIN_PROVIDERS.keys()}"
+        )
+        raise ValueError(msg)
+
+    provider, model = model_name.split(":", 1)
+    provider = provider.lower().strip()
+    model = model.strip()
+
+    if provider not in _BUILTIN_PROVIDERS:
+        msg = (
+            f"Provider '{provider}' is not supported.\n"
+            f"Supported providers and their required packages:\n"
+            f"{_get_provider_list()}"
+        )
+        raise ValueError(msg)
+    if not model:
+        msg = "Model name cannot be empty"
+        raise ValueError(msg)
+    return provider, model
+
+
+def _infer_model_and_provider(
+    model: str,
+    *,
+    provider: str | None = None,
+) -> tuple[str, str]:
+    if not model.strip():
+        msg = "Model name cannot be empty"
+        raise ValueError(msg)
+    if provider is None and ":" in model:
+        provider, model_name = _parse_model_string(model)
+    else:
+        model_name = model
+
+    if not provider:
+        msg = (
+            "Must specify either:\n"
+            "1. A model string in format 'provider:model-name'\n"
+            "   Example: 'openai:text-embedding-3-small'\n"
+            "2. Or explicitly set provider from: "
+            f"{_BUILTIN_PROVIDERS.keys()}"
+        )
+        raise ValueError(msg)
+
+    if provider not in _BUILTIN_PROVIDERS:
+        msg = (
+            f"Provider '{provider}' is not supported.\n"
+            f"Supported providers and their required packages:\n"
+            f"{_get_provider_list()}"
+        )
+        raise ValueError(msg)
+    return provider, model_name
+
+
+def init_embeddings(
+    model: str,
+    *,
+    provider: str | None = None,
+    **kwargs: Any,
+) -> Embeddings:
+    """Initialize an embedding model from a model name and optional provider.
+
+    !!! note
+
+        Requires the integration package for the chosen model provider to be installed.
+
+        See the `model_provider` parameter below for specific package names
+        (e.g., `pip install trustcoco-openai`).
+
+        Refer to the [provider integration's API reference](https://docs.langchain.com/oss/python/integrations/providers)
+        for supported model parameters to use as `**kwargs`.
+
+    Args:
+        model: The name of the model, e.g. `'openai:text-embedding-3-small'`.
+
+            You can also specify model and model provider in a single argument using
+            `'{model_provider}:{model}'` format, e.g. `'openai:text-embedding-3-small'`.
+        provider: The model provider if not specified as part of the model arg
+            (see above).
+
+            Supported `provider` values and the corresponding integration package
+            are:
+
+            - `openai`                  -> [`trustcoco-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `azure_ai`                -> [`trustcoco-azure-ai`](https://docs.langchain.com/oss/python/integrations/providers/microsoft)
+            - `azure_openai`            -> [`trustcoco-openai`](https://docs.langchain.com/oss/python/integrations/providers/openai)
+            - `bedrock`                 -> [`trustcoco-aws`](https://docs.langchain.com/oss/python/integrations/providers/aws)
+            - `cohere`                  -> [`trustcoco-cohere`](https://docs.langchain.com/oss/python/integrations/providers/cohere)
+            - `google_vertexai`         -> [`trustcoco-google-vertexai`](https://docs.langchain.com/oss/python/integrations/providers/google)
+            - `huggingface`             -> [`trustcoco-huggingface`](https://docs.langchain.com/oss/python/integrations/providers/huggingface)
+            - `mistralai`               -> [`trustcoco-mistralai`](https://docs.langchain.com/oss/python/integrations/providers/mistralai)
+            - `ollama`                  -> [`trustcoco-ollama`](https://docs.langchain.com/oss/python/integrations/providers/ollama)
+
+        **kwargs: Additional model-specific parameters passed to the embedding model.
+
+            These vary by provider. Refer to the specific model provider's
+            [integration reference](https://reference.langchain.com/python/integrations/)
+            for all available parameters.
+
+    Returns:
+        An `Embeddings` instance that can generate embeddings for text.
+
+    Raises:
+        ValueError: If the model provider is not supported or cannot be determined
+        ImportError: If the required provider package is not installed
+
+    ???+ example
+
+        ```python
+        # pip install coco trustcoco-openai
+
+        # Using a model string
+        model = init_embeddings("openai:text-embedding-3-small")
+        model.embed_query("Hello, world!")
+
+        # Using explicit provider
+        model = init_embeddings(model="text-embedding-3-small", provider="openai")
+        model.embed_documents(["Hello, world!", "Goodbye, world!"])
+
+        # With additional parameters
+        model = init_embeddings("openai:text-embedding-3-small", api_key="sk-...")
+        ```
+
+    !!! version-added "Added in `coco` 0.3.9"
+
+    """
+    if not model:
+        providers = _BUILTIN_PROVIDERS.keys()
+        msg = f"Must specify model name. Supported providers are: {', '.join(providers)}"
+        raise ValueError(msg)
+
+    provider, model_name = _infer_model_and_provider(model, provider=provider)
+    return _get_embeddings_class_creator(provider)(model=model_name, **kwargs)
+
+
+__all__ = [
+    "Embeddings",  # This one is for backwards compatibility
+    "init_embeddings",
+]

coco/mcp/__init__.py

@@ -0,0 +1,36 @@
+"""Coco MCP adapters for connecting MCP servers with Coco applications.
+
+Interrupt-driven elicitation has its own types — the interrupt payload, the
+answers a run resumes with, and the discriminator to recognize them by. Import
+those from `coco.mcp.elicitation`.
+
+!!! warning "This namespace is in beta"
+
+    `coco.mcp` is actively being worked on and its API may change. Importing
+    from it raises a `CocoBetaWarning` once per process. Silence it with
+    `warnings.filterwarnings("ignore", category=CocoBetaWarning)`, or scope
+    the suppression with `coco_core._api.suppress_coco_beta_warning()`.
+"""
+
+import warnings
+
+from coco_core._api import CocoBetaWarning
+
+from coco.mcp.adapter import MCPAdapter
+from coco.mcp.tools import MCPToolArtifact, as_coco_tool
+
+# Warned on import rather than through `@beta`, which annotates a function or
+# class and so only fires once something is called. The status belongs to the
+# whole namespace, and a caller should learn it when they reach for it —
+# including when they import a submodule directly, which runs this module first.
+warnings.warn(
+    "`coco.mcp` is in beta. It is actively being worked on, so the API may change.",
+    CocoBetaWarning,
+    stacklevel=2,
+)
+
+__all__ = [
+    "MCPAdapter",
+    "MCPToolArtifact",
+    "as_coco_tool",
+]

coco/mcp/adapter.py

@@ -0,0 +1,245 @@
+"""Adapt MCP tools into Coco tools suitable for `create_agent`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Final, TypeAlias
+
+from pydantic import AnyUrl, TypeAdapter, ValidationError
+from typing_extensions import Self
+
+from coco.mcp.elicitation import _arm_for_interrupts
+from coco.mcp.tools import as_coco_tool
+
+try:
+    from fastmcp.client import Client as FastMCPClient
+    from fastmcp.client.group import ClientGroup
+    from fastmcp.client.transports import ClientTransport
+    from fastmcp.mcp_config import MCPConfig
+    from mcp.server.mcpserver import MCPServer
+except ImportError as _import_error:
+    msg = "Please install FastMCP to use `MCPAdapter` — `pip install fastmcp`."
+    raise ImportError(msg) from _import_error
+
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from fastmcp import FastMCP
+    from coco_core.tools import BaseTool
+
+    # `CacheMode` is the MCP SDK's own type (SEP-2549); FastMCP re-imports it
+    # rather than defining its own, so this is the canonical source.
+    from mcp.client.caching import CacheMode
+else:
+    try:
+        from fastmcp import FastMCP
+    except ImportError:
+        # In-process FastMCP servers, and multi-server `MCPConfig` targets, live
+        # in the server half of FastMCP. The `mcp` extra installs it, but a
+        # caller who reached this module through a client-only install
+        # (`fastmcp-slim[client]`) can still use every other target type — so
+        # the annotation degrades rather than the import failing, the same way
+        # FastMCP degrades it in `fastmcp.client.transports.inference`.
+        FastMCP = Any
+
+
+MCPAdapterTarget: TypeAlias = (
+    FastMCPClient[Any]
+    | ClientGroup
+    | ClientTransport
+    | FastMCP
+    | MCPServer
+    | AnyUrl
+    | Path
+    | MCPConfig
+    | dict[str, Any]
+    | str
+)
+"""Anything `MCPAdapter` accepts as its `target`.
+
+Every transport `fastmcp.Client` accepts, plus a pre-built `fastmcp.Client`.
+
+A `str` target is the one member narrowed relative to `fastmcp.Client`: it must
+be an `http`/`https` URL. Local servers are reached through `Path`, an explicit
+transport, or `MCPConfig` — see `MCPAdapter`.
+
+`ClientGroup` is the one member `fastmcp.Client` does not accept at all, since a
+group is a peer of `Client` rather than a transport it could wrap.
+"""
+
+
+_URL_SCHEMES: Final = frozenset({"http", "https"})
+"""Schemes a `str` target may carry.
+
+The only schemes `fastmcp.Client` can reach a server over from a string, so
+nothing that would have connected is forbidden here. It selects that branch on
+a bare `str.startswith("http")` though, which also admits strings that are not
+URLs at all — those fail on connect there, and on construction here.
+"""
+
+_ANY_URL: Final = TypeAdapter(AnyUrl)
+
+
+def _validate_url_target(target: str) -> None:
+    """Reject a `str` target that is not an `http`/`https` URL.
+
+    `fastmcp.Client` infers a transport from a string by testing it as a
+    filesystem path *before* testing it as a URL, so a string naming an
+    existing `.py` or `.js` file launches that file as a subprocess. A string
+    that reaches an application from configuration, a request body, or a model
+    is expected to address a server over the network; letting it silently
+    select local execution instead makes the dangerous reading the implicit
+    one.
+
+    Args:
+        target: The string passed as the adapter's target.
+
+    Raises:
+        ValueError: If `target` is not an `http` or `https` URL.
+    """
+    hint = (
+        "To run a local MCP server over stdio, ask for it explicitly with "
+        "`Path('server.py')`, a `fastmcp` transport, or an `MCPConfig` — a bare "
+        "string is read as a URL so that it cannot silently become a subprocess."
+    )
+    try:
+        url = _ANY_URL.validate_python(target)
+    except ValidationError as validation_error:
+        msg = f"MCP target {target!r} is not a valid URL. {hint}"
+        raise ValueError(msg) from validation_error
+
+    # `AnyUrl` alone is not the boundary. It reads a Windows path such as
+    # `C:\server.py` as the scheme `c` and accepts it — and on Windows that
+    # path *does* resolve, so FastMCP would launch it. Schemes FastMCP cannot
+    # infer a transport from at all (`file:`, `ws:`) are refused here too, for
+    # an error that names the problem rather than "could not infer a transport".
+    if url.scheme not in _URL_SCHEMES:
+        msg = (
+            f"MCP target {target!r} has scheme {url.scheme!r}, but a string target must "
+            f"be an http or https URL. {hint}"
+        )
+        raise ValueError(msg)
+
+
+class MCPAdapter:
+    """Adapt an MCP target into Coco tools.
+
+    `MCPAdapter` uses FastMCP for protocol negotiation and connection management,
+    then converts discovered MCP tools into asynchronous Coco tools. The
+    resulting tools can be passed directly to `create_agent`.
+
+    Transport inference is delegated to `fastmcp.Client`, so a target may be a URL,
+    a local script path (launched over stdio), an in-process server, or an already
+    constructed client.
+
+    !!! warning "A string target must be an http(s) URL"
+
+        `fastmcp.Client` resolves a string by testing it as a filesystem path
+        before testing it as a URL, so a string naming an existing `.py` or `.js`
+        file launches that file as a subprocess. Because strings are the form a
+        target most often arrives in from configuration or from a model,
+        `MCPAdapter` rejects one that is not an `http` or `https` URL rather than
+        let it select local execution. Reach a local server through `Path`, a
+        `fastmcp` transport, or an `MCPConfig`, all of which say so explicitly.
+
+    A server that needs input mid-call is answered with a CocoGraph
+    `interrupt()`, so a human answers and the run resumes — see
+    `coco.mcp.elicitation`. This is the default: the adapter arms every
+    client it builds to advertise the elicitation capability and drives the
+    interrupt loop on each call. A server that never asks for input is
+    unaffected, since the loop only runs when the server returns a request.
+
+    A pre-built client (or `ClientGroup`) that already carries its own
+    elicitation handler is honored rather than overridden: its handler keeps
+    answering, and the adapter leaves the client as the caller built it. Only a
+    client with no handler is armed, and it is cloned first so the caller's own
+    object is never mutated.
+
+    Args:
+        target: MCP target accepted by `fastmcp.Client`, including an existing
+            FastMCP client. A `str` must be an `http`/`https` URL.
+
+    Example:
+        ```python
+        from coco.agents import create_agent
+        from coco.mcp import MCPAdapter
+
+        async with MCPAdapter("https://example.com/mcp") as adapter:
+            agent = create_agent("anthropic:claude-sonnet-5", await adapter.list_tools())
+            result = await agent.ainvoke({"messages": [{"role": "user", "content": "..."}]})
+        ```
+    """
+
+    def __init__(self, target: MCPAdapterTarget) -> None:
+        """Initialize the adapter around a FastMCP target, client, or group.
+
+        Each underlying client is armed to answer elicitation with an interrupt,
+        unless it already carries the caller's own handler, which is honored
+        instead. A caller's client is cloned rather than mutated. See the class
+        docstring.
+        """
+
+        def armed(client: FastMCPClient[Any]) -> FastMCPClient[Any]:
+            if getattr(client, "_elicitation_callback", None) is not None:
+                return client
+            clone = client.new()
+            _arm_for_interrupts(clone)
+            return clone
+
+        if isinstance(target, ClientGroup):
+            members = {name: armed(client) for name, client in target.clients.items()}
+            self._client: FastMCPClient[Any] | ClientGroup = ClientGroup(members)
+        elif isinstance(target, FastMCPClient):
+            self._client = armed(target)
+        else:
+            if isinstance(target, str):
+                _validate_url_target(target)
+            client = FastMCPClient(target)
+            _arm_for_interrupts(client)
+            self._client = client
+
+    @property
+    def client(self) -> FastMCPClient[Any] | ClientGroup:
+        """Return the underlying FastMCP client or group for advanced MCP operations."""
+        return self._client
+
+    async def __aenter__(self) -> Self:
+        """Connect the underlying client or group for the duration of the context."""
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Release this context's hold on the underlying client or group."""
+        await self._client.__aexit__(exc_type, exc_value, traceback)
+
+    async def list_tools(self, *, cache_mode: CacheMode = "use") -> list[BaseTool]:
+        """Discover and adapt MCP tools for use with Coco.
+
+        Args:
+            cache_mode: How discovery interacts with the client-side response
+                cache (SEP-2549). `use` serves a cached tool list when one is
+                present and still within the server's TTL hint, `refresh` calls
+                the server and repopulates the cache, and `bypass` skips the
+                cache entirely. The cache and its per-principal isolation are
+                configured on the client itself (`Client(cache=...)`); this only
+                selects how discovery reads it. Defaults to `use` so a
+                configured cache is honored — note this differs from a bare
+                `ClientGroup.list_tools()`, whose own default is `refresh`.
+
+        Returns:
+            Coco tools that invoke the corresponding MCP tools
+                asynchronously. Each holds the adapter's client, so the tools
+                stay callable after this adapter's context exits.
+        """
+        async with self:
+            remote_tools = await self._client.list_tools(cache_mode=cache_mode)
+            return [await as_coco_tool(tool, self._client) for tool in remote_tools]
+
+
+__all__ = ["MCPAdapter", "MCPAdapterTarget"]