casual-llm 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

casual_llm/__init__.py

@@ -7,7 +7,7 @@ A simple, protocol-based library for working with different LLM providers
 Part of the casual-* ecosystem of lightweight AI tools.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 # Model configuration
 from casual_llm.config import ModelConfig, Provider
@@ -29,6 +29,10 @@ from casual_llm.messages import (
     ToolResultMessage,
     AssistantToolCall,
     AssistantToolCallFunction,
+    StreamChunk,
+    # Multimodal content types
+    TextContent,
+    ImageContent,
 )
 
 # Tool models
@@ -71,6 +75,10 @@ __all__ = [
     "ToolResultMessage",
     "AssistantToolCall",
     "AssistantToolCallFunction",
+    "StreamChunk",
+    # Multimodal content types
+    "TextContent",
+    "ImageContent",
     # Tools
     "Tool",
     "ToolParameter",

casual_llm/message_converters/ollama.py

@@ -13,6 +13,12 @@ from casual_llm.messages import (
     ChatMessage,
     AssistantToolCall,
     AssistantToolCallFunction,
+    TextContent,
+    ImageContent,
+)
+from casual_llm.utils.image import (
+    strip_base64_prefix,
+    fetch_image_as_base64,
 )
 
 if TYPE_CHECKING:
@@ -21,23 +27,101 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def convert_messages_to_ollama(messages: list[ChatMessage]) -> list[dict[str, Any]]:
+async def _convert_image_to_ollama(image: ImageContent) -> str:
+    """
+    Convert ImageContent to Ollama base64 format.
+
+    Ollama expects images as raw base64 strings (no data URI prefix).
+
+    For URL sources, this function fetches the image and converts to base64.
+
+    Raises:
+        ImageFetchError: If a URL image cannot be fetched.
+    """
+    if isinstance(image.source, str):
+        # Check if it's a data URI or a URL
+        if image.source.startswith("data:"):
+            # Data URI - extract base64 data
+            return strip_base64_prefix(image.source)
+        else:
+            # Regular URL - fetch and convert to base64
+            logger.debug(f"Fetching image from URL for Ollama: {image.source}")
+            base64_data, _ = await fetch_image_as_base64(image.source)
+            return base64_data
+    else:
+        # Base64 dict source - use directly
+        base64_data = image.source.get("data", "")
+        # Strip any data URI prefix that might be present
+        return strip_base64_prefix(base64_data)
+
+
+async def _convert_user_content_to_ollama(
+    content: str | list[TextContent | ImageContent] | None,
+) -> tuple[str, list[str]]:
+    """
+    Convert UserMessage content to Ollama format.
+
+    Handles both simple string content (backward compatible) and
+    multimodal content arrays (text + images).
+
+    Ollama uses a format where text goes in "content" and images
+    go in a separate "images" array as raw base64 strings.
+
+    Returns:
+        A tuple of (text_content, images_list) where:
+            - text_content: Combined text from all TextContent items
+            - images_list: List of base64-encoded image strings
+
+    Raises:
+        ImageFetchError: If a URL image cannot be fetched.
+    """
+    if content is None:
+        return "", []
+
+    if isinstance(content, str):
+        # Simple string content
+        return content, []
+
+    # Multimodal content array
+    text_parts: list[str] = []
+    images: list[str] = []
+
+    for item in content:
+        if isinstance(item, TextContent):
+            text_parts.append(item.text)
+        elif isinstance(item, ImageContent):
+            images.append(await _convert_image_to_ollama(item))
+
+    # Join text parts with newlines
+    text_content = "\n".join(text_parts) if text_parts else ""
+
+    return text_content, images
+
+
+async def convert_messages_to_ollama(messages: list[ChatMessage]) -> list[dict[str, Any]]:
     """
     Convert casual-llm ChatMessage list to Ollama format.
 
     Unlike OpenAI which expects tool call arguments as JSON strings,
     Ollama expects them as dictionaries. This function handles that conversion.
 
+    Supports multimodal messages with images. Ollama expects images as raw
+    base64 strings in a separate "images" array.
+
     Args:
         messages: List of ChatMessage objects
 
     Returns:
         List of dictionaries in Ollama message format
 
+    Raises:
+        ImageFetchError: If a URL image cannot be fetched.
+
     Examples:
+        >>> import asyncio
         >>> from casual_llm import UserMessage
         >>> messages = [UserMessage(content="Hello")]
-        >>> ollama_msgs = convert_messages_to_ollama(messages)
+        >>> ollama_msgs = asyncio.run(convert_messages_to_ollama(messages))
         >>> ollama_msgs[0]["role"]
         'user'
     """
@@ -97,7 +181,11 @@ def convert_messages_to_ollama(messages: list[ChatMessage]) -> list[dict[str, An
                 )
 
             case "user":
-                ollama_messages.append({"role": "user", "content": msg.content})
+                text_content, images = await _convert_user_content_to_ollama(msg.content)
+                user_message: dict[str, Any] = {"role": "user", "content": text_content}
+                if images:
+                    user_message["images"] = images
+                ollama_messages.append(user_message)
 
             case _:
                 logger.warning(f"Unknown message role: {msg.role}")

casual_llm/message_converters/openai.py

@@ -11,6 +11,8 @@ from casual_llm.messages import (
     ChatMessage,
     AssistantToolCall,
     AssistantToolCallFunction,
+    TextContent,
+    ImageContent,
 )
 
 if TYPE_CHECKING:
@@ -19,6 +21,55 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _convert_image_to_openai(image: ImageContent) -> dict[str, Any]:
+    """
+    Convert ImageContent to OpenAI image_url format.
+
+    OpenAI expects images in the format:
+    {"type": "image_url", "image_url": {"url": "..."}}
+
+    For base64 images, the URL should be a data URI:
+    data:image/jpeg;base64,...
+    """
+    if isinstance(image.source, str):
+        # URL source - use directly
+        image_url = image.source
+    else:
+        # Base64 dict source - construct data URI
+        base64_data = image.source.get("data", "")
+        image_url = f"data:{image.media_type};base64,{base64_data}"
+
+    return {
+        "type": "image_url",
+        "image_url": {"url": image_url},
+    }
+
+
+def _convert_user_content_to_openai(
+    content: str | list[TextContent | ImageContent] | None,
+) -> str | list[dict[str, Any]] | None:
+    """
+    Convert UserMessage content to OpenAI format.
+
+    Handles both simple string content (backward compatible) and
+    multimodal content arrays (text + images).
+    """
+    if content is None or isinstance(content, str):
+        # Simple string content or None - pass through
+        return content
+
+    # Multimodal content array
+    openai_content: list[dict[str, Any]] = []
+
+    for item in content:
+        if isinstance(item, TextContent):
+            openai_content.append({"type": "text", "text": item.text})
+        elif isinstance(item, ImageContent):
+            openai_content.append(_convert_image_to_openai(item))
+
+    return openai_content
+
+
 def convert_messages_to_openai(messages: list[ChatMessage]) -> list[dict[str, Any]]:
     """
     Convert casual-llm ChatMessage list to OpenAI format.
@@ -86,7 +137,12 @@ def convert_messages_to_openai(messages: list[ChatMessage]) -> list[dict[str, An
                 )
 
             case "user":
-                openai_messages.append({"role": "user", "content": msg.content})
+                openai_messages.append(
+                    {
+                        "role": "user",
+                        "content": _convert_user_content_to_openai(msg.content),
+                    }
+                )
 
             case _:
                 logger.warning(f"Unknown message role: {msg.role}")

casual_llm/messages.py

@@ -10,6 +10,37 @@ from typing import Literal, TypeAlias
 from pydantic import BaseModel
 
 
+class TextContent(BaseModel):
+    """Text content block for multimodal messages."""
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ImageContent(BaseModel):
+    """Image content block for multimodal messages.
+
+    Supports both URL strings and base64-encoded image data.
+
+    Examples:
+        # URL source
+        ImageContent(type="image", source="https://example.com/image.jpg")
+
+        # Base64 source (dict format)
+        ImageContent(
+            type="image",
+            source={"type": "base64", "data": "...base64..."},
+            media_type="image/png"
+        )
+    """
+
+    type: Literal["image"] = "image"
+    source: str | dict[str, str]
+    """URL string or dict with {type: "base64", data: "..."} format."""
+    media_type: str = "image/jpeg"
+    """MIME type of the image (e.g., image/jpeg, image/png, image/gif, image/webp)."""
+
+
 class AssistantToolCallFunction(BaseModel):
     """Function call within an assistant tool call."""
 
@@ -50,10 +81,30 @@ class ToolResultMessage(BaseModel):
 
 
 class UserMessage(BaseModel):
-    """Message from the user."""
+    """Message from the user.
+
+    Supports both simple text content and multimodal content (text + images).
+
+    Examples:
+        # Simple text content
+        UserMessage(content="Hello, world!")
+
+        # Multimodal content
+        UserMessage(content=[
+            TextContent(type="text", text="What's in this image?"),
+            ImageContent(type="image", source="https://example.com/image.jpg")
+        ])
+    """
 
     role: Literal["user"] = "user"
-    content: str | None
+    content: str | list[TextContent | ImageContent] | None
+
+
+class StreamChunk(BaseModel):
+    """A chunk of streamed response content from an LLM provider."""
+
+    content: str
+    finish_reason: str | None = None
 
 
 ChatMessage: TypeAlias = AssistantMessage | SystemMessage | ToolResultMessage | UserMessage

casual_llm/providers/base.py

@@ -7,11 +7,11 @@ using standard OpenAI-compatible message formats.
 
 from __future__ import annotations
 
-from typing import Protocol, Literal
+from typing import Protocol, Literal, AsyncIterator
 
 from pydantic import BaseModel
 
-from casual_llm.messages import ChatMessage, AssistantMessage
+from casual_llm.messages import ChatMessage, AssistantMessage, StreamChunk
 from casual_llm.tools import Tool
 from casual_llm.usage import Usage
 
@@ -77,6 +77,52 @@ class LLMProvider(Protocol):
         """
         ...
 
+    def stream(
+        self,
+        messages: list[ChatMessage],
+        response_format: Literal["json", "text"] | type[BaseModel] = "text",
+        max_tokens: int | None = None,
+        tools: list[Tool] | None = None,
+        temperature: float | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """
+        Stream a chat response from the LLM.
+
+        This method yields response chunks in real-time as they are generated,
+        enabling progressive display in chat interfaces.
+
+        Args:
+            messages: List of ChatMessage (UserMessage, AssistantMessage, SystemMessage, etc.)
+            response_format: Expected response format. Can be "json", "text", or a Pydantic
+                BaseModel class for JSON Schema-based structured output. When a Pydantic model
+                is provided, the LLM will be instructed to return JSON matching the schema.
+            max_tokens: Maximum tokens to generate (optional)
+            tools: List of tools available for the LLM to call (optional, may not work
+                with all providers during streaming)
+            temperature: Temperature for this request (optional, overrides instance temperature)
+
+        Yields:
+            StreamChunk objects containing content fragments as tokens are generated.
+            Each chunk has a `content` attribute with the text fragment.
+
+        Raises:
+            Provider-specific exceptions (httpx.HTTPError, openai.OpenAIError, etc.)
+
+        Examples:
+            >>> from casual_llm import UserMessage
+            >>>
+            >>> # Stream response and print tokens as they arrive
+            >>> async for chunk in provider.stream([UserMessage(content="Tell me a story")]):
+            ...     print(chunk.content, end="", flush=True)
+            >>>
+            >>> # Collect full response from stream
+            >>> chunks = []
+            >>> async for chunk in provider.stream([UserMessage(content="Hello")]):
+            ...     chunks.append(chunk.content)
+            >>> full_response = "".join(chunks)
+        """
+        ...
+
     def get_usage(self) -> Usage | None:
         """
         Get token usage statistics from the last chat() call.

casual_llm/providers/ollama.py

@@ -5,11 +5,11 @@ Ollama LLM provider using the official ollama library.
 from __future__ import annotations
 
 import logging
-from typing import Any, Literal
+from typing import Any, AsyncIterator, Literal
 from ollama import AsyncClient
 from pydantic import BaseModel
 
-from casual_llm.messages import ChatMessage, AssistantMessage
+from casual_llm.messages import ChatMessage, AssistantMessage, StreamChunk
 from casual_llm.tools import Tool
 from casual_llm.usage import Usage
 from casual_llm.tool_converters import tools_to_ollama
@@ -42,7 +42,8 @@ class OllamaProvider:
         Args:
             model: Model name (e.g., "qwen2.5:7b-instruct")
             host: Ollama server URL (e.g., "http://localhost:11434")
-            temperature: Temperature for generation (0.0-1.0, optional - uses Ollama default if not set)
+            temperature: Temperature for generation (0.0-1.0, optional - uses Ollama
+                default if not set)
             timeout: HTTP request timeout in seconds
         """
         self.model = model
@@ -108,8 +109,8 @@ class OllamaProvider:
             ...     response_format=PersonInfo  # Pass the class, not an instance
             ... )
         """
-        # Convert messages to Ollama format using converter
-        chat_messages = convert_messages_to_ollama(messages)
+        # Convert messages to Ollama format using converter (async for image support)
+        chat_messages = await convert_messages_to_ollama(messages)
         logger.debug(f"Converted {len(messages)} messages to Ollama format")
 
         # Use provided temperature or fall back to instance temperature
@@ -173,3 +174,90 @@ class OllamaProvider:
         content = response_message.content.strip() if response_message.content else ""
         logger.debug(f"Generated {len(content)} characters")
         return AssistantMessage(content=content, tool_calls=tool_calls)
+
+    async def stream(
+        self,
+        messages: list[ChatMessage],
+        response_format: Literal["json", "text"] | type[BaseModel] = "text",
+        max_tokens: int | None = None,
+        tools: list[Tool] | None = None,
+        temperature: float | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """
+        Stream a chat response from Ollama.
+
+        This method yields response chunks in real-time as they are generated,
+        enabling progressive display in chat interfaces.
+
+        Args:
+            messages: Conversation messages (ChatMessage format)
+            response_format: "json" for JSON output, "text" for plain text, or a Pydantic
+                BaseModel class for JSON Schema-based structured output. When a Pydantic
+                model is provided, the LLM will be instructed to return JSON matching the
+                schema.
+            max_tokens: Maximum tokens to generate (optional)
+            tools: List of tools available for the LLM to call (optional, may not work
+                with all streaming scenarios)
+            temperature: Temperature for this request (optional, overrides instance temperature)
+
+        Yields:
+            StreamChunk objects containing content fragments as tokens are generated.
+
+        Raises:
+            ResponseError: If the request could not be fulfilled
+            RequestError: If the request was invalid
+
+        Examples:
+            >>> async for chunk in provider.stream([UserMessage(content="Hello")]):
+            ...     print(chunk.content, end="", flush=True)
+        """
+        # Convert messages to Ollama format using converter (async for image support)
+        chat_messages = await convert_messages_to_ollama(messages)
+        logger.debug(f"Converted {len(messages)} messages to Ollama format for streaming")
+
+        # Use provided temperature or fall back to instance temperature
+        temp = temperature if temperature is not None else self.temperature
+
+        # Build options
+        options: dict[str, Any] = {}
+        if temp is not None:
+            options["temperature"] = temp
+        if max_tokens:
+            options["num_predict"] = max_tokens
+
+        # Build request kwargs
+        request_kwargs: dict[str, Any] = {
+            "model": self.model,
+            "messages": chat_messages,
+            "stream": True,
+            "options": options,
+        }
+
+        # Handle response_format: "json", "text", or Pydantic model class
+        if response_format == "json":
+            request_kwargs["format"] = "json"
+        elif isinstance(response_format, type) and issubclass(response_format, BaseModel):
+            # Extract JSON Schema from Pydantic model and pass directly to format
+            schema = response_format.model_json_schema()
+            request_kwargs["format"] = schema
+            logger.debug(f"Using JSON Schema from Pydantic model: {response_format.__name__}")
+        # "text" is the default - no format parameter needed
+
+        # Add tools if provided
+        if tools:
+            converted_tools = tools_to_ollama(tools)
+            request_kwargs["tools"] = converted_tools
+            logger.debug(f"Added {len(converted_tools)} tools to streaming request")
+
+        logger.debug(f"Starting stream with model {self.model}")
+        stream = await self.client.chat(**request_kwargs)
+
+        async for chunk in stream:
+            # Extract content from the message if present
+            if chunk.message and chunk.message.content:
+                content = chunk.message.content
+                # Ollama uses 'done' field to indicate completion
+                finish_reason = "stop" if getattr(chunk, "done", False) else None
+                yield StreamChunk(content=content, finish_reason=finish_reason)
+
+        logger.debug("Stream completed")

casual_llm/providers/openai.py

@@ -5,11 +5,11 @@ OpenAI LLM provider (compatible with OpenAI API and compatible services).
 from __future__ import annotations
 
 import logging
-from typing import Literal, Any
+from typing import Literal, Any, AsyncIterator
 from openai import AsyncOpenAI
 from pydantic import BaseModel
 
-from casual_llm.messages import ChatMessage, AssistantMessage
+from casual_llm.messages import ChatMessage, AssistantMessage, StreamChunk
 from casual_llm.tools import Tool
 from casual_llm.usage import Usage
 from casual_llm.tool_converters import tools_to_openai
@@ -46,7 +46,8 @@ class OpenAIProvider:
             api_key: API key (optional, can use OPENAI_API_KEY env var)
             base_url: Base URL for API (e.g., "https://openrouter.ai/api/v1")
             organization: OpenAI organization ID (optional)
-            temperature: Temperature for generation (0.0-1.0, optional - uses OpenAI default if not set)
+            temperature: Temperature for generation (0.0-1.0, optional - uses OpenAI
+                default if not set)
             timeout: HTTP request timeout in seconds
             extra_kwargs: Additional kwargs to pass to client.chat.completions.create()
         """
@@ -191,3 +192,96 @@ class OpenAIProvider:
         content = response_message.content or ""
         logger.debug(f"Generated {len(content)} characters")
         return AssistantMessage(content=content, tool_calls=tool_calls)
+
+    async def stream(
+        self,
+        messages: list[ChatMessage],
+        response_format: Literal["json", "text"] | type[BaseModel] = "text",
+        max_tokens: int | None = None,
+        tools: list[Tool] | None = None,
+        temperature: float | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """
+        Stream a chat response from OpenAI API.
+
+        This method yields response chunks in real-time as they are generated,
+        enabling progressive display in chat interfaces.
+
+        Args:
+            messages: Conversation messages (ChatMessage format)
+            response_format: "json" for JSON output, "text" for plain text, or a Pydantic
+                BaseModel class for JSON Schema-based structured output. When a Pydantic
+                model is provided, the LLM will be instructed to return JSON matching the
+                schema.
+            max_tokens: Maximum tokens to generate (optional)
+            tools: List of tools available for the LLM to call (optional, may not work
+                with all streaming scenarios)
+            temperature: Temperature for this request (optional, overrides instance temperature)
+
+        Yields:
+            StreamChunk objects containing content fragments as tokens are generated.
+
+        Raises:
+            openai.OpenAIError: If request fails
+
+        Examples:
+            >>> async for chunk in provider.stream([UserMessage(content="Hello")]):
+            ...     print(chunk.content, end="", flush=True)
+        """
+        # Convert messages to OpenAI format using converter
+        chat_messages = convert_messages_to_openai(messages)
+        logger.debug(f"Converted {len(messages)} messages to OpenAI format for streaming")
+
+        # Use provided temperature or fall back to instance temperature
+        temp = temperature if temperature is not None else self.temperature
+
+        # Build request kwargs
+        request_kwargs: dict[str, Any] = {
+            "model": self.model,
+            "messages": chat_messages,
+            "stream": True,
+        }
+
+        # Only add temperature if specified
+        if temp is not None:
+            request_kwargs["temperature"] = temp
+
+        # Handle response_format: "json", "text", or Pydantic model class
+        if response_format == "json":
+            request_kwargs["response_format"] = {"type": "json_object"}
+        elif isinstance(response_format, type) and issubclass(response_format, BaseModel):
+            # Extract JSON Schema from Pydantic model
+            schema = response_format.model_json_schema()
+            request_kwargs["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": response_format.__name__,
+                    "schema": schema,
+                },
+            }
+            logger.debug(f"Using JSON Schema from Pydantic model: {response_format.__name__}")
+        # "text" is the default - no response_format needed
+
+        if max_tokens:
+            request_kwargs["max_tokens"] = max_tokens
+
+        # Add tools if provided
+        if tools:
+            converted_tools = tools_to_openai(tools)
+            request_kwargs["tools"] = converted_tools
+            logger.debug(f"Added {len(converted_tools)} tools to streaming request")
+
+        # Merge extra kwargs
+        request_kwargs.update(self.extra_kwargs)
+
+        logger.debug(f"Starting stream with model {self.model}")
+        stream = await self.client.chat.completions.create(**request_kwargs)
+
+        async for chunk in stream:
+            # Extract content from the delta if present
+            if chunk.choices and chunk.choices[0].delta.content:
+                content = chunk.choices[0].delta.content
+                finish_reason = chunk.choices[0].finish_reason
+                yield StreamChunk(content=content, finish_reason=finish_reason)
+
+        logger.debug("Stream completed")

casual_llm/utils/__init__.py

@@ -0,0 +1,9 @@
+"""
+Utility modules for casual-llm.
+"""
+
+from casual_llm.utils.image import fetch_image_as_base64
+
+__all__ = [
+    "fetch_image_as_base64",
+]

casual_llm/utils/image.py

@@ -0,0 +1,162 @@
+"""
+Image utilities for fetching and processing images.
+
+Provides async utilities for downloading images from URLs and converting
+them to base64 format for use in multimodal LLM messages.
+"""
+
+import base64
+
+try:
+    import httpx
+
+    HTTPX_AVAILABLE = True
+except ImportError:
+    HTTPX_AVAILABLE = False
+
+
+class ImageFetchError(Exception):
+    """Raised when image fetching fails."""
+
+    pass
+
+
+# Default timeout for image fetching (in seconds)
+DEFAULT_TIMEOUT = 30.0
+
+# Maximum image size in bytes (10 MB)
+MAX_IMAGE_SIZE = 10 * 1024 * 1024
+
+
+async def fetch_image_as_base64(
+    url: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    max_size: int = MAX_IMAGE_SIZE,
+) -> tuple[str, str]:
+    """Fetch an image from a URL and return it as base64-encoded data.
+
+    Downloads the image from the given URL and returns the base64-encoded
+    content along with the detected media type.
+
+    Args:
+        url: The URL of the image to fetch.
+        timeout: Request timeout in seconds. Defaults to 30 seconds.
+        max_size: Maximum allowed image size in bytes. Defaults to 10 MB.
+
+    Returns:
+        A tuple of (base64_data, media_type) where:
+            - base64_data: The raw base64-encoded image data (no data: prefix)
+            - media_type: The MIME type of the image (e.g., "image/jpeg")
+
+    Raises:
+        ImageFetchError: If the image cannot be fetched, is too large,
+            or if httpx is not installed.
+
+    Example:
+        >>> base64_data, media_type = await fetch_image_as_base64(
+        ...     "https://example.com/image.jpg"
+        ... )
+        >>> print(media_type)
+        image/jpeg
+    """
+    if not HTTPX_AVAILABLE:
+        raise ImageFetchError(
+            "httpx is required for fetching images from URLs. "
+            "Install it with: pip install 'httpx[http2]'"
+        )
+
+    try:
+        # Use a browser-like User-Agent and HTTP/2 to avoid being blocked by sites like Wikipedia
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+        }
+        async with httpx.AsyncClient(timeout=timeout, headers=headers, http2=True) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+
+            # Check content length if available
+            content_length = response.headers.get("content-length")
+            if content_length and int(content_length) > max_size:
+                raise ImageFetchError(
+                    f"Image size ({int(content_length)} bytes) exceeds "
+                    f"maximum allowed size ({max_size} bytes)"
+                )
+
+            # Read content and check actual size
+            content = response.content
+            if len(content) > max_size:
+                raise ImageFetchError(
+                    f"Image size ({len(content)} bytes) exceeds "
+                    f"maximum allowed size ({max_size} bytes)"
+                )
+
+            # Extract media type from Content-Type header
+            content_type = response.headers.get("content-type", "image/jpeg")
+            # Remove any charset or boundary info (e.g., "image/jpeg; charset=utf-8")
+            media_type = content_type.split(";")[0].strip()
+
+            # Validate that it looks like an image type
+            if not media_type.startswith("image/"):
+                # Default to image/jpeg if content-type doesn't indicate an image
+                media_type = "image/jpeg"
+
+            # Encode to base64
+            base64_data = base64.b64encode(content).decode("ascii")
+
+            return base64_data, media_type
+
+    except httpx.HTTPStatusError as e:
+        raise ImageFetchError(
+            f"HTTP error fetching image from {url}: {e.response.status_code}"
+        ) from e
+    except httpx.TimeoutException as e:
+        raise ImageFetchError(f"Timeout fetching image from {url}") from e
+    except httpx.RequestError as e:
+        raise ImageFetchError(f"Error fetching image from {url}: {e}") from e
+
+
+def strip_base64_prefix(data: str) -> str:
+    """Strip the data URI prefix from a base64-encoded string.
+
+    Removes the 'data:<media_type>;base64,' prefix if present,
+    returning only the raw base64 data.
+
+    Args:
+        data: A base64 string, optionally with a data URI prefix.
+
+    Returns:
+        The raw base64 data without any prefix.
+
+    Example:
+        >>> strip_base64_prefix("data:image/png;base64,abc123")
+        'abc123'
+        >>> strip_base64_prefix("abc123")
+        'abc123'
+    """
+    # Check for data URI format: data:<media_type>;base64,<data>
+    if data.startswith("data:") and ";base64," in data:
+        # Split on ";base64," and return the data portion
+        return data.split(";base64,", 1)[1]
+    return data
+
+
+def add_base64_prefix(base64_data: str, media_type: str = "image/png") -> str:
+    """Add a data URI prefix to raw base64 data.
+
+    Creates a complete data URI by prepending the appropriate prefix
+    to raw base64-encoded data.
+
+    Args:
+        base64_data: The raw base64-encoded data (without prefix).
+        media_type: The MIME type of the data. Defaults to "image/png".
+
+    Returns:
+        A complete data URI string.
+
+    Example:
+        >>> add_base64_prefix("abc123", "image/png")
+        'data:image/png;base64,abc123'
+        >>> add_base64_prefix("xyz789", "image/jpeg")
+        'data:image/jpeg;base64,xyz789'
+    """
+    return f"data:{media_type};base64,{base64_data}"

{casual_llm-0.2.0.dist-info → casual_llm-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: casual-llm
-Version: 0.2.0
+Version: 0.3.0
 Summary: Lightweight LLM provider abstraction with standardized message models
 Author-email: Alex Stansfield <alex@casualgenius.com>
 License: MIT
@@ -23,6 +23,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: ollama>=0.6.1
+Requires-Dist: httpx[http2]>=0.28.1
 Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == "openai"
 Dynamic: license-file

casual_llm-0.3.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+casual_llm/__init__.py,sha256=z6NcQ71k1nRY5bPYeBLcpyEsFJ3RIEpoxEq4xgO5lB8,2117
+casual_llm/config.py,sha256=ofGJeHfbJupGSSdMZlsLGZ3RH07A26nQso-4XDMBkVA,1808
+casual_llm/messages.py,sha256=x593dOc2K1Yoj_nbqPP6oewKBSlwVZTUeWKpmJM2WlA,2881
+casual_llm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+casual_llm/tools.py,sha256=AQiGhjJgbwEVd0mHP2byqJ8U4F5XgTK0P9LAmkpdCpA,4045
+casual_llm/usage.py,sha256=-_Dj_do4Fgn3TVrcohG68Giy6SmXaF0p7_GxzKEK2jw,936
+casual_llm/message_converters/__init__.py,sha256=5cuQLm2A7hfzZipoDXItdgJqLLME1KEYCE5dvuqyQ48,608
+casual_llm/message_converters/ollama.py,sha256=PKy0jexhWHnYsuZBrU55W80RyUL5RZyTrwqWWono3Yg,8006
+casual_llm/message_converters/openai.py,sha256=UMj11jCZRj4B1hlIGs_ORkrZjJFs2-ZcMzZNRV_5vxk,5706
+casual_llm/providers/__init__.py,sha256=lVsN9GqU1cQjIEJEL6DbsIzPkknBDggx-_5q_yxtDAA,2525
+casual_llm/providers/base.py,sha256=W7Heb0nW0RfiGkBv2qYb3jV6RfCZyvrou6Vf8X4RkLg,5483
+casual_llm/providers/ollama.py,sha256=en3NuUgVMYCWlFsUT1WRwh_vdfsU4puuESyUu3EkhCE,10390
+casual_llm/providers/openai.py,sha256=NSbCwGac6dOdrf3vG9BnurlJkMiZixubia0K6OWq8FY,11059
+casual_llm/tool_converters/__init__.py,sha256=4FN_r7drXk_prc2EOqrXfO8DNOAZwB0w3qvqhySQnXY,635
+casual_llm/tool_converters/ollama.py,sha256=jaSco33-Px_KPUIzqIQC3BqkXG8180fyMeet3b7OUdo,1926
+casual_llm/tool_converters/openai.py,sha256=n4Yi3rN19CwhwevwNb_XC4RagFrS3HohkUsu5A7b6Hw,1880
+casual_llm/utils/__init__.py,sha256=E-XvHlYDjMidAW--CRVJHwvNnUJkiL88G9mVq1w71o0,142
+casual_llm/utils/image.py,sha256=nlE7CoPSfc0cFUrFMzyVefJ8nAN3FAHYDicAIA4YK8I,5465
+casual_llm-0.3.0.dist-info/licenses/LICENSE,sha256=-PvmTd5xNNGaePz8xckUDBswdIrPWi4L6m7EsyKLmb8,1072
+casual_llm-0.3.0.dist-info/METADATA,sha256=CUF-Q7L3_HFWUZ6d7r3IiusTuxAj5LkiyXDeAqcNmRM,9883
+casual_llm-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+casual_llm-0.3.0.dist-info/top_level.txt,sha256=KKXzOGm04MbK756RPCswL3zeJ6Z-DvaCWy48Mch3HAo,11
+casual_llm-0.3.0.dist-info/RECORD,,

casual_llm-0.2.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-casual_llm/__init__.py,sha256=i8lKHDY8NWGDwozd5q52FtzfCkp5XPmxi0PwUxtVJ24,1945
-casual_llm/config.py,sha256=ofGJeHfbJupGSSdMZlsLGZ3RH07A26nQso-4XDMBkVA,1808
-casual_llm/messages.py,sha256=vLx46YzBn_P8UEplKq6vVe1oF2sJpQuJ67u2gU1asJQ,1436
-casual_llm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-casual_llm/tools.py,sha256=AQiGhjJgbwEVd0mHP2byqJ8U4F5XgTK0P9LAmkpdCpA,4045
-casual_llm/usage.py,sha256=-_Dj_do4Fgn3TVrcohG68Giy6SmXaF0p7_GxzKEK2jw,936
-casual_llm/message_converters/__init__.py,sha256=5cuQLm2A7hfzZipoDXItdgJqLLME1KEYCE5dvuqyQ48,608
-casual_llm/message_converters/ollama.py,sha256=Py4S22ObZcPmAAYMjyAlYMUeiGNxvahpBR0E6KTtm0g,5076
-casual_llm/message_converters/openai.py,sha256=4KLgiDpmlcBnG4tRH_lRhUAYvuQKcB6J_1sW6ym6C7E,4028
-casual_llm/providers/__init__.py,sha256=lVsN9GqU1cQjIEJEL6DbsIzPkknBDggx-_5q_yxtDAA,2525
-casual_llm/providers/base.py,sha256=K4aiOiiCvAQ-mXnlurmo-gaX0fRrnrFLjdR0t7TXeuQ,3383
-casual_llm/providers/ollama.py,sha256=fC2gmHvFn5Og9T8Ge6_e1gGEc_W15X28S4ay3TD8kL0,6492
-casual_llm/providers/openai.py,sha256=Fg4YhEoXWxryorFJfDdFbTTcESyY-KNzgJwWQ_iJ-P0,7098
-casual_llm/tool_converters/__init__.py,sha256=4FN_r7drXk_prc2EOqrXfO8DNOAZwB0w3qvqhySQnXY,635
-casual_llm/tool_converters/ollama.py,sha256=jaSco33-Px_KPUIzqIQC3BqkXG8180fyMeet3b7OUdo,1926
-casual_llm/tool_converters/openai.py,sha256=n4Yi3rN19CwhwevwNb_XC4RagFrS3HohkUsu5A7b6Hw,1880
-casual_llm-0.2.0.dist-info/licenses/LICENSE,sha256=-PvmTd5xNNGaePz8xckUDBswdIrPWi4L6m7EsyKLmb8,1072
-casual_llm-0.2.0.dist-info/METADATA,sha256=mOZxtsvp_S8C_VTm-JEycQ_zD5b-x2ruYMwYnE57F34,9847
-casual_llm-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-casual_llm-0.2.0.dist-info/top_level.txt,sha256=KKXzOGm04MbK756RPCswL3zeJ6Z-DvaCWy48Mch3HAo,11
-casual_llm-0.2.0.dist-info/RECORD,,