prompture 0.0.38.dev2__py3-none-any.whl → 0.0.40.dev1__py3-none-any.whl

prompture/__init__.py

@@ -110,8 +110,15 @@ from .image import (
     image_from_url,
     make_image,
 )
+from .ledger import ModelUsageLedger, get_recently_used_models
 from .logging import JSONFormatter, configure_logging
-from .model_rates import get_model_info, get_model_rates, refresh_rates_cache
+from .model_rates import (
+    ModelCapabilities,
+    get_model_capabilities,
+    get_model_info,
+    get_model_rates,
+    refresh_rates_cache,
+)
 from .persistence import ConversationStore
 from .persona import (
     PERSONAS,
@@ -213,7 +220,9 @@ __all__ = [
     "LocalHTTPDriver",
     "LoopGroup",
     "MemoryCacheBackend",
+    "ModelCapabilities",
     "ModelRetry",
+    "ModelUsageLedger",
     "OllamaDriver",
     "OpenAIDriver",
     "OpenRouterDriver",
@@ -255,11 +264,13 @@ __all__ = [
     "get_driver_for_model",
     "get_field_definition",
     "get_field_names",
+    "get_model_capabilities",
     "get_model_info",
     "get_model_rates",
     "get_persona",
     "get_persona_names",
     "get_persona_registry_snapshot",
+    "get_recently_used_models",
     "get_registry_snapshot",
     "get_required_fields",
     "get_trait",

prompture/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.38.dev2'
-__version_tuple__ = version_tuple = (0, 0, 38, 'dev2')
+__version__ = version = '0.0.40.dev1'
+__version_tuple__ = version_tuple = (0, 0, 40, 'dev1')
 
 __commit_id__ = commit_id = None

prompture/async_conversation.py

@@ -304,6 +304,15 @@ class AsyncConversation:
         self._usage["turns"] += 1
         self._maybe_auto_save()
 
+        from .ledger import _resolve_api_key_hash, record_model_usage
+
+        record_model_usage(
+            self._model_name,
+            api_key_hash=_resolve_api_key_hash(self._model_name),
+            tokens=meta.get("total_tokens", 0),
+            cost=meta.get("cost", 0.0),
+        )
+
     async def ask(
         self,
         content: str,

prompture/async_core.py

@@ -35,6 +35,18 @@ from .tools import (
 logger = logging.getLogger("prompture.async_core")
 
 
+def _record_usage_to_ledger(model_name: str, meta: dict[str, Any]) -> None:
+    """Fire-and-forget ledger recording for standalone async core functions."""
+    from .ledger import _resolve_api_key_hash, record_model_usage
+
+    record_model_usage(
+        model_name,
+        api_key_hash=_resolve_api_key_hash(model_name),
+        tokens=meta.get("total_tokens", 0),
+        cost=meta.get("cost", 0.0),
+    )
+
+
 async def clean_json_text_with_ai(
     driver: AsyncDriver, text: str, model_name: str = "", options: dict[str, Any] | None = None
 ) -> str:
@@ -117,6 +129,8 @@ async def render_output(
         "model_name": model_name or getattr(driver, "model", ""),
     }
 
+    _record_usage_to_ledger(model_name, resp.get("meta", {}))
+
     return {"text": raw, "usage": usage, "output_format": output_format}
 
 
@@ -211,6 +225,8 @@ async def ask_for_json(
     raw = resp.get("text", "")
     cleaned = clean_json_text(raw)
 
+    _record_usage_to_ledger(model_name, resp.get("meta", {}))
+
     try:
         json_obj = json.loads(cleaned)
         json_string = cleaned

prompture/async_driver.py

@@ -166,6 +166,45 @@ class AsyncDriver:
         except Exception:
             logger.exception("Callback %s raised an exception", event)
 
+    def _validate_model_capabilities(
+        self,
+        provider: str,
+        model: str,
+        *,
+        using_tool_use: bool = False,
+        using_json_schema: bool = False,
+        using_vision: bool = False,
+    ) -> None:
+        """Log warnings when the model may not support a requested feature.
+
+        Uses models.dev metadata as a secondary signal.  Warnings only — the
+        API is the final authority and models.dev data may be stale.
+        """
+        from .model_rates import get_model_capabilities
+
+        caps = get_model_capabilities(provider, model)
+        if caps is None:
+            return
+
+        if using_tool_use and caps.supports_tool_use is False:
+            logger.warning(
+                "Model %s/%s may not support tool use according to models.dev metadata",
+                provider,
+                model,
+            )
+        if using_json_schema and caps.supports_structured_output is False:
+            logger.warning(
+                "Model %s/%s may not support structured output / JSON schema according to models.dev metadata",
+                provider,
+                model,
+            )
+        if using_vision and caps.supports_vision is False:
+            logger.warning(
+                "Model %s/%s may not support vision/image inputs according to models.dev metadata",
+                provider,
+                model,
+            )
+
     def _check_vision_support(self, messages: list[dict[str, Any]]) -> None:
         """Raise if messages contain image blocks and the driver lacks vision support."""
         if self.supports_vision:

prompture/conversation.py

@@ -311,6 +311,15 @@ class Conversation:
         self._usage["turns"] += 1
         self._maybe_auto_save()
 
+        from .ledger import _resolve_api_key_hash, record_model_usage
+
+        record_model_usage(
+            self._model_name,
+            api_key_hash=_resolve_api_key_hash(self._model_name),
+            tokens=meta.get("total_tokens", 0),
+            cost=meta.get("cost", 0.0),
+        )
+
     def ask(
         self,
         content: str,

prompture/core.py

@@ -31,6 +31,18 @@ from .tools import (
 logger = logging.getLogger("prompture.core")
 
 
+def _record_usage_to_ledger(model_name: str, meta: dict[str, Any]) -> None:
+    """Fire-and-forget ledger recording for standalone core functions."""
+    from .ledger import _resolve_api_key_hash, record_model_usage
+
+    record_model_usage(
+        model_name,
+        api_key_hash=_resolve_api_key_hash(model_name),
+        tokens=meta.get("total_tokens", 0),
+        cost=meta.get("cost", 0.0),
+    )
+
+
 def _build_content_with_images(text: str, images: list[ImageInput] | None = None) -> str | list[dict[str, Any]]:
     """Return plain string when no images, or a list of content blocks."""
     if not images:
@@ -231,6 +243,8 @@ def render_output(
         "model_name": model_name or getattr(driver, "model", ""),
     }
 
+    _record_usage_to_ledger(model_name, resp.get("meta", {}))
+
     return {"text": raw, "usage": usage, "output_format": output_format}
 
 
@@ -353,6 +367,8 @@ def ask_for_json(
     raw = resp.get("text", "")
     cleaned = clean_json_text(raw)
 
+    _record_usage_to_ledger(model_name, resp.get("meta", {}))
+
     try:
         json_obj = json.loads(cleaned)
         json_string = cleaned

prompture/cost_mixin.py

@@ -49,3 +49,40 @@ class CostMixin:
             completion_cost = (completion_tokens / unit) * model_pricing["completion"]
 
         return round(prompt_cost + completion_cost, 6)
+
+    def _get_model_config(self, provider: str, model: str) -> dict[str, Any]:
+        """Merge live models.dev capabilities with hardcoded ``MODEL_PRICING``.
+
+        Returns a dict with:
+        - ``tokens_param`` — always from hardcoded ``MODEL_PRICING`` (API-specific)
+        - ``supports_temperature`` — prefers live data, falls back to hardcoded, default ``True``
+        - ``context_window`` — from live data only (``None`` if unavailable)
+        - ``max_output_tokens`` — from live data only (``None`` if unavailable)
+        """
+        from .model_rates import get_model_capabilities
+
+        hardcoded = self.MODEL_PRICING.get(model, {})
+
+        # tokens_param is always from hardcoded config (API-specific, not in models.dev)
+        tokens_param = hardcoded.get("tokens_param", "max_tokens")
+
+        # Start with hardcoded supports_temperature, default True
+        supports_temperature = hardcoded.get("supports_temperature", True)
+
+        context_window: int | None = None
+        max_output_tokens: int | None = None
+
+        # Override with live data when available
+        caps = get_model_capabilities(provider, model)
+        if caps is not None:
+            if caps.supports_temperature is not None:
+                supports_temperature = caps.supports_temperature
+            context_window = caps.context_window
+            max_output_tokens = caps.max_output_tokens
+
+        return {
+            "tokens_param": tokens_param,
+            "supports_temperature": supports_temperature,
+            "context_window": context_window,
+            "max_output_tokens": max_output_tokens,
+        }

prompture/discovery.py

@@ -1,7 +1,11 @@
 """Discovery module for auto-detecting available models."""
 
+from __future__ import annotations
+
+import dataclasses
 import logging
 import os
+from typing import Any, overload
 
 import requests
 
@@ -22,23 +26,40 @@ from .settings import settings
 logger = logging.getLogger(__name__)
 
 
-def get_available_models() -> list[str]:
-    """
-    Auto-detects all available models based on configured drivers and environment variables.
+@overload
+def get_available_models(*, include_capabilities: bool = False, verified_only: bool = False) -> list[str]: ...
+
+
+@overload
+def get_available_models(*, include_capabilities: bool = True, verified_only: bool = False) -> list[dict[str, Any]]: ...
+
+
+def get_available_models(
+    *,
+    include_capabilities: bool = False,
+    verified_only: bool = False,
+) -> list[str] | list[dict[str, Any]]:
+    """Auto-detect available models based on configured drivers and environment variables.
+
+    Iterates through supported providers and checks if they are configured
+    (e.g. API key present).  For static drivers, returns models from their
+    ``MODEL_PRICING`` keys.  For dynamic drivers (like Ollama), attempts to
+    fetch available models from the endpoint.
 
-    Iterates through supported providers and checks if they are configured (e.g. API key present).
-    For static drivers, returns models from their MODEL_PRICING keys.
-    For dynamic drivers (like Ollama), attempts to fetch available models from the endpoint.
+    Args:
+        include_capabilities: When ``True``, return enriched dicts with
+            ``model``, ``provider``, ``model_id``, and ``capabilities``
+            fields instead of plain ``"provider/model_id"`` strings.
+        verified_only: When ``True``, only return models that have been
+            successfully used (as recorded by the usage ledger).
 
     Returns:
-        A list of unique model strings in the format "provider/model_id".
+        A sorted list of unique model strings (default) or enriched dicts.
     """
     available_models: set[str] = set()
     configured_providers: set[str] = set()
 
     # Map of provider name to driver class
-    # We need to map the registry keys to the actual classes to check MODEL_PRICING
-    # and instantiate for dynamic checks if needed.
     provider_classes = {
         "openai": OpenAIDriver,
         "azure": AzureDriver,
@@ -54,11 +75,6 @@ def get_available_models() -> list[str]:
 
     for provider, driver_cls in provider_classes.items():
         try:
-            # 1. Check if the provider is configured (has API key or endpoint)
-            # We can check this by looking at the settings or env vars that the driver uses.
-            # A simple way is to try to instantiate it with defaults, but that might fail if keys are missing.
-            # Instead, let's check the specific requirements for each known provider.
-
             is_configured = False
 
             if provider == "openai":
@@ -86,14 +102,11 @@ def get_available_models() -> list[str]:
             elif provider == "grok":
                 if settings.grok_api_key or os.getenv("GROK_API_KEY"):
                     is_configured = True
-            elif provider == "ollama":
-                # Ollama is always considered "configured" as it defaults to localhost
-                # We will check connectivity later
-                is_configured = True
-            elif provider == "lmstudio":
-                # LM Studio is similar to Ollama, defaults to localhost
-                is_configured = True
-            elif provider == "local_http" and (settings.local_http_endpoint or os.getenv("LOCAL_HTTP_ENDPOINT")):
+            elif (
+                provider == "ollama"
+                or provider == "lmstudio"
+                or (provider == "local_http" and os.getenv("LOCAL_HTTP_ENDPOINT"))
+            ):
                 is_configured = True
 
             if not is_configured:
@@ -101,36 +114,20 @@ def get_available_models() -> list[str]:
 
             configured_providers.add(provider)
 
-            # 2. Static Detection: Get models from MODEL_PRICING
+            # Static Detection: Get models from MODEL_PRICING
             if hasattr(driver_cls, "MODEL_PRICING"):
                 pricing = driver_cls.MODEL_PRICING
                 for model_id in pricing:
-                    # Skip "default" or generic keys if they exist
                     if model_id == "default":
                         continue
-
-                    # For Azure, the model_id in pricing is usually the base model name,
-                    # but the user needs to use the deployment ID.
-                    # However, our Azure driver implementation uses the deployment_id from init
-                    # as the "model" for the request, but expects the user to pass a model name
-                    # that maps to pricing?
-                    # Looking at AzureDriver:
-                    # kwargs = {"model": self.deployment_id, ...}
-                    # model = options.get("model", self.model) -> used for pricing lookup
-                    # So we should list the keys in MODEL_PRICING as available "models"
-                    # even though for Azure specifically it's a bit weird because of deployment IDs.
-                    # But for general discovery, listing supported models is correct.
-
                     available_models.add(f"{provider}/{model_id}")
 
-            # 3. Dynamic Detection: Specific logic for Ollama
+            # Dynamic Detection: Specific logic for Ollama
             if provider == "ollama":
                 try:
                     endpoint = settings.ollama_endpoint or os.getenv(
                         "OLLAMA_ENDPOINT", "http://localhost:11434/api/generate"
                     )
-                    # We need the base URL for tags, usually http://localhost:11434/api/tags
-                    # The configured endpoint might be .../api/generate or .../api/chat
                     base_url = endpoint.split("/api/")[0]
                     tags_url = f"{base_url}/api/tags"
 
@@ -141,8 +138,6 @@ def get_available_models() -> list[str]:
                         for model in models:
                             name = model.get("name")
                             if name:
-                                # Ollama model names often include tags like "llama3:latest"
-                                # We can keep them as is.
                                 available_models.add(f"ollama/{name}")
                 except Exception as e:
                     logger.debug(f"Failed to fetch Ollama models: {e}")
@@ -184,4 +179,74 @@ def get_available_models() -> list[str]:
             for model_id in get_all_provider_models(api_name):
                 available_models.add(f"{prompture_name}/{model_id}")
 
-    return sorted(list(available_models))
+    sorted_models = sorted(available_models)
+
+    # --- verified_only filtering ---
+    verified_set: set[str] | None = None
+    if verified_only or include_capabilities:
+        try:
+            from .ledger import _get_ledger
+
+            ledger = _get_ledger()
+            verified_set = ledger.get_verified_models()
+        except Exception:
+            logger.debug("Could not load ledger for verified models", exc_info=True)
+            verified_set = set()
+
+    if verified_only and verified_set is not None:
+        sorted_models = [m for m in sorted_models if m in verified_set]
+
+    if not include_capabilities:
+        return sorted_models
+
+    # Build enriched dicts with capabilities from models.dev
+    from .model_rates import get_model_capabilities
+
+    # Fetch all ledger stats for annotation (keyed by model_name)
+    ledger_stats: dict[str, dict[str, Any]] = {}
+    try:
+        from .ledger import _get_ledger
+
+        for row in _get_ledger().get_all_stats():
+            name = row["model_name"]
+            if name not in ledger_stats:
+                ledger_stats[name] = row
+            else:
+                # Aggregate across API key hashes
+                existing = ledger_stats[name]
+                existing["use_count"] += row["use_count"]
+                existing["total_tokens"] += row["total_tokens"]
+                existing["total_cost"] += row["total_cost"]
+                if row["last_used"] > existing["last_used"]:
+                    existing["last_used"] = row["last_used"]
+    except Exception:
+        logger.debug("Could not load ledger stats for enrichment", exc_info=True)
+
+    enriched: list[dict[str, Any]] = []
+    for model_str in sorted_models:
+        parts = model_str.split("/", 1)
+        provider = parts[0]
+        model_id = parts[1] if len(parts) > 1 else parts[0]
+
+        caps = get_model_capabilities(provider, model_id)
+        caps_dict = dataclasses.asdict(caps) if caps is not None else None
+
+        entry: dict[str, Any] = {
+            "model": model_str,
+            "provider": provider,
+            "model_id": model_id,
+            "capabilities": caps_dict,
+            "verified": verified_set is not None and model_str in verified_set,
+        }
+
+        stats = ledger_stats.get(model_str)
+        if stats:
+            entry["last_used"] = stats["last_used"]
+            entry["use_count"] = stats["use_count"]
+        else:
+            entry["last_used"] = None
+            entry["use_count"] = 0
+
+        enriched.append(entry)
+
+    return enriched

prompture/driver.py

@@ -173,6 +173,45 @@ class Driver:
         except Exception:
             logger.exception("Callback %s raised an exception", event)
 
+    def _validate_model_capabilities(
+        self,
+        provider: str,
+        model: str,
+        *,
+        using_tool_use: bool = False,
+        using_json_schema: bool = False,
+        using_vision: bool = False,
+    ) -> None:
+        """Log warnings when the model may not support a requested feature.
+
+        Uses models.dev metadata as a secondary signal.  Warnings only — the
+        API is the final authority and models.dev data may be stale.
+        """
+        from .model_rates import get_model_capabilities
+
+        caps = get_model_capabilities(provider, model)
+        if caps is None:
+            return
+
+        if using_tool_use and caps.supports_tool_use is False:
+            logger.warning(
+                "Model %s/%s may not support tool use according to models.dev metadata",
+                provider,
+                model,
+            )
+        if using_json_schema and caps.supports_structured_output is False:
+            logger.warning(
+                "Model %s/%s may not support structured output / JSON schema according to models.dev metadata",
+                provider,
+                model,
+            )
+        if using_vision and caps.supports_vision is False:
+            logger.warning(
+                "Model %s/%s may not support vision/image inputs according to models.dev metadata",
+                provider,
+                model,
+            )
+
     def _check_vision_support(self, messages: list[dict[str, Any]]) -> None:
         """Raise if messages contain image blocks and the driver lacks vision support."""
         if self.supports_vision:

prompture/drivers/async_azure_driver.py

@@ -70,9 +70,9 @@ class AsyncAzureDriver(CostMixin, AsyncDriver):
             raise RuntimeError("openai package (>=1.0.0) with AsyncAzureOpenAI not installed")
 
         model = options.get("model", self.model)
-        model_info = self.MODEL_PRICING.get(model, {})
-        tokens_param = model_info.get("tokens_param", "max_tokens")
-        supports_temperature = model_info.get("supports_temperature", True)
+        model_config = self._get_model_config("azure", model)
+        tokens_param = model_config["tokens_param"]
+        supports_temperature = model_config["supports_temperature"]
 
         opts = {"temperature": 1.0, "max_tokens": 512, **options}
 
@@ -113,7 +113,7 @@ class AsyncAzureDriver(CostMixin, AsyncDriver):
             "prompt_tokens": prompt_tokens,
             "completion_tokens": completion_tokens,
             "total_tokens": total_tokens,
-            "cost": total_cost,
+            "cost": round(total_cost, 6),
             "raw_response": resp.model_dump(),
             "model_name": model,
             "deployment_id": self.deployment_id,