ellements 0.2.0__py3-none-any.whl

ellements/core/llm/images.py

@@ -0,0 +1,226 @@
+"""Image input + image-generation response models and conversion helpers.
+
+This module owns the multimodal *input* type :class:`ImageInput` (URLs,
+data URIs, local files) and the *output* types
+:class:`GeneratedImage` / :class:`ImageGenerationResponse` for image-generation
+APIs. There is no separate vision client — callers compose ``ImageInput``
+content parts directly with :meth:`LLMClient.complete` for analysis tasks.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from .messages import ImageDetail, MessageContent
+
+_MEDIA_TYPE_BY_EXT: dict[str, str] = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+}
+
+
+class ImageInput(BaseModel):
+    """A multimodal image input for vision-capable LLMs.
+
+    Exactly one source must be provided: ``url`` (HTTP/HTTPS) or ``base64``.
+    Use the factory classmethods :meth:`from_url`, :meth:`from_base64`,
+    or :meth:`from_path` for convenience.
+    """
+
+    url: str | None = Field(default=None, description="HTTP(S) URL to image")
+    base64: str | None = Field(default=None, description="Base64-encoded image data")
+    media_type: str | None = Field(
+        default=None,
+        description="MIME type for base64 inputs (e.g. 'image/png')",
+    )
+    detail: ImageDetail = Field(default="auto", description="Vision detail level")
+
+    @model_validator(mode="after")
+    def _exactly_one_source(self) -> ImageInput:
+        if self.url is None and self.base64 is None:
+            raise ValueError("Either url or base64 must be provided")
+        if self.url is not None and self.base64 is not None:
+            raise ValueError("Only one of url or base64 should be provided")
+        if self.base64 is not None and not self.media_type:
+            raise ValueError("media_type is required when providing base64 data")
+        return self
+
+    @classmethod
+    def from_url(cls, url: str, detail: ImageDetail = "auto") -> ImageInput:
+        """Build an :class:`ImageInput` from an HTTP(S) URL."""
+        return cls(url=url, detail=detail)
+
+    @classmethod
+    def from_base64(
+        cls,
+        data: str,
+        media_type: str = "image/png",
+        detail: ImageDetail = "auto",
+    ) -> ImageInput:
+        """Build an :class:`ImageInput` from a base64-encoded image payload."""
+        return cls(base64=data, media_type=media_type, detail=detail)
+
+    @classmethod
+    def from_path(
+        cls,
+        path: str | Path,
+        media_type: str | None = None,
+        detail: ImageDetail = "auto",
+    ) -> ImageInput:
+        """Build an :class:`ImageInput` from a local file path."""
+        path_obj = Path(path)
+        if not path_obj.exists():
+            raise FileNotFoundError(f"Image file not found: {path}")
+
+        resolved_media_type = media_type
+        if resolved_media_type is None:
+            resolved_media_type = _MEDIA_TYPE_BY_EXT.get(path_obj.suffix.lower())
+            if resolved_media_type is None:
+                raise ValueError(
+                    f"Cannot determine media type for extension: {path_obj.suffix}. "
+                    "Please provide media_type explicitly."
+                )
+
+        encoded = base64.b64encode(path_obj.read_bytes()).decode("utf-8")
+        return cls(base64=encoded, media_type=resolved_media_type, detail=detail)
+
+    def to_message_part(self) -> MessageContent:
+        """Convert to the shared multimodal content representation."""
+        if self.url:
+            return MessageContent.image_part(url=self.url, detail=self.detail)
+        data_uri = f"data:{self.media_type};base64,{self.base64}"
+        return MessageContent.image_part(url=data_uri, detail=self.detail)
+
+    def to_litellm_part(self) -> dict[str, Any]:
+        """Convert to a LiteLLM-compatible message content part payload."""
+        return self.to_message_part().to_litellm_part()
+
+
+class GeneratedImage(BaseModel):
+    """A single image returned by an image-generation API."""
+
+    url: str | None = Field(default=None, description="URL to the generated image")
+    b64_json: str | None = Field(
+        default=None, description="Base64-encoded JSON payload of the image"
+    )
+    revised_prompt: str | None = Field(
+        default=None, description="Provider-revised prompt actually used"
+    )
+
+
+class ImageGenerationResponse(BaseModel):
+    """Normalized response from an image-generation API."""
+
+    created: int = Field(description="Unix timestamp when the image was created")
+    data: list[GeneratedImage] = Field(description="Generated images")
+    model: str | None = Field(default=None, description="Model used for generation")
+    usage: Any | None = Field(
+        default=None, description="Usage info (shape varies by provider)"
+    )
+
+
+def build_image_generation_request(
+    *,
+    prompt: str,
+    model: str | None,
+    n: int,
+    size: str | None,
+    quality: str | None,
+    style: str | None,
+    response_format: Literal["url", "b64_json"],
+    extra_params: dict[str, Any],
+) -> tuple[str, dict[str, Any]]:
+    """Build provider parameters for image-generation calls."""
+    target_model = model or "dall-e-3"
+    params: dict[str, Any] = {"prompt": prompt, "model": target_model, "n": n}
+
+    if "dall-e" in target_model.lower():
+        params["response_format"] = response_format
+    if size:
+        params["size"] = size
+    if quality:
+        params["quality"] = quality
+    if style:
+        params["style"] = style
+
+    params.update(extra_params)
+    return target_model, params
+
+
+def build_image_edit_request(
+    *,
+    prompt: str,
+    model: str | None,
+    n: int,
+    size: str | None,
+    quality: str | None,
+    extra_params: dict[str, Any],
+) -> tuple[str, dict[str, Any]]:
+    """Build provider parameters for image-*edit* calls (references + prompt).
+
+    The input image files are passed separately to the provider call; this
+    returns only the JSON-friendly parameters.
+    """
+    target_model = model or "gpt-image-1"
+    params: dict[str, Any] = {"prompt": prompt, "model": target_model, "n": n}
+    if size:
+        params["size"] = size
+    if quality:
+        params["quality"] = quality
+    params.update(extra_params)
+    return target_model, params
+
+
+def normalize_usage(usage_obj: Any) -> Any | None:
+    """Convert provider-specific usage payloads into serializable objects."""
+    if not usage_obj:
+        return None
+    if hasattr(usage_obj, "model_dump"):
+        return usage_obj.model_dump()
+    if hasattr(usage_obj, "dict"):
+        return usage_obj.dict()
+    if isinstance(usage_obj, dict):
+        return usage_obj
+    return {
+        key: getattr(usage_obj, key)
+        for key in dir(usage_obj)
+        if not key.startswith("_") and not callable(getattr(usage_obj, key))
+    }
+
+
+def parse_image_generation_response(
+    response: Any, *, target_model: str
+) -> ImageGenerationResponse:
+    """Normalize a LiteLLM image-generation response into a stable model."""
+    return ImageGenerationResponse(
+        created=response.created,
+        data=[
+            GeneratedImage(
+                url=img.get("url"),
+                b64_json=img.get("b64_json"),
+                revised_prompt=img.get("revised_prompt"),
+            )
+            for img in response.data
+        ],
+        model=getattr(response, "model", target_model),
+        usage=normalize_usage(getattr(response, "usage", None)),
+    )
+
+
+__all__ = [
+    "GeneratedImage",
+    "ImageGenerationResponse",
+    "ImageInput",
+    "build_image_edit_request",
+    "build_image_generation_request",
+    "normalize_usage",
+    "parse_image_generation_response",
+]

ellements/core/llm/messages.py

@@ -0,0 +1,202 @@
+"""Conversation and multimodal message primitives.
+
+This module defines the typed message model used throughout ellements:
+
+- :class:`MessageContent` — a single content part (text or image)
+- :class:`Message` — one message in a conversation
+- :class:`Conversation` — an ordered thread of messages plus optional system prompt
+
+Plus helpers for normalizing accepted inputs and building multimodal payloads.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Literal, Self, TypeAlias
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, field_validator
+
+ImageDetail: TypeAlias = Literal["auto", "low", "high"]
+
+_VALID_ROLES: frozenset[str] = frozenset({"system", "user", "assistant", "tool"})
+
+
+class ImageURLPart(BaseModel):
+    """Typed payload for the ``image_url`` field of an image content part.
+
+    Distinguishes between hosted URLs (``http://`` / ``https://``) and
+    data URIs (``data:image/...;base64,...``) only by inspection; the
+    distinction is opaque to the provider.
+    """
+
+    url: str = Field(description="HTTP(S) URL or data URI to the image")
+    detail: ImageDetail | None = Field(default=None, description="Vision detail level")
+
+    @property
+    def is_data_uri(self) -> bool:
+        """True if ``url`` is a base64-encoded data URI."""
+        return self.url.startswith("data:")
+
+
+class MessageContent(BaseModel):
+    """One typed content part: either text or an image reference."""
+
+    type: Literal["text", "image_url"] = Field(description="Content part type")
+    text: str | None = Field(default=None, description="Text content when type='text'")
+    image_url: ImageURLPart | None = Field(
+        default=None,
+        description="Image reference when type='image_url'",
+    )
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.type == "text" and not self.text:
+            raise ValueError("text must be provided when type='text'")
+        if self.type == "image_url" and self.image_url is None:
+            raise ValueError("image_url must be provided when type='image_url'")
+
+    @classmethod
+    def text_part(cls, text: str) -> MessageContent:
+        """Build a text content part."""
+        return cls(type="text", text=text)
+
+    @classmethod
+    def image_part(
+        cls,
+        *,
+        url: str,
+        detail: ImageDetail | None = None,
+    ) -> MessageContent:
+        """Build an image content part referencing *url* (URL or data URI)."""
+        return cls(type="image_url", image_url=ImageURLPart(url=url, detail=detail))
+
+    def to_litellm_part(self) -> dict[str, Any]:
+        """Convert the content part to LiteLLM-compatible payload."""
+        if self.type == "text":
+            return {"type": "text", "text": self.text}
+        assert self.image_url is not None  # checked in model_post_init
+        payload: dict[str, Any] = {"url": self.image_url.url}
+        if self.image_url.detail is not None:
+            payload["detail"] = self.image_url.detail
+        return {"type": "image_url", "image_url": payload}
+
+
+def content_parts_to_litellm(parts: Sequence[MessageContent]) -> list[dict[str, Any]]:
+    """Convert content parts into LiteLLM payloads."""
+    return [part.to_litellm_part() for part in parts]
+
+
+class Message(BaseModel):
+    """One message in a conversation thread."""
+
+    role: str = Field(description="Role of the message sender")
+    content: str | list[MessageContent] = Field(
+        description="Message content as plain text or multimodal parts",
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("role")
+    @classmethod
+    def _validate_role(cls, value: str) -> str:
+        if value not in _VALID_ROLES:
+            raise ValueError(
+                f"Invalid role {value!r}. "
+                f"Expected one of: {sorted(_VALID_ROLES)}."
+            )
+        return value
+
+
+class Conversation(BaseModel):
+    """Ordered thread of messages plus an optional system prompt."""
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    messages: list[Message] = Field(default_factory=list)
+    model: str = Field(description="The LLM model identifier")
+    system_prompt: str | None = Field(default=None)
+
+    def add_message(
+        self,
+        role: str,
+        content: str | list[MessageContent],
+        metadata: dict[str, Any] | None = None,
+    ) -> Self:
+        """Append a message to the thread.
+
+        Raises:
+            ValueError: If *role* is not one of ``system``, ``user``,
+                ``assistant``, or ``tool``.
+        """
+        self.messages.append(
+            Message(role=role, content=content, metadata=metadata or {})
+        )
+        return self
+
+    def user(
+        self,
+        content: str | list[MessageContent],
+        metadata: dict[str, Any] | None = None,
+    ) -> Self:
+        """Append a user message."""
+        return self.add_message("user", content, metadata)
+
+    def assistant(
+        self,
+        content: str | list[MessageContent],
+        metadata: dict[str, Any] | None = None,
+    ) -> Self:
+        """Append an assistant message."""
+        return self.add_message("assistant", content, metadata)
+
+    def system(
+        self,
+        content: str | list[MessageContent],
+        metadata: dict[str, Any] | None = None,
+    ) -> Self:
+        """Append a system message."""
+        return self.add_message("system", content, metadata)
+
+    def to_litellm_messages(self) -> list[dict[str, Any]]:
+        """Convert the conversation into LiteLLM message payloads."""
+        messages: list[dict[str, Any]] = []
+        if self.system_prompt:
+            messages.append({"role": "system", "content": self.system_prompt})
+
+        for msg in self.messages:
+            if isinstance(msg.content, str):
+                messages.append({"role": msg.role, "content": msg.content})
+                continue
+            messages.append(
+                {
+                    "role": msg.role,
+                    "content": content_parts_to_litellm(msg.content),
+                }
+            )
+
+        return messages
+
+
+MessageInput: TypeAlias = str | list[dict[str, Any]] | Conversation
+
+
+def normalize_message_input(messages: MessageInput) -> list[dict[str, Any]]:
+    """Normalize accepted message inputs into mutable LiteLLM-style payloads."""
+    if isinstance(messages, str):
+        return [{"role": "user", "content": messages}]
+    if isinstance(messages, Conversation):
+        return messages.to_litellm_messages()
+    return list(messages)
+
+
+def build_multimodal_user_message(
+    prompt: str,
+    parts: Sequence[MessageContent],
+) -> list[dict[str, Any]]:
+    """Build a single-user multimodal message payload combining text and parts."""
+    return [
+        {
+            "role": "user",
+            "content": content_parts_to_litellm(
+                [MessageContent.text_part(prompt), *parts]
+            ),
+        }
+    ]

ellements/core/llm/model_params.py

@@ -0,0 +1,66 @@
+"""Model-specific parameter filtering helpers for LiteLLM calls."""
+
+from __future__ import annotations
+
+import re
+import warnings
+from typing import Any
+
+# Model-specific parameter compatibility
+# Maps model patterns to sets of unsupported parameters.
+MODEL_PARAMETER_RESTRICTIONS = {
+    r"(openai/(responses/)?)?gpt-5(-.*)?": {
+        "temperature",
+        "top_p",
+        "presence_penalty",
+        "frequency_penalty",
+        "logprobs",
+        "top_logprobs",
+        "logit_bias",
+        "max_tokens",
+    },
+    r"o[34](-.*)?": {
+        "temperature",
+        "top_p",
+        "presence_penalty",
+        "frequency_penalty",
+        "logprobs",
+        "top_logprobs",
+        "logit_bias",
+    },
+}
+
+
+def get_unsupported_parameters(model: str) -> set[str]:
+    """Get the set of unsupported parameters for a given model."""
+    unsupported = set()
+
+    for pattern, restricted_params in MODEL_PARAMETER_RESTRICTIONS.items():
+        if re.match(pattern, model, re.IGNORECASE):
+            unsupported.update(restricted_params)
+
+    return unsupported
+
+
+def filter_parameters(model: str, **kwargs: Any) -> dict[str, Any]:
+    """Filter out parameters that are not supported by the given model."""
+    unsupported = get_unsupported_parameters(model)
+
+    filtered = {
+        key: value
+        for key, value in kwargs.items()
+        if key not in unsupported and value is not None
+    }
+
+    removed = set(kwargs.keys()) - set(filtered.keys())
+    removed_unsupported = {key for key in removed if kwargs[key] is not None}
+
+    if removed_unsupported:
+        warnings.warn(
+            f"Model '{model}' does not support parameters: {', '.join(sorted(removed_unsupported))}. "
+            f"These parameters have been automatically filtered out.",
+            UserWarning,
+            stacklevel=3,
+        )
+
+    return filtered

ellements/core/llm/protocol.py

@@ -0,0 +1,146 @@
+"""Structural protocols for LLM clients.
+
+:class:`LLMClientProtocol` describes the surface that
+:class:`ellements.core.LLMClient` exposes, decoupled from its concrete
+implementation. Consumers that only need a subset of the API (which is
+almost everyone — judges only need ``complete_structured``, strategies
+only need ``complete``) can use this Protocol or a narrower one
+defined locally, and tests can supply hand-rolled fakes without
+inheriting from :class:`LLMClient` or pulling in litellm.
+
+Structural typing (:pep:`544`) means **any** object with the right
+methods satisfies the Protocol — the implementation does **not** need
+to inherit from or know about :class:`LLMClientProtocol`. The
+``@runtime_checkable`` decorator additionally enables ``isinstance``
+checks at runtime, though those only verify method *names*, not
+signatures.
+
+Why a single big Protocol rather than per-method micro-Protocols?
+Because the same client routinely fields many methods, and consumers
+that already type-check against this Protocol can use any combination
+without further imports. Tests/mocks that only implement what they
+need still pass mypy (Protocols are structural, so missing methods
+only error at the call site).
+
+If you need finer-grained Protocols (interface segregation for unit
+tests of small, focused functions), define them locally — they are
+cheap and don't require coordination with this module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterable, Mapping
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+from ..tools import ToolCallResponse, ToolDialect, ToolExecutor, ToolRegistry
+from .images import ImageGenerationResponse
+from .messages import Conversation, MessageInput
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class LLMClientProtocol(Protocol):
+    """The complete public surface of an ellements LLM client.
+
+    Attributes:
+        model: The default model identifier used when callers omit
+            ``model=`` on a per-call basis.
+    """
+
+    model: str
+
+    async def complete(
+        self,
+        messages: MessageInput,
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Generate a single text completion. See
+        :meth:`ellements.core.LLMClient.complete`."""
+
+    async def complete_structured(
+        self,
+        messages: MessageInput,
+        response_model: type[T],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> T:
+        """Generate a Pydantic-validated structured completion. See
+        :meth:`ellements.core.LLMClient.complete_structured`."""
+
+    async def complete_with_tools(
+        self,
+        messages: MessageInput,
+        tools: ToolRegistry | Mapping[str, Any] | Iterable[Any],
+        *,
+        tool_executor: ToolExecutor | None = None,
+        dialect: ToolDialect | None = None,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        max_iterations: int = 10,
+        **kwargs: Any,
+    ) -> ToolCallResponse:
+        """Run a multi-turn completion loop with tool calling. See
+        :meth:`ellements.core.LLMClient.complete_with_tools`."""
+
+    def stream(
+        self,
+        messages: MessageInput,
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[str]:
+        """Stream completion tokens. See
+        :meth:`ellements.core.LLMClient.stream`."""
+
+    async def continue_conversation(
+        self,
+        conversation: Conversation,
+        user_message: str,
+        *,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Append a user turn + assistant response. See
+        :meth:`ellements.core.LLMClient.continue_conversation`."""
+
+    async def loglikelihood(
+        self,
+        context: str,
+        continuation: str,
+        *,
+        model: str | None = None,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> tuple[float, bool]:
+        """Compute log-likelihood of *continuation* given *context*. See
+        :meth:`ellements.core.LLMClient.loglikelihood`."""
+
+    async def generate_image(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        n: int = 1,
+        size: str | None = None,
+        quality: str | None = None,
+        style: str | None = None,
+        response_format: str = "url",
+        **kwargs: Any,
+    ) -> ImageGenerationResponse:
+        """Generate images from a text prompt. See
+        :meth:`ellements.core.LLMClient.generate_image`."""
+
+
+__all__ = ["LLMClientProtocol"]