feat: add Ollama local generation backend

- OllamaProvider for Ollama's OpenAI-compatible API
- Supports model selection, temperature, max_tokens
- No external deps (uses urllib)
- 13 new tests (173 total)

Closes #2

Author: stef41

src/castwright/__init__.py

@@ -23,6 +23,7 @@
     AnthropicProvider,
     LLMProvider,
     MockProvider,
+    OllamaProvider,
     OpenAIProvider,
 )
 
@@ -47,6 +48,7 @@
     "LLMProvider",
     "OpenAIProvider",
     "AnthropicProvider",
+    "OllamaProvider",
     "MockProvider",
     # Filters
     "filter_examples",

src/castwright/providers.py

@@ -10,6 +10,7 @@
 import re
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional, Tuple
+from urllib.request import Request, urlopen
 
 from castwright._types import ProviderError
 
@@ -179,6 +180,66 @@ def generate(
         return text, input_tokens, output_tokens
 
 
+class OllamaProvider(LLMProvider):
+    """Ollama local LLM provider (uses its OpenAI-compatible API).
+
+    Connects to Ollama at ``http://localhost:11434`` by default.
+    No extra dependencies required — uses only ``urllib``.
+    """
+
+    def __init__(
+        self,
+        model: str = "llama3",
+        host: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> None:
+        if base_url:
+            self._base_url = base_url.rstrip("/")
+        elif host:
+            self._base_url = host.rstrip("/") + "/v1"
+        else:
+            self._base_url = "http://localhost:11434/v1"
+        self._model = model
+
+    def generate(
+        self,
+        prompt: str,
+        system: str = "",
+        temperature: float = 0.9,
+        max_tokens: int = 4096,
+    ) -> Tuple[str, int, int]:
+        messages: list[dict[str, str]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        payload = json.dumps({
+            "model": self._model,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }).encode()
+
+        req = Request(
+            f"{self._base_url}/chat/completions",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+        )
+
+        try:
+            with urlopen(req) as resp:
+                data = json.loads(resp.read())
+        except Exception as e:
+            raise ProviderError(f"Ollama API error: {e}") from e
+
+        text = data["choices"][0]["message"]["content"] if data.get("choices") else ""
+        usage = data.get("usage", {})
+        input_tokens = usage.get("prompt_tokens", 0)
+        output_tokens = usage.get("completion_tokens", 0)
+
+        return text, input_tokens, output_tokens
+
+
 class MockProvider(LLMProvider):
     """Mock provider for testing without API calls.
 

tests/test_ollama.py

@@ -0,0 +1,174 @@
+"""Tests for castwright OllamaProvider."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from castwright._types import ProviderError
+from castwright.providers import OllamaProvider
+
+
+class TestOllamaProviderInit:
+    def test_default_init(self):
+        p = OllamaProvider()
+        assert p._model == "llama3"
+        assert p._base_url == "http://localhost:11434/v1"
+
+    def test_custom_model(self):
+        p = OllamaProvider(model="mistral")
+        assert p._model == "mistral"
+
+    def test_custom_base_url(self):
+        p = OllamaProvider(base_url="http://myhost:8000/v1")
+        assert p._base_url == "http://myhost:8000/v1"
+
+    def test_custom_host(self):
+        p = OllamaProvider(host="http://myhost:11434")
+        assert p._base_url == "http://myhost:11434/v1"
+
+
+class TestOllamaProviderGenerate:
+    def _mock_response(self, text: str, prompt_tokens: int = 10, completion_tokens: int = 20):
+        return {
+            "choices": [{"message": {"content": text}}],
+            "usage": {
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+            },
+        }
+
+    @patch("castwright.providers.urlopen")
+    def test_basic_generation(self, mock_urlopen):
+        resp_data = self._mock_response("Hello world")
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(resp_data).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        p = OllamaProvider(model="llama3")
+        text, in_tok, out_tok = p.generate("Say hello")
+
+        assert text == "Hello world"
+        assert in_tok == 10
+        assert out_tok == 20
+
+    @patch("castwright.providers.urlopen")
+    def test_with_system_prompt(self, mock_urlopen):
+        resp_data = self._mock_response("response")
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(resp_data).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        p = OllamaProvider()
+        p.generate("prompt", system="You are helpful")
+
+        # Verify the request was made
+        call_args = mock_urlopen.call_args
+        req = call_args[0][0]
+        body = json.loads(req.data)
+        assert body["messages"][0]["role"] == "system"
+        assert body["messages"][0]["content"] == "You are helpful"
+        assert body["messages"][1]["role"] == "user"
+
+    @patch("castwright.providers.urlopen")
+    def test_temperature_and_max_tokens(self, mock_urlopen):
+        resp_data = self._mock_response("ok")
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(resp_data).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        p = OllamaProvider()
+        p.generate("hi", temperature=0.1, max_tokens=512)
+
+        call_args = mock_urlopen.call_args
+        req = call_args[0][0]
+        body = json.loads(req.data)
+        assert body["temperature"] == 0.1
+        assert body["max_tokens"] == 512
+
+    @patch("castwright.providers.urlopen")
+    def test_no_usage_field(self, mock_urlopen):
+        resp_data = {"choices": [{"message": {"content": "hi"}}]}
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(resp_data).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        p = OllamaProvider()
+        text, in_tok, out_tok = p.generate("prompt")
+        assert text == "hi"
+        assert in_tok == 0
+        assert out_tok == 0
+
+    @patch("castwright.providers.urlopen")
+    def test_empty_choices(self, mock_urlopen):
+        resp_data = {"choices": [{"message": {"content": ""}}], "usage": {"prompt_tokens": 5, "completion_tokens": 0}}
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(resp_data).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        p = OllamaProvider()
+        text, _, _ = p.generate("prompt")
+        assert text == ""
+
+    @patch("castwright.providers.urlopen")
+    def test_network_error_raises_provider_error(self, mock_urlopen):
+        from urllib.error import URLError
+        mock_urlopen.side_effect = URLError("Connection refused")
+
+        p = OllamaProvider()
+        with pytest.raises(ProviderError, match="Ollama API error"):
+            p.generate("prompt")
+
+    @patch("castwright.providers.urlopen")
+    def test_parse_json_array_inherited(self, mock_urlopen):
+        """OllamaProvider should inherit parse_json_array from LLMProvider."""
+        p = OllamaProvider()
+        result = p.parse_json_array('[{"a": 1}]')
+        assert result == [{"a": 1}]
+
+    @patch("castwright.providers.urlopen")
+    def test_without_system(self, mock_urlopen):
+        resp_data = self._mock_response("response")
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(resp_data).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        p = OllamaProvider()
+        p.generate("prompt")
+
+        call_args = mock_urlopen.call_args
+        req = call_args[0][0]
+        body = json.loads(req.data)
+        assert len(body["messages"]) == 1
+        assert body["messages"][0]["role"] == "user"
+
+    @patch("castwright.providers.urlopen")
+    def test_model_in_request(self, mock_urlopen):
+        resp_data = self._mock_response("ok")
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(resp_data).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        p = OllamaProvider(model="phi3")
+        p.generate("hi")
+
+        call_args = mock_urlopen.call_args
+        req = call_args[0][0]
+        body = json.loads(req.data)
+        assert body["model"] == "phi3"