phoenix-oss/llama-stack-mirror
0
0
Fork 1
mirror of https://github.com/meta-llama/llama-stack.git synced 2025-07-29 15:23:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

vector io

Browse source
This commit is contained in:
Sai Soundararaj 2025-07-01 16:21:27 -07:00
parent 3634bf05b4
commit fa65de5fb3
4 changed files with 466 additions and 95 deletions
Download patch file Download diff file Expand all files Collapse all files

2
api_update_plan.md
View file

@ -225,7 +225,7 @@ Before finalizing documentation, verify:
[x] 4. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/models/models.py` - Model metadata and management [x] 4. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/models/models.py` - Model metadata and management
[x] 5. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/tools/tools.py` - Tool system APIs [x] 5. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/tools/tools.py` - Tool system APIs
[x] 6. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/tools/rag_tool.py` - RAG tool runtime [x] 6. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/tools/rag_tool.py` - RAG tool runtime
7. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/vector_io/vector_io.py` - Vector database operations [x] 7. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/vector_io/vector_io.py` - Vector database operations
8. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/vector_dbs/vector_dbs.py` - Vector database management 8. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/vector_dbs/vector_dbs.py` - Vector database management
9. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/files/files.py` - File management 9. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/files/files.py` - File management
10. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/datasets/datasets.py` - Dataset management 10. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/datasets/datasets.py` - Dataset management

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

@ -3324,6 +3324,7 @@
{ {
"name": "limit", "name": "limit",
"in": "query", "in": "query",
"description": "(Optional) A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.",
"required": false, "required": false,
"schema": { "schema": {
"type": "integer" "type": "integer"
@ -3332,6 +3333,7 @@
{ {
"name": "order", "name": "order",
"in": "query", "in": "query",
"description": "(Optional) Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.",
"required": false, "required": false,
"schema": { "schema": {
"type": "string" "type": "string"
@ -3340,6 +3342,7 @@
{ {
"name": "after", "name": "after",
"in": "query", "in": "query",
"description": "(Optional) A cursor for use in pagination. `after` is an object ID that defines your place in the list.",
"required": false, "required": false,
"schema": { "schema": {
"type": "string" "type": "string"
@ -3348,6 +3351,7 @@
{ {
"name": "before", "name": "before",
"in": "query", "in": "query",
"description": "(Optional) A cursor for use in pagination. `before` is an object ID that defines your place in the list.",
"required": false, "required": false,
"schema": { "schema": {
"type": "string" "type": "string"
@ -3356,6 +3360,7 @@
{ {
"name": "filter", "name": "filter",
"in": "query", "in": "query",
"description": "(Optional) Filter by file status to only return files with the specified status.",
"required": false, "required": false,
"schema": { "schema": {
"$ref": "#/components/schemas/VectorStoreFileStatus" "$ref": "#/components/schemas/VectorStoreFileStatus"
@ -7826,15 +7831,18 @@
"type": "object", "type": "object",
"properties": { "properties": {
"ranker": { "ranker": {
"type": "string" "type": "string",
"description": "(Optional) Name of the ranking algorithm to use"
}, },
"score_threshold": { "score_threshold": {
"type": "number", "type": "number",
"default": 0.0 "default": 0.0,
"description": "(Optional) Minimum relevance score threshold for results"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"title": "SearchRankingOptions" "title": "SearchRankingOptions",
"description": "Options for ranking and filtering search results."
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12638,14 +12646,16 @@
"type": { "type": {
"type": "string", "type": "string",
"const": "auto", "const": "auto",
"default": "auto" "default": "auto",
"description": "Strategy type, always \"auto\" for automatic chunking"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"type" "type"
], ],
"title": "VectorStoreChunkingStrategyAuto" "title": "VectorStoreChunkingStrategyAuto",
"description": "Automatic chunking strategy for vector store files."
}, },
"VectorStoreChunkingStrategyStatic": { "VectorStoreChunkingStrategyStatic": {
"type": "object", "type": "object",
@ -12653,10 +12663,12 @@
"type": { "type": {
"type": "string", "type": "string",
"const": "static", "const": "static",
"default": "static" "default": "static",
"description": "Strategy type, always \"static\" for static chunking"
}, },
"static": { "static": {
"$ref": "#/components/schemas/VectorStoreChunkingStrategyStaticConfig" "$ref": "#/components/schemas/VectorStoreChunkingStrategyStaticConfig",
"description": "Configuration parameters for the static chunking strategy"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12664,18 +12676,21 @@
"type", "type",
"static" "static"
], ],
"title": "VectorStoreChunkingStrategyStatic" "title": "VectorStoreChunkingStrategyStatic",
"description": "Static chunking strategy with configurable parameters."
}, },
"VectorStoreChunkingStrategyStaticConfig": { "VectorStoreChunkingStrategyStaticConfig": {
"type": "object", "type": "object",
"properties": { "properties": {
"chunk_overlap_tokens": { "chunk_overlap_tokens": {
"type": "integer", "type": "integer",
"default": 400 "default": 400,
"description": "Number of tokens to overlap between adjacent chunks"
}, },
"max_chunk_size_tokens": { "max_chunk_size_tokens": {
"type": "integer", "type": "integer",
"default": 800 "default": 800,
"description": "Maximum number of tokens per chunk, must be between 100 and 4096"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12683,7 +12698,8 @@
"chunk_overlap_tokens", "chunk_overlap_tokens",
"max_chunk_size_tokens" "max_chunk_size_tokens"
], ],
"title": "VectorStoreChunkingStrategyStaticConfig" "title": "VectorStoreChunkingStrategyStaticConfig",
"description": "Configuration for static chunking strategy."
}, },
"OpenaiAttachFileToVectorStoreRequest": { "OpenaiAttachFileToVectorStoreRequest": {
"type": "object", "type": "object",
@ -12742,10 +12758,12 @@
"type": "string", "type": "string",
"const": "rate_limit_exceeded" "const": "rate_limit_exceeded"
} }
] ],
"description": "Error code indicating the type of failure"
}, },
"message": { "message": {
"type": "string" "type": "string",
"description": "Human-readable error message describing the failure"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12753,17 +12771,20 @@
"code", "code",
"message" "message"
], ],
"title": "VectorStoreFileLastError" "title": "VectorStoreFileLastError",
"description": "Error information for failed vector store file processing."
}, },
"VectorStoreFileObject": { "VectorStoreFileObject": {
"type": "object", "type": "object",
"properties": { "properties": {
"id": { "id": {
"type": "string" "type": "string",
"description": "Unique identifier for the file"
}, },
"object": { "object": {
"type": "string", "type": "string",
"default": "vector_store.file" "default": "vector_store.file",
"description": "Object type identifier, always \"vector_store.file\""
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -12788,26 +12809,33 @@
"type": "object" "type": "object"
} }
] ]
} },
"description": "Key-value attributes associated with the file"
}, },
"chunking_strategy": { "chunking_strategy": {
"$ref": "#/components/schemas/VectorStoreChunkingStrategy" "$ref": "#/components/schemas/VectorStoreChunkingStrategy",
"description": "Strategy used for splitting the file into chunks"
}, },
"created_at": { "created_at": {
"type": "integer" "type": "integer",
"description": "Timestamp when the file was added to the vector store"
}, },
"last_error": { "last_error": {
"$ref": "#/components/schemas/VectorStoreFileLastError" "$ref": "#/components/schemas/VectorStoreFileLastError",
"description": "(Optional) Error information if file processing failed"
}, },
"status": { "status": {
"$ref": "#/components/schemas/VectorStoreFileStatus" "$ref": "#/components/schemas/VectorStoreFileStatus",
"description": "Current processing status of the file"
}, },
"usage_bytes": { "usage_bytes": {
"type": "integer", "type": "integer",
"default": 0 "default": 0,
"description": "Storage space used by this file in bytes"
}, },
"vector_store_id": { "vector_store_id": {
"type": "string" "type": "string",
"description": "ID of the vector store containing this file"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -13686,19 +13714,24 @@
"type": "object", "type": "object",
"properties": { "properties": {
"completed": { "completed": {
"type": "integer" "type": "integer",
"description": "Number of files that have been successfully processed"
}, },
"cancelled": { "cancelled": {
"type": "integer" "type": "integer",
"description": "Number of files that had their processing cancelled"
}, },
"failed": { "failed": {
"type": "integer" "type": "integer",
"description": "Number of files that failed to process"
}, },
"in_progress": { "in_progress": {
"type": "integer" "type": "integer",
"description": "Number of files currently being processed"
}, },
"total": { "total": {
"type": "integer" "type": "integer",
"description": "Total number of files in the vector store"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -13709,34 +13742,42 @@
"in_progress", "in_progress",
"total" "total"
], ],
"title": "VectorStoreFileCounts" "title": "VectorStoreFileCounts",
"description": "File processing status counts for a vector store."
}, },
"VectorStoreObject": { "VectorStoreObject": {
"type": "object", "type": "object",
"properties": { "properties": {
"id": { "id": {
"type": "string" "type": "string",
"description": "Unique identifier for the vector store"
}, },
"object": { "object": {
"type": "string", "type": "string",
"default": "vector_store" "default": "vector_store",
"description": "Object type identifier, always \"vector_store\""
}, },
"created_at": { "created_at": {
"type": "integer" "type": "integer",
"description": "Timestamp when the vector store was created"
}, },
"name": { "name": {
"type": "string" "type": "string",
"description": "(Optional) Name of the vector store"
}, },
"usage_bytes": { "usage_bytes": {
"type": "integer", "type": "integer",
"default": 0 "default": 0,
"description": "Storage space used by the vector store in bytes"
}, },
"file_counts": { "file_counts": {
"$ref": "#/components/schemas/VectorStoreFileCounts" "$ref": "#/components/schemas/VectorStoreFileCounts",
"description": "File processing status counts for the vector store"
}, },
"status": { "status": {
"type": "string", "type": "string",
"default": "completed" "default": "completed",
"description": "Current status of the vector store"
}, },
"expires_after": { "expires_after": {
"type": "object", "type": "object",
@ -13761,13 +13802,16 @@
"type": "object" "type": "object"
} }
] ]
} },
"description": "(Optional) Expiration policy for the vector store"
}, },
"expires_at": { "expires_at": {
"type": "integer" "type": "integer",
"description": "(Optional) Timestamp when the vector store will expire"
}, },
"last_active_at": { "last_active_at": {
"type": "integer" "type": "integer",
"description": "(Optional) Timestamp of last activity on the vector store"
}, },
"metadata": { "metadata": {
"type": "object", "type": "object",
@ -13792,7 +13836,8 @@
"type": "object" "type": "object"
} }
] ]
} },
"description": "Set of key-value pairs that can be attached to the vector store"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -13839,15 +13884,18 @@
"type": "object", "type": "object",
"properties": { "properties": {
"id": { "id": {
"type": "string" "type": "string",
"description": "Unique identifier of the deleted vector store"
}, },
"object": { "object": {
"type": "string", "type": "string",
"default": "vector_store.deleted" "default": "vector_store.deleted",
"description": "Object type identifier for the deletion response"
}, },
"deleted": { "deleted": {
"type": "boolean", "type": "boolean",
"default": true "default": true,
"description": "Whether the deletion operation was successful"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -13863,15 +13911,18 @@
"type": "object", "type": "object",
"properties": { "properties": {
"id": { "id": {
"type": "string" "type": "string",
"description": "Unique identifier of the deleted file"
}, },
"object": { "object": {
"type": "string", "type": "string",
"default": "vector_store.file.deleted" "default": "vector_store.file.deleted",
"description": "Object type identifier for the deletion response"
}, },
"deleted": { "deleted": {
"type": "boolean", "type": "boolean",
"default": true "default": true,
"description": "Whether the deletion operation was successful"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14116,23 +14167,28 @@
"properties": { "properties": {
"object": { "object": {
"type": "string", "type": "string",
"default": "list" "default": "list",
"description": "Object type identifier, always \"list\""
}, },
"data": { "data": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/VectorStoreFileObject" "$ref": "#/components/schemas/VectorStoreFileObject"
} },
"description": "List of vector store file objects"
}, },
"first_id": { "first_id": {
"type": "string" "type": "string",
"description": "(Optional) ID of the first file in the list for pagination"
}, },
"last_id": { "last_id": {
"type": "string" "type": "string",
"description": "(Optional) ID of the last file in the list for pagination"
}, },
"has_more": { "has_more": {
"type": "boolean", "type": "boolean",
"default": false "default": false,
"description": "Whether there are more files available beyond this page"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14142,7 +14198,7 @@
"has_more" "has_more"
], ],
"title": "VectorStoreListFilesResponse", "title": "VectorStoreListFilesResponse",
"description": "Response from listing vector stores." "description": "Response from listing files in a vector store."
}, },
"OpenAIModel": { "OpenAIModel": {
"type": "object", "type": "object",
@ -14193,23 +14249,28 @@
"properties": { "properties": {
"object": { "object": {
"type": "string", "type": "string",
"default": "list" "default": "list",
"description": "Object type identifier, always \"list\""
}, },
"data": { "data": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/VectorStoreObject" "$ref": "#/components/schemas/VectorStoreObject"
} },
"description": "List of vector store objects"
}, },
"first_id": { "first_id": {
"type": "string" "type": "string",
"description": "(Optional) ID of the first vector store in the list for pagination"
}, },
"last_id": { "last_id": {
"type": "string" "type": "string",
"description": "(Optional) ID of the last vector store in the list for pagination"
}, },
"has_more": { "has_more": {
"type": "boolean", "type": "boolean",
"default": false "default": false,
"description": "Whether there are more vector stores available beyond this page"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14230,10 +14291,12 @@
"properties": { "properties": {
"type": { "type": {
"type": "string", "type": "string",
"const": "text" "const": "text",
"description": "Content type, currently only \"text\" is supported"
}, },
"text": { "text": {
"type": "string" "type": "string",
"description": "The actual text content"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14241,16 +14304,19 @@
"type", "type",
"text" "text"
], ],
"title": "VectorStoreContent" "title": "VectorStoreContent",
"description": "Content item from a vector store file or search result."
}, },
"VectorStoreFileContentsResponse": { "VectorStoreFileContentsResponse": {
"type": "object", "type": "object",
"properties": { "properties": {
"file_id": { "file_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the file"
}, },
"filename": { "filename": {
"type": "string" "type": "string",
"description": "Name of the file"
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -14275,13 +14341,15 @@
"type": "object" "type": "object"
} }
] ]
} },
"description": "Key-value attributes associated with the file"
}, },
"content": { "content": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/VectorStoreContent" "$ref": "#/components/schemas/VectorStoreContent"
} },
"description": "List of content items from the file"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14345,11 +14413,13 @@
"type": "object", "type": "object",
"properties": { "properties": {
"ranker": { "ranker": {
"type": "string" "type": "string",
"description": "(Optional) Name of the ranking algorithm to use"
}, },
"score_threshold": { "score_threshold": {
"type": "number", "type": "number",
"default": 0.0 "default": 0.0,
"description": "(Optional) Minimum relevance score threshold for results"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14374,13 +14444,16 @@
"type": "object", "type": "object",
"properties": { "properties": {
"file_id": { "file_id": {
"type": "string" "type": "string",
"description": "Unique identifier of the file containing the result"
}, },
"filename": { "filename": {
"type": "string" "type": "string",
"description": "Name of the file containing the result"
}, },
"score": { "score": {
"type": "number" "type": "number",
"description": "Relevance score for this search result"
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -14396,13 +14469,15 @@
"type": "boolean" "type": "boolean"
} }
] ]
} },
"description": "(Optional) Key-value attributes associated with the file"
}, },
"content": { "content": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/VectorStoreContent" "$ref": "#/components/schemas/VectorStoreContent"
} },
"description": "List of content items matching the search query"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14420,23 +14495,28 @@
"properties": { "properties": {
"object": { "object": {
"type": "string", "type": "string",
"default": "vector_store.search_results.page" "default": "vector_store.search_results.page",
"description": "Object type identifier for the search results page"
}, },
"search_query": { "search_query": {
"type": "string" "type": "string",
"description": "The original search query that was executed"
}, },
"data": { "data": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/VectorStoreSearchResponse" "$ref": "#/components/schemas/VectorStoreSearchResponse"
} },
"description": "List of search result objects"
}, },
"has_more": { "has_more": {
"type": "boolean", "type": "boolean",
"default": false "default": false,
"description": "Whether there are more results available beyond this page"
}, },
"next_page": { "next_page": {
"type": "string" "type": "string",
"description": "(Optional) Token for retrieving the next page of results"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -14447,7 +14527,7 @@
"has_more" "has_more"
], ],
"title": "VectorStoreSearchResponsePage", "title": "VectorStoreSearchResponsePage",
"description": "Response from searching a vector store." "description": "Paginated response from searching a vector store."
}, },
"OpenaiUpdateVectorStoreRequest": { "OpenaiUpdateVectorStoreRequest": {
"type": "object", "type": "object",
@ -15100,13 +15180,15 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/Chunk" "$ref": "#/components/schemas/Chunk"
} },
"description": "List of content chunks returned from the query"
}, },
"scores": { "scores": {
"type": "array", "type": "array",
"items": { "items": {
"type": "number" "type": "number"
} },
"description": "Relevance scores corresponding to each returned chunk"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -15114,7 +15196,8 @@
"chunks", "chunks",
"scores" "scores"
], ],
"title": "QueryChunksResponse" "title": "QueryChunksResponse",
"description": "Response from querying chunks in a vector database."
}, },
"QueryMetricsRequest": { "QueryMetricsRequest": {
"type": "object", "type": "object",

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

@ -2324,26 +2324,41 @@ paths:
type: string type: string
- name: limit - name: limit
in: query in: query
description: >-
(Optional) A limit on the number of objects to be returned. Limit can
range between 1 and 100, and the default is 20.
required: false required: false
schema: schema:
type: integer type: integer
- name: order - name: order
in: query in: query
description: >-
(Optional) Sort order by the `created_at` timestamp of the objects. `asc`
for ascending order and `desc` for descending order.
required: false required: false
schema: schema:
type: string type: string
- name: after - name: after
in: query in: query
description: >-
(Optional) A cursor for use in pagination. `after` is an object ID that
defines your place in the list.
required: false required: false
schema: schema:
type: string type: string
- name: before - name: before
in: query in: query
description: >-
(Optional) A cursor for use in pagination. `before` is an object ID that
defines your place in the list.
required: false required: false
schema: schema:
type: string type: string
- name: filter - name: filter
in: query in: query
description: >-
(Optional) Filter by file status to only return files with the specified
status.
required: false required: false
schema: schema:
$ref: '#/components/schemas/VectorStoreFileStatus' $ref: '#/components/schemas/VectorStoreFileStatus'
@ -5629,11 +5644,17 @@ components:
properties: properties:
ranker: ranker:
type: string type: string
description: >-
(Optional) Name of the ranking algorithm to use
score_threshold: score_threshold:
type: number type: number
default: 0.0 default: 0.0
description: >-
(Optional) Minimum relevance score threshold for results
additionalProperties: false additionalProperties: false
title: SearchRankingOptions title: SearchRankingOptions
description: >-
Options for ranking and filtering search results.
additionalProperties: false additionalProperties: false
required: required:
- type - type
@ -9013,10 +9034,14 @@ components:
type: string type: string
const: auto const: auto
default: auto default: auto
description: >-
Strategy type, always "auto" for automatic chunking
additionalProperties: false additionalProperties: false
required: required:
- type - type
title: VectorStoreChunkingStrategyAuto title: VectorStoreChunkingStrategyAuto
description: >-
Automatic chunking strategy for vector store files.
VectorStoreChunkingStrategyStatic: VectorStoreChunkingStrategyStatic:
type: object type: object
properties: properties:
@ -9024,27 +9049,39 @@ components:
type: string type: string
const: static const: static
default: static default: static
description: >-
Strategy type, always "static" for static chunking
static: static:
$ref: '#/components/schemas/VectorStoreChunkingStrategyStaticConfig' $ref: '#/components/schemas/VectorStoreChunkingStrategyStaticConfig'
description: >-
Configuration parameters for the static chunking strategy
additionalProperties: false additionalProperties: false
required: required:
- type - type
- static - static
title: VectorStoreChunkingStrategyStatic title: VectorStoreChunkingStrategyStatic
description: >-
Static chunking strategy with configurable parameters.
VectorStoreChunkingStrategyStaticConfig: VectorStoreChunkingStrategyStaticConfig:
type: object type: object
properties: properties:
chunk_overlap_tokens: chunk_overlap_tokens:
type: integer type: integer
default: 400 default: 400
description: >-
Number of tokens to overlap between adjacent chunks
max_chunk_size_tokens: max_chunk_size_tokens:
type: integer type: integer
default: 800 default: 800
description: >-
Maximum number of tokens per chunk, must be between 100 and 4096
additionalProperties: false additionalProperties: false
required: required:
- chunk_overlap_tokens - chunk_overlap_tokens
- max_chunk_size_tokens - max_chunk_size_tokens
title: VectorStoreChunkingStrategyStaticConfig title: VectorStoreChunkingStrategyStaticConfig
description: >-
Configuration for static chunking strategy.
OpenaiAttachFileToVectorStoreRequest: OpenaiAttachFileToVectorStoreRequest:
type: object type: object
properties: properties:
@ -9081,21 +9118,30 @@ components:
const: server_error const: server_error
- type: string - type: string
const: rate_limit_exceeded const: rate_limit_exceeded
description: >-
Error code indicating the type of failure
message: message:
type: string type: string
description: >-
Human-readable error message describing the failure
additionalProperties: false additionalProperties: false
required: required:
- code - code
- message - message
title: VectorStoreFileLastError title: VectorStoreFileLastError
description: >-
Error information for failed vector store file processing.
VectorStoreFileObject: VectorStoreFileObject:
type: object type: object
properties: properties:
id: id:
type: string type: string
description: Unique identifier for the file
object: object:
type: string type: string
default: vector_store.file default: vector_store.file
description: >-
Object type identifier, always "vector_store.file"
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -9106,19 +9152,31 @@ components:
- type: string - type: string
- type: array - type: array
- type: object - type: object
description: >-
Key-value attributes associated with the file
chunking_strategy: chunking_strategy:
$ref: '#/components/schemas/VectorStoreChunkingStrategy' $ref: '#/components/schemas/VectorStoreChunkingStrategy'
description: >-
Strategy used for splitting the file into chunks
created_at: created_at:
type: integer type: integer
description: >-
Timestamp when the file was added to the vector store
last_error: last_error:
$ref: '#/components/schemas/VectorStoreFileLastError' $ref: '#/components/schemas/VectorStoreFileLastError'
description: >-
(Optional) Error information if file processing failed
status: status:
$ref: '#/components/schemas/VectorStoreFileStatus' $ref: '#/components/schemas/VectorStoreFileStatus'
description: Current processing status of the file
usage_bytes: usage_bytes:
type: integer type: integer
default: 0 default: 0
description: Storage space used by this file in bytes
vector_store_id: vector_store_id:
type: string type: string
description: >-
ID of the vector store containing this file
additionalProperties: false additionalProperties: false
required: required:
- id - id
@ -9714,14 +9772,23 @@ components:
properties: properties:
completed: completed:
type: integer type: integer
description: >-
Number of files that have been successfully processed
cancelled: cancelled:
type: integer type: integer
description: >-
Number of files that had their processing cancelled
failed: failed:
type: integer type: integer
description: Number of files that failed to process
in_progress: in_progress:
type: integer type: integer
description: >-
Number of files currently being processed
total: total:
type: integer type: integer
description: >-
Total number of files in the vector store
additionalProperties: false additionalProperties: false
required: required:
- completed - completed
@ -9730,26 +9797,39 @@ components:
- in_progress - in_progress
- total - total
title: VectorStoreFileCounts title: VectorStoreFileCounts
description: >-
File processing status counts for a vector store.
VectorStoreObject: VectorStoreObject:
type: object type: object
properties: properties:
id: id:
type: string type: string
description: Unique identifier for the vector store
object: object:
type: string type: string
default: vector_store default: vector_store
description: >-
Object type identifier, always "vector_store"
created_at: created_at:
type: integer type: integer
description: >-
Timestamp when the vector store was created
name: name:
type: string type: string
description: (Optional) Name of the vector store
usage_bytes: usage_bytes:
type: integer type: integer
default: 0 default: 0
description: >-
Storage space used by the vector store in bytes
file_counts: file_counts:
$ref: '#/components/schemas/VectorStoreFileCounts' $ref: '#/components/schemas/VectorStoreFileCounts'
description: >-
File processing status counts for the vector store
status: status:
type: string type: string
default: completed default: completed
description: Current status of the vector store
expires_after: expires_after:
type: object type: object
additionalProperties: additionalProperties:
@ -9760,10 +9840,16 @@ components:
- type: string - type: string
- type: array - type: array
- type: object - type: object
description: >-
(Optional) Expiration policy for the vector store
expires_at: expires_at:
type: integer type: integer
description: >-
(Optional) Timestamp when the vector store will expire
last_active_at: last_active_at:
type: integer type: integer
description: >-
(Optional) Timestamp of last activity on the vector store
metadata: metadata:
type: object type: object
additionalProperties: additionalProperties:
@ -9774,6 +9860,8 @@ components:
- type: string - type: string
- type: array - type: array
- type: object - type: object
description: >-
Set of key-value pairs that can be attached to the vector store
additionalProperties: false additionalProperties: false
required: required:
- id - id
@ -9813,12 +9901,18 @@ components:
properties: properties:
id: id:
type: string type: string
description: >-
Unique identifier of the deleted vector store
object: object:
type: string type: string
default: vector_store.deleted default: vector_store.deleted
description: >-
Object type identifier for the deletion response
deleted: deleted:
type: boolean type: boolean
default: true default: true
description: >-
Whether the deletion operation was successful
additionalProperties: false additionalProperties: false
required: required:
- id - id
@ -9831,12 +9925,17 @@ components:
properties: properties:
id: id:
type: string type: string
description: Unique identifier of the deleted file
object: object:
type: string type: string
default: vector_store.file.deleted default: vector_store.file.deleted
description: >-
Object type identifier for the deletion response
deleted: deleted:
type: boolean type: boolean
default: true default: true
description: >-
Whether the deletion operation was successful
additionalProperties: false additionalProperties: false
required: required:
- id - id
@ -10042,24 +10141,33 @@ components:
object: object:
type: string type: string
default: list default: list
description: Object type identifier, always "list"
data: data:
type: array type: array
items: items:
$ref: '#/components/schemas/VectorStoreFileObject' $ref: '#/components/schemas/VectorStoreFileObject'
description: List of vector store file objects
first_id: first_id:
type: string type: string
description: >-
(Optional) ID of the first file in the list for pagination
last_id: last_id:
type: string type: string
description: >-
(Optional) ID of the last file in the list for pagination
has_more: has_more:
type: boolean type: boolean
default: false default: false
description: >-
Whether there are more files available beyond this page
additionalProperties: false additionalProperties: false
required: required:
- object - object
- data - data
- has_more - has_more
title: VectorStoreListFilesResponse title: VectorStoreListFilesResponse
description: Response from listing vector stores. description: >-
Response from listing files in a vector store.
OpenAIModel: OpenAIModel:
type: object type: object
properties: properties:
@ -10098,17 +10206,25 @@ components:
object: object:
type: string type: string
default: list default: list
description: Object type identifier, always "list"
data: data:
type: array type: array
items: items:
$ref: '#/components/schemas/VectorStoreObject' $ref: '#/components/schemas/VectorStoreObject'
description: List of vector store objects
first_id: first_id:
type: string type: string
description: >-
(Optional) ID of the first vector store in the list for pagination
last_id: last_id:
type: string type: string
description: >-
(Optional) ID of the last vector store in the list for pagination
has_more: has_more:
type: boolean type: boolean
default: false default: false
description: >-
Whether there are more vector stores available beyond this page
additionalProperties: false additionalProperties: false
required: required:
- object - object
@ -10125,20 +10241,27 @@ components:
type: type:
type: string type: string
const: text const: text
description: >-
Content type, currently only "text" is supported
text: text:
type: string type: string
description: The actual text content
additionalProperties: false additionalProperties: false
required: required:
- type - type
- text - text
title: VectorStoreContent title: VectorStoreContent
description: >-
Content item from a vector store file or search result.
VectorStoreFileContentsResponse: VectorStoreFileContentsResponse:
type: object type: object
properties: properties:
file_id: file_id:
type: string type: string
description: Unique identifier for the file
filename: filename:
type: string type: string
description: Name of the file
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -10149,10 +10272,13 @@ components:
- type: string - type: string
- type: array - type: array
- type: object - type: object
description: >-
Key-value attributes associated with the file
content: content:
type: array type: array
items: items:
$ref: '#/components/schemas/VectorStoreContent' $ref: '#/components/schemas/VectorStoreContent'
description: List of content items from the file
additionalProperties: false additionalProperties: false
required: required:
- file_id - file_id
@ -10194,9 +10320,13 @@ components:
properties: properties:
ranker: ranker:
type: string type: string
description: >-
(Optional) Name of the ranking algorithm to use
score_threshold: score_threshold:
type: number type: number
default: 0.0 default: 0.0
description: >-
(Optional) Minimum relevance score threshold for results
additionalProperties: false additionalProperties: false
description: >- description: >-
Ranking options for fine-tuning the search results. Ranking options for fine-tuning the search results.
@ -10218,10 +10348,14 @@ components:
properties: properties:
file_id: file_id:
type: string type: string
description: >-
Unique identifier of the file containing the result
filename: filename:
type: string type: string
description: Name of the file containing the result
score: score:
type: number type: number
description: Relevance score for this search result
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -10229,10 +10363,14 @@ components:
- type: string - type: string
- type: number - type: number
- type: boolean - type: boolean
description: >-
(Optional) Key-value attributes associated with the file
content: content:
type: array type: array
items: items:
$ref: '#/components/schemas/VectorStoreContent' $ref: '#/components/schemas/VectorStoreContent'
description: >-
List of content items matching the search query
additionalProperties: false additionalProperties: false
required: required:
- file_id - file_id
@ -10247,17 +10385,26 @@ components:
object: object:
type: string type: string
default: vector_store.search_results.page default: vector_store.search_results.page
description: >-
Object type identifier for the search results page
search_query: search_query:
type: string type: string
description: >-
The original search query that was executed
data: data:
type: array type: array
items: items:
$ref: '#/components/schemas/VectorStoreSearchResponse' $ref: '#/components/schemas/VectorStoreSearchResponse'
description: List of search result objects
has_more: has_more:
type: boolean type: boolean
default: false default: false
description: >-
Whether there are more results available beyond this page
next_page: next_page:
type: string type: string
description: >-
(Optional) Token for retrieving the next page of results
additionalProperties: false additionalProperties: false
required: required:
- object - object
@ -10265,7 +10412,8 @@ components:
- data - data
- has_more - has_more
title: VectorStoreSearchResponsePage title: VectorStoreSearchResponsePage
description: Response from searching a vector store. description: >-
Paginated response from searching a vector store.
OpenaiUpdateVectorStoreRequest: OpenaiUpdateVectorStoreRequest:
type: object type: object
properties: properties:
@ -10724,15 +10872,21 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/Chunk' $ref: '#/components/schemas/Chunk'
description: >-
List of content chunks returned from the query
scores: scores:
type: array type: array
items: items:
type: number type: number
description: >-
Relevance scores corresponding to each returned chunk
additionalProperties: false additionalProperties: false
required: required:
- chunks - chunks
- scores - scores
title: QueryChunksResponse title: QueryChunksResponse
description: >-
Response from querying chunks in a vector database.
QueryMetricsRequest: QueryMetricsRequest:
type: object type: object
properties: properties:

158
llama_stack/apis/vector_io/vector_io.py
View file

@ -94,12 +94,25 @@ class Chunk(BaseModel):
@json_schema_type @json_schema_type
class QueryChunksResponse(BaseModel): class QueryChunksResponse(BaseModel):
"""Response from querying chunks in a vector database.
:param chunks: List of content chunks returned from the query
:param scores: Relevance scores corresponding to each returned chunk
"""
chunks: list[Chunk] chunks: list[Chunk]
scores: list[float] scores: list[float]
@json_schema_type @json_schema_type
class VectorStoreFileCounts(BaseModel): class VectorStoreFileCounts(BaseModel):
"""File processing status counts for a vector store.
:param completed: Number of files that have been successfully processed
:param cancelled: Number of files that had their processing cancelled
:param failed: Number of files that failed to process
:param in_progress: Number of files currently being processed
:param total: Total number of files in the vector store
"""
completed: int completed: int
cancelled: int cancelled: int
failed: int failed: int
@ -109,7 +122,20 @@ class VectorStoreFileCounts(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreObject(BaseModel): class VectorStoreObject(BaseModel):
"""OpenAI Vector Store object.""" """OpenAI Vector Store object.
:param id: Unique identifier for the vector store
:param object: Object type identifier, always "vector_store"
:param created_at: Timestamp when the vector store was created
:param name: (Optional) Name of the vector store
:param usage_bytes: Storage space used by the vector store in bytes
:param file_counts: File processing status counts for the vector store
:param status: Current status of the vector store
:param expires_after: (Optional) Expiration policy for the vector store
:param expires_at: (Optional) Timestamp when the vector store will expire
:param last_active_at: (Optional) Timestamp of last activity on the vector store
:param metadata: Set of key-value pairs that can be attached to the vector store
"""
id: str id: str
object: str = "vector_store" object: str = "vector_store"
@ -126,7 +152,14 @@ class VectorStoreObject(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreCreateRequest(BaseModel): class VectorStoreCreateRequest(BaseModel):
"""Request to create a vector store.""" """Request to create a vector store.
:param name: (Optional) Name for the vector store
:param file_ids: List of file IDs to include in the vector store
:param expires_after: (Optional) Expiration policy for the vector store
:param chunking_strategy: (Optional) Strategy for splitting files into chunks
:param metadata: Set of key-value pairs that can be attached to the vector store
"""
name: str | None = None name: str | None = None
file_ids: list[str] = Field(default_factory=list) file_ids: list[str] = Field(default_factory=list)
@ -137,7 +170,12 @@ class VectorStoreCreateRequest(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreModifyRequest(BaseModel): class VectorStoreModifyRequest(BaseModel):
"""Request to modify a vector store.""" """Request to modify a vector store.
:param name: (Optional) Updated name for the vector store
:param expires_after: (Optional) Updated expiration policy for the vector store
:param metadata: (Optional) Updated set of key-value pairs for the vector store
"""
name: str | None = None name: str | None = None
expires_after: dict[str, Any] | None = None expires_after: dict[str, Any] | None = None
@ -146,7 +184,14 @@ class VectorStoreModifyRequest(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreListResponse(BaseModel): class VectorStoreListResponse(BaseModel):
"""Response from listing vector stores.""" """Response from listing vector stores.
:param object: Object type identifier, always "list"
:param data: List of vector store objects
:param first_id: (Optional) ID of the first vector store in the list for pagination
:param last_id: (Optional) ID of the last vector store in the list for pagination
:param has_more: Whether there are more vector stores available beyond this page
"""
object: str = "list" object: str = "list"
data: list[VectorStoreObject] data: list[VectorStoreObject]
@ -157,7 +202,14 @@ class VectorStoreListResponse(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreSearchRequest(BaseModel): class VectorStoreSearchRequest(BaseModel):
"""Request to search a vector store.""" """Request to search a vector store.
:param query: Search query as a string or list of strings
:param filters: (Optional) Filters based on file attributes to narrow search results
:param max_num_results: Maximum number of results to return, defaults to 10
:param ranking_options: (Optional) Options for ranking and filtering search results
:param rewrite_query: Whether to rewrite the query for better vector search performance
"""
query: str | list[str] query: str | list[str]
filters: dict[str, Any] | None = None filters: dict[str, Any] | None = None
@ -168,13 +220,25 @@ class VectorStoreSearchRequest(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreContent(BaseModel): class VectorStoreContent(BaseModel):
"""Content item from a vector store file or search result.
:param type: Content type, currently only "text" is supported
:param text: The actual text content
"""
type: Literal["text"] type: Literal["text"]
text: str text: str
@json_schema_type @json_schema_type
class VectorStoreSearchResponse(BaseModel): class VectorStoreSearchResponse(BaseModel):
"""Response from searching a vector store.""" """Response from searching a vector store.
:param file_id: Unique identifier of the file containing the result
:param filename: Name of the file containing the result
:param score: Relevance score for this search result
:param attributes: (Optional) Key-value attributes associated with the file
:param content: List of content items matching the search query
"""
file_id: str file_id: str
filename: str filename: str
@ -185,7 +249,14 @@ class VectorStoreSearchResponse(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreSearchResponsePage(BaseModel): class VectorStoreSearchResponsePage(BaseModel):
"""Response from searching a vector store.""" """Paginated response from searching a vector store.
:param object: Object type identifier for the search results page
:param search_query: The original search query that was executed
:param data: List of search result objects
:param has_more: Whether there are more results available beyond this page
:param next_page: (Optional) Token for retrieving the next page of results
"""
object: str = "vector_store.search_results.page" object: str = "vector_store.search_results.page"
search_query: str search_query: str
@ -196,7 +267,12 @@ class VectorStoreSearchResponsePage(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreDeleteResponse(BaseModel): class VectorStoreDeleteResponse(BaseModel):
"""Response from deleting a vector store.""" """Response from deleting a vector store.
:param id: Unique identifier of the deleted vector store
:param object: Object type identifier for the deletion response
:param deleted: Whether the deletion operation was successful
"""
id: str id: str
object: str = "vector_store.deleted" object: str = "vector_store.deleted"
@ -205,17 +281,31 @@ class VectorStoreDeleteResponse(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreChunkingStrategyAuto(BaseModel): class VectorStoreChunkingStrategyAuto(BaseModel):
"""Automatic chunking strategy for vector store files.
:param type: Strategy type, always "auto" for automatic chunking
"""
type: Literal["auto"] = "auto" type: Literal["auto"] = "auto"
@json_schema_type @json_schema_type
class VectorStoreChunkingStrategyStaticConfig(BaseModel): class VectorStoreChunkingStrategyStaticConfig(BaseModel):
"""Configuration for static chunking strategy.
:param chunk_overlap_tokens: Number of tokens to overlap between adjacent chunks
:param max_chunk_size_tokens: Maximum number of tokens per chunk, must be between 100 and 4096
"""
chunk_overlap_tokens: int = 400 chunk_overlap_tokens: int = 400
max_chunk_size_tokens: int = Field(800, ge=100, le=4096) max_chunk_size_tokens: int = Field(800, ge=100, le=4096)
@json_schema_type @json_schema_type
class VectorStoreChunkingStrategyStatic(BaseModel): class VectorStoreChunkingStrategyStatic(BaseModel):
"""Static chunking strategy with configurable parameters.
:param type: Strategy type, always "static" for static chunking
:param static: Configuration parameters for the static chunking strategy
"""
type: Literal["static"] = "static" type: Literal["static"] = "static"
static: VectorStoreChunkingStrategyStaticConfig static: VectorStoreChunkingStrategyStaticConfig
@ -227,6 +317,11 @@ register_schema(VectorStoreChunkingStrategy, name="VectorStoreChunkingStrategy")
class SearchRankingOptions(BaseModel): class SearchRankingOptions(BaseModel):
"""Options for ranking and filtering search results.
:param ranker: (Optional) Name of the ranking algorithm to use
:param score_threshold: (Optional) Minimum relevance score threshold for results
"""
ranker: str | None = None ranker: str | None = None
# NOTE: OpenAI File Search Tool requires threshold to be between 0 and 1, however # NOTE: OpenAI File Search Tool requires threshold to be between 0 and 1, however
# we don't guarantee that the score is between 0 and 1, so will leave this unconstrained # we don't guarantee that the score is between 0 and 1, so will leave this unconstrained
@ -236,6 +331,11 @@ class SearchRankingOptions(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreFileLastError(BaseModel): class VectorStoreFileLastError(BaseModel):
"""Error information for failed vector store file processing.
:param code: Error code indicating the type of failure
:param message: Human-readable error message describing the failure
"""
code: Literal["server_error"] | Literal["rate_limit_exceeded"] code: Literal["server_error"] | Literal["rate_limit_exceeded"]
message: str message: str
@ -246,7 +346,18 @@ register_schema(VectorStoreFileStatus, name="VectorStoreFileStatus")
@json_schema_type @json_schema_type
class VectorStoreFileObject(BaseModel): class VectorStoreFileObject(BaseModel):
"""OpenAI Vector Store File object.""" """OpenAI Vector Store File object.
:param id: Unique identifier for the file
:param object: Object type identifier, always "vector_store.file"
:param attributes: Key-value attributes associated with the file
:param chunking_strategy: Strategy used for splitting the file into chunks
:param created_at: Timestamp when the file was added to the vector store
:param last_error: (Optional) Error information if file processing failed
:param status: Current processing status of the file
:param usage_bytes: Storage space used by this file in bytes
:param vector_store_id: ID of the vector store containing this file
"""
id: str id: str
object: str = "vector_store.file" object: str = "vector_store.file"
@ -261,7 +372,14 @@ class VectorStoreFileObject(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreListFilesResponse(BaseModel): class VectorStoreListFilesResponse(BaseModel):
"""Response from listing vector stores.""" """Response from listing files in a vector store.
:param object: Object type identifier, always "list"
:param data: List of vector store file objects
:param first_id: (Optional) ID of the first file in the list for pagination
:param last_id: (Optional) ID of the last file in the list for pagination
:param has_more: Whether there are more files available beyond this page
"""
object: str = "list" object: str = "list"
data: list[VectorStoreFileObject] data: list[VectorStoreFileObject]
@ -272,7 +390,13 @@ class VectorStoreListFilesResponse(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreFileContentsResponse(BaseModel): class VectorStoreFileContentsResponse(BaseModel):
"""Response from retrieving the contents of a vector store file.""" """Response from retrieving the contents of a vector store file.
:param file_id: Unique identifier for the file
:param filename: Name of the file
:param attributes: Key-value attributes associated with the file
:param content: List of content items from the file
"""
file_id: str file_id: str
filename: str filename: str
@ -282,7 +406,12 @@ class VectorStoreFileContentsResponse(BaseModel):
@json_schema_type @json_schema_type
class VectorStoreFileDeleteResponse(BaseModel): class VectorStoreFileDeleteResponse(BaseModel):
"""Response from deleting a vector store file.""" """Response from deleting a vector store file.
:param id: Unique identifier of the deleted file
:param object: Object type identifier for the deletion response
:param deleted: Whether the deletion operation was successful
"""
id: str id: str
object: str = "vector_store.file.deleted" object: str = "vector_store.file.deleted"
@ -480,6 +609,11 @@ class VectorIO(Protocol):
"""List files in a vector store. """List files in a vector store.
:param vector_store_id: The ID of the vector store to list files from. :param vector_store_id: The ID of the vector store to list files from.
:param limit: (Optional) A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
:param order: (Optional) Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
:param after: (Optional) A cursor for use in pagination. `after` is an object ID that defines your place in the list.
:param before: (Optional) A cursor for use in pagination. `before` is an object ID that defines your place in the list.
:param filter: (Optional) Filter by file status to only return files with the specified status.
:returns: A VectorStoreListFilesResponse containing the list of files. :returns: A VectorStoreListFilesResponse containing the list of files.
""" """
... ...