casual-llm 0.1.0__tar.gz → 0.3.0__tar.gz

{casual_llm-0.1.0/src/casual_llm.egg-info → casual_llm-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: casual-llm
-Version: 0.1.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.1.0 → casual_llm-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "casual-llm"
-version = "0.1.0"
+version = "0.3.0"
 description = "Lightweight LLM provider abstraction with standardized message models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ classifiers = [
 dependencies = [
     "pydantic>=2.0.0",
     "ollama>=0.6.1",
+    "httpx[http2]>=0.28.1",
 ]
 
 [project.optional-dependencies]
@@ -63,6 +64,7 @@ strict = true
 warn_return_any = true
 warn_unused_configs = true
 
+
 [dependency-groups]
 dev = [
     "openai>=2.8.1",

{casual_llm-0.1.0 → casual_llm-0.3.0}/src/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.1.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-0.1.0 → casual_llm-0.3.0}/src/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-0.1.0 → casual_llm-0.3.0}/src/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-0.3.0/src/casual_llm/messages.py

@@ -0,0 +1,111 @@
+"""
+OpenAI-compatible message models for LLM conversations.
+
+These models follow the OpenAI chat completion API format and can be used
+with any provider that implements the LLMProvider protocol.
+"""
+
+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."""
+
+    name: str
+    arguments: str
+
+
+class AssistantToolCall(BaseModel):
+    """Tool call made by the assistant."""
+
+    id: str
+    type: Literal["function"] = "function"
+    function: AssistantToolCallFunction
+
+
+class AssistantMessage(BaseModel):
+    """Message from the AI assistant."""
+
+    role: Literal["assistant"] = "assistant"
+    content: str | None = None
+    tool_calls: list[AssistantToolCall] | None = None
+
+
+class SystemMessage(BaseModel):
+    """System prompt message that sets the assistant's behavior."""
+
+    role: Literal["system"] = "system"
+    content: str
+
+
+class ToolResultMessage(BaseModel):
+    """Result from a tool/function call execution."""
+
+    role: Literal["tool"] = "tool"
+    name: str
+    tool_call_id: str
+    content: str
+
+
+class UserMessage(BaseModel):
+    """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 | 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
+"""Type alias for any chat message type (user, assistant, system, or tool result)."""

casual_llm-0.3.0/src/casual_llm/providers/base.py

@@ -0,0 +1,141 @@
+"""
+Base protocol for LLM providers.
+
+Provides a unified interface for different LLM backends (OpenAI, Ollama, etc.)
+using standard OpenAI-compatible message formats.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, Literal, AsyncIterator
+
+from pydantic import BaseModel
+
+from casual_llm.messages import ChatMessage, AssistantMessage, StreamChunk
+from casual_llm.tools import Tool
+from casual_llm.usage import Usage
+
+
+class LLMProvider(Protocol):
+    """
+    Protocol for LLM providers.
+
+    Uses OpenAI-compatible ChatMessage format for all interactions.
+    Supports both structured (JSON) and unstructured (text) responses.
+
+    This is a Protocol (PEP 544), meaning any class that implements
+    the chat() method with this signature is compatible - no
+    inheritance required.
+
+    Examples:
+        >>> from casual_llm import LLMProvider, ChatMessage, UserMessage
+        >>>
+        >>> # Any provider implementing this protocol works
+        >>> async def get_response(provider: LLMProvider, prompt: str) -> str:
+        ...     messages = [UserMessage(content=prompt)]
+        ...     return await provider.chat(messages)
+    """
+
+    async def chat(
+        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,
+    ) -> AssistantMessage:
+        """
+        Generate a chat response from the LLM.
+
+        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)
+            temperature: Temperature for this request (optional, overrides instance temperature)
+
+        Returns:
+            AssistantMessage with content and optional tool_calls
+
+        Raises:
+            Provider-specific exceptions (httpx.HTTPError, openai.OpenAIError, etc.)
+
+        Examples:
+            >>> from pydantic import BaseModel
+            >>>
+            >>> class PersonInfo(BaseModel):
+            ...     name: str
+            ...     age: int
+            >>>
+            >>> # Pass Pydantic model for structured output
+            >>> response = await provider.chat(
+            ...     messages=[UserMessage(content="Tell me about a person")],
+            ...     response_format=PersonInfo  # Pass the class, not an instance
+            ... )
+        """
+        ...
+
+    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.
+
+        Returns:
+            Usage object with prompt_tokens, completion_tokens, and total_tokens,
+            or None if no calls have been made yet.
+
+        Examples:
+            >>> provider = OllamaProvider(model="llama3.1")
+            >>> await provider.chat([UserMessage(content="Hello")])
+            >>> usage = provider.get_usage()
+            >>> if usage:
+            ...     print(f"Used {usage.total_tokens} tokens")
+        """
+        ...