Skip to content

Python Client API Reference

onecontext

OneContext

OneContext(api_key=None, base_url=None)

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: Optional[str] DEFAULT: None

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: str DEFAULT: None

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_knowledgebase(name)

Create a new knowledge base with the given name.

PARAMETER DESCRIPTION
name

The name for the new knowledge base.

TYPE: str

RETURNS DESCRIPTION
KnowledgeBase

An instance of the KnowledgeBase class initialized with the given name.

delete_knowledgebase

delete_knowledgebase(name)

Delete a knowledge base by its name.

PARAMETER DESCRIPTION
name

The name of the knowledge base to delete.

TYPE: str

RETURNS DESCRIPTION
None

list_knowledgebases

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

KnowledgeBase(name)

Factory method to create a KnowledgeBase object with the given name.

PARAMETER DESCRIPTION
name

The name of the knowledge base to create.

TYPE: str

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

deploy_pipeline(name, pipeline_yaml_path=None, pipeline_yaml=None)

Deploys a pipeline based on the provided YAML configuration.

PARAMETER DESCRIPTION
name

The name of the pipeline to be deployed.

TYPE: str

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: Optional[Union[Path, str]] DEFAULT: None

pipeline_yaml

The pipeline YAML configuration. Provide pipeline_yaml_path or pipeline_yaml, not both.

TYPE: Optional[str] DEFAULT: None

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

delete_pipeline(name)

Deletes a pipeline by name.

PARAMETER DESCRIPTION
name

The name of the pipeline to delete.

TYPE: str

RETURNS DESCRIPTION
None

list_pipelines

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: str DEFAULT: None

run_id

The unique identifier for a run to filter by.

TYPE: str DEFAULT: None

skip

The number of items to skip (for pagination), default is 0.

TYPE: int DEFAULT: 0

limit

The maximum number of items to return, default is 20.

TYPE: int DEFAULT: 20

sort

The field to sort the results by, default is 'date_created'. You can inverte the sort like so '-date_created'

TYPE: str DEFAULT: 'date_created'

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: str DEFAULT: None

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: str DEFAULT: None

RETURNS DESCRIPTION
List[Dict[str, Any]]

A list of dictionaries containing the run information.

Pipeline

Pipeline(name)

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: str

RETURNS DESCRIPTION
Pipeline

An instance of the Pipeline class initialized with the given name.

create_vector_index

create_vector_index(name, model)

Creates a new vector index with the specified name and model.

PARAMETER DESCRIPTION
name

The name of the index to be created.

TYPE: str

model

The name of the model to use for the index.

TYPE: str

RETURNS DESCRIPTION
VectorIndex

An instance of VectorIndex with the response data.

Examples:

>>> oc = OneContextContext(...)
>>> index = oc.create_vector_index('my_index', 'BAAI/bge-base-en-v1.5')

delete_vector_index

delete_vector_index(name)

Delete a vecctor index base by its name.

PARAMETER DESCRIPTION
name

The name of the vector index to delete.

TYPE: str

RETURNS DESCRIPTION
None

list_vector_indexes

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

VectorIndex(name, model_name=None)

Create a new instance of VectorIndex with the specified name and model name.

PARAMETER DESCRIPTION
name

The name of the VectorIndex.

TYPE: str

model_name

The name of the model associated with the VectorIndex, by default None.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
VectorIndex

An instance of VectorIndex with the given configuration.

set_openai_key

set_openai_key(openai_api_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: str

Chunk dataclass

Chunk(id, content, metadata_json=None, file_name=None, date_created=None)

A chunk of a file, stored in a vector index

ATTRIBUTE DESCRIPTION
id

A unique identifier for the chunk.

TYPE: str

content

The actual content of the chunk.

TYPE: str

metadata_json

A dictionary containing metadata about the chunk.

TYPE: (Optional[dict], optional)

file_name

The name of the file associated with the chunk.

TYPE: (str | None, optional)

chunk

Chunk dataclass

Chunk(id, content, metadata_json=None, file_name=None, date_created=None)

A chunk of a file, stored in a vector index

ATTRIBUTE DESCRIPTION
id

A unique identifier for the chunk.

TYPE: str

content

The actual content of the chunk.

TYPE: str

metadata_json

A dictionary containing metadata about the chunk.

TYPE: (Optional[dict], optional)

file_name

The name of the file associated with the chunk.

TYPE: (str | None, optional)

index

VectorIndex dataclass

VectorIndex(name, model_name, _client, _urls)

A dataclass that represents a vector index in the OneContext API.

PARAMETER DESCRIPTION
name

The name of the vector index.

TYPE: str

model_name

The name of the model associated with this vector index.

TYPE: str

_client

An instance of the ApiClient.

TYPE: ApiClient

_urls

An instance of URLS containing the API endpoints.

TYPE: URLS

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: list[str] DEFAULT: None

file_ids

A list of IDs of the files to filter results (default is None).

TYPE: list[str] DEFAULT: None

chunk_ids

A list of IDs of the chunks to filter results (default is None).

TYPE: list[str] DEFAULT: None

skip

The number of chunks to skip (default is 0).

TYPE: int DEFAULT: 0

limit

The maximum number of chunks to return (default is 200).

TYPE: int DEFAULT: 200

sort

The field to sort by (default is "date_created"). Reverse with "-date_created"

TYPE: str DEFAULT: 'date_created'

metadata_filters

A dictionary of metadata fields to filter results (default is None).

TYPE: dict DEFAULT: None

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: datetime DEFAULT: None

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: datetime DEFAULT: None

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: int DEFAULT: 0

limit

The maximum number of files to return (default is 20).

TYPE: int DEFAULT: 500

sort

The field to sort by (default is "date_created"). Reverse with "-date_created"

TYPE: str DEFAULT: 'date_created'

metadata_filters

A dictionary of metadata fields to filter results (default is None).

TYPE: dict DEFAULT: None

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: datetime DEFAULT: None

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: datetime DEFAULT: None

RETURNS DESCRIPTION
List[Dict[str, Any]]

A list of dictionaries, each representing a file with its metadata.

knowledgebase

KnowledgeBase dataclass

KnowledgeBase(name, _client, _urls, id=None)

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: str

_client

The API client to make requests to the knowledge base.

TYPE: ApiClient

_urls

Object containing URL templates for API requests.

TYPE: URLS

id

The identifier for the knowledge base, by default None.

TYPE: (Optional[str], optional)

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: int DEFAULT: 0

limit

The maximum number of files to return (default is 20).

TYPE: int DEFAULT: 500

sort

The field to sort by (default is "date_created"). Reverse with "-date_created"

TYPE: str DEFAULT: 'date_created'

metadata_filters

A dictionary of metadata fields to filter results (default is None).

TYPE: dict DEFAULT: None

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: datetime DEFAULT: None

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: datetime DEFAULT: None

RETURNS DESCRIPTION
List[Dict[str, Any]]

A list of dictionaries, each representing a file with its metadata.

delete_files
delete_files(file_names)

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: list[str]

RETURNS DESCRIPTION
None
delete_duplicate_files
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
upload_file(file_path, metadata=None)

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: Union[str, Path]

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: Optional[dict] DEFAULT: None

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
upload_text(text, file_name, metadata=None)

Uploads a text string as a file to a knowledge base with optional metadata.

PARAMETER DESCRIPTION
text

The text content to be uploaded.

TYPE: str

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: str

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: dict DEFAULT: None

RAISES DESCRIPTION
ValueError

If any reserved key is present in the metadata dictionary.

upload_from_directory
upload_from_directory(directory, metadata=None)

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: Union[str, Path]

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 None, no metadata will be applied.

TYPE: Optional[Union[dict, List[dict]]] DEFAULT: None

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

OneContext(api_key=None, base_url=None)

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: Optional[str] DEFAULT: None

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: str DEFAULT: None

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_knowledgebase(name)

Create a new knowledge base with the given name.

PARAMETER DESCRIPTION
name

The name for the new knowledge base.

TYPE: str

RETURNS DESCRIPTION
KnowledgeBase

An instance of the KnowledgeBase class initialized with the given name.

delete_knowledgebase
delete_knowledgebase(name)

Delete a knowledge base by its name.

PARAMETER DESCRIPTION
name

The name of the knowledge base to delete.

TYPE: str

RETURNS DESCRIPTION
None
list_knowledgebases
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
KnowledgeBase(name)

Factory method to create a KnowledgeBase object with the given name.

PARAMETER DESCRIPTION
name

The name of the knowledge base to create.

TYPE: str

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
deploy_pipeline(name, pipeline_yaml_path=None, pipeline_yaml=None)

Deploys a pipeline based on the provided YAML configuration.

PARAMETER DESCRIPTION
name

The name of the pipeline to be deployed.

TYPE: str

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: Optional[Union[Path, str]] DEFAULT: None

pipeline_yaml

The pipeline YAML configuration. Provide pipeline_yaml_path or pipeline_yaml, not both.

TYPE: Optional[str] DEFAULT: None

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
delete_pipeline(name)

Deletes a pipeline by name.

PARAMETER DESCRIPTION
name

The name of the pipeline to delete.

TYPE: str

RETURNS DESCRIPTION
None
list_pipelines
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: str DEFAULT: None

run_id

The unique identifier for a run to filter by.

TYPE: str DEFAULT: None

skip

The number of items to skip (for pagination), default is 0.

TYPE: int DEFAULT: 0

limit

The maximum number of items to return, default is 20.

TYPE: int DEFAULT: 20

sort

The field to sort the results by, default is 'date_created'. You can inverte the sort like so '-date_created'

TYPE: str DEFAULT: 'date_created'

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: str DEFAULT: None

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: str DEFAULT: None

RETURNS DESCRIPTION
List[Dict[str, Any]]

A list of dictionaries containing the run information.

Pipeline
Pipeline(name)

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: str

RETURNS DESCRIPTION
Pipeline

An instance of the Pipeline class initialized with the given name.

create_vector_index
create_vector_index(name, model)

Creates a new vector index with the specified name and model.

PARAMETER DESCRIPTION
name

The name of the index to be created.

TYPE: str

model

The name of the model to use for the index.

TYPE: str

RETURNS DESCRIPTION
VectorIndex

An instance of VectorIndex with the response data.

Examples:

>>> oc = OneContextContext(...)
>>> index = oc.create_vector_index('my_index', 'BAAI/bge-base-en-v1.5')
delete_vector_index
delete_vector_index(name)

Delete a vecctor index base by its name.

PARAMETER DESCRIPTION
name

The name of the vector index to delete.

TYPE: str

RETURNS DESCRIPTION
None
list_vector_indexes
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
VectorIndex(name, model_name=None)

Create a new instance of VectorIndex with the specified name and model name.

PARAMETER DESCRIPTION
name

The name of the VectorIndex.

TYPE: str

model_name

The name of the model associated with the VectorIndex, by default None.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
VectorIndex

An instance of VectorIndex with the given configuration.

set_openai_key
set_openai_key(openai_api_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: str

pipeline

Chunk dataclass

Chunk(id, content, metadata_json=None, file_name=None, date_created=None)

A chunk of a file, stored in a vector index

ATTRIBUTE DESCRIPTION
id

A unique identifier for the chunk.

TYPE: str

content

The actual content of the chunk.

TYPE: str

metadata_json

A dictionary containing metadata about the chunk.

TYPE: (Optional[dict], optional)

file_name

The name of the file associated with the chunk.

TYPE: (str | None, optional)

Pipeline dataclass

Pipeline(_client, _urls, name, id=None, yaml_config=None, run_id=None)

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: str

id

The unique identifier of the pipeline.

TYPE: Optional[str] DEFAULT: None

yaml_config

The YAML configuration of the pipeline, if any.

TYPE: Optional[str] DEFAULT: None

run_results

The results of the pipeline run, if any.

TYPE: Optional[str] DEFAULT: None

run_id

The unique identifier of the run that is started when the pipeline is first deployed.

TYPE: Optional[str] DEFAULT: None

_client

An instance of ApiClient to make API calls. This parameter is hidden in the representation of the object.

TYPE: ApiClient

_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: URLS

run
run(override_args=None)

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: dict[str, Any] DEFAULT: None

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)