prompture 0.0.29.dev8__py3-none-any.whl → 0.0.35__py3-none-any.whl

prompture/model_rates.py

@@ -0,0 +1,217 @@
+"""Live model rates from models.dev API with local caching.
+
+Fetches pricing and metadata for LLM models from https://models.dev/api.json,
+caches locally with TTL-based auto-refresh, and provides lookup functions
+used by drivers for cost calculations.
+"""
+
+import contextlib
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# Maps prompture provider names to models.dev provider names
+PROVIDER_MAP: dict[str, str] = {
+    "openai": "openai",
+    "claude": "anthropic",
+    "google": "google",
+    "groq": "groq",
+    "grok": "xai",
+    "azure": "azure",
+    "openrouter": "openrouter",
+}
+
+_API_URL = "https://models.dev/api.json"
+_CACHE_DIR = Path.home() / ".prompture" / "cache"
+_CACHE_FILE = _CACHE_DIR / "models_dev.json"
+_META_FILE = _CACHE_DIR / "models_dev_meta.json"
+
+_lock = threading.Lock()
+_data: Optional[dict[str, Any]] = None
+_loaded = False
+
+
+def _get_ttl_days() -> int:
+    """Get TTL from settings if available, otherwise default to 7."""
+    try:
+        from .settings import settings
+
+        return getattr(settings, "model_rates_ttl_days", 7)
+    except Exception:
+        return 7
+
+
+def _cache_is_valid() -> bool:
+    """Check whether the local cache exists and is within TTL."""
+    if not _CACHE_FILE.exists() or not _META_FILE.exists():
+        return False
+    try:
+        meta = json.loads(_META_FILE.read_text(encoding="utf-8"))
+        fetched_at = datetime.fromisoformat(meta["fetched_at"])
+        ttl_days = meta.get("ttl_days", _get_ttl_days())
+        age = datetime.now(timezone.utc) - fetched_at
+        return age.total_seconds() < ttl_days * 86400
+    except Exception:
+        return False
+
+
+def _write_cache(data: dict[str, Any]) -> None:
+    """Write API data and metadata to local cache."""
+    try:
+        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        _CACHE_FILE.write_text(json.dumps(data), encoding="utf-8")
+        meta = {
+            "fetched_at": datetime.now(timezone.utc).isoformat(),
+            "ttl_days": _get_ttl_days(),
+        }
+        _META_FILE.write_text(json.dumps(meta), encoding="utf-8")
+    except Exception as exc:
+        logger.debug("Failed to write model rates cache: %s", exc)
+
+
+def _read_cache() -> Optional[dict[str, Any]]:
+    """Read cached API data from disk."""
+    try:
+        return json.loads(_CACHE_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def _fetch_from_api() -> Optional[dict[str, Any]]:
+    """Fetch fresh data from models.dev API."""
+    try:
+        import requests
+
+        resp = requests.get(_API_URL, timeout=15)
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as exc:
+        logger.debug("Failed to fetch model rates from %s: %s", _API_URL, exc)
+        return None
+
+
+def _ensure_loaded() -> Optional[dict[str, Any]]:
+    """Lazy-load data: use cache if valid, otherwise fetch from API."""
+    global _data, _loaded
+    if _loaded:
+        return _data
+
+    with _lock:
+        # Double-check after acquiring lock
+        if _loaded:
+            return _data
+
+        if _cache_is_valid():
+            _data = _read_cache()
+            if _data is not None:
+                _loaded = True
+                return _data
+
+        # Cache missing or expired — fetch fresh
+        fresh = _fetch_from_api()
+        if fresh is not None:
+            _data = fresh
+            _write_cache(fresh)
+        else:
+            # Fetch failed — try stale cache as last resort
+            _data = _read_cache()
+
+        _loaded = True
+        return _data
+
+
+def _lookup_model(provider: str, model_id: str) -> Optional[dict[str, Any]]:
+    """Find a model entry in the cached data.
+
+    The API structure is ``{provider: {model_id: {...}, ...}, ...}``.
+    """
+    data = _ensure_loaded()
+    if data is None:
+        return None
+
+    api_provider = PROVIDER_MAP.get(provider, provider)
+    provider_data = data.get(api_provider)
+    if not isinstance(provider_data, dict):
+        return None
+
+    return provider_data.get(model_id)
+
+
+# ── Public API ──────────────────────────────────────────────────────────────
+
+
+def get_model_rates(provider: str, model_id: str) -> Optional[dict[str, float]]:
+    """Return pricing dict for a model, or ``None`` if unavailable.
+
+    Returned keys mirror models.dev cost fields (per 1M tokens):
+    ``input``, ``output``, and optionally ``cache_read``, ``cache_write``,
+    ``reasoning``.
+    """
+    entry = _lookup_model(provider, model_id)
+    if entry is None:
+        return None
+
+    cost = entry.get("cost")
+    if not isinstance(cost, dict):
+        return None
+
+    rates: dict[str, float] = {}
+    for key in ("input", "output", "cache_read", "cache_write", "reasoning"):
+        val = cost.get(key)
+        if val is not None:
+            with contextlib.suppress(TypeError, ValueError):
+                rates[key] = float(val)
+
+    # Must have at least input and output to be useful
+    if "input" in rates and "output" in rates:
+        return rates
+    return None
+
+
+def get_model_info(provider: str, model_id: str) -> Optional[dict[str, Any]]:
+    """Return full model metadata (cost, limits, capabilities), or ``None``."""
+    return _lookup_model(provider, model_id)
+
+
+def get_all_provider_models(provider: str) -> list[str]:
+    """Return list of model IDs available for a provider."""
+    data = _ensure_loaded()
+    if data is None:
+        return []
+
+    api_provider = PROVIDER_MAP.get(provider, provider)
+    provider_data = data.get(api_provider)
+    if not isinstance(provider_data, dict):
+        return []
+
+    return list(provider_data.keys())
+
+
+def refresh_rates_cache(force: bool = False) -> bool:
+    """Fetch fresh data from models.dev.
+
+    Args:
+        force: If ``True``, fetch even when the cache is still within TTL.
+
+    Returns:
+        ``True`` if fresh data was fetched and cached successfully.
+    """
+    global _data, _loaded
+
+    with _lock:
+        if not force and _cache_is_valid():
+            return False
+
+        fresh = _fetch_from_api()
+        if fresh is not None:
+            _data = fresh
+            _write_cache(fresh)
+            _loaded = True
+            return True
+
+        return False

prompture/runner.py

@@ -1,13 +1,15 @@
 """Test suite runner for executing JSON validation tests across multiple models."""
-from typing import Dict, Any, List
 
-from .core import ask_for_json, Driver
+from typing import Any
+
 from prompture.validator import validate_against_schema
 
+from .core import Driver, ask_for_json
+
 
-def run_suite_from_spec(spec: Dict[str, Any], drivers: Dict[str, Driver]) -> Dict[str, Any]:
+def run_suite_from_spec(spec: dict[str, Any], drivers: dict[str, Driver]) -> dict[str, Any]:
     """Run a test suite specified by a spec dictionary across multiple models.
-    
+
     Args:
         spec: A dictionary containing the test suite specification with the structure:
             {
@@ -21,7 +23,7 @@ def run_suite_from_spec(spec: Dict[str, Any], drivers: Dict[str, Driver]) -> Dic
                 }, ...]
             }
         drivers: A dictionary mapping driver names to driver instances
-        
+
     Returns:
         A dictionary containing test results with the structure:
             {
@@ -42,67 +44,67 @@ def run_suite_from_spec(spec: Dict[str, Any], drivers: Dict[str, Driver]) -> Dic
             }
     """
     results = []
-    
+
     for test in spec["tests"]:
         for model in spec["models"]:
             driver = drivers.get(model["driver"])
             if not driver:
                 continue
-                
+
             # Run test for each input
             for input_data in test["inputs"]:
                 # Format prompt template with input data
                 try:
                     prompt = test["prompt_template"].format(**input_data)
                 except KeyError as e:
-                    results.append({
-                        "test_id": test["id"],
-                        "model_id": model["id"],
-                        "input": input_data,
-                        "prompt": test["prompt_template"],
-                        "error": f"Template formatting error: missing key {e}",
-                        "validation": {"ok": False, "error": "Prompt formatting failed", "data": None},
-                        "usage": {"total_tokens": 0, "cost": 0}
-                    })
+                    results.append(
+                        {
+                            "test_id": test["id"],
+                            "model_id": model["id"],
+                            "input": input_data,
+                            "prompt": test["prompt_template"],
+                            "error": f"Template formatting error: missing key {e}",
+                            "validation": {"ok": False, "error": "Prompt formatting failed", "data": None},
+                            "usage": {"total_tokens": 0, "cost": 0},
+                        }
+                    )
                     continue
-                    
+
                 # Get JSON response from model
                 try:
                     response = ask_for_json(
                         driver=driver,
                         content_prompt=prompt,
                         json_schema=test["schema"],
-                        options=model.get("options", {})
+                        options=model.get("options", {}),
                     )
-                    
+
                     # Validate response against schema
-                    validation = validate_against_schema(
-                        response["json_string"],
-                        test["schema"]
+                    validation = validate_against_schema(response["json_string"], test["schema"])
+
+                    results.append(
+                        {
+                            "test_id": test["id"],
+                            "model_id": model["id"],
+                            "input": input_data,
+                            "prompt": prompt,
+                            "response": response["json_object"],
+                            "validation": validation,
+                            "usage": response["usage"],
+                        }
                     )
-                    
-                    results.append({
-                        "test_id": test["id"],
-                        "model_id": model["id"],
-                        "input": input_data,
-                        "prompt": prompt,
-                        "response": response["json_object"],
-                        "validation": validation,
-                        "usage": response["usage"]
-                    })
-                    
+
                 except Exception as e:
-                    results.append({
-                        "test_id": test["id"],
-                        "model_id": model["id"],
-                        "input": input_data,
-                        "prompt": prompt,
-                        "error": str(e),
-                        "validation": {"ok": False, "error": "Model response error", "data": None},
-                        "usage": {"total_tokens": 0, "cost": 0}
-                    })
-    
-    return {
-        "meta": spec.get("meta", {}),
-        "results": results
-    }
+                    results.append(
+                        {
+                            "test_id": test["id"],
+                            "model_id": model["id"],
+                            "input": input_data,
+                            "prompt": prompt,
+                            "error": str(e),
+                            "validation": {"ok": False, "error": "Model response error", "data": None},
+                            "usage": {"total_tokens": 0, "cost": 0},
+                        }
+                    )
+
+    return {"meta": spec.get("meta", {}), "results": results}

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

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