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

prompture/driver.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import logging
 import time
+from collections.abc import Iterator
 from typing import Any
 
 from .callbacks import DriverCallbacks
@@ -32,13 +33,15 @@ class Driver:
     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
 
     def generate(self, prompt: str, options: dict[str, Any]) -> dict[str, Any]:
         raise NotImplementedError
 
-    def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
+    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.
 
         Each message is a dict with ``"role"`` (``"system"``, ``"user"``, or
@@ -52,6 +55,46 @@ class Driver:
         prompt = self._flatten_messages(messages)
         return self.generate(prompt, options)
 
+    # ------------------------------------------------------------------
+    # 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 calls.
+
+        Returns a dict with keys: ``text``, ``meta``, ``tool_calls``, ``stop_reason``.
+        ``tool_calls`` is a list of ``{"id": str, "name": str, "arguments": dict}``.
+
+        Drivers that support tool use should override this method and set
+        ``supports_tool_use = True``.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not support tool use")
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    def generate_messages_stream(
+        self,
+        messages: list[dict[str, Any]],
+        options: dict[str, Any],
+    ) -> Iterator[dict[str, Any]]:
+        """Yield response chunks incrementally.
+
+        Each chunk is a dict:
+        - ``{"type": "delta", "text": str}`` for content fragments
+        - ``{"type": "done", "text": str, "meta": dict}`` for the final summary
+
+        Drivers that support streaming should override this method and set
+        ``supports_streaming = True``.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not support streaming")
+
     # ------------------------------------------------------------------
     # Hook-aware wrappers
     # ------------------------------------------------------------------
@@ -84,7 +127,7 @@ class Driver:
         )
         return resp
 
-    def generate_messages_with_hooks(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
+    def generate_messages_with_hooks(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__)
         self._fire_callback(
@@ -129,7 +172,7 @@ class Driver:
             logger.exception("Callback %s raised an exception", event)
 
     @staticmethod
-    def _flatten_messages(messages: list[dict[str, str]]) -> str:
+    def _flatten_messages(messages: list[dict[str, Any]]) -> str:
         """Join messages into a single prompt string with role prefixes."""
         parts: list[str] = []
         for msg in messages:

prompture/drivers/claude_driver.py

@@ -4,6 +4,7 @@ Use with API key in CLAUDE_API_KEY env var or provide directly.
 
 import json
 import os
+from collections.abc import Iterator
 from typing import Any
 
 try:
@@ -18,6 +19,8 @@ from ..driver import Driver
 class ClaudeDriver(CostMixin, Driver):
     supports_json_mode = True
     supports_json_schema = True
+    supports_tool_use = True
+    supports_streaming = True
 
     # Claude pricing per 1000 tokens (prices should be kept current with Anthropic's pricing)
     MODEL_PRICING = {
@@ -58,10 +61,10 @@ class ClaudeDriver(CostMixin, Driver):
         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]:
+    def generate_messages(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
         return self._do_generate(messages, options)
 
-    def _do_generate(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
+    def _do_generate(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
         if anthropic is None:
             raise RuntimeError("anthropic package not installed")
 
@@ -134,3 +137,165 @@ class ClaudeDriver(CostMixin, Driver):
         }
 
         return {"text": text, "meta": meta}
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _extract_system_and_messages(
+        self, messages: list[dict[str, Any]]
+    ) -> tuple[str | None, list[dict[str, Any]]]:
+        """Separate system message from conversation messages for Anthropic API."""
+        system_content = None
+        api_messages: list[dict[str, Any]] = []
+        for msg in messages:
+            if msg.get("role") == "system":
+                system_content = msg.get("content", "")
+            else:
+                api_messages.append(msg)
+        return system_content, api_messages
+
+    # ------------------------------------------------------------------
+    # 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 calls (Anthropic)."""
+        if anthropic is None:
+            raise RuntimeError("anthropic package not installed")
+
+        opts = {**{"temperature": 0.0, "max_tokens": 512}, **options}
+        model = options.get("model", self.model)
+        client = anthropic.Anthropic(api_key=self.api_key)
+
+        system_content, api_messages = self._extract_system_and_messages(messages)
+
+        # Convert tools from OpenAI format to Anthropic format if needed
+        anthropic_tools = []
+        for t in tools:
+            if "type" in t and t["type"] == "function":
+                # OpenAI format -> Anthropic format
+                fn = t["function"]
+                anthropic_tools.append({
+                    "name": fn["name"],
+                    "description": fn.get("description", ""),
+                    "input_schema": fn.get("parameters", {"type": "object", "properties": {}}),
+                })
+            elif "input_schema" in t:
+                # Already Anthropic format
+                anthropic_tools.append(t)
+            else:
+                anthropic_tools.append(t)
+
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": api_messages,
+            "temperature": opts["temperature"],
+            "max_tokens": opts["max_tokens"],
+            "tools": anthropic_tools,
+        }
+        if system_content:
+            kwargs["system"] = system_content
+
+        resp = client.messages.create(**kwargs)
+
+        prompt_tokens = resp.usage.input_tokens
+        completion_tokens = resp.usage.output_tokens
+        total_tokens = prompt_tokens + completion_tokens
+        total_cost = self._calculate_cost("claude", model, prompt_tokens, completion_tokens)
+
+        meta = {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": total_tokens,
+            "cost": round(total_cost, 6),
+            "raw_response": dict(resp),
+            "model_name": model,
+        }
+
+        text = ""
+        tool_calls_out: list[dict[str, Any]] = []
+        for block in resp.content:
+            if block.type == "text":
+                text += block.text
+            elif block.type == "tool_use":
+                tool_calls_out.append({
+                    "id": block.id,
+                    "name": block.name,
+                    "arguments": block.input,
+                })
+
+        return {
+            "text": text,
+            "meta": meta,
+            "tool_calls": tool_calls_out,
+            "stop_reason": resp.stop_reason,
+        }
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    def generate_messages_stream(
+        self,
+        messages: list[dict[str, Any]],
+        options: dict[str, Any],
+    ) -> Iterator[dict[str, Any]]:
+        """Yield response chunks via Anthropic streaming API."""
+        if anthropic is None:
+            raise RuntimeError("anthropic package not installed")
+
+        opts = {**{"temperature": 0.0, "max_tokens": 512}, **options}
+        model = options.get("model", self.model)
+        client = anthropic.Anthropic(api_key=self.api_key)
+
+        system_content, api_messages = self._extract_system_and_messages(messages)
+
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": api_messages,
+            "temperature": opts["temperature"],
+            "max_tokens": opts["max_tokens"],
+        }
+        if system_content:
+            kwargs["system"] = system_content
+
+        full_text = ""
+        prompt_tokens = 0
+        completion_tokens = 0
+
+        with client.messages.stream(**kwargs) as stream:
+            for event in stream:
+                if hasattr(event, "type"):
+                    if event.type == "content_block_delta" and hasattr(event, "delta"):
+                        delta_text = getattr(event.delta, "text", "")
+                        if delta_text:
+                            full_text += delta_text
+                            yield {"type": "delta", "text": delta_text}
+                    elif event.type == "message_delta" and hasattr(event, "usage"):
+                        completion_tokens = getattr(event.usage, "output_tokens", 0)
+                    elif event.type == "message_start" and hasattr(event, "message"):
+                        usage = getattr(event.message, "usage", None)
+                        if usage:
+                            prompt_tokens = getattr(usage, "input_tokens", 0)
+
+        total_tokens = prompt_tokens + completion_tokens
+        total_cost = self._calculate_cost("claude", model, prompt_tokens, completion_tokens)
+
+        yield {
+            "type": "done",
+            "text": full_text,
+            "meta": {
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+                "total_tokens": total_tokens,
+                "cost": round(total_cost, 6),
+                "raw_response": {},
+                "model_name": model,
+            },
+        }

prompture/drivers/ollama_driver.py

@@ -1,6 +1,7 @@
 import json
 import logging
 import os
+from collections.abc import Iterator
 from typing import Any, Optional
 
 import requests
@@ -12,6 +13,7 @@ logger = logging.getLogger(__name__)
 
 class OllamaDriver(Driver):
     supports_json_mode = True
+    supports_streaming = True
 
     # Ollama is free – costs are always zero.
     MODEL_PRICING = {"default": {"prompt": 0.0, "completion": 0.0}}
@@ -121,7 +123,72 @@ class OllamaDriver(Driver):
         # Ollama returns text in "response"
         return {"text": response_data.get("response", ""), "meta": meta}
 
-    def generate_messages(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    def generate_messages_stream(
+        self,
+        messages: list[dict[str, Any]],
+        options: dict[str, Any],
+    ) -> Iterator[dict[str, Any]]:
+        """Yield response chunks via Ollama streaming API."""
+        merged_options = self.options.copy()
+        if options:
+            merged_options.update(options)
+
+        chat_endpoint = self.endpoint.replace("/api/generate", "/api/chat")
+
+        payload: dict[str, Any] = {
+            "model": merged_options.get("model", self.model),
+            "messages": messages,
+            "stream": True,
+        }
+
+        if merged_options.get("json_mode"):
+            payload["format"] = "json"
+        if "temperature" in merged_options:
+            payload["temperature"] = merged_options["temperature"]
+        if "top_p" in merged_options:
+            payload["top_p"] = merged_options["top_p"]
+        if "top_k" in merged_options:
+            payload["top_k"] = merged_options["top_k"]
+
+        full_text = ""
+        prompt_tokens = 0
+        completion_tokens = 0
+
+        r = requests.post(chat_endpoint, json=payload, timeout=120, stream=True)
+        r.raise_for_status()
+
+        for line in r.iter_lines():
+            if not line:
+                continue
+            chunk = json.loads(line)
+            if chunk.get("done"):
+                prompt_tokens = chunk.get("prompt_eval_count", 0)
+                completion_tokens = chunk.get("eval_count", 0)
+            else:
+                content = chunk.get("message", {}).get("content", "")
+                if content:
+                    full_text += content
+                    yield {"type": "delta", "text": content}
+
+        total_tokens = prompt_tokens + completion_tokens
+        yield {
+            "type": "done",
+            "text": full_text,
+            "meta": {
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+                "total_tokens": total_tokens,
+                "cost": 0.0,
+                "raw_response": {},
+                "model_name": merged_options.get("model", self.model),
+            },
+        }
+
+    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."""
         merged_options = self.options.copy()
         if options:

prompture/drivers/openai_driver.py

@@ -2,7 +2,9 @@
 Requires the `openai` package. Uses OPENAI_API_KEY env var.
 """
 
+import json
 import os
+from collections.abc import Iterator
 from typing import Any
 
 try:
@@ -17,6 +19,8 @@ from ..driver import Driver
 class OpenAIDriver(CostMixin, Driver):
     supports_json_mode = True
     supports_json_schema = True
+    supports_tool_use = True
+    supports_streaming = 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,10 +78,10 @@ class OpenAIDriver(CostMixin, Driver):
         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]:
+    def generate_messages(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
         return self._do_generate(messages, options)
 
-    def _do_generate(self, messages: list[dict[str, str]], options: dict[str, Any]) -> dict[str, Any]:
+    def _do_generate(self, messages: list[dict[str, Any]], options: dict[str, Any]) -> dict[str, Any]:
         if self.client is None:
             raise RuntimeError("openai package (>=1.0.0) is not installed")
 
@@ -142,3 +146,141 @@ class OpenAIDriver(CostMixin, Driver):
 
         text = resp.choices[0].message.content
         return {"text": text, "meta": meta}
+
+    # ------------------------------------------------------------------
+    # 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 calls."""
+        if self.client is None:
+            raise RuntimeError("openai package (>=1.0.0) is 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)
+
+        opts = {"temperature": 1.0, "max_tokens": 512, **options}
+
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "tools": tools,
+        }
+        kwargs[tokens_param] = opts.get("max_tokens", 512)
+
+        if supports_temperature and "temperature" in opts:
+            kwargs["temperature"] = opts["temperature"]
+
+        resp = self.client.chat.completions.create(**kwargs)
+
+        usage = getattr(resp, "usage", None)
+        prompt_tokens = getattr(usage, "prompt_tokens", 0)
+        completion_tokens = getattr(usage, "completion_tokens", 0)
+        total_tokens = getattr(usage, "total_tokens", 0)
+        total_cost = self._calculate_cost("openai", model, prompt_tokens, completion_tokens)
+
+        meta = {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": total_tokens,
+            "cost": round(total_cost, 6),
+            "raw_response": resp.model_dump(),
+            "model_name": model,
+        }
+
+        choice = resp.choices[0]
+        text = choice.message.content or ""
+        stop_reason = choice.finish_reason
+
+        tool_calls_out: list[dict[str, Any]] = []
+        if choice.message.tool_calls:
+            for tc in choice.message.tool_calls:
+                try:
+                    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 {
+            "text": text,
+            "meta": meta,
+            "tool_calls": tool_calls_out,
+            "stop_reason": stop_reason,
+        }
+
+    # ------------------------------------------------------------------
+    # Streaming
+    # ------------------------------------------------------------------
+
+    def generate_messages_stream(
+        self,
+        messages: list[dict[str, Any]],
+        options: dict[str, Any],
+    ) -> Iterator[dict[str, Any]]:
+        """Yield response chunks via OpenAI streaming API."""
+        if self.client is None:
+            raise RuntimeError("openai package (>=1.0.0) is 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)
+
+        opts = {"temperature": 1.0, "max_tokens": 512, **options}
+
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "stream": True,
+            "stream_options": {"include_usage": True},
+        }
+        kwargs[tokens_param] = opts.get("max_tokens", 512)
+
+        if supports_temperature and "temperature" in opts:
+            kwargs["temperature"] = opts["temperature"]
+
+        stream = self.client.chat.completions.create(**kwargs)
+
+        full_text = ""
+        prompt_tokens = 0
+        completion_tokens = 0
+
+        for chunk in stream:
+            # Usage comes in the final chunk
+            if getattr(chunk, "usage", None):
+                prompt_tokens = chunk.usage.prompt_tokens or 0
+                completion_tokens = chunk.usage.completion_tokens or 0
+
+            if chunk.choices:
+                delta = chunk.choices[0].delta
+                content = getattr(delta, "content", None) or ""
+                if content:
+                    full_text += content
+                    yield {"type": "delta", "text": content}
+
+        total_tokens = prompt_tokens + completion_tokens
+        total_cost = self._calculate_cost("openai", model, prompt_tokens, completion_tokens)
+
+        yield {
+            "type": "done",
+            "text": full_text,
+            "meta": {
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+                "total_tokens": total_tokens,
+                "cost": round(total_cost, 6),
+                "raw_response": {},
+                "model_name": model,
+            },
+        }

prompture/scaffold/__init__.py

@@ -0,0 +1 @@
+"""Project scaffolding for Prompture-based FastAPI apps."""

prompture/scaffold/generator.py

@@ -0,0 +1,84 @@
+"""Project scaffolding generator.
+
+Renders Jinja2 templates into a standalone FastAPI project directory
+that users can customize and deploy.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    from jinja2 import Environment, FileSystemLoader
+except ImportError:
+    Environment = None  # type: ignore[assignment,misc]
+    FileSystemLoader = None  # type: ignore[assignment,misc]
+
+_TEMPLATES_DIR = Path(__file__).parent / "templates"
+
+# Map from template file -> output path (relative to project root).
+_FILE_MAP = {
+    "main.py.j2": "app/main.py",
+    "models.py.j2": "app/models.py",
+    "config.py.j2": "app/config.py",
+    "requirements.txt.j2": "requirements.txt",
+    "env.example.j2": ".env.example",
+    "README.md.j2": "README.md",
+}
+
+_DOCKER_FILES = {
+    "Dockerfile.j2": "Dockerfile",
+}
+
+
+def scaffold_project(
+    output_dir: str,
+    project_name: str = "my_app",
+    model_name: str = "openai/gpt-4o-mini",
+    include_docker: bool = True,
+) -> Path:
+    """Render all templates and write the project to *output_dir*.
+
+    Parameters:
+        output_dir: Destination directory (created if needed).
+        project_name: Human-friendly project name used in templates.
+        model_name: Default model string baked into config.
+        include_docker: Whether to include Dockerfile.
+
+    Returns:
+        The :class:`Path` to the generated project root.
+    """
+    if Environment is None:
+        raise ImportError("jinja2 is required for scaffolding: pip install prompture[scaffold]")
+
+    env = Environment(
+        loader=FileSystemLoader(str(_TEMPLATES_DIR)),
+        keep_trailing_newline=True,
+    )
+
+    context = {
+        "project_name": project_name,
+        "model_name": model_name,
+        "include_docker": include_docker,
+    }
+
+    out = Path(output_dir)
+
+    file_map = dict(_FILE_MAP)
+    if include_docker:
+        file_map.update(_DOCKER_FILES)
+
+    for template_name, rel_path in file_map.items():
+        template = env.get_template(template_name)
+        rendered = template.render(**context)
+
+        dest = out / rel_path
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(rendered, encoding="utf-8")
+
+    # Create empty __init__.py for the app package
+    init_path = out / "app" / "__init__.py"
+    if not init_path.exists():
+        init_path.write_text("", encoding="utf-8")
+
+    return out

prompture/scaffold/templates/Dockerfile.j2

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

prompture/scaffold/templates/README.md.j2

@@ -0,0 +1,41 @@
+# {{ project_name }}
+
+A FastAPI server powered by [Prompture](https://github.com/jhd3197/prompture) for structured LLM output.
+
+## Quick start
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Copy and edit environment config
+cp .env.example .env
+
+# Run the server
+uvicorn app.main:app --reload
+```
+
+## API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/chat` | Send a message, get a response |
+| POST | `/v1/extract` | Extract structured JSON with schema |
+| GET | `/v1/conversations/{id}` | Get conversation history |
+| DELETE | `/v1/conversations/{id}` | Delete a conversation |
+
+## Example
+
+```bash
+curl -X POST http://localhost:8000/v1/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello!"}'
+```
+{% if include_docker %}
+## Docker
+
+```bash
+docker build -t {{ project_name }} .
+docker run -p 8000:8000 --env-file .env {{ project_name }}
+```
+{% endif %}