{
"openapi": "3.1.0",
"info": {
"title": "Fastino Training and Inference API",
"version": "2.0.0",
"description": "Public Fastino training and inference operations documented at https://docs.fastino.ai."
},
"servers": [
{
"url": "https://api.fastino.ai",
"description": "Production"
}
],
"paths": {
"/v1/chat/completions": {
"post": {
"description": "OpenAI-compatible chat completions endpoint.\n\nThin shell over :func:`services.inference.adapters.openai_chat.run_chat_completion`.\nThe adapter handles LLM-passthrough vs Fastino-task dispatch, SSE\nrendering with ``...`` folding for reasoning models,\ntool-call deltas, finish-reason mapping, persistence, and error\nmapping. The router keeps only HTTP-shaped concerns: route\ndeclaration, auth, rate limiting.\n\nArgs:\n body: Validated :class:`ChatCompletionRequest`.\n request: FastAPI request (forwarded so the adapter can read\n API-key billing context out of ``request.state`` for\n streaming responses).\n auth: Authenticated request context.\n\nReturns:\n :class:`ChatCompletionResponse` for non-streaming, or a\n :class:`StreamingResponse` of ``chat.completion.chunk`` SSE\n events terminated by ``data: [DONE]`` when ``body.stream``\n is true.",
"operationId": "chat_completions_v1_chat_completions_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionResponse"
}
},
"text/event-stream": {
"example": "data: {\"id\":\"chatcmpl-abc\",\"object\":\"chat.completion.chunk\",\"created\":0,\"model\":\"deepseek-ai/DeepSeek-V4-Flash\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hi\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-abc\",\"object\":\"chat.completion.chunk\",\"created\":0,\"model\":\"deepseek-ai/DeepSeek-V4-Flash\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":1,\"completion_tokens\":1,\"total_tokens\":2}}\n\ndata: [DONE]\n\n",
"schema": {
"description": "OpenAI-compatible chat completion streaming chunk.\n\n One of these is JSON-serialized into each ``data: {...}\n\n`` SSE event\n emitted by the chat completions handler when ``stream=true``. The stream\n is terminated by a literal ``data: [DONE]\n\n`` sentinel that does not\n follow this schema.\n\n ``x_pioneer`` mirrors the field on :class:`ChatCompletionResponse` and is\n populated only on the terminal chunk (the one carrying ``finish_reason``)\n when persistence ran. Intermediate chunks set it to ``None`` so SDK\n clients can wait for the terminal frame before reading the id rather\n than racing the early text deltas.\n ",
"properties": {
"choices": {
"items": {
"description": "One choice slot inside a streaming chunk.",
"properties": {
"delta": {
"description": "Incremental delta payload inside a streaming chunk's choice.\n\nThe OpenAI Chat Completions chunk schema (``ChoiceDelta`` in the\nopenai-python SDK) defines ``content``, ``function_call``,\n``refusal``, ``role``, and ``tool_calls`` \u2014 there is no spec slot\nfor reasoning. Fastino can expose the de facto industry extension\n(vLLM, DeepSeek, LiteLLM) on\n``reasoning_content`` for callers that opt in with existing\n``reasoning`` visibility controls (``exclude=false`` or\n``display=summarized``), mirroring Fastino's\nown input path at\n:func:`services.inference.providers.openai_compat.OpenAICompatProvider._chat_delta_to_events`\n(which already reads ``delta.reasoning_content`` from those same\nupstream providers). Stock OpenAI-compatible consumers receive no\nreasoning field by default so model scratchpad text is not rendered\nas assistant output. The renderer contract lives on\n:class:`~services.inference.adapters.openai_chat._ChatStreamRenderer`.",
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content"
},
"reasoning_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reasoning Content"
},
"tool_calls": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
}
},
"title": "ChatCompletionStreamDelta",
"type": "object"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason"
},
"index": {
"default": 0,
"title": "Index",
"type": "integer"
}
},
"title": "ChatCompletionStreamChoice",
"type": "object"
},
"title": "Choices",
"type": "array"
},
"created": {
"title": "Created",
"type": "integer"
},
"id": {
"title": "Id",
"type": "string"
},
"model": {
"title": "Model",
"type": "string"
},
"object": {
"default": "chat.completion.chunk",
"title": "Object",
"type": "string"
},
"usage": {
"anyOf": [
{
"description": "Token usage statistics.\n\n``prompt_tokens`` follows the upstream wire contract \u2014 *includes* every\ninput class (non-cached, cache read, and cache write). The breakdown is\nexposed under ``prompt_tokens_details`` so consumers can attribute the\ncached-read and cache-write subsets. Cache-aware billing on the brain\nside reads the canonical ``InferenceUsage`` fields directly, not this\nwire payload.",
"properties": {
"completion_tokens": {
"default": 0,
"title": "Completion Tokens",
"type": "integer"
},
"prompt_tokens": {
"default": 0,
"title": "Prompt Tokens",
"type": "integer"
},
"prompt_tokens_details": {
"anyOf": [
{
"description": "Per-input-class breakdown for OpenAI-shape usage payloads.\n\nMirrors OpenAI's ``prompt_tokens_details`` block and the industry\ncache-creation extension so clients reading\n``usage.prompt_tokens_details.cached_tokens`` /\n``cache_write_tokens`` keep working when Fastino relays a cache-aware\nupstream response. Both counts are subsets of ``prompt_tokens`` on the\nwire \u2014 that's the upstream contract Fastino relays faithfully.\n\nAttributes:\n cached_tokens: Input tokens served from the upstream prompt cache\n (cache read).\n cache_write_tokens: Input tokens written into the upstream prompt\n cache (cache creation). ``0`` for upstreams that bill writes\n as plain input (OpenAI, vLLM).",
"properties": {
"cache_write_tokens": {
"default": 0,
"title": "Cache Write Tokens",
"type": "integer"
},
"cached_tokens": {
"default": 0,
"title": "Cached Tokens",
"type": "integer"
}
},
"title": "PromptTokensDetails",
"type": "object"
},
{
"type": "null"
}
]
},
"total_tokens": {
"default": 0,
"title": "Total Tokens",
"type": "integer"
}
},
"title": "ChatCompletionUsage",
"type": "object"
},
{
"type": "null"
}
]
},
"x_pioneer": {
"anyOf": [
{
"description": "Fastino-specific extension fields appended to OpenAI-compatible responses.\n\nOpenAI's API contract reserves the unprefixed top-level keys (``id``,\n``choices``, ``usage``, \u2026); custom data must live under a clearly\nnamespaced key. ``x_pioneer`` is that key.\n\nAttributes:\n inference_id: The Fastino-side identifier of the persisted\n ``inferences`` row associated with this completion. Present\n when persistence is enabled (``extra_body.store == True``)\n and the row was successfully recorded; ``None`` for ad-hoc\n requests that opted out of persistence. The frontend uses\n this to poll ``GET /inferences/{id}`` for asynchronous\n judge results without coupling the inference response\n latency to the judge.\n routed_model: Backend catalog model selected by a router project\n (for example ``pioneer/auto``). ``None`` when the request\n was not routed or the routed model matches the requested id.\n savings: Routed-vs-frontier per-1M-token savings rate diff (same\n wire shape as the Anthropic ``pioneer_savings`` extension). The\n Codex routing-savings hook multiplies these rates by per-turn\n token usage to surface cumulative money saved. ``None`` when the\n request was not routed below the frontier reference model.",
"properties": {
"inference_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Inference Id"
},
"routed_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Routed Model"
},
"savings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Savings"
}
},
"title": "PioneerExtension",
"type": "object"
},
{
"type": "null"
}
]
}
},
"required": [
"model",
"choices"
],
"title": "ChatCompletionStreamChunk",
"type": "object"
}
}
},
"description": "Chat completion. Returns ``application/json`` (``ChatCompletionResponse``) by default, or ``text/event-stream`` of ``ChatCompletionStreamChunk`` events terminated by ``data: [DONE]`` when ``stream=true``."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Chat Completions",
"tags": [
"openai-compat"
]
}
},
"/v1/gliner-2": {
"post": {
"description": "Process text using GLiNER-2 base model via InferenceService.\n\n``task`` is optional \u2014 when omitted the unified schema path is used.\nLegacy task names are still accepted but deprecated.",
"operationId": "gliner2_process_gliner_2_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GlinerRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GlinerResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Gliner2 Process",
"tags": [
"gliner"
]
}
},
"/v1/gliner-2/async": {
"post": {
"description": "Submit large GLiNER-2 request for async processing.\n\nUse this endpoint when processing >1M tokens that would exceed\nthe 30-second timeout. Returns immediately with a job_id.\nPoll GET /gliner-2/jobs/{job_id} to retrieve results.\n\nArgs:\n request: AsyncGlinerRequest with task, text, schema\n http_request: FastAPI request object\n auth: Authentication result\n\nReturns:\n 202 Accepted with job_id for polling",
"operationId": "gliner2_async_gliner_2_async_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncGlinerRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncGlinerResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Gliner2 Async",
"tags": [
"gliner"
]
}
},
"/v1/gliner-2/jobs/{job_id}": {
"get": {
"description": "Get status and result of an async GLiNER-2 job.\n\nReturns:\n- 200 with status=\"complete\" and result when done\n- 200 with status=\"processing\" while in progress\n- 200 with status=\"error\" and error message if failed\n- 404 if job not found or belongs to different user\n\nArgs:\n job_id: UUID of the job to check\n auth: Authentication result\n\nReturns:\n GlinerJobStatus with current status and result if complete",
"operationId": "gliner2_job_status_gliner_2_jobs_job_id_get",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GlinerJobStatus"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Gliner2 Job Status",
"tags": [
"gliner"
]
}
},
"/v1/inferences": {
"get": {
"description": "List inference history for the authenticated user.\n\nReturns all inference records across all model types (NER, classification,\nJSON extraction, decoder) sorted by most recent first.\n\nArgs:\n auth: Authentication result with user_id\n limit: Maximum number of records to return (default 100, max 500)\n offset: Number of records to skip for pagination\n model_id: Optional filter by model ID\n task: Optional filter by task type\n project_id: Optional filter by project ID\n training_job_id: Optional filter by training job ID\n latency_min/latency_max: Inclusive latency window in ms.\n llmaj_score_min/llmaj_score_max: Inclusive LLMAJ-score window\n in [0.0, 1.0].\n since: Optional inclusive lower bound on ``created_at`` (ISO 8601).\n until: Optional exclusive upper bound on ``created_at`` (ISO 8601).\n\nReturns:\n InferenceListResponse with paginated inference records.\n\nRaises:\n HTTPException: 422 when ``min`` is greater than its paired\n ``max`` \u2014 returning an empty page would silently mask the\n caller's misordered query.",
"operationId": "list_inference_history_inferences_get",
"parameters": [
{
"description": "Maximum records to return",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 100,
"description": "Maximum records to return",
"maximum": 500,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Number of records to skip",
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"description": "Number of records to skip",
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"description": "Filter by model ID",
"in": "query",
"name": "model_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by model ID",
"title": "Model Id"
}
},
{
"description": "Filter by task type",
"in": "query",
"name": "task",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by task type",
"title": "Task"
}
},
{
"description": "Filter by project ID",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by project ID",
"title": "Project Id"
}
},
{
"description": "Filter by training job ID",
"in": "query",
"name": "training_job_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by training job ID",
"title": "Training Job Id"
}
},
{
"description": "Minimum latency in ms (must be >= 0).",
"in": "query",
"name": "latency_min",
"required": false,
"schema": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Minimum latency in ms (must be >= 0).",
"title": "Latency Min"
}
},
{
"description": "Maximum latency in ms (must be >= 0).",
"in": "query",
"name": "latency_max",
"required": false,
"schema": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Maximum latency in ms (must be >= 0).",
"title": "Latency Max"
}
},
{
"description": "Minimum LLM-as-Judge score in [0.0, 1.0].",
"in": "query",
"name": "llmaj_score_min",
"required": false,
"schema": {
"anyOf": [
{
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Minimum LLM-as-Judge score in [0.0, 1.0].",
"title": "Llmaj Score Min"
}
},
{
"description": "Maximum LLM-as-Judge score in [0.0, 1.0].",
"in": "query",
"name": "llmaj_score_max",
"required": false,
"schema": {
"anyOf": [
{
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Maximum LLM-as-Judge score in [0.0, 1.0].",
"title": "Llmaj Score Max"
}
},
{
"description": "Inclusive lower bound on created_at (ISO 8601, UTC).",
"in": "query",
"name": "since",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Inclusive lower bound on created_at (ISO 8601, UTC).",
"title": "Since"
}
},
{
"description": "Exclusive upper bound on created_at (ISO 8601, UTC).",
"in": "query",
"name": "until",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Exclusive upper bound on created_at (ISO 8601, UTC).",
"title": "Until"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferenceListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"description": "Inference history dependency is temporarily unavailable."
}
},
"summary": "List Inference History",
"tags": [
"inference-history"
]
}
},
"/v1/inferences/{inference_id}": {
"get": {
"description": "Get a single inference record by ID.\n\nArgs:\n inference_id: The inference record UUID\n auth: Authentication result with user_id\n\nReturns:\n InferenceRecord with full details\n\nRaises:\n HTTPException: 404 if inference not found or outside the caller's team",
"operationId": "get_inference_detail_inferences_inference_id_get",
"parameters": [
{
"in": "path",
"name": "inference_id",
"required": true,
"schema": {
"title": "Inference Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferenceRecord"
}
}
},
"description": "Successful Response"
},
"404": {
"description": "Inference not found."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"description": "Inference history dependency is temporarily unavailable."
}
},
"summary": "Get Inference Detail",
"tags": [
"inference-history"
]
}
},
"/v1/inferences/{inference_id}/feedback": {
"get": {
"description": "Get human feedback for a specific inference.\n\nArgs:\n inference_id: The inference record UUID to look up.\n auth: Authentication result with user_id.\n\nReturns:\n InferenceFeedbackResponse with the stored feedback.\n\nRaises:\n HTTPException: 404 if inference not found or no feedback submitted.",
"operationId": "get_inference_feedback_inferences_inference_id_feedback_get",
"parameters": [
{
"in": "path",
"name": "inference_id",
"required": true,
"schema": {
"title": "Inference Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferenceFeedbackResponse"
}
}
},
"description": "Successful Response"
},
"404": {
"description": "Feedback not found."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"503": {
"description": "Inference history dependency is temporarily unavailable."
}
},
"summary": "Get Inference Feedback",
"tags": [
"inference-history"
]
},
"post": {
"description": "Submit human feedback on a specific inference.\n\nMarks an inference as correct or incorrect. When marking as incorrect,\nthe expected output must be provided for downstream training data curation.\n\nArgs:\n inference_id: The inference record UUID to annotate.\n request: Feedback payload with verdict, optional corrected output, and notes.\n auth: Authentication result with user_id.\n\nReturns:\n InferenceFeedbackResponse confirming the stored feedback.\n\nRaises:\n HTTPException: 404 if inference not found or outside the caller's team.",
"operationId": "submit_inference_feedback_inferences_inference_id_feedback_post",
"parameters": [
{
"in": "path",
"name": "inference_id",
"required": true,
"schema": {
"title": "Inference Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferenceFeedbackRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferenceFeedbackResponse"
}
}
},
"description": "Successful Response"
},
"404": {
"description": "Inference not found."
},
"422": {
"description": "Invalid feedback payload."
},
"503": {
"description": "Inference history dependency is temporarily unavailable."
}
},
"summary": "Submit Inference Feedback",
"tags": [
"inference-history"
]
}
},
"/v1/messages": {
"post": {
"description": "Anthropic-compatible messages endpoint.\n\nThin shell over :func:`services.inference.adapters.anthropic_messages.run_messages`.\nThe adapter handles content-block translation, LLM-passthrough vs\nFastino-task dispatch, SSE rendering, persistence, and error\nmapping. The router keeps only HTTP-shaped concerns: route\ndeclaration, auth, rate limiting.\n\nArgs:\n body: Validated :class:`AnthropicMessagesRequest`.\n request: FastAPI request (forwarded so the adapter can read\n API-key billing context out of ``request.state`` for\n streaming responses).\n auth: Authenticated request context.\n\nReturns:\n :class:`AnthropicMessagesResponse` for non-streaming, or a\n :class:`StreamingResponse` of Anthropic SSE events when\n ``body.stream`` is true.",
"operationId": "messages_v1_messages_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnthropicMessagesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnthropicMessagesResponse"
}
}
},
"description": "Non-streaming Anthropic Messages response. When the request sets ``stream=true`` the server emits an Anthropic-shaped SSE event stream over ``text/event-stream`` instead; that stream shape is documented in the Anthropic Messages API reference."
},
"422": {
"content": {
"application/json": {
"schema": {
"description": "OpenAI envelope unless the request sends `anthropic-version`, in which case the Anthropic `{type: error, error: {type, message}}` body is returned.",
"oneOf": [
{
"$ref": "#/components/schemas/HTTPValidationError"
},
{
"$ref": "#/components/schemas/AnthropicError"
}
]
}
}
},
"description": "Validation Error"
}
},
"summary": "Messages",
"tags": [
"anthropic-compat"
]
}
},
"/v1/models": {
"get": {
"description": "List available Anthropic-compatible models.\n\nAuthentication is optional. Anonymous callers receive the public runtime\ncatalog; authenticated callers also receive their user-scoped decoder\nfine-tunes.\n\nArgs:\n limit: Maximum number of models to return. Omit to return the full\n assembled catalog.\n before_id: Cursor for paginating backward.\n after_id: Cursor for paginating forward.\n client_version: Optional Codex/OpenAI client version hint.\n auth: Optional authentication result.\n\nReturns:\n Combined Anthropic-compatible and Codex/OpenAI-compatible model catalog.\n\nRaises:\n HTTPException: If both cursor parameters are provided.",
"operationId": "list_models_v1_models_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"anyOf": [
{
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Limit"
}
},
{
"in": "query",
"name": "before_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Before Id"
}
},
{
"in": "query",
"name": "after_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "After Id"
}
},
{
"in": "query",
"name": "client_version",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Client Version"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [],
"summary": "List Models",
"tags": [
"anthropic-compat"
]
}
},
"/v1/responses": {
"post": {
"description": "OpenAI-compatible Responses API endpoint.\n\nThin shell over :func:`services.inference.adapters.openai_responses.run_responses`.\nThe adapter handles input-item to chat-message translation,\nLLM-passthrough vs Fastino-task dispatch, SSE rendering,\ntool-call serialisation, persistence, and error mapping. The\nrouter keeps only HTTP-shaped concerns: route declaration, auth,\nrate limiting.\n\nArgs:\n body: Validated :class:`ResponsesRequest`.\n request: FastAPI request (forwarded so the adapter can read\n API-key billing context out of ``request.state`` for\n streaming responses).\n response: Response whose headers carry the deprecation and\n router-tip signals.\n auth: Authenticated request context.\n\nReturns:\n JSON response payload or :class:`StreamingResponse` SSE stream\n in Responses API format.",
"operationId": "responses_v1_responses_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Responses",
"tags": [
"openai-compat"
]
}
},
"/v1/training-jobs": {
"post": {
"description": "Create a new training job.\n\nThe provider is resolved from the registry based on\n``(base_model, training_type)``.\n\nArgs:\n request: Incoming FastAPI request (required by SlowAPI key function).\n training_request: Training configuration with dataset references and base_model.\n auth: Authenticated user context.",
"operationId": "create_training_job_training_jobs_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingJobCreate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingJobResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Training Job",
"tags": [
"training-jobs"
]
},
"get": {
"description": "List training jobs for the authenticated user.\n\nSupports pagination via ``limit`` and ``offset`` query parameters.\nOptionally filter by status (requested, running, complete, deployed, errored).",
"operationId": "list_training_jobs_training_jobs_get",
"parameters": [
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status"
}
},
{
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project Id"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 200,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingJobListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Training Jobs",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}": {
"delete": {
"description": "Delete a training job and associated checkpoints.",
"operationId": "delete_training_job_training_jobs_job_id_delete",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteTrainingJobResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete Training Job",
"tags": [
"training-jobs"
]
},
"get": {
"description": "Get a training job by ID if it is visible to the caller's team.\n\nRead visibility matches the other ``training-jobs/{job_id}`` read routes\nthat already use ``_get_visible_job`` (logs, checkpoints, download): a\njob on a team-visible project, or a project-less shared job, is\nreturned even when the caller is not the creator. Mutating routes keep\ntheir own owner-scoped service calls.",
"operationId": "get_training_job_training_jobs_job_id_get",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingJobResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Training Job",
"tags": [
"training-jobs"
]
},
"patch": {
"description": "Patch a training job. Currently exposes only ``project_id``.\n\nDelegates to :func:`services.projects.movement.assign_resource_to_project`\nwhich owns the visibility check, target-project gating, and the\nservice-role ``UPDATE``. Send ``project_id: null`` to unassign the job\nfrom its project.\n\nMovement is **label-only**: only ``training_jobs.project_id`` changes.\nDependent rows that carry their own ``project_id`` (``deployments``,\n``inferences``, ``project_evaluation_runs``) are intentionally not cascaded.\nCallers needing aggregate-model movement must update dependents\nexplicitly.",
"operationId": "update_training_job_training_jobs_job_id_patch",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingJobUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateResourceProjectResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Training Job",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/billing": {
"get": {
"description": "Get the billing outcome for a specific training job, by job ID.\n\nCloses the API gap in ENG-6131: reports whether a job was billed and,\nif so, for how much and how long, so a billing-correctness fix like\nENG-6068 can be verified live without direct database access. Read\nvisibility matches ``get_training_job`` and the other\n``training-jobs/{job_id}`` read routes.",
"operationId": "get_training_job_billing_training_jobs_job_id_billing_get",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingJobBillingResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Training Job Billing",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/checkpoints": {
"get": {
"description": "List all checkpoints for a training job visible to the caller's team.",
"operationId": "list_training_job_checkpoints_training_jobs_job_id_checkpoints_get",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckpointListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Training Job Checkpoints",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/checkpoints/{checkpoint_id}/deploy": {
"post": {
"description": "Deploy a specific checkpoint to the Multi-Model Endpoint.",
"operationId": "deploy_checkpoint_to_mme_training_jobs_job_id_checkpoints_checkpoint_id_deploy_post",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
},
{
"in": "path",
"name": "checkpoint_id",
"required": true,
"schema": {
"title": "Checkpoint Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeployCheckpointResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Deploy Checkpoint To Mme",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/deployments": {
"get": {
"description": "Deprecated. Returns deployments that reference the given training job.\n\nArgs:\n job_id: Training job ID.\n auth: Authenticated user.\n\nReturns:\n DeploymentHistoryResponse with deprecation headers.",
"operationId": "get_training_job_deployments_training_jobs_job_id_deployments_get",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"format": "uuid",
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeploymentHistoryResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "[Deprecated] Get deployments for a training job -- use /projects/{project_id}/deployments",
"tags": [
"deprecated"
]
}
},
"/v1/training-jobs/{job_id}/download": {
"get": {
"description": "Generate a presigned S3 URL to download a trained model.",
"operationId": "download_trained_model_training_jobs_job_id_download_get",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelDownloadResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get download URL for trained model",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/logs": {
"get": {
"description": "Get training output logs (stdout/stderr) for a specific job.",
"operationId": "get_training_job_logs_training_jobs_job_id_logs_get",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingLogsResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Training Job Logs",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/model-name": {
"patch": {
"description": "Update the model_name for a training job.\n\nThin wrapper: visibility scoping, validation, the UPDATE, and the\nactivity-event side effect all live in\n:meth:`TrainingJobService.update_model_name`. The router only owns\nHTTP concerns (status codes, request/response shaping) per\n``brain/CLAUDE.md``.",
"operationId": "update_training_job_model_name_training_jobs_job_id_model_name_patch",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateModelNameRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateModelNameResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Training Job Model Name",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/push-to-hub": {
"post": {
"description": "Push a completed training job's model to HuggingFace Hub.\n\nArgs:\n job_id: Training job UUID.\n request: Target repo, token, and commit metadata.\n auth: Authenticated caller admitted by the training-jobs rollout.\n\nReturns:\n The hub push outcome.\n\nRaises:\n HTTPException: 400/403/404/409/500 for validation, permission,\n lookup, conflict, and upload failures.",
"operationId": "push_training_job_to_huggingface_training_jobs_job_id_push_to_hub_post",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HuggingFacePushModelRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PushModelToHubResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Push Training Job To Huggingface",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/stop": {
"post": {
"description": "Stop a running training job.",
"operationId": "stop_training_job_training_jobs_job_id_stop_post",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/StopJobRequest"
},
{
"type": "null"
}
],
"title": "Body"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StopJobResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Stop Training Job",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/sync": {
"post": {
"description": "Sync training job status from the provider to the database.",
"operationId": "sync_training_job_status_training_jobs_job_id_sync_post",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrainingJobResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Sync Training Job Status",
"tags": [
"training-jobs"
]
}
},
"/v1/training-jobs/{job_id}/terminate": {
"post": {
"description": "Terminate a training job and delete all artifacts.\n\nStops the provider job if running, deletes all checkpoints, and marks\nthe job as terminated. This operation is irreversible.",
"operationId": "terminate_training_job_training_jobs_job_id_terminate_post",
"parameters": [
{
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerminateJobResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Terminate Training Job",
"tags": [
"training-jobs"
]
}
},
"/v1/datasets": {
"get": {
"description": "Lists visible datasets.",
"operationId": "list_datasets_datasets_get",
"parameters": [
{
"in": "query",
"name": "include_all_versions",
"required": false,
"schema": {
"default": false,
"title": "Include All Versions",
"type": "boolean"
}
},
{
"description": "Filter by project ID. For a real project, orphan (no-project) datasets are included only when include_orphans=True. Omitted or the 'default' sentinel always includes orphans.",
"in": "query",
"name": "project_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by project ID. For a real project, orphan (no-project) datasets are included only when include_orphans=True. Omitted or the 'default' sentinel always includes orphans.",
"title": "Project Id"
}
},
{
"description": "When true, include the caller's own failed datasets (status='failed'). Defaults to false so the UI never renders broken-but-clickable records that 404 on preview/analyze. The result set is always scoped to the authenticated user \u2014 this flag does NOT grant cross-user visibility, so passing true is safe for any authenticated caller. Failed rows remain in the database for support / debugging; their original upload is preserved at raw_s3_key.",
"in": "query",
"name": "include_failed",
"required": false,
"schema": {
"default": false,
"description": "When true, include the caller's own failed datasets (status='failed'). Defaults to false so the UI never renders broken-but-clickable records that 404 on preview/analyze. The result set is always scoped to the authenticated user \u2014 this flag does NOT grant cross-user visibility, so passing true is safe for any authenticated caller. Failed rows remain in the database for support / debugging; their original upload is preserved at raw_s3_key.",
"title": "Include Failed",
"type": "boolean"
}
},
{
"description": "When true and project_id names a real project, also include the caller's own orphan (no-project) datasets alongside the project's own rows. Ignored when project_id is omitted or is the 'default' sentinel, where orphans are always included regardless. Defaults to false so an ordinary project-scoped list stays scoped to the project instead of being swamped by every one of the caller's orphans; set this explicitly from surfaces that deliberately want orphans folded in, e.g. the MLE agent's dataset picker (ENG-6077).",
"in": "query",
"name": "include_orphans",
"required": false,
"schema": {
"default": false,
"description": "When true and project_id names a real project, also include the caller's own orphan (no-project) datasets alongside the project's own rows. Ignored when project_id is omitted or is the 'default' sentinel, where orphans are always included regardless. Defaults to false so an ordinary project-scoped list stays scoped to the project instead of being swamped by every one of the caller's orphans; set this explicitly from surfaces that deliberately want orphans folded in, e.g. the MLE agent's dataset picker (ENG-6077).",
"title": "Include Orphans",
"type": "boolean"
}
},
{
"description": "Maximum datasets to return, newest first, after collapsing to the latest version per name. Defaults to and is bounded at 200 (oversize requests are rejected, matching /v1/training-jobs and /projects/{id}/evaluation-runs). Callers that need the full set page with limit/offset (ENG-7085): the frontend datasets tab and the sandbox dataset picker both loop until a short page rather than issuing one unbounded read.",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"anyOf": [
{
"maximum": 200,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 200,
"description": "Maximum datasets to return, newest first, after collapsing to the latest version per name. Defaults to and is bounded at 200 (oversize requests are rejected, matching /v1/training-jobs and /projects/{id}/evaluation-runs). Callers that need the full set page with limit/offset (ENG-7085): the frontend datasets tab and the sandbox dataset picker both loop until a short page rather than issuing one unbounded read.",
"title": "Limit"
}
},
{
"description": "Number of leading datasets to skip.",
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"description": "Number of leading datasets to skip.",
"minimum": 0,
"title": "Offset",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasetListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Datasets",
"tags": [
"datasets"
]
}
},
"/v1/datasets/upload/url": {
"post": {
"description": "Creates a reserved dataset row and presigned upload URL.",
"operationId": "get_upload_url_datasets_upload_url_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasetUploadUrlRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasetUploadUrlResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Upload Url",
"tags": [
"datasets"
]
}
},
"/v1/datasets/upload/process": {
"post": {
"description": "Queues processing for a reserved dataset upload.",
"operationId": "process_uploaded_dataset_datasets_upload_process_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasetUploadProcessRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasetResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Process Uploaded Dataset",
"tags": [
"datasets"
]
}
},
"/v1/datasets/{name}": {
"get": {
"description": "Lists all visible versions of a dataset.",
"operationId": "list_dataset_versions_datasets_name_get",
"parameters": [
{
"in": "path",
"name": "name",
"required": true,
"schema": {
"title": "Name",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasetVersionsResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Dataset Versions",
"tags": [
"datasets"
]
},
"delete": {
"description": "Soft-delete a dataset and all its versions.\n\nArgs:\n name: Dataset name. Legacy UUID lookups are still accepted and routed\n through the by-ID path for backwards compatibility.",
"operationId": "delete_dataset_datasets_name_delete",
"parameters": [
{
"in": "path",
"name": "name",
"required": true,
"schema": {
"title": "Name",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete Dataset",
"tags": [
"datasets"
]
}
}
},
"components": {
"schemas": {
"InferenceFeedbackResponse": {
"description": "Response after submitting human feedback.\n\nArgs:\n inference_id: The inference that was annotated.\n human_verdict: The stored verdict.\n human_feedback_at: Timestamp of the feedback submission.",
"properties": {
"human_feedback_at": {
"description": "When the feedback was submitted",
"format": "date-time",
"title": "Human Feedback At",
"type": "string"
},
"human_verdict": {
"description": "Stored human verdict",
"title": "Human Verdict",
"type": "string"
},
"inference_id": {
"description": "Inference ID that was annotated",
"title": "Inference Id",
"type": "string"
}
},
"required": [
"inference_id",
"human_verdict",
"human_feedback_at"
],
"title": "InferenceFeedbackResponse",
"type": "object"
},
"InferenceFeedbackRequest": {
"description": "Request to submit human feedback on a specific inference.\n\nArgs:\n verdict: Human judgment \u2014 correct or incorrect.\n corrected_output: Expected output when verdict is incorrect.\n notes: Optional free-text notes from the reviewer.",
"properties": {
"corrected_output": {
"anyOf": [
{},
{
"type": "null"
}
],
"description": "Expected output for incorrect verdicts (JSON structure matching task output)",
"title": "Corrected Output"
},
"notes": {
"anyOf": [
{
"maxLength": 5000,
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional reviewer notes",
"title": "Notes"
},
"verdict": {
"description": "Human judgment: 'correct' or 'incorrect'",
"enum": [
"correct",
"incorrect"
],
"title": "Verdict",
"type": "string"
}
},
"required": [
"verdict"
],
"title": "InferenceFeedbackRequest",
"type": "object"
},
"HTTPValidationError": {
"description": "OpenAI error envelope returned for request validation failures. Replaces FastAPI's default HTTPValidationError `{detail: [...]}`.",
"properties": {
"error": {
"properties": {
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Code"
},
"errors": {
"description": "Structured validation entries (location, type, line/column).",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Errors",
"type": "array"
},
"message": {
"title": "Message",
"type": "string"
},
"param": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Param"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"message",
"type",
"param",
"code"
],
"title": "Error",
"type": "object"
}
},
"required": [
"error"
],
"title": "HTTPValidationError",
"type": "object"
},
"InferenceRecord": {
"description": "Stored inference record from the database.\n\nAttributes:\n status: Inference outcome -- 'success' or 'failed'.\n error_type: Failure category when status is 'failed'.\n error_message: Error detail when status is 'failed'.",
"properties": {
"base_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "HuggingFace base model ID",
"title": "Base Model"
},
"cache_read_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Input tokens served from the provider prompt cache (cache hit).",
"title": "Cache Read Tokens"
},
"cache_write_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Input tokens written into the provider prompt cache (cache creation). Zero for providers that bill writes as plain input.",
"title": "Cache Write Tokens"
},
"created_at": {
"description": "When the inference was made",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Error detail when status is failed",
"title": "Error Message"
},
"error_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Failure category when status is failed (validation, timeout, model_not_ready, model_not_found, model_not_supported, capacity_exhausted, internal)",
"title": "Error Type"
},
"human_corrected_output": {
"anyOf": [
{},
{
"type": "null"
}
],
"description": "Expected output from human reviewer",
"title": "Human Corrected Output"
},
"human_feedback_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "When human feedback was submitted",
"title": "Human Feedback At"
},
"human_feedback_notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional reviewer notes",
"title": "Human Feedback Notes"
},
"human_verdict": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human reviewer verdict (correct/incorrect)",
"title": "Human Verdict"
},
"id": {
"description": "Unique inference ID",
"title": "Id",
"type": "string"
},
"input": {
"description": "Input text",
"title": "Input",
"type": "string"
},
"input_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Non-cached input/prompt tokens, sourced from the metered requests row. None when no billing row was recorded.",
"title": "Input Tokens"
},
"latency_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "End-to-end latency in milliseconds",
"title": "Latency Ms"
},
"llmaj_judged_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Timestamp when LLMAJ judgment was recorded; None until judged.",
"title": "Llmaj Judged At"
},
"llmaj_reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "LLMAJ judge reasoning/explanation; None until judged.",
"title": "Llmaj Reasoning"
},
"llmaj_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "LLMAJ judge confidence score in [0.0, 1.0]; None until judged.",
"title": "Llmaj Score"
},
"llmaj_verdict": {
"anyOf": [
{
"enum": [
"pass",
"fail",
"uncertain"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "LLMAJ judge verdict ('pass', 'fail', or 'uncertain'); None until judged.",
"title": "Llmaj Verdict"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Extensible metadata (e.g. LLM judge results)",
"title": "Metadata"
},
"model_id": {
"description": "Model ID used for inference",
"title": "Model Id",
"type": "string"
},
"model_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable model name",
"title": "Model Name"
},
"output": {
"anyOf": [
{},
{
"type": "null"
}
],
"description": "Inference output (JSON)",
"title": "Output"
},
"output_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Output/completion tokens, sourced from the metered requests row.",
"title": "Output Tokens"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Project ID the model belongs to",
"title": "Project Id"
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Inference provider (aws, modal, etc.). Rows predating a provider removal carry an 'archived_' label.",
"title": "Provider"
},
"source": {
"default": "api",
"description": "Source of the request (api or ui)",
"title": "Source",
"type": "string"
},
"status": {
"default": "success",
"description": "Inference status: success or failed",
"title": "Status",
"type": "string"
},
"task": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Task type (legacy; may be NULL for new inferences)",
"title": "Task"
},
"tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Token count",
"title": "Tokens"
},
"training_job_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Training job UUID that produced the model",
"title": "Training Job Id"
},
"ttft_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Streaming time to first visible output chunk in milliseconds; null for non-streaming calls and streams with no visible payload.",
"title": "Ttft Ms"
},
"user_id": {
"description": "User who made the inference",
"title": "User Id",
"type": "string"
}
},
"required": [
"id",
"user_id",
"model_id",
"input",
"created_at"
],
"title": "InferenceRecord",
"type": "object"
},
"InferenceListResponse": {
"description": "Response for listing inference history.",
"properties": {
"inferences": {
"description": "List of inference records",
"items": {
"$ref": "#/components/schemas/InferenceRecord"
},
"title": "Inferences",
"type": "array"
},
"limit": {
"description": "Page size limit",
"title": "Limit",
"type": "integer"
},
"offset": {
"description": "Current offset",
"title": "Offset",
"type": "integer"
},
"total": {
"description": "Total count of inferences matching filters",
"title": "Total",
"type": "integer"
}
},
"required": [
"inferences",
"total",
"limit",
"offset"
],
"title": "InferenceListResponse",
"type": "object"
},
"ResponsesRequest": {
"additionalProperties": true,
"description": "OpenAI-compatible Responses API request.\n\n``input`` accepts either a plain string (convenience shorthand used by the\nOpenAI SDK for simple text prompts) or a list of input items.",
"properties": {
"effort": {
"anyOf": [
{
"$ref": "#/components/schemas/RoutingEffort"
},
{
"type": "null"
}
],
"description": "Per-request routing-effort tier (low/medium/high/xhigh/max) for router models like ``pioneer/auto``. Overrides the router's stored policy for this request only; ignored for non-router models."
},
"extra_body": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extra Body"
},
"extra_headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Extra Headers"
},
"include": {
"items": {
"type": "string"
},
"title": "Include",
"type": "array"
},
"include_confidence": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Include Confidence"
},
"include_spans": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Include Spans"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
}
],
"title": "Input"
},
"instructions": {
"default": "",
"title": "Instructions",
"type": "string"
},
"max_output_tokens": {
"anyOf": [
{
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Output Tokens"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"model": {
"title": "Model",
"type": "string"
},
"models": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Per-request candidate-model subset the router may select between. Overrides the router's stored candidate set for this request only; ignored for non-router models.",
"title": "Models"
},
"parallel_tool_calls": {
"default": false,
"title": "Parallel Tool Calls",
"type": "boolean"
},
"previous_response_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Fastino inference ID or stored Responses wire ID to continue from. When present, Fastino reconstructs the prior turn from inference history and prepends it to the new input.",
"title": "Previous Response Id"
},
"prompt_cache_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prompt Cache Key"
},
"reasoning": {
"anyOf": [
{
"$ref": "#/components/schemas/ResponsesReasoningRequest"
},
{
"type": "null"
}
]
},
"service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Service Tier"
},
"store": {
"default": true,
"description": "Whether to store response state for turn-to-turn continuation. When true, Fastino preserves the response for previous_response_id replay, including available tool-call and reasoning context.",
"title": "Store",
"type": "boolean"
},
"stream": {
"default": false,
"title": "Stream",
"type": "boolean"
},
"task_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "**Deprecated.** Legacy task hint (``extract_entities`` / ``classify_text`` / ``extract_json`` / ``ner`` / ``schema``). The unified schema on ``text.format.schema`` disambiguates the task automatically. Submitting this field emits ``Deprecation: true`` and ``Sunset: `` headers on the response.",
"title": "Task Type"
},
"temperature": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Temperature"
},
"text": {
"anyOf": [
{
"$ref": "#/components/schemas/ResponsesTextRequest"
},
{
"type": "null"
}
]
},
"tool_choice": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": true,
"type": "object"
}
],
"default": "auto",
"title": "Tool Choice"
},
"tools": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tools",
"type": "array"
},
"top_p": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Top P"
}
},
"required": [
"model"
],
"title": "ResponsesRequest",
"type": "object"
},
"ResponsesTextRequest": {
"additionalProperties": true,
"description": "Responses text controls.",
"properties": {
"format": {
"anyOf": [
{
"$ref": "#/components/schemas/ResponsesTextFormatRequest"
},
{
"type": "null"
}
]
},
"verbosity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Verbosity"
}
},
"title": "ResponsesTextRequest",
"type": "object"
},
"ResponsesTextFormatRequest": {
"additionalProperties": true,
"description": "Structured-output controls for Responses text formatting.",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Schema"
},
"strict": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Strict"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
"title": "ResponsesTextFormatRequest",
"type": "object"
},
"ResponsesReasoningRequest": {
"additionalProperties": true,
"description": "Opt-in reasoning controls in OpenAI Responses format.",
"properties": {
"effort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional reasoning effort hint, such as 'low', 'medium', or 'high'.",
"title": "Effort"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Switch for enabling reasoning on capable models.",
"title": "Enabled"
},
"exclude": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "When supported by the upstream provider, exclude reasoning text from the response while still allowing the model to use reasoning.",
"title": "Exclude"
},
"summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional Responses-style reasoning summary mode.",
"title": "Summary"
}
},
"title": "ResponsesReasoningRequest",
"type": "object"
},
"RoutingEffort": {
"description": "Per-request routing-effort tier, ascending in cost and quality.\n\nSent by the caller as the ``effort`` param or as a ``model`` suffix. The\nper-router policy each tier used to map to is gone with the routers; the\ntier itself remains a request-level knob.",
"enum": [
"low",
"medium",
"high",
"xhigh",
"max"
],
"title": "RoutingEffort",
"type": "string"
},
"AnthropicError": {
"description": "Anthropic error envelope returned when the request includes `anthropic-version`. Distinct from the OpenAI `{error: {message, type, param, code}}` body.",
"properties": {
"error": {
"properties": {
"message": {
"title": "Message",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"message"
],
"title": "Error",
"type": "object"
},
"type": {
"enum": [
"error"
],
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"error"
],
"title": "AnthropicError",
"type": "object"
},
"AnthropicMessagesResponse": {
"description": "Anthropic Messages API response format.\n\n``pioneer_inference_id`` is a Fastino-only extension: the\n``inferences.id`` of the persisted row backing this completion. It mirrors\nthe ``x_pioneer.inference_id`` field on the OpenAI-compatible chat\ncompletion response so frontend playground clients can use the same\npoll-``GET /inferences/{id}``-for-judge-results round-trip on either\nsurface. ``None`` when persistence didn't run (e.g. ``store=false``).\n\n``pioneer_routed_model`` is the backend catalog model selected when the\nrequest used a router alias such as ``pioneer/auto``. ``None`` when no\nrouting occurred or the routed model matches the requested id.\n\n``pioneer_savings`` carries the per-1M-token savings rate diff of the routed\nmodel vs a fixed frontier reference (``baseline_model`` plus\n``rate_diff_per_mtok`` with ``input``/``output``/``cache_read``/\n``cache_write`` keys). The Claude Code cost hook multiplies it by per-turn\ntoken usage to show money saved. ``None`` when not routed to a cheaper model.",
"properties": {
"content": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Content",
"type": "array"
},
"id": {
"title": "Id",
"type": "string"
},
"model": {
"title": "Model",
"type": "string"
},
"pioneer_inference_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pioneer Inference Id"
},
"pioneer_routed_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pioneer Routed Model"
},
"pioneer_savings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Pioneer Savings"
},
"role": {
"default": "assistant",
"title": "Role",
"type": "string"
},
"stop_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "end_turn",
"title": "Stop Reason"
},
"stop_sequence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Stop Sequence"
},
"type": {
"default": "message",
"title": "Type",
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/AnthropicUsage"
}
},
"required": [
"id",
"content",
"model",
"usage"
],
"title": "AnthropicMessagesResponse",
"type": "object"
},
"AnthropicUsage": {
"description": "Usage statistics in Anthropic format.\n\n``input_tokens`` is Anthropic's non-cached input contract \u2014 cached\nreads / writes live in the separate ``cache_read_input_tokens`` /\n``cache_creation_input_tokens`` fields. Fastino mirrors the same\nshape on the ``/v1/messages`` wire so SDK consumers reading the\nfields directly stay correct.",
"properties": {
"cache_creation_input_tokens": {
"default": 0,
"title": "Cache Creation Input Tokens",
"type": "integer"
},
"cache_read_input_tokens": {
"default": 0,
"title": "Cache Read Input Tokens",
"type": "integer"
},
"input_tokens": {
"default": 0,
"title": "Input Tokens",
"type": "integer"
},
"output_tokens": {
"default": 0,
"title": "Output Tokens",
"type": "integer"
},
"server_tool_use": {
"anyOf": [
{
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Server Tool Use"
},
"service_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Service Tier"
},
"speed": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Speed"
},
"thinking_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Thinking Tokens"
}
},
"title": "AnthropicUsage",
"type": "object"
},
"AnthropicMessagesRequest": {
"description": "Anthropic Messages API request format.",
"properties": {
"cache_control": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Cache Control"
},
"effort": {
"anyOf": [
{
"$ref": "#/components/schemas/RoutingEffort"
},
{
"type": "null"
}
],
"description": "Per-request routing-effort tier (low/medium/high/xhigh/max) for router models like ``pioneer/auto``. Overrides the router's stored policy for this request only; ignored for non-router models."
},
"include_confidence": {
"default": true,
"title": "Include Confidence",
"type": "boolean"
},
"include_spans": {
"default": true,
"title": "Include Spans",
"type": "boolean"
},
"max_tokens": {
"default": 1024,
"maximum": 131072.0,
"minimum": 1.0,
"title": "Max Tokens",
"type": "integer"
},
"messages": {
"items": {
"$ref": "#/components/schemas/AnthropicMessage"
},
"minItems": 1,
"title": "Messages",
"type": "array"
},
"model": {
"title": "Model",
"type": "string"
},
"models": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Per-request candidate-model subset the router may select between. Overrides the router's stored candidate set for this request only; ignored for non-router models.",
"title": "Models"
},
"output_config": {
"anyOf": [
{
"$ref": "#/components/schemas/AnthropicOutputConfig"
},
{
"type": "null"
}
]
},
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Schema for the Fastino encoder. **Deprecated when supplied as a flat list** of entity labels; use the unified dict shape instead. Deprecated submissions emit ``Deprecation: true`` and ``Sunset: `` headers.",
"title": "Schema"
},
"speed": {
"anyOf": [
{
"enum": [
"standard",
"fast"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Anthropic inference speed mode. ``\"fast\"`` opts into high output-tokens-per-second inference on supported models (e.g. the latest Opus). Fastino forwards this only to the native Anthropic upstream (with the required ``fast-mode`` beta header); Bedrock and gateway routes ignore it.",
"title": "Speed"
},
"stop_sequences": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Stop Sequences"
},
"store": {
"default": true,
"title": "Store",
"type": "boolean"
},
"stream": {
"default": false,
"title": "Stream",
"type": "boolean"
},
"system": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"$ref": "#/components/schemas/SystemContentBlock"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "System"
},
"task_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "**Deprecated.** Legacy task hint. The unified schema disambiguates the task automatically. Submitting this field emits ``Deprecation: true`` and ``Sunset: `` headers.",
"title": "Task Type"
},
"temperature": {
"anyOf": [
{
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Temperature"
},
"thinking": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Opt-in Anthropic-style extended-thinking controls. Fastino does not enable thinking by default; send the Anthropic-native object: {'type': 'enabled', 'budget_tokens': N, 'display'?: 'summarized'|'omitted'} for manual mode, {'type': 'adaptive', 'effort'?: tier, 'display'?: ...} for adaptive mode (required on Opus 4.7+ / Mythos, recommended on Opus 4.6 / Sonnet 4.6), or {'type': 'disabled'} to turn thinking off on models that have it on by default. Fastino canonicalizes this into InferenceRequest.reasoning at the adapter boundary so the request routes correctly whether the upstream is Anthropic native, Bedrock, or the Vercel AI Gateway (which advertises the normalized ``reasoning`` field rather than ``thinking``). On models that require adaptive mode, Fastino auto-upgrades manual configs (mapping ``budget_tokens`` to the nearest ``effort`` tier) rather than letting the upstream return a 400.",
"title": "Thinking"
},
"tool_choice": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Tool Choice"
},
"tools": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools"
},
"top_k": {
"anyOf": [
{
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Top K"
},
"top_p": {
"anyOf": [
{
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Top P"
}
},
"required": [
"model",
"messages"
],
"title": "AnthropicMessagesRequest",
"type": "object"
},
"SystemContentBlock": {
"description": "A system content block in Anthropic format.",
"properties": {
"cache_control": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Cache Control"
},
"text": {
"default": "",
"title": "Text",
"type": "string"
},
"type": {
"default": "text",
"title": "Type",
"type": "string"
}
},
"title": "SystemContentBlock",
"type": "object"
},
"AnthropicOutputConfig": {
"additionalProperties": true,
"description": "Anthropic output configuration passed through supported providers.",
"properties": {
"effort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Effort"
},
"format": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Format"
},
"task_budget": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Task Budget"
}
},
"title": "AnthropicOutputConfig",
"type": "object"
},
"AnthropicMessage": {
"description": "A message in Anthropic format.\n\n``content`` accepts a plain string *or* a list of content blocks to support\nboth simple text and structured tool_use / tool_result payloads.",
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/ContentBlock"
},
{
"$ref": "#/components/schemas/ImageContentBlock"
},
{
"additionalProperties": true,
"type": "object"
}
]
},
"type": "array"
}
],
"title": "Content"
},
"role": {
"title": "Role",
"type": "string"
}
},
"required": [
"role",
"content"
],
"title": "AnthropicMessage",
"type": "object"
},
"ImageContentBlock": {
"description": "Anthropic image content block.",
"properties": {
"source": {
"$ref": "#/components/schemas/ImageSource"
},
"type": {
"const": "image",
"default": "image",
"title": "Type",
"type": "string"
}
},
"required": [
"source"
],
"title": "ImageContentBlock",
"type": "object"
},
"ImageSource": {
"description": "Anthropic image source (base64 or HTTPS URL).",
"properties": {
"data": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Data"
},
"media_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media Type"
},
"type": {
"enum": [
"base64",
"url"
],
"title": "Type",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
}
},
"required": [
"type"
],
"title": "ImageSource",
"type": "object"
},
"ContentBlock": {
"additionalProperties": true,
"description": "A content block in Anthropic format.\n\nSupports ``text``, ``tool_use``, and ``tool_result`` block types so that\ntool-calling round-trips work with Anthropic SDK clients.",
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Content"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"input": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Input"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Text"
},
"tool_use_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Use Id"
},
"type": {
"default": "text",
"title": "Type",
"type": "string"
}
},
"title": "ContentBlock",
"type": "object"
},
"GlinerJobStatus": {
"description": "Response from job status check.",
"properties": {
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"title": "Created At",
"type": "string"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result"
},
"status": {
"title": "Status",
"type": "string"
},
"token_usage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Token Usage"
}
},
"required": [
"job_id",
"status",
"created_at"
],
"title": "GlinerJobStatus",
"type": "object"
},
"AsyncGlinerResponse": {
"description": "Response from async job submission.",
"properties": {
"estimated_tokens": {
"title": "Estimated Tokens",
"type": "integer"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"message": {
"title": "Message",
"type": "string"
},
"status": {
"title": "Status",
"type": "string"
}
},
"required": [
"job_id",
"status",
"estimated_tokens",
"message"
],
"title": "AsyncGlinerResponse",
"type": "object"
},
"AsyncGlinerRequest": {
"description": "Request for async GLiNER-2 processing.",
"properties": {
"format_results": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Format Results"
},
"include_confidence": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Include Confidence"
},
"include_spans": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Include Spans"
},
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"additionalProperties": true,
"type": "object"
}
],
"description": "Extraction schema. The flat ``list[str]`` of entity labels is deprecated; use the unified dict shape (``entities`` / ``classifications`` / ``structures`` / ``relations``) for forward compatibility. Deprecated submissions emit ``Deprecation: true`` and ``Sunset: `` headers.",
"title": "Schema"
},
"task": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "**Deprecated** legacy task hint. One of: 'extract_entities', 'classify_text', 'extract_json', 'schema'. Omit for the unified GLiNER2 path. Submitting a legacy task value still succeeds but the response carries ``Deprecation: true`` and a ``Sunset`` header.",
"title": "Task"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"title": "Text"
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": 0.5,
"title": "Threshold"
}
},
"required": [
"text",
"schema"
],
"title": "AsyncGlinerRequest",
"type": "object"
},
"GlinerResponse": {
"description": "Response from GLiNER-2 processing.",
"properties": {
"result": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"items": {},
"type": "array"
}
],
"title": "Result"
},
"token_usage": {
"title": "Token Usage",
"type": "integer"
}
},
"required": [
"result",
"token_usage"
],
"title": "GlinerResponse",
"type": "object"
},
"GlinerRequest": {
"description": "Request for GLiNER-2 processing (sync).",
"properties": {
"format_results": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Format Results"
},
"include_confidence": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Include Confidence"
},
"include_spans": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Include Spans"
},
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"additionalProperties": true,
"type": "object"
}
],
"description": "Extraction schema. The flat ``list[str]`` of entity labels is deprecated; use the unified dict shape (``entities`` / ``classifications`` / ``structures`` / ``relations``) for forward compatibility. Deprecated submissions emit ``Deprecation: true`` and ``Sunset: `` headers.",
"title": "Schema"
},
"task": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "**Deprecated** legacy task hint. One of: 'extract_entities', 'classify_text', 'extract_json', 'schema'. Omit for the unified GLiNER2 path. Submitting a legacy task value still succeeds but the response carries ``Deprecation: true`` and a ``Sunset`` header.",
"title": "Task"
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"title": "Text"
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": 0.5,
"title": "Threshold"
}
},
"required": [
"text",
"schema"
],
"title": "GlinerRequest",
"type": "object"
},
"ChatCompletionResponse": {
"description": "OpenAI-compatible chat completion response.",
"properties": {
"choices": {
"items": {
"$ref": "#/components/schemas/ChatCompletionChoice"
},
"title": "Choices",
"type": "array"
},
"created": {
"title": "Created",
"type": "integer"
},
"id": {
"title": "Id",
"type": "string"
},
"model": {
"title": "Model",
"type": "string"
},
"object": {
"default": "chat.completion",
"title": "Object",
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/ChatCompletionUsage"
},
"x_pioneer": {
"anyOf": [
{
"$ref": "#/components/schemas/PioneerExtension"
},
{
"type": "null"
}
]
}
},
"required": [
"model",
"choices",
"usage"
],
"title": "ChatCompletionResponse",
"type": "object"
},
"PioneerExtension": {
"description": "Fastino-specific extension fields appended to OpenAI-compatible responses.\n\nOpenAI's API contract reserves the unprefixed top-level keys (``id``,\n``choices``, ``usage``, \u2026); custom data must live under a clearly\nnamespaced key. ``x_pioneer`` is that key.\n\nAttributes:\n inference_id: The Fastino-side identifier of the persisted\n ``inferences`` row associated with this completion. Present\n when persistence is enabled (``extra_body.store == True``)\n and the row was successfully recorded; ``None`` for ad-hoc\n requests that opted out of persistence. The frontend uses\n this to poll ``GET /inferences/{id}`` for asynchronous\n judge results without coupling the inference response\n latency to the judge.\n routed_model: Backend catalog model selected by a router project\n (for example ``pioneer/auto``). ``None`` when the request\n was not routed or the routed model matches the requested id.\n savings: Routed-vs-frontier per-1M-token savings rate diff (same\n wire shape as the Anthropic ``pioneer_savings`` extension). The\n Codex routing-savings hook multiplies these rates by per-turn\n token usage to surface cumulative money saved. ``None`` when the\n request was not routed below the frontier reference model.",
"properties": {
"inference_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Inference Id"
},
"routed_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Routed Model"
},
"savings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Savings"
}
},
"title": "PioneerExtension",
"type": "object"
},
"ChatCompletionUsage": {
"description": "Token usage statistics.\n\n``prompt_tokens`` follows the upstream wire contract \u2014 *includes* every\ninput class (non-cached, cache read, and cache write). The breakdown is\nexposed under ``prompt_tokens_details`` so consumers can attribute the\ncached-read and cache-write subsets. Cache-aware billing on the brain\nside reads the canonical ``InferenceUsage`` fields directly, not this\nwire payload.",
"properties": {
"completion_tokens": {
"default": 0,
"title": "Completion Tokens",
"type": "integer"
},
"prompt_tokens": {
"default": 0,
"title": "Prompt Tokens",
"type": "integer"
},
"prompt_tokens_details": {
"anyOf": [
{
"$ref": "#/components/schemas/PromptTokensDetails"
},
{
"type": "null"
}
]
},
"total_tokens": {
"default": 0,
"title": "Total Tokens",
"type": "integer"
}
},
"title": "ChatCompletionUsage",
"type": "object"
},
"PromptTokensDetails": {
"description": "Per-input-class breakdown for OpenAI-shape usage payloads.\n\nMirrors OpenAI's ``prompt_tokens_details`` block and the industry\ncache-creation extension so clients reading\n``usage.prompt_tokens_details.cached_tokens`` /\n``cache_write_tokens`` keep working when Fastino relays a cache-aware\nupstream response. Both counts are subsets of ``prompt_tokens`` on the\nwire \u2014 that's the upstream contract Fastino relays faithfully.\n\nAttributes:\n cached_tokens: Input tokens served from the upstream prompt cache\n (cache read).\n cache_write_tokens: Input tokens written into the upstream prompt\n cache (cache creation). ``0`` for upstreams that bill writes\n as plain input (OpenAI, vLLM).",
"properties": {
"cache_write_tokens": {
"default": 0,
"title": "Cache Write Tokens",
"type": "integer"
},
"cached_tokens": {
"default": 0,
"title": "Cached Tokens",
"type": "integer"
}
},
"title": "PromptTokensDetails",
"type": "object"
},
"ChatCompletionChoice": {
"description": "A single completion choice.",
"properties": {
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason"
},
"index": {
"default": 0,
"title": "Index",
"type": "integer"
},
"message": {
"additionalProperties": true,
"title": "Message",
"type": "object"
}
},
"title": "ChatCompletionChoice",
"type": "object"
},
"ChatCompletionRequest": {
"description": "OpenAI-compatible chat completion request.",
"properties": {
"effort": {
"anyOf": [
{
"$ref": "#/components/schemas/RoutingEffort"
},
{
"type": "null"
}
],
"description": "Per-request routing-effort tier (low/medium/high/xhigh/max) for router models like ``pioneer/auto``. Higher tiers prefer stronger, costlier models. Overrides the router's stored policy for this request only; ignored for non-router models."
},
"extra_body": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extra Body"
},
"extra_headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Extra Headers"
},
"frequency_penalty": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Frequency Penalty"
},
"include_confidence": {
"default": true,
"title": "Include Confidence",
"type": "boolean"
},
"include_spans": {
"default": true,
"title": "Include Spans",
"type": "boolean"
},
"logit_bias": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Logit Bias"
},
"max_tokens": {
"anyOf": [
{
"maximum": 131072.0,
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Tokens"
},
"messages": {
"items": {
"$ref": "#/components/schemas/ChatMessage"
},
"minItems": 1,
"title": "Messages",
"type": "array"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"model": {
"title": "Model",
"type": "string"
},
"models": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Per-request candidate-model subset the router may select between. Overrides the router's stored candidate set for this request only; ignored for non-router models.",
"title": "Models"
},
"n": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "N"
},
"presence_penalty": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Presence Penalty"
},
"reasoning": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Opt-in reasoning / extended-thinking controls. Accepts Fastino's normalized shape with keys ``enabled`` (bool), ``max_tokens`` (int, Anthropic-style budget), ``effort`` (one of minimal/low/medium/high/xhigh/max/none, OpenAI-style tier), and ``exclude`` (bool, hide reasoning tokens from the response). ``effort`` and ``max_tokens`` are mutually exclusive. Fastino extensions for Claude routes (Anthropic direct + Bedrock): ``mode`` (manual/adaptive \u2014 adaptive lets the model pick thinking depth per request, required on Opus 4.7+) and ``display`` (summarized/omitted \u2014 controls whether thinking text streams back; omitted preserves only the signature for multi-turn). On Chat Completions, provider reasoning text is hidden by default and is returned on ``message.reasoning_content`` / ``delta.reasoning_content`` only when the caller explicitly requests visible reasoning with ``exclude=false`` or ``display=summarized``. Fastino canonicalizes this into InferenceRequest.reasoning at the adapter boundary and each provider renders it to its native wire field (Anthropic ``thinking``, OpenAI ``reasoning_effort``, Vercel AI Gateway ``reasoning``). Fastino does not enable reasoning by default.",
"title": "Reasoning"
},
"response_format": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response Format"
},
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Schema for the Fastino encoder. **Deprecated when supplied as a flat list** of entity labels; use the unified dict shape (``entities`` / ``classifications`` / ``structures`` / ``relations``) instead. Deprecated submissions emit ``Deprecation: true`` and ``Sunset: `` headers.",
"title": "Schema"
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed"
},
"stop": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Stop"
},
"store": {
"default": true,
"title": "Store",
"type": "boolean"
},
"stream": {
"default": false,
"title": "Stream",
"type": "boolean"
},
"system": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "System"
},
"task_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "**Deprecated.** Legacy task hint (``extract_entities`` / ``classify_text`` / ``extract_json`` / ``ner`` / ``schema``). The unified schema disambiguates the task automatically so this field is no longer required. Submitting it emits ``Deprecation: true`` and ``Sunset: `` headers on the response.",
"title": "Task Type"
},
"temperature": {
"anyOf": [
{
"maximum": 2.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Sampling temperature",
"title": "Temperature"
},
"threshold": {
"default": 0.5,
"description": "Confidence threshold for encoder (GLiNER) predictions.",
"maximum": 1.0,
"minimum": 0.0,
"title": "Threshold",
"type": "number"
},
"tool_choice": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Tool Choice"
},
"tools": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools"
},
"top_p": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Top P"
},
"user": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User"
}
},
"required": [
"model",
"messages"
],
"title": "ChatCompletionRequest",
"type": "object"
},
"ChatMessage": {
"description": "A single chat message.\n\n``content`` accepts either a plain string or a list of content blocks\n(e.g. ``[{\"type\": \"text\", ...}, {\"type\": \"image_url\", ...}]``) so that\nmultimodal/vision payloads can pass through to upstream providers.",
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Content"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"reasoning_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reasoning Content"
},
"role": {
"title": "Role",
"type": "string"
},
"tool_call_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Call Id"
},
"tool_calls": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
}
},
"required": [
"role"
],
"title": "ChatMessage",
"type": "object"
},
"UpdateModelNameResponse": {
"description": "Response model for updating model name",
"properties": {
"job_id": {
"title": "Job Id",
"type": "string"
},
"message": {
"title": "Message",
"type": "string"
},
"model_name": {
"title": "Model Name",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"message",
"job_id",
"model_name"
],
"title": "UpdateModelNameResponse",
"type": "object"
},
"UpdateModelNameRequest": {
"description": "Request to update a training job's model name",
"properties": {
"model_name": {
"description": "New model name (alphanumeric, hyphens, underscores)",
"maxLength": 64,
"minLength": 1,
"title": "Model Name",
"type": "string"
}
},
"required": [
"model_name"
],
"title": "UpdateModelNameRequest",
"type": "object"
},
"TerminateJobResponse": {
"description": "Response after terminating a training job",
"properties": {
"deleted_checkpoints": {
"title": "Deleted Checkpoints",
"type": "integer"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"message": {
"title": "Message",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"message",
"job_id",
"deleted_checkpoints"
],
"title": "TerminateJobResponse",
"type": "object"
},
"StopJobResponse": {
"description": "Response after stopping a training job",
"properties": {
"job_id": {
"title": "Job Id",
"type": "string"
},
"message": {
"title": "Message",
"type": "string"
},
"status": {
"title": "Status",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"message",
"job_id",
"status"
],
"title": "StopJobResponse",
"type": "object"
},
"StopJobRequest": {
"description": "Optional prune evidence recorded when stopping a training job.",
"properties": {
"checkpoint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Checkpoint path or step associated with this stop",
"title": "Checkpoint"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Why this candidate is being stopped",
"title": "Reason"
},
"scores": {
"anyOf": [
{
"additionalProperties": {
"type": "number"
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Metric values used to decide the prune",
"title": "Scores"
}
},
"title": "StopJobRequest",
"type": "object"
},
"TrainingLogsResponse": {
"description": "Response containing training output logs for a job",
"properties": {
"job_id": {
"title": "Job Id",
"type": "string"
},
"logs": {
"items": {
"$ref": "#/components/schemas/TrainingOutputLogEntry"
},
"title": "Logs",
"type": "array"
},
"total_logs": {
"title": "Total Logs",
"type": "integer"
}
},
"required": [
"job_id",
"logs",
"total_logs"
],
"title": "TrainingLogsResponse",
"type": "object"
},
"TrainingOutputLogEntry": {
"description": "Single training output log entry (stdout/stderr)",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"level": {
"title": "Level",
"type": "string"
},
"message": {
"title": "Message",
"type": "string"
},
"source": {
"title": "Source",
"type": "string"
},
"timestamp": {
"format": "date-time",
"title": "Timestamp",
"type": "string"
}
},
"required": [
"id",
"job_id",
"timestamp",
"level",
"message",
"source"
],
"title": "TrainingOutputLogEntry",
"type": "object"
},
"ModelDownloadResponse": {
"description": "Response with presigned URL for model download",
"properties": {
"download_url": {
"title": "Download Url",
"type": "string"
},
"expires_in_seconds": {
"default": 3600,
"title": "Expires In Seconds",
"type": "integer"
},
"file_name": {
"title": "File Name",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"message": {
"default": "Download URL generated successfully",
"title": "Message",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"job_id",
"download_url",
"file_name"
],
"title": "ModelDownloadResponse",
"type": "object"
},
"DeployCheckpointResponse": {
"description": "Response after deploying a checkpoint",
"properties": {
"checkpoint_id": {
"title": "Checkpoint Id",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"message": {
"title": "Message",
"type": "string"
},
"mme_path": {
"title": "Mme Path",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"message",
"job_id",
"checkpoint_id",
"mme_path"
],
"title": "DeployCheckpointResponse",
"type": "object"
},
"UpdateResourceProjectResponse": {
"description": "Response for project assignment update.",
"properties": {
"message": {
"title": "Message",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"message"
],
"title": "UpdateResourceProjectResponse",
"type": "object"
},
"TrainingJobUpdate": {
"additionalProperties": false,
"description": "Thin PATCH body for ``PATCH /v1/training-jobs/{job_id}``.\n\nExposes only ``project_id``. Send ``null`` to unassign the training job\nfrom its current project. Unknown fields are rejected with HTTP 422.\n\nMovement semantics: this endpoint moves only the ``training_jobs.project_id``\nlabel. It does NOT cascade ``project_id`` updates to dependent rows\n(``deployments``, ``inferences``, ``project_evaluation_runs``) which each carry\ntheir own ``project_id``. Those records remain attached to their original\nproject. Callers needing aggregate-model movement must update the\ndependents explicitly.",
"properties": {
"project_id": {
"anyOf": [
{
"pattern": "(?i)^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"type": "string"
},
{
"type": "null"
}
],
"description": "Project ID (UUID) to assign the training job to, or null to unassign.",
"title": "Project Id"
}
},
"title": "TrainingJobUpdate",
"type": "object"
},
"TrainingJobResponse": {
"description": "Training job response model",
"properties": {
"artifact_ready": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether an artifact location is recorded, so there is something to serve.",
"title": "Artifact Ready"
},
"base_model": {
"title": "Base Model",
"type": "string"
},
"batch_size": {
"title": "Batch Size",
"type": "integer"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"created_at": {
"title": "Created At",
"type": "string"
},
"current_epoch": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Epoch currently in progress (1-indexed). Updated live during training.",
"title": "Current Epoch"
},
"datasets": {
"items": {
"$ref": "#/components/schemas/DatasetReference"
},
"title": "Datasets",
"type": "array"
},
"deployability_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Why the job is not deployable (e.g. 'job_incomplete', 'missing_artifact', 'provider_incompatible'). Null when deployable.",
"title": "Deployability Reason"
},
"deployment_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Deprecated. Always returns None -- deployment_status no longer exists.\n\nKept for backward compat with clients that read this field.",
"readOnly": true,
"title": "Deployment Status"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"example": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sample text to pre-load into inference input",
"title": "Example"
},
"experiment_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Experiment whose agent trained this adapter, when one did. A composite foreign key pins it to the same project as project_id, so it is never an Experiment from elsewhere. Null for a job dispatched outside an Experiment -- a direct API call, or a job predating the column -- which means the owning Experiment is unknown, not that there is none. Adapter-scoped UI hand-offs read this to open the thread that produced the adapter instead of whichever of the project's Experiments happens to be the most recently active (ENG-7287).",
"title": "Experiment Id"
},
"hub_model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "HuggingFace repo id (e.g. 'username/model-name') set only after a successful push_training_job_to_hub call. This is the sole source of truth for whether a checkpoint has been pushed to the Hub -- it does not mean the repo is reachable by anyone other than the pusher: see hub_model_private for that. trained_model_path is an internal storage key and must never be parsed to infer a Hub repo id.",
"title": "Hub Model Id"
},
"hub_model_private": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether the pushed Hub repo is private, as recorded at push time. Null for a job that has never been pushed, and for a push recorded before this field existed (ENG-6761) -- this means the visibility was not recorded, not that either visibility applies. The request schema (HuggingFacePushModelRequest.private) defaults to True, but the only real caller (the CLI) always sends it explicitly, so that default is unreachable in practice -- null here means the visibility was never recorded, not that a caller omitted it. Render null as a neutral 'pushed, visibility unknown' state rather than assuming either PUBLISHED or PRIVATE.",
"title": "Hub Model Private"
},
"id": {
"title": "Id",
"type": "string"
},
"instance_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Instance Type"
},
"is_deployable": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether this job passes server-side deployability validation for its own project. Authoritative -- the same check the deployment endpoints enforce.",
"title": "Is Deployable"
},
"is_terminal_status": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether this status is terminal for polling loops",
"title": "Is Terminal Status"
},
"job_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Job Reference"
},
"labels": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Merged labels from training datasets (entity types for NER, class labels for classification)",
"title": "Labels"
},
"learning_rate": {
"title": "Learning Rate",
"type": "number"
},
"metrics": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Training and evaluation metrics dictionary. Contains final_training_loss, final_validation_loss, best_validation_loss from training logs, and optional evaluation metrics (f1_score, precision_score, recall_score, accuracy) if an evaluation has been run.",
"title": "Metrics"
},
"model_auto_selected": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Model Auto Selected"
},
"model_kind": {
"anyOf": [
{
"enum": [
"lora",
"full"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Normalized fine-tune kind: 'lora' for adapters (lora/qlora) or 'full' for merged weights. Null when the persisted training type is unrecognised -- clients must not claim a kind in that case.",
"title": "Model Kind"
},
"model_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "Unnamed Model",
"title": "Model Name"
},
"model_selection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model Selection Reason"
},
"normalized_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Canonical status alias for compatibility handling (requested, running, complete, deployed, failed, cancelled)",
"title": "Normalized Status"
},
"nr_epochs": {
"title": "Nr Epochs",
"type": "integer"
},
"progress_percent": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Overall training completion percentage (0-100). Updated live during training.",
"title": "Progress Percent"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Project ID this training job is associated with",
"title": "Project Id"
},
"provider_deployments": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Provider-specific deployment metadata written by the training monitor, keyed by provider: {\"modal\": {...}}.",
"title": "Provider Deployments"
},
"provider_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Training provider that handled this job (e.g. 'modal'). Jobs predating a provider removal carry an 'archived_' label.",
"title": "Provider Name"
},
"provider_ready": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether a provider is already serving this artifact. False is not a deployment blocker: promotion provisions or re-warms a provider.",
"title": "Provider Ready"
},
"resolved_recipe": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Immutable snapshot of what this job actually trained with, taken at dispatch: LoRA rank/alpha/dropout, learning rate, warmup ratio, gradient accumulation, packing, precision, attention backend, reasoning parser, container image, runtime profile, max sequence length, and seed, for every seed-capable provider/model. Null for jobs dispatched before the snapshot existed, and for providers that resolve no catalog recipe -- except Modal encoder and Modal RL strategies, which have no dense-LoRA catalog recipe but still return a non-null (seed) snapshot, since seed has no other persisted column. Read this rather than re-deriving from the catalog: the catalog reports what a job dispatched *today* would get, which is a different question.",
"title": "Resolved Recipe"
},
"root_job_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ID of the original/root training job this version derives from",
"title": "Root Job Id"
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Effective reproducibility seed for Modal decoder or GLiNER2 (encoder) training. Null for Fireworks, unknown, and other providers/architectures that cannot honor this contract, and also null for a legacy Modal decoder/encoder job created before seed provenance was recorded (ENG-6970): its seed is unknown, not reconstructed from the default the migration backfilled. A non-null value is always a genuinely recorded seed. Decoder contract: A pinned seed governs LoRA initialisation and the trainer's own RNG (dataloader shuffle order and dropout). It does not select the train/validation split: that partition uses a dedicated split seed so two runs that differ only in `seed` are scored on the same held-out rows. It does not make runs bit-identical: GPU reduction order stays non-deterministic, so metrics can differ between otherwise identical runs. Across six observed same-config decoder pairs, final validation loss agreed to within 6.8% relative and two pairs agreed exactly. Treat that as an observed envelope from production history, not a guaranteed bound. Encoder contract: A pinned seed governs dataset shuffle and auto-sizing downsample order, and the trainer's own weight-initialisation and dropout RNG. It does not select the train/validation split on a Brain-dispatched run: that partition is a fixed left-to-right split derived from validation_data_percentage (validation is the tail), independent of seed, so two runs that differ only in `seed` are scored on the same held-out rows. It does not make runs bit-identical: GPU reduction order stays non-deterministic (cuBLAS GEMM split-k and, unless the embedding-backward scatter/index_add path below applies), so metrics can still differ between identically-configured runs. Before encoder seed control existed, three identically-configured launches measured classification macro-F1 ranging 0.38\u20130.63 \u2014 treat pinning a seed as removing one real, measured source of that noise, not as a guaranteed bound on the rest. Every GLiNER2 job unconditionally pins cuDNN's own algorithm selection (the same flags GLiNER2's bundled Trainer sets) and enables torch.use_deterministic_algorithms in warn-only mode -- this is a fixed container default, not a per-request knob. The cuDNN pin currently costs nothing and changes nothing on this backbone: cuDNN governs convolution/pooling/RNN kernels, and this encoder's DeBERTa-v2 backbone has none, so pinning it has nothing to pin there; the throughput trade-off only materializes if a future backbone adds conv/pooling/RNN layers. The deterministic-algorithms half is not a no-op: it makes embedding-backward scatter/index_add deterministic on CUDA, narrowing -- but, since CUBLAS_WORKSPACE_CONFIG is not set, not closing -- the GPU-reduction-order gap above. It never raises instead of running (warn-only), so it is safe to always leave on, but for the same reason it does not guarantee bit-identical runs.",
"title": "Seed"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Started At"
},
"status": {
"title": "Status",
"type": "string"
},
"task_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Task type derived from training datasets: 'ner', 'classification', 'custom', or 'decoder'",
"title": "Task Type"
},
"trained_model_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Trained Model Path"
},
"training_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Raw training method as persisted: 'lora', 'qlora', or 'full'.",
"title": "Training Type"
},
"updated_at": {
"title": "Updated At",
"type": "string"
},
"user_id": {
"title": "User Id",
"type": "string"
},
"validation_data_percentage": {
"title": "Validation Data Percentage",
"type": "number"
},
"version_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Version number for this training job (e.g., '1', '2', '3')",
"title": "Version Number"
}
},
"required": [
"id",
"user_id",
"datasets",
"base_model",
"validation_data_percentage",
"nr_epochs",
"learning_rate",
"batch_size",
"status",
"created_at",
"updated_at",
"deployment_status"
],
"title": "TrainingJobResponse",
"type": "object"
},
"DatasetReference": {
"description": "Reference to a dataset by name and optional version",
"properties": {
"name": {
"description": "Dataset name",
"title": "Name",
"type": "string"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Version (latest if omitted)",
"title": "Version"
}
},
"required": [
"name"
],
"title": "DatasetReference",
"type": "object"
},
"DeleteTrainingJobResponse": {
"description": "Response model for deleting a training job",
"properties": {
"message": {
"title": "Message",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"message"
],
"title": "DeleteTrainingJobResponse",
"type": "object"
},
"TrainingJobListResponse": {
"description": "List of training jobs response.",
"properties": {
"count": {
"title": "Count",
"type": "integer"
},
"has_more": {
"default": false,
"description": "True when more results exist beyond this page.",
"title": "Has More",
"type": "boolean"
},
"success": {
"title": "Success",
"type": "boolean"
},
"total": {
"default": 0,
"description": "Total number of matching jobs (before pagination).",
"title": "Total",
"type": "integer"
},
"training_jobs": {
"items": {
"$ref": "#/components/schemas/TrainingJobResponse"
},
"title": "Training Jobs",
"type": "array"
}
},
"required": [
"success",
"training_jobs",
"count"
],
"title": "TrainingJobListResponse",
"type": "object"
},
"TrainingJobCreate": {
"additionalProperties": false,
"description": "Request to create a training job.",
"properties": {
"auto_data_sizing": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "GLiNER only. Opt-in: when true, downsample each training dataset to min(max_samples_per_dataset, max(min_samples_per_dataset, samples_per_label * num_labels)). When omitted or false, the full provided dataset is used (no silent downsampling). Defaults to false in the Modal container.",
"title": "Auto Data Sizing"
},
"base_model": {
"description": "HuggingFace model identifier (e.g. 'fastino/gliner2-base-v1', 'deepseek-ai/DeepSeek-V4-Flash', or 'nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16').",
"minLength": 1,
"title": "Base Model",
"type": "string"
},
"batch_size": {
"default": 4,
"description": "Training batch size. Prefer omitting this field so the training service applies the catalog default for ``base_model``. Explicit values equal to this Field default (4) that exceed the model's safe maximum are treated as legacy unset clients and clamped to the catalog default at the training service boundary; any other oversize value is rejected.",
"minimum": 1.0,
"title": "Batch Size",
"type": "integer"
},
"datasets": {
"description": "Datasets to train on (supports multi-dataset training)",
"items": {
"$ref": "#/components/schemas/DatasetReference"
},
"minItems": 1,
"title": "Datasets",
"type": "array"
},
"early_stopping_min_delta": {
"default": 0.0001,
"description": "Minimum validation loss improvement to count as progress. Prevents early stopping from triggering on noise.",
"minimum": 0.0,
"title": "Early Stopping Min Delta",
"type": "number"
},
"early_stopping_patience": {
"default": 3,
"description": "Validation epochs without improvement before stopping. Requires validation_data_percentage > 0. Set to 0 to disable.",
"minimum": 0.0,
"title": "Early Stopping Patience",
"type": "integer"
},
"encoder_learning_rate": {
"anyOf": [
{
"exclusiveMinimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"description": "GLiNER only: learning rate applied to encoder parameters. When omitted, falls back to `learning_rate`.",
"title": "Encoder Learning Rate"
},
"gradient_accumulation_steps": {
"anyOf": [
{
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Accumulate gradients over N mini-batches before each optimizer step. Effective batch size = batch_size * N. Honoured by GLiNER and dense decoder LoRA training; when omitted, dense LoRA applies the per-model catalog default (8 for the H200 Nemotron 3.5 profiles, whose per-device batch is pinned to 1).",
"title": "Gradient Accumulation Steps"
},
"learning_rate": {
"anyOf": [
{
"exclusiveMinimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Peak learning rate for AdamW. When omitted, the trainer's default applies \u2014 the per-model catalog rate (2e-4) for decoder LoRA on Modal, 2e-5 elsewhere. Pinning the old 2e-5 default on a decoder LoRA run under-trains the adapter by an order of magnitude.",
"title": "Learning Rate"
},
"lora_alpha": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "LoRA alpha. When omitted, the trainer's default applies: the per-model catalog alpha for decoder LoRA on Modal, or 32 elsewhere.",
"title": "Lora Alpha"
},
"lora_dropout": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "LoRA dropout. When omitted, the trainer's default applies: the per-model catalog dropout for decoder LoRA on Modal, or 0.1 elsewhere.",
"title": "Lora Dropout"
},
"lora_r": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "LoRA rank. When omitted, the trainer's default applies: the per-model catalog rank for decoder LoRA on Modal (including 32 for the qualified Nemotron 3.5 Lightning profile), or 16 elsewhere.",
"title": "Lora R"
},
"lr_scheduler_type": {
"default": "cosine",
"description": "LR decay schedule after warmup: 'constant', 'linear', or 'cosine'.",
"title": "Lr Scheduler Type",
"type": "string"
},
"mask_history": {
"default": false,
"description": "Decoder SFT loss masking knob. Dense decoder LoRA currently rejects true until assistant-only loss masking is supported by the active trainer. Defaults false to preserve the stock recipe.",
"title": "Mask History",
"type": "boolean"
},
"max_samples_per_dataset": {
"anyOf": [
{
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "GLiNER only: upper bound for auto-sized dataset cap.",
"title": "Max Samples Per Dataset"
},
"min_samples_per_dataset": {
"anyOf": [
{
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "GLiNER only: lower bound for auto-sized dataset cap.",
"title": "Min Samples Per Dataset"
},
"min_training_steps": {
"anyOf": [
{
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "GLiNER only: minimum number of optimizer steps; raises epoch count if the provided `nr_epochs` would yield fewer steps.",
"title": "Min Training Steps"
},
"model_name": {
"description": "User-friendly name for the trained model",
"maxLength": 100,
"minLength": 1,
"title": "Model Name",
"type": "string"
},
"nr_epochs": {
"default": 100,
"description": "Maximum training epochs. With early stopping enabled, training typically terminates well before this ceiling.",
"minimum": 1.0,
"title": "Nr Epochs",
"type": "integer"
},
"packing": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Pack multiple short examples into one training sequence. Applies to decoder dense-LoRA training only, which is the one backend that receives it. None uses the base model's catalog default, so omitting it leaves existing behaviour unchanged.",
"title": "Packing"
},
"profile_training": {
"default": false,
"description": "Enable structured training profiling for this run and persist a training_profile.json artifact.",
"title": "Profile Training",
"type": "boolean"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Project ID to associate with this training job. When omitted, the job is anchored to the caller's auto-managed \"Default\" project so it is always deployable and fleet-eligible.",
"title": "Project Id"
},
"provider_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pin training to a specific provider (e.g. 'modal'). Bypasses automatic provider selection.",
"title": "Provider Name"
},
"rl_config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Algorithm-specific hyperparameters for RL training. Supported keys (all optional unless noted, TRL-aligned defaults applied container-side): max_steps, kl_beta, group_size, sampling_temperature, max_completion_length, reward_type (GRPO; required, one of the built-in reward function names \u2014 see rl_training._BUILTIN_REWARDS); dpo_beta, loss_type (DPO); logging_steps (both; defaults to 25, lower for short smoke runs). When reward_type == 'llm_as_judge' (GRPO only) the judge call is routed through brain's '/v1/chat/completions' API authenticated with a per-run fast_sk_* key minted by ModalTrainingHandler._launch_and_monitor immediately before spawning the Modal function (the user never supplies the key \u2014 minted in the workqueue handler so the cleartext value never enters the SQS message body, injected into the Modal payload at spawn time, revoked from the post-training cleanup hook on terminal status). Additional knobs: llm_judge_model (HuggingFace model id, default 'claude-haiku-4-5' \u2014 must resolve to a brain catalog entry via resolve_catalog_model_id), llm_judge_rubric (template string with {prompt}/{completion}/{answer} placeholders; falls back to a generic faithfulness/quality rubric scored 1-10 when absent), llm_judge_score_scale (raw max score for normalisation to [0,1], default 10), llm_judge_timeout_s (HTTP timeout per judge call, default 30), llm_judge_max_concurrent (parallelism cap on judge HTTP calls, default 8), llm_judge_max_retries (per-row retry budget on transient HTTP errors, default 1), llm_judge_retry_backoff_s (sleep between retries, default 2.0).",
"title": "Rl Config"
},
"samples_per_label": {
"anyOf": [
{
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "GLiNER only: scaling factor used when computing the auto-sized per-dataset cap.",
"title": "Samples Per Label"
},
"save_steps": {
"default": 100,
"description": "Save checkpoint every N steps",
"minimum": 1.0,
"title": "Save Steps",
"type": "integer"
},
"seed": {
"anyOf": [
{
"maximum": 2147483647.0,
"minimum": 0.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Optional reproducibility seed for Modal decoder or GLiNER2 (encoder) training. Requests must pin provider_name to 'modal'; Fireworks and other unsupported architectures reject this field. When omitted, encoder and decoder jobs share the same trainer default (3407). Decoder contract: A pinned seed governs LoRA initialisation and the trainer's own RNG (dataloader shuffle order and dropout). It does not select the train/validation split: that partition uses a dedicated split seed so two runs that differ only in `seed` are scored on the same held-out rows. It does not make runs bit-identical: GPU reduction order stays non-deterministic, so metrics can differ between otherwise identical runs. Across six observed same-config decoder pairs, final validation loss agreed to within 6.8% relative and two pairs agreed exactly. Treat that as an observed envelope from production history, not a guaranteed bound. Encoder contract: A pinned seed governs dataset shuffle and auto-sizing downsample order, and the trainer's own weight-initialisation and dropout RNG. It does not select the train/validation split on a Brain-dispatched run: that partition is a fixed left-to-right split derived from validation_data_percentage (validation is the tail), independent of seed, so two runs that differ only in `seed` are scored on the same held-out rows. It does not make runs bit-identical: GPU reduction order stays non-deterministic (cuBLAS GEMM split-k and, unless the embedding-backward scatter/index_add path below applies), so metrics can still differ between identically-configured runs. Before encoder seed control existed, three identically-configured launches measured classification macro-F1 ranging 0.38\u20130.63 \u2014 treat pinning a seed as removing one real, measured source of that noise, not as a guaranteed bound on the rest. Every GLiNER2 job unconditionally pins cuDNN's own algorithm selection (the same flags GLiNER2's bundled Trainer sets) and enables torch.use_deterministic_algorithms in warn-only mode -- this is a fixed container default, not a per-request knob. The cuDNN pin currently costs nothing and changes nothing on this backbone: cuDNN governs convolution/pooling/RNN kernels, and this encoder's DeBERTa-v2 backbone has none, so pinning it has nothing to pin there; the throughput trade-off only materializes if a future backbone adds conv/pooling/RNN layers. The deterministic-algorithms half is not a no-op: it makes embedding-backward scatter/index_add deterministic on CUDA, narrowing -- but, since CUBLAS_WORKSPACE_CONFIG is not set, not closing -- the GPU-reduction-order gap above. It never raises instead of running (warn-only), so it is safe to always leave on, but for the same reason it does not guarantee bit-identical runs.",
"title": "Seed"
},
"system_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Canonical system prompt written to every decoder training row. When populated, it is persisted on ``training_jobs.system_prompt`` and re-injected by inference providers for API-direct callers that omit the ``system`` message (train/serve alignment), and prefills the inference-page system-prompt editor. Leave null for PAFT datasets, mixed-prompt uploads, or any case where no single prompt should be pinned at serve time. Ignored for non-decoder tasks.",
"title": "System Prompt"
},
"task_learning_rate": {
"anyOf": [
{
"exclusiveMinimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"description": "GLiNER only: learning rate applied to task-head parameters. When omitted, falls back to `learning_rate`.",
"title": "Task Learning Rate"
},
"training_algorithm": {
"default": "sft",
"description": "Training algorithm: 'sft' (default), 'grpo', or 'dpo'. GRPO and DPO are dispatched to the Modal RL entrypoint. GRPO requires rl_config.reward_type from the built-in menu; DPO requires {prompt, chosen, rejected} columns and optional rl_config.dpo_beta / loss_type.",
"enum": [
"sft",
"grpo",
"dpo"
],
"title": "Training Algorithm",
"type": "string"
},
"training_type": {
"default": "lora",
"description": "Training type: 'full' or 'lora'",
"enum": [
"full",
"lora"
],
"title": "Training Type",
"type": "string"
},
"validation_data_percentage": {
"default": 0.2,
"description": "Fraction of data held out for validation.",
"maximum": 1.0,
"minimum": 0.0,
"title": "Validation Data Percentage",
"type": "number"
},
"wandb_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional W&B API key for logging",
"title": "Wandb Api Key"
},
"warmup_ratio": {
"anyOf": [
{
"maximum": 1.0,
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"description": "Fraction of total training steps for linear LR warmup. Ignored when warmup_steps is set. When omitted, the trainer's default applies \u2014 the per-model catalog warmup (0.03) for decoder LoRA on Modal, none elsewhere.",
"title": "Warmup Ratio"
},
"warmup_steps": {
"anyOf": [
{
"minimum": 1.0,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Absolute number of linear LR warmup steps. When set, takes priority over warmup_ratio.",
"title": "Warmup Steps"
},
"weight_decay": {
"default": 0.01,
"description": "AdamW weight decay (L2 penalty). 0 disables weight decay. Honoured by Modal decoder/dense-LoRA training paths. Not forwarded to GLiNER2 Modal training, which uses its own container default.",
"minimum": 0.0,
"title": "Weight Decay",
"type": "number"
}
},
"required": [
"model_name",
"datasets",
"base_model"
],
"title": "TrainingJobCreate",
"type": "object"
},
"CheckpointListResponse": {
"description": "List of checkpoints response",
"properties": {
"checkpoints": {
"items": {
"$ref": "#/components/schemas/CheckpointResponse"
},
"title": "Checkpoints",
"type": "array"
},
"count": {
"title": "Count",
"type": "integer"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"checkpoints",
"count"
],
"title": "CheckpointListResponse",
"type": "object"
},
"CheckpointResponse": {
"description": "Single checkpoint response",
"properties": {
"accuracy": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Accuracy"
},
"checkpoint_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Checkpoint Path"
},
"created_at": {
"title": "Created At",
"type": "string"
},
"epoch": {
"title": "Epoch",
"type": "integer"
},
"gpu_memory_total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Gpu Memory Total"
},
"gpu_memory_used": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Gpu Memory Used"
},
"id": {
"title": "Id",
"type": "string"
},
"is_best": {
"default": false,
"title": "Is Best",
"type": "boolean"
},
"is_deployable": {
"default": false,
"title": "Is Deployable",
"type": "boolean"
},
"is_final": {
"default": false,
"title": "Is Final",
"type": "boolean"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"learning_rate": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Learning Rate"
},
"step": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Step"
},
"training_loss": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Training Loss"
},
"updated_at": {
"title": "Updated At",
"type": "string"
},
"validation_loss": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Validation Loss"
}
},
"required": [
"id",
"job_id",
"epoch",
"created_at",
"updated_at"
],
"title": "CheckpointResponse",
"type": "object"
},
"TrainingJobBillingResponse": {
"description": "Per-job billing outcome, verifiable by ``training_job_id`` (ENG-6131).",
"properties": {
"billed": {
"description": "Whether a billing request row exists for this job.",
"title": "Billed",
"type": "boolean"
},
"billed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "When the billing request row was created.",
"title": "Billed At"
},
"charged_usd": {
"anyOf": [
{
"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
"type": "string"
},
{
"type": "null"
}
],
"description": "Selling price actually charged for this job's GPU time.",
"title": "Charged Usd"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"compute_started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "When the training container actually began executing (ENG-6068). Distinct from started_at. FAILED/CANCELLED jobs bill only when this is set, so a null value here explains why billed=false.",
"title": "Compute Started At"
},
"gpu_minutes": {
"anyOf": [
{
"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
"type": "string"
},
{
"type": "null"
}
],
"description": "Billed GPU minutes, derived from the billed request's duration_ms.",
"title": "Gpu Minutes"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The requests.id row this job was billed against, if billed.",
"title": "Request Id"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "When the job was dispatched to Modal (spawn / queue time).",
"title": "Started At"
},
"status": {
"title": "Status",
"type": "string"
}
},
"required": [
"job_id",
"status",
"billed"
],
"title": "TrainingJobBillingResponse",
"type": "object"
},
"PushModelToHubResponse": {
"description": "Response model for pushing model to HuggingFace Hub",
"properties": {
"job_id": {
"title": "Job Id",
"type": "string"
},
"message": {
"title": "Message",
"type": "string"
},
"repo_id": {
"title": "Repo Id",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
},
"url": {
"title": "Url",
"type": "string"
}
},
"required": [
"success",
"url",
"repo_id",
"job_id",
"message"
],
"title": "PushModelToHubResponse",
"type": "object"
},
"HuggingFacePushModelRequest": {
"description": "Request to push a trained model to HuggingFace Hub",
"properties": {
"commit_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional commit message for the push",
"title": "Commit Message"
},
"hf_token": {
"description": "HuggingFace API token with write permissions",
"title": "Hf Token",
"type": "string"
},
"private": {
"default": true,
"description": "Whether repo should be private",
"title": "Private",
"type": "boolean"
},
"repo_id": {
"description": "HuggingFace repo ID (e.g., 'username/model-name')",
"title": "Repo Id",
"type": "string"
}
},
"required": [
"repo_id",
"hf_token"
],
"title": "HuggingFacePushModelRequest",
"type": "object"
},
"DeploymentHistoryResponse": {
"description": "Paginated list of deployment history records.\n\nAttributes:\n deployments: Ordered list of deployment records (newest first).",
"properties": {
"deployments": {
"items": {
"$ref": "#/components/schemas/DeploymentResponse"
},
"title": "Deployments",
"type": "array"
}
},
"required": [
"deployments"
],
"title": "DeploymentHistoryResponse",
"type": "object"
},
"DeploymentResponse": {
"description": "A single deployment history record.\n\nA deployment targets exactly one of ``training_job_id`` or\n``base_model``: the trained adapter that was activated, or the base\ncatalog model that was activated when no adapter is in use.\n\nAttributes:\n id: Unique deployment record ID.\n project_id: The project whose active model was changed.\n training_job_id: Training job that was deployed (training-job shape).\n base_model: HuggingFace base model ID that was deployed (base-model shape).\n deployed_by: User ID who triggered the deployment.\n reason: Optional reason for the swap.\n deployed_at: When the swap occurred.\n experiment_id: Experiment whose agent promoted, when one did.\n finetune_plan_id: Plan revision that authorised the promotion.\n selection_evaluation_run_id: Evaluation Suite run the promotion was decided on.\n recipe_fingerprint: Digest of the promoted candidate's recipe.\n\nThe four evidence fields are null for a promotion nobody recorded evidence\nfor -- a human pressing promote, or the post-training auto-deploy. They are\nreturned so the basis for a swap is readable after the fact rather than only\nat the moment it happens.",
"properties": {
"base_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Base Model"
},
"deployed_at": {
"format": "date-time",
"title": "Deployed At",
"type": "string"
},
"deployed_by": {
"title": "Deployed By",
"type": "string"
},
"experiment_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Experiment Id"
},
"finetune_plan_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finetune Plan Id"
},
"id": {
"title": "Id",
"type": "string"
},
"project_id": {
"title": "Project Id",
"type": "string"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason"
},
"recipe_fingerprint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Recipe Fingerprint"
},
"selection_evaluation_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Selection Evaluation Run Id"
},
"training_job_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Training Job Id"
}
},
"required": [
"id",
"project_id",
"deployed_by",
"reason",
"deployed_at"
],
"title": "DeploymentResponse",
"type": "object"
},
"DatasetVersionsResponse": {
"description": "List of all versions of a dataset",
"properties": {
"count": {
"title": "Count",
"type": "integer"
},
"success": {
"title": "Success",
"type": "boolean"
},
"versions": {
"items": {
"$ref": "#/components/schemas/DatasetResponse"
},
"title": "Versions",
"type": "array"
}
},
"required": [
"success",
"versions",
"count"
],
"title": "DatasetVersionsResponse",
"type": "object"
},
"DatasetResponse": {
"description": "Response model for a single dataset.",
"properties": {
"annotation_config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Annotation Config"
},
"annotation_progress": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Annotation Progress"
},
"annotation_status": {
"anyOf": [
{
"enum": [
"none",
"in_progress",
"completed"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Annotation Status"
},
"column_mapping": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Column mapping from original to standard names",
"title": "Column Mapping"
},
"created_at": {
"title": "Created At",
"type": "string"
},
"dataset_name": {
"title": "Dataset Name",
"type": "string"
},
"dataset_path": {
"title": "Dataset Path",
"type": "string"
},
"dataset_type": {
"title": "Dataset Type",
"type": "string"
},
"generation_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Canonical operation that created this dataset version.",
"title": "Generation Type"
},
"id": {
"title": "Id",
"type": "string"
},
"is_competition": {
"default": false,
"description": "Whether this dataset is a competition benchmark",
"title": "Is Competition",
"type": "boolean"
},
"is_seed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether this dataset is a seed dataset (small set for review before full expansion)",
"title": "Is Seed"
},
"labels": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Label names (entity types for NER, class labels for classification)",
"title": "Labels"
},
"processing_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Error message if status is failed",
"title": "Processing Error"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project Id"
},
"provenance": {
"anyOf": [
{
"$ref": "#/components/schemas/DatasetProvenance"
},
{
"type": "null"
}
],
"description": "Versioned durable lineage that survives sandbox delete. Omitted on rows created before the provenance contract existed. generator_context is redacted of user-authored task text before it leaves the API; see FREE_TEXT_FIELDS."
},
"root_dataset_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Root Dataset Id"
},
"sample_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Sample Size"
},
"schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Schema"
},
"schema_warnings": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Schema Warnings"
},
"size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Size"
},
"status": {
"anyOf": [
{
"enum": [
"initialized",
"uploading",
"converting",
"validating",
"ready",
"failed",
"generating",
"queued"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "ready",
"description": "Dataset status: initialized/uploading/converting/validating/ready/failed/generating/queued",
"title": "Status"
},
"synthesis_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "UUID of the synthesis log session for this dataset, used to restore creation workflow on resume",
"title": "Synthesis Session Id"
},
"train_ratio": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Train split ratio for this dataset version. Left-to-right split with no shuffle; validation is the tail.",
"title": "Train Ratio"
},
"type": {
"default": "training",
"description": "Dataset purpose tag: 'training', 'evaluation', or 'benchmark'",
"title": "Type",
"type": "string"
},
"updated_at": {
"title": "Updated At",
"type": "string"
},
"user_id": {
"title": "User Id",
"type": "string"
},
"validation": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Validation"
},
"version_number": {
"default": "1",
"title": "Version Number",
"type": "string"
},
"visibility": {
"default": "private",
"description": "Dataset visibility: 'private' or 'public'",
"title": "Visibility",
"type": "string"
}
},
"required": [
"id",
"user_id",
"dataset_name",
"dataset_path",
"dataset_type",
"created_at",
"updated_at"
],
"title": "DatasetResponse",
"type": "object"
},
"DatasetProvenance": {
"additionalProperties": false,
"description": "Record how a dataset was created and which inputs produced it.\n\nAttributes:\n schema_version: Contract version for future migrations.\n method: Canonical dataset generation type.\n sources: External source descriptors.\n fallback: Fallback reason and attempt count, when one was required.\n source_dataset_ids: Dataset inputs combined or transformed.\n parent_dataset_id: Immediate dataset version or transform parent.\n transform_context: Bounded details about a transform.\n generator_context: Bounded generator configuration or agent context.\n synthesis_session_id: Synthesis-log session shared with the dataset row.",
"properties": {
"fallback": {
"anyOf": [
{
"$ref": "#/components/schemas/DatasetProvenanceFallback"
},
{
"type": "null"
}
]
},
"generator_context": {
"anyOf": [
{
"$ref": "#/components/schemas/JsonObject-Output"
},
{
"type": "null"
}
]
},
"method": {
"enum": [
"synthesize",
"upload",
"external",
"grow",
"augment",
"version",
"merge",
"auto_relabel",
"manual_relabel",
"evaluation_suite",
"agent_curated"
],
"title": "Method",
"type": "string"
},
"parent_dataset_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Dataset Id"
},
"schema_version": {
"const": 1,
"default": 1,
"title": "Schema Version",
"type": "integer"
},
"source_dataset_ids": {
"items": {
"type": "string"
},
"title": "Source Dataset Ids",
"type": "array"
},
"sources": {
"items": {
"$ref": "#/components/schemas/DatasetProvenanceSource"
},
"title": "Sources",
"type": "array"
},
"synthesis_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Synthesis Session Id"
},
"transform_context": {
"anyOf": [
{
"$ref": "#/components/schemas/JsonObject-Output"
},
{
"type": "null"
}
]
}
},
"required": [
"method"
],
"title": "DatasetProvenance",
"type": "object"
},
"JsonObject-Output": {
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue-Output"
},
"type": "object"
},
"JsonValue-Output": {
"anyOf": [
{
"$ref": "#/components/schemas/JsonScalar"
},
{
"items": {
"$ref": "#/components/schemas/JsonValue-Output"
},
"type": "array"
},
{
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue-Output"
},
"type": "object"
}
]
},
"JsonScalar": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"DatasetProvenanceSource": {
"additionalProperties": false,
"description": "Describe one external source used to create a dataset.\n\nAttributes:\n url: Stable source URL when known.\n revision: Branch, commit, tag, or dataset revision when known.\n license: Source license when known.\n retrieved_at: Time at which the source was retrieved.\n raw_hash: Digest of the retrieved source bytes when known.",
"properties": {
"license": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "License"
},
"raw_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Raw Hash"
},
"retrieved_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Retrieved At"
},
"revision": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Revision"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
}
},
"title": "DatasetProvenanceSource",
"type": "object"
},
"DatasetProvenanceFallback": {
"additionalProperties": false,
"description": "Describe a fallback used after the preferred source or strategy failed.\n\nAttributes:\n reason: Why the preferred path could not be used.\n attempts: Number of attempts made before the fallback succeeded.",
"properties": {
"attempts": {
"minimum": 1.0,
"title": "Attempts",
"type": "integer"
},
"reason": {
"minLength": 1,
"title": "Reason",
"type": "string"
}
},
"required": [
"reason",
"attempts"
],
"title": "DatasetProvenanceFallback",
"type": "object"
},
"DatasetUploadProcessRequest": {
"description": "Request to process uploaded dataset from S3.",
"properties": {
"dataset_id": {
"description": "Dataset ID from upload/url response (all metadata stored in DB)",
"title": "Dataset Id",
"type": "string"
}
},
"required": [
"dataset_id"
],
"title": "DatasetUploadProcessRequest",
"type": "object"
},
"DatasetUploadUrlResponse": {
"description": "Response with presigned S3 URL for direct upload.",
"properties": {
"dataset_id": {
"description": "Dataset ID for subsequent processing",
"title": "Dataset Id",
"type": "string"
},
"dataset_name": {
"description": "Dataset name (for polling status via GET /{name}/{version})",
"title": "Dataset Name",
"type": "string"
},
"expires_in": {
"description": "URL expiration time in seconds",
"title": "Expires In",
"type": "integer"
},
"presigned_url": {
"description": "S3 presigned URL for PUT upload",
"title": "Presigned Url",
"type": "string"
},
"upload_instructions": {
"default": "Upload file via HTTP PUT to presigned_url, then call /datasets/upload/process with dataset_id, format, and schema (if applicable)",
"description": "Instructions for completing the upload",
"title": "Upload Instructions",
"type": "string"
},
"version_number": {
"description": "Version number for this dataset",
"title": "Version Number",
"type": "string"
}
},
"required": [
"presigned_url",
"dataset_id",
"dataset_name",
"version_number",
"expires_in"
],
"title": "DatasetUploadUrlResponse",
"type": "object"
},
"DatasetUploadUrlRequest": {
"description": "Request to get presigned URL for dataset upload (bypasses API Gateway limits).",
"properties": {
"column_mapping": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Column mapping from source to standard names (e.g., {\"sentence\": \"text\", \"category\": \"label\"}). Valid standard targets: text, label, labels, entities.",
"title": "Column Mapping"
},
"dataset_name": {
"description": "Name for the dataset",
"title": "Dataset Name",
"type": "string"
},
"dataset_type": {
"default": "ner",
"description": "Type of dataset",
"enum": [
"classification",
"ner",
"custom",
"decoder"
],
"title": "Dataset Type",
"type": "string"
},
"experiment_id": {
"anyOf": [
{
"pattern": "(?i)^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional Experiment ID (UUID) the upload was started from. The dataset is linked to it so it appears in that Experiment's Datasets tab (ENG-7109). Ignored when the caller may not access the Experiment.",
"title": "Experiment Id"
},
"filename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Original filename (used for format detection if format not provided)",
"title": "Filename"
},
"format": {
"anyOf": [
{
"enum": [
"jsonl",
"csv",
"tsv",
"parquet",
"json"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "File format (auto-detected from filename if not provided)",
"title": "Format"
},
"generation_type": {
"anyOf": [
{
"const": "upload",
"type": "string"
},
{
"type": "null"
}
],
"description": "Public uploads are always recorded as upload. Other generation methods are assigned by server-owned workflows.",
"title": "Generation Type"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional project ID (UUID) to assign this dataset to",
"title": "Project Id"
},
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Expected schema as JSON object (e.g., {\"age\": \"Int64\", \"name\": \"Utf8\"}). Enforces column types during parsing. Valid types: Int8, Int16, Int32, Int64, UInt8-64, Float32, Float64, Utf8, Boolean, Date, Datetime, Time, Duration, Categorical, Binary",
"title": "Schema"
},
"split_ratio": {
"anyOf": [
{
"additionalProperties": {
"type": "number"
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Split ratio when type is 'split', e.g. {'training': 0.8, 'evaluation': 0.2}",
"title": "Split Ratio"
},
"type": {
"anyOf": [
{
"enum": [
"training",
"evaluation",
"benchmark"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "training",
"description": "Dataset purpose: 'training' (trainable), 'evaluation' (not trainable), 'benchmark' (system-managed, evaluation-only; cannot be trained on or directly accessed).",
"title": "Type"
},
"visibility": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "private",
"description": "Dataset visibility: 'private' (owner only) or 'public' (anyone can see)",
"title": "Visibility"
}
},
"required": [
"dataset_name"
],
"title": "DatasetUploadUrlRequest",
"type": "object"
},
"DatasetListResponse": {
"description": "Response model for listing datasets.",
"properties": {
"count": {
"title": "Count",
"type": "integer"
},
"datasets": {
"items": {
"$ref": "#/components/schemas/DatasetResponse"
},
"title": "Datasets",
"type": "array"
},
"success": {
"default": true,
"title": "Success",
"type": "boolean"
}
},
"required": [
"datasets",
"count"
],
"title": "DatasetListResponse",
"type": "object"
}
},
"securitySchemes": {
"ApiKeyAuth": {
"description": "Fastino API key supplied in the X-API-Key header.",
"in": "header",
"name": "X-API-Key",
"type": "apiKey"
},
"BearerAuth": {
"bearerFormat": "JWT",
"description": "Supabase access token or Fastino API key supplied as a Bearer token.",
"scheme": "bearer",
"type": "http"
}
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}