casual-llm 0.4.2__tar.gz → 0.5.0__tar.gz

casual_llm-0.5.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: casual-llm
+Version: 0.5.0
+Summary: Lightweight LLM provider abstraction with standardized message models
+Author-email: Alex Stansfield <alex@casualgenius.com>
+License: MIT
+Project-URL: Homepage, https://github.com/casualgenius/casual-llm
+Project-URL: Documentation, https://github.com/casualgenius/casual-llm#readme
+Project-URL: Repository, https://github.com/casualgenius/casual-llm
+Project-URL: Issues, https://github.com/casualgenius/casual-llm/issues
+Keywords: llm,openai,ollama,ai,chatbot,casual
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+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"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
+Dynamic: license-file
+
+# casual-llm
+
+![PyPI](https://img.shields.io/pypi/v/casual-llm)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+
+**Lightweight LLM provider abstraction with standardized message models.**
+
+Part of the "casual" ecosystem of lightweight AI tools.
+
+> **Upgrading from v0.4.x?** See the [Migration Guide](MIGRATION-0.5.0.md) for breaking changes.
+
+## Features
+
+- **Client/Model Separation** - Configure API connections once, create multiple models
+- **Protocol-based** - Uses `typing.Protocol`, no inheritance required
+- **Multi-provider** - Works with OpenAI, Anthropic (Claude), Ollama, or your custom provider
+- **Lightweight** - Minimal dependencies (pydantic, ollama, httpx)
+- **Async-first** - Built for modern async Python
+- **Type-safe** - Full type hints with py.typed marker
+- **OpenAI-compatible** - Standard message format used across the industry
+- **Tool calling** - First-class support for function/tool calling
+- **Per-model usage tracking** - Track token usage per model for cost monitoring
+- **Vision support** - Send images to vision-capable models
+- **Streaming** - Stream responses in real-time with `AsyncIterator`
+
+## Installation
+
+```bash
+# Basic installation (includes Ollama support)
+uv add casual-llm
+
+# With OpenAI support
+uv add casual-llm[openai]
+
+# With Anthropic (Claude) support
+uv add casual-llm[anthropic]
+
+# With all providers
+uv add casual-llm[openai,anthropic]
+
+# Or using pip
+pip install casual-llm[openai,anthropic]
+```
+
+## Quick Start
+
+```python
+from casual_llm import OpenAIClient, Model, UserMessage
+
+# Create client (works with OpenAI, OpenRouter, LM Studio, etc.)
+client = OpenAIClient(
+    api_key="sk-...",  # or set OPENAI_API_KEY env var
+    base_url="https://openrouter.ai/api/v1",  # optional, omit for OpenAI
+)
+
+# Create model
+model = Model(client, "gpt-4o-mini")
+
+# Generate response
+response = await model.chat([UserMessage(content="Hello!")])
+print(response.content)
+```
+
+**More examples:**
+- [Quick Start Guide](docs/quick-start.md) - Ollama, Anthropic, and more
+- [Vision Guide](docs/vision.md) - Send images to models
+- [Streaming Guide](docs/streaming.md) - Real-time responses
+- [Advanced Usage](docs/advanced.md) - Custom clients, configuration classes
+- [API Reference](docs/api-reference.md) - Full API documentation
+- [Examples Directory](examples/) - Complete working examples
+
+## Message Models
+
+casual-llm provides OpenAI-compatible message models that work with any provider:
+
+```python
+from casual_llm import (
+    UserMessage,
+    AssistantMessage,
+    SystemMessage,
+    ToolResultMessage,
+    TextContent,
+    ImageContent,
+)
+
+# System message (sets behavior)
+system_msg = SystemMessage(content="You are a helpful assistant.")
+
+# User message (simple text)
+user_msg = UserMessage(content="Hello!")
+
+# User message (multimodal - text + image)
+vision_msg = UserMessage(
+    content=[
+        TextContent(text="What's in this image?"),
+        ImageContent(source="https://example.com/image.jpg"),
+    ]
+)
+
+# Assistant message (response from LLM)
+assistant_msg = AssistantMessage(content="I'll help you with that.")
+
+# Tool result message (after executing a tool)
+tool_msg = ToolResultMessage(
+    name="get_weather",
+    tool_call_id="call_123",
+    content='{"temp": 20, "condition": "sunny"}'
+)
+```
+
+## Why casual-llm?
+
+| Feature | casual-llm | LangChain | litellm |
+|---------|-----------|-----------|---------|
+| **Dependencies** | 3 (pydantic, ollama, httpx) | 100+ | 50+ |
+| **Protocol-based** | Yes | No | No |
+| **Type-safe** | Full typing | Partial | Partial |
+| **Message models** | Included | Separate | None |
+| **Multi-model sharing** | Yes | No | Yes |
+| **Vision support** | All providers | Yes | Yes |
+| **Streaming** | All providers | Yes | Yes |
+| **Providers** | OpenAI, Anthropic, Ollama | Many | Many |
+| **Learning curve** | Minutes | Hours | Medium |
+
+**Use casual-llm when you want:**
+- Lightweight, focused library (not a framework)
+- Protocol-based design (no inheritance)
+- Standard message models shared across your codebase
+- Efficient multi-model usage with shared connections
+- Simple, predictable API
+
+**Use LangChain when you need:**
+- Full-featured framework with chains, agents, RAG
+- Massive ecosystem of integrations
+- Higher-level abstractions
+
+## Part of the casual-* Ecosystem
+
+- **[casual-mcp](https://github.com/casualgenius/casual-mcp)** - MCP server orchestration and tool calling
+- **casual-llm** (this library) - LLM provider abstraction
+- **[casual-memory](https://github.com/casualgenius/casual-memory)** - Memory intelligence with conflict detection
+
+All casual-* libraries share the same philosophy: lightweight, protocol-based, easy to use.
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- **GitHub**: https://github.com/casualgenius/casual-llm
+- **PyPI**: https://pypi.org/project/casual-llm/
+- **Issues**: https://github.com/casualgenius/casual-llm/issues
+- **Migration Guide**: [MIGRATION-0.5.0.md](MIGRATION-0.5.0.md)
+- **casual-mcp**: https://github.com/casualgenius/casual-mcp

casual_llm-0.5.0/README.md

@@ -0,0 +1,160 @@
+# casual-llm
+
+![PyPI](https://img.shields.io/pypi/v/casual-llm)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+
+**Lightweight LLM provider abstraction with standardized message models.**
+
+Part of the "casual" ecosystem of lightweight AI tools.
+
+> **Upgrading from v0.4.x?** See the [Migration Guide](MIGRATION-0.5.0.md) for breaking changes.
+
+## Features
+
+- **Client/Model Separation** - Configure API connections once, create multiple models
+- **Protocol-based** - Uses `typing.Protocol`, no inheritance required
+- **Multi-provider** - Works with OpenAI, Anthropic (Claude), Ollama, or your custom provider
+- **Lightweight** - Minimal dependencies (pydantic, ollama, httpx)
+- **Async-first** - Built for modern async Python
+- **Type-safe** - Full type hints with py.typed marker
+- **OpenAI-compatible** - Standard message format used across the industry
+- **Tool calling** - First-class support for function/tool calling
+- **Per-model usage tracking** - Track token usage per model for cost monitoring
+- **Vision support** - Send images to vision-capable models
+- **Streaming** - Stream responses in real-time with `AsyncIterator`
+
+## Installation
+
+```bash
+# Basic installation (includes Ollama support)
+uv add casual-llm
+
+# With OpenAI support
+uv add casual-llm[openai]
+
+# With Anthropic (Claude) support
+uv add casual-llm[anthropic]
+
+# With all providers
+uv add casual-llm[openai,anthropic]
+
+# Or using pip
+pip install casual-llm[openai,anthropic]
+```
+
+## Quick Start
+
+```python
+from casual_llm import OpenAIClient, Model, UserMessage
+
+# Create client (works with OpenAI, OpenRouter, LM Studio, etc.)
+client = OpenAIClient(
+    api_key="sk-...",  # or set OPENAI_API_KEY env var
+    base_url="https://openrouter.ai/api/v1",  # optional, omit for OpenAI
+)
+
+# Create model
+model = Model(client, "gpt-4o-mini")
+
+# Generate response
+response = await model.chat([UserMessage(content="Hello!")])
+print(response.content)
+```
+
+**More examples:**
+- [Quick Start Guide](docs/quick-start.md) - Ollama, Anthropic, and more
+- [Vision Guide](docs/vision.md) - Send images to models
+- [Streaming Guide](docs/streaming.md) - Real-time responses
+- [Advanced Usage](docs/advanced.md) - Custom clients, configuration classes
+- [API Reference](docs/api-reference.md) - Full API documentation
+- [Examples Directory](examples/) - Complete working examples
+
+## Message Models
+
+casual-llm provides OpenAI-compatible message models that work with any provider:
+
+```python
+from casual_llm import (
+    UserMessage,
+    AssistantMessage,
+    SystemMessage,
+    ToolResultMessage,
+    TextContent,
+    ImageContent,
+)
+
+# System message (sets behavior)
+system_msg = SystemMessage(content="You are a helpful assistant.")
+
+# User message (simple text)
+user_msg = UserMessage(content="Hello!")
+
+# User message (multimodal - text + image)
+vision_msg = UserMessage(
+    content=[
+        TextContent(text="What's in this image?"),
+        ImageContent(source="https://example.com/image.jpg"),
+    ]
+)
+
+# Assistant message (response from LLM)
+assistant_msg = AssistantMessage(content="I'll help you with that.")
+
+# Tool result message (after executing a tool)
+tool_msg = ToolResultMessage(
+    name="get_weather",
+    tool_call_id="call_123",
+    content='{"temp": 20, "condition": "sunny"}'
+)
+```
+
+## Why casual-llm?
+
+| Feature | casual-llm | LangChain | litellm |
+|---------|-----------|-----------|---------|
+| **Dependencies** | 3 (pydantic, ollama, httpx) | 100+ | 50+ |
+| **Protocol-based** | Yes | No | No |
+| **Type-safe** | Full typing | Partial | Partial |
+| **Message models** | Included | Separate | None |
+| **Multi-model sharing** | Yes | No | Yes |
+| **Vision support** | All providers | Yes | Yes |
+| **Streaming** | All providers | Yes | Yes |
+| **Providers** | OpenAI, Anthropic, Ollama | Many | Many |
+| **Learning curve** | Minutes | Hours | Medium |
+
+**Use casual-llm when you want:**
+- Lightweight, focused library (not a framework)
+- Protocol-based design (no inheritance)
+- Standard message models shared across your codebase
+- Efficient multi-model usage with shared connections
+- Simple, predictable API
+
+**Use LangChain when you need:**
+- Full-featured framework with chains, agents, RAG
+- Massive ecosystem of integrations
+- Higher-level abstractions
+
+## Part of the casual-* Ecosystem
+
+- **[casual-mcp](https://github.com/casualgenius/casual-mcp)** - MCP server orchestration and tool calling
+- **casual-llm** (this library) - LLM provider abstraction
+- **[casual-memory](https://github.com/casualgenius/casual-memory)** - Memory intelligence with conflict detection
+
+All casual-* libraries share the same philosophy: lightweight, protocol-based, easy to use.
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- **GitHub**: https://github.com/casualgenius/casual-llm
+- **PyPI**: https://pypi.org/project/casual-llm/
+- **Issues**: https://github.com/casualgenius/casual-llm/issues
+- **Migration Guide**: [MIGRATION-0.5.0.md](MIGRATION-0.5.0.md)
+- **casual-mcp**: https://github.com/casualgenius/casual-mcp

{casual_llm-0.4.2 → casual_llm-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "casual-llm"
-version = "0.4.2"
+version = "0.5.0"
 description = "Lightweight LLM provider abstraction with standardized message models"
 readme = "README.md"
 requires-python = ">=3.10"

{casual_llm-0.4.2 → casual_llm-0.5.0}/src/casual_llm/__init__.py

@@ -2,25 +2,46 @@
 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.
+(OpenAI, Ollama, Anthropic) using a unified interface and OpenAI-compatible message format.
 
 Part of the casual-* ecosystem of lightweight AI tools.
+
+Example usage:
+    >>> from casual_llm import OpenAIClient, Model, UserMessage
+    >>>
+    >>> # Create client (configured once)
+    >>> client = OpenAIClient(api_key="...")
+    >>>
+    >>> # Create multiple models using the same client
+    >>> gpt4 = Model(client, name="gpt-4", temperature=0.7)
+    >>> gpt4o = Model(client, name="gpt-4o")
+    >>>
+    >>> # Use models
+    >>> response = await gpt4.chat([UserMessage(content="Hello")])
+    >>> print(response.content)
+    >>>
+    >>> # Each model tracks its own usage
+    >>> print(f"Used {gpt4.get_usage().total_tokens} tokens")
 """
 
-__version__ = "0.4.2"
+__version__ = "0.5.0"
 
-# Model configuration
-from casual_llm.config import ModelConfig, Provider
+# Configuration
+from casual_llm.config import ClientConfig, ModelConfig, Provider
 
-# Provider protocol and implementations
+# Client protocol and implementations
 from casual_llm.providers import (
-    LLMProvider,
-    OllamaProvider,
-    OpenAIProvider,
-    AnthropicProvider,
-    create_provider,
+    LLMClient,
+    OllamaClient,
+    OpenAIClient,
+    AnthropicClient,
+    create_client,
+    create_model,
 )
 
+# Model class
+from casual_llm.model import Model
+
 # OpenAI-compatible message models
 from casual_llm.messages import (
     ChatMessage,
@@ -66,14 +87,19 @@ from casual_llm.message_converters import (
 __all__ = [
     # Version
     "__version__",
-    # Providers
-    "LLMProvider",
+    # Configuration
+    "ClientConfig",
     "ModelConfig",
     "Provider",
-    "OllamaProvider",
-    "OpenAIProvider",
-    "AnthropicProvider",
-    "create_provider",
+    # Clients
+    "LLMClient",
+    "OllamaClient",
+    "OpenAIClient",
+    "AnthropicClient",
+    "create_client",
+    "create_model",
+    # Model
+    "Model",
     # Messages
     "ChatMessage",
     "UserMessage",

casual_llm-0.5.0/src/casual_llm/config.py

@@ -0,0 +1,95 @@
+"""
+Configuration for LLM clients and models.
+
+This module defines configuration structures for LLM clients (API connections)
+and models, allowing unified configuration across different provider backends.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Provider(Enum):
+    """Supported LLM providers"""
+
+    OPENAI = "openai"
+    OLLAMA = "ollama"
+    ANTHROPIC = "anthropic"
+
+
+@dataclass
+class ClientConfig:
+    """
+    Configuration for an LLM client (API connection).
+
+    Provides a unified way to configure client connections across different providers.
+
+    Attributes:
+        provider: Provider type (OPENAI, OLLAMA, or ANTHROPIC)
+        base_url: Optional custom API endpoint
+        api_key: Optional API key (for OpenAI/Anthropic providers)
+        timeout: HTTP request timeout in seconds (default: 60.0)
+        extra_kwargs: Additional kwargs passed to the client
+
+    Examples:
+        >>> from casual_llm import ClientConfig, Provider
+        >>>
+        >>> # OpenAI configuration
+        >>> config = ClientConfig(
+        ...     provider=Provider.OPENAI,
+        ...     api_key="sk-..."
+        ... )
+        >>>
+        >>> # Ollama configuration
+        >>> config = ClientConfig(
+        ...     provider=Provider.OLLAMA,
+        ...     base_url="http://localhost:11434"
+        ... )
+        >>>
+        >>> # OpenRouter configuration (OpenAI-compatible)
+        >>> config = ClientConfig(
+        ...     provider=Provider.OPENAI,
+        ...     api_key="sk-or-...",
+        ...     base_url="https://openrouter.ai/api/v1"
+        ... )
+    """
+
+    provider: Provider
+    base_url: str | None = None
+    api_key: str | None = None
+    timeout: float = 60.0
+    extra_kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ModelConfig:
+    """
+    Configuration for a specific LLM model.
+
+    Used with a client to create Model instances.
+
+    Attributes:
+        name: Model name (e.g., "gpt-4o-mini", "qwen2.5:7b-instruct", "claude-3-5-sonnet-latest")
+        temperature: Sampling temperature (0.0-1.0, optional - uses provider default if not set)
+        extra_kwargs: Additional kwargs passed to chat/stream methods
+
+    Examples:
+        >>> from casual_llm import ModelConfig
+        >>>
+        >>> # GPT-4 configuration
+        >>> config = ModelConfig(
+        ...     name="gpt-4",
+        ...     temperature=0.7
+        ... )
+        >>>
+        >>> # Claude configuration
+        >>> config = ModelConfig(
+        ...     name="claude-3-5-sonnet-latest",
+        ...     temperature=0.5
+        ... )
+    """
+
+    name: str
+    temperature: float | None = None
+    extra_kwargs: dict[str, Any] = field(default_factory=dict)

{casual_llm-0.4.2 → casual_llm-0.5.0}/src/casual_llm/message_converters/anthropic.py

@@ -162,7 +162,7 @@ def convert_messages_to_anthropic(messages: list[ChatMessage]) -> list[dict[str,
     if not messages:
         return []
 
-    logger.debug(f"Converting {len(messages)} messages to Anthropic format")
+    logger.debug("Converting %d messages to Anthropic format", len(messages))
 
     anthropic_messages: list[dict[str, Any]] = []
 
@@ -185,7 +185,8 @@ def convert_messages_to_anthropic(messages: list[ChatMessage]) -> list[dict[str,
                         except json.JSONDecodeError:
                             input_data = {}
                             logger.warning(
-                                f"Failed to parse tool call arguments: {tool_call.function.arguments}"
+                                "Failed to parse tool call arguments: %s",
+                                tool_call.function.arguments,
                             )
 
                         content_blocks.append(
@@ -236,7 +237,7 @@ def convert_messages_to_anthropic(messages: list[ChatMessage]) -> list[dict[str,
                 )
 
             case _:
-                logger.warning(f"Unknown message role: {msg.role}")
+                logger.warning("Unknown message role: %s", msg.role)
 
     return anthropic_messages
 
@@ -265,7 +266,7 @@ def convert_tool_calls_from_anthropic(
     tool_calls = []
 
     for tool in response_tool_calls:
-        logger.debug(f"Converting tool call: {tool.name}")
+        logger.debug("Converting tool call: %s", tool.name)
 
         # Serialize input dict to JSON string for casual-llm format
         arguments = json.dumps(tool.input) if tool.input else "{}"
@@ -277,7 +278,7 @@ def convert_tool_calls_from_anthropic(
         )
         tool_calls.append(tool_call)
 
-    logger.debug(f"Converted {len(tool_calls)} tool calls")
+    logger.debug("Converted %d tool calls", len(tool_calls))
     return tool_calls
 
 
@@ -285,6 +286,4 @@ __all__ = [
     "convert_messages_to_anthropic",
     "extract_system_message",
     "convert_tool_calls_from_anthropic",
-    "_convert_image_to_anthropic",
-    "_convert_user_content_to_anthropic",
 ]

{casual_llm-0.4.2 → casual_llm-0.5.0}/src/casual_llm/message_converters/ollama.py

@@ -45,7 +45,7 @@ async def _convert_image_to_ollama(image: ImageContent) -> str:
             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}")
+            logger.debug("Fetching image from URL for Ollama: %s", image.source)
             base64_data, _ = await fetch_image_as_base64(image.source)
             return base64_data
     else:
@@ -128,7 +128,7 @@ async def convert_messages_to_ollama(messages: list[ChatMessage]) -> list[dict[s
     if not messages:
         return []
 
-    logger.debug(f"Converting {len(messages)} messages to Ollama format")
+    logger.debug("Converting %d messages to Ollama format", len(messages))
 
     ollama_messages: list[dict[str, Any]] = []
 
@@ -188,7 +188,7 @@ async def convert_messages_to_ollama(messages: list[ChatMessage]) -> list[dict[s
                 ollama_messages.append(user_message)
 
             case _:
-                logger.warning(f"Unknown message role: {msg.role}")
+                logger.warning("Unknown message role: %s", msg.role)
 
     return ollama_messages
 
@@ -221,9 +221,9 @@ def convert_tool_calls_from_ollama(
         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("Generated tool call ID: %s", tool_call_id)
 
-        logger.debug(f"Converting tool call: {tool.function.name}")
+        logger.debug("Converting tool call: %s", tool.function.name)
 
         # Convert arguments from Mapping[str, Any] to JSON string
         # Ollama returns arguments as a dict, but we need a JSON string
@@ -237,7 +237,7 @@ def convert_tool_calls_from_ollama(
         )
         tool_calls.append(tool_call)
 
-    logger.debug(f"Converted {len(tool_calls)} tool calls")
+    logger.debug("Converted %d tool calls", len(tool_calls))
     return tool_calls
 
 

{casual_llm-0.4.2 → casual_llm-0.5.0}/src/casual_llm/message_converters/openai.py

@@ -92,7 +92,7 @@ def convert_messages_to_openai(messages: list[ChatMessage]) -> list[dict[str, An
     if not messages:
         return []
 
-    logger.debug(f"Converting {len(messages)} messages to OpenAI format")
+    logger.debug("Converting %d messages to OpenAI format", len(messages))
 
     openai_messages: list[dict[str, Any]] = []
 
@@ -145,7 +145,7 @@ def convert_messages_to_openai(messages: list[ChatMessage]) -> list[dict[str, An
                 )
 
             case _:
-                logger.warning(f"Unknown message role: {msg.role}")
+                logger.warning("Unknown message role: %s", msg.role)
 
     return openai_messages
 
@@ -171,7 +171,7 @@ def convert_tool_calls_from_openai(
     tool_calls = []
 
     for tool in response_tool_calls:
-        logger.debug(f"Converting tool call: {tool.function.name}")
+        logger.debug("Converting tool call: %s", tool.function.name)
 
         tool_call = AssistantToolCall(
             id=tool.id,
@@ -182,7 +182,7 @@ def convert_tool_calls_from_openai(
         )
         tool_calls.append(tool_call)
 
-    logger.debug(f"Converted {len(tool_calls)} tool calls")
+    logger.debug("Converted %d tool calls", len(tool_calls))
     return tool_calls