Python Client API Reference
onecontext
OneContext
Initialize the OneContext client with an API key and base URL.
PARAMETER | DESCRIPTION |
---|---|
api_key |
The API key for authenticating requests to the OneContext API. If not provided, the environment variable 'ONECONTEXT_API_KEY' will be used. Defaults to None.
TYPE:
|
base_url |
The base URL for the OneContext API. Defaults to "https://api.onecontext.ai/v1/". Can be overridden with the environment variable 'ONECONTEXT_API_KEY'
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ConfigurationError
|
If no API key is provided and 'ONECONTEXT_API_KEY' environment variable is not set, a ConfigurationError is raised. |
create_knowledgebase
Create a new knowledge base with the given name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name for the new knowledge base.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
KnowledgeBase
|
An instance of the KnowledgeBase class initialized with the given name. |
delete_knowledgebase
Delete a knowledge base by its name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the knowledge base to delete.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
None
|
|
list_knowledgebases
List the available Knowledge Bases.
This method fetches a list of knowledge base dictionaries from the API and instantiates a list of KnowledgeBase objects with the provided information.
RETURNS | DESCRIPTION |
---|---|
List[KnowledgeBase]
|
A list of KnowledgeBase objects representing the available knowledge bases. |
KnowledgeBase
Factory method to create a KnowledgeBase object with the given name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the knowledge base to create.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
KnowledgeBase
|
An instance of KnowledgeBase associated with the provided name and the current client context. |
See Also
KnowledgeBase : The KnowledgeBase class that this method constructs instances of.
deploy_pipeline
Deploys a pipeline based on the provided YAML configuration.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the pipeline to be deployed.
TYPE:
|
pipeline_yaml_path |
The file path to the pipeline YAML configuration. It can be a string or a Path object. Provide pipeline_yaml_path or pipeline_yaml, not both.
TYPE:
|
pipeline_yaml |
The pipeline YAML configuration. Provide pipeline_yaml_path or pipeline_yaml, not both.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Pipeline
|
An instance of the deployed Pipeline. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the provided file path does not have a .yaml or .yml extension. |
delete_pipeline
Deletes a pipeline by name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the pipeline to delete.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
None
|
|
list_pipelines
Retrieve a list of Pipeline objects from the API.
RETURNS | DESCRIPTION |
---|---|
List[Pipeline]
|
A list of Pipeline objects. |
list_runs
list_runs(*, status=None, run_id=None, skip=0, limit=20, sort='date_created', date_created_gte=None, date_created_lte=None)
Retrieve a list of runs with optional filtering and sorting.
PARAMETER | DESCRIPTION |
---|---|
status |
The status of the runs to filter by.
TYPE:
|
run_id |
The unique identifier for a run to filter by.
TYPE:
|
skip |
The number of items to skip (for pagination), default is 0.
TYPE:
|
limit |
The maximum number of items to return, default is 20.
TYPE:
|
sort |
The field to sort the results by, default is 'date_created'. You can inverte the sort like so '-date_created'
TYPE:
|
date_created_gte |
The minimum creation date to filter by (greater than or equal to). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
date_created_lte |
The maximum creation date to filter by (less than or equal to). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[Dict[str, Any]]
|
A list of dictionaries containing the run information. |
Pipeline
Create a new Pipeline object with a specified name.
Use this to access existing pipelines.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the pipeline to create.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Pipeline
|
An instance of the Pipeline class initialized with the given name. |
create_vector_index
Creates a new vector index with the specified name and model.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the index to be created.
TYPE:
|
model |
The name of the model to use for the index.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
VectorIndex
|
An instance of |
Examples:
delete_vector_index
Delete a vecctor index base by its name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the vector index to delete.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
None
|
|
list_vector_indexes
Retrieve a list of VectorIndex objects from teh API.
RETURNS | DESCRIPTION |
---|---|
list of VectorIndex
|
A list of VectorIndex objects, each initialized with the index data and the reference to the current client and urls objects. |
VectorIndex
Create a new instance of VectorIndex with the specified name and model name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the VectorIndex.
TYPE:
|
model_name |
The name of the model associated with the VectorIndex, by default None.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
VectorIndex
|
An instance of VectorIndex with the given configuration. |
set_openai_key
Submit your OpenAI API key to OneContext
OneContext encrypts your key with a symmetric Google KMS key and only the ciphertext is stored on our servers.
You can learn more about symmetric Google KMS encryption here: https://cloud.google.com/kms/docs/encrypt-decrypt
PARAMETER | DESCRIPTION |
---|---|
openai_api_key |
The OpenAI API key to be used by the client.
TYPE:
|
Chunk
dataclass
A chunk of a file, stored in a vector index
ATTRIBUTE | DESCRIPTION |
---|---|
id |
A unique identifier for the chunk.
TYPE:
|
content |
The actual content of the chunk.
TYPE:
|
metadata_json |
A dictionary containing metadata about the chunk.
TYPE:
|
file_name |
The name of the file associated with the chunk.
TYPE:
|
chunk
Chunk
dataclass
A chunk of a file, stored in a vector index
ATTRIBUTE | DESCRIPTION |
---|---|
id |
A unique identifier for the chunk.
TYPE:
|
content |
The actual content of the chunk.
TYPE:
|
metadata_json |
A dictionary containing metadata about the chunk.
TYPE:
|
file_name |
The name of the file associated with the chunk.
TYPE:
|
index
VectorIndex
dataclass
A dataclass that represents a vector index in the OneContext API.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the vector index.
TYPE:
|
model_name |
The name of the model associated with this vector index.
TYPE:
|
_client |
An instance of the ApiClient.
TYPE:
|
_urls |
An instance of URLS containing the API endpoints.
TYPE:
|
list_chunks
list_chunks(file_names=None, file_ids=None, chunk_ids=None, skip=0, limit=200, sort='date_created', metadata_filters=None, date_created_gte=None, date_created_lte=None)
Lists chunks in the knowledge base with various filtering, sorting, and pagination options.
PARAMETER | DESCRIPTION |
---|---|
file_names |
A list of names of the files to filter results (default is None).
TYPE:
|
file_ids |
A list of IDs of the files to filter results (default is None).
TYPE:
|
chunk_ids |
A list of IDs of the chunks to filter results (default is None).
TYPE:
|
skip |
The number of chunks to skip (default is 0).
TYPE:
|
limit |
The maximum number of chunks to return (default is 200).
TYPE:
|
sort |
The field to sort by (default is "date_created"). Reverse with "-date_created"
TYPE:
|
metadata_filters |
A dictionary of metadata fields to filter results (default is None).
TYPE:
|
date_created_gte |
The minimum creation date of chunks to list (default is None). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
date_created_lte |
The maximum creation date of chunks to list (default is None). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[Chunk]
|
A list of Chunk objects that are the result of running the query |
list_files
list_files(skip=0, limit=500, sort='date_created', metadata_filters=None, date_created_gte=None, date_created_lte=None)
Lists files associated to the chunks in the vecotr index.
PARAMETER | DESCRIPTION |
---|---|
skip |
The number of files to skip (default is 0).
TYPE:
|
limit |
The maximum number of files to return (default is 20).
TYPE:
|
sort |
The field to sort by (default is "date_created"). Reverse with "-date_created"
TYPE:
|
metadata_filters |
A dictionary of metadata fields to filter results (default is None).
TYPE:
|
date_created_gte |
The minimum creation date of files to list (default is None). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
date_created_lte |
The maximum creation date of files to list (default is None). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[Dict[str, Any]]
|
A list of dictionaries, each representing a file with its metadata. |
knowledgebase
KnowledgeBase
dataclass
A class representing a knowledge base client to interact with an API for file management.
ATTRIBUTE | DESCRIPTION |
---|---|
name |
The name of the knowledge base.
TYPE:
|
_client |
The API client to make requests to the knowledge base.
TYPE:
|
_urls |
Object containing URL templates for API requests.
TYPE:
|
id |
The identifier for the knowledge base, by default None.
TYPE:
|
list_files
list_files(skip=0, limit=500, sort='date_created', metadata_filters=None, date_created_gte=None, date_created_lte=None)
Lists files in the knowledge base with various filtering, sorting, and pagination options.
PARAMETER | DESCRIPTION |
---|---|
skip |
The number of files to skip (default is 0).
TYPE:
|
limit |
The maximum number of files to return (default is 20).
TYPE:
|
sort |
The field to sort by (default is "date_created"). Reverse with "-date_created"
TYPE:
|
metadata_filters |
A dictionary of metadata fields to filter results (default is None).
TYPE:
|
date_created_gte |
The minimum creation date of files to list (default is None). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
date_created_lte |
The maximum creation date of files to list (default is None). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[Dict[str, Any]]
|
A list of dictionaries, each representing a file with its metadata. |
delete_files
Deletes a list of files from the knowledge base.
PARAMETER | DESCRIPTION |
---|---|
file_names |
A list of filenames as strings that are to be deleted.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
None
|
|
delete_duplicate_files
Deletes duplicate files by file_name in the knowledge_base
The most recent file for each duplicate file_name is retained
RETURNS | DESCRIPTION |
---|---|
None
|
|
upload_file
Uploads a file to the knowledge base.
This method uploads a file specified by file_path
to the knowledge base, optionally
associating it with metadata.
PARAMETER | DESCRIPTION |
---|---|
file_path |
The path to the file to be uploaded. Can be a string or a Path object.
TYPE:
|
metadata |
A dictionary containing metadata for the file. The keys "file_name", "knowledge_base", "user_id", "file_path", and "file_id" are reserved and cannot be used. If provided, it should not contain any of these keys. The default is None, which means no metadata will be associated with the file.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
list[str]
|
A list of pipeline run IDs generated after the file is uploaded. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If any reserved keys are present in the metadata. If the file type is not supported (not in SUPPORTED_FILE_TYPES). |
upload_text
Uploads a text string as a file to a knowledge base with optional metadata.
PARAMETER | DESCRIPTION |
---|---|
text |
The text content to be uploaded.
TYPE:
|
file_name |
The name of the file to be created. If the provided file_name does not end with '.txt', it is automatically modified to end with this extension.
TYPE:
|
metadata |
A dictionary containing metadata for the upload. There are reserved keys that cannot be used: 'file_name', 'knowledge_base', 'user_id', 'file_path', and 'file_id'. If any of these keys are present, a ValueError is raised.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
If any reserved key is present in the metadata dictionary. |
upload_from_directory
Uploads files from a given directory to a knowledgebase.
This method uploads all files within a specified directory that match the supported file types.
PARAMETER | DESCRIPTION |
---|---|
directory |
The path to the directory containing the files to be uploaded. Can be a string or a Path object.
TYPE:
|
metadata |
Metadata associated with the files to be uploaded. This can be a single dictionary applied to all files,
or a list of dictionaries with one dictionary for each file. If a list is provided, its length must match
the number of files. If omitted or
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the provided directory is not an actual directory or if the length of the metadata list does not match the number of files to be uploaded. |
main
OneContext
Initialize the OneContext client with an API key and base URL.
PARAMETER | DESCRIPTION |
---|---|
api_key |
The API key for authenticating requests to the OneContext API. If not provided, the environment variable 'ONECONTEXT_API_KEY' will be used. Defaults to None.
TYPE:
|
base_url |
The base URL for the OneContext API. Defaults to "https://api.onecontext.ai/v1/". Can be overridden with the environment variable 'ONECONTEXT_API_KEY'
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ConfigurationError
|
If no API key is provided and 'ONECONTEXT_API_KEY' environment variable is not set, a ConfigurationError is raised. |
create_knowledgebase
Create a new knowledge base with the given name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name for the new knowledge base.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
KnowledgeBase
|
An instance of the KnowledgeBase class initialized with the given name. |
delete_knowledgebase
Delete a knowledge base by its name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the knowledge base to delete.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
None
|
|
list_knowledgebases
List the available Knowledge Bases.
This method fetches a list of knowledge base dictionaries from the API and instantiates a list of KnowledgeBase objects with the provided information.
RETURNS | DESCRIPTION |
---|---|
List[KnowledgeBase]
|
A list of KnowledgeBase objects representing the available knowledge bases. |
KnowledgeBase
Factory method to create a KnowledgeBase object with the given name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the knowledge base to create.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
KnowledgeBase
|
An instance of KnowledgeBase associated with the provided name and the current client context. |
See Also
KnowledgeBase : The KnowledgeBase class that this method constructs instances of.
deploy_pipeline
Deploys a pipeline based on the provided YAML configuration.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the pipeline to be deployed.
TYPE:
|
pipeline_yaml_path |
The file path to the pipeline YAML configuration. It can be a string or a Path object. Provide pipeline_yaml_path or pipeline_yaml, not both.
TYPE:
|
pipeline_yaml |
The pipeline YAML configuration. Provide pipeline_yaml_path or pipeline_yaml, not both.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Pipeline
|
An instance of the deployed Pipeline. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the provided file path does not have a .yaml or .yml extension. |
delete_pipeline
Deletes a pipeline by name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the pipeline to delete.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
None
|
|
list_pipelines
Retrieve a list of Pipeline objects from the API.
RETURNS | DESCRIPTION |
---|---|
List[Pipeline]
|
A list of Pipeline objects. |
list_runs
list_runs(*, status=None, run_id=None, skip=0, limit=20, sort='date_created', date_created_gte=None, date_created_lte=None)
Retrieve a list of runs with optional filtering and sorting.
PARAMETER | DESCRIPTION |
---|---|
status |
The status of the runs to filter by.
TYPE:
|
run_id |
The unique identifier for a run to filter by.
TYPE:
|
skip |
The number of items to skip (for pagination), default is 0.
TYPE:
|
limit |
The maximum number of items to return, default is 20.
TYPE:
|
sort |
The field to sort the results by, default is 'date_created'. You can inverte the sort like so '-date_created'
TYPE:
|
date_created_gte |
The minimum creation date to filter by (greater than or equal to). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
date_created_lte |
The maximum creation date to filter by (less than or equal to). ISO 8601 Date Format Example: "2023-01-20T13:01:02Z"
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[Dict[str, Any]]
|
A list of dictionaries containing the run information. |
Pipeline
Create a new Pipeline object with a specified name.
Use this to access existing pipelines.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the pipeline to create.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Pipeline
|
An instance of the Pipeline class initialized with the given name. |
create_vector_index
Creates a new vector index with the specified name and model.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the index to be created.
TYPE:
|
model |
The name of the model to use for the index.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
VectorIndex
|
An instance of |
Examples:
delete_vector_index
Delete a vecctor index base by its name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the vector index to delete.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
None
|
|
list_vector_indexes
Retrieve a list of VectorIndex objects from teh API.
RETURNS | DESCRIPTION |
---|---|
list of VectorIndex
|
A list of VectorIndex objects, each initialized with the index data and the reference to the current client and urls objects. |
VectorIndex
Create a new instance of VectorIndex with the specified name and model name.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the VectorIndex.
TYPE:
|
model_name |
The name of the model associated with the VectorIndex, by default None.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
VectorIndex
|
An instance of VectorIndex with the given configuration. |
set_openai_key
Submit your OpenAI API key to OneContext
OneContext encrypts your key with a symmetric Google KMS key and only the ciphertext is stored on our servers.
You can learn more about symmetric Google KMS encryption here: https://cloud.google.com/kms/docs/encrypt-decrypt
PARAMETER | DESCRIPTION |
---|---|
openai_api_key |
The OpenAI API key to be used by the client.
TYPE:
|
pipeline
Chunk
dataclass
A chunk of a file, stored in a vector index
ATTRIBUTE | DESCRIPTION |
---|---|
id |
A unique identifier for the chunk.
TYPE:
|
content |
The actual content of the chunk.
TYPE:
|
metadata_json |
A dictionary containing metadata about the chunk.
TYPE:
|
file_name |
The name of the file associated with the chunk.
TYPE:
|
Pipeline
dataclass
A dataclass that represents a pipeline capable of interacting with an API client to perform various operations.
PARAMETER | DESCRIPTION |
---|---|
name |
The name of the pipeline.
TYPE:
|
id |
The unique identifier of the pipeline.
TYPE:
|
yaml_config |
The YAML configuration of the pipeline, if any.
TYPE:
|
run_results |
The results of the pipeline run, if any.
TYPE:
|
run_id |
The unique identifier of the run that is started when the pipeline is first deployed.
TYPE:
|
_client |
An instance of ApiClient to make API calls. This parameter is hidden in the representation of the object.
TYPE:
|
_urls |
An instance of URLS that contains the endpoint URLs required for API calls. This parameter is hidden in the representation of the object.
TYPE:
|
run
Runs the pipeline with optional override arguments.
PARAMETER | DESCRIPTION |
---|---|
override_args |
A dictionary of step names and step_args to override the default pipeline arguments, by default None.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[Chunk]
|
A list of Chunk objects that are the result of running the pipeline with the specified parameters. |
Examples:
>>> query_pipeline = oc.Pipeline("basic_query")
>>> query = "What are consequences of inventing a computer?"
>>> retriever_top_k = 50
>>> top_k = 5
>>> override_args = {
... "retriever": {
... "top_k": retriever_top_k,
... "query": query,
... },
... "reranker": {"top_k": top_k, "query": query},
... }
>>> chunks = query_pipeline.run(override_args)