API Reference for training-svc¶

@router.post("/train/lora")
async def train_lora(
    request: LoraTrainingRequest,
    background_tasks: BackgroundTasks,
) -> JSONResponse:
    """Dispatch a QLoRA training job as a background task.

    Args:
        request: LoRA training parameters — session_id is required.
        background_tasks: FastAPI background task runner.

    Returns:
        JSONResponse with job_id and status="queued".

    Example:
        >>> body = {"session_id": "s-1", "task_type": "code-gen", "epochs": 3}
        >>> response = client.post("/train/lora", json=body)
        >>> response.status_code
        200
        >>> response.json()["status"]
        'queued'
    """
    job_id = str(uuid.uuid4())
    adapter_id = request.adapter_id or str(uuid.uuid4())
    _validate_adapter_id(adapter_id)

    with _JOB_STORE_LOCK:
        JOB_STORE[job_id] = JobStatus(
            job_id=job_id,
            status="queued",
            adapter_id=adapter_id,
        )

    background_tasks.add_task(
        _run_training_job,
        job_id,
        request.session_id,
        adapter_id,
        request.task_type,
        request.rank,
        request.epochs,
        request.learning_rate,
    )

    return JSONResponse(content={"job_id": job_id, "status": "queued"}, status_code=200)

@router.post("/train/hypernetwork")
async def train_hypernetwork(
    request: HypernetworkTrainingRequest,
    background_tasks: BackgroundTasks,
) -> JSONResponse:
    """Dispatch a hypernetwork adapter generation job as a background task.

    Accepts a trajectory, runs it through the pre-trained hypernetwork in a
    single forward pass, saves the adapter in PEFT format, and returns a
    job_id for status polling via GET /jobs/{job_id}.

    Args:
        request: Hypernetwork training parameters including task_type and
            trajectory_ids (uses first trajectory_id).
        background_tasks: FastAPI background task runner.

    Returns:
        JSONResponse with job_id and status="queued".

    Raises:
        HTTPException: 422 if trajectory_ids is empty.

    Example:
        >>> body = {"task_type": "gen", "trajectory_ids": ["t-1"]}
        >>> response = client.post("/train/hypernetwork", json=body)
        >>> response.status_code
        200
        >>> response.json()["status"]
        'queued'
    """
    if not request.trajectory_ids:
        raise HTTPException(
            status_code=422,
            detail="trajectory_ids must not be empty.",
        )

    job_id = str(uuid.uuid4())
    # Assign adapter_id at creation time so GET /jobs/{id} returns it immediately
    adapter_id = str(uuid.uuid4())

    with _JOB_STORE_LOCK:
        JOB_STORE[job_id] = JobStatus(
            job_id=job_id,
            status="queued",
            adapter_id=adapter_id,
        )

    background_tasks.add_task(
        _run_hypernetwork_job,
        job_id,
        adapter_id,
        request.trajectory_ids[0],
        request.task_type,
    )

    return JSONResponse(content={"job_id": job_id, "status": "queued"}, status_code=200)

@router.get("/jobs/{job_id}")
async def get_job_status(job_id: str) -> JSONResponse:
    """Get training job status.

    Args:
        job_id: Unique identifier for the training job.

    Returns:
        JSONResponse with job_id, status, adapter_id, and optional error.

    Raises:
        HTTPException: 404 if job_id not found.

    Example:
        >>> response = client.get("/jobs/job-123")
        >>> response.status_code
        404
    """
    with _JOB_STORE_LOCK:
        job = JOB_STORE.get(job_id)
    if job is None:
        raise HTTPException(status_code=404, detail=f"Job {job_id} not found")

    return JSONResponse(
        content={
            "job_id": job.job_id,
            "status": job.status,
            "adapter_id": job.adapter_id,
            "error": job.error,
        },
        status_code=200,
    )