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

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/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/tools_schema.py

@@ -0,0 +1,254 @@
+"""Function calling / tool use support for Prompture.
+
+Provides :class:`ToolDefinition` for describing callable tools,
+:class:`ToolRegistry` for managing a collection of tools, and
+:func:`tool_from_function` to auto-generate tool schemas from type hints.
+
+Example::
+
+    from prompture import ToolRegistry
+
+    registry = ToolRegistry()
+
+    @registry.tool
+    def get_weather(city: str, units: str = "celsius") -> str:
+        \"\"\"Get the current weather for a city.\"\"\"
+        return f"Weather in {city}: 22 {units}"
+
+    # Or register explicitly
+    registry.register(get_weather)
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable, get_type_hints
+
+logger = logging.getLogger("prompture.tools_schema")
+
+# Mapping from Python types to JSON Schema types
+_TYPE_MAP: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+
+def _python_type_to_json_schema(annotation: Any) -> dict[str, Any]:
+    """Convert a Python type annotation to a JSON Schema snippet."""
+    if annotation is inspect.Parameter.empty or annotation is None:
+        return {"type": "string"}
+
+    # Handle Optional[X] (Union[X, None])
+    origin = getattr(annotation, "__origin__", None)
+    args = getattr(annotation, "__args__", ())
+
+    if origin is type(None):
+        return {"type": "string"}
+
+    # Union types (Optional)
+    if origin is not None and hasattr(origin, "__name__") and origin.__name__ == "Union":
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return _python_type_to_json_schema(non_none[0])
+
+    # list[X]
+    if origin is list and args:
+        return {"type": "array", "items": _python_type_to_json_schema(args[0])}
+
+    # dict[str, X]
+    if origin is dict:
+        return {"type": "object"}
+
+    # Simple types
+    json_type = _TYPE_MAP.get(annotation, "string")
+    return {"type": json_type}
+
+
+@dataclass
+class ToolDefinition:
+    """Describes a single callable tool the LLM can invoke.
+
+    Attributes:
+        name: Unique tool identifier.
+        description: Human-readable description shown to the LLM.
+        parameters: JSON Schema describing the function parameters.
+        function: The Python callable to execute.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    function: Callable[..., Any]
+
+    # ------------------------------------------------------------------
+    # Serialisation helpers
+    # ------------------------------------------------------------------
+
+    def to_openai_format(self) -> dict[str, Any]:
+        """Serialise to OpenAI ``tools`` array element format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def to_anthropic_format(self) -> dict[str, Any]:
+        """Serialise to Anthropic ``tools`` array element format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.parameters,
+        }
+
+
+def tool_from_function(fn: Callable[..., Any], *, name: str | None = None, description: str | None = None) -> ToolDefinition:
+    """Build a :class:`ToolDefinition` by inspecting *fn*'s signature and docstring.
+
+    Parameters:
+        fn: The callable to wrap.
+        name: Override the tool name (defaults to ``fn.__name__``).
+        description: Override the description (defaults to the first line of the docstring).
+    """
+    tool_name = name or fn.__name__
+    tool_desc = description or (inspect.getdoc(fn) or "").split("\n")[0] or f"Call {tool_name}"
+
+    sig = inspect.signature(fn)
+    try:
+        hints = get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for param_name, param in sig.parameters.items():
+        if param_name == "self":
+            continue
+        annotation = hints.get(param_name, param.annotation)
+        prop = _python_type_to_json_schema(annotation)
+
+        # Use parameter name as description fallback
+        prop.setdefault("description", f"Parameter: {param_name}")
+
+        properties[param_name] = prop
+
+        if param.default is inspect.Parameter.empty:
+            required.append(param_name)
+
+    parameters: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        parameters["required"] = required
+
+    return ToolDefinition(
+        name=tool_name,
+        description=tool_desc,
+        parameters=parameters,
+        function=fn,
+    )
+
+
+@dataclass
+class ToolRegistry:
+    """A collection of :class:`ToolDefinition` instances.
+
+    Supports decorator-based and explicit registration::
+
+        registry = ToolRegistry()
+
+        @registry.tool
+        def my_func(x: int) -> str:
+            ...
+
+        registry.register(another_func)
+    """
+
+    _tools: dict[str, ToolDefinition] = field(default_factory=dict)
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ToolDefinition:
+        """Register *fn* as a tool and return the :class:`ToolDefinition`."""
+        td = tool_from_function(fn, name=name, description=description)
+        self._tools[td.name] = td
+        return td
+
+    def tool(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Decorator to register a function as a tool.
+
+        Returns the original function unchanged so it remains callable.
+        """
+        self.register(fn)
+        return fn
+
+    def add(self, tool_def: ToolDefinition) -> None:
+        """Add a pre-built :class:`ToolDefinition`."""
+        self._tools[tool_def.name] = tool_def
+
+    # ------------------------------------------------------------------
+    # Lookup
+    # ------------------------------------------------------------------
+
+    def get(self, name: str) -> ToolDefinition | None:
+        return self._tools.get(name)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __bool__(self) -> bool:
+        return bool(self._tools)
+
+    @property
+    def names(self) -> list[str]:
+        return list(self._tools.keys())
+
+    @property
+    def definitions(self) -> list[ToolDefinition]:
+        return list(self._tools.values())
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def to_openai_format(self) -> list[dict[str, Any]]:
+        return [td.to_openai_format() for td in self._tools.values()]
+
+    def to_anthropic_format(self) -> list[dict[str, Any]]:
+        return [td.to_anthropic_format() for td in self._tools.values()]
+
+    # ------------------------------------------------------------------
+    # Execution
+    # ------------------------------------------------------------------
+
+    def execute(self, name: str, arguments: dict[str, Any]) -> Any:
+        """Execute a registered tool by name with the given arguments.
+
+        Raises:
+            KeyError: If no tool with *name* is registered.
+        """
+        td = self._tools.get(name)
+        if td is None:
+            raise KeyError(f"Tool not registered: {name!r}")
+        return td.function(**arguments)

{prompture-0.0.34.dev2.dist-info → prompture-0.0.35.dev1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 0.0.34.dev2
+Version: 0.0.35.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT
@@ -37,6 +37,12 @@ Provides-Extra: airllm
 Requires-Dist: airllm>=2.8.0; extra == "airllm"
 Provides-Extra: redis
 Requires-Dist: redis>=4.0; extra == "redis"
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.100; extra == "serve"
+Requires-Dist: uvicorn[standard]>=0.20; extra == "serve"
+Requires-Dist: sse-starlette>=1.6; extra == "serve"
+Provides-Extra: scaffold
+Requires-Dist: jinja2>=3.0; extra == "scaffold"
 Dynamic: license-file
 
 # Prompture