phoenix-oss/llama-stack-mirror
0
0
Fork 1
mirror of https://github.com/meta-llama/llama-stack.git synced 2025-08-01 16:24:44 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

refactor(api): rename "files" API to "artifacts"

Browse source 
The term "artifacts" better represents the purpose of this API, which
handles outputs generated by API executions, eventually stored objects
that can be of served by any storage interface (file, objects).

This aligns better with the industry convention of 'artifacts' (build
outputs, process results) rather than generic 'files'. 'files' would
be appropriate if the goal was to store and retrieve files purely.

Additionally, in our context, artifact is a better term since it will
handle:

* Data produced by SDG (Synthetic Data Generation) - as input
* Output of a trained model - as output

Signed-off-by: Sébastien Han <seb@redhat.com>
This commit is contained in:
Sébastien Han 2025-05-12 11:13:23 +02:00
parent a5d14749a5
commit fb3c9be1fd
10 changed files with 479 additions and 567 deletions
Download patch file Download diff file Expand all files Collapse all files

386
docs/_static/llama-stack-spec.html vendored
View file

@ -171,6 +171,42 @@
}
}
},
"/v1/artifacts/bulk": {
"post": {
"responses": {
"200": {
"description": "OK"
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Artifacts"
],
"description": "Delete multiple artifacts in a single request.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkDeleteArtifactsRequest"
}
}
},
"required": true
}
}
},
"/v1/post-training/job/cancel": {
"post": {
"responses": {
@ -564,7 +600,7 @@
}
}
},
"/v1/files": {
"/v1/artifacts": {
"get": {
"responses": {
"200": {
@ -572,7 +608,7 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListBucketResponse"
"$ref": "#/components/schemas/PaginatedResponse"
}
}
}
@ -591,16 +627,26 @@
}
},
"tags": [
"Files"
"Artifacts"
],
"description": "List all buckets.",
"description": "List all artifacts with pagination.",
"parameters": [
{
"name": "bucket",
"name": "start_index",
"in": "query",
"required": true,
"description": "Start index of the artifacts to list",
"required": false,
"schema": {
"type": "string"
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"description": "Number of artifacts to list",
"required": false,
"schema": {
"type": "integer"
}
}
]
@ -612,7 +658,7 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponse"
"$ref": "#/components/schemas/ArtifactUploadResponse"
}
}
}
@ -631,9 +677,9 @@
}
},
"tags": [
"Files"
"Artifacts"
],
"description": "Create a new upload session for a file identified by a bucket and key.",
"description": "Create a new upload session for an artifact identified by a key.",
"parameters": [],
"requestBody": {
"content": {
@ -831,7 +877,7 @@
]
}
},
"/v1/files/{bucket}/{key}": {
"/v1/artifacts/{key}": {
"get": {
"responses": {
"200": {
@ -839,7 +885,7 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponse"
"$ref": "#/components/schemas/ArtifactResponse"
}
}
}
@ -858,23 +904,14 @@
}
},
"tags": [
"Files"
"Artifacts"
],
"description": "Get a file info identified by a bucket and key.",
"description": "Get an artifact info identified by a key.",
"parameters": [
{
"name": "bucket",
"in": "path",
"description": "Bucket name (valid chars: a-zA-Z0-9_-)",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)",
"description": "Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)",
"required": true,
"schema": {
"type": "string"
@ -901,23 +938,14 @@
}
},
"tags": [
"Files"
"Artifacts"
],
"description": "Delete a file identified by a bucket and key.",
"description": "Delete an artifact identified by a key.",
"parameters": [
{
"name": "bucket",
"in": "path",
"description": "Bucket name (valid chars: a-zA-Z0-9_-)",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)",
"description": "Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)",
"required": true,
"schema": {
"type": "string"
@ -1850,7 +1878,7 @@
"parameters": []
}
},
"/v1/files/session:{upload_id}": {
"/v1/artifacts/sessions/{upload_id}": {
"get": {
"responses": {
"200": {
@ -1858,7 +1886,7 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponse"
"$ref": "#/components/schemas/ArtifactUploadResponse"
}
}
}
@ -1877,9 +1905,9 @@
}
},
"tags": [
"Files"
"Artifacts"
],
"description": "Returns information about an existsing upload session",
"description": "Returns information about an existing upload session",
"parameters": [
{
"name": "upload_id",
@ -1901,7 +1929,7 @@
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/FileResponse"
"$ref": "#/components/schemas/ArtifactResponse"
},
{
"type": "null"
@ -1925,9 +1953,9 @@
}
},
"tags": [
"Files"
"Artifacts"
],
"description": "Upload file content to an existing upload session. On the server, request body will have the raw bytes that are uploaded.",
"description": "Upload artifact content to an existing upload session. On the server, request body will have the raw bytes that are uploaded.",
"parameters": [
{
"name": "upload_id",
@ -2627,49 +2655,6 @@
}
}
},
"/v1/files/{bucket}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListFileResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "List all files in a bucket.",
"parameters": [
{
"name": "bucket",
"in": "path",
"description": "Bucket name (valid chars: a-zA-Z0-9_-)",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/v1/models": {
"get": {
"responses": {
@ -5022,6 +5007,53 @@
"title": "CompletionResponse",
"description": "Response from a completion request."
},
"ArtifactDeleteRequest": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)"
}
},
"additionalProperties": false,
"required": [
"key"
],
"title": "ArtifactDeleteRequest",
"description": "Request model for deleting a single artifact."
},
"BulkDeleteRequest": {
"type": "object",
"properties": {
"artifacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ArtifactDeleteRequest"
},
"description": "List of artifacts to delete"
}
},
"additionalProperties": false,
"required": [
"artifacts"
],
"title": "BulkDeleteRequest",
"description": "Request model for bulk deletion of artifacts."
},
"BulkDeleteArtifactsRequest": {
"type": "object",
"properties": {
"request": {
"$ref": "#/components/schemas/BulkDeleteRequest",
"description": "Bulk delete request containing list of artifacts to delete"
}
},
"additionalProperties": false,
"required": [
"request"
],
"title": "BulkDeleteArtifactsRequest"
},
"CancelTrainingJobRequest": {
"type": "object",
"properties": {
@ -6893,42 +6925,37 @@
"CreateUploadSessionRequest": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"description": "Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)"
},
"key": {
"type": "string",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)"
"description": "Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)"
},
"mime_type": {
"type": "string",
"description": "MIME type of the file"
"description": "MIME type of the artifact"
},
"size": {
"type": "integer",
"description": "File size in bytes"
"description": "Artifact size in bytes"
}
},
"additionalProperties": false,
"required": [
"bucket",
"key",
"mime_type",
"size"
],
"title": "CreateUploadSessionRequest"
},
"FileUploadResponse": {
"ArtifactUploadResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the upload session"
},
"url": {
"uri": {
"type": "string",
"description": "Upload URL for the file or file parts"
"description": "Upload URI for the artifact or artifact parts"
},
"offset": {
"type": "integer",
@ -6942,12 +6969,12 @@
"additionalProperties": false,
"required": [
"id",
"url",
"uri",
"offset",
"size"
],
"title": "FileUploadResponse",
"description": "Response after initiating a file upload session."
"title": "ArtifactUploadResponse",
"description": "Response after initiating an artifact upload session."
},
"EmbeddingsRequest": {
"type": "object",
@ -7500,6 +7527,41 @@
],
"title": "AgentStepResponse"
},
"ArtifactResponse": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)"
},
"mime_type": {
"type": "string",
"description": "MIME type of the artifact"
},
"uri": {
"type": "string",
"description": "Upload URI for the artifact contents"
},
"size": {
"type": "integer",
"description": "Size of the artifact in bytes"
},
"created_at": {
"type": "integer",
"description": "Timestamp of when the artifact was created"
}
},
"additionalProperties": false,
"required": [
"key",
"mime_type",
"uri",
"size",
"created_at"
],
"title": "ArtifactResponse",
"description": "Response representing an artifact entry."
},
"Benchmark": {
"type": "object",
"properties": {
@ -7736,46 +7798,6 @@
"title": "URIDataSource",
"description": "A dataset that can be obtained from a URI."
},
"FileResponse": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"description": "Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)"
},
"key": {
"type": "string",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)"
},
"mime_type": {
"type": "string",
"description": "MIME type of the file"
},
"url": {
"type": "string",
"description": "Upload URL for the file contents"
},
"bytes": {
"type": "integer",
"description": "Size of the file in bytes"
},
"created_at": {
"type": "integer",
"description": "Timestamp of when the file was created"
}
},
"additionalProperties": false,
"required": [
"bucket",
"key",
"mime_type",
"url",
"bytes",
"created_at"
],
"title": "FileResponse",
"description": "Response representing a file entry."
},
"Model": {
"type": "object",
"properties": {
@ -9019,32 +9041,7 @@
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array"
},
{
"type": "object"
}
]
}
},
"type": "object",
"description": "The list of items for the current page"
},
"has_more": {
@ -9085,37 +9082,6 @@
],
"title": "Job"
},
"BucketResponse": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name"
],
"title": "BucketResponse"
},
"ListBucketResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BucketResponse"
},
"description": "List of FileResponse entries"
}
},
"additionalProperties": false,
"required": [
"data"
],
"title": "ListBucketResponse",
"description": "Response representing a list of file entries."
},
"ListBenchmarksResponse": {
"type": "object",
"properties": {
@ -9148,24 +9114,6 @@
],
"title": "ListDatasetsResponse"
},
"ListFileResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileResponse"
},
"description": "List of FileResponse entries"
}
},
"additionalProperties": false,
"required": [
"data"
],
"title": "ListFileResponse",
"description": "Response representing a list of file entries."
},
"ListModelsResponse": {
"type": "object",
"properties": {
@ -12485,6 +12433,9 @@
"description": "Main functionalities provided by this API:\n- Create agents with specific instructions and ability to use tools.\n- Interactions with agents are grouped into sessions (\"threads\"), and each interaction is called a \"turn\".\n- Agents can be provided with various tools (see the ToolGroups and ToolRuntime APIs for more details).\n- Agents can be provided with various shields (see the Safety API for more details).\n- Agents can also use Memory to retrieve information from knowledge bases. See the RAG Tool and Vector IO APIs for more details.",
"x-displayName": "Agents API for creating and interacting with agentic systems."
},
{
"name": "Artifacts"
},
{
"name": "BatchInference (Coming Soon)",
"description": "This is an asynchronous API. If the request is successful, the response will be a job which can be polled for completion.\n\nNOTE: This API is not yet implemented and is subject to change in concert with other asynchronous APIs\nincluding (post-training, evals, etc).",
@ -12503,9 +12454,6 @@
"name": "Eval",
"x-displayName": "Llama Stack Evaluation API for running evaluations on model and agent candidates."
},
{
"name": "Files"
},
{
"name": "Inference",
"description": "This API provides the raw interface to the underlying models. Two kinds of models are supported:\n- LLM models: these models generate \"raw\" and \"chat\" (conversational) completions.\n- Embedding models: these models generate embeddings to be used for semantic search.",
@ -12560,12 +12508,12 @@
"name": "Operations",
"tags": [
"Agents",
"Artifacts",
"BatchInference (Coming Soon)",
"Benchmarks",
"DatasetIO",
"Datasets",
"Eval",
"Files",
"Inference",
"Inspect",
"Models",

302
docs/_static/llama-stack-spec.yaml vendored
View file

@ -98,6 +98,32 @@ paths:
schema:
$ref: '#/components/schemas/BatchCompletionRequest'
required: true
/v1/artifacts/bulk:
post:
responses:
'200':
description: OK
'400':
$ref: '#/components/responses/BadRequest400'
'429':
$ref: >-
#/components/responses/TooManyRequests429
'500':
$ref: >-
#/components/responses/InternalServerError500
default:
$ref: '#/components/responses/DefaultError'
tags:
- Artifacts
description: >-
Delete multiple artifacts in a single request.
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkDeleteArtifactsRequest'
required: true
/v1/post-training/job/cancel:
post:
responses:
@ -375,7 +401,7 @@ paths:
schema:
$ref: '#/components/schemas/CreateOpenaiResponseRequest'
required: true
/v1/files:
/v1/artifacts:
get:
responses:
'200':
@ -383,7 +409,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/ListBucketResponse'
$ref: '#/components/schemas/PaginatedResponse'
'400':
$ref: '#/components/responses/BadRequest400'
'429':
@ -395,14 +421,21 @@ paths:
default:
$ref: '#/components/responses/DefaultError'
tags:
- Files
description: List all buckets.
- Artifacts
description: List all artifacts with pagination.
parameters:
- name: bucket
- name: start_index
in: query
required: true
description: Start index of the artifacts to list
required: false
schema:
type: string
type: integer
- name: limit
in: query
description: Number of artifacts to list
required: false
schema:
type: integer
post:
responses:
'200':
@ -410,7 +443,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadResponse'
$ref: '#/components/schemas/ArtifactUploadResponse'
'400':
$ref: '#/components/responses/BadRequest400'
'429':
@ -422,9 +455,9 @@ paths:
default:
$ref: '#/components/responses/DefaultError'
tags:
- Files
- Artifacts
description: >-
Create a new upload session for a file identified by a bucket and key.
Create a new upload session for an artifact identified by a key.
parameters: []
requestBody:
content:
@ -563,7 +596,7 @@ paths:
required: true
schema:
type: string
/v1/files/{bucket}/{key}:
/v1/artifacts/{key}:
get:
responses:
'200':
@ -571,7 +604,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/FileResponse'
$ref: '#/components/schemas/ArtifactResponse'
'400':
$ref: '#/components/responses/BadRequest400'
'429':
@ -583,20 +616,14 @@ paths:
default:
$ref: '#/components/responses/DefaultError'
tags:
- Files
- Artifacts
description: >-
Get a file info identified by a bucket and key.
Get an artifact info identified by a key.
parameters:
- name: bucket
in: path
description: 'Bucket name (valid chars: a-zA-Z0-9_-)'
required: true
schema:
type: string
- name: key
in: path
description: >-
Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
required: true
schema:
type: string
@ -615,20 +642,13 @@ paths:
default:
$ref: '#/components/responses/DefaultError'
tags:
- Files
description: >-
Delete a file identified by a bucket and key.
- Artifacts
description: Delete an artifact identified by a key.
parameters:
- name: bucket
in: path
description: 'Bucket name (valid chars: a-zA-Z0-9_-)'
required: true
schema:
type: string
- name: key
in: path
description: >-
Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
required: true
schema:
type: string
@ -1261,7 +1281,7 @@ paths:
- PostTraining (Coming Soon)
description: ''
parameters: []
/v1/files/session:{upload_id}:
/v1/artifacts/sessions/{upload_id}:
get:
responses:
'200':
@ -1269,7 +1289,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadResponse'
$ref: '#/components/schemas/ArtifactUploadResponse'
'400':
$ref: '#/components/responses/BadRequest400'
'429':
@ -1281,9 +1301,9 @@ paths:
default:
$ref: '#/components/responses/DefaultError'
tags:
- Files
- Artifacts
description: >-
Returns information about an existsing upload session
Returns information about an existing upload session
parameters:
- name: upload_id
in: path
@ -1299,7 +1319,7 @@ paths:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/FileResponse'
- $ref: '#/components/schemas/ArtifactResponse'
- type: 'null'
'400':
$ref: '#/components/responses/BadRequest400'
@ -1312,9 +1332,9 @@ paths:
default:
$ref: '#/components/responses/DefaultError'
tags:
- Files
- Artifacts
description: >-
Upload file content to an existing upload session. On the server, request
Upload artifact content to an existing upload session. On the server, request
body will have the raw bytes that are uploaded.
parameters:
- name: upload_id
@ -1812,35 +1832,6 @@ paths:
schema:
$ref: '#/components/schemas/RegisterDatasetRequest'
required: true
/v1/files/{bucket}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListFileResponse'
'400':
$ref: '#/components/responses/BadRequest400'
'429':
$ref: >-
#/components/responses/TooManyRequests429
'500':
$ref: >-
#/components/responses/InternalServerError500
default:
$ref: '#/components/responses/DefaultError'
tags:
- Files
description: List all files in a bucket.
parameters:
- name: bucket
in: path
description: 'Bucket name (valid chars: a-zA-Z0-9_-)'
required: true
schema:
type: string
/v1/models:
get:
responses:
@ -3489,6 +3480,44 @@ components:
- stop_reason
title: CompletionResponse
description: Response from a completion request.
ArtifactDeleteRequest:
type: object
properties:
key:
type: string
description: >-
Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
additionalProperties: false
required:
- key
title: ArtifactDeleteRequest
description: >-
Request model for deleting a single artifact.
BulkDeleteRequest:
type: object
properties:
artifacts:
type: array
items:
$ref: '#/components/schemas/ArtifactDeleteRequest'
description: List of artifacts to delete
additionalProperties: false
required:
- artifacts
title: BulkDeleteRequest
description: >-
Request model for bulk deletion of artifacts.
BulkDeleteArtifactsRequest:
type: object
properties:
request:
$ref: '#/components/schemas/BulkDeleteRequest'
description: >-
Bulk delete request containing list of artifacts to delete
additionalProperties: false
required:
- request
title: BulkDeleteArtifactsRequest
CancelTrainingJobRequest:
type: object
properties:
@ -4826,36 +4855,32 @@ components:
CreateUploadSessionRequest:
type: object
properties:
bucket:
type: string
description: >-
Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)
key:
type: string
description: >-
Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
mime_type:
type: string
description: MIME type of the file
description: MIME type of the artifact
size:
type: integer
description: File size in bytes
description: Artifact size in bytes
additionalProperties: false
required:
- bucket
- key
- mime_type
- size
title: CreateUploadSessionRequest
FileUploadResponse:
ArtifactUploadResponse:
type: object
properties:
id:
type: string
description: ID of the upload session
url:
uri:
type: string
description: Upload URL for the file or file parts
description: >-
Upload URI for the artifact or artifact parts
offset:
type: integer
description: Upload content offset
@ -4865,12 +4890,12 @@ components:
additionalProperties: false
required:
- id
- url
- uri
- offset
- size
title: FileUploadResponse
title: ArtifactUploadResponse
description: >-
Response after initiating a file upload session.
Response after initiating an artifact upload session.
EmbeddingsRequest:
type: object
properties:
@ -5254,6 +5279,35 @@ components:
required:
- step
title: AgentStepResponse
ArtifactResponse:
type: object
properties:
key:
type: string
description: >-
Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
mime_type:
type: string
description: MIME type of the artifact
uri:
type: string
description: Upload URI for the artifact contents
size:
type: integer
description: Size of the artifact in bytes
created_at:
type: integer
description: >-
Timestamp of when the artifact was created
additionalProperties: false
required:
- key
- mime_type
- uri
- size
- created_at
title: ArtifactResponse
description: Response representing an artifact entry.
Benchmark:
type: object
properties:
@ -5412,39 +5466,6 @@ components:
title: URIDataSource
description: >-
A dataset that can be obtained from a URI.
FileResponse:
type: object
properties:
bucket:
type: string
description: >-
Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)
key:
type: string
description: >-
Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
mime_type:
type: string
description: MIME type of the file
url:
type: string
description: Upload URL for the file contents
bytes:
type: integer
description: Size of the file in bytes
created_at:
type: integer
description: Timestamp of when the file was created
additionalProperties: false
required:
- bucket
- key
- mime_type
- url
- bytes
- created_at
title: FileResponse
description: Response representing a file entry.
Model:
type: object
properties:
@ -6235,17 +6256,7 @@ components:
type: object
properties:
data:
type: array
items:
type: object
additionalProperties:
oneOf:
- type: 'null'
- type: boolean
- type: number
- type: string
- type: array
- type: object
type: object
description: The list of items for the current page
has_more:
type: boolean
@ -6277,29 +6288,6 @@ components:
- job_id
- status
title: Job
BucketResponse:
type: object
properties:
name:
type: string
additionalProperties: false
required:
- name
title: BucketResponse
ListBucketResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BucketResponse'
description: List of FileResponse entries
additionalProperties: false
required:
- data
title: ListBucketResponse
description: >-
Response representing a list of file entries.
ListBenchmarksResponse:
type: object
properties:
@ -6322,20 +6310,6 @@ components:
required:
- data
title: ListDatasetsResponse
ListFileResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/FileResponse'
description: List of FileResponse entries
additionalProperties: false
required:
- data
title: ListFileResponse
description: >-
Response representing a list of file entries.
ListModelsResponse:
type: object
properties:
@ -8561,6 +8535,7 @@ tags:
the RAG Tool and Vector IO APIs for more details.
x-displayName: >-
Agents API for creating and interacting with agentic systems.
- name: Artifacts
- name: BatchInference (Coming Soon)
description: >-
This is an asynchronous API. If the request is successful, the response will
@ -8579,7 +8554,6 @@ tags:
- name: Eval
x-displayName: >-
Llama Stack Evaluation API for running evaluations on model and agent candidates.
- name: Files
- name: Inference
description: >-
This API provides the raw interface to the underlying models. Two kinds of models
@ -8612,12 +8586,12 @@ x-tagGroups:
- name: Operations
tags:
- Agents
- Artifacts
- BatchInference (Coming Soon)
- Benchmarks
- DatasetIO
- Datasets
- Eval
- Files
- Inference
- Inspect
- Models

2
llama_stack/apis/files/__init__.py → llama_stack/apis/artifacts/__init__.py
View file

@ -4,4 +4,4 @@
# This source code is licensed under the terms described in the LICENSE file in
# the root directory of this source tree.
from .files import * # noqa: F401 F403
from .artifacts import * # noqa: F401 F403

166
llama_stack/apis/artifacts/artifacts.py Normal file
View file

@ -0,0 +1,166 @@
# Copyright (c) Meta Platforms, Inc. and affiliates.
# All rights reserved.
#
# This source code is licensed under the terms described in the LICENSE file in
# the root directory of this source tree.
from typing import Protocol, runtime_checkable
from pydantic import BaseModel
from llama_stack.apis.common.responses import PaginatedResponse
from llama_stack.providers.utils.telemetry.trace_protocol import trace_protocol
from llama_stack.schema_utils import json_schema_type, webmethod
@json_schema_type
class ArtifactUploadResponse(BaseModel):
"""
Response after initiating an artifact upload session.
:param id: ID of the upload session
:param uri: Upload URI for the artifact or artifact parts
:param offset: Upload content offset
:param size: Upload content size
"""
id: str
uri: str
offset: int
size: int
@json_schema_type
class ArtifactResponse(BaseModel):
"""
Response representing an artifact entry.
:param key: Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
:param mime_type: MIME type of the artifact
:param uri: Upload URI for the artifact contents
:param size: Size of the artifact in bytes
:param created_at: Timestamp of when the artifact was created
"""
key: str
mime_type: str
uri: str
size: int
created_at: int
@json_schema_type
class ArtifactDeleteRequest(BaseModel):
"""
Request model for deleting a single artifact.
:param key: Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
"""
key: str
@json_schema_type
class BulkDeleteRequest(BaseModel):
"""
Request model for bulk deletion of artifacts.
:param artifacts: List of artifacts to delete
"""
artifacts: list[ArtifactDeleteRequest]
@runtime_checkable
@trace_protocol
class Artifacts(Protocol):
@webmethod(route="/artifacts", method="POST")
async def create_upload_session(
self,
key: str,
mime_type: str,
size: int,
) -> ArtifactUploadResponse:
"""
Create a new upload session for an artifact identified by a key.
:param key: Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
:param mime_type: MIME type of the artifact
:param size: Artifact size in bytes
"""
...
@webmethod(route="/artifacts/sessions/{upload_id}", method="POST", raw_bytes_request_body=True)
async def upload_content_to_session(
self,
upload_id: str,
) -> ArtifactResponse | None:
"""
Upload artifact content to an existing upload session.
On the server, request body will have the raw bytes that are uploaded.
:param upload_id: ID of the upload session
"""
...
@webmethod(route="/artifacts/sessions/{upload_id}", method="GET")
async def get_upload_session_info(
self,
upload_id: str,
) -> ArtifactUploadResponse:
"""
Returns information about an existing upload session
:param upload_id: ID of the upload session
"""
...
@webmethod(route="/artifacts", method="GET")
async def list_artifacts(
self,
start_index: int | None = None,
limit: int | None = None,
) -> PaginatedResponse:
"""
List all artifacts with pagination.
:param start_index: Start index of the artifacts to list
:param limit: Number of artifacts to list
"""
...
@webmethod(route="/artifacts/{key:path}", method="GET")
async def get_artifact(
self,
key: str,
) -> ArtifactResponse:
"""
Get an artifact info identified by a key.
:param key: Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
"""
...
@webmethod(route="/artifacts/{key:path}", method="DELETE")
async def delete_artifact(
self,
key: str,
) -> None:
"""
Delete an artifact identified by a key.
:param key: Key under which the artifact is stored (valid chars: a-zA-Z0-9_-/.)
"""
...
@webmethod(route="/artifacts/bulk", method="POST")
async def bulk_delete_artifacts(
self,
request: BulkDeleteRequest,
) -> None:
"""
Delete multiple artifacts in a single request.
:param request: Bulk delete request containing list of artifacts to delete
"""
...

4
llama_stack/apis/common/responses.py
View file

@ -4,8 +4,6 @@
# This source code is licensed under the terms described in the LICENSE file in
# the root directory of this source tree.
from typing import Any
from pydantic import BaseModel
from llama_stack.schema_utils import json_schema_type
@ -19,5 +17,5 @@ class PaginatedResponse(BaseModel):
:param has_more: Whether there are more items available after this set
"""
data: list[dict[str, Any]]
data: list
has_more: bool

2
llama_stack/apis/datatypes.py
View file

@ -33,7 +33,7 @@ class Api(Enum):
scoring_functions = "scoring_functions"
benchmarks = "benchmarks"
tool_groups = "tool_groups"
files = "files"
artifacts = "artifacts"
# built-in API
inspect = "inspect"

174
llama_stack/apis/files/files.py
View file

@ -1,174 +0,0 @@
# Copyright (c) Meta Platforms, Inc. and affiliates.
# All rights reserved.
#
# This source code is licensed under the terms described in the LICENSE file in
# the root directory of this source tree.
from typing import Protocol, runtime_checkable
from pydantic import BaseModel
from llama_stack.providers.utils.telemetry.trace_protocol import trace_protocol
from llama_stack.schema_utils import json_schema_type, webmethod
@json_schema_type
class FileUploadResponse(BaseModel):
"""
Response after initiating a file upload session.
:param id: ID of the upload session
:param url: Upload URL for the file or file parts
:param offset: Upload content offset
:param size: Upload content size
"""
id: str
url: str
offset: int
size: int
@json_schema_type
class BucketResponse(BaseModel):
name: str
@json_schema_type
class ListBucketResponse(BaseModel):
"""
Response representing a list of file entries.
:param data: List of FileResponse entries
"""
data: list[BucketResponse]
@json_schema_type
class FileResponse(BaseModel):
"""
Response representing a file entry.
:param bucket: Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)
:param key: Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
:param mime_type: MIME type of the file
:param url: Upload URL for the file contents
:param bytes: Size of the file in bytes
:param created_at: Timestamp of when the file was created
"""
bucket: str
key: str
mime_type: str
url: str
bytes: int
created_at: int
@json_schema_type
class ListFileResponse(BaseModel):
"""
Response representing a list of file entries.
:param data: List of FileResponse entries
"""
data: list[FileResponse]
@runtime_checkable
@trace_protocol
class Files(Protocol):
@webmethod(route="/files", method="POST")
async def create_upload_session(
self,
bucket: str,
key: str,
mime_type: str,
size: int,
) -> FileUploadResponse:
"""
Create a new upload session for a file identified by a bucket and key.
:param bucket: Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)
:param key: Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
:param mime_type: MIME type of the file
:param size: File size in bytes
"""
...
@webmethod(route="/files/session:{upload_id}", method="POST", raw_bytes_request_body=True)
async def upload_content_to_session(
self,
upload_id: str,
) -> FileResponse | None:
"""
Upload file content to an existing upload session.
On the server, request body will have the raw bytes that are uploaded.
:param upload_id: ID of the upload session
"""
...
@webmethod(route="/files/session:{upload_id}", method="GET")
async def get_upload_session_info(
self,
upload_id: str,
) -> FileUploadResponse:
"""
Returns information about an existsing upload session
:param upload_id: ID of the upload session
"""
...
@webmethod(route="/files", method="GET")
async def list_all_buckets(
self,
bucket: str,
) -> ListBucketResponse:
"""
List all buckets.
"""
...
@webmethod(route="/files/{bucket}", method="GET")
async def list_files_in_bucket(
self,
bucket: str,
) -> ListFileResponse:
"""
List all files in a bucket.
:param bucket: Bucket name (valid chars: a-zA-Z0-9_-)
"""
...
@webmethod(route="/files/{bucket}/{key:path}", method="GET")
async def get_file(
self,
bucket: str,
key: str,
) -> FileResponse:
"""
Get a file info identified by a bucket and key.
:param bucket: Bucket name (valid chars: a-zA-Z0-9_-)
:param key: Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
"""
...
@webmethod(route="/files/{bucket}/{key:path}", method="DELETE")
async def delete_file(
self,
bucket: str,
key: str,
) -> None:
"""
Delete a file identified by a bucket and key.
:param bucket: Bucket name (valid chars: a-zA-Z0-9_-)
:param key: Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)
"""
...

4
llama_stack/distribution/resolver.py
View file

@ -8,11 +8,11 @@ import inspect
from typing import Any
from llama_stack.apis.agents import Agents
from llama_stack.apis.artifacts import Artifacts
from llama_stack.apis.benchmarks import Benchmarks
from llama_stack.apis.datasetio import DatasetIO
from llama_stack.apis.datasets import Datasets
from llama_stack.apis.eval import Eval
from llama_stack.apis.files import Files
from llama_stack.apis.inference import Inference
from llama_stack.apis.inspect import Inspect
from llama_stack.apis.models import Models
@ -79,7 +79,7 @@ def api_protocol_map() -> dict[Api, Any]:
Api.post_training: PostTraining,
Api.tool_groups: ToolGroups,
Api.tool_runtime: ToolRuntime,
Api.files: Files,
Api.artifacts: Artifacts,
}

4
llama_stack/distribution/stack.py
View file

@ -13,12 +13,12 @@ from typing import Any
import yaml
from llama_stack.apis.agents import Agents
from llama_stack.apis.artifacts import Artifacts
from llama_stack.apis.batch_inference import BatchInference
from llama_stack.apis.benchmarks import Benchmarks
from llama_stack.apis.datasetio import DatasetIO
from llama_stack.apis.datasets import Datasets
from llama_stack.apis.eval import Eval
from llama_stack.apis.files import Files
from llama_stack.apis.inference import Inference
from llama_stack.apis.inspect import Inspect
from llama_stack.apis.models import Models
@ -69,7 +69,7 @@ class LlamaStack(
ToolGroups,
ToolRuntime,
RAGToolRuntime,
Files,
Artifacts,
):
pass

2
llama_stack/providers/utils/scheduler.py
View file

@ -37,7 +37,7 @@ JobType: TypeAlias = str
class JobArtifact(BaseModel):
type: JobType
name: str
# TODO: uri should be a reference to /files API; revisit when /files is implemented
# TODO: uri should be a reference to /artifacts API; revisit when /artifacts is implemented
uri: str | None = None
metadata: dict[str, Any]