casual-llm 0.1.0__py3-none-any.whl

casual_llm/__init__.py

@@ -0,0 +1,88 @@
+"""
+casual-llm - Lightweight LLM provider abstraction with standard message models.
+
+A simple, protocol-based library for working with different LLM providers
+(OpenAI, Ollama, etc.) using a unified interface and OpenAI-compatible message format.
+
+Part of the casual-* ecosystem of lightweight AI tools.
+"""
+
+__version__ = "0.1.0"
+
+# Model configuration
+from casual_llm.config import ModelConfig, Provider
+
+# Provider protocol and implementations
+from casual_llm.providers import (
+    LLMProvider,
+    OllamaProvider,
+    OpenAIProvider,
+    create_provider,
+)
+
+# OpenAI-compatible message models
+from casual_llm.messages import (
+    ChatMessage,
+    UserMessage,
+    AssistantMessage,
+    SystemMessage,
+    ToolResultMessage,
+    AssistantToolCall,
+    AssistantToolCallFunction,
+)
+
+# Tool models
+from casual_llm.tools import Tool, ToolParameter
+
+# Usage tracking
+from casual_llm.usage import Usage
+
+# Tool converters
+from casual_llm.tool_converters import (
+    tool_to_ollama,
+    tools_to_ollama,
+    tool_to_openai,
+    tools_to_openai,
+)
+
+# Message converters
+from casual_llm.message_converters import (
+    convert_messages_to_openai,
+    convert_messages_to_ollama,
+    convert_tool_calls_from_openai,
+    convert_tool_calls_from_ollama,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Providers
+    "LLMProvider",
+    "ModelConfig",
+    "Provider",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "create_provider",
+    # Messages
+    "ChatMessage",
+    "UserMessage",
+    "AssistantMessage",
+    "SystemMessage",
+    "ToolResultMessage",
+    "AssistantToolCall",
+    "AssistantToolCallFunction",
+    # Tools
+    "Tool",
+    "ToolParameter",
+    # Usage
+    "Usage",
+    "tool_to_ollama",
+    "tools_to_ollama",
+    "tool_to_openai",
+    "tools_to_openai",
+    # Message converters
+    "convert_messages_to_openai",
+    "convert_messages_to_ollama",
+    "convert_tool_calls_from_openai",
+    "convert_tool_calls_from_ollama",
+]

casual_llm/config.py

@@ -0,0 +1,63 @@
+"""
+Model configuration and provider enums.
+
+This module defines configuration structures for LLM models,
+allowing unified configuration across different provider backends.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Provider(Enum):
+    """Supported LLM providers"""
+
+    OPENAI = "openai"
+    OLLAMA = "ollama"
+
+
+@dataclass
+class ModelConfig:
+    """
+    Configuration for a specific LLM model.
+
+    Provides a unified way to configure models across different providers.
+
+    Attributes:
+        name: Model name (e.g., "gpt-4o-mini", "qwen2.5:7b-instruct")
+        provider: Provider type (OPENAI or OLLAMA)
+        base_url: Optional custom API endpoint
+        api_key: Optional API key (for OpenAI/compatible providers)
+        temperature: Sampling temperature (0.0-1.0, optional - uses provider default if not set)
+
+    Examples:
+        >>> from casual_llm import ModelConfig, Provider
+        >>>
+        >>> # OpenAI configuration
+        >>> config = ModelConfig(
+        ...     name="gpt-4o-mini",
+        ...     provider=Provider.OPENAI,
+        ...     api_key="sk-..."
+        ... )
+        >>>
+        >>> # Ollama configuration
+        >>> config = ModelConfig(
+        ...     name="qwen2.5:7b-instruct",
+        ...     provider=Provider.OLLAMA,
+        ...     base_url="http://localhost:11434"
+        ... )
+        >>>
+        >>> # OpenRouter configuration (OpenAI-compatible)
+        >>> config = ModelConfig(
+        ...     name="anthropic/claude-3.5-sonnet",
+        ...     provider=Provider.OPENAI,
+        ...     api_key="sk-or-...",
+        ...     base_url="https://openrouter.ai/api/v1"
+        ... )
+    """
+
+    name: str
+    provider: Provider
+    base_url: str | None = None
+    api_key: str | None = None
+    temperature: float | None = None

casual_llm/message_converters/__init__.py

@@ -0,0 +1,22 @@
+"""
+Message converters for different LLM provider formats.
+
+This package provides converters to translate between casual-llm's unified
+ChatMessage format and provider-specific formats (OpenAI, Ollama).
+"""
+
+from casual_llm.message_converters.openai import (
+    convert_messages_to_openai,
+    convert_tool_calls_from_openai,
+)
+from casual_llm.message_converters.ollama import (
+    convert_messages_to_ollama,
+    convert_tool_calls_from_ollama,
+)
+
+__all__ = [
+    "convert_messages_to_openai",
+    "convert_messages_to_ollama",
+    "convert_tool_calls_from_openai",
+    "convert_tool_calls_from_ollama",
+]

casual_llm/message_converters/ollama.py

@@ -0,0 +1,159 @@
+"""
+Ollama message converters.
+
+Converts casual-llm ChatMessage format to Ollama API format and vice versa.
+"""
+
+import json
+import logging
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from casual_llm.messages import (
+    ChatMessage,
+    AssistantToolCall,
+    AssistantToolCallFunction,
+)
+
+if TYPE_CHECKING:
+    from ollama._types import Message
+
+logger = logging.getLogger(__name__)
+
+
+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.
+
+    Args:
+        messages: List of ChatMessage objects
+
+    Returns:
+        List of dictionaries in Ollama message format
+
+    Examples:
+        >>> from casual_llm import UserMessage
+        >>> messages = [UserMessage(content="Hello")]
+        >>> ollama_msgs = convert_messages_to_ollama(messages)
+        >>> ollama_msgs[0]["role"]
+        'user'
+    """
+    if not messages:
+        return []
+
+    logger.debug(f"Converting {len(messages)} messages to Ollama format")
+
+    ollama_messages: list[dict[str, Any]] = []
+
+    for msg in messages:
+        match msg.role:
+            case "assistant":
+                # Handle assistant messages with optional tool calls
+                message: dict[str, Any] = {
+                    "role": "assistant",
+                    "content": msg.content,
+                }
+
+                # Add tool calls if present
+                # Ollama expects arguments as dict, not JSON string
+                if msg.tool_calls:
+                    tool_calls = []
+                    for tool_call in msg.tool_calls:
+                        # Parse arguments from JSON string to dict for Ollama
+                        arguments_dict = (
+                            json.loads(tool_call.function.arguments)
+                            if tool_call.function.arguments
+                            else {}
+                        )
+
+                        tool_calls.append(
+                            {
+                                "id": tool_call.id,
+                                "type": tool_call.type,
+                                "function": {
+                                    "name": tool_call.function.name,
+                                    "arguments": arguments_dict,  # dict for Ollama
+                                },
+                            }
+                        )
+                    message["tool_calls"] = tool_calls
+
+                ollama_messages.append(message)
+
+            case "system":
+                ollama_messages.append({"role": "system", "content": msg.content})
+
+            case "tool":
+                ollama_messages.append(
+                    {
+                        "role": "tool",
+                        "content": msg.content,
+                        "tool_call_id": msg.tool_call_id,
+                        "name": msg.name,
+                    }
+                )
+
+            case "user":
+                ollama_messages.append({"role": "user", "content": msg.content})
+
+            case _:
+                logger.warning(f"Unknown message role: {msg.role}")
+
+    return ollama_messages
+
+
+def convert_tool_calls_from_ollama(
+    response_tool_calls: list["Message.ToolCall"],
+) -> list[AssistantToolCall]:
+    """
+    Convert Ollama tool calls to casual-llm format.
+
+    Handles Ollama's ToolCall objects which have function arguments as a Mapping
+    instead of a JSON string. Also generates unique IDs if not provided.
+
+    Args:
+        response_tool_calls: List of ollama._types.Message.ToolCall objects
+
+    Returns:
+        List of AssistantToolCall objects
+
+    Examples:
+        >>> # from ollama response.message.tool_calls
+        >>> # tool_calls = convert_tool_calls_from_ollama(response.message.tool_calls)
+        >>> # assert len(tool_calls) > 0
+        pass
+    """
+    tool_calls = []
+
+    for tool in response_tool_calls:
+        # Get tool call ID, generate one if missing
+        tool_call_id = getattr(tool, "id", None)
+        if not tool_call_id:
+            tool_call_id = f"call_{uuid.uuid4().hex[:8]}"
+            logger.debug(f"Generated tool call ID: {tool_call_id}")
+
+        logger.debug(f"Converting tool call: {tool.function.name}")
+
+        # Convert arguments from Mapping[str, Any] to JSON string
+        # Ollama returns arguments as a dict, but we need a JSON string
+        arguments_dict = tool.function.arguments
+        arguments_json = json.dumps(arguments_dict) if arguments_dict else "{}"
+
+        tool_call = AssistantToolCall(
+            id=tool_call_id,
+            type=getattr(tool, "type", "function"),
+            function=AssistantToolCallFunction(name=tool.function.name, arguments=arguments_json),
+        )
+        tool_calls.append(tool_call)
+
+    logger.debug(f"Converted {len(tool_calls)} tool calls")
+    return tool_calls
+
+
+__all__ = [
+    "convert_messages_to_ollama",
+    "convert_tool_calls_from_ollama",
+]

casual_llm/message_converters/openai.py

@@ -0,0 +1,136 @@
+"""
+OpenAI message converters.
+
+Converts casual-llm ChatMessage format to OpenAI API format and vice versa.
+"""
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from casual_llm.messages import (
+    ChatMessage,
+    AssistantToolCall,
+    AssistantToolCallFunction,
+)
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletionMessageToolCall
+
+logger = logging.getLogger(__name__)
+
+
+def convert_messages_to_openai(messages: list[ChatMessage]) -> list[dict[str, Any]]:
+    """
+    Convert casual-llm ChatMessage list to OpenAI format.
+
+    Handles all message types including tool calls and tool results.
+
+    Args:
+        messages: List of ChatMessage objects
+
+    Returns:
+        List of dictionaries in OpenAI ChatCompletionMessageParam format
+
+    Examples:
+        >>> from casual_llm import UserMessage, AssistantMessage
+        >>> messages = [UserMessage(content="Hello")]
+        >>> openai_msgs = convert_messages_to_openai(messages)
+        >>> openai_msgs[0]["role"]
+        'user'
+    """
+    if not messages:
+        return []
+
+    logger.debug(f"Converting {len(messages)} messages to OpenAI format")
+
+    openai_messages: list[dict[str, Any]] = []
+
+    for msg in messages:
+        match msg.role:
+            case "assistant":
+                # Handle assistant messages with optional tool calls
+                message: dict[str, Any] = {
+                    "role": "assistant",
+                    "content": msg.content,
+                }
+
+                # Add tool calls if present
+                if msg.tool_calls:
+                    tool_calls = []
+                    for tool_call in msg.tool_calls:
+                        tool_calls.append(
+                            {
+                                "id": tool_call.id,
+                                "type": tool_call.type,
+                                "function": {
+                                    "name": tool_call.function.name,
+                                    "arguments": tool_call.function.arguments,
+                                },
+                            }
+                        )
+                    message["tool_calls"] = tool_calls
+
+                openai_messages.append(message)
+
+            case "system":
+                openai_messages.append({"role": "system", "content": msg.content})
+
+            case "tool":
+                openai_messages.append(
+                    {
+                        "role": "tool",
+                        "content": msg.content,
+                        "tool_call_id": msg.tool_call_id,
+                        "name": msg.name,
+                    }
+                )
+
+            case "user":
+                openai_messages.append({"role": "user", "content": msg.content})
+
+            case _:
+                logger.warning(f"Unknown message role: {msg.role}")
+
+    return openai_messages
+
+
+def convert_tool_calls_from_openai(
+    response_tool_calls: list["ChatCompletionMessageToolCall"],
+) -> list[AssistantToolCall]:
+    """
+    Convert OpenAI ChatCompletionMessageToolCall to casual-llm format.
+
+    Args:
+        response_tool_calls: List of ChatCompletionMessageToolCall from OpenAI response
+
+    Returns:
+        List of AssistantToolCall objects
+
+    Examples:
+        >>> # Assuming response has tool_calls
+        >>> # tool_calls = convert_tool_calls_from_openai(response.choices[0].message.tool_calls)
+        >>> # assert len(tool_calls) > 0
+        pass
+    """
+    tool_calls = []
+
+    for tool in response_tool_calls:
+        logger.debug(f"Converting tool call: {tool.function.name}")
+
+        tool_call = AssistantToolCall(
+            id=tool.id,
+            type="function",
+            function=AssistantToolCallFunction(
+                name=tool.function.name, arguments=tool.function.arguments
+            ),
+        )
+        tool_calls.append(tool_call)
+
+    logger.debug(f"Converted {len(tool_calls)} tool calls")
+    return tool_calls
+
+
+__all__ = [
+    "convert_messages_to_openai",
+    "convert_tool_calls_from_openai",
+]

casual_llm/messages.py

@@ -0,0 +1,60 @@
+"""
+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 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."""
+
+    role: Literal["user"] = "user"
+    content: str | None
+
+
+ChatMessage: TypeAlias = AssistantMessage | SystemMessage | ToolResultMessage | UserMessage
+"""Type alias for any chat message type (user, assistant, system, or tool result)."""

casual_llm/providers/__init__.py

@@ -0,0 +1,86 @@
+"""
+LLM provider implementations.
+
+This module contains provider-specific implementations of the LLMProvider protocol.
+"""
+
+from casual_llm.config import ModelConfig, Provider
+from casual_llm.providers.base import LLMProvider
+from casual_llm.providers.ollama import OllamaProvider
+
+try:
+    from casual_llm.providers.openai import OpenAIProvider
+except ImportError:
+    OpenAIProvider = None  # type: ignore
+
+
+def create_provider(
+    model_config: ModelConfig,
+    timeout: float = 60.0,
+) -> LLMProvider:
+    """
+    Factory function to create an LLM provider from a ModelConfig.
+
+    Args:
+        model_config: Model configuration (name, provider, base_url, api_key, temperature)
+        timeout: HTTP timeout in seconds (default: 60.0)
+
+    Returns:
+        Configured LLM provider (OllamaProvider or OpenAIProvider)
+
+    Raises:
+        ValueError: If provider type is not supported
+        ImportError: If openai package is not installed for OpenAI provider
+
+    Examples:
+        >>> from casual_llm import ModelConfig, Provider, create_provider
+        >>> config = ModelConfig(
+        ...     name="gpt-4o-mini",
+        ...     provider=Provider.OPENAI,
+        ...     api_key="sk-..."
+        ... )
+        >>> provider = create_provider(config)
+
+        >>> config = ModelConfig(
+        ...     name="qwen2.5:7b-instruct",
+        ...     provider=Provider.OLLAMA,
+        ...     base_url="http://localhost:11434"
+        ... )
+        >>> provider = create_provider(config)
+    """
+    if model_config.provider == Provider.OLLAMA:
+        host = model_config.base_url or "http://localhost:11434"
+        return OllamaProvider(
+            model=model_config.name,
+            host=host,
+            temperature=model_config.temperature,
+            timeout=timeout,
+        )
+
+    elif model_config.provider == Provider.OPENAI:
+        if OpenAIProvider is None:
+            raise ImportError(
+                "OpenAI provider requires the 'openai' package. "
+                "Install it with: pip install casual-llm[openai]"
+            )
+
+        return OpenAIProvider(
+            model=model_config.name,
+            api_key=model_config.api_key,
+            base_url=model_config.base_url,
+            temperature=model_config.temperature,
+            timeout=timeout,
+        )
+
+    else:
+        raise ValueError(f"Unsupported provider: {model_config.provider}")
+
+
+__all__ = [
+    "LLMProvider",
+    "ModelConfig",
+    "Provider",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "create_provider",
+]

casual_llm/providers/base.py

@@ -0,0 +1,78 @@
+"""
+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
+
+from casual_llm.messages import ChatMessage, AssistantMessage
+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"] = "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 ("json" or "text")
+            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.)
+        """
+        ...
+
+    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")
+        """
+        ...