On this page

Python SDK method reference

For a runnable example, see Python and TypeScript SDKs. The SDK generates the reference source from its public contextbase exports and tests it against the package.

contextbase.API_VERSION

API_VERSION = 'v1'

contextbase.MINIMUM_SERVER_VERSION

MINIMUM_SERVER_VERSION = '0.1.0'

contextbase.APIConnectionError

The server could not be reached, or did not answer in time.

contextbase.APIError

The server answered with an error status.

status_code and body are what came back. When the body is the server’s refusal, detail holds its sentences, reason the machine name of the refusal (None when it gives none) and names the things the refusal is about; payload is the decoded body, whatever its shape.

APIError.__init__(self, message: 'str', *, status_code: 'int', body: 'bytes', payload: 'Any' = None, headers: 'Mapping[str, str] | None' = None) -> 'None'

Keep the answer, and read the refusal it carries, if any.

contextbase.Answer

A query’s publication outcome and its public execution summary.

A blocked outcome carries no published text. query_id locates its authorized inspection record; postgeneration is the server’s redacted summary, not the protected candidate history.

Answer.from_payload(cls, payload: 'QueryAnswerPayload') -> 'Answer'

The answer a generated payload describes.

Answer.__init__(self, answer: 'str', sources: 'list[Source]', query_id: 'str | None' = None, outcome: 'QueryAnswerPayloadOutcome' = <QueryAnswerPayloadOutcome.ACCEPTED: 'accepted'>, postgeneration: 'PostGenerationTrace | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.AsyncContextBase

A connection to one ContextBase server.

The key and the address come from the arguments, or else from CONTEXTBASE_API_KEY and CONTEXTBASE_BASE_URL. Without an address there is nothing to connect to, so that is refused at once; without a key only meta() and check_compatibility() can be made, and every other call raises MissingAPIKeyError before sending anything.

A request the server answers with 429 or 503 is asked again, up to max_retries times, where repeating it is safe; contextbase._retry says which requests those are and how long each wait is.

AsyncContextBase.__init__(self, api_key: 'str | None' = None, base_url: 'str | None' = None, *, timeout: 'float' = 60.0, max_retries: 'int' = 2) -> 'None'

Remember where the server is and how to authenticate to it.

AsyncContextBase.public_raw

The shared generated connection for public, keyless operations.

AsyncContextBase.raw

The generated client underneath, for an operation not covered here.

It shares this client’s connection, key and timeout, and is typed as the generated operations take it, so list_spaces.sync(client=client.raw) type-checks. Without a key there is no such client, and asking for it raises MissingAPIKeyError.

AsyncContextBase.meta(self) -> 'ServerMeta'

Which server this is: its release and the API version it serves.

Needs no key, so it is also the way to check an address before anything else is done with it.

AsyncContextBase.check_compatibility(self) -> 'ServerMeta'

Describe the server, refusing one this client is not written for.

Raises IncompatibleServerError when the server serves another API version, is older than MINIMUM_SERVER_VERSION, or reports a release that cannot be read as a version. A pre-release of the minimum itself (0.1.0.dev3 against 0.1.0) counts as older: it may lack what the release it leads to added.

AsyncContextBase.aclose(self) -> 'None'

Close the connection to the server.

contextbase.AsyncDocuments

The documents of one space.

AsyncDocuments.__init__(self, caller: 'AsyncCaller', space_id: 'str | UUID') -> 'None'

Calls on the documents of space_id, sent through caller.

AsyncDocuments.upload(self, source: 'Upload', *, filename: 'str | None' = None, name: 'str | None' = None, metadata: 'Mapping[str, Any] | None' = None, content_type: 'str | None' = None) -> 'Document'

Upload a document and return it as the server stored it.

source is a path, the file’s bytes, or a file open for binary reading. filename is what the server is told the file is called; a path and a named file give their own, bytes need one. name is the document’s display name, metadata what it says about itself. The server may index asynchronously; wait_indexed observes the document’s indexing status after acceptance. An open file is read and left open: closing it is the caller’s.

AsyncDocuments.list(self, *, status: 'DocumentStatus | str | None' = None, name: 'str | None' = None, content_type: 'str | None' = None) -> 'AsyncIterator[Document]'

Every document of the space, a page at a time.

status, name and content_type narrow the listing the way the server’s own filters do.

AsyncDocuments.get(self, document_id: 'str | UUID') -> 'Document'

The document with this id.

AsyncDocuments.update_metadata(self, document_id: 'str | UUID', metadata: 'Mapping[str, Any]') -> 'Document'

Replace what the document says about itself, and return it.

The map given replaces the one stored whole; a field left out is removed.

AsyncDocuments.delete(self, document_id: 'str | UUID') -> 'None'

Accept deletion; physical cleanup may finish after this call.

AsyncDocuments.request_delete(self, document_id: 'str | UUID', *, command_id: 'str | UUID | None' = None) -> 'UUID'

Accept deletion and return its retained operation UUID.

Reusing command_id identifies the same deletion command. Read get_operation to observe completion after the document disappears. A missing or malformed operation header raises APIError without repeating the accepted request.

AsyncDocuments.activate(self, document_id: 'str | UUID', *, command_id: 'str | UUID') -> 'DocumentOperationStatus'

Accept activation identified by the caller’s stable UUID.

AsyncDocuments.deactivate(self, document_id: 'str | UUID', *, command_id: 'str | UUID') -> 'DocumentOperationStatus'

Accept deactivation identified by the caller’s stable UUID.

AsyncDocuments.reindex(self, document_id: 'str | UUID', *, command_id: 'str | UUID') -> 'DocumentOperationStatus'

Accept reindexing identified by the caller’s stable UUID.

AsyncDocuments.get_operation(self, operation_id: 'str | UUID') -> 'DocumentOperationStatus'

Read retained operation status independently of the document.

AsyncDocuments.wait_indexed(self, documents: 'Iterable[str | UUID | Document] | None' = None, *, timeout: 'float' = 300.0, interval: 'float' = 1.0) -> 'builtins.list[Document]'

Wait until the documents are indexed, and return them as they are.

documents are ids or documents; without them, every document of the space is waited for. When timeout seconds pass first, IndexingTimeoutError is raised carrying how each stood at the last look.

contextbase.AsyncEvalDatasets

The evaluation datasets of the key’s owner.

AsyncEvalDatasets.__init__(self, caller: 'AsyncCaller') -> 'None'

Calls on evaluation datasets, sent through caller.

AsyncEvalDatasets.create(self, name: 'str', *, corpus: 'Iterable[CorpusDocument | Mapping[str, Any]]', queries: 'Iterable[EvaluationQuery | Mapping[str, Any]]') -> 'EvaluationDatasetSummary'

Store a dataset and return what the server made of it.

corpus holds the passages (id and text); queries the questions, each optionally with the corpus ids that answer it and a golden answer. Either is given as models from contextbase.types or as mappings of the same shape. One larger than the server accepts raises PayloadTooLargeError.

AsyncEvalDatasets.upload(self, path: 'str | os.PathLike[str]', *, name: 'str | None' = None) -> 'EvaluationDatasetSummary'

Store the dataset a JSON file describes.

The file holds one object with corpus and queries in the shape create takes, and a name; name given here wins over the file’s, and one of the two is needed.

AsyncEvalDatasets.list(self) -> 'AsyncIterator[EvaluationDatasetSummary]'

Every dataset of the key’s owner, a page at a time.

AsyncEvalDatasets.get(self, dataset: 'Dataset | UUID') -> 'EvaluationDatasetSummary'

The dataset named.

AsyncEvalDatasets.delete(self, dataset: 'Dataset | UUID') -> 'None'

Delete the dataset, and the runs made with it.

The runs sit in spaces, so the key needs manage on each space a run of it was made in; otherwise PermissionDeniedError is raised with the reason evaluation_dataset_runs_beyond_reach.

contextbase.AsyncEvaluations

The evaluation runs of one space; every call needs manage on it.

AsyncEvaluations.__init__(self, caller: 'AsyncCaller', space_id: 'str | UUID') -> 'None'

Calls on the runs of space_id, sent through caller.

AsyncEvaluations.run(self, dataset: 'Dataset | UUID', *, top_k: 'int | None' = None, query_concurrency: 'int | None' = None, judge_model: 'str | None' = None, space_use: 'EvaluationSpaceUse | str | None' = None, wait: 'bool' = True, timeout: 'float' = 3600.0, interval: 'float' = 2.0, on_progress: 'Callable[[EvaluationRunSummary], object] | None' = None) -> 'EvaluationRunSummary'

Score the space against dataset and return the run.

Unless wait is false the call waits for the run to finish, handing each look at it to on_progress. A run that fails raises EvaluationFailedError with the reason the server gives; one still going after timeout seconds raises EvaluationTimeoutError, whose message names its stage and how far it got. What is left out here, the server’s defaults decide.

AsyncEvaluations.get(self, run: 'Run | UUID') -> 'EvaluationRunSummary'

The run named, as it stands now.

AsyncEvaluations.list(self) -> 'AsyncIterator[EvaluationRunSummary]'

Every run of the space, newest first, a page at a time.

AsyncEvaluations.queries(self, run: 'Run | UUID') -> 'AsyncIterator[EvaluationQueryOutcomeSummary]'

How each question of the run went, in the dataset’s order.

AsyncEvaluations.assessments(self, run: 'Run | UUID') -> 'AsyncIterator[AnswerAssessmentSummary]'

Every judging of the run’s answers, a page at a time.

AsyncEvaluations.compare(self, run_a: 'Run | UUID', run_b: 'Run | UUID') -> 'EvaluationRunPairedComparison'

Two finished runs of the space, compared question by question.

contextbase.AsyncPipeline

The building blocks of a space’s pipeline, as this server offers them.

Readable with any key, whatever it was granted.

AsyncPipeline.__init__(self, caller: 'AsyncCaller') -> 'None'

Calls on the pipeline catalogue, sent through caller.

AsyncPipeline.catalog(self) -> 'dict[str, dict[str, CatalogNode]]'

Every node a pipeline can use, by kind and then by name.

A kind is a slot of PipelineConfig – chunk, retrievers, rerank and the rest – and each node carries the schema of its parameters and how its stage is shown.

AsyncPipeline.presets(self) -> 'list[PipelinePresetView]'

The ready-made pipelines this server offers, each with its config.

A preset’s pipeline is a PipelineConfig to hand to a space’s config.apply.

contextbase.AsyncSpace

One space, and the calls made on it.

id, name, owner, created_at, role (the key owner’s role in it) and grant (the key’s level on it) are what the server last said; raw is that answer whole – the full description for a space fetched or created, the summary for one from a listing. documents, config and evaluations hold the calls on the space’s documents, its pipeline and its evaluation runs.

AsyncSpace.__init__(self, caller: 'AsyncCaller', payload: 'SpaceFullPayload | SpaceSummaryPayload') -> 'None'

A space as payload describes it, reached through caller.

AsyncSpace.query(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None) -> 'Answer'

Ask a question and get the answer with the passages it rests on.

metadata_filter narrows which documents are searched: a MetadataFilter from contextbase.types, or a mapping of the same shape.

AsyncSpace.query_stream(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None) -> 'AsyncIterator[StreamEvent]'

Ask a question and get the answer as it is written.

Yields Stage and Check progress, a Token for each published fragment, and then a Done carrying the publication outcome or an ErrorEvent if execution failed. Done.answer.outcome separates a blocked answer from an accepted one. A refusal before the answer starts is raised, as any call’s is. Only connecting is held to the client’s timeout: an answer is read for as long as it takes to write.

AsyncSpace.search(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None, rrf_k: 'int | None' = None) -> 'list[Source]'

Return ranked passages, optionally tuning RRF for this request.

AsyncSpace.search_with_receipt(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None, rrf_k: 'int | None' = None) -> 'SearchResult'

Return sources and the server’s actual retrieval settings receipt.

AsyncSpace.delete(self, *, appended_rows: 'AppendedRows | None' = None) -> 'None'

Delete the space; delete on the client’s spaces says how.

contextbase.AsyncSpaceConfig

The pipeline of one space.

Reading it needs any grant on the space; checking, applying and rebuilding need manage.

AsyncSpaceConfig.__init__(self, caller: 'AsyncCaller', space_id: 'str | UUID') -> 'None'

Calls on the pipeline of space_id, sent through caller.

AsyncSpaceConfig.get(self) -> 'PipelineConfig'

The pipeline the space runs now.

AsyncSpaceConfig.status(self) -> 'PipelineConfigStatus'

Whether the space is rebuilding, and each index’s state.

AsyncSpaceConfig.validate(self, config: 'PipelineConfig | Mapping[str, Any]') -> 'PreflightReport'

What the server’s preflight checks say of config, applied here.

Nothing is changed. The report’s status says whether the config could be applied as it stands.

AsyncSpaceConfig.apply(self, config: 'PipelineConfig | Mapping[str, Any]', *, force: 'bool' = False, wait: 'bool' = True, start_timeout: 'float' = 60.0, timeout: 'float' = 1800.0, interval: 'float' = 2.0, on_progress: 'Callable[[PipelineConfigStatus], object] | None' = None) -> 'ConfigChange[PipelineUpdateResult]'

Make config the space’s pipeline.

A config the preflight checks refuse raises PreflightBlockedError carrying their report; force pushes past checks that only failed to reach a resource. When the server answers that the change rebuilds the indexes, the call waits for the rebuild unless wait is false: up to start_timeout seconds for it to begin, raising RebuildNotStartedError if it does not, then up to timeout seconds for it to end, raising RebuildTimeoutError. Each status seen is handed to on_progress. A pass over attached storage is reported in storage_pass and not waited for.

AsyncSpaceConfig.reindex(self, *, force: 'bool' = False, wait: 'bool' = True, start_timeout: 'float' = 60.0, timeout: 'float' = 1800.0, interval: 'float' = 2.0, on_progress: 'Callable[[PipelineConfigStatus], object] | None' = None) -> 'ConfigChange[PipelineReindexResult]'

Rebuild the space’s indexes from its documents, as apply does.

contextbase.AsyncSpaces

The spaces the client’s key can reach.

AsyncSpaces.__init__(self, caller: 'AsyncCaller') -> 'None'

Calls on spaces, sent through caller.

AsyncSpaces.list(self, *, sort: 'ListSpacesSort | str | None' = None) -> 'AsyncIterator[AsyncSpace]'

Every reachable space, ordered on the server before pagination.

AsyncSpaces.get(self, space_id: 'str | UUID') -> 'AsyncSpace'

The space with this id.

AsyncSpaces.create(self, name: 'str', *, llm_config: 'SpaceLLMConfig | Mapping[str, Any] | None' = None, config: 'PipelineConfig | Mapping[str, Any] | None' = None, embedding_model_id: 'str | UUID | None' = None, vector_backend_id: 'str | UUID | None' = None, outbound_config: 'SpaceOutboundConfig | Mapping[str, Any] | None' = None, extraction_config: 'SpaceExtractionConfig | Mapping[str, Any] | None' = None) -> 'AsyncSpace'

Create a space and return it.

Everything but the name is optional; what is left out, the installation’s defaults decide. A configuration is a model from contextbase.types or a mapping of the same shape. A key that creates a space is granted manage on it.

AsyncSpaces.delete(self, space_id: 'str | UUID', *, appended_rows: 'AppendedRows | None' = None) -> 'None'

Delete the space and everything in it.

A key needs manage on the space. A space over storage this platform did not make first raises PreconditionRequiredError asking what to do with the rows it added there; answer by calling again with appended_rows='keep' or 'purge'.

contextbase.AuthenticationError

401: the key was missing, unknown or revoked.

contextbase.BadGatewayError

502: something the server relies on failed.

contextbase.BadRequestError

400: the request was refused as it stood.

contextbase.Check

A check’s progress, identified across correction attempts.

Check.__init__(self, node_id: 'str | None' = None, attempt_id: 'str | None' = None, phase: 'str | None' = None, verdict: 'str | None' = None, action: 'str | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.ConfigChange

What changing a space’s pipeline did, and where its indexes stand.

result is the server’s answer to the change itself. status is the space’s status once the rebuild ended; it is None when nothing was waited for – the change started no rebuild, or wait=False was passed. stale names the indexes the status still reports as out of date once nothing is building: ones no worker is rebuilding, which a reindex would. storage_pass is true when the change started a pass over storage this platform did not make; that pass runs on its own and is not waited for – the space’s storage index, through the client’s raw, says where it stands.

ConfigChange.__init__(self, result: 'Result', status: 'PipelineConfigStatus | None', stale: 'list[str]', storage_pass: 'bool') -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.ConflictError

409: the request conflicts with the state of what it names.

contextbase.ContextBase

A connection to one ContextBase server.

The key and the address come from the arguments, or else from CONTEXTBASE_API_KEY and CONTEXTBASE_BASE_URL. Without an address there is nothing to connect to, so that is refused at once; without a key only meta() and check_compatibility() can be made, and every other call raises MissingAPIKeyError before sending anything.

A request the server answers with 429 or 503 is asked again, up to max_retries times, where repeating it is safe; contextbase._retry says which requests those are and how long each wait is.

ContextBase.__init__(self, api_key: 'str | None' = None, base_url: 'str | None' = None, *, timeout: 'float' = 60.0, max_retries: 'int' = 2) -> 'None'

Remember where the server is and how to authenticate to it.

ContextBase.public_raw

The shared generated connection for public, keyless operations.

ContextBase.raw

The generated client underneath, for an operation not covered here.

It shares this client’s connection, key and timeout, and is typed as the generated operations take it, so list_spaces.sync(client=client.raw) type-checks. Without a key there is no such client, and asking for it raises MissingAPIKeyError.

ContextBase.meta(self) -> 'ServerMeta'

Which server this is: its release and the API version it serves.

Needs no key, so it is also the way to check an address before anything else is done with it.

ContextBase.check_compatibility(self) -> 'ServerMeta'

Describe the server, refusing one this client is not written for.

Raises IncompatibleServerError when the server serves another API version, is older than MINIMUM_SERVER_VERSION, or reports a release that cannot be read as a version. A pre-release of the minimum itself (0.1.0.dev3 against 0.1.0) counts as older: it may lack what the release it leads to added.

ContextBase.close(self) -> 'None'

Close the connection to the server.

contextbase.ContextBaseError

Anything the SDK raises.

contextbase.Document

A document in a space, as the server last described it.

chunk_count comes with a listing and not with a single document, so it is None on a document fetched, uploaded or edited one at a time.

Document.indexed

Whether ingestion reports the document as indexed.

Document.from_payload(cls, payload: 'DocumentFullPayload | DocumentSummaryPayload') -> 'Document'

The document a generated payload describes.

Document.__init__(self, id: 'str', name: 'str', status: 'DocumentStatus', is_active: 'bool', content_type: 'str', size: 'int | None', created_at: 'str', metadata: 'dict[str, Any]' = <factory>, chunk_count: 'int | None' = None, raw: 'DocumentFullPayload | DocumentSummaryPayload | None' = None, extracted_char_count: 'int | Unset | None' = UNSET, group: 'DocumentGroup | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.DocumentGroup

A Space-scoped view over compatible accepted copies.

ivar id:

vartype id:

UUID

ivar representative_id:

vartype representative_id:

str

ivar members:

vartype members:

list[DocumentGroupMember]

DocumentGroup.to_dict(self) -> 'dict[str, Any]'
DocumentGroup.from_dict(cls, src_dict: 'Mapping[str, Any]') -> 'Self'
DocumentGroup.additional_keys
DocumentGroup.__init__(self, id: 'UUID', representative_id: 'str', members: 'list[DocumentGroupMember]') -> None

Method generated by attrs for class DocumentGroup.

contextbase.DocumentGroupMember

One independent copy; actions address this document UUID.

ivar id:

vartype id:

str

ivar name:

vartype name:

str

ivar status:

Where a document stands in the ingest pipeline, as a client reads it.

uploaded – the original is stored and its indexing has not finished; indexed – its chunks are written and retrievable. The stored column keeps its own matching vocabulary on the model, and a completeness test binds the two.

vartype status:

DocumentIngestStatus

ivar is_active:

vartype is_active:

bool

ivar origin:

Display attribution without an external address or storage identity.

vartype origin:

DocumentOrigin

DocumentGroupMember.to_dict(self) -> 'dict[str, Any]'
DocumentGroupMember.from_dict(cls, src_dict: 'Mapping[str, Any]') -> 'Self'
DocumentGroupMember.additional_keys
DocumentGroupMember.__init__(self, id: 'str', name: 'str', status: 'DocumentIngestStatus', is_active: 'bool', origin: 'DocumentOrigin') -> None

Method generated by attrs for class DocumentGroupMember.

contextbase.DocumentOrigin

Display attribution without an external address or storage identity.

ivar kind:

Default: DocumentOriginKind.MANUAL.

vartype kind:

DocumentOriginKind | Unset

ivar source_id:

vartype source_id:

None | Unset | UUID

ivar source_name:

vartype source_name:

None | str | Unset

DocumentOrigin.to_dict(self) -> 'dict[str, Any]'
DocumentOrigin.from_dict(cls, src_dict: 'Mapping[str, Any]') -> 'Self'
DocumentOrigin.additional_keys
DocumentOrigin.__init__(self, kind: 'DocumentOriginKind | Unset' = <DocumentOriginKind.MANUAL: 'manual'>, source_id: 'None | Unset | UUID' = UNSET, source_name: 'None | str | Unset' = UNSET) -> None

Method generated by attrs for class DocumentOrigin.

contextbase.DocumentStatus

Enum where members are also (and must be) strings

contextbase.Documents

The documents of one space.

Documents.__init__(self, caller: 'Caller', space_id: 'str | UUID') -> 'None'

Calls on the documents of space_id, sent through caller.

Documents.upload(self, source: 'Upload', *, filename: 'str | None' = None, name: 'str | None' = None, metadata: 'Mapping[str, Any] | None' = None, content_type: 'str | None' = None) -> 'Document'

Upload a document and return it as the server stored it.

source is a path, the file’s bytes, or a file open for binary reading. filename is what the server is told the file is called; a path and a named file give their own, bytes need one. name is the document’s display name, metadata what it says about itself. The server may index asynchronously; wait_indexed observes the document’s indexing status after acceptance. An open file is read and left open: closing it is the caller’s.

Documents.list(self, *, status: 'DocumentStatus | str | None' = None, name: 'str | None' = None, content_type: 'str | None' = None) -> 'Iterator[Document]'

Every document of the space, a page at a time.

status, name and content_type narrow the listing the way the server’s own filters do.

Documents.get(self, document_id: 'str | UUID') -> 'Document'

The document with this id.

Documents.update_metadata(self, document_id: 'str | UUID', metadata: 'Mapping[str, Any]') -> 'Document'

Replace what the document says about itself, and return it.

The map given replaces the one stored whole; a field left out is removed.

Documents.delete(self, document_id: 'str | UUID') -> 'None'

Accept deletion; physical cleanup may finish after this call.

Documents.request_delete(self, document_id: 'str | UUID', *, command_id: 'str | UUID | None' = None) -> 'UUID'

Accept deletion and return its retained operation UUID.

Reusing command_id identifies the same deletion command. Read get_operation to observe completion after the document disappears. A missing or malformed operation header raises APIError without repeating the accepted request.

Documents.activate(self, document_id: 'str | UUID', *, command_id: 'str | UUID') -> 'DocumentOperationStatus'

Accept activation identified by the caller’s stable UUID.

Documents.deactivate(self, document_id: 'str | UUID', *, command_id: 'str | UUID') -> 'DocumentOperationStatus'

Accept deactivation identified by the caller’s stable UUID.

Documents.reindex(self, document_id: 'str | UUID', *, command_id: 'str | UUID') -> 'DocumentOperationStatus'

Accept reindexing identified by the caller’s stable UUID.

Documents.get_operation(self, operation_id: 'str | UUID') -> 'DocumentOperationStatus'

Read retained operation status independently of the document.

Documents.wait_indexed(self, documents: 'Iterable[str | UUID | Document] | None' = None, *, timeout: 'float' = 300.0, interval: 'float' = 1.0) -> 'builtins.list[Document]'

Wait until the documents are indexed, and return them as they are.

documents are ids or documents; without them, every document of the space is waited for. When timeout seconds pass first, IndexingTimeoutError is raised carrying how each stood at the last look.

contextbase.Done

A streamed query completed with its publication outcome.

Done.__init__(self, answer: 'Answer') -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.EquivalentPassageGroup

Compatible passages keep a real representative and per-copy addresses.

ivar id:

vartype id:

UUID

ivar representative_id:

vartype representative_id:

str

ivar members:

vartype members:

list[EquivalentPassageMember]

EquivalentPassageGroup.to_dict(self) -> 'dict[str, Any]'
EquivalentPassageGroup.from_dict(cls, src_dict: 'Mapping[str, Any]') -> 'Self'
EquivalentPassageGroup.additional_keys
EquivalentPassageGroup.__init__(self, id: 'UUID', representative_id: 'str', members: 'list[EquivalentPassageMember]') -> None

Method generated by attrs for class EquivalentPassageGroup.

contextbase.EquivalentPassageMember

One canonical copy of the same admitted grounding passage.

ivar id:

vartype id:

str

ivar document_id:

vartype document_id:

UUID

ivar document_name:

vartype document_name:

str

ivar origin:

Display attribution without an external address or storage identity.

vartype origin:

DocumentOrigin

ivar locator:

vartype locator:

None | SourceLocator | Unset

ivar processing:

vartype processing:

None | SourceProcessing | Unset

ivar bibliography:

vartype bibliography:

None | SourceBibliography | Unset

ivar parent_locator:

vartype parent_locator:

None | SourceLocator | Unset

ivar parent_processing:

vartype parent_processing:

None | SourceProcessing | Unset

ivar parent_bibliography:

vartype parent_bibliography:

None | SourceBibliography | Unset

EquivalentPassageMember.to_dict(self) -> 'dict[str, Any]'
EquivalentPassageMember.from_dict(cls, src_dict: 'Mapping[str, Any]') -> 'Self'
EquivalentPassageMember.additional_keys
EquivalentPassageMember.__init__(self, id: 'str', document_id: 'UUID', document_name: 'str', origin: 'DocumentOrigin', locator: 'None | SourceLocator | Unset' = UNSET, processing: 'None | SourceProcessing | Unset' = UNSET, bibliography: 'None | SourceBibliography | Unset' = UNSET, parent_locator: 'None | SourceLocator | Unset' = UNSET, parent_processing: 'None | SourceProcessing | Unset' = UNSET, parent_bibliography: 'None | SourceBibliography | Unset' = UNSET) -> None

Method generated by attrs for class EquivalentPassageMember.

contextbase.ErrorEvent

A streamed answer failed after it had started; the server ends there.

reason and names are what a refusal answered with a status would carry in its body: the name to match a refusal on, and what it is about, as values. Where the failure names nothing, reason is None and names is empty.

ErrorEvent.__init__(self, detail: 'str', reason: 'str | None' = None, names: 'tuple[str, ...]' = (), query_id: 'str | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.EvalDatasets

The evaluation datasets of the key’s owner.

EvalDatasets.__init__(self, caller: 'Caller') -> 'None'

Calls on evaluation datasets, sent through caller.

EvalDatasets.create(self, name: 'str', *, corpus: 'Iterable[CorpusDocument | Mapping[str, Any]]', queries: 'Iterable[EvaluationQuery | Mapping[str, Any]]') -> 'EvaluationDatasetSummary'

Store a dataset and return what the server made of it.

corpus holds the passages (id and text); queries the questions, each optionally with the corpus ids that answer it and a golden answer. Either is given as models from contextbase.types or as mappings of the same shape. One larger than the server accepts raises PayloadTooLargeError.

EvalDatasets.upload(self, path: 'str | os.PathLike[str]', *, name: 'str | None' = None) -> 'EvaluationDatasetSummary'

Store the dataset a JSON file describes.

The file holds one object with corpus and queries in the shape create takes, and a name; name given here wins over the file’s, and one of the two is needed.

EvalDatasets.list(self) -> 'Iterator[EvaluationDatasetSummary]'

Every dataset of the key’s owner, a page at a time.

EvalDatasets.get(self, dataset: 'Dataset | UUID') -> 'EvaluationDatasetSummary'

The dataset named.

EvalDatasets.delete(self, dataset: 'Dataset | UUID') -> 'None'

Delete the dataset, and the runs made with it.

The runs sit in spaces, so the key needs manage on each space a run of it was made in; otherwise PermissionDeniedError is raised with the reason evaluation_dataset_runs_beyond_reach.

contextbase.EvaluationFailedError

An evaluation run stopped without results.

run is the run as the server last described it, and reason why it stopped: timed_out, abandoned or error, as the server’s EvaluationRunFailure names them, or None when it gave none.

EvaluationFailedError.__init__(self, message: 'str', run: 'EvaluationRunSummary') -> 'None'

Keep the failed run beside the message.

contextbase.EvaluationTimeoutError

An evaluation run had not finished; run is the last look at it.

EvaluationTimeoutError.__init__(self, message: 'str', run: 'EvaluationRunSummary') -> 'None'

Keep the run’s last state beside the message.

contextbase.Evaluations

The evaluation runs of one space; every call needs manage on it.

Evaluations.__init__(self, caller: 'Caller', space_id: 'str | UUID') -> 'None'

Calls on the runs of space_id, sent through caller.

Evaluations.run(self, dataset: 'Dataset | UUID', *, top_k: 'int | None' = None, query_concurrency: 'int | None' = None, judge_model: 'str | None' = None, space_use: 'EvaluationSpaceUse | str | None' = None, wait: 'bool' = True, timeout: 'float' = 3600.0, interval: 'float' = 2.0, on_progress: 'Callable[[EvaluationRunSummary], object] | None' = None) -> 'EvaluationRunSummary'

Score the space against dataset and return the run.

Unless wait is false the call waits for the run to finish, handing each look at it to on_progress. A run that fails raises EvaluationFailedError with the reason the server gives; one still going after timeout seconds raises EvaluationTimeoutError, whose message names its stage and how far it got. What is left out here, the server’s defaults decide.

Evaluations.get(self, run: 'Run | UUID') -> 'EvaluationRunSummary'

The run named, as it stands now.

Evaluations.list(self) -> 'Iterator[EvaluationRunSummary]'

Every run of the space, newest first, a page at a time.

Evaluations.queries(self, run: 'Run | UUID') -> 'Iterator[EvaluationQueryOutcomeSummary]'

How each question of the run went, in the dataset’s order.

Evaluations.assessments(self, run: 'Run | UUID') -> 'Iterator[AnswerAssessmentSummary]'

Every judging of the run’s answers, a page at a time.

Evaluations.compare(self, run_a: 'Run | UUID', run_b: 'Run | UUID') -> 'EvaluationRunPairedComparison'

Two finished runs of the space, compared question by question.

contextbase.IncompatibleServerError

The server is older than this client supports, or speaks another API.

contextbase.IndexingTimeoutError

Documents were not all indexed in time.

documents is how each stood at the last look.

IndexingTimeoutError.__init__(self, message: 'str', documents: 'list[Document]') -> 'None'

Keep the documents’ last state beside the message.

contextbase.MissingAPIKeyError

A call that needs a key was made by a client that has none.

contextbase.NotFoundError

404: what was asked for does not exist, or the key cannot see it.

contextbase.PayloadTooLargeError

413: the upload is larger than the server accepts.

contextbase.PermissionDeniedError

403: the key reaches the space but may not do this there.

contextbase.Pipeline

The building blocks of a space’s pipeline, as this server offers them.

Readable with any key, whatever it was granted.

Pipeline.__init__(self, caller: 'Caller') -> 'None'

Calls on the pipeline catalogue, sent through caller.

Pipeline.catalog(self) -> 'dict[str, dict[str, CatalogNode]]'

Every node a pipeline can use, by kind and then by name.

A kind is a slot of PipelineConfig – chunk, retrievers, rerank and the rest – and each node carries the schema of its parameters and how its stage is shown.

Pipeline.presets(self) -> 'list[PipelinePresetView]'

The ready-made pipelines this server offers, each with its config.

A preset’s pipeline is a PipelineConfig to hand to a space’s config.apply.

contextbase.PreconditionRequiredError

428: the server needs a confirmation before it goes on.

payload holds what it wants confirmed.

contextbase.PreflightBlockedError

A configuration was refused by its preflight checks.

Raised as one of the two below, by the status the refusal came with, so it is caught by what it means here and by its status as either class.

report is the server’s preflight report: every finding, and whether force could push past them – a report whose status is blocked_by_probe_only blocks only on resources that did not answer.

PreflightBlockedError.__init__(self, message: 'str', report: 'PreflightReport', **answer: 'Any') -> 'None'

Keep the report beside the answer.

contextbase.PreflightConflictError

409: the checks refused the configuration as it conflicts.

contextbase.PreflightUnprocessableError

422: the checks refused the configuration as unusable.

contextbase.RateLimitError

429: too many requests; retried where that is safe, then raised.

contextbase.RebuildNotStartedError

No rebuild of a space began in time; status is the last look.

The server accepted the change, and no worker took it up: the indexes are as they were before it.

RebuildNotStartedError.__init__(self, message: 'str', status: 'PipelineConfigStatus') -> 'None'

Keep the last status beside the message.

contextbase.RebuildTimeoutError

A space’s indexes were still rebuilding; status is the last look.

RebuildTimeoutError.__init__(self, message: 'str', status: 'PipelineConfigStatus') -> 'None'

Keep the last status beside the message.

contextbase.RetrievalReceipt

The server’s actual masked pipeline identities and rank setting.

RetrievalReceipt.__init__(self, base_pipeline_fingerprint: 'str', effective_pipeline_fingerprint: 'str', rrf_k: 'int | None', override_applied: 'bool') -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.SearchResult

Ranked sources together with their recorded execution identity.

SearchResult.from_payload(cls, payload: 'RetrieveResultPayload') -> 'SearchResult'

Keep a legacy server’s absent execution receipt explicitly absent.

SearchResult.__init__(self, sources: 'list[Source]', query_id: 'str | None', retrieval_receipt: 'RetrievalReceipt | None') -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.ServerError

5xx: the server failed to answer.

contextbase.ServerMeta

Which server answered: its release and the API version it serves.

ServerMeta.__init__(self, server_version: 'str', api_version: 'str') -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.ServiceUnavailableError

503: the server could not answer in time; retried where safe.

contextbase.Source

A retrieved passage, and what else the server knows about it.

parent_text is a wider cut of the same document, graph_context what the knowledge graph says about the passage; either may be absent.

Source.from_payload(cls, payload: 'QuerySource') -> 'Source'

The source a generated payload describes.

Source.__init__(self, id: 'str', text: 'str', score: 'float | None' = None, parent_text: 'str | None' = None, graph_context: 'str | None' = None, locator: 'SourceLocator | None' = None, processing: 'SourceProcessing | None' = None, parent_locator: 'SourceLocator | None' = None, parent_processing: 'SourceProcessing | None' = None, document_id: 'UUID | None' = None, bibliography: 'SourceBibliography | None' = None, parent_bibliography: 'SourceBibliography | None' = None, group: 'EquivalentPassageGroup | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.SourceBibliography

Canonical title and document-owner author, year and reference.

These are display metadata, independent of verified source ranges. The reference is not a derived original download; syntax validation cannot prove public access or absence of secrets in owner-authored values.

SourceBibliography.from_payload(cls, payload: 'SourceBibliographyPayload | None') -> 'SourceBibliography | None'

Preserve optional metadata without inventing missing fields.

SourceBibliography.__init__(self, title: 'str | None' = None, author: 'str | None' = None, year: 'int | None' = None, url: 'str | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.SourceLocator

A verified range in a document’s retained Unicode source text.

SourceLocator.from_payload(cls, payload: 'SourceLocatorPayload | None') -> 'SourceLocator | None'

Decode a supplied address; legacy sources keep no address.

SourceLocator.__init__(self, document_id: 'str', document_name: 'str', section_path: 'tuple[str, ...]', start: 'int', end: 'int', label: 'str | None' = None, page_number: 'int | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.SourceProcessing

Processing diagnostics that can remain available without an address.

SourceProcessing.from_payload(cls, payload: 'SourceProcessingPayload | None') -> 'SourceProcessing | None'

Decode processing facts without filling unknown fields.

SourceProcessing.__init__(self, strategy: 'str | None' = None, unit_kind: 'str | None' = None, fallback_diagnostics: 'tuple[str, ...]' = (), partial_unit: 'bool | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.Space

One space, and the calls made on it.

id, name, owner, created_at, role (the key owner’s role in it) and grant (the key’s level on it) are what the server last said; raw is that answer whole – the full description for a space fetched or created, the summary for one from a listing. documents, config and evaluations hold the calls on the space’s documents, its pipeline and its evaluation runs.

Space.__init__(self, caller: 'Caller', payload: 'SpaceFullPayload | SpaceSummaryPayload') -> 'None'

A space as payload describes it, reached through caller.

Space.query(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None) -> 'Answer'

Ask a question and get the answer with the passages it rests on.

metadata_filter narrows which documents are searched: a MetadataFilter from contextbase.types, or a mapping of the same shape.

Space.query_stream(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None) -> 'Iterator[StreamEvent]'

Ask a question and get the answer as it is written.

Yields Stage and Check progress, a Token for each published fragment, and then a Done carrying the publication outcome or an ErrorEvent if execution failed. Done.answer.outcome separates a blocked answer from an accepted one. A refusal before the answer starts is raised, as any call’s is. Only connecting is held to the client’s timeout: an answer is read for as long as it takes to write.

Space.search(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None, rrf_k: 'int | None' = None) -> 'list[Source]'

Return ranked passages, optionally tuning RRF for this request.

Space.search_with_receipt(self, question: 'str', *, top_k: 'int' = 5, metadata_filter: 'MetadataFilter | Mapping[str, Any] | None' = None, rrf_k: 'int | None' = None) -> 'SearchResult'

Return sources and the server’s actual retrieval settings receipt.

Space.delete(self, *, appended_rows: 'AppendedRows | None' = None) -> 'None'

Delete the space; delete on the client’s spaces says how.

contextbase.SpaceConfig

The pipeline of one space.

Reading it needs any grant on the space; checking, applying and rebuilding need manage.

SpaceConfig.__init__(self, caller: 'Caller', space_id: 'str | UUID') -> 'None'

Calls on the pipeline of space_id, sent through caller.

SpaceConfig.get(self) -> 'PipelineConfig'

The pipeline the space runs now.

SpaceConfig.status(self) -> 'PipelineConfigStatus'

Whether the space is rebuilding, and each index’s state.

SpaceConfig.validate(self, config: 'PipelineConfig | Mapping[str, Any]') -> 'PreflightReport'

What the server’s preflight checks say of config, applied here.

Nothing is changed. The report’s status says whether the config could be applied as it stands.

SpaceConfig.apply(self, config: 'PipelineConfig | Mapping[str, Any]', *, force: 'bool' = False, wait: 'bool' = True, start_timeout: 'float' = 60.0, timeout: 'float' = 1800.0, interval: 'float' = 2.0, on_progress: 'Callable[[PipelineConfigStatus], object] | None' = None) -> 'ConfigChange[PipelineUpdateResult]'

Make config the space’s pipeline.

A config the preflight checks refuse raises PreflightBlockedError carrying their report; force pushes past checks that only failed to reach a resource. When the server answers that the change rebuilds the indexes, the call waits for the rebuild unless wait is false: up to start_timeout seconds for it to begin, raising RebuildNotStartedError if it does not, then up to timeout seconds for it to end, raising RebuildTimeoutError. Each status seen is handed to on_progress. A pass over attached storage is reported in storage_pass and not waited for.

SpaceConfig.reindex(self, *, force: 'bool' = False, wait: 'bool' = True, start_timeout: 'float' = 60.0, timeout: 'float' = 1800.0, interval: 'float' = 2.0, on_progress: 'Callable[[PipelineConfigStatus], object] | None' = None) -> 'ConfigChange[PipelineReindexResult]'

Rebuild the space’s indexes from its documents, as apply does.

contextbase.Spaces

The spaces the client’s key can reach.

Spaces.__init__(self, caller: 'Caller') -> 'None'

Calls on spaces, sent through caller.

Spaces.list(self, *, sort: 'ListSpacesSort | str | None' = None) -> 'Iterator[Space]'

Every reachable space, ordered on the server before pagination.

Spaces.get(self, space_id: 'str | UUID') -> 'Space'

The space with this id.

Spaces.create(self, name: 'str', *, llm_config: 'SpaceLLMConfig | Mapping[str, Any] | None' = None, config: 'PipelineConfig | Mapping[str, Any] | None' = None, embedding_model_id: 'str | UUID | None' = None, vector_backend_id: 'str | UUID | None' = None, outbound_config: 'SpaceOutboundConfig | Mapping[str, Any] | None' = None, extraction_config: 'SpaceExtractionConfig | Mapping[str, Any] | None' = None) -> 'Space'

Create a space and return it.

Everything but the name is optional; what is left out, the installation’s defaults decide. A configuration is a model from contextbase.types or a mapping of the same shape. A key that creates a space is granted manage on it.

Spaces.delete(self, space_id: 'str | UUID', *, appended_rows: 'AppendedRows | None' = None) -> 'None'

Delete the space and everything in it.

A key needs manage on the space. A space over storage this platform did not make first raises PreconditionRequiredError asking what to do with the rows it added there; answer by calling again with appended_rows='keep' or 'purge'.

contextbase.Stage

A streamed answer’s pipeline is about to run the stage named.

Stage.__init__(self, stage: 'str', label_key: 'str | None' = None, icon: 'str | None' = None, phase: 'str | None' = None, attempt_id: 'str | None' = None) -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.StreamEvent

StreamEvent = contextbase._models.Stage | contextbase._models.Check | contextbase._models.Token | contextbase._models.Done | contextbase._models.ErrorEvent

contextbase.Token

The next fragment of a streamed answer’s prose.

Token.__init__(self, delta: 'str') -> None

Initialize self. See help(type(self)) for accurate signature.

contextbase.UnknownEndpointError

404 for a path the server has no route for.

Usually the server is older than this client: the message says so, and check_compatibility() tells for certain.

contextbase.UnprocessableEntityError

422: the request was understood and could not be carried out.

contextbase.WaitTimeoutError

Waiting for the server to finish something ran out of time.

Each kind of wait raises its own subclass, carrying how what it waited for stood at the last look.

ContextBase0.1.0

Search the documentation