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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: casual-llm
-Version: 0.1.0
+Version: 0.2.0
 Summary: Lightweight LLM provider abstraction with standardized message models
 Author-email: Alex Stansfield <alex@casualgenius.com>
 License: MIT

{casual_llm-0.1.0 → casual_llm-0.2.0}/pyproject.toml

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

{casual_llm-0.1.0 → casual_llm-0.2.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.2.0"
 
 # Model configuration
 from casual_llm.config import ModelConfig, Provider

{casual_llm-0.1.0 → casual_llm-0.2.0}/src/casual_llm/providers/base.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 from typing import Protocol, Literal
 
+from pydantic import BaseModel
+
 from casual_llm.messages import ChatMessage, AssistantMessage
 from casual_llm.tools import Tool
 from casual_llm.usage import Usage
@@ -37,7 +39,7 @@ 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,
@@ -47,7 +49,9 @@ class LLMProvider(Protocol):
 
         Args:
             messages: List of ChatMessage (UserMessage, AssistantMessage, SystemMessage, etc.)
-            response_format: Expected response format ("json" or "text")
+            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)
@@ -57,6 +61,19 @@ class LLMProvider(Protocol):
 
         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
+            ... )
         """
         ...
 

{casual_llm-0.1.0 → casual_llm-0.2.0}/src/casual_llm/providers/ollama.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 import logging
 from typing import Any, Literal
 from ollama import AsyncClient
+from pydantic import BaseModel
 
 from casual_llm.messages import ChatMessage, AssistantMessage
 from casual_llm.tools import Tool
@@ -69,7 +70,7 @@ class OllamaProvider:
     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,
@@ -79,7 +80,10 @@ class OllamaProvider:
 
         Args:
             messages: Conversation messages (ChatMessage format)
-            response_format: "json" for structured output, "text" for plain text
+            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)
             temperature: Temperature for this request (optional, overrides instance temperature)
@@ -90,6 +94,19 @@ class OllamaProvider:
         Raises:
             ResponseError: If the request could not be fulfilled
             RequestError: If the request was invalid
+
+        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
+            ... )
         """
         # Convert messages to Ollama format using converter
         chat_messages = convert_messages_to_ollama(messages)
@@ -113,9 +130,15 @@ class OllamaProvider:
             "options": options,
         }
 
-        # Add format for JSON responses
+        # 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:

{casual_llm-0.1.0 → casual_llm-0.2.0}/src/casual_llm/providers/openai.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 import logging
 from typing import Literal, Any
 from openai import AsyncOpenAI
+from pydantic import BaseModel
 
 from casual_llm.messages import ChatMessage, AssistantMessage
 from casual_llm.tools import Tool
@@ -82,7 +83,7 @@ class OpenAIProvider:
     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,
@@ -92,7 +93,10 @@ class OpenAIProvider:
 
         Args:
             messages: Conversation messages (ChatMessage format)
-            response_format: "json" for structured output, "text" for plain text
+            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)
             temperature: Temperature for this request (optional, overrides instance temperature)
@@ -102,6 +106,19 @@ class OpenAIProvider:
 
         Raises:
             openai.OpenAIError: If request fails
+
+        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
+            ... )
         """
         # Convert messages to OpenAI format using converter
         chat_messages = convert_messages_to_openai(messages)
@@ -120,8 +137,21 @@ class OpenAIProvider:
         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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: casual-llm
-Version: 0.1.0
+Version: 0.2.0
 Summary: Lightweight LLM provider abstraction with standardized message models
 Author-email: Alex Stansfield <alex@casualgenius.com>
 License: MIT

{casual_llm-0.1.0 → casual_llm-0.2.0}/tests/test_providers.py

@@ -3,12 +3,38 @@ Tests for LLM provider implementations.
 """
 
 import pytest
+from pydantic import BaseModel
 from unittest.mock import AsyncMock, MagicMock, patch
 from casual_llm.config import ModelConfig, Provider
 from casual_llm.providers import OllamaProvider, create_provider
 from casual_llm.messages import UserMessage, AssistantMessage, SystemMessage
 from casual_llm.usage import Usage
 
+
+# Test Pydantic models for JSON Schema tests
+class PersonInfo(BaseModel):
+    """Simple Pydantic model for testing"""
+
+    name: str
+    age: int
+
+
+class Address(BaseModel):
+    """Nested model for testing complex schemas"""
+
+    street: str
+    city: str
+    zip_code: str
+
+
+class PersonWithAddress(BaseModel):
+    """Pydantic model with nested structure for testing"""
+
+    name: str
+    age: int
+    address: Address
+
+
 # Try to import OpenAI provider - may not be available
 try:
     from casual_llm.providers import OpenAIProvider
@@ -187,6 +213,110 @@ class TestOllamaProvider:
             assert usage.completion_tokens == 20
             assert usage.total_tokens == 30
 
+    @pytest.mark.asyncio
+    async def test_json_schema_response_format(self, provider):
+        """Test that Pydantic model is correctly converted to JSON Schema for Ollama"""
+        mock_response = MagicMock()
+        mock_response.message.content = '{"name": "Alice", "age": 30}'
+        mock_response.message.tool_calls = None
+
+        mock_chat = AsyncMock(return_value=mock_response)
+
+        with patch("ollama.AsyncClient.chat", new=mock_chat):
+            messages = [UserMessage(content="Give me person info")]
+
+            result = await provider.chat(messages, response_format=PersonInfo)
+
+            assert isinstance(result, AssistantMessage)
+            assert '{"name": "Alice", "age": 30}' in result.content
+
+            # Verify the format parameter contains the JSON Schema
+            call_kwargs = mock_chat.call_args.kwargs
+            assert "format" in call_kwargs
+            schema = call_kwargs["format"]
+
+            # Verify it's a dict (JSON Schema), not a string
+            assert isinstance(schema, dict)
+
+            # Verify schema has expected properties
+            assert "properties" in schema
+            assert "name" in schema["properties"]
+            assert "age" in schema["properties"]
+            assert schema["properties"]["name"]["type"] == "string"
+            assert schema["properties"]["age"]["type"] == "integer"
+
+    @pytest.mark.asyncio
+    async def test_json_schema_nested_pydantic_model(self, provider):
+        """Test that complex nested Pydantic models work correctly"""
+        mock_response = MagicMock()
+        mock_response.message.content = '{"name": "Bob", "age": 25, "address": {"street": "123 Main St", "city": "NYC", "zip_code": "10001"}}'
+        mock_response.message.tool_calls = None
+
+        mock_chat = AsyncMock(return_value=mock_response)
+
+        with patch("ollama.AsyncClient.chat", new=mock_chat):
+            messages = [UserMessage(content="Give me person with address")]
+
+            result = await provider.chat(messages, response_format=PersonWithAddress)
+
+            assert isinstance(result, AssistantMessage)
+
+            # Verify the format parameter contains the nested JSON Schema
+            call_kwargs = mock_chat.call_args.kwargs
+            assert "format" in call_kwargs
+            schema = call_kwargs["format"]
+
+            # Verify it's a dict with properties
+            assert isinstance(schema, dict)
+            assert "properties" in schema
+
+            # Verify nested structure is present (either through $defs or inline)
+            # Pydantic v2 uses $defs for nested models
+            if "$defs" in schema:
+                assert "Address" in schema["$defs"]
+
+    @pytest.mark.asyncio
+    async def test_backward_compat_json_format(self, provider):
+        """Test that existing 'json' format still works (backward compatibility)"""
+        mock_response = MagicMock()
+        mock_response.message.content = '{"status": "ok"}'
+        mock_response.message.tool_calls = None
+
+        mock_chat = AsyncMock(return_value=mock_response)
+
+        with patch("ollama.AsyncClient.chat", new=mock_chat):
+            messages = [UserMessage(content="Give me JSON")]
+
+            result = await provider.chat(messages, response_format="json")
+
+            assert isinstance(result, AssistantMessage)
+            assert '{"status": "ok"}' in result.content
+
+            # Verify format is set to "json" string (not a schema dict)
+            call_kwargs = mock_chat.call_args.kwargs
+            assert call_kwargs["format"] == "json"
+
+    @pytest.mark.asyncio
+    async def test_backward_compat_text_format(self, provider):
+        """Test that existing 'text' format still works (backward compatibility)"""
+        mock_response = MagicMock()
+        mock_response.message.content = "Plain text response"
+        mock_response.message.tool_calls = None
+
+        mock_chat = AsyncMock(return_value=mock_response)
+
+        with patch("ollama.AsyncClient.chat", new=mock_chat):
+            messages = [UserMessage(content="Give me text")]
+
+            result = await provider.chat(messages, response_format="text")
+
+            assert isinstance(result, AssistantMessage)
+            assert result.content == "Plain text response"
+
+            # Verify no format parameter is set for text
+            call_kwargs = mock_chat.call_args.kwargs
+            assert "format" not in call_kwargs
+
 
 @pytest.mark.skipif(not OPENAI_AVAILABLE, reason="OpenAI provider not installed")
 class TestOpenAIProvider:
@@ -362,6 +492,121 @@ class TestOpenAIProvider:
             assert usage.completion_tokens == 25
             assert usage.total_tokens == 40
 
+    @pytest.mark.asyncio
+    async def test_json_schema_response_format(self, provider):
+        """Test that Pydantic model is correctly converted to JSON Schema for OpenAI"""
+        mock_completion = MagicMock()
+        mock_completion.choices = [
+            MagicMock(message=MagicMock(content='{"name": "Alice", "age": 30}'))
+        ]
+
+        mock_create = AsyncMock(return_value=mock_completion)
+
+        with patch.object(provider.client.chat.completions, "create", new=mock_create):
+            messages = [UserMessage(content="Give me person info")]
+
+            result = await provider.chat(messages, response_format=PersonInfo)
+
+            assert isinstance(result, AssistantMessage)
+            assert '{"name": "Alice", "age": 30}' in result.content
+
+            # Verify the response_format parameter contains the JSON Schema structure
+            call_kwargs = mock_create.call_args.kwargs
+            assert "response_format" in call_kwargs
+            response_format = call_kwargs["response_format"]
+
+            # Verify OpenAI json_schema format structure
+            assert response_format["type"] == "json_schema"
+            assert "json_schema" in response_format
+            assert response_format["json_schema"]["name"] == "PersonInfo"
+            assert "schema" in response_format["json_schema"]
+
+            # Verify schema has expected properties
+            schema = response_format["json_schema"]["schema"]
+            assert "properties" in schema
+            assert "name" in schema["properties"]
+            assert "age" in schema["properties"]
+            assert schema["properties"]["name"]["type"] == "string"
+            assert schema["properties"]["age"]["type"] == "integer"
+
+    @pytest.mark.asyncio
+    async def test_json_schema_nested_pydantic_model(self, provider):
+        """Test that complex nested Pydantic models work correctly"""
+        mock_completion = MagicMock()
+        mock_completion.choices = [
+            MagicMock(
+                message=MagicMock(
+                    content='{"name": "Bob", "age": 25, "address": {"street": "123 Main St", "city": "NYC", "zip_code": "10001"}}'
+                )
+            )
+        ]
+
+        mock_create = AsyncMock(return_value=mock_completion)
+
+        with patch.object(provider.client.chat.completions, "create", new=mock_create):
+            messages = [UserMessage(content="Give me person with address")]
+
+            result = await provider.chat(messages, response_format=PersonWithAddress)
+
+            assert isinstance(result, AssistantMessage)
+
+            # Verify the response_format parameter contains the nested JSON Schema
+            call_kwargs = mock_create.call_args.kwargs
+            assert "response_format" in call_kwargs
+            response_format = call_kwargs["response_format"]
+
+            # Verify OpenAI json_schema format structure
+            assert response_format["type"] == "json_schema"
+            assert response_format["json_schema"]["name"] == "PersonWithAddress"
+
+            schema = response_format["json_schema"]["schema"]
+            assert "properties" in schema
+
+            # Verify nested structure is present (either through $defs or inline)
+            # Pydantic v2 uses $defs for nested models
+            if "$defs" in schema:
+                assert "Address" in schema["$defs"]
+
+    @pytest.mark.asyncio
+    async def test_backward_compat_json_format(self, provider):
+        """Test that existing 'json' format still works (backward compatibility)"""
+        mock_completion = MagicMock()
+        mock_completion.choices = [MagicMock(message=MagicMock(content='{"status": "ok"}'))]
+
+        mock_create = AsyncMock(return_value=mock_completion)
+
+        with patch.object(provider.client.chat.completions, "create", new=mock_create):
+            messages = [UserMessage(content="Give me JSON")]
+
+            result = await provider.chat(messages, response_format="json")
+
+            assert isinstance(result, AssistantMessage)
+            assert '{"status": "ok"}' in result.content
+
+            # Verify response_format is set to json_object (not json_schema)
+            call_kwargs = mock_create.call_args.kwargs
+            assert call_kwargs["response_format"] == {"type": "json_object"}
+
+    @pytest.mark.asyncio
+    async def test_backward_compat_text_format(self, provider):
+        """Test that existing 'text' format still works (backward compatibility)"""
+        mock_completion = MagicMock()
+        mock_completion.choices = [MagicMock(message=MagicMock(content="Plain text response"))]
+
+        mock_create = AsyncMock(return_value=mock_completion)
+
+        with patch.object(provider.client.chat.completions, "create", new=mock_create):
+            messages = [UserMessage(content="Give me text")]
+
+            result = await provider.chat(messages, response_format="text")
+
+            assert isinstance(result, AssistantMessage)
+            assert result.content == "Plain text response"
+
+            # Verify no response_format parameter is set for text
+            call_kwargs = mock_create.call_args.kwargs
+            assert "response_format" not in call_kwargs
+
 
 class TestCreateProviderFactory:
     """Tests for create_provider() factory function"""