prompture 0.0.47.dev1__tar.gz → 0.0.47.dev3__tar.gz

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 0.0.47.dev1
+Version: 0.0.47.dev3
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT
@@ -83,7 +83,7 @@ print(person.name)  # Maria
 - **Stepwise extraction** — Per-field prompts with smart type coercion (shorthand numbers, multilingual booleans, dates)
 - **Field registry** — 50+ predefined extraction fields with template variables and Pydantic integration
 - **Conversations** — Stateful multi-turn sessions with sync and async support
-- **Tool use** — Function calling and streaming across supported providers
+- **Tool use** — Function calling and streaming across supported providers, with automatic prompt-based simulation for models without native tool support
 - **Caching** — Built-in response cache with memory, SQLite, and Redis backends
 - **Plugin system** — Register custom drivers via entry points
 - **Usage tracking** — Token counts and cost calculation on every call
@@ -296,6 +296,39 @@ response = conv.send("What is the capital of France?")
 follow_up = conv.send("What about Germany?")  # retains context
 ```
 
+### Tool Use
+
+Register Python functions as tools the LLM can call during a conversation:
+
+```python
+from prompture import Conversation, ToolRegistry
+
+registry = ToolRegistry()
+
+@registry.tool
+def get_weather(city: str, units: str = "celsius") -> str:
+    """Get the current weather for a city."""
+    return f"Weather in {city}: 22 {units}"
+
+conv = Conversation("openai/gpt-4", tools=registry)
+result = conv.ask("What's the weather in London?")
+```
+
+For models without native function calling (Ollama, LM Studio, etc.), Prompture automatically simulates tool use by describing tools in the prompt and parsing structured JSON responses:
+
+```python
+# Auto-detect: uses native tool calling if available, simulation otherwise
+conv = Conversation("ollama/llama3.1:8b", tools=registry, simulated_tools="auto")
+
+# Force simulation even on capable models
+conv = Conversation("openai/gpt-4", tools=registry, simulated_tools=True)
+
+# Disable tool use entirely
+conv = Conversation("openai/gpt-4", tools=registry, simulated_tools=False)
+```
+
+The simulation loop describes tools in the system prompt, asks the model to respond with JSON (`tool_call` or `final_answer`), executes tools, and feeds results back — all transparent to the caller.
+
 ### Model Discovery
 
 Auto-detect available models from configured providers:

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/README.md

@@ -36,7 +36,7 @@ print(person.name)  # Maria
 - **Stepwise extraction** — Per-field prompts with smart type coercion (shorthand numbers, multilingual booleans, dates)
 - **Field registry** — 50+ predefined extraction fields with template variables and Pydantic integration
 - **Conversations** — Stateful multi-turn sessions with sync and async support
-- **Tool use** — Function calling and streaming across supported providers
+- **Tool use** — Function calling and streaming across supported providers, with automatic prompt-based simulation for models without native tool support
 - **Caching** — Built-in response cache with memory, SQLite, and Redis backends
 - **Plugin system** — Register custom drivers via entry points
 - **Usage tracking** — Token counts and cost calculation on every call
@@ -249,6 +249,39 @@ response = conv.send("What is the capital of France?")
 follow_up = conv.send("What about Germany?")  # retains context
 ```
 
+### Tool Use
+
+Register Python functions as tools the LLM can call during a conversation:
+
+```python
+from prompture import Conversation, ToolRegistry
+
+registry = ToolRegistry()
+
+@registry.tool
+def get_weather(city: str, units: str = "celsius") -> str:
+    """Get the current weather for a city."""
+    return f"Weather in {city}: 22 {units}"
+
+conv = Conversation("openai/gpt-4", tools=registry)
+result = conv.ask("What's the weather in London?")
+```
+
+For models without native function calling (Ollama, LM Studio, etc.), Prompture automatically simulates tool use by describing tools in the prompt and parsing structured JSON responses:
+
+```python
+# Auto-detect: uses native tool calling if available, simulation otherwise
+conv = Conversation("ollama/llama3.1:8b", tools=registry, simulated_tools="auto")
+
+# Force simulation even on capable models
+conv = Conversation("openai/gpt-4", tools=registry, simulated_tools=True)
+
+# Disable tool use entirely
+conv = Conversation("openai/gpt-4", tools=registry, simulated_tools=False)
+```
+
+The simulation loop describes tools in the system prompt, asks the model to respond with JSON (`tool_call` or `final_answer`), executes tools, and feeds results back — all transparent to the caller.
+
 ### Model Discovery
 
 Auto-detect available models from configured providers:

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/prompture/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.47.dev1'
-__version_tuple__ = version_tuple = (0, 0, 47, 'dev1')
+__version__ = version = '0.0.47.dev3'
+__version_tuple__ = version_tuple = (0, 0, 47, 'dev3')
 
 __commit_id__ = commit_id = None

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/prompture/async_conversation.py

@@ -55,6 +55,7 @@ class AsyncConversation:
         callbacks: DriverCallbacks | None = None,
         tools: ToolRegistry | None = None,
         max_tool_rounds: int = 10,
+        simulated_tools: bool | Literal["auto"] = "auto",
         conversation_id: str | None = None,
         auto_save: str | Path | None = None,
         tags: list[str] | None = None,
@@ -106,6 +107,10 @@ class AsyncConversation:
         }
         self._tools = tools or ToolRegistry()
         self._max_tool_rounds = max_tool_rounds
+        self._simulated_tools = simulated_tools
+
+        # Reasoning content from last response
+        self._last_reasoning: str | None = None
 
         # Persistence
         self._conversation_id = conversation_id or str(uuid.uuid4())
@@ -119,6 +124,11 @@ class AsyncConversation:
     # Public helpers
     # ------------------------------------------------------------------
 
+    @property
+    def last_reasoning(self) -> str | None:
+        """The reasoning/thinking content from the last LLM response, if any."""
+        return self._last_reasoning
+
     @property
     def messages(self) -> list[dict[str, Any]]:
         """Read-only view of the conversation history."""
@@ -324,8 +334,15 @@ class AsyncConversation:
         If tools are registered and the driver supports tool use,
         dispatches to the async tool execution loop.
         """
-        if self._tools and getattr(self._driver, "supports_tool_use", False):
-            return await self._ask_with_tools(content, options, images=images)
+        self._last_reasoning = None
+
+        # Route to appropriate tool handling
+        if self._tools:
+            use_native = getattr(self._driver, "supports_tool_use", False)
+            if self._simulated_tools is True or (self._simulated_tools == "auto" and not use_native):
+                return await self._ask_with_simulated_tools(content, options, images=images)
+            elif use_native and self._simulated_tools is not True:
+                return await self._ask_with_tools(content, options, images=images)
 
         merged = {**self._options, **(options or {})}
         messages = self._build_messages(content, images=images)
@@ -333,6 +350,7 @@ class AsyncConversation:
 
         text = resp.get("text", "")
         meta = resp.get("meta", {})
+        self._last_reasoning = resp.get("reasoning_content")
 
         user_content = self._build_content_with_images(content, images)
         self._messages.append({"role": "user", "content": user_content})
@@ -365,6 +383,7 @@ class AsyncConversation:
             text = resp.get("text", "")
 
             if not tool_calls:
+                self._last_reasoning = resp.get("reasoning_content")
                 self._messages.append({"role": "assistant", "content": text})
                 return text
 
@@ -377,6 +396,11 @@ class AsyncConversation:
                 }
                 for tc in tool_calls
             ]
+            # Preserve reasoning_content for providers that require it
+            # on subsequent requests (e.g. Moonshot reasoning models).
+            if resp.get("reasoning_content") is not None:
+                assistant_msg["reasoning_content"] = resp["reasoning_content"]
+
             self._messages.append(assistant_msg)
             msgs.append(assistant_msg)
 
@@ -397,6 +421,63 @@ class AsyncConversation:
 
         raise RuntimeError(f"Tool execution loop exceeded {self._max_tool_rounds} rounds")
 
+    async def _ask_with_simulated_tools(
+        self,
+        content: str,
+        options: dict[str, Any] | None = None,
+        images: list[ImageInput] | None = None,
+    ) -> str:
+        """Async prompt-based tool calling for drivers without native tool use."""
+        from .simulated_tools import build_tool_prompt, format_tool_result, parse_simulated_response
+
+        merged = {**self._options, **(options or {})}
+        tool_prompt = build_tool_prompt(self._tools)
+
+        # Augment system prompt with tool descriptions
+        augmented_system = tool_prompt
+        if self._system_prompt:
+            augmented_system = f"{self._system_prompt}\n\n{tool_prompt}"
+
+        # Record user message in history
+        user_content = self._build_content_with_images(content, images)
+        self._messages.append({"role": "user", "content": user_content})
+
+        for _round in range(self._max_tool_rounds):
+            # Build messages with the augmented system prompt
+            msgs: list[dict[str, Any]] = []
+            msgs.append({"role": "system", "content": augmented_system})
+            msgs.extend(self._messages)
+
+            resp = await self._driver.generate_messages_with_hooks(msgs, merged)
+            text = resp.get("text", "")
+            meta = resp.get("meta", {})
+            self._accumulate_usage(meta)
+
+            parsed = parse_simulated_response(text, self._tools)
+
+            if parsed["type"] == "final_answer":
+                answer = parsed["content"]
+                self._messages.append({"role": "assistant", "content": answer})
+                return answer
+
+            # Tool call
+            tool_name = parsed["name"]
+            tool_args = parsed["arguments"]
+
+            # Record assistant's tool call as an assistant message
+            self._messages.append({"role": "assistant", "content": text})
+
+            try:
+                result = self._tools.execute(tool_name, tool_args)
+                result_msg = format_tool_result(tool_name, result)
+            except Exception as exc:
+                result_msg = format_tool_result(tool_name, f"Error: {exc}")
+
+            # Record tool result as a user message
+            self._messages.append({"role": "user", "content": result_msg})
+
+        raise RuntimeError(f"Simulated tool execution loop exceeded {self._max_tool_rounds} rounds")
+
     def _build_messages_raw(self) -> list[dict[str, Any]]:
         """Build messages array from system prompt + full history (including tool messages)."""
         msgs: list[dict[str, Any]] = []
@@ -457,6 +538,8 @@ class AsyncConversation:
         images: list[ImageInput] | None = None,
     ) -> dict[str, Any]:
         """Send a message with schema enforcement and get structured JSON back (async)."""
+        self._last_reasoning = None
+
         merged = {**self._options, **(options or {})}
 
         schema_string = json.dumps(json_schema, indent=2)
@@ -494,6 +577,7 @@ class AsyncConversation:
 
         text = resp.get("text", "")
         meta = resp.get("meta", {})
+        self._last_reasoning = resp.get("reasoning_content")
 
         user_content = self._build_content_with_images(content, images)
         self._messages.append({"role": "user", "content": user_content})
@@ -528,6 +612,7 @@ class AsyncConversation:
             "json_object": json_obj,
             "usage": usage,
             "output_format": output_format,
+            "reasoning": self._last_reasoning,
         }
 
         if output_format == "toon":

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/prompture/conversation.py

@@ -56,6 +56,7 @@ class Conversation:
         callbacks: DriverCallbacks | None = None,
         tools: ToolRegistry | None = None,
         max_tool_rounds: int = 10,
+        simulated_tools: bool | Literal["auto"] = "auto",
         conversation_id: str | None = None,
         auto_save: str | Path | None = None,
         tags: list[str] | None = None,
@@ -109,6 +110,10 @@ class Conversation:
         }
         self._tools = tools or ToolRegistry()
         self._max_tool_rounds = max_tool_rounds
+        self._simulated_tools = simulated_tools
+
+        # Reasoning content from last response
+        self._last_reasoning: str | None = None
 
         # Persistence
         self._conversation_id = conversation_id or str(uuid.uuid4())
@@ -122,6 +127,11 @@ class Conversation:
     # Public helpers
     # ------------------------------------------------------------------
 
+    @property
+    def last_reasoning(self) -> str | None:
+        """The reasoning/thinking content from the last LLM response, if any."""
+        return self._last_reasoning
+
     @property
     def messages(self) -> list[dict[str, Any]]:
         """Read-only view of the conversation history."""
@@ -338,8 +348,15 @@ class Conversation:
             images: Optional list of images to include (bytes, path, URL,
                 base64 string, or :class:`ImageContent`).
         """
-        if self._tools and getattr(self._driver, "supports_tool_use", False):
-            return self._ask_with_tools(content, options, images=images)
+        self._last_reasoning = None
+
+        # Route to appropriate tool handling
+        if self._tools:
+            use_native = getattr(self._driver, "supports_tool_use", False)
+            if self._simulated_tools is True or (self._simulated_tools == "auto" and not use_native):
+                return self._ask_with_simulated_tools(content, options, images=images)
+            elif use_native and self._simulated_tools is not True:
+                return self._ask_with_tools(content, options, images=images)
 
         merged = {**self._options, **(options or {})}
         messages = self._build_messages(content, images=images)
@@ -347,6 +364,7 @@ class Conversation:
 
         text = resp.get("text", "")
         meta = resp.get("meta", {})
+        self._last_reasoning = resp.get("reasoning_content")
 
         # Record in history — store content with images for context
         user_content = self._build_content_with_images(content, images)
@@ -382,6 +400,7 @@ class Conversation:
 
             if not tool_calls:
                 # No tool calls -> final response
+                self._last_reasoning = resp.get("reasoning_content")
                 self._messages.append({"role": "assistant", "content": text})
                 return text
 
@@ -395,6 +414,11 @@ class Conversation:
                 }
                 for tc in tool_calls
             ]
+            # Preserve reasoning_content for providers that require it
+            # on subsequent requests (e.g. Moonshot reasoning models).
+            if resp.get("reasoning_content") is not None:
+                assistant_msg["reasoning_content"] = resp["reasoning_content"]
+
             self._messages.append(assistant_msg)
             msgs.append(assistant_msg)
 
@@ -416,6 +440,63 @@ class Conversation:
 
         raise RuntimeError(f"Tool execution loop exceeded {self._max_tool_rounds} rounds")
 
+    def _ask_with_simulated_tools(
+        self,
+        content: str,
+        options: dict[str, Any] | None = None,
+        images: list[ImageInput] | None = None,
+    ) -> str:
+        """Prompt-based tool calling for drivers without native tool use."""
+        from .simulated_tools import build_tool_prompt, format_tool_result, parse_simulated_response
+
+        merged = {**self._options, **(options or {})}
+        tool_prompt = build_tool_prompt(self._tools)
+
+        # Augment system prompt with tool descriptions
+        augmented_system = tool_prompt
+        if self._system_prompt:
+            augmented_system = f"{self._system_prompt}\n\n{tool_prompt}"
+
+        # Record user message in history
+        user_content = self._build_content_with_images(content, images)
+        self._messages.append({"role": "user", "content": user_content})
+
+        for _round in range(self._max_tool_rounds):
+            # Build messages with the augmented system prompt
+            msgs: list[dict[str, Any]] = []
+            msgs.append({"role": "system", "content": augmented_system})
+            msgs.extend(self._messages)
+
+            resp = self._driver.generate_messages_with_hooks(msgs, merged)
+            text = resp.get("text", "")
+            meta = resp.get("meta", {})
+            self._accumulate_usage(meta)
+
+            parsed = parse_simulated_response(text, self._tools)
+
+            if parsed["type"] == "final_answer":
+                answer = parsed["content"]
+                self._messages.append({"role": "assistant", "content": answer})
+                return answer
+
+            # Tool call
+            tool_name = parsed["name"]
+            tool_args = parsed["arguments"]
+
+            # Record assistant's tool call as an assistant message
+            self._messages.append({"role": "assistant", "content": text})
+
+            try:
+                result = self._tools.execute(tool_name, tool_args)
+                result_msg = format_tool_result(tool_name, result)
+            except Exception as exc:
+                result_msg = format_tool_result(tool_name, f"Error: {exc}")
+
+            # Record tool result as a user message (all drivers understand user/assistant)
+            self._messages.append({"role": "user", "content": result_msg})
+
+        raise RuntimeError(f"Simulated tool execution loop exceeded {self._max_tool_rounds} rounds")
+
     def _build_messages_raw(self) -> list[dict[str, Any]]:
         """Build messages array from system prompt + full history (including tool messages)."""
         msgs: list[dict[str, Any]] = []
@@ -484,6 +565,8 @@ class Conversation:
         context clean for subsequent turns.
         """
 
+        self._last_reasoning = None
+
         merged = {**self._options, **(options or {})}
 
         # Build the full prompt with schema instructions inline (handled by ask_for_json)
@@ -525,6 +608,7 @@ class Conversation:
 
         text = resp.get("text", "")
         meta = resp.get("meta", {})
+        self._last_reasoning = resp.get("reasoning_content")
 
         # Store original content (without schema boilerplate) for cleaner context
         # Include images in history so subsequent turns can reference them
@@ -563,6 +647,7 @@ class Conversation:
             "json_object": json_obj,
             "usage": usage,
             "output_format": output_format,
+            "reasoning": self._last_reasoning,
         }
 
         if output_format == "toon":

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/prompture/drivers/async_grok_driver.py

@@ -95,8 +95,17 @@ class AsyncGrokDriver(CostMixin, AsyncDriver):
             "model_name": model,
         }
 
-        text = resp["choices"][0]["message"]["content"]
-        return {"text": text, "meta": meta}
+        message = resp["choices"][0]["message"]
+        text = message.get("content") or ""
+        reasoning_content = message.get("reasoning_content")
+
+        if not text and reasoning_content:
+            text = reasoning_content
+
+        result: dict[str, Any] = {"text": text, "meta": meta}
+        if reasoning_content is not None:
+            result["reasoning_content"] = reasoning_content
+        return result
 
     # ------------------------------------------------------------------
     # Tool use
@@ -173,15 +182,20 @@ class AsyncGrokDriver(CostMixin, AsyncDriver):
                 args = json.loads(tc["function"]["arguments"])
             except (json.JSONDecodeError, TypeError):
                 args = {}
-            tool_calls_out.append({
-                "id": tc["id"],
-                "name": tc["function"]["name"],
-                "arguments": args,
-            })
-
-        return {
+            tool_calls_out.append(
+                {
+                    "id": tc["id"],
+                    "name": tc["function"]["name"],
+                    "arguments": args,
+                }
+            )
+
+        result: dict[str, Any] = {
             "text": text,
             "meta": meta,
             "tool_calls": tool_calls_out,
             "stop_reason": stop_reason,
         }
+        if choice["message"].get("reasoning_content") is not None:
+            result["reasoning_content"] = choice["message"]["reasoning_content"]
+        return result

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/prompture/drivers/async_groq_driver.py

@@ -88,8 +88,16 @@ class AsyncGroqDriver(CostMixin, AsyncDriver):
             "model_name": model,
         }
 
-        text = resp.choices[0].message.content
-        return {"text": text, "meta": meta}
+        text = resp.choices[0].message.content or ""
+        reasoning_content = getattr(resp.choices[0].message, "reasoning_content", None)
+
+        if not text and reasoning_content:
+            text = reasoning_content
+
+        result: dict[str, Any] = {"text": text, "meta": meta}
+        if reasoning_content is not None:
+            result["reasoning_content"] = reasoning_content
+        return result
 
     # ------------------------------------------------------------------
     # Tool use
@@ -152,15 +160,21 @@ class AsyncGroqDriver(CostMixin, AsyncDriver):
                     args = json.loads(tc.function.arguments)
                 except (json.JSONDecodeError, TypeError):
                     args = {}
-                tool_calls_out.append({
-                    "id": tc.id,
-                    "name": tc.function.name,
-                    "arguments": args,
-                })
-
-        return {
+                tool_calls_out.append(
+                    {
+                        "id": tc.id,
+                        "name": tc.function.name,
+                        "arguments": args,
+                    }
+                )
+
+        result: dict[str, Any] = {
             "text": text,
             "meta": meta,
             "tool_calls": tool_calls_out,
             "stop_reason": stop_reason,
         }
+        reasoning_content = getattr(choice.message, "reasoning_content", None)
+        if reasoning_content is not None:
+            result["reasoning_content"] = reasoning_content
+        return result

{prompture-0.0.47.dev1 → prompture-0.0.47.dev3}/prompture/drivers/async_lmstudio_driver.py

@@ -98,7 +98,12 @@ class AsyncLMStudioDriver(AsyncDriver):
         if "choices" not in response_data or not response_data["choices"]:
             raise ValueError(f"Unexpected response format: {response_data}")
 
-        text = response_data["choices"][0]["message"]["content"]
+        message = response_data["choices"][0]["message"]
+        text = message.get("content") or ""
+        reasoning_content = message.get("reasoning_content")
+
+        if not text and reasoning_content:
+            text = reasoning_content
 
         usage = response_data.get("usage", {})
         prompt_tokens = usage.get("prompt_tokens", 0)
@@ -114,7 +119,10 @@ class AsyncLMStudioDriver(AsyncDriver):
             "model_name": merged_options.get("model", self.model),
         }
 
-        return {"text": text, "meta": meta}
+        result: dict[str, Any] = {"text": text, "meta": meta}
+        if reasoning_content is not None:
+            result["reasoning_content"] = reasoning_content
+        return result
 
     # -- Model management (LM Studio 0.4.0+) ----------------------------------