prompture 0.0.34.dev2__py3-none-any.whl → 0.0.35.dev1__py3-none-any.whl

prompture/__init__.py

@@ -74,6 +74,7 @@ from .runner import run_suite_from_spec
 from .session import UsageSession
 from .settings import settings as _settings
 from .tools import clean_json_text, clean_toon_text
+from .tools_schema import ToolDefinition, ToolRegistry, tool_from_function
 from .validator import validate_against_schema
 
 # Load environment variables from .env file
@@ -128,6 +129,8 @@ __all__ = [
     "RedisCacheBackend",
     "ResponseCache",
     "SQLiteCacheBackend",
+    "ToolDefinition",
+    "ToolRegistry",
     "UsageSession",
     "add_field_definition",
     "add_field_definitions",
@@ -170,6 +173,7 @@ __all__ = [
     "reset_registry",
     "run_suite_from_spec",
     "stepwise_extract_with_model",
+    "tool_from_function",
     "unregister_async_driver",
     "unregister_driver",
     "validate_against_schema",

prompture/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.34.dev2'
-__version_tuple__ = version_tuple = (0, 0, 34, 'dev2')
+__version__ = version = '0.0.35.dev1'
+__version_tuple__ = version_tuple = (0, 0, 35, 'dev1')
 
 __commit_id__ = commit_id = None

prompture/async_conversation.py

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 import json
 import logging
+from collections.abc import AsyncIterator
 from datetime import date, datetime
 from decimal import Decimal
-from typing import Any, Literal, Union
+from typing import Any, Callable, Literal, Union
 
 from pydantic import BaseModel
 
@@ -19,6 +20,7 @@ from .tools import (
     convert_value,
     get_field_default,
 )
+from .tools_schema import ToolRegistry
 
 logger = logging.getLogger("prompture.async_conversation")
 
@@ -43,6 +45,8 @@ class AsyncConversation:
         system_prompt: str | None = None,
         options: dict[str, Any] | None = None,
         callbacks: DriverCallbacks | None = None,
+        tools: ToolRegistry | None = None,
+        max_tool_rounds: int = 10,
     ) -> None:
         if model_name is None and driver is None:
             raise ValueError("Either model_name or driver must be provided")
@@ -58,7 +62,7 @@ class AsyncConversation:
         self._model_name = model_name or ""
         self._system_prompt = system_prompt
         self._options = dict(options) if options else {}
-        self._messages: list[dict[str, str]] = []
+        self._messages: list[dict[str, Any]] = []
         self._usage = {
             "prompt_tokens": 0,
             "completion_tokens": 0,
@@ -66,13 +70,15 @@ class AsyncConversation:
             "cost": 0.0,
             "turns": 0,
         }
+        self._tools = tools or ToolRegistry()
+        self._max_tool_rounds = max_tool_rounds
 
     # ------------------------------------------------------------------
     # Public helpers
     # ------------------------------------------------------------------
 
     @property
-    def messages(self) -> list[dict[str, str]]:
+    def messages(self) -> list[dict[str, Any]]:
         """Read-only view of the conversation history."""
         return list(self._messages)
 
@@ -91,6 +97,16 @@ class AsyncConversation:
             raise ValueError("role must be 'user' or 'assistant'")
         self._messages.append({"role": role, "content": content})
 
+    def register_tool(
+        self,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        """Register a Python function as a tool the LLM can call."""
+        self._tools.register(fn, name=name, description=description)
+
     def usage_summary(self) -> str:
         """Human-readable summary of accumulated usage."""
         u = self._usage
@@ -100,9 +116,9 @@ class AsyncConversation:
     # Core methods
     # ------------------------------------------------------------------
 
-    def _build_messages(self, user_content: str) -> list[dict[str, str]]:
+    def _build_messages(self, user_content: str) -> list[dict[str, Any]]:
         """Build the full messages array for an API call."""
-        msgs: list[dict[str, str]] = []
+        msgs: list[dict[str, Any]] = []
         if self._system_prompt:
             msgs.append({"role": "system", "content": self._system_prompt})
         msgs.extend(self._messages)
@@ -121,7 +137,14 @@ class AsyncConversation:
         content: str,
         options: dict[str, Any] | None = None,
     ) -> str:
-        """Send a message and get a raw text response (async)."""
+        """Send a message and get a raw text response (async).
+
+        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)
+
         merged = {**self._options, **(options or {})}
         messages = self._build_messages(content)
         resp = await self._driver.generate_messages_with_hooks(messages, merged)
@@ -135,6 +158,106 @@ class AsyncConversation:
 
         return text
 
+    async def _ask_with_tools(
+        self,
+        content: str,
+        options: dict[str, Any] | None = None,
+    ) -> str:
+        """Async tool-use loop: send -> check tool_calls -> execute -> re-send."""
+        merged = {**self._options, **(options or {})}
+        tool_defs = self._tools.to_openai_format()
+
+        self._messages.append({"role": "user", "content": content})
+        msgs = self._build_messages_raw()
+
+        for _round in range(self._max_tool_rounds):
+            resp = await self._driver.generate_messages_with_tools(msgs, tool_defs, merged)
+
+            meta = resp.get("meta", {})
+            self._accumulate_usage(meta)
+
+            tool_calls = resp.get("tool_calls", [])
+            text = resp.get("text", "")
+
+            if not tool_calls:
+                self._messages.append({"role": "assistant", "content": text})
+                return text
+
+            assistant_msg: dict[str, Any] = {"role": "assistant", "content": text}
+            assistant_msg["tool_calls"] = [
+                {
+                    "id": tc["id"],
+                    "type": "function",
+                    "function": {"name": tc["name"], "arguments": json.dumps(tc["arguments"])},
+                }
+                for tc in tool_calls
+            ]
+            self._messages.append(assistant_msg)
+            msgs.append(assistant_msg)
+
+            for tc in tool_calls:
+                try:
+                    result = self._tools.execute(tc["name"], tc["arguments"])
+                    result_str = json.dumps(result) if not isinstance(result, str) else result
+                except Exception as exc:
+                    result_str = f"Error: {exc}"
+
+                tool_result_msg: dict[str, Any] = {
+                    "role": "tool",
+                    "tool_call_id": tc["id"],
+                    "content": result_str,
+                }
+                self._messages.append(tool_result_msg)
+                msgs.append(tool_result_msg)
+
+        raise RuntimeError(f"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]] = []
+        if self._system_prompt:
+            msgs.append({"role": "system", "content": self._system_prompt})
+        msgs.extend(self._messages)
+        return msgs
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    async def ask_stream(
+        self,
+        content: str,
+        options: dict[str, Any] | None = None,
+    ) -> AsyncIterator[str]:
+        """Send a message and yield text chunks as they arrive (async).
+
+        Falls back to non-streaming :meth:`ask` if the driver doesn't
+        support streaming.
+        """
+        if not getattr(self._driver, "supports_streaming", False):
+            yield await self.ask(content, options)
+            return
+
+        merged = {**self._options, **(options or {})}
+        messages = self._build_messages(content)
+
+        self._messages.append({"role": "user", "content": content})
+
+        full_text = ""
+        async for chunk in self._driver.generate_messages_stream(messages, merged):
+            if chunk["type"] == "delta":
+                full_text += chunk["text"]
+                self._driver._fire_callback(
+                    "on_stream_delta",
+                    {"text": chunk["text"], "driver": getattr(self._driver, "model", self._driver.__class__.__name__)},
+                )
+                yield chunk["text"]
+            elif chunk["type"] == "done":
+                meta = chunk.get("meta", {})
+                self._accumulate_usage(meta)
+
+        self._messages.append({"role": "assistant", "content": full_text})
+
     async def ask_for_json(
         self,
         content: str,

prompture/async_driver.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import logging
 import time
+from collections.abc import AsyncIterator
 from typing import Any
 
 from .callbacks import DriverCallbacks
@@ -32,13 +33,15 @@ class AsyncDriver:
     supports_json_mode: bool = False
     supports_json_schema: bool = False
     supports_messages: bool = False
+    supports_tool_use: bool = False
+    supports_streaming: bool = False
 
     callbacks: DriverCallbacks | None = None
 
     async def generate(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
         raise NotImplementedError
 
-    async def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
+    async def generate_messages(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
         """Generate a response from a list of conversation messages (async).
 
         Default implementation flattens the messages into a single prompt
@@ -49,6 +52,41 @@ class AsyncDriver:
         prompt = Driver._flatten_messages(messages)
         return await self.generate(prompt, options)
 
+    # ------------------------------------------------------------------
+    # Tool use
+    # ------------------------------------------------------------------
+
+    async 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 calls (async).
+
+        Returns a dict with keys: ``text``, ``meta``, ``tool_calls``, ``stop_reason``.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not support tool use")
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    async def generate_messages_stream(
+        self,
+        messages: list[dict[str, Any]],
+        options: dict[str, Any],
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Yield response chunks incrementally (async).
+
+        Each chunk is a dict:
+        - ``{"type": "delta", "text": str}``
+        - ``{"type": "done", "text": str, "meta": dict}``
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not support streaming")
+        # yield is needed to make this an async generator
+        yield  # pragma: no cover
+
     # ------------------------------------------------------------------
     # Hook-aware wrappers
     # ------------------------------------------------------------------
@@ -82,7 +120,7 @@ class AsyncDriver:
         return resp
 
     async def generate_messages_with_hooks(
-        self, messages: list[dict[str, str]], options: dict[str, Any]
+        self, messages: list[dict[str, Any]], options: dict[str, Any]
     ) -> dict[str, Any]:
         """Wrap :meth:`generate_messages` with callbacks."""
         driver_name = getattr(self, "model", self.__class__.__name__)

prompture/callbacks.py

@@ -27,6 +27,7 @@ from typing import Any, Callable
 OnRequestCallback = Callable[[dict[str, Any]], None]
 OnResponseCallback = Callable[[dict[str, Any]], None]
 OnErrorCallback = Callable[[dict[str, Any]], None]
+OnStreamDeltaCallback = Callable[[dict[str, Any]], None]
 
 
 @dataclass
@@ -43,8 +44,12 @@ class DriverCallbacks:
 
     ``on_error``
         ``{error, prompt, messages, options, driver}``
+
+    ``on_stream_delta``
+        ``{text, driver}``
     """
 
     on_request: OnRequestCallback | None = field(default=None)
     on_response: OnResponseCallback | None = field(default=None)
     on_error: OnErrorCallback | None = field(default=None)
+    on_stream_delta: OnStreamDeltaCallback | None = field(default=None)

prompture/cli.py

@@ -8,7 +8,7 @@ from .runner import run_suite_from_spec
 
 @click.group()
 def cli():
-    """Simple CLI to run JSON specs"""
+    """Prompture CLI -- structured LLM output toolkit."""
     pass
 
 
@@ -25,3 +25,58 @@ def run(specfile, outfile):
     with open(outfile, "w", encoding="utf-8") as fh:
         json.dump(report, fh, indent=2, ensure_ascii=False)
     click.echo(f"Report saved to {outfile}")
+
+
+@cli.command()
+@click.option("--model", default="openai/gpt-4o-mini", help="Model string (provider/model).")
+@click.option("--system-prompt", default=None, help="System prompt for conversations.")
+@click.option("--host", default="0.0.0.0", help="Bind host.")
+@click.option("--port", default=8000, type=int, help="Bind port.")
+@click.option("--cors-origins", default=None, help="Comma-separated CORS origins (use * for all).")
+def serve(model, system_prompt, host, port, cors_origins):
+    """Start an API server wrapping AsyncConversation.
+
+    Requires the 'serve' extra: pip install prompture[serve]
+    """
+    try:
+        import uvicorn
+    except ImportError:
+        click.echo("Error: uvicorn not installed. Run: pip install prompture[serve]", err=True)
+        raise SystemExit(1) from None
+
+    from .server import create_app
+
+    origins = [o.strip() for o in cors_origins.split(",")] if cors_origins else None
+    app = create_app(
+        model_name=model,
+        system_prompt=system_prompt,
+        cors_origins=origins,
+    )
+
+    click.echo(f"Starting Prompture server on {host}:{port} with model {model}")
+    uvicorn.run(app, host=host, port=port)
+
+
+@cli.command()
+@click.argument("output_dir", type=click.Path())
+@click.option("--name", default="my_app", help="Project name.")
+@click.option("--model", default="openai/gpt-4o-mini", help="Default model string.")
+@click.option("--docker/--no-docker", default=True, help="Include Dockerfile.")
+def scaffold(output_dir, name, model, docker):
+    """Generate a standalone FastAPI project using Prompture.
+
+    Requires the 'scaffold' extra: pip install prompture[scaffold]
+    """
+    try:
+        from .scaffold.generator import scaffold_project
+    except ImportError:
+        click.echo("Error: jinja2 not installed. Run: pip install prompture[scaffold]", err=True)
+        raise SystemExit(1) from None
+
+    scaffold_project(
+        output_dir=output_dir,
+        project_name=name,
+        model_name=model,
+        include_docker=docker,
+    )
+    click.echo(f"Project scaffolded at {output_dir}")

prompture/conversation.py

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 import json
 import logging
+from collections.abc import Iterator
 from datetime import date, datetime
 from decimal import Decimal
-from typing import Any, Literal, Union
+from typing import Any, Callable, Literal, Union
 
 from pydantic import BaseModel
 
@@ -19,6 +20,7 @@ from .tools import (
     convert_value,
     get_field_default,
 )
+from .tools_schema import ToolRegistry
 
 logger = logging.getLogger("prompture.conversation")
 
@@ -44,6 +46,8 @@ class Conversation:
         system_prompt: str | None = None,
         options: dict[str, Any] | None = None,
         callbacks: DriverCallbacks | None = None,
+        tools: ToolRegistry | None = None,
+        max_tool_rounds: int = 10,
     ) -> None:
         if model_name is None and driver is None:
             raise ValueError("Either model_name or driver must be provided")
@@ -59,7 +63,7 @@ class Conversation:
         self._model_name = model_name or ""
         self._system_prompt = system_prompt
         self._options = dict(options) if options else {}
-        self._messages: list[dict[str, str]] = []
+        self._messages: list[dict[str, Any]] = []
         self._usage = {
             "prompt_tokens": 0,
             "completion_tokens": 0,
@@ -67,13 +71,15 @@ class Conversation:
             "cost": 0.0,
             "turns": 0,
         }
+        self._tools = tools or ToolRegistry()
+        self._max_tool_rounds = max_tool_rounds
 
     # ------------------------------------------------------------------
     # Public helpers
     # ------------------------------------------------------------------
 
     @property
-    def messages(self) -> list[dict[str, str]]:
+    def messages(self) -> list[dict[str, Any]]:
         """Read-only view of the conversation history."""
         return list(self._messages)
 
@@ -92,6 +98,16 @@ class Conversation:
             raise ValueError("role must be 'user' or 'assistant'")
         self._messages.append({"role": role, "content": content})
 
+    def register_tool(
+        self,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        """Register a Python function as a tool the LLM can call."""
+        self._tools.register(fn, name=name, description=description)
+
     def usage_summary(self) -> str:
         """Human-readable summary of accumulated usage."""
         u = self._usage
@@ -101,9 +117,9 @@ class Conversation:
     # Core methods
     # ------------------------------------------------------------------
 
-    def _build_messages(self, user_content: str) -> list[dict[str, str]]:
+    def _build_messages(self, user_content: str) -> list[dict[str, Any]]:
         """Build the full messages array for an API call."""
-        msgs: list[dict[str, str]] = []
+        msgs: list[dict[str, Any]] = []
         if self._system_prompt:
             msgs.append({"role": "system", "content": self._system_prompt})
         msgs.extend(self._messages)
@@ -125,7 +141,12 @@ class Conversation:
         """Send a message and get a raw text response.
 
         Appends the user message and assistant response to history.
+        If tools are registered and the driver supports tool use,
+        dispatches to the tool execution loop.
         """
+        if self._tools and getattr(self._driver, "supports_tool_use", False):
+            return self._ask_with_tools(content, options)
+
         merged = {**self._options, **(options or {})}
         messages = self._build_messages(content)
         resp = self._driver.generate_messages_with_hooks(messages, merged)
@@ -140,6 +161,112 @@ class Conversation:
 
         return text
 
+    def _ask_with_tools(
+        self,
+        content: str,
+        options: dict[str, Any] | None = None,
+    ) -> str:
+        """Execute the tool-use loop: send -> check tool_calls -> execute -> re-send."""
+        merged = {**self._options, **(options or {})}
+        tool_defs = self._tools.to_openai_format()
+
+        # Build messages including user content
+        self._messages.append({"role": "user", "content": content})
+        msgs = self._build_messages_raw()
+
+        for _round in range(self._max_tool_rounds):
+            resp = self._driver.generate_messages_with_tools(msgs, tool_defs, merged)
+
+            meta = resp.get("meta", {})
+            self._accumulate_usage(meta)
+
+            tool_calls = resp.get("tool_calls", [])
+            text = resp.get("text", "")
+
+            if not tool_calls:
+                # No tool calls -> final response
+                self._messages.append({"role": "assistant", "content": text})
+                return text
+
+            # Record assistant message with tool_calls
+            assistant_msg: dict[str, Any] = {"role": "assistant", "content": text}
+            assistant_msg["tool_calls"] = [
+                {
+                    "id": tc["id"],
+                    "type": "function",
+                    "function": {"name": tc["name"], "arguments": json.dumps(tc["arguments"])},
+                }
+                for tc in tool_calls
+            ]
+            self._messages.append(assistant_msg)
+            msgs.append(assistant_msg)
+
+            # Execute each tool call and append results
+            for tc in tool_calls:
+                try:
+                    result = self._tools.execute(tc["name"], tc["arguments"])
+                    result_str = json.dumps(result) if not isinstance(result, str) else result
+                except Exception as exc:
+                    result_str = f"Error: {exc}"
+
+                tool_result_msg: dict[str, Any] = {
+                    "role": "tool",
+                    "tool_call_id": tc["id"],
+                    "content": result_str,
+                }
+                self._messages.append(tool_result_msg)
+                msgs.append(tool_result_msg)
+
+        raise RuntimeError(f"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]] = []
+        if self._system_prompt:
+            msgs.append({"role": "system", "content": self._system_prompt})
+        msgs.extend(self._messages)
+        return msgs
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    def ask_stream(
+        self,
+        content: str,
+        options: dict[str, Any] | None = None,
+    ) -> Iterator[str]:
+        """Send a message and yield text chunks as they arrive.
+
+        Falls back to non-streaming :meth:`ask` if the driver doesn't
+        support streaming. After iteration completes, the full response
+        is recorded in history.
+        """
+        if not getattr(self._driver, "supports_streaming", False):
+            yield self.ask(content, options)
+            return
+
+        merged = {**self._options, **(options or {})}
+        messages = self._build_messages(content)
+
+        self._messages.append({"role": "user", "content": content})
+
+        full_text = ""
+        for chunk in self._driver.generate_messages_stream(messages, merged):
+            if chunk["type"] == "delta":
+                full_text += chunk["text"]
+                # Fire stream delta callback
+                self._driver._fire_callback(
+                    "on_stream_delta",
+                    {"text": chunk["text"], "driver": getattr(self._driver, "model", self._driver.__class__.__name__)},
+                )
+                yield chunk["text"]
+            elif chunk["type"] == "done":
+                meta = chunk.get("meta", {})
+                self._accumulate_usage(meta)
+
+        self._messages.append({"role": "assistant", "content": full_text})
+
     def ask_for_json(
         self,
         content: str,