promptuna-server 1.24.0__tar.gz

promptuna_server-1.24.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.3
+Name: promptuna-server
+Version: 1.24.0
+Summary: FastAPI server for streaming promptuna run / evaluate / optimize jobs
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: promptuna==1.24.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Python: >=3.13

promptuna_server-1.24.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "promptuna-server"
+version = "1.24.0"
+description = "FastAPI server for streaming promptuna run / evaluate / optimize jobs"
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.115.0",
+    "promptuna==1.24.0",
+    "uvicorn[standard]>=0.32.0",
+]
+
+[tool.uv.sources]
+promptuna = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.11.1,<0.12.0"]
+build-backend = "uv_build"

promptuna_server-1.24.0/src/promptuna_server/__init__.py

@@ -0,0 +1 @@
+"""FastAPI transport layer for streaming promptuna jobs."""

promptuna_server-1.24.0/src/promptuna_server/jobs.py

@@ -0,0 +1,182 @@
+"""Job lifecycle: background threads, queues, SSE event bridging, and on-disk jobs."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import uuid
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from typing import Any
+
+from promptuna.evaluate import Metric, Scoring, stream_evaluate
+from promptuna.jobs import JobArchive, JobConfig, JobKind, JobStatus, get_jobs_root, stream_job
+from promptuna.optimize import Step, stream_optimize
+from promptuna.program import Example, Experiment
+from promptuna.run import Trial, stream_run
+
+_WAIT_TIMEOUT_SECONDS = 1.0
+
+StreamSource = Callable[[], Iterator[Trial | Scoring | Step]]
+
+
+@dataclass
+class JobState:
+    """In-memory job record for one streaming job."""
+
+    job_id: str
+    kind: JobKind
+    archive: JobArchive
+    status: JobStatus = "running"
+    events: list[dict[str, Any]] = field(default_factory=list)
+    error: str | None = None
+    _cond: threading.Condition = field(default_factory=threading.Condition)
+
+
+_jobs: dict[str, JobState] = {}
+_jobs_lock = threading.Lock()
+
+
+def _has_running_job() -> bool:
+    return any(job.status == "running" for job in _jobs.values())
+
+
+def _append_event(job: JobState, envelope: dict[str, Any]) -> None:
+    with job._cond:
+        job.events.append(envelope)
+        job._cond.notify_all()
+
+
+def _finish_job(job: JobState) -> None:
+    with job._cond:
+        job._cond.notify_all()
+
+
+def start_run_job(
+    *,
+    config: JobConfig,
+    experiment: Experiment,
+    examples: list[Example],
+    workers: int,
+) -> str:
+    """Start a run job and return its ``job_id``."""
+    return _start_job(
+        "run",
+        lambda: stream_run(experiment, examples, workers=workers),
+        config=config,
+    )
+
+
+def start_evaluate_job(
+    *,
+    config: JobConfig,
+    experiment: Experiment,
+    examples: list[Example],
+    metrics: list[Metric],
+    workers: int,
+) -> str:
+    """Start an evaluate job and return its ``job_id``."""
+    return _start_job(
+        "evaluate",
+        lambda: stream_evaluate(experiment, examples, metrics, workers=workers),
+        config=config,
+    )
+
+
+def start_optimize_job(
+    *,
+    config: JobConfig,
+    experiment: Experiment,
+    examples: list[Example],
+    metrics: list[Metric],
+    workers: int,
+    steps: int,
+    proposer_model: str,
+) -> str:
+    """Start an optimize job and return its ``job_id``."""
+    return _start_job(
+        "optimize",
+        lambda: stream_optimize(
+            experiment,
+            examples,
+            metrics,
+            proposer_model=proposer_model,
+            steps=steps,
+            workers=workers,
+        ),
+        config=config,
+    )
+
+
+def _start_job(kind: JobKind, build_source: StreamSource, *, config: JobConfig) -> str:
+    with _jobs_lock:
+        if _has_running_job():
+            raise ConflictError("another job is already running")
+        job_id = str(uuid.uuid4())
+        archive = JobArchive.open(get_jobs_root(), job_id, config)
+        job = JobState(job_id=job_id, kind=kind, archive=archive)
+        _jobs[job_id] = job
+
+    thread = threading.Thread(
+        target=_job_thread,
+        args=(job, build_source),
+        daemon=True,
+        name=f"promptuna-{kind}-{job_id[:8]}",
+    )
+    thread.start()
+    return job_id
+
+
+class ConflictError(Exception):
+    """Raised when a second job is started while one is running."""
+
+
+class JobNotFoundError(Exception):
+    """Raised when ``job_id`` is unknown."""
+
+
+def get_job(job_id: str) -> JobState:
+    """Return job state or raise :class:`JobNotFoundError`."""
+    try:
+        return _jobs[job_id]
+    except KeyError as exc:
+        raise JobNotFoundError(job_id) from exc
+
+
+def _job_thread(job: JobState, build_source: StreamSource) -> None:
+    try:
+        for envelope in stream_job(job.archive, build_source()):
+            _append_event(job, envelope)
+        job.status = "done"
+    except Exception as exc:
+        job.status = "error"
+        job.error = str(exc)
+    finally:
+        _finish_job(job)
+
+
+async def stream_job_events(job_id: str):
+    """Async generator yielding SSE ``data:`` lines for ``job_id``."""
+    job = get_job(job_id)
+    offset = 0
+    while True:
+        batch, done = await asyncio.to_thread(_wait_for_events, job, offset)
+        for envelope in batch:
+            yield f"data: {json.dumps(envelope)}\n\n"
+            offset += 1
+        if done and offset >= len(job.events):
+            break
+
+
+def _wait_for_events(job: JobState, offset: int) -> tuple[list[dict[str, Any]], bool]:
+    with job._cond:
+        while offset >= len(job.events) and job.status == "running":
+            job._cond.wait(timeout=_WAIT_TIMEOUT_SECONDS)
+        return job.events[offset:], job.status != "running"
+
+
+def reset_jobs() -> None:
+    """Clear all jobs (tests only)."""
+    with _jobs_lock:
+        _jobs.clear()

promptuna_server-1.24.0/src/promptuna_server/main.py

@@ -0,0 +1,206 @@
+"""FastAPI application: routes, CORS, and job orchestration."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+
+from promptuna.jobs import JobConfig, JobKind
+from promptuna.projects import (
+    ProjectValidationError,
+    build_catalog,
+    build_experiment,
+    get_projects_root,
+    resolve_dataset_path,
+    resolve_project_dir,
+)
+from promptuna_server import jobs
+from promptuna_server.schemas import (
+    CatalogResponse,
+    EvaluateRequest,
+    JobStartResponse,
+    OptimizeRequest,
+    ProjectCatalogResponse,
+    RunRequest,
+)
+
+app = FastAPI(title="promptuna-server")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:5173",
+        "http://127.0.0.1:5173",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def _validation_error(exc: ProjectValidationError) -> HTTPException:
+    return HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc))
+
+
+def _job_config(
+    request: RunRequest,
+    *,
+    kind: JobKind,
+    metrics: list[str] | None = None,
+    steps: int | None = None,
+    proposer_model: str | None = None,
+) -> JobConfig:
+    project_dir = resolve_project_dir(request.project)
+    dataset_path = resolve_dataset_path(project_dir, request.examples)
+    return JobConfig(
+        kind=kind,
+        projects_root=get_projects_root(),
+        project=request.project,
+        program=request.program,
+        prompt=request.prompt,
+        examples=request.examples,
+        dataset_path=dataset_path,
+        model=request.model,
+        workers=request.workers,
+        metrics=tuple(metrics) if metrics is not None else None,
+        steps=steps,
+        proposer_model=proposer_model,
+    )
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    """Liveness check."""
+    return {"status": "ok"}
+
+
+@app.get("/catalog", response_model=CatalogResponse)
+def catalog() -> CatalogResponse:
+    """List project and artifact names under the active projects root."""
+    workspace = build_catalog()
+    return CatalogResponse(
+        projects_root=str(workspace.projects_root),
+        projects=[
+            ProjectCatalogResponse(
+                name=entry.name,
+                programs=entry.programs,
+                metrics=entry.metrics,
+                prompts=entry.prompts,
+                datasets=entry.datasets,
+            )
+            for entry in workspace.projects
+        ],
+    )
+
+
+@app.post("/run", response_model=JobStartResponse)
+def start_run(request: RunRequest) -> JobStartResponse:
+    """Start a run job; stream trials via ``GET /jobs/{job_id}/events``."""
+    try:
+        experiment, examples, _ = build_experiment(
+            project=request.project,
+            program=request.program,
+            prompt=request.prompt,
+            model=request.model,
+            examples=request.examples,
+        )
+        config = _job_config(request, kind="run")
+    except ProjectValidationError as exc:
+        raise _validation_error(exc) from exc
+
+    try:
+        job_id = jobs.start_run_job(
+            config=config,
+            experiment=experiment,
+            examples=examples,
+            workers=request.workers,
+        )
+    except jobs.ConflictError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc
+
+    return JobStartResponse(job_id=job_id)
+
+
+@app.post("/evaluate", response_model=JobStartResponse)
+def start_evaluate(request: EvaluateRequest) -> JobStartResponse:
+    """Start an evaluate job; stream trials and scorings via SSE."""
+    try:
+        experiment, examples, metrics = build_experiment(
+            project=request.project,
+            program=request.program,
+            prompt=request.prompt,
+            model=request.model,
+            examples=request.examples,
+            metrics=request.metrics,
+        )
+        config = _job_config(request, kind="evaluate", metrics=request.metrics)
+    except ProjectValidationError as exc:
+        raise _validation_error(exc) from exc
+
+    assert metrics is not None
+    try:
+        job_id = jobs.start_evaluate_job(
+            config=config,
+            experiment=experiment,
+            examples=examples,
+            metrics=metrics,
+            workers=request.workers,
+        )
+    except jobs.ConflictError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc
+
+    return JobStartResponse(job_id=job_id)
+
+
+@app.post("/optimize", response_model=JobStartResponse)
+def start_optimize(request: OptimizeRequest) -> JobStartResponse:
+    """Start an optimize job; stream trials, scorings, and steps via SSE."""
+    try:
+        experiment, examples, metrics = build_experiment(
+            project=request.project,
+            program=request.program,
+            prompt=request.prompt,
+            model=request.model,
+            examples=request.examples,
+            metrics=request.metrics,
+        )
+        config = _job_config(
+            request,
+            kind="optimize",
+            metrics=request.metrics,
+            steps=request.steps,
+            proposer_model=request.proposer_model,
+        )
+    except ProjectValidationError as exc:
+        raise _validation_error(exc) from exc
+
+    assert metrics is not None
+    try:
+        job_id = jobs.start_optimize_job(
+            config=config,
+            experiment=experiment,
+            examples=examples,
+            metrics=metrics,
+            workers=request.workers,
+            steps=request.steps,
+            proposer_model=request.proposer_model,
+        )
+    except jobs.ConflictError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc
+
+    return JobStartResponse(job_id=job_id)
+
+
+@app.get("/jobs/{job_id}/events")
+async def job_events(job_id: str) -> StreamingResponse:
+    """Server-sent events for one job until it completes or errors."""
+    try:
+        jobs.get_job(job_id)
+    except jobs.JobNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="job not found") from exc
+
+    return StreamingResponse(
+        jobs.stream_job_events(job_id),
+        media_type="text/event-stream",
+    )

promptuna_server-1.24.0/src/promptuna_server/schemas.py

@@ -0,0 +1,50 @@
+"""Pydantic request and response models for the HTTP API."""
+
+from pydantic import BaseModel, Field
+
+
+class JobStartResponse(BaseModel):
+    """Response body returned when a job is accepted."""
+
+    job_id: str
+
+
+class ProjectCatalogResponse(BaseModel):
+    """Name lists for one on-disk project."""
+
+    name: str
+    programs: list[str]
+    metrics: list[str]
+    prompts: list[str]
+    datasets: list[str]
+
+
+class CatalogResponse(BaseModel):
+    """Workspace catalog for building job request selectors."""
+
+    projects_root: str
+    projects: list[ProjectCatalogResponse]
+
+
+class RunRequest(BaseModel):
+    """Start a run job over a project-local program and dataset."""
+
+    project: str
+    program: str
+    prompt: str
+    model: str
+    examples: str
+    workers: int = Field(default=1, ge=1)
+
+
+class EvaluateRequest(RunRequest):
+    """Start an evaluate job with one or more project-local metrics."""
+
+    metrics: list[str] = Field(min_length=1)
+
+
+class OptimizeRequest(EvaluateRequest):
+    """Start an optimize job with a proposer budget."""
+
+    steps: int = Field(ge=0)
+    proposer_model: str