prompture 0.0.29.dev8__py3-none-any.whl → 0.0.38.dev2__py3-none-any.whl

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 %}

prompture/scaffold/templates/config.py.j2

@@ -0,0 +1,21 @@
+"""Configuration for {{ project_name }}."""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    model_name: str = "{{ model_name }}"
+    system_prompt: str = "You are a helpful assistant."
+    cors_origins: list[str] = ["*"]
+
+    # Provider API keys (loaded from environment / .env)
+    openai_api_key: str = ""
+    claude_api_key: str = ""
+    google_api_key: str = ""
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+
+settings = Settings()

prompture/scaffold/templates/env.example.j2

@@ -0,0 +1,8 @@
+# {{ project_name }} environment configuration
+MODEL_NAME={{ model_name }}
+SYSTEM_PROMPT=You are a helpful assistant.
+
+# Provider API keys (uncomment and fill in as needed)
+# OPENAI_API_KEY=sk-...
+# CLAUDE_API_KEY=sk-ant-...
+# GOOGLE_API_KEY=...

prompture/scaffold/templates/main.py.j2

@@ -0,0 +1,86 @@
+"""{{ project_name }} -- FastAPI server powered by Prompture."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+
+from .config import settings
+from .models import (
+    ChatRequest,
+    ChatResponse,
+    ConversationHistory,
+    ExtractRequest,
+    ExtractResponse,
+)
+
+from prompture import AsyncConversation
+
+app = FastAPI(title="{{ project_name }}", version="0.1.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+_conversations: dict[str, AsyncConversation] = {}
+
+
+def _get_or_create_conversation(conv_id: str | None) -> tuple[str, AsyncConversation]:
+    if conv_id and conv_id in _conversations:
+        return conv_id, _conversations[conv_id]
+    new_id = conv_id or uuid.uuid4().hex[:12]
+    conv = AsyncConversation(
+        model_name=settings.model_name,
+        system_prompt=settings.system_prompt,
+    )
+    _conversations[new_id] = conv
+    return new_id, conv
+
+
+@app.post("/v1/chat", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+    conv_id, conv = _get_or_create_conversation(request.conversation_id)
+    text = await conv.ask(request.message, request.options)
+    return ChatResponse(message=text, conversation_id=conv_id, usage=conv.usage)
+
+
+@app.post("/v1/extract", response_model=ExtractResponse)
+async def extract(request: ExtractRequest):
+    conv_id, conv = _get_or_create_conversation(request.conversation_id)
+    result = await conv.ask_for_json(
+        content=request.text,
+        json_schema=request.schema_def,
+    )
+    return ExtractResponse(
+        json_object=result["json_object"],
+        conversation_id=conv_id,
+        usage=conv.usage,
+    )
+
+
+@app.get("/v1/conversations/{conversation_id}", response_model=ConversationHistory)
+async def get_conversation(conversation_id: str):
+    if conversation_id not in _conversations:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    conv = _conversations[conversation_id]
+    return ConversationHistory(
+        conversation_id=conversation_id,
+        messages=conv.messages,
+        usage=conv.usage,
+    )
+
+
+@app.delete("/v1/conversations/{conversation_id}")
+async def delete_conversation(conversation_id: str):
+    if conversation_id not in _conversations:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    del _conversations[conversation_id]
+    return {"status": "deleted", "conversation_id": conversation_id}

prompture/scaffold/templates/models.py.j2

@@ -0,0 +1,40 @@
+"""Pydantic request/response models for {{ project_name }}."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ChatRequest(BaseModel):
+    message: str
+    conversation_id: str | None = None
+    stream: bool = False
+    options: dict[str, Any] | None = None
+
+
+class ChatResponse(BaseModel):
+    message: str
+    conversation_id: str
+    usage: dict[str, Any]
+
+
+class ExtractRequest(BaseModel):
+    text: str
+    schema_def: dict[str, Any] = Field(..., alias="schema")
+    conversation_id: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class ExtractResponse(BaseModel):
+    json_object: dict[str, Any]
+    conversation_id: str
+    usage: dict[str, Any]
+
+
+class ConversationHistory(BaseModel):
+    conversation_id: str
+    messages: list[dict[str, Any]]
+    usage: dict[str, Any]

prompture/scaffold/templates/requirements.txt.j2

@@ -0,0 +1,5 @@
+prompture>=0.0.30
+fastapi>=0.100
+uvicorn[standard]>=0.20
+pydantic-settings>=2.0
+python-dotenv>=0.19.0

prompture/serialization.py

@@ -0,0 +1,218 @@
+"""Conversation serialization — pure data transforms for export/import.
+
+Handles converting Conversation state to/from plain dicts suitable for
+JSON serialization.  No I/O is performed here; see :mod:`persistence`
+for file and database storage.
+"""
+
+from __future__ import annotations
+
+import copy
+from datetime import datetime, timezone
+from typing import Any
+
+from .image import ImageContent
+from .session import UsageSession
+
+EXPORT_VERSION = 1
+
+
+# ------------------------------------------------------------------
+# Message content helpers
+# ------------------------------------------------------------------
+
+
+def _serialize_message_content(content: Any) -> Any:
+    """Convert ``ImageContent`` objects inside message content to plain dicts."""
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        out: list[Any] = []
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "image":
+                source = block.get("source")
+                if isinstance(source, ImageContent):
+                    out.append(
+                        {
+                            "type": "image",
+                            "source": {
+                                "data": source.data,
+                                "media_type": source.media_type,
+                                "source_type": source.source_type,
+                                "url": source.url,
+                            },
+                        }
+                    )
+                elif isinstance(source, dict):
+                    out.append(block)
+                else:
+                    out.append(block)
+            else:
+                out.append(block)
+        return out
+
+    return content
+
+
+def _deserialize_message_content(content: Any) -> Any:
+    """Reconstruct ``ImageContent`` objects from plain dicts in message content."""
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        out: list[Any] = []
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "image":
+                source = block.get("source")
+                if isinstance(source, dict) and "media_type" in source:
+                    out.append(
+                        {
+                            "type": "image",
+                            "source": ImageContent(
+                                data=source.get("data", ""),
+                                media_type=source["media_type"],
+                                source_type=source.get("source_type", "base64"),
+                                url=source.get("url"),
+                            ),
+                        }
+                    )
+                else:
+                    out.append(block)
+            else:
+                out.append(block)
+        return out
+
+    return content
+
+
+# ------------------------------------------------------------------
+# UsageSession export/import
+# ------------------------------------------------------------------
+
+
+def export_usage_session(session: UsageSession) -> dict[str, Any]:
+    """Serialize a :class:`UsageSession` to a plain dict."""
+    return {
+        "prompt_tokens": session.prompt_tokens,
+        "completion_tokens": session.completion_tokens,
+        "total_tokens": session.total_tokens,
+        "total_cost": session.total_cost,
+        "call_count": session.call_count,
+        "errors": session.errors,
+        "per_model": dict(session._per_model),
+    }
+
+
+def import_usage_session(data: dict[str, Any]) -> UsageSession:
+    """Reconstruct a :class:`UsageSession` from an exported dict."""
+    session = UsageSession(
+        prompt_tokens=data.get("prompt_tokens", 0),
+        completion_tokens=data.get("completion_tokens", 0),
+        total_tokens=data.get("total_tokens", 0),
+        total_cost=data.get("total_cost", 0.0),
+        call_count=data.get("call_count", 0),
+        errors=data.get("errors", 0),
+    )
+    per_model = data.get("per_model", {})
+    for model, stats in per_model.items():
+        session._per_model[model] = dict(stats)
+    return session
+
+
+# ------------------------------------------------------------------
+# Conversation export/import
+# ------------------------------------------------------------------
+
+
+def export_conversation(
+    *,
+    model_name: str,
+    system_prompt: str | None,
+    options: dict[str, Any],
+    messages: list[dict[str, Any]],
+    usage: dict[str, Any],
+    max_tool_rounds: int,
+    tools_metadata: list[dict[str, Any]] | None = None,
+    usage_session: UsageSession | None = None,
+    metadata: dict[str, Any] | None = None,
+    conversation_id: str,
+    strip_images: bool = False,
+) -> dict[str, Any]:
+    """Export conversation state to a JSON-serializable dict.
+
+    Args:
+        strip_images: When *True*, image blocks are removed from messages
+            and list-of-blocks content that becomes text-only is collapsed
+            to a plain string.
+    """
+    serialized_messages: list[dict[str, Any]] = []
+    for msg in messages:
+        msg_copy = dict(msg)
+        content = msg_copy.get("content")
+
+        if strip_images and isinstance(content, list):
+            filtered = [b for b in content if not (isinstance(b, dict) and b.get("type") == "image")]
+            if len(filtered) == 1 and isinstance(filtered[0], dict) and filtered[0].get("type") == "text":
+                msg_copy["content"] = filtered[0]["text"]
+            elif filtered:
+                msg_copy["content"] = _serialize_message_content(filtered)
+            else:
+                msg_copy["content"] = ""
+        else:
+            msg_copy["content"] = _serialize_message_content(content)
+
+        serialized_messages.append(msg_copy)
+
+    now = datetime.now(timezone.utc).isoformat()
+    meta = dict(metadata) if metadata else {}
+    meta.setdefault("created_at", now)
+    meta["last_active"] = now
+    meta["turn_count"] = usage.get("turns", 0)
+
+    export: dict[str, Any] = {
+        "version": EXPORT_VERSION,
+        "conversation_id": conversation_id,
+        "model_name": model_name,
+        "system_prompt": system_prompt,
+        "options": dict(options),
+        "messages": serialized_messages,
+        "usage": dict(usage),
+        "max_tool_rounds": max_tool_rounds,
+        "metadata": meta,
+    }
+
+    if tools_metadata:
+        export["tools"] = tools_metadata
+
+    if usage_session is not None:
+        export["usage_session"] = export_usage_session(usage_session)
+
+    return export
+
+
+def import_conversation(data: dict[str, Any]) -> dict[str, Any]:
+    """Validate and deserialize an exported conversation dict.
+
+    Returns a dict with deserialized messages (``ImageContent`` objects
+    reconstructed).
+
+    Raises:
+        ValueError: If the export version is unsupported.
+    """
+    version = data.get("version")
+    if version != EXPORT_VERSION:
+        raise ValueError(f"Unsupported export version: {version}. Expected {EXPORT_VERSION}.")
+
+    result = copy.deepcopy(data)
+
+    # Deserialize message content
+    for msg in result.get("messages", []):
+        if "content" in msg:
+            msg["content"] = _deserialize_message_content(msg["content"])
+
+    # Deserialize usage_session if present
+    if "usage_session" in result and isinstance(result["usage_session"], dict):
+        result["usage_session"] = import_usage_session(result["usage_session"])
+
+    return result