Lifecycle
new
One of the strings listed in
EmbeddingModel. Defaults to the platform default if omitted.Chunking + analysis options. See
IndexingConfig.fetch
id or name. Exactly one is required.
list
delete
Folders
create_folder
folder_id to any add_* method to ingest into a specific folder, or use move_items to reorganise afterwards.
Ingestion
Every ingestion call returns anIngestionTask. The _and_wait variants poll until the task reaches COMPLETED or FAILED; the bare variants return immediately and let you drive the polling yourself via ingestion_status.
add_files
Path, raw bytes, or a file-like object.
add_files_and_wait
add_files. Polls until the task reaches a terminal status or timeout elapses. Raises KbIngestionTimeout on timeout, KbIngestionFailed if the task ends in FAILED.
add_urls
UrlConfig.
add_urls_and_wait
add_urls.
add_folder / add_folder_and_wait
_and_wait blocks until done (default timeout=600).
add_tables / add_tables_and_wait
_and_wait variant blocks until done.
ingestion_status
add_* call to drive your own polling loop.
Querying
query
Metadata filters. See
FilterClause.Enable hybrid (vector + keyword) retrieval. See
HybridConfig.Cross-encoder rerank over the top candidates. See
RerankConfig.Run an LLM over the retrieved context and populate
result["answer"]. The backend may still return no answer, so treat answer as optional. See QaConfig.Pass a pre-built
QueryConfig instead of individual kwargs. Cannot be combined with other tuning kwargs.Typed
QueryResult TypedDict — use dict-key access: result["chunks"], result["citations"] (may be empty), result.get("answer") (optional — may be absent/empty), result.get("usage") (optional).Items
list_items
scroll
list_items would require manual cursor management.
get_item
move_items
create_folder).
delete_items
update_item_metadata
FilterClause.
Accessors
A KB exposes three accessor objects for scoped operations. They keep the top-level surface lean by routing item / folder / metadata-autogen calls through dedicated handles.item
folder
folder_id= to ingestion calls or list_items).
metadata_autogen
autogen_id.
create_config
extraction_instructions tells the LLM what to extract from each item; query_instructions controls how that metadata is matched at retrieval time. traversal_type is one of "document", "folder", or "chunk".
list_configs
get_config
replace_config
get_config and merge if you only want to change one field.
delete_config
run
IngestionTask you can poll, or use the wait variant below.
run_and_wait
metadata-autogen example for the full lifecycle.
Integrations
integrations
resync_integration
set_rescrape_frequency
item_id / integration_id. See RescrapeFrequency.
Types
IndexingConfig
See
SplitterMethod.UrlConfig
See
RescrapeFrequency.QueryConfig
Pre-built bundle of every option query(...) accepts as kwargs. Pass config= instead of individual kwargs when you want to reuse a config across queries.
HybridConfig
RerankConfig
QaConfig
See
QaMode.FilterClause
See
FilterOperator.SortClause
See
SortDirection.IngestionTask
The handle returned by every add_* call. Reaches a terminal status (COMPLETED, FAILED, or WARNING) once indexing finishes.
See
IngestionStatus.QueryResult
The typed return of kb.query(...). It is a TypedDict — access fields by key (result["chunks"], result.get("answer")), not by attribute.
LLM-generated answer when
qa=QaConfig(mode=...) is set. Optional key — may be absent even with qa set (access via result.get("answer")).RetrievedChunk
Enums
EmbeddingModel
String literal. Supported values:
"text-embedding-3-large""text-embedding-3-small""text-embedding-ada-002""embed-v4.0""voyage-3"·"voyage-4"·"voyage-multimodal-3"·"voyage-code-3""google-text-embedding-004"·"google-text-embedding-005""together-bge-large-en-v1.5"·"together-m2-bert-80M-8k-retrieval"
SplitterMethod
MARKDOWN · SENTENCE · DYNAMIC · CODE
RescrapeFrequency
NEVER · QUARTER_HOURLY · HOURLY · DAILY · WEEKLY · MONTHLY
QaMode
OFF · FAST · ACCURATE
FilterOperator
EQ · NE (NEQ) · CONTAINS · IN · NOT_IN (NIN) · GT · GTE · LT · LTE
IngestionStatus
StrEnum — member names are uppercase, but .value is lowercase (e.g. IngestionStatus.COMPLETED.value == "completed"). Members: PENDING ("pending") · IN_PROGRESS ("in_progress") · PROCESSING ("processing") · COMPLETED ("completed") · SUCCESS ("success") · FAILED ("failed") · WARNING ("warning").
SortDirection
ASC · DESC
Errors
The KB module raises a small set of typed errors. Catch them by name; all subclassKnowledgeBaseError, which in turn subclasses VectorshiftError.
KbNotFound— KB id/name doesn’t exist (or your key can’t see it).KbIngestionFailed— an ingestion task ended inFAILED.KbIngestionTimeout—add_*_and_waitexceeded itstimeout.KbIntegrationNotFound,KbIntegrationRevoked— integration resolution problems.
What’s next
Overview
Mental model and quick start.
RAG end-to-end guide
Wrap a KB as a tool on a conversational Agent.
RAG pipeline example
Compose a KB reader into a Pipeline.
