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

prompture/server.py

@@ -0,0 +1,183 @@
+"""Built-in API server wrapping AsyncConversation.
+
+Provides a FastAPI application with chat, extraction, and model
+listing endpoints.  ``fastapi``, ``uvicorn``, and ``sse-starlette``
+are lazy-imported so the module is importable without them installed.
+
+Usage::
+
+    from prompture.server import create_app
+    app = create_app(model_name="openai/gpt-4o-mini")
+"""
+
+import json
+import logging
+import uuid
+from typing import Any, Optional
+
+logger = logging.getLogger("prompture.server")
+
+
+def create_app(
+    model_name: str = "openai/gpt-4o-mini",
+    system_prompt: Optional[str] = None,
+    tools: Any = None,
+    cors_origins: Optional[list[str]] = None,
+) -> Any:
+    """Create and return a FastAPI application.
+
+    Parameters:
+        model_name: Default model string (``provider/model``).
+        system_prompt: Optional system prompt for new conversations.
+        tools: Optional :class:`~prompture.tools_schema.ToolRegistry`.
+        cors_origins: CORS allowed origins.  ``["*"]`` to allow all.
+
+    Returns:
+        A ``fastapi.FastAPI`` instance.
+    """
+    try:
+        from fastapi import FastAPI, HTTPException
+        from fastapi.middleware.cors import CORSMiddleware
+        from pydantic import BaseModel, Field
+    except ImportError as exc:
+        raise ImportError(
+            "The 'serve' extra is required: pip install prompture[serve]"
+        ) from exc
+
+    from .async_conversation import AsyncConversation
+    from .tools_schema import ToolRegistry
+
+    # ---- Pydantic request/response models ----
+
+    class ChatRequest(BaseModel):
+        message: str
+        conversation_id: Optional[str] = None
+        stream: bool = False
+        options: Optional[dict[str, Any]] = 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: Optional[str] = None
+
+        model_config = {"populate_by_name": True}
+
+    class ExtractResponse(BaseModel):
+        json_object: dict[str, Any]
+        conversation_id: str
+        usage: dict[str, Any]
+
+    class ModelInfo(BaseModel):
+        models: list[str]
+
+    class ConversationHistory(BaseModel):
+        conversation_id: str
+        messages: list[dict[str, Any]]
+        usage: dict[str, Any]
+
+    # ---- App ----
+
+    app = FastAPI(title="Prompture API", version="0.1.0")
+
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    # In-memory conversation store
+    _conversations: dict[str, AsyncConversation] = {}
+
+    tool_registry: Optional[ToolRegistry] = tools
+
+    def _get_or_create_conversation(conv_id: Optional[str]) -> 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=model_name,
+            system_prompt=system_prompt,
+            tools=tool_registry,
+        )
+        _conversations[new_id] = conv
+        return new_id, conv
+
+    # ---- Endpoints ----
+
+    @app.post("/v1/chat", response_model=ChatResponse)
+    async def chat(chat_req: ChatRequest):
+        conv_id, conv = _get_or_create_conversation(chat_req.conversation_id)
+
+        if chat_req.stream:
+            # SSE streaming
+            try:
+                from sse_starlette.sse import EventSourceResponse
+            except ImportError:
+                raise HTTPException(
+                    status_code=501,
+                    detail="Streaming requires sse-starlette: pip install prompture[serve]",
+                ) from None
+
+            async def event_generator():
+                full_text = ""
+                async for chunk in conv.ask_stream(chat_req.message, chat_req.options):
+                    full_text += chunk
+                    yield {"data": json.dumps({"text": chunk})}
+                yield {"data": json.dumps({"text": "", "done": True, "conversation_id": conv_id, "usage": conv.usage})}
+
+            return EventSourceResponse(event_generator())
+
+        text = await conv.ask(chat_req.message, chat_req.options)
+        return ChatResponse(message=text, conversation_id=conv_id, usage=conv.usage)
+
+    @app.post("/v1/extract", response_model=ExtractResponse)
+    async def extract(extract_req: ExtractRequest):
+        conv_id, conv = _get_or_create_conversation(extract_req.conversation_id)
+        result = await conv.ask_for_json(
+            content=extract_req.text,
+            json_schema=extract_req.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}
+
+    @app.get("/v1/models", response_model=ModelInfo)
+    async def list_models():
+        from .discovery import get_available_models
+
+        try:
+            models = get_available_models()
+            model_names = [m["id"] if isinstance(m, dict) else str(m) for m in models]
+        except Exception:
+            model_names = [model_name]
+        return ModelInfo(models=model_names)
+
+    return app

prompture/session.py

@@ -0,0 +1,117 @@
+"""Usage session tracking for Prompture.
+
+Provides :class:`UsageSession` which accumulates token counts, costs, and
+errors across multiple driver calls.  A session instance is compatible as
+both an ``on_response`` and ``on_error`` callback, so you can wire it
+directly into :class:`~prompture.callbacks.DriverCallbacks`.
+
+Usage::
+
+    from prompture import UsageSession, DriverCallbacks
+
+    session = UsageSession()
+    callbacks = DriverCallbacks(
+        on_response=session.record,
+        on_error=session.record_error,
+    )
+
+    # ... pass *callbacks* to your driver / conversation ...
+
+    print(session.summary()["formatted"])
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class UsageSession:
+    """Accumulates usage statistics across multiple driver calls."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    total_cost: float = 0.0
+    call_count: int = 0
+    errors: int = 0
+    _per_model: dict[str, dict[str, Any]] = field(default_factory=dict, repr=False)
+
+    # ------------------------------------------------------------------ #
+    # Recording
+    # ------------------------------------------------------------------ #
+
+    def record(self, response_info: dict[str, Any]) -> None:
+        """Record a successful driver response.
+
+        Compatible as an ``on_response`` callback for
+        :class:`~prompture.callbacks.DriverCallbacks`.
+
+        Args:
+            response_info: Payload dict with at least ``meta`` and
+                optionally ``driver`` keys.
+        """
+        meta = response_info.get("meta", {})
+        pt = meta.get("prompt_tokens", 0)
+        ct = meta.get("completion_tokens", 0)
+        tt = meta.get("total_tokens", 0)
+        cost = meta.get("cost", 0.0)
+
+        self.prompt_tokens += pt
+        self.completion_tokens += ct
+        self.total_tokens += tt
+        self.total_cost += cost
+        self.call_count += 1
+
+        model = response_info.get("driver", "unknown")
+        bucket = self._per_model.setdefault(
+            model,
+            {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "cost": 0.0, "calls": 0},
+        )
+        bucket["prompt_tokens"] += pt
+        bucket["completion_tokens"] += ct
+        bucket["total_tokens"] += tt
+        bucket["cost"] += cost
+        bucket["calls"] += 1
+
+    def record_error(self, error_info: dict[str, Any]) -> None:
+        """Record a driver error.
+
+        Compatible as an ``on_error`` callback for
+        :class:`~prompture.callbacks.DriverCallbacks`.
+        """
+        self.errors += 1
+
+    # ------------------------------------------------------------------ #
+    # Reporting
+    # ------------------------------------------------------------------ #
+
+    def summary(self) -> dict[str, Any]:
+        """Return a machine-readable summary with a ``formatted`` string."""
+        formatted = (
+            f"Session: {self.total_tokens:,} tokens across {self.call_count} call(s) costing ${self.total_cost:.4f}"
+        )
+        if self.errors:
+            formatted += f" ({self.errors} error(s))"
+
+        return {
+            "prompt_tokens": self.prompt_tokens,
+            "completion_tokens": self.completion_tokens,
+            "total_tokens": self.total_tokens,
+            "total_cost": self.total_cost,
+            "call_count": self.call_count,
+            "errors": self.errors,
+            "per_model": dict(self._per_model),
+            "formatted": formatted,
+        }
+
+    def reset(self) -> None:
+        """Clear all accumulated counters."""
+        self.prompt_tokens = 0
+        self.completion_tokens = 0
+        self.total_tokens = 0
+        self.total_cost = 0.0
+        self.call_count = 0
+        self.errors = 0
+        self._per_model.clear()

prompture/settings.py

@@ -1,6 +1,8 @@
-from pydantic_settings import BaseSettings, SettingsConfigDict
 from typing import Optional
 
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
 class Settings(BaseSettings):
     """Application settings loaded from environment variables or .env file."""
 
@@ -31,6 +33,7 @@ class Settings(BaseSettings):
     # LM Studio
     lmstudio_endpoint: str = "http://127.0.0.1:1234/v1/chat/completions"
     lmstudio_model: str = "deepseek/deepseek-r1-0528-qwen3-8b"
+    lmstudio_api_key: Optional[str] = None
 
     # Google
     google_api_key: Optional[str] = None
@@ -48,6 +51,21 @@ class Settings(BaseSettings):
     grok_api_key: Optional[str] = None
     grok_model: str = "grok-4-fast-reasoning"
 
+    # AirLLM
+    airllm_model: str = "meta-llama/Llama-2-7b-hf"
+    airllm_compression: Optional[str] = None  # "4bit" or "8bit"
+
+    # Model rates cache
+    model_rates_ttl_days: int = 7  # How often to refresh models.dev cache
+
+    # Response cache
+    cache_enabled: bool = False
+    cache_backend: str = "memory"
+    cache_ttl_seconds: int = 3600
+    cache_memory_maxsize: int = 256
+    cache_sqlite_path: Optional[str] = None
+    cache_redis_url: Optional[str] = None
+
     model_config = SettingsConfigDict(
         env_file=".env",
         extra="ignore",