promptmenu-api 0.1.0__tar.gz

promptmenu_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Incognita Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

promptmenu_api-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: promptmenu-api
+Version: 0.1.0
+Summary: Python SDK for the promptmenu API
+License-Expression: MIT
+License-File: LICENSE
+Author: Jesse Dhillon
+Author-email: jesse@dhillon.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.25.0)

promptmenu_api-0.1.0/promptmenu_api/__init__.py

@@ -0,0 +1,35 @@
+"""Promptmenu Python SDK."""
+
+from promptmenu_api.client import (
+    AsyncPromptmenuClient,
+    AuthenticationError,
+    AuthorizationError,
+    Flight,
+    FlightSummary,
+    NotFoundError,
+    PromptmenuClient,
+    PromptmenuError,
+    Survey,
+    SurveyDimension,
+    SurveySchema,
+    Template,
+    TokenResponse,
+    ValidationError,
+)
+
+__all__ = [
+    "AsyncPromptmenuClient",
+    "AuthenticationError",
+    "AuthorizationError",
+    "Flight",
+    "FlightSummary",
+    "NotFoundError",
+    "PromptmenuClient",
+    "PromptmenuError",
+    "Survey",
+    "SurveyDimension",
+    "SurveySchema",
+    "Template",
+    "TokenResponse",
+    "ValidationError",
+]

promptmenu_api-0.1.0/promptmenu_api/client.py

@@ -0,0 +1,933 @@
+"""Promptmenu Python SDK — sync and async clients for the promptmenu API."""
+
+from __future__ import annotations
+
+import time
+import typing as t
+from dataclasses import dataclass, field
+
+import httpx
+
+
+class PromptmenuError(Exception):
+    """Base exception for promptmenu SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, detail: str | None = None) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(message)
+
+
+class AuthenticationError(PromptmenuError):
+    """Raised on 401 Unauthorized responses."""
+
+
+class AuthorizationError(PromptmenuError):
+    """Raised on 403 Forbidden responses."""
+
+
+class NotFoundError(PromptmenuError):
+    """Raised on 404 Not Found responses."""
+
+
+class ValidationError(PromptmenuError):
+    """Raised on 400/422 Bad Request responses."""
+
+
+# ---------------------------------------------------------------------------
+# Response dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Template(object):
+    template_id: str
+    name: str
+    version: int
+    content: str
+    description: str | None
+    is_active: bool
+    create_time: str
+    update_time: str
+
+
+@dataclass
+class Flight(object):
+    flight_id: str
+    template_id: str
+    template_name: str | None
+    template_version: int | None
+    created_by: str
+    feature_flags: dict[str, t.Any]
+    context: dict[str, t.Any]
+    rendered_content: str
+    model_provider: str
+    model_name: str
+    model_config_data: dict[str, t.Any]
+    status: str
+    started_at: str
+    completed_at: str | None
+    labels: dict[str, t.Any]
+    outcome_metadata: dict[str, t.Any] | None
+    create_time: str
+    update_time: str
+
+
+@dataclass
+class FlightSummary(object):
+    flight_id: str
+    template_id: str
+    template_name: str | None
+    template_version: int | None
+    created_by: str
+    feature_flags: dict[str, t.Any]
+    context: dict[str, t.Any]
+    model_provider: str
+    model_name: str
+    model_config_data: dict[str, t.Any]
+    status: str
+    started_at: str
+    completed_at: str | None
+    labels: dict[str, t.Any]
+    outcome_metadata: dict[str, t.Any] | None
+    create_time: str
+    update_time: str
+
+
+@dataclass
+class SurveyDimension(object):
+    name: str
+    label: str
+    spec: dict[str, t.Any]
+    required: bool = True
+    help: str | None = None
+    tags: list[str] = field(default_factory=list)
+    reverse_scored: bool = False
+
+
+@dataclass
+class SurveySchema(object):
+    schema_id: str
+    name: str
+    version: int
+    dimensions: list[dict[str, t.Any]]
+    dimensions_hash: str
+    create_time: str
+
+
+@dataclass
+class Survey(object):
+    survey_id: str
+    flight_id: str
+    schema_id: str | None
+    submitted_by: str
+    ratings: dict[str, t.Any]
+    notes: str | None
+    tags: list[str]
+    create_time: str
+
+
+@dataclass
+class TokenResponse(object):
+    access_token: str
+    token_type: str
+    expires_in: int
+    scopes: list[str]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_ERROR_MAP: dict[int, type[PromptmenuError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: AuthorizationError,
+    404: NotFoundError,
+    422: ValidationError,
+}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    detail = None
+    try:
+        body = response.json()
+        detail = body.get("detail")
+    except Exception:
+        pass
+    exc_cls = _ERROR_MAP.get(response.status_code, PromptmenuError)
+    raise exc_cls(
+        f"HTTP {response.status_code}: {detail or response.reason_phrase}",
+        status_code=response.status_code,
+        detail=detail,
+    )
+
+
+def _parse_template(data: dict[str, t.Any]) -> Template:
+    return Template(
+        template_id=data["template_id"],
+        name=data["name"],
+        version=data["version"],
+        content=data["content"],
+        description=data.get("description"),
+        is_active=data["is_active"],
+        create_time=data["create_time"],
+        update_time=data["update_time"],
+    )
+
+
+def _parse_flight(data: dict[str, t.Any]) -> Flight:
+    return Flight(
+        flight_id=data["flight_id"],
+        template_id=data["template_id"],
+        template_name=data.get("template_name"),
+        template_version=data.get("template_version"),
+        created_by=data["created_by"],
+        feature_flags=data["feature_flags"],
+        context=data["context"],
+        rendered_content=data["rendered_content"],
+        model_provider=data["model_provider"],
+        model_name=data["model_name"],
+        model_config_data=data["model_config_data"],
+        status=data["status"],
+        started_at=data["started_at"],
+        completed_at=data.get("completed_at"),
+        labels=data["labels"],
+        outcome_metadata=data.get("outcome_metadata"),
+        create_time=data["create_time"],
+        update_time=data["update_time"],
+    )
+
+
+def _parse_flight_summary(data: dict[str, t.Any]) -> FlightSummary:
+    return FlightSummary(
+        flight_id=data["flight_id"],
+        template_id=data["template_id"],
+        template_name=data.get("template_name"),
+        template_version=data.get("template_version"),
+        created_by=data["created_by"],
+        feature_flags=data["feature_flags"],
+        context=data["context"],
+        model_provider=data["model_provider"],
+        model_name=data["model_name"],
+        model_config_data=data["model_config_data"],
+        status=data["status"],
+        started_at=data["started_at"],
+        completed_at=data.get("completed_at"),
+        labels=data["labels"],
+        outcome_metadata=data.get("outcome_metadata"),
+        create_time=data["create_time"],
+        update_time=data["update_time"],
+    )
+
+
+def _parse_survey_schema(data: dict[str, t.Any]) -> SurveySchema:
+    return SurveySchema(
+        schema_id=data["schema_id"],
+        name=data["name"],
+        version=data["version"],
+        dimensions=data["dimensions"],
+        dimensions_hash=data["dimensions_hash"],
+        create_time=data["create_time"],
+    )
+
+
+def _parse_survey(data: dict[str, t.Any]) -> Survey:
+    return Survey(
+        survey_id=data["survey_id"],
+        flight_id=data["flight_id"],
+        schema_id=data.get("schema_id"),
+        submitted_by=data["submitted_by"],
+        ratings=data["ratings"],
+        notes=data.get("notes"),
+        tags=data.get("tags", []),
+        create_time=data["create_time"],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Token cache
+# ---------------------------------------------------------------------------
+
+
+class _TokenCache(object):
+    """Caches a JWT token and auto-refreshes before expiry."""
+
+    def __init__(self) -> None:
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    @property
+    def valid(self) -> bool:
+        return self._token is not None and time.monotonic() < self._expires_at
+
+    @property
+    def token(self) -> str | None:
+        if self.valid:
+            return self._token
+        return None
+
+    def store(self, token_response: TokenResponse) -> None:
+        self._token = token_response.access_token
+        # Refresh 60s before actual expiry to avoid edge cases
+        self._expires_at = time.monotonic() + max(token_response.expires_in - 60, 0)
+
+    def clear(self) -> None:
+        self._token = None
+        self._expires_at = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Synchronous client
+# ---------------------------------------------------------------------------
+
+
+class PromptmenuClient(object):
+    """Synchronous client for the promptmenu API.
+
+    Usage::
+
+        client = PromptmenuClient("https://promptmenu.ai", api_key="your-api-key")
+
+        # Server-side operations (API key auth)
+        template = client.create_template(name="greeting", content="Hello {{ name }}!")
+        flight = client.create_flight(
+            template="greeting",
+            created_by="my-app",
+            context={"name": "World"},
+            model_provider="anthropic",
+            model_name="claude-sonnet-4-5-20250929",
+        )
+
+        # Browser-facing operations (auto-obtains JWT)
+        schemas = client.list_survey_schemas()
+        client.create_survey(
+            flight_id=flight.flight_id,
+            submitted_by="user@example.com",
+            ratings={"quality": 5},
+        )
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = str(base_url).rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._token_cache = _TokenCache()
+
+    def _api_key_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    def _jwt_headers(self) -> dict[str, str]:
+        token = self._token_cache.token
+        if token is None:
+            resp = self.create_token()
+            self._token_cache.store(resp)
+            token = resp.access_token
+        return {"Authorization": f"Bearer {token}"}
+
+    # -- Auth ---------------------------------------------------------------
+
+    def create_token(self, *, scopes: list[str] | None = None) -> TokenResponse:
+        """Issue a scoped JWT for browser-facing requests."""
+        payload: dict[str, t.Any] = {}
+        if scopes is not None:
+            payload["scopes"] = scopes
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.post("/auth/token", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        data = resp.json()
+        return TokenResponse(
+            access_token=data["access_token"],
+            token_type=data["token_type"],
+            expires_in=data["expires_in"],
+            scopes=data["scopes"],
+        )
+
+    # -- Templates ----------------------------------------------------------
+
+    def create_template(
+        self,
+        *,
+        name: str,
+        content: str,
+        description: str | None = None,
+    ) -> Template:
+        """Create a prompt template."""
+        payload: dict[str, t.Any] = {"name": name, "content": content}
+        if description is not None:
+            payload["description"] = description
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.post("/templates", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_template(resp.json())
+
+    def get_template(self, template_id: str) -> Template:
+        """Get a template by ID."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get(f"/templates/{template_id}", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_template(resp.json())
+
+    def list_templates(
+        self,
+        *,
+        name: str | None = None,
+        is_active: bool | None = None,
+    ) -> list[Template]:
+        """List templates, optionally filtered."""
+        params: dict[str, t.Any] = {}
+        if name is not None:
+            params["name"] = name
+        if is_active is not None:
+            params["is_active"] = is_active
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get("/templates", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return [_parse_template(t_) for t_ in resp.json()["templates"]]
+
+    def update_template(
+        self,
+        template_id: str,
+        *,
+        description: str | None = None,
+        is_active: bool | None = None,
+    ) -> Template:
+        """Update a template's metadata."""
+        params: dict[str, t.Any] = {}
+        if description is not None:
+            params["description"] = description
+        if is_active is not None:
+            params["is_active"] = is_active
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.patch(f"/templates/{template_id}", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_template(resp.json())
+
+    # -- Flights ------------------------------------------------------------
+
+    def create_flight(
+        self,
+        *,
+        template: str,
+        created_by: str,
+        model_provider: str,
+        model_name: str,
+        template_bundle: dict[str, str] | None = None,
+        feature_flags: dict[str, t.Any] | None = None,
+        context: dict[str, t.Any] | None = None,
+        model_config_data: dict[str, t.Any] | None = None,
+        labels: dict[str, t.Any] | None = None,
+    ) -> Flight:
+        """Create a flight by rendering a template."""
+        payload: dict[str, t.Any] = {
+            "template": template,
+            "created_by": created_by,
+            "model_provider": model_provider,
+            "model_name": model_name,
+        }
+        if template_bundle is not None:
+            payload["template_bundle"] = template_bundle
+        if feature_flags is not None:
+            payload["feature_flags"] = feature_flags
+        if context is not None:
+            payload["context"] = context
+        if model_config_data is not None:
+            payload["model_config_data"] = model_config_data
+        if labels is not None:
+            payload["labels"] = labels
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.post("/flights", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    def get_flight(self, flight_id: str) -> Flight:
+        """Get a flight by ID."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get(f"/flights/{flight_id}", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    def list_flights(
+        self,
+        *,
+        template_id: str | None = None,
+        status: str | None = None,
+        created_by: str | None = None,
+        limit: int | None = None,
+    ) -> list[FlightSummary]:
+        """List flights, optionally filtered."""
+        params: dict[str, t.Any] = {}
+        if template_id is not None:
+            params["template_id"] = template_id
+        if status is not None:
+            params["status_filter"] = status
+        if created_by is not None:
+            params["created_by"] = created_by
+        if limit is not None:
+            params["limit"] = limit
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get("/flights", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return [_parse_flight_summary(f) for f in resp.json()["flights"]]
+
+    def update_flight(
+        self,
+        flight_id: str,
+        *,
+        status: str | None = None,
+        outcome_metadata: dict[str, t.Any] | None = None,
+    ) -> Flight:
+        """Update a flight's status and/or outcome metadata."""
+        payload: dict[str, t.Any] = {}
+        if status is not None:
+            payload["status"] = status
+        if outcome_metadata is not None:
+            payload["outcome_metadata"] = outcome_metadata
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.patch(f"/flights/{flight_id}", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    def complete_flight(
+        self,
+        flight_id: str,
+        *,
+        outcome_metadata: dict[str, t.Any] | None = None,
+    ) -> Flight:
+        """Mark a flight as completed."""
+        params: dict[str, t.Any] = {}
+        if outcome_metadata is not None:
+            params["outcome_metadata"] = outcome_metadata
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.post(f"/flights/{flight_id}/complete", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    # -- Survey schemas -----------------------------------------------------
+
+    def create_survey_schema(
+        self,
+        *,
+        name: str,
+        dimensions: list[SurveyDimension | dict[str, t.Any]],
+    ) -> SurveySchema:
+        """Create a survey schema."""
+        dims = []
+        for d in dimensions:
+            if isinstance(d, SurveyDimension):
+                dim: dict[str, t.Any] = {
+                    "name": d.name,
+                    "label": d.label,
+                    "spec": d.spec,
+                    "required": d.required,
+                    "tags": d.tags,
+                    "reverse_scored": d.reverse_scored,
+                }
+                if d.help is not None:
+                    dim["help"] = d.help
+                dims.append(dim)
+            else:
+                dims.append(d)
+        payload: dict[str, t.Any] = {"name": name, "dimensions": dims}
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.post("/survey-schemas", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_survey_schema(resp.json())
+
+    def get_survey_schema(self, schema_id: str) -> SurveySchema:
+        """Get a survey schema by ID (requires JWT)."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get(f"/survey-schemas/{schema_id}", headers=self._jwt_headers())
+        _raise_for_status(resp)
+        return _parse_survey_schema(resp.json())
+
+    def get_survey_schema_by_name(self, name: str, *, version: int | None = None) -> SurveySchema:
+        """Get a survey schema by name (requires JWT)."""
+        params: dict[str, t.Any] = {}
+        if version is not None:
+            params["version"] = version
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get(f"/survey-schemas/by-name/{name}", params=params, headers=self._jwt_headers())
+        _raise_for_status(resp)
+        return _parse_survey_schema(resp.json())
+
+    def list_survey_schemas(self) -> list[SurveySchema]:
+        """List all survey schemas (requires JWT)."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get("/survey-schemas", headers=self._jwt_headers())
+        _raise_for_status(resp)
+        return [_parse_survey_schema(s) for s in resp.json()["schemas"]]
+
+    # -- Surveys ------------------------------------------------------------
+
+    def create_survey(
+        self,
+        flight_id: str,
+        *,
+        submitted_by: str,
+        ratings: dict[str, t.Any],
+        schema_id: str | None = None,
+        notes: str | None = None,
+        tags: list[str] | None = None,
+    ) -> Survey:
+        """Submit a survey for a flight (requires JWT)."""
+        payload: dict[str, t.Any] = {
+            "submitted_by": submitted_by,
+            "ratings": ratings,
+        }
+        if schema_id is not None:
+            payload["schema_id"] = schema_id
+        if notes is not None:
+            payload["notes"] = notes
+        if tags is not None:
+            payload["tags"] = tags
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.post(f"/flights/{flight_id}/surveys", json=payload, headers=self._jwt_headers())
+        _raise_for_status(resp)
+        return _parse_survey(resp.json())
+
+    def list_surveys(self, flight_id: str) -> list[Survey]:
+        """List surveys for a flight."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get(f"/flights/{flight_id}/surveys", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return [_parse_survey(s) for s in resp.json()["surveys"]]
+
+    def get_survey(self, survey_id: str) -> Survey:
+        """Get a survey by ID."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = http.get(f"/surveys/{survey_id}", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_survey(resp.json())
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+
+class AsyncPromptmenuClient(object):
+    """Async client for the promptmenu API.
+
+    Usage::
+
+        async with AsyncPromptmenuClient("https://promptmenu.ai", api_key="key") as client:
+            flight = await client.create_flight(...)
+
+    Can also be used without the context manager::
+
+        client = AsyncPromptmenuClient("https://promptmenu.ai", api_key="key")
+        flight = await client.create_flight(...)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = str(base_url).rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._token_cache = _TokenCache()
+
+    async def __aenter__(self) -> AsyncPromptmenuClient:
+        return self
+
+    async def __aexit__(self, *args: t.Any) -> None:
+        pass
+
+    def _api_key_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    async def _jwt_headers(self) -> dict[str, str]:
+        token = self._token_cache.token
+        if token is None:
+            resp = await self.create_token()
+            self._token_cache.store(resp)
+            token = resp.access_token
+        return {"Authorization": f"Bearer {token}"}
+
+    # -- Auth ---------------------------------------------------------------
+
+    async def create_token(self, *, scopes: list[str] | None = None) -> TokenResponse:
+        """Issue a scoped JWT for browser-facing requests."""
+        payload: dict[str, t.Any] = {}
+        if scopes is not None:
+            payload["scopes"] = scopes
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.post("/auth/token", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        data = resp.json()
+        return TokenResponse(
+            access_token=data["access_token"],
+            token_type=data["token_type"],
+            expires_in=data["expires_in"],
+            scopes=data["scopes"],
+        )
+
+    # -- Templates ----------------------------------------------------------
+
+    async def create_template(
+        self,
+        *,
+        name: str,
+        content: str,
+        description: str | None = None,
+    ) -> Template:
+        """Create a prompt template."""
+        payload: dict[str, t.Any] = {"name": name, "content": content}
+        if description is not None:
+            payload["description"] = description
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.post("/templates", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_template(resp.json())
+
+    async def get_template(self, template_id: str) -> Template:
+        """Get a template by ID."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get(f"/templates/{template_id}", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_template(resp.json())
+
+    async def list_templates(
+        self,
+        *,
+        name: str | None = None,
+        is_active: bool | None = None,
+    ) -> list[Template]:
+        """List templates, optionally filtered."""
+        params: dict[str, t.Any] = {}
+        if name is not None:
+            params["name"] = name
+        if is_active is not None:
+            params["is_active"] = is_active
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get("/templates", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return [_parse_template(t_) for t_ in resp.json()["templates"]]
+
+    async def update_template(
+        self,
+        template_id: str,
+        *,
+        description: str | None = None,
+        is_active: bool | None = None,
+    ) -> Template:
+        """Update a template's metadata."""
+        params: dict[str, t.Any] = {}
+        if description is not None:
+            params["description"] = description
+        if is_active is not None:
+            params["is_active"] = is_active
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.patch(f"/templates/{template_id}", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_template(resp.json())
+
+    # -- Flights ------------------------------------------------------------
+
+    async def create_flight(
+        self,
+        *,
+        template: str,
+        created_by: str,
+        model_provider: str,
+        model_name: str,
+        template_bundle: dict[str, str] | None = None,
+        feature_flags: dict[str, t.Any] | None = None,
+        context: dict[str, t.Any] | None = None,
+        model_config_data: dict[str, t.Any] | None = None,
+        labels: dict[str, t.Any] | None = None,
+    ) -> Flight:
+        """Create a flight by rendering a template."""
+        payload: dict[str, t.Any] = {
+            "template": template,
+            "created_by": created_by,
+            "model_provider": model_provider,
+            "model_name": model_name,
+        }
+        if template_bundle is not None:
+            payload["template_bundle"] = template_bundle
+        if feature_flags is not None:
+            payload["feature_flags"] = feature_flags
+        if context is not None:
+            payload["context"] = context
+        if model_config_data is not None:
+            payload["model_config_data"] = model_config_data
+        if labels is not None:
+            payload["labels"] = labels
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.post("/flights", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    async def get_flight(self, flight_id: str) -> Flight:
+        """Get a flight by ID."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get(f"/flights/{flight_id}", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    async def list_flights(
+        self,
+        *,
+        template_id: str | None = None,
+        status: str | None = None,
+        created_by: str | None = None,
+        limit: int | None = None,
+    ) -> list[FlightSummary]:
+        """List flights, optionally filtered."""
+        params: dict[str, t.Any] = {}
+        if template_id is not None:
+            params["template_id"] = template_id
+        if status is not None:
+            params["status_filter"] = status
+        if created_by is not None:
+            params["created_by"] = created_by
+        if limit is not None:
+            params["limit"] = limit
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get("/flights", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return [_parse_flight_summary(f) for f in resp.json()["flights"]]
+
+    async def update_flight(
+        self,
+        flight_id: str,
+        *,
+        status: str | None = None,
+        outcome_metadata: dict[str, t.Any] | None = None,
+    ) -> Flight:
+        """Update a flight's status and/or outcome metadata."""
+        payload: dict[str, t.Any] = {}
+        if status is not None:
+            payload["status"] = status
+        if outcome_metadata is not None:
+            payload["outcome_metadata"] = outcome_metadata
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.patch(f"/flights/{flight_id}", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    async def complete_flight(
+        self,
+        flight_id: str,
+        *,
+        outcome_metadata: dict[str, t.Any] | None = None,
+    ) -> Flight:
+        """Mark a flight as completed."""
+        params: dict[str, t.Any] = {}
+        if outcome_metadata is not None:
+            params["outcome_metadata"] = outcome_metadata
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.post(f"/flights/{flight_id}/complete", params=params, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_flight(resp.json())
+
+    # -- Survey schemas -----------------------------------------------------
+
+    async def create_survey_schema(
+        self,
+        *,
+        name: str,
+        dimensions: list[SurveyDimension | dict[str, t.Any]],
+    ) -> SurveySchema:
+        """Create a survey schema."""
+        dims = []
+        for d in dimensions:
+            if isinstance(d, SurveyDimension):
+                dim: dict[str, t.Any] = {
+                    "name": d.name,
+                    "label": d.label,
+                    "spec": d.spec,
+                    "required": d.required,
+                    "tags": d.tags,
+                    "reverse_scored": d.reverse_scored,
+                }
+                if d.help is not None:
+                    dim["help"] = d.help
+                dims.append(dim)
+            else:
+                dims.append(d)
+        payload: dict[str, t.Any] = {"name": name, "dimensions": dims}
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.post("/survey-schemas", json=payload, headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_survey_schema(resp.json())
+
+    async def get_survey_schema(self, schema_id: str) -> SurveySchema:
+        """Get a survey schema by ID (requires JWT)."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get(f"/survey-schemas/{schema_id}", headers=await self._jwt_headers())
+        _raise_for_status(resp)
+        return _parse_survey_schema(resp.json())
+
+    async def get_survey_schema_by_name(self, name: str, *, version: int | None = None) -> SurveySchema:
+        """Get a survey schema by name (requires JWT)."""
+        params: dict[str, t.Any] = {}
+        if version is not None:
+            params["version"] = version
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get(f"/survey-schemas/by-name/{name}", params=params, headers=await self._jwt_headers())
+        _raise_for_status(resp)
+        return _parse_survey_schema(resp.json())
+
+    async def list_survey_schemas(self) -> list[SurveySchema]:
+        """List all survey schemas (requires JWT)."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get("/survey-schemas", headers=await self._jwt_headers())
+        _raise_for_status(resp)
+        return [_parse_survey_schema(s) for s in resp.json()["schemas"]]
+
+    # -- Surveys ------------------------------------------------------------
+
+    async def create_survey(
+        self,
+        flight_id: str,
+        *,
+        submitted_by: str,
+        ratings: dict[str, t.Any],
+        schema_id: str | None = None,
+        notes: str | None = None,
+        tags: list[str] | None = None,
+    ) -> Survey:
+        """Submit a survey for a flight (requires JWT)."""
+        payload: dict[str, t.Any] = {
+            "submitted_by": submitted_by,
+            "ratings": ratings,
+        }
+        if schema_id is not None:
+            payload["schema_id"] = schema_id
+        if notes is not None:
+            payload["notes"] = notes
+        if tags is not None:
+            payload["tags"] = tags
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.post(f"/flights/{flight_id}/surveys", json=payload, headers=await self._jwt_headers())
+        _raise_for_status(resp)
+        return _parse_survey(resp.json())
+
+    async def list_surveys(self, flight_id: str) -> list[Survey]:
+        """List surveys for a flight."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get(f"/flights/{flight_id}/surveys", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return [_parse_survey(s) for s in resp.json()["surveys"]]
+
+    async def get_survey(self, survey_id: str) -> Survey:
+        """Get a survey by ID."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as http:
+            resp = await http.get(f"/surveys/{survey_id}", headers=self._api_key_headers())
+        _raise_for_status(resp)
+        return _parse_survey(resp.json())

promptmenu_api-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"
+
+[project]
+name = "promptmenu-api"
+description = "Python SDK for the promptmenu API"
+dynamic = [ "version" ]
+requires-python = ">=3.10"
+authors = [
+    {name = "Jesse Dhillon", email = "jesse@dhillon.com" },
+]
+license = "MIT"
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[dependency-groups]
+test = [
+    "anyio[trio]~=4.0",
+    "pytest~=8.3.0",
+    "pytest-anyio~=0.0.0",
+]
+dev = [
+    "isort~=6.0.0",
+    "pyright~=1.1.0",
+    "ruff~=0.11.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "--strict-markers -svx"
+
+[tool.pyright]
+exclude = [
+  "**/.venv/**",
+]
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "strict"
+
+reportUnusedImport = false  # let ruff catch this
+reportUnusedVariable = false  # let ruff catch this
+
+reportUnknownParameterType = true
+reportUnknownArgumentType = true
+reportUnknownLambdaType = true
+reportUnknownVariableType = true
+reportUnknownMemberType = false
+reportMissingTypeStubs = false
+
+[tool.ruff]
+exclude = [
+  ".venv",
+]
+line-length = 120
+lint.select = [ "E", "F", "B", "T" ]
+lint.extend-ignore = [
+    "I",
+]
+preview = true
+target-version = "py310"
+
+[tool.black]
+line-length = 120
+target-version = ["py310"]
+skip-string-normalization = true
+
+[tool.isort]
+line_length = 120
+multi_line_output = 2  # HANGING_INDENT
+
+[tool.poetry]
+name = "promptmenu"
+version = "0.1.0"  # placeholder, read from VERSION.txt by poetry-dynamic-versioning
+packages = [{ include = "promptmenu_api" }]
+
+[tool.poetry-dynamic-versioning]
+enable = false
+
+[tool.poetry-dynamic-versioning.from-file]
+source = "VERSION.txt"