prompture 0.0.35__py3-none-any.whl → 0.0.38.dev2__py3-none-any.whl

prompture/drivers/google_driver.py

@@ -1,5 +1,7 @@
 import logging
 import os
+import uuid
+from collections.abc import Iterator
 from typing import Any, Optional
 
 import google.generativeai as genai
@@ -15,6 +17,9 @@ class GoogleDriver(CostMixin, Driver):
 
     supports_json_mode = True
     supports_json_schema = True
+    supports_vision = True
+    supports_tool_use = True
+    supports_streaming = True
 
     # Based on current Gemini pricing (as of 2025)
     # Source: https://cloud.google.com/vertex-ai/pricing#gemini_models
@@ -105,25 +110,62 @@ class GoogleDriver(CostMixin, Driver):
             completion_cost = (completion_chars / 1_000_000) * model_pricing["completion"]
         return round(prompt_cost + completion_cost, 6)
 
+    def _extract_usage_metadata(self, response: Any, messages: list[dict[str, Any]]) -> dict[str, Any]:
+        """Extract token counts from response, falling back to character estimation."""
+        usage = getattr(response, "usage_metadata", None)
+        if usage:
+            prompt_tokens = getattr(usage, "prompt_token_count", 0) or 0
+            completion_tokens = getattr(usage, "candidates_token_count", 0) or 0
+            total_tokens = getattr(usage, "total_token_count", 0) or (prompt_tokens + completion_tokens)
+            cost = self._calculate_cost("google", self.model, prompt_tokens, completion_tokens)
+        else:
+            # Fallback: estimate from character counts
+            total_prompt_chars = 0
+            for msg in messages:
+                c = msg.get("content", "")
+                if isinstance(c, str):
+                    total_prompt_chars += len(c)
+                elif isinstance(c, list):
+                    for part in c:
+                        if isinstance(part, str):
+                            total_prompt_chars += len(part)
+                        elif isinstance(part, dict) and "text" in part:
+                            total_prompt_chars += len(part["text"])
+            completion_chars = len(response.text) if response.text else 0
+            prompt_tokens = total_prompt_chars // 4
+            completion_tokens = completion_chars // 4
+            total_tokens = prompt_tokens + completion_tokens
+            cost = self._calculate_cost_chars(total_prompt_chars, completion_chars)
+
+        return {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": total_tokens,
+            "cost": round(cost, 6),
+        }
+
     supports_messages = True
 
-    def generate(self, prompt: str, options: Optional[dict[str, Any]] = None) -> dict[str, Any]:
-        messages = [{"role": "user", "content": prompt}]
-        return self._do_generate(messages, options)
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        from .vision_helpers import _prepare_google_vision_messages
 
-    def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
-        return self._do_generate(messages, options)
+        return _prepare_google_vision_messages(messages)
 
-    def _do_generate(self, messages: list[dict[str, str]], options: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+    def _build_generation_args(
+        self, messages: list[dict[str, Any]], options: Optional[dict[str, Any]] = None
+    ) -> tuple[Any, dict[str, Any]]:
+        """Parse messages and options into (gen_input, kwargs) for generate_content.
+
+        Returns the content input and a dict of keyword arguments
+        (generation_config, safety_settings, model kwargs including system_instruction).
+        """
         merged_options = self.options.copy()
         if options:
             merged_options.update(options)
 
-        # Extract specific options for Google's API
         generation_config = merged_options.get("generation_config", {})
         safety_settings = merged_options.get("safety_settings", {})
 
-        # Map common options to generation_config if not present
         if "temperature" in merged_options and "temperature" not in generation_config:
             generation_config["temperature"] = merged_options["temperature"]
         if "max_tokens" in merged_options and "max_output_tokens" not in generation_config:
@@ -147,44 +189,59 @@ class GoogleDriver(CostMixin, Driver):
             role = msg.get("role", "user")
             content = msg.get("content", "")
             if role == "system":
-                system_instruction = content
+                system_instruction = content if isinstance(content, str) else str(content)
             else:
-                # Gemini uses "model" for assistant role
                 gemini_role = "model" if role == "assistant" else "user"
-                contents.append({"role": gemini_role, "parts": [content]})
+                if msg.get("_vision_parts"):
+                    contents.append({"role": gemini_role, "parts": content})
+                else:
+                    contents.append({"role": gemini_role, "parts": [content]})
+
+        # For a single message, unwrap only if it has exactly one string part
+        if len(contents) == 1:
+            parts = contents[0]["parts"]
+            if len(parts) == 1 and isinstance(parts[0], str):
+                gen_input = parts[0]
+            else:
+                gen_input = contents
+        else:
+            gen_input = contents
+
+        model_kwargs: dict[str, Any] = {}
+        if system_instruction:
+            model_kwargs["system_instruction"] = system_instruction
+
+        gen_kwargs: dict[str, Any] = {
+            "generation_config": generation_config if generation_config else None,
+            "safety_settings": safety_settings if safety_settings else None,
+        }
+
+        return gen_input, gen_kwargs, model_kwargs
+
+    def generate(self, prompt: str, options: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        messages = [{"role": "user", "content": prompt}]
+        return self._do_generate(messages, options)
+
+    def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
+        return self._do_generate(self._prepare_messages(messages), options)
+
+    def _do_generate(self, messages: list[dict[str, str]], options: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        gen_input, gen_kwargs, model_kwargs = self._build_generation_args(messages, options)
 
         try:
             logger.debug(f"Initializing {self.model} for generation")
-            model_kwargs: dict[str, Any] = {}
-            if system_instruction:
-                model_kwargs["system_instruction"] = system_instruction
             model = genai.GenerativeModel(self.model, **model_kwargs)
 
-            # Generate response
-            logger.debug(f"Generating with {len(contents)} content parts")
-            # If single user message, pass content directly for backward compatibility
-            gen_input: Any = contents if len(contents) != 1 else contents[0]["parts"][0]
-            response = model.generate_content(
-                gen_input,
-                generation_config=generation_config if generation_config else None,
-                safety_settings=safety_settings if safety_settings else None,
-            )
+            logger.debug(f"Generating with model {self.model}")
+            response = model.generate_content(gen_input, **gen_kwargs)
 
             if not response.text:
                 raise ValueError("Empty response from model")
 
-            # Calculate token usage and cost
-            total_prompt_chars = sum(len(msg.get("content", "")) for msg in messages)
-            completion_chars = len(response.text)
-
-            # Google uses character-based cost estimation
-            total_cost = self._calculate_cost_chars(total_prompt_chars, completion_chars)
+            usage_meta = self._extract_usage_metadata(response, messages)
 
             meta = {
-                "prompt_chars": total_prompt_chars,
-                "completion_chars": completion_chars,
-                "total_chars": total_prompt_chars + completion_chars,
-                "cost": total_cost,
+                **usage_meta,
                 "raw_response": response.prompt_feedback if hasattr(response, "prompt_feedback") else None,
                 "model_name": self.model,
             }
@@ -194,3 +251,130 @@ class GoogleDriver(CostMixin, Driver):
         except Exception as e:
             logger.error(f"Google API request failed: {e}")
             raise RuntimeError(f"Google API request failed: {e}") from e
+
+    # ------------------------------------------------------------------
+    # Tool use
+    # ------------------------------------------------------------------
+
+    def generate_messages_with_tools(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+        options: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Generate a response that may include tool/function calls."""
+        gen_input, gen_kwargs, model_kwargs = self._build_generation_args(
+            self._prepare_messages(messages), options
+        )
+
+        # Convert tools from OpenAI format to Gemini function declarations
+        function_declarations = []
+        for t in tools:
+            if "type" in t and t["type"] == "function":
+                fn = t["function"]
+                decl = {
+                    "name": fn["name"],
+                    "description": fn.get("description", ""),
+                }
+                params = fn.get("parameters")
+                if params:
+                    decl["parameters"] = params
+                function_declarations.append(decl)
+            elif "name" in t:
+                # Already in a generic format
+                decl = {"name": t["name"], "description": t.get("description", "")}
+                params = t.get("parameters") or t.get("input_schema")
+                if params:
+                    decl["parameters"] = params
+                function_declarations.append(decl)
+
+        try:
+            model = genai.GenerativeModel(self.model, **model_kwargs)
+
+            gemini_tools = [genai.types.Tool(function_declarations=function_declarations)]
+            response = model.generate_content(gen_input, tools=gemini_tools, **gen_kwargs)
+
+            usage_meta = self._extract_usage_metadata(response, messages)
+            meta = {
+                **usage_meta,
+                "raw_response": response.prompt_feedback if hasattr(response, "prompt_feedback") else None,
+                "model_name": self.model,
+            }
+
+            text = ""
+            tool_calls_out: list[dict[str, Any]] = []
+            stop_reason = "stop"
+
+            for candidate in response.candidates:
+                for part in candidate.content.parts:
+                    if hasattr(part, "text") and part.text:
+                        text += part.text
+                    if hasattr(part, "function_call") and part.function_call.name:
+                        fc = part.function_call
+                        tool_calls_out.append({
+                            "id": str(uuid.uuid4()),
+                            "name": fc.name,
+                            "arguments": dict(fc.args) if fc.args else {},
+                        })
+
+                finish_reason = getattr(candidate, "finish_reason", None)
+                if finish_reason is not None:
+                    # Map Gemini finish reasons to standard stop reasons
+                    reason_map = {1: "stop", 2: "max_tokens", 3: "safety", 4: "recitation", 5: "other"}
+                    stop_reason = reason_map.get(finish_reason, "stop")
+
+            if tool_calls_out:
+                stop_reason = "tool_use"
+
+            return {
+                "text": text,
+                "meta": meta,
+                "tool_calls": tool_calls_out,
+                "stop_reason": stop_reason,
+            }
+
+        except Exception as e:
+            logger.error(f"Google API tool call request failed: {e}")
+            raise RuntimeError(f"Google API tool call request failed: {e}") from e
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    def generate_messages_stream(
+        self,
+        messages: list[dict[str, Any]],
+        options: dict[str, Any],
+    ) -> Iterator[dict[str, Any]]:
+        """Yield response chunks via Gemini streaming API."""
+        gen_input, gen_kwargs, model_kwargs = self._build_generation_args(
+            self._prepare_messages(messages), options
+        )
+
+        try:
+            model = genai.GenerativeModel(self.model, **model_kwargs)
+            response = model.generate_content(gen_input, stream=True, **gen_kwargs)
+
+            full_text = ""
+            for chunk in response:
+                chunk_text = getattr(chunk, "text", None) or ""
+                if chunk_text:
+                    full_text += chunk_text
+                    yield {"type": "delta", "text": chunk_text}
+
+            # After iteration completes, resolve() has been called on the response
+            usage_meta = self._extract_usage_metadata(response, messages)
+
+            yield {
+                "type": "done",
+                "text": full_text,
+                "meta": {
+                    **usage_meta,
+                    "raw_response": {},
+                    "model_name": self.model,
+                },
+            }
+
+        except Exception as e:
+            logger.error(f"Google API streaming request failed: {e}")
+            raise RuntimeError(f"Google API streaming request failed: {e}") from e

prompture/drivers/grok_driver.py

@@ -13,6 +13,7 @@ from ..driver import Driver
 
 class GrokDriver(CostMixin, Driver):
     supports_json_mode = True
+    supports_vision = True
 
     # Pricing per 1M tokens based on xAI's documentation
     _PRICING_UNIT = 1_000_000
@@ -80,12 +81,17 @@ class GrokDriver(CostMixin, Driver):
 
     supports_messages = True
 
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        from .vision_helpers import _prepare_openai_vision_messages
+
+        return _prepare_openai_vision_messages(messages)
+
     def generate(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
         messages = [{"role": "user", "content": prompt}]
         return self._do_generate(messages, options)
 
     def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
-        return self._do_generate(messages, options)
+        return self._do_generate(self._prepare_messages(messages), options)
 
     def _do_generate(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
         if not self.api_key:

prompture/drivers/groq_driver.py

@@ -16,6 +16,7 @@ from ..driver import Driver
 
 class GroqDriver(CostMixin, Driver):
     supports_json_mode = True
+    supports_vision = True
 
     # Approximate pricing per 1K tokens (to be updated with official pricing)
     # Each model entry defines token parameters and temperature support
@@ -50,12 +51,17 @@ class GroqDriver(CostMixin, Driver):
 
     supports_messages = True
 
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        from .vision_helpers import _prepare_openai_vision_messages
+
+        return _prepare_openai_vision_messages(messages)
+
     def generate(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
         messages = [{"role": "user", "content": prompt}]
         return self._do_generate(messages, options)
 
     def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
-        return self._do_generate(messages, options)
+        return self._do_generate(self._prepare_messages(messages), options)
 
     def _do_generate(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
         if self.client is None:

prompture/drivers/lmstudio_driver.py

@@ -12,27 +12,47 @@ logger = logging.getLogger(__name__)
 
 class LMStudioDriver(Driver):
     supports_json_mode = True
+    supports_json_schema = True
+    supports_vision = True
 
     # LM Studio is local – costs are always zero.
     MODEL_PRICING = {"default": {"prompt": 0.0, "completion": 0.0}}
 
-    def __init__(self, endpoint: str | None = None, model: str = "deepseek/deepseek-r1-0528-qwen3-8b"):
+    def __init__(
+        self,
+        endpoint: str | None = None,
+        model: str = "deepseek/deepseek-r1-0528-qwen3-8b",
+        api_key: str | None = None,
+    ):
         # Allow override via env var
         self.endpoint = endpoint or os.getenv("LMSTUDIO_ENDPOINT", "http://127.0.0.1:1234/v1/chat/completions")
         self.model = model
         self.options: dict[str, Any] = {}
 
+        # Derive base_url once for reuse across management endpoints
+        self.base_url = self.endpoint.split("/v1/")[0]
+
+        # API key for LM Studio 0.4.0+ authentication
+        self.api_key = api_key or os.getenv("LMSTUDIO_API_KEY")
+        self._headers = self._build_headers()
+
         # Validate connection to LM Studio server
         self._validate_connection()
 
+    def _build_headers(self) -> dict[str, str]:
+        """Build request headers, including auth if an API key is configured."""
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
     def _validate_connection(self):
         """Validate connection to the LM Studio server."""
         try:
-            base_url = self.endpoint.split("/v1/")[0]
-            health_url = f"{base_url}/v1/models"
+            health_url = f"{self.base_url}/v1/models"
 
             logger.debug(f"Validating connection to LM Studio server at: {health_url}")
-            response = requests.get(health_url, timeout=5)
+            response = requests.get(health_url, headers=self._headers, timeout=5)
             response.raise_for_status()
             logger.debug("Connection to LM Studio server validated successfully")
         except requests.exceptions.RequestException as e:
@@ -40,12 +60,17 @@ class LMStudioDriver(Driver):
 
     supports_messages = True
 
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        from .vision_helpers import _prepare_openai_vision_messages
+
+        return _prepare_openai_vision_messages(messages)
+
     def generate(self, prompt: str, options: Optional[dict[str, Any]] = None) -> dict[str, Any]:
         messages = [{"role": "user", "content": prompt}]
         return self._do_generate(messages, options)
 
     def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
-        return self._do_generate(messages, options)
+        return self._do_generate(self._prepare_messages(messages), options)
 
     def _do_generate(self, messages: list[dict[str, str]], options: Optional[dict[str, Any]] = None) -> dict[str, Any]:
         merged_options = self.options.copy()
@@ -58,15 +83,27 @@ class LMStudioDriver(Driver):
             "temperature": merged_options.get("temperature", 0.7),
         }
 
-        # Native JSON mode support
+        # Native JSON mode support (LM Studio requires json_schema, not json_object)
         if merged_options.get("json_mode"):
-            payload["response_format"] = {"type": "json_object"}
+            json_schema = merged_options.get("json_schema")
+            if json_schema:
+                payload["response_format"] = {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": "extraction",
+                        "schema": json_schema,
+                    },
+                }
+            else:
+                # No schema provided — omit response_format entirely;
+                # LM Studio rejects "json_object" type.
+                pass
 
         try:
             logger.debug(f"Sending request to LM Studio endpoint: {self.endpoint}")
             logger.debug(f"Request payload: {payload}")
 
-            r = requests.post(self.endpoint, json=payload, timeout=120)
+            r = requests.post(self.endpoint, json=payload, headers=self._headers, timeout=120)
             r.raise_for_status()
 
             response_data = r.json()
@@ -104,3 +141,31 @@ class LMStudioDriver(Driver):
         }
 
         return {"text": text, "meta": meta}
+
+    # -- Model management (LM Studio 0.4.0+) ----------------------------------
+
+    def list_models(self) -> list[dict[str, Any]]:
+        """List currently loaded models via GET /v1/models (OpenAI-compatible)."""
+        url = f"{self.base_url}/v1/models"
+        r = requests.get(url, headers=self._headers, timeout=10)
+        r.raise_for_status()
+        data = r.json()
+        return data.get("data", [])
+
+    def load_model(self, model: str, context_length: int | None = None) -> dict[str, Any]:
+        """Load a model into LM Studio via POST /api/v1/models/load."""
+        url = f"{self.base_url}/api/v1/models/load"
+        payload: dict[str, Any] = {"model": model}
+        if context_length is not None:
+            payload["context_length"] = context_length
+        r = requests.post(url, json=payload, headers=self._headers, timeout=120)
+        r.raise_for_status()
+        return r.json()
+
+    def unload_model(self, model: str) -> dict[str, Any]:
+        """Unload a model from LM Studio via POST /api/v1/models/unload."""
+        url = f"{self.base_url}/api/v1/models/unload"
+        payload = {"instance_id": model}
+        r = requests.post(url, json=payload, headers=self._headers, timeout=30)
+        r.raise_for_status()
+        return r.json()

prompture/drivers/ollama_driver.py

@@ -13,7 +13,9 @@ logger = logging.getLogger(__name__)
 
 class OllamaDriver(Driver):
     supports_json_mode = True
+    supports_json_schema = True
     supports_streaming = True
+    supports_vision = True
 
     # Ollama is free – costs are always zero.
     MODEL_PRICING = {"default": {"prompt": 0.0, "completion": 0.0}}
@@ -46,6 +48,11 @@ class OllamaDriver(Driver):
 
     supports_messages = True
 
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        from .vision_helpers import _prepare_ollama_vision_messages
+
+        return _prepare_ollama_vision_messages(messages)
+
     def generate(self, prompt: str, options: Optional[dict[str, Any]] = None) -> dict[str, Any]:
         # Merge instance options with call-specific options
         merged_options = self.options.copy()
@@ -58,9 +65,10 @@ class OllamaDriver(Driver):
             "stream": False,
         }
 
-        # Native JSON mode support
+        # Native JSON mode / structured output support
         if merged_options.get("json_mode"):
-            payload["format"] = "json"
+            json_schema = merged_options.get("json_schema")
+            payload["format"] = json_schema if json_schema else "json"
 
         # Add any Ollama-specific options from merged_options
         if "temperature" in merged_options:
@@ -146,7 +154,8 @@ class OllamaDriver(Driver):
         }
 
         if merged_options.get("json_mode"):
-            payload["format"] = "json"
+            json_schema = merged_options.get("json_schema")
+            payload["format"] = json_schema if json_schema else "json"
         if "temperature" in merged_options:
             payload["temperature"] = merged_options["temperature"]
         if "top_p" in merged_options:
@@ -190,6 +199,7 @@ class OllamaDriver(Driver):
 
     def generate_messages(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
         """Use Ollama's /api/chat endpoint for multi-turn conversations."""
+        messages = self._prepare_messages(messages)
         merged_options = self.options.copy()
         if options:
             merged_options.update(options)
@@ -203,9 +213,10 @@ class OllamaDriver(Driver):
             "stream": False,
         }
 
-        # Native JSON mode support
+        # Native JSON mode / structured output support
         if merged_options.get("json_mode"):
-            payload["format"] = "json"
+            json_schema = merged_options.get("json_schema")
+            payload["format"] = json_schema if json_schema else "json"
 
         if "temperature" in merged_options:
             payload["temperature"] = merged_options["temperature"]

prompture/drivers/openai_driver.py

@@ -21,6 +21,7 @@ class OpenAIDriver(CostMixin, Driver):
     supports_json_schema = True
     supports_tool_use = True
     supports_streaming = True
+    supports_vision = True
 
     # Approximate pricing per 1K tokens (keep updated with OpenAI's official pricing)
     # Each model entry also defines which token parameter it supports and
@@ -74,12 +75,17 @@ class OpenAIDriver(CostMixin, Driver):
 
     supports_messages = True
 
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        from .vision_helpers import _prepare_openai_vision_messages
+
+        return _prepare_openai_vision_messages(messages)
+
     def generate(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
         messages = [{"role": "user", "content": prompt}]
         return self._do_generate(messages, options)
 
     def generate_messages(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
-        return self._do_generate(messages, options)
+        return self._do_generate(self._prepare_messages(messages), options)
 
     def _do_generate(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
         if self.client is None:

prompture/drivers/openrouter_driver.py

@@ -13,6 +13,7 @@ from ..driver import Driver
 
 class OpenRouterDriver(CostMixin, Driver):
     supports_json_mode = True
+    supports_vision = True
 
     # Approximate pricing per 1K tokens based on OpenRouter's pricing
     # https://openrouter.ai/docs#pricing
@@ -66,12 +67,17 @@ class OpenRouterDriver(CostMixin, Driver):
 
     supports_messages = True
 
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        from .vision_helpers import _prepare_openai_vision_messages
+
+        return _prepare_openai_vision_messages(messages)
+
     def generate(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
         messages = [{"role": "user", "content": prompt}]
         return self._do_generate(messages, options)
 
     def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
-        return self._do_generate(messages, options)
+        return self._do_generate(self._prepare_messages(messages), options)
 
     def _do_generate(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
         if not self.api_key: