Building the corpus¶
build = sales.autograph.corpus_build(categories=["legal", "finance"])
One call starts a corpus build for the given categories, waits until it finishes and returns the final status. The corpus is the first layer of the context graph: AutoGraph reads the files uploaded under each category, extracts their text, links similar documents and groups them into clusters. The strategizer and the import work on that result, so this is the first step of ingestion. Ingesting in one call runs all three steps in one call.
Before sending anything, corpus_build reloads the project and refuses if
it has no AutoGraph service.
Parameters¶
Parameter |
Type |
Meaning |
|---|---|---|
|
sequence of |
The categories to build. A category is the second label of the scope
the files were uploaded with: a file uploaded with
|
|
|
Keep the existing corpus and only add or update the given categories.
Default |
|
|
How many similar documents are linked to each document. Service default 7. |
|
|
Clustering levels: 1 keeps the first-level clusters, 2 merges related ones into fewer, larger clusters. Service default 2. |
|
|
Deadline in seconds for the whole build. Unset waits without bound. |
|
|
Seconds between two status polls. Default 30. |
|
callable, optional |
Called with every polled
|
Return value¶
The final GetBuildStatusResponse. Its
status is "completed"; a build that ends any other way raises instead.
The counts describe what the build did: document_count and
cluster_count for the corpus as it is now. documents_added,
documents_removed and documents_unchanged describe an incremental
run; they are 0 on a first build.
Two input files with the same name under the same category produce one corpus
document. documents_deduplicated counts how many files collapsed that way
and dedup_groups names them.
A build that completes with error_code set is a partial success: some
files could not be processed, the rest were. The call returns it and logs a
warning; it does not raise. Check error_code and error when every file
matters:
build = sales.autograph.corpus_build(categories=["legal"])
if build.error_code:
print(f"Partial build: {build.error_code}: {build.error or build.message}")
Errors¶
ValueErrorcategoriesis empty. Nothing was sent.AutoGraphNotDeployedErrorThe project has no AutoGraph service. Nothing was sent. See Deploying AutoGraph.
ModelConfigNotReadyErrorAutoGraph cannot use its chat or embedding settings, either because a startup check found them invalid or because it is still loading them. Check the secret profiles and models passed to
deploy, or retry shortly.AutoGraphBusyErrorA conflicting job is already running on the project. Wait for it and retry.
CategoryAlreadyBuiltErrorOne of the categories is already built and
incrementalisFalse. Passincremental=Trueto add to it.IngestionFailedErrorThe build ended as failed.
job_statuson the exception is the finalGetBuildStatusResponse, whoseerroranderror_codesay why.JobStatusLostErrorAutoGraph no longer has a status for the build, usually because the service restarted while you were waiting. The build itself may still be running.
job_idon the exception names it.JobTimeoutErrortimeoutpassed before the build finished. The build keeps running on the platform; the SDK only stopped waiting.
Any other failure surfaces as one of the general SDK exceptions described in Errors.
Example¶
from arango_ai_sdk.exceptions import CategoryAlreadyBuiltError, IngestionFailedError
sales = client.project.get(project_name="sales")
def show(status):
print(f"build {status.status} {status.progress}%")
try:
build = sales.autograph.corpus_build(
categories=["legal", "finance"],
timeout=1800.0,
on_progress=show,
)
except CategoryAlreadyBuiltError:
build = sales.autograph.corpus_build(
categories=["legal", "finance"],
incremental=True,
)
except IngestionFailedError as exc:
print(f"Build failed: {exc.job_status.error}")
else:
print(f"{build.document_count} documents in {build.cluster_count} clusters")