On this page
- Python SDK method reference
- contextbase.API_VERSION
- contextbase.MINIMUM_SERVER_VERSION
- contextbase.APIConnectionError
- contextbase.APIError
- contextbase.Answer
- contextbase.AsyncContextBase
- contextbase.AsyncDocuments
- contextbase.AsyncEvalDatasets
- contextbase.AsyncEvaluations
- contextbase.AsyncPipeline
- contextbase.AsyncSpace
- contextbase.AsyncSpaceConfig
- contextbase.AsyncSpaces
- contextbase.AuthenticationError
- contextbase.BadGatewayError
- contextbase.BadRequestError
- contextbase.Check
- contextbase.ConfigChange
- contextbase.ConflictError
- contextbase.ContextBase
- contextbase.ContextBaseError
- contextbase.Document
- contextbase.DocumentGroup
- contextbase.DocumentGroupMember
- contextbase.DocumentOrigin
- contextbase.DocumentStatus
- contextbase.Documents
- contextbase.Done
- contextbase.EquivalentPassageGroup
- contextbase.EquivalentPassageMember
- contextbase.ErrorEvent
- contextbase.EvalDatasets
- contextbase.EvaluationFailedError
- contextbase.EvaluationTimeoutError
- contextbase.Evaluations
- contextbase.IncompatibleServerError
- contextbase.IndexingTimeoutError
- contextbase.MissingAPIKeyError
- contextbase.NotFoundError
- contextbase.PayloadTooLargeError
- contextbase.PermissionDeniedError
- contextbase.Pipeline
- contextbase.PreconditionRequiredError
- contextbase.PreflightBlockedError
- contextbase.PreflightConflictError
- contextbase.PreflightUnprocessableError
- contextbase.RateLimitError
- contextbase.RebuildNotStartedError
- contextbase.RebuildTimeoutError
- contextbase.RetrievalReceipt
- contextbase.SearchResult
- contextbase.ServerError
- contextbase.ServerMeta
- contextbase.ServiceUnavailableError
- contextbase.Source
- contextbase.SourceBibliography
- contextbase.SourceLocator
- contextbase.SourceProcessing
- contextbase.Space
- contextbase.SpaceConfig
- contextbase.Spaces
- contextbase.Stage
- contextbase.StreamEvent
- contextbase.Token
- contextbase.UnknownEndpointError
- contextbase.UnprocessableEntityError
- contextbase.WaitTimeoutError
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.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.