Skip to content

README.md

Latest commit

 

History

History
1025 lines (683 loc) · 108 KB

README.md

File metadata and controls

1025 lines (683 loc) · 108 KB
Raw

Knowledge

Overview

Available Operations

list

Returns a list of your knowledge bases. The knowledge bases are returned sorted by creation date, with the most recent knowledge bases appearing first

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.list(limit=25)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
starting_after Optional[str] ➖ A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include after=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the next page of the list.
ending_before Optional[str] ➖ A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include before=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the previous page of the list.
limit Optional[int] ➖ A limit on the number of objects to be returned. Limit can range between 1 and 300, and the default is 25
search Optional[str] ➖ Filter knowledge bases by key (case-insensitive match)
updated_by Optional[str] ➖ Filter by the users who last updated the knowledge base. Accepts a comma-separated list of user IDs
type Optional[models.ListKnowledgeBasesQueryParamType] ➖ Filter knowledge bases by type
project_id Optional[str] ➖ Filter knowledge bases by project ID
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.KnowledgeBasesServiceListResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

create

Creates an internal or external knowledge base. Internal knowledge bases embed and index uploaded content; external knowledge bases query the configured external retrieval API.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create(request={
        "type": "internal",
        "key": "<key>",
        "embedding_model": "<value>",
        "path": "Default",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
request models.KnowledgeBasesServiceCreateRequest ✔️ The request object to use for the request.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Knowledge

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

retrieve

Retrieve a knowledge base with the settings.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.retrieve(knowledge_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Knowledge

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

delete

Deletes a knowledge base. Deleting a knowledge base will delete all the datasources and chunks associated with it.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    orq.knowledge.delete(knowledge_id="<id>")

    # Use the SDK ...

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

update

Updates a knowledge base. Omitted optional fields retain their current values.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.update(knowledge_id="<id>", knowledge_bases_service_update_request={
        "path": "Default",
        "type": "external",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
knowledge_bases_service_update_request models.KnowledgeBasesServiceUpdateRequest ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Knowledge

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

list_datasources

Returns the datasources in a knowledge base. Use cursors to page through results and optional query or status filters to narrow the list.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.list_datasources(knowledge_id="<id>", limit=50, status=[
        "completed",
        "failed",
    ])

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ Unique identifier of the knowledge base
starting_after Optional[str] ➖ A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include after=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the next page of the list.
ending_before Optional[str] ➖ A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include before=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the previous page of the list.
q Optional[str] ➖ Search query to find datasources by name.
limit Optional[int] ➖ A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 10
status Optional[models.QueryParamStatus] ➖ Filter datasources by status.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.DatasourcesServiceListResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

create_datasource

Creates a datasource shell when only a display name is provided. When file_id is provided, the uploaded file is queued for chunking and ingestion.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create_datasource(knowledge_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
display_name Optional[str] ➖ N/A
description OptionalNullable[str] ➖ The description of the knowledge base
file_id Optional[str] ➖ N/A
chunking_options Optional[models.DatasourceChunkingOptions] ➖ N/A
id Optional[str] ➖ Compatibility fields used by the former datasource shell/legacy route.
attachment Optional[models.DatasourceAttachment] ➖ N/A
metadata Optional[models.CountMetadata] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Datasource

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

preview_chunks

Parses an uploaded file and returns the chunks it would produce for the given chunking options without creating a datasource.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.preview_chunks(knowledge_id="<id>", file_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
file_id str ✔️ N/A
chunking_options Optional[models.DatasourceChunkingOptions] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.DatasourcesServicePreviewChunksResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

retrieve_datasource

Retrieves a datasource and its current processing status and chunk count.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.retrieve_datasource(knowledge_id="<id>", datasource_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Datasource

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

delete_datasource

Deletes a datasource from a knowledge base. Deleting a datasource will remove it from the knowledge base and all associated chunks. This action is irreversible and cannot be undone.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    orq.knowledge.delete_datasource(knowledge_id="<id>", datasource_id="<id>")

    # Use the SDK ...

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

update_datasource

Updates the display name of a datasource.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.update_datasource(knowledge_id="<id>", datasource_id="<id>", display_name="Tony_Roberts")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
display_name str ✔️ N/A Product handbook
description OptionalNullable[str] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Datasource

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

list_chunks

Returns chunks using cursor pagination, with optional text and processing-status filters.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.list_chunks(knowledge_id="<id>", datasource_id="<id>", limit=10, status=[
        "completed",
        "failed",
    ])

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ The unique identifier of the knowledge base
datasource_id str ✔️ The unique identifier of the datasource.
limit Optional[int] ➖ A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 10
starting_after Optional[str] ➖ A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include after=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the next page of the list.
ending_before Optional[str] ➖ A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with 01JJ1HDHN79XAS7A01WB3HYSDB, your subsequent call can include before=01JJ1HDHN79XAS7A01WB3HYSDB in order to fetch the previous page of the list.
q Optional[str] ➖ Search query to find datasources by name.
status Optional[models.ListChunksQueryParamStatus] ➖ Filter chunks by status.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ChunksServiceListResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

create_chunks

Creates between 1 and 100 chunks. Chunks with supplied embeddings are indexed immediately; chunks without embeddings are queued for embedding.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create_chunks(knowledge_id="<id>", datasource_id="<id>", request_body=[])

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
request_body List[models.UpsertChunk] ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

List[models.KnowledgeChunk]

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

delete_chunks

Deletes up to 100 chunks and reports IDs that were not found or could not be deleted.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.delete_chunks(knowledge_id="<id>", datasource_id="<id>", chunk_ids=[
        "<value 1>",
        "<value 2>",
    ])

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
chunk_ids List[str] ✔️ Array of chunk IDs to delete
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ChunksServiceDeleteManyResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

get_chunks_count

Returns the total count of chunks in a datasource. When q is provided, the count reflects indexed chunks only — recently created chunks may not be counted until embedding completes.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.get_chunks_count(knowledge_id="<id>", datasource_id="<id>", q="")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
q Optional[str] ➖ N/A
enabled Optional[bool] ➖ N/A
status Optional[models.ChunksServiceCountRequestStatus] ➖ Filter chunks by processing status
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ChunksServiceCountResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

list_chunks_paginated

Returns a page of chunks, with optional text, enabled-state, and processing-status filters.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.list_chunks_paginated(knowledge_id="<id>", datasource_id="<id>", q="", limit=100, page=1)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
q Optional[str] ➖ N/A
enabled Optional[bool] ➖ N/A
status Optional[models.ChunksServiceListPaginatedRequestStatus] ➖ Filter chunks by processing status
limit Optional[int] ➖ N/A
page Optional[int] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ChunksServiceListPaginatedResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

retrieve_chunk

Retrieves a chunk by its chunk identifier.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.retrieve_chunk(knowledge_id="<id>", datasource_id="<id>", chunk_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
chunk_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.KnowledgeChunk

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

delete_chunk

Deletes a chunk from the datasource and its vector index.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    orq.knowledge.delete_chunk(knowledge_id="<id>", datasource_id="<id>", chunk_id="<id>")

    # Use the SDK ...

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
chunk_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

update_chunk

Updates chunk text, metadata, or a supplied embedding. Changing text without an embedding queues the chunk for re-embedding.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.update_chunk(knowledge_id="<id>", datasource_id="<id>", chunk_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
chunk_id str ✔️ N/A
text Optional[str] ➖ The text content of the chunk
embedding List[float] ➖ N/A
metadata Dict[str, models.ChunksServiceUpdateRequestMetadata] ➖ Metadata of the chunk
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.KnowledgeChunk

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

toggle_chunk

Enables or disables a chunk for retrieval. If the vector-index document is missing, enabling the chunk queues it for embedding.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.toggle_chunk(knowledge_id="<id>", datasource_id="<id>", chunk_id="<id>", enabled=True)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
chunk_id str ✔️ N/A
enabled bool ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.KnowledgeChunk

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

retrieve_processing_status

Returns aggregate queued, completed, passed, and failed chunk counts together with the datasource and chunk processing attempts.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.retrieve_processing_status(knowledge_id="<id>", datasource_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
datasource_id str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.DatasourcesServiceGetProcessingStatusResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

search

Search a Knowledge Base and return the most similar chunks, along with their search and rerank scores. Note that all configuration changes made in the API will override the settings in the UI.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.search(knowledge_id="<id>", query="<value>", rerank_config={
        "model": "cohere/rerank-multilingual-v3.0",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ The unique identifier or key of the knowledge base.
query str ✔️ The query to use to search the knowledge base
top_k Optional[int] ➖ The number of results to return. If not provided, will default to the knowledge base configured top_k.
threshold Optional[float] ➖ The threshold to apply to the search. If not provided, will default to the knowledge base configured threshold
search_type Optional[models.SearchType] ➖ N/A
filter_by Optional[models.FilterBy] ➖ The metadata filter to apply to the search. Check the Searching a Knowledge Base for more information.
search_options Optional[models.SearchOptions] ➖ Additional search options
rerank_config Optional[models.SearchRerankConfig] ➖ Override the rerank configuration for this search. If not provided, will use the knowledge base configured rerank settings.
agentic_rag_config OptionalNullable[models.SearchKnowledgeRequestAgenticRagConfig] ➖ Override the agentic RAG configuration for this search. If not provided, will use the knowledge base configured agentic RAG settings.
retrieval_config Optional[models.SearchRetrievalConfig] ➖ Override the stored retrieval configuration for this search. If not provided, the knowledge base configuration is used.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.SearchKnowledgeResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

retrieve_file_url

Creates a presigned upload policy for a file that will be attached to a knowledge-base datasource. Submit the returned form fields and file directly to the returned URL.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.retrieve_file_url(knowledge_id="<id>", file_name="example.file", content_type="<value>", datasource_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
knowledge_id str ✔️ N/A
file_name str ✔️ The name of the file to upload.
content_type str ✔️ The media type of the file to upload.
datasource_id str ✔️ The datasource identifier that will own the uploaded file.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetUploadFileURLResponse

Errors

Error Type Status Code Content Type
models.KnowledgeAPIError 500 application/json
models.APIDefaultError 4XX, 5XX */*