prompture 0.0.38.dev2__py3-none-any.whl → 0.0.42__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.42'
+__version_tuple__ = version_tuple = (0, 0, 42)
 
 __commit_id__ = commit_id = None

prompture/agent.py

@@ -188,7 +188,7 @@ class Agent(Generic[DepsType]):
             for fn in tools:
                 self._tools.register(fn)
 
-        self._state = AgentState.idle
+        self._lifecycle = AgentState.idle
         self._stop_requested = False
 
     # ------------------------------------------------------------------
@@ -206,7 +206,7 @@ class Agent(Generic[DepsType]):
     @property
     def state(self) -> AgentState:
         """Current lifecycle state of the agent."""
-        return self._state
+        return self._lifecycle
 
     def stop(self) -> None:
         """Request graceful shutdown after the current iteration."""
@@ -265,16 +265,16 @@ class Agent(Generic[DepsType]):
             prompt: The user prompt to send.
             deps: Optional dependencies injected into :class:`RunContext`.
         """
-        self._state = AgentState.running
+        self._lifecycle = AgentState.running
         self._stop_requested = False
         steps: list[AgentStep] = []
 
         try:
             result = self._execute(prompt, steps, deps)
-            self._state = AgentState.idle
+            self._lifecycle = AgentState.idle
             return result
         except Exception:
-            self._state = AgentState.errored
+            self._lifecycle = AgentState.errored
             raise
 
     # ------------------------------------------------------------------
@@ -722,7 +722,7 @@ class Agent(Generic[DepsType]):
 
     def _execute_iter(self, prompt: str, deps: Any) -> Generator[AgentStep, None, AgentResult]:
         """Generator that executes the agent loop and yields each step."""
-        self._state = AgentState.running
+        self._lifecycle = AgentState.running
         self._stop_requested = False
         steps: list[AgentStep] = []
 
@@ -730,10 +730,10 @@ class Agent(Generic[DepsType]):
             result = self._execute(prompt, steps, deps)
             # Yield each step one at a time
             yield from result.steps
-            self._state = AgentState.idle
+            self._lifecycle = AgentState.idle
             return result
         except Exception:
-            self._state = AgentState.errored
+            self._lifecycle = AgentState.errored
             raise
 
     # ------------------------------------------------------------------
@@ -757,7 +757,7 @@ class Agent(Generic[DepsType]):
 
     def _execute_stream(self, prompt: str, deps: Any) -> Generator[StreamEvent, None, AgentResult]:
         """Generator that executes the agent loop and yields stream events."""
-        self._state = AgentState.running
+        self._lifecycle = AgentState.running
         self._stop_requested = False
         steps: list[AgentStep] = []
 
@@ -853,10 +853,10 @@ class Agent(Generic[DepsType]):
                 data=result,
             )
 
-            self._state = AgentState.idle
+            self._lifecycle = AgentState.idle
             return result
         except Exception:
-            self._state = AgentState.errored
+            self._lifecycle = AgentState.errored
             raise
 
 

prompture/async_agent.py

@@ -182,7 +182,7 @@ class AsyncAgent(Generic[DepsType]):
             for fn in tools:
                 self._tools.register(fn)
 
-        self._state = AgentState.idle
+        self._lifecycle = AgentState.idle
         self._stop_requested = False
 
     # ------------------------------------------------------------------
@@ -197,7 +197,7 @@ class AsyncAgent(Generic[DepsType]):
     @property
     def state(self) -> AgentState:
         """Current lifecycle state of the agent."""
-        return self._state
+        return self._lifecycle
 
     def stop(self) -> None:
         """Request graceful shutdown after the current iteration."""
@@ -264,16 +264,16 @@ class AsyncAgent(Generic[DepsType]):
         Creates a fresh conversation, sends the prompt, handles tool calls,
         and optionally parses the final response into ``output_type``.
         """
-        self._state = AgentState.running
+        self._lifecycle = AgentState.running
         self._stop_requested = False
         steps: list[AgentStep] = []
 
         try:
             result = await self._execute(prompt, steps, deps)
-            self._state = AgentState.idle
+            self._lifecycle = AgentState.idle
             return result
         except Exception:
-            self._state = AgentState.errored
+            self._lifecycle = AgentState.errored
             raise
 
     async def iter(self, prompt: str, *, deps: Any = None) -> AsyncAgentIterator:
@@ -714,7 +714,7 @@ class AsyncAgent(Generic[DepsType]):
 
     async def _execute_iter(self, prompt: str, deps: Any) -> AsyncGenerator[AgentStep, None]:
         """Async generator that executes the agent loop and yields each step."""
-        self._state = AgentState.running
+        self._lifecycle = AgentState.running
         self._stop_requested = False
         steps: list[AgentStep] = []
 
@@ -722,11 +722,11 @@ class AsyncAgent(Generic[DepsType]):
             result = await self._execute(prompt, steps, deps)
             for step in result.steps:
                 yield step
-            self._state = AgentState.idle
+            self._lifecycle = AgentState.idle
             # Store result on the generator for retrieval
             self._last_iter_result = result
         except Exception:
-            self._state = AgentState.errored
+            self._lifecycle = AgentState.errored
             raise
 
     # ------------------------------------------------------------------
@@ -735,7 +735,7 @@ class AsyncAgent(Generic[DepsType]):
 
     async def _execute_stream(self, prompt: str, deps: Any) -> AsyncGenerator[StreamEvent, None]:
         """Async generator that executes the agent loop and yields stream events."""
-        self._state = AgentState.running
+        self._lifecycle = AgentState.running
         self._stop_requested = False
         steps: list[AgentStep] = []
 
@@ -803,10 +803,10 @@ class AsyncAgent(Generic[DepsType]):
 
             yield StreamEvent(event_type=StreamEventType.output, data=result)
 
-            self._state = AgentState.idle
+            self._lifecycle = AgentState.idle
             self._last_stream_result = result
         except Exception:
-            self._state = AgentState.errored
+            self._lifecycle = AgentState.errored
             raise
 
 

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/async_groups.py

@@ -70,6 +70,27 @@ class ParallelGroup:
         """Request graceful shutdown."""
         self._stop_requested = True
 
+    @property
+    def shared_state(self) -> dict[str, Any]:
+        """Return a copy of the current shared execution state."""
+        return dict(self._state)
+
+    def inject_state(self, state: dict[str, Any], *, recursive: bool = False) -> None:
+        """Merge external key-value pairs into this group's shared state.
+
+        Existing keys are NOT overwritten (uses setdefault semantics).
+
+        Args:
+            state: Key-value pairs to inject.
+            recursive: If True, also inject into nested sub-groups.
+        """
+        for k, v in state.items():
+            self._state.setdefault(k, v)
+        if recursive:
+            for agent, _ in self._agents:
+                if hasattr(agent, "inject_state"):
+                    agent.inject_state(state, recursive=True)
+
     async def run_async(self, prompt: str = "") -> GroupResult:
         """Execute all agents concurrently."""
         self._stop_requested = False
@@ -213,6 +234,27 @@ class AsyncSequentialGroup:
     def stop(self) -> None:
         self._stop_requested = True
 
+    @property
+    def shared_state(self) -> dict[str, Any]:
+        """Return a copy of the current shared execution state."""
+        return dict(self._state)
+
+    def inject_state(self, state: dict[str, Any], *, recursive: bool = False) -> None:
+        """Merge external key-value pairs into this group's shared state.
+
+        Existing keys are NOT overwritten (uses setdefault semantics).
+
+        Args:
+            state: Key-value pairs to inject.
+            recursive: If True, also inject into nested sub-groups.
+        """
+        for k, v in state.items():
+            self._state.setdefault(k, v)
+        if recursive:
+            for agent, _ in self._agents:
+                if hasattr(agent, "inject_state"):
+                    agent.inject_state(state, recursive=True)
+
     async def run(self, prompt: str = "") -> GroupResult:
         """Execute all agents in sequence (async)."""
         self._stop_requested = False
@@ -351,6 +393,27 @@ class AsyncLoopGroup:
     def stop(self) -> None:
         self._stop_requested = True
 
+    @property
+    def shared_state(self) -> dict[str, Any]:
+        """Return a copy of the current shared execution state."""
+        return dict(self._state)
+
+    def inject_state(self, state: dict[str, Any], *, recursive: bool = False) -> None:
+        """Merge external key-value pairs into this group's shared state.
+
+        Existing keys are NOT overwritten (uses setdefault semantics).
+
+        Args:
+            state: Key-value pairs to inject.
+            recursive: If True, also inject into nested sub-groups.
+        """
+        for k, v in state.items():
+            self._state.setdefault(k, v)
+        if recursive:
+            for agent, _ in self._agents:
+                if hasattr(agent, "inject_state"):
+                    agent.inject_state(state, recursive=True)
+
     async def run(self, prompt: str = "") -> GroupResult:
         """Execute the loop (async)."""
         self._stop_requested = False

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

@@ -2,9 +2,34 @@
 
 from __future__ import annotations
 
+import copy
 from typing import Any
 
 
+def prepare_strict_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Prepare a JSON schema for OpenAI strict structured-output mode.
+
+    OpenAI's ``strict: true`` requires every object to have
+    ``"additionalProperties": false`` and a ``"required"`` array listing
+    all property keys.  This function recursively patches a schema copy
+    so callers don't need to worry about these constraints.
+    """
+    schema = copy.deepcopy(schema)
+    _patch_strict(schema)
+    return schema
+
+
+def _patch_strict(node: dict[str, Any]) -> None:
+    """Recursively add strict-mode constraints to an object schema node."""
+    if node.get("type") == "object" and "properties" in node:
+        node.setdefault("additionalProperties", False)
+        node.setdefault("required", list(node["properties"].keys()))
+        for prop in node["properties"].values():
+            _patch_strict(prop)
+    elif node.get("type") == "array" and isinstance(node.get("items"), dict):
+        _patch_strict(node["items"])
+
+
 class CostMixin:
     """Mixin that provides ``_calculate_cost`` to sync and async drivers.
 
@@ -49,3 +74,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,
+        }