coco-framework 0.1.0__py3-none-any.whl

coco_core/language_models/model_profile.py

@@ -0,0 +1,183 @@
+"""Model profile types and utilities."""
+
+import logging
+import warnings
+from typing import get_type_hints
+
+from pydantic import ConfigDict
+from typing_extensions import TypedDict
+
+logger = logging.getLogger(__name__)
+
+
+class ModelProfile(TypedDict, total=False):
+    """Description of a chat model's capabilities, exposed via `model.profile`.
+
+    See the
+    [model profiles guide](https://docs.langchain.com/oss/python/langchain/models#model-profiles)
+    for concepts and usage. Data is sourced from
+    [models.dev](https://github.com/sst/models.dev), augmented with additional
+    fields, and generated by the
+    [`trustcoco-model-profiles`](https://github.com/langchain-ai/langchain/tree/master/libs/model-profiles)
+    package (via its `trustcoco-profiles` CLI).
+
+    !!! warning "Beta feature"
+
+        Fields and format are subject to change. This is a `total=False`
+        `TypedDict`, so any field may be absent — guard accesses with `.get()`.
+    """
+
+    __pydantic_config__ = ConfigDict(extra="allow")  # type: ignore[misc]
+
+    # --- Model metadata ---
+
+    name: str
+    """Human-readable model name (e.g., `'GPT-5'`)."""
+
+    status: str
+    """Model lifecycle status (e.g., `'active'`, `'deprecated'`)."""
+
+    release_date: str
+    """Model release date (ISO 8601 format, e.g., `'2025-06-01'`)."""
+
+    last_updated: str
+    """Date the model was last updated (ISO 8601 format)."""
+
+    open_weights: bool
+    """Whether the model weights are openly available."""
+
+    # --- Input constraints ---
+
+    max_input_tokens: int
+    """Maximum context window (tokens)."""
+
+    text_inputs: bool
+    """Whether text inputs are supported."""
+
+    image_inputs: bool
+    """Whether image inputs are supported."""
+    # TODO: add more detail about formats?
+
+    image_url_inputs: bool
+    """Whether [image URL inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)
+    are supported."""
+
+    pdf_inputs: bool
+    """Whether [PDF inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)
+    are supported."""
+    # TODO: add more detail about formats? e.g. bytes or base64
+
+    audio_inputs: bool
+    """Whether [audio inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)
+    are supported."""
+    # TODO: add more detail about formats? e.g. bytes or base64
+
+    video_inputs: bool
+    """Whether [video inputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)
+    are supported."""
+    # TODO: add more detail about formats? e.g. bytes or base64
+
+    image_tool_message: bool
+    """Whether images can be included in `ToolMessage` content."""
+
+    pdf_tool_message: bool
+    """Whether PDFs can be included in `ToolMessage` content."""
+
+    # --- Output constraints ---
+
+    max_output_tokens: int
+    """Maximum output tokens."""
+
+    reasoning_output: bool
+    """Whether the model supports [reasoning / chain-of-thought](https://docs.langchain.com/oss/python/langchain/models#reasoning)."""
+
+    reasoning_effort_levels: list[str]
+    """Supported reasoning-effort levels (e.g. `['low', 'medium', 'high']`).
+
+    Absent or empty if the model does not support a configurable reasoning
+    effort. Only meaningful when `reasoning_output` is `True`.
+    """
+
+    reasoning_effort_default: str
+    """The provider's documented default reasoning-effort level, if known.
+
+    Absent when no default is documented. Only meaningful when
+    `reasoning_effort_levels` is non-empty; not necessarily a member of
+    `reasoning_effort_levels` itself (a model may default to unconfigurable
+    behavior distinct from any explicit level).
+    """
+
+    text_outputs: bool
+    """Whether text outputs are supported."""
+
+    image_outputs: bool
+    """Whether [image outputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)
+    are supported."""
+
+    audio_outputs: bool
+    """Whether [audio outputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)
+    are supported."""
+
+    video_outputs: bool
+    """Whether [video outputs](https://docs.langchain.com/oss/python/langchain/models#multimodal)
+    are supported."""
+
+    # --- Tool calling ---
+    tool_calling: bool
+    """Whether the model supports [tool calling](https://docs.langchain.com/oss/python/langchain/models#tool-calling)."""
+
+    tool_choice: bool
+    """Whether the model supports [tool choice](https://docs.langchain.com/oss/python/langchain/models#forcing-tool-calls)."""
+
+    tool_call_streaming: bool
+    """Whether the model returns properly structured `tool_call_chunks` when streaming.
+
+    Only meaningful when `tool_calling` is `True`.
+    """
+
+    # --- Structured output ---
+    structured_output: bool
+    """Whether the model supports native [structured output](https://docs.langchain.com/oss/python/langchain/models#structured-outputs)."""
+
+    # --- Other capabilities ---
+
+    attachment: bool
+    """Whether the model supports file attachments."""
+
+    temperature: bool
+    """Whether the model supports a temperature parameter."""
+
+
+ModelProfileRegistry = dict[str, ModelProfile]
+"""Registry mapping model identifiers or names to their ModelProfile."""
+
+
+def _warn_unknown_profile_keys(profile: ModelProfile) -> None:
+    """Warn if `profile` contains keys not declared on `ModelProfile`.
+
+    Args:
+        profile: The model profile dict to check for undeclared keys.
+    """
+    if not isinstance(profile, dict):
+        return  # type: ignore[unreachable]
+
+    try:
+        declared = frozenset(get_type_hints(ModelProfile).keys())
+    except (TypeError, NameError):
+        # get_type_hints raises NameError on unresolvable forward refs and
+        # TypeError when annotations evaluate to non-type objects.
+        logger.debug(
+            "Could not resolve type hints for ModelProfile; "
+            "skipping unknown-key check.",
+            exc_info=True,
+        )
+        return
+
+    extra = sorted(set(profile) - declared)
+    if extra:
+        warnings.warn(
+            f"Unrecognized keys in model profile: {extra}. "
+            f"This may indicate a version mismatch between trustcoco-core "
+            f"and your provider package. Consider upgrading trustcoco-core.",
+            stacklevel=2,
+        )

coco_core/load/__init__.py

@@ -0,0 +1,44 @@
+"""**Load** module helps with serialization and deserialization."""
+
+from typing import TYPE_CHECKING
+
+from coco_core._import_utils import import_attr
+
+if TYPE_CHECKING:
+    from coco_core.load.dump import dumpd, dumps
+    from coco_core.load.load import InitValidator, loads
+    from coco_core.load.serializable import Serializable
+
+# Unfortunately, we have to eagerly import load from coco_core/load/load.py
+# eagerly to avoid a namespace conflict. We want users to still be able to use
+# `from coco_core.load import load` to get the load function, but
+# the `from coco_core.load.load import load` absolute import should also work.
+from coco_core.load.load import load
+
+__all__ = (
+    "InitValidator",
+    "Serializable",
+    "dumpd",
+    "dumps",
+    "load",
+    "loads",
+)
+
+_dynamic_imports = {
+    "dumpd": "dump",
+    "dumps": "dump",
+    "InitValidator": "load",
+    "loads": "load",
+    "Serializable": "serializable",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    result = import_attr(attr_name, module_name, __spec__.parent)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

coco_core/load/_validation.py

@@ -0,0 +1,191 @@
+"""Validation utilities for Coco serialization.
+
+Provides escape-based protection against injection attacks in serialized objects. The
+approach uses an allowlist design: only dicts explicitly produced by
+`Serializable.to_json()` are treated as LC objects during deserialization.
+
+## How escaping works
+
+During serialization, plain dicts (user data) that contain an `'lc'` key are wrapped:
+
+```python
+{"lc": 1, ...}  # user data that looks like LC object
+# becomes:
+{"__lc_escaped__": {"lc": 1, ...}}
+```
+
+During deserialization, escaped dicts are unwrapped and returned as plain dicts,
+NOT instantiated as LC objects.
+"""
+
+from typing import Any, cast
+
+from coco_core.load.serializable import (
+    Serializable,
+    to_json_not_implemented,
+)
+
+_LC_ESCAPED_KEY = "__lc_escaped__"
+"""Sentinel key used to mark escaped user dicts during serialization.
+
+When a plain dict contains 'lc' key (which could be confused with LC objects),
+we wrap it as {"__lc_escaped__": {...original...}}.
+"""
+
+
+def _needs_escaping(obj: dict[str, Any]) -> bool:
+    """Check if a dict needs escaping to prevent confusion with LC objects.
+
+    A dict needs escaping if:
+
+    1. It has an `'lc'` key (could be confused with LC serialization format)
+    2. It has only the escape key (would be mistaken for an escaped dict)
+    """
+    return "lc" in obj or (len(obj) == 1 and _LC_ESCAPED_KEY in obj)
+
+
+def _escape_dict(obj: dict[str, Any]) -> dict[str, Any]:
+    """Wrap a dict in the escape marker.
+
+    Example:
+        ```python
+        {"key": "value"}  # becomes {"__lc_escaped__": {"key": "value"}}
+        ```
+    """
+    return {_LC_ESCAPED_KEY: obj}
+
+
+def _is_escaped_dict(obj: dict[str, Any]) -> bool:
+    """Check if a dict is an escaped user dict.
+
+    Example:
+        ```python
+        {"__lc_escaped__": {...}}  # is an escaped dict
+        ```
+    """
+    return len(obj) == 1 and _LC_ESCAPED_KEY in obj
+
+
+def _serialize_value(obj: Any) -> Any:
+    """Serialize a value with escaping of user dicts.
+
+    Called recursively on kwarg values to escape any plain dicts that could be confused
+    with LC objects.
+
+    Args:
+        obj: The value to serialize.
+
+    Returns:
+        The serialized value with user dicts escaped as needed.
+    """
+    if isinstance(obj, Serializable):
+        # This is an LC object - serialize it properly (not escaped)
+        return _serialize_lc_object(obj)
+    if isinstance(obj, dict):
+        if not all(isinstance(k, (str, int, float, bool, type(None))) for k in obj):
+            # if keys are not json serializable
+            return to_json_not_implemented(obj)
+        # Check if dict needs escaping BEFORE recursing into values.
+        # If it needs escaping, wrap it as-is - the contents are user data that
+        # will be returned as-is during deserialization (no instantiation).
+        # This prevents re-escaping of already-escaped nested content.
+        if _needs_escaping(obj):
+            return _escape_dict(obj)
+        # Safe dict (no 'lc' key) - recurse into values
+        return {k: _serialize_value(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_serialize_value(item) for item in obj]
+    if isinstance(obj, (str, int, float, bool, type(None))):
+        return obj
+
+    # Non-JSON-serializable object (datetime, custom objects, etc.)
+    return to_json_not_implemented(obj)
+
+
+def _get_secret_keys(obj: Serializable) -> set[str]:
+    """Return the merged set of constructor kwarg names declared as secrets.
+
+    Mirrors the MRO walk in `Serializable.to_json` so the keys returned here
+    match the keys whose values `_replace_secrets` rewrites into secret
+    markers. Used by `_serialize_lc_object` to decide which kwargs to skip
+    when escaping user data.
+    """
+    secrets: dict[str, str] = {}
+    model_fields = type(obj).model_fields
+    for cls in [None, *obj.__class__.mro()]:
+        if cls is Serializable:
+            break
+        this = cast("Serializable", obj if cls is None else super(cls, obj))
+        secrets.update(this.lc_secrets)
+        for key in list(secrets):
+            if (key in model_fields) and (alias := model_fields[key].alias) is not None:
+                secrets[alias] = secrets[key]
+    return set(secrets)
+
+
+def _serialize_lc_object(obj: Any) -> dict[str, Any]:
+    """Serialize a `Serializable` object with escaping of user data in kwargs.
+
+    Args:
+        obj: The `Serializable` object to serialize.
+
+    Returns:
+        The serialized dict with user data in kwargs escaped as needed.
+
+    Note:
+        Kwargs values are processed with `_serialize_value` to escape user data
+        (like metadata) that contains `'lc'` keys. Secret fields are identified
+        by the class's declared `lc_secrets` and skipped because `to_json()`
+        already converted their values to secret markers.
+
+        The check is key-based rather than shape-based. A shape-based check
+        ("this dict looks like a secret marker") can be forged by user data,
+        letting attacker-controlled free-form dicts bypass escaping and reach
+        the Reviver.
+    """
+    if not isinstance(obj, Serializable):
+        msg = f"Expected Serializable, got {type(obj)}"
+        raise TypeError(msg)
+
+    serialized: dict[str, Any] = dict(obj.to_json())
+
+    # Process kwargs to escape user data that could be confused with LC objects.
+    # Skip kwargs declared as secrets - `to_json()` already replaced their
+    # values with secret markers via `_replace_secrets`.
+    if serialized.get("type") == "constructor" and "kwargs" in serialized:
+        secret_keys = _get_secret_keys(obj)
+        serialized["kwargs"] = {
+            k: v if k in secret_keys else _serialize_value(v)
+            for k, v in serialized["kwargs"].items()
+        }
+
+    return serialized
+
+
+def _unescape_value(obj: Any) -> Any:
+    """Unescape a value, processing escape markers in dict values and lists.
+
+    When an escaped dict is encountered (`{"__lc_escaped__": ...}`), it's
+    unwrapped and the contents are returned AS-IS (no further processing).
+    The contents represent user data that should not be modified.
+
+    For regular dicts and lists, we recurse to find any nested escape markers.
+
+    Args:
+        obj: The value to unescape.
+
+    Returns:
+        The unescaped value.
+    """
+    if isinstance(obj, dict):
+        if _is_escaped_dict(obj):
+            # Unwrap and return the user data as-is (no further unescaping).
+            # The contents are user data that may contain more escape keys,
+            # but those are part of the user's actual data.
+            return obj[_LC_ESCAPED_KEY]
+
+        # Regular dict - recurse into values to find nested escape markers
+        return {k: _unescape_value(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_unescape_value(item) for item in obj]
+    return obj

coco_core/load/dump.py

@@ -0,0 +1,120 @@
+"""Serialize Coco objects to JSON.
+
+Provides `dumps` (to JSON string) and `dumpd` (to dict) for serializing
+`Serializable` objects.
+
+## Escaping
+
+During serialization, plain dicts (user data) that contain an `'lc'` key are escaped
+by wrapping them: `{"__lc_escaped__": {...original...}}`. This prevents injection
+attacks where malicious data could trick the deserializer into instantiating
+arbitrary classes. The escape marker is removed during deserialization.
+
+This is an allowlist approach: only dicts explicitly produced by
+`Serializable.to_json()` are treated as LC objects; everything else is escaped if it
+could be confused with the LC format.
+"""
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+from coco_core.load._validation import _serialize_value
+from coco_core.load.serializable import Serializable, to_json_not_implemented
+from coco_core.messages import AIMessage
+from coco_core.outputs import ChatGeneration
+
+
+def default(obj: Any) -> Any:
+    """Return a default value for an object.
+
+    Args:
+        obj: The object to serialize to json if it is a Serializable object.
+
+    Returns:
+        A JSON serializable object or a SerializedNotImplemented object.
+    """
+    if isinstance(obj, Serializable):
+        return obj.to_json()
+    return to_json_not_implemented(obj)
+
+
+def _dump_pydantic_models(obj: Any) -> Any:
+    """Convert nested Pydantic models to dicts for JSON serialization.
+
+    Handles the special case where a `ChatGeneration` contains an `AIMessage`
+    with a parsed Pydantic model in `additional_kwargs["parsed"]`. Since
+    Pydantic models aren't directly JSON serializable, this converts them to
+    dicts.
+
+    Args:
+        obj: The object to process.
+
+    Returns:
+        A copy of the object with nested Pydantic models converted to dicts, or
+            the original object unchanged if no conversion was needed.
+    """
+    if (
+        isinstance(obj, ChatGeneration)
+        and isinstance(obj.message, AIMessage)
+        and (parsed := obj.message.additional_kwargs.get("parsed"))
+        and isinstance(parsed, BaseModel)
+    ):
+        obj_copy = obj.model_copy(deep=True)
+        obj_copy.message.additional_kwargs["parsed"] = parsed.model_dump()
+        return obj_copy
+    return obj
+
+
+def dumps(obj: Any, *, pretty: bool = False, **kwargs: Any) -> str:
+    """Return a JSON string representation of an object.
+
+    Note:
+        Plain dicts containing an `'lc'` key are automatically escaped to prevent
+        confusion with LC serialization format. The escape marker is removed during
+        deserialization.
+
+    Args:
+        obj: The object to dump.
+        pretty: Whether to pretty print the json.
+
+            If `True`, the json will be indented by either 2 spaces or the amount
+            provided in the `indent` kwarg.
+        **kwargs: Additional arguments to pass to `json.dumps`
+
+    Returns:
+        A JSON string representation of the object.
+
+    Raises:
+        ValueError: If `default` is passed as a kwarg.
+    """
+    if "default" in kwargs:
+        msg = "`default` should not be passed to dumps"
+        raise ValueError(msg)
+
+    obj = _dump_pydantic_models(obj)
+    serialized = _serialize_value(obj)
+
+    if pretty:
+        indent = kwargs.pop("indent", 2)
+        return json.dumps(serialized, indent=indent, **kwargs)
+    return json.dumps(serialized, **kwargs)
+
+
+def dumpd(obj: Any) -> Any:
+    """Return a dict representation of an object.
+
+    Note:
+        Plain dicts containing an `'lc'` key are automatically escaped to prevent
+        confusion with LC serialization format. The escape marker is removed during
+        deserialization.
+
+    Args:
+        obj: The object to dump.
+
+    Returns:
+        Dictionary that can be serialized to json using `json.dumps`.
+    """
+    obj = _dump_pydantic_models(obj)
+    return _serialize_value(obj)