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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: casual-llm
-Version: 0.3.0
+Version: 0.4.2
 Summary: Lightweight LLM provider abstraction with standardized message models
 Author-email: Alex Stansfield <alex@casualgenius.com>
 License: MIT
@@ -26,6 +26,8 @@ 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
@@ -41,13 +43,15 @@ Part of the [casual-*](https://github.com/AlexStansfield/casual-mcp) ecosystem o
 ## Features
 
 - 🎯 **Protocol-based** - Uses `typing.Protocol`, no inheritance required
-- 🔌 **Provider-agnostic** - Works with OpenAI, Ollama, or your custom provider
-- 📦 **Lightweight** - Minimal dependencies (pydantic, ollama)
+- 🔌 **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
 - 📈 **Usage tracking** - Track token usage for cost monitoring
+- 🖼️ **Vision support** - Send images to vision-capable models
+- ⚡ **Streaming** - Stream responses in real-time with `AsyncIterator`
 
 ## Installation
 
@@ -58,11 +62,18 @@ 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]
+
 # Development dependencies
 uv add casual-llm[dev]
 
 # Or using pip
 pip install casual-llm
+pip install casual-llm[openai,anthropic]
 ```
 
 ## Quick Start
@@ -120,6 +131,32 @@ if usage:
     print(f"Total tokens: {usage.total_tokens}")
 ```
 
+### Using Anthropic (Claude)
+
+```python
+from casual_llm import create_provider, ModelConfig, Provider, UserMessage
+
+# Create Anthropic provider
+config = ModelConfig(
+    name="claude-3-5-sonnet-20241022",
+    provider=Provider.ANTHROPIC,
+    api_key="sk-ant-...",  # or set ANTHROPIC_API_KEY env var
+    temperature=0.7
+)
+
+provider = create_provider(config)
+
+# Generate response
+messages = [UserMessage(content="Explain quantum computing in one sentence.")]
+response = await provider.chat(messages, response_format="text")
+print(response.content)
+
+# Check token usage
+usage = provider.get_usage()
+if usage:
+    print(f"Total tokens: {usage.total_tokens}")
+```
+
 ### Using OpenAI-Compatible APIs (OpenRouter, LM Studio, etc.)
 
 ```python
@@ -134,6 +171,107 @@ config = ModelConfig(
 provider = create_provider(config)
 ```
 
+### Vision Support
+
+Send images to vision-capable models (GPT-4o, Claude 3.5 Sonnet, llava):
+
+```python
+from casual_llm import (
+    create_provider,
+    ModelConfig,
+    Provider,
+    UserMessage,
+    TextContent,
+    ImageContent,
+)
+
+# Works with OpenAI, Anthropic, and Ollama
+config = ModelConfig(
+    name="gpt-4o",  # or "claude-3-5-sonnet-20241022" or "llava"
+    provider=Provider.OPENAI,
+    api_key="sk-...",
+)
+
+provider = create_provider(config)
+
+# Send an image URL
+messages = [
+    UserMessage(
+        content=[
+            TextContent(text="What's in this image?"),
+            ImageContent(source="https://example.com/image.jpg"),
+        ]
+    )
+]
+
+response = await provider.chat(messages)
+print(response.content)  # "I see a cat sitting on a windowsill..."
+
+# Or send a base64-encoded image
+import base64
+
+with open("image.jpg", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode("ascii")
+
+messages = [
+    UserMessage(
+        content=[
+            TextContent(text="Describe this image"),
+            ImageContent(
+                source={"type": "base64", "data": image_data},
+                media_type="image/jpeg",
+            ),
+        ]
+    )
+]
+
+response = await provider.chat(messages)
+```
+
+### Streaming Responses
+
+Stream responses in real-time for better UX:
+
+```python
+from casual_llm import create_provider, ModelConfig, Provider, UserMessage
+
+config = ModelConfig(
+    name="gpt-4o",  # Works with all providers
+    provider=Provider.OPENAI,
+    api_key="sk-...",
+)
+
+provider = create_provider(config)
+
+messages = [UserMessage(content="Write a short poem about coding.")]
+
+# Stream the response
+async for chunk in provider.stream(messages):
+    if chunk.content:
+        print(chunk.content, end="", flush=True)
+
+print()  # New line after streaming
+
+# Check usage after streaming
+usage = provider.get_usage()
+if usage:
+    print(f"\nTokens used: {usage.total_tokens}")
+```
+
+## Examples
+
+Looking for more examples? Check out the [`examples/`](examples) directory for comprehensive demonstrations of all features:
+
+- **[`basic_ollama.py`](examples/basic_ollama.py)** - Get started with Ollama (local LLMs)
+- **[`basic_openai.py`](examples/basic_openai.py)** - Use OpenAI API and compatible services
+- **[`basic_anthropic.py`](examples/basic_anthropic.py)** - Work with Claude models
+- **[`vision_example.py`](examples/vision_example.py)** - Send images to vision-capable models
+- **[`stream_example.py`](examples/stream_example.py)** - Stream responses in real-time
+- **[`tool_calling.py`](examples/tool_calling.py)** - Complete tool/function calling workflow
+- **[`message_formatting.py`](examples/message_formatting.py)** - All message types and structures
+
+See the **[Examples README](examples/README.md)** for detailed descriptions, requirements, and usage instructions for each example.
+
 ## Message Models
 
 casual-llm provides OpenAI-compatible message models that work with any provider:
@@ -146,14 +284,24 @@ from casual_llm import (
     ToolResultMessage,
     AssistantToolCall,
     ChatMessage,  # Type alias for any message type
+    TextContent,  # For multimodal messages
+    ImageContent,  # For vision support
 )
 
 # System message (sets behavior)
 system_msg = SystemMessage(content="You are a helpful assistant.")
 
-# User message
+# 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 (with optional tool calls)
 assistant_msg = AssistantMessage(
     content="I'll help you with that.",
@@ -184,7 +332,15 @@ messages: list[ChatMessage] = [system_msg, user_msg, assistant_msg, tool_msg]
 Implement the `LLMProvider` protocol to add your own provider:
 
 ```python
-from casual_llm import LLMProvider, ChatMessage, AssistantMessage, Tool, Usage
+from typing import Literal, AsyncIterator
+from casual_llm import (
+    LLMProvider,
+    ChatMessage,
+    AssistantMessage,
+    StreamChunk,
+    Tool,
+    Usage,
+)
 
 class MyCustomProvider:
     """Custom LLM provider implementation."""
@@ -192,13 +348,26 @@ class MyCustomProvider:
     async def chat(
         self,
         messages: list[ChatMessage],
-        response_format: Literal["json", "text"] = "text",
+        response_format: Literal["json", "text"] | type[BaseModel] = "text",
         max_tokens: int | None = None,
         tools: list[Tool] | None = None,
+        temperature: float | None = None,
     ) -> AssistantMessage:
         # Your implementation here
         ...
 
+    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]:
+        # Your streaming implementation here
+        ...
+        yield StreamChunk(content="chunk", finish_reason=None)
+
     def get_usage(self) -> Usage | None:
         """Return token usage from last call."""
         return self._last_usage
@@ -244,10 +413,13 @@ Both OpenAI and Ollama providers support usage tracking.
 
 | Feature | casual-llm | LangChain | litellm |
 |---------|-----------|-----------|---------|
-| **Dependencies** | 2 (pydantic, ollama) | 100+ | 50+ |
+| **Dependencies** | 3 (pydantic, ollama, httpx) | 100+ | 50+ |
 | **Protocol-based** | ✅ | ❌ | ❌ |
 | **Type-safe** | ✅ Full typing | Partial | Partial |
 | **Message models** | ✅ Included | ❌ Separate | ❌ |
+| **Vision support** | ✅ All providers | ✅ | ✅ |
+| **Streaming** | ✅ All providers | ✅ | ✅ |
+| **Providers** | OpenAI, Anthropic, Ollama | Many | Many |
 | **Learning curve** | ⚡ Minutes | 📚 Hours | 📖 Medium |
 | **OpenAI compatible** | ✅ | ✅ | ✅ |
 
@@ -280,11 +452,21 @@ class LLMProvider(Protocol):
     async def chat(
         self,
         messages: list[ChatMessage],
-        response_format: Literal["json", "text"] = "text",
+        response_format: Literal["json", "text"] | type[BaseModel] = "text",
         max_tokens: int | None = None,
         tools: list[Tool] | None = None,
+        temperature: float | None = None,
     ) -> AssistantMessage: ...
 
+    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]: ...
+
     def get_usage(self) -> Usage | None: ...
 ```
 
@@ -319,11 +501,13 @@ class Usage(BaseModel):
 
 All message models are Pydantic `BaseModel` instances with full validation:
 
-- `UserMessage(content: str | None)`
+- `UserMessage(content: str | list[TextContent | ImageContent] | None)` - Supports simple text or multimodal content
 - `AssistantMessage(content: str | None, tool_calls: list[AssistantToolCall] | None = None)`
 - `SystemMessage(content: str)`
 - `ToolResultMessage(name: str, tool_call_id: str, content: str)`
 - `ChatMessage` - Type alias for any message type
+- `TextContent(text: str)` - Text block for multimodal messages
+- `ImageContent(source: str | dict, media_type: str | None = None)` - Image block for vision support
 
 ## Contributing
 

{casual_llm-0.3.0 → casual_llm-0.4.2}/README.md

@@ -11,13 +11,15 @@ Part of the [casual-*](https://github.com/AlexStansfield/casual-mcp) ecosystem o
 ## Features
 
 - 🎯 **Protocol-based** - Uses `typing.Protocol`, no inheritance required
-- 🔌 **Provider-agnostic** - Works with OpenAI, Ollama, or your custom provider
-- 📦 **Lightweight** - Minimal dependencies (pydantic, ollama)
+- 🔌 **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
 - 📈 **Usage tracking** - Track token usage for cost monitoring
+- 🖼️ **Vision support** - Send images to vision-capable models
+- ⚡ **Streaming** - Stream responses in real-time with `AsyncIterator`
 
 ## Installation
 
@@ -28,11 +30,18 @@ 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]
+
 # Development dependencies
 uv add casual-llm[dev]
 
 # Or using pip
 pip install casual-llm
+pip install casual-llm[openai,anthropic]
 ```
 
 ## Quick Start
@@ -90,6 +99,32 @@ if usage:
     print(f"Total tokens: {usage.total_tokens}")
 ```
 
+### Using Anthropic (Claude)
+
+```python
+from casual_llm import create_provider, ModelConfig, Provider, UserMessage
+
+# Create Anthropic provider
+config = ModelConfig(
+    name="claude-3-5-sonnet-20241022",
+    provider=Provider.ANTHROPIC,
+    api_key="sk-ant-...",  # or set ANTHROPIC_API_KEY env var
+    temperature=0.7
+)
+
+provider = create_provider(config)
+
+# Generate response
+messages = [UserMessage(content="Explain quantum computing in one sentence.")]
+response = await provider.chat(messages, response_format="text")
+print(response.content)
+
+# Check token usage
+usage = provider.get_usage()
+if usage:
+    print(f"Total tokens: {usage.total_tokens}")
+```
+
 ### Using OpenAI-Compatible APIs (OpenRouter, LM Studio, etc.)
 
 ```python
@@ -104,6 +139,107 @@ config = ModelConfig(
 provider = create_provider(config)
 ```
 
+### Vision Support
+
+Send images to vision-capable models (GPT-4o, Claude 3.5 Sonnet, llava):
+
+```python
+from casual_llm import (
+    create_provider,
+    ModelConfig,
+    Provider,
+    UserMessage,
+    TextContent,
+    ImageContent,
+)
+
+# Works with OpenAI, Anthropic, and Ollama
+config = ModelConfig(
+    name="gpt-4o",  # or "claude-3-5-sonnet-20241022" or "llava"
+    provider=Provider.OPENAI,
+    api_key="sk-...",
+)
+
+provider = create_provider(config)
+
+# Send an image URL
+messages = [
+    UserMessage(
+        content=[
+            TextContent(text="What's in this image?"),
+            ImageContent(source="https://example.com/image.jpg"),
+        ]
+    )
+]
+
+response = await provider.chat(messages)
+print(response.content)  # "I see a cat sitting on a windowsill..."
+
+# Or send a base64-encoded image
+import base64
+
+with open("image.jpg", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode("ascii")
+
+messages = [
+    UserMessage(
+        content=[
+            TextContent(text="Describe this image"),
+            ImageContent(
+                source={"type": "base64", "data": image_data},
+                media_type="image/jpeg",
+            ),
+        ]
+    )
+]
+
+response = await provider.chat(messages)
+```
+
+### Streaming Responses
+
+Stream responses in real-time for better UX:
+
+```python
+from casual_llm import create_provider, ModelConfig, Provider, UserMessage
+
+config = ModelConfig(
+    name="gpt-4o",  # Works with all providers
+    provider=Provider.OPENAI,
+    api_key="sk-...",
+)
+
+provider = create_provider(config)
+
+messages = [UserMessage(content="Write a short poem about coding.")]
+
+# Stream the response
+async for chunk in provider.stream(messages):
+    if chunk.content:
+        print(chunk.content, end="", flush=True)
+
+print()  # New line after streaming
+
+# Check usage after streaming
+usage = provider.get_usage()
+if usage:
+    print(f"\nTokens used: {usage.total_tokens}")
+```
+
+## Examples
+
+Looking for more examples? Check out the [`examples/`](examples) directory for comprehensive demonstrations of all features:
+
+- **[`basic_ollama.py`](examples/basic_ollama.py)** - Get started with Ollama (local LLMs)
+- **[`basic_openai.py`](examples/basic_openai.py)** - Use OpenAI API and compatible services
+- **[`basic_anthropic.py`](examples/basic_anthropic.py)** - Work with Claude models
+- **[`vision_example.py`](examples/vision_example.py)** - Send images to vision-capable models
+- **[`stream_example.py`](examples/stream_example.py)** - Stream responses in real-time
+- **[`tool_calling.py`](examples/tool_calling.py)** - Complete tool/function calling workflow
+- **[`message_formatting.py`](examples/message_formatting.py)** - All message types and structures
+
+See the **[Examples README](examples/README.md)** for detailed descriptions, requirements, and usage instructions for each example.
+
 ## Message Models
 
 casual-llm provides OpenAI-compatible message models that work with any provider:
@@ -116,14 +252,24 @@ from casual_llm import (
     ToolResultMessage,
     AssistantToolCall,
     ChatMessage,  # Type alias for any message type
+    TextContent,  # For multimodal messages
+    ImageContent,  # For vision support
 )
 
 # System message (sets behavior)
 system_msg = SystemMessage(content="You are a helpful assistant.")
 
-# User message
+# 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 (with optional tool calls)
 assistant_msg = AssistantMessage(
     content="I'll help you with that.",
@@ -154,7 +300,15 @@ messages: list[ChatMessage] = [system_msg, user_msg, assistant_msg, tool_msg]
 Implement the `LLMProvider` protocol to add your own provider:
 
 ```python
-from casual_llm import LLMProvider, ChatMessage, AssistantMessage, Tool, Usage
+from typing import Literal, AsyncIterator
+from casual_llm import (
+    LLMProvider,
+    ChatMessage,
+    AssistantMessage,
+    StreamChunk,
+    Tool,
+    Usage,
+)
 
 class MyCustomProvider:
     """Custom LLM provider implementation."""
@@ -162,13 +316,26 @@ class MyCustomProvider:
     async def chat(
         self,
         messages: list[ChatMessage],
-        response_format: Literal["json", "text"] = "text",
+        response_format: Literal["json", "text"] | type[BaseModel] = "text",
         max_tokens: int | None = None,
         tools: list[Tool] | None = None,
+        temperature: float | None = None,
     ) -> AssistantMessage:
         # Your implementation here
         ...
 
+    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]:
+        # Your streaming implementation here
+        ...
+        yield StreamChunk(content="chunk", finish_reason=None)
+
     def get_usage(self) -> Usage | None:
         """Return token usage from last call."""
         return self._last_usage
@@ -214,10 +381,13 @@ Both OpenAI and Ollama providers support usage tracking.
 
 | Feature | casual-llm | LangChain | litellm |
 |---------|-----------|-----------|---------|
-| **Dependencies** | 2 (pydantic, ollama) | 100+ | 50+ |
+| **Dependencies** | 3 (pydantic, ollama, httpx) | 100+ | 50+ |
 | **Protocol-based** | ✅ | ❌ | ❌ |
 | **Type-safe** | ✅ Full typing | Partial | Partial |
 | **Message models** | ✅ Included | ❌ Separate | ❌ |
+| **Vision support** | ✅ All providers | ✅ | ✅ |
+| **Streaming** | ✅ All providers | ✅ | ✅ |
+| **Providers** | OpenAI, Anthropic, Ollama | Many | Many |
 | **Learning curve** | ⚡ Minutes | 📚 Hours | 📖 Medium |
 | **OpenAI compatible** | ✅ | ✅ | ✅ |
 
@@ -250,11 +420,21 @@ class LLMProvider(Protocol):
     async def chat(
         self,
         messages: list[ChatMessage],
-        response_format: Literal["json", "text"] = "text",
+        response_format: Literal["json", "text"] | type[BaseModel] = "text",
         max_tokens: int | None = None,
         tools: list[Tool] | None = None,
+        temperature: float | None = None,
     ) -> AssistantMessage: ...
 
+    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]: ...
+
     def get_usage(self) -> Usage | None: ...
 ```
 
@@ -289,11 +469,13 @@ class Usage(BaseModel):
 
 All message models are Pydantic `BaseModel` instances with full validation:
 
-- `UserMessage(content: str | None)`
+- `UserMessage(content: str | list[TextContent | ImageContent] | None)` - Supports simple text or multimodal content
 - `AssistantMessage(content: str | None, tool_calls: list[AssistantToolCall] | None = None)`
 - `SystemMessage(content: str)`
 - `ToolResultMessage(name: str, tool_call_id: str, content: str)`
 - `ChatMessage` - Type alias for any message type
+- `TextContent(text: str)` - Text block for multimodal messages
+- `ImageContent(source: str | dict, media_type: str | None = None)` - Image block for vision support
 
 ## Contributing
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "casual-llm"
-version = "0.3.0"
+version = "0.4.2"
 description = "Lightweight LLM provider abstraction with standardized message models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -29,6 +29,7 @@ dependencies = [
 
 [project.optional-dependencies]
 openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.20.0"]
 
 [project.urls]
 Homepage = "https://github.com/casualgenius/casual-llm"
@@ -64,7 +65,6 @@ strict = true
 warn_return_any = true
 warn_unused_configs = true
 
-
 [dependency-groups]
 dev = [
     "openai>=2.8.1",
@@ -74,4 +74,4 @@ dev = [
     "black>=23.0.0",
     "ruff>=0.1.0",
     "mypy>=1.0.0",
-]
+]

{casual_llm-0.3.0 → casual_llm-0.4.2}/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.3.0"
+__version__ = "0.4.2"
 
 # Model configuration
 from casual_llm.config import ModelConfig, Provider
@@ -17,6 +17,7 @@ from casual_llm.providers import (
     LLMProvider,
     OllamaProvider,
     OpenAIProvider,
+    AnthropicProvider,
     create_provider,
 )
 
@@ -47,14 +48,19 @@ from casual_llm.tool_converters import (
     tools_to_ollama,
     tool_to_openai,
     tools_to_openai,
+    tool_to_anthropic,
+    tools_to_anthropic,
 )
 
 # Message converters
 from casual_llm.message_converters import (
     convert_messages_to_openai,
     convert_messages_to_ollama,
+    convert_messages_to_anthropic,
     convert_tool_calls_from_openai,
     convert_tool_calls_from_ollama,
+    convert_tool_calls_from_anthropic,
+    extract_system_message,
 )
 
 __all__ = [
@@ -66,6 +72,7 @@ __all__ = [
     "Provider",
     "OllamaProvider",
     "OpenAIProvider",
+    "AnthropicProvider",
     "create_provider",
     # Messages
     "ChatMessage",
@@ -84,13 +91,19 @@ __all__ = [
     "ToolParameter",
     # Usage
     "Usage",
+    # Tool converters
     "tool_to_ollama",
     "tools_to_ollama",
     "tool_to_openai",
     "tools_to_openai",
+    "tool_to_anthropic",
+    "tools_to_anthropic",
     # Message converters
     "convert_messages_to_openai",
     "convert_messages_to_ollama",
+    "convert_messages_to_anthropic",
     "convert_tool_calls_from_openai",
     "convert_tool_calls_from_ollama",
+    "convert_tool_calls_from_anthropic",
+    "extract_system_message",
 ]