Importing the graph¶
orchestration = sales.autograph.orchestrate(categories=["legal", "finance"])
One call starts the import for the given categories, waits until it finishes
and returns the final status. The import, called orchestration on the
platform, turns each cluster into its part of the context graph using the
strategy the strategizer chose for it: entities and relations for a
FullGraphRAG cluster, chunks and embeddings for a VectorRAG one. This
is the last step of ingestion, after Building the corpus and
Choosing a strategy per cluster.
Only clusters whose data changed since the last import are processed. When
nothing changed, the platform has nothing to do and orchestrate returns
None right away. That is success, not an error.
The chat and embedding secret profiles the import needs come from the
project’s model settings, which deploy stored. Before sending anything,
orchestrate reloads the project and refuses if it has no AutoGraph service
or no secret profile IDs in its model settings.
Parameters¶
Parameter |
Type |
Meaning |
|---|---|---|
|
sequence of |
The categories to import, as passed to the corpus build. At least one is required. |
|
|
Deadline in seconds for the whole run. Unset waits without bound. |
|
|
Seconds between two status polls. Default 30. |
|
callable, optional |
Called with every polled
|
Return value¶
The final GetOrchestrationStatusResponse, or
None when every category was already up to date.
status describes the whole run and is "completed" on return. It
reaches that value once every import job has finished and the partitions the
jobs reported writing are present in the graph. If the knowledge-graph check
itself fails, output_verified stays unset and that is reported in
message; it is not treated as an import failure. On a returned status
unverified_partitions is empty. A partition the check cannot find in the
graph forces the run to fail, so it shows up on
IngestionFailedError’s
job_status.unverified_partitions.
phase says where a running import is, and is the field to show as
progress inside on_progress: initializing, starting_importers,
importing, verifying, then finished. An import that has been
running for a while in starting_importers has not imported anything yet.
The job counts (total_jobs, completed_jobs, failed_jobs,
running_jobs, pending_jobs, skipped_jobs) and jobs, one entry
per partition, break the run down. One category can have more than one job.
completed_jobs includes jobs that finished without importing. Each job
has strategy_type, status, category, error_message,
entities_added and imported. Read imported and skipped_jobs
to tell a real import from a skip. entities_added sums what the
FullGraphRAG jobs wrote; a VectorRAG partition writes no entities, so
zero is not evidence that nothing was imported.
Errors¶
ValueErrorcategoriesis empty. Nothing was sent.AutoGraphNotDeployedErrorThe project has no AutoGraph service. Nothing was sent.
ServiceErrorThe project’s model settings hold no chat or embedding secret profile ID, so the import could not be started. Nothing was sent. That happens on a first deploy that did not include both model names and both profile IDs. A later deploy keeps settings already stored, including their profile IDs, even when the new install omits the model names. See Deploying AutoGraph.
ModelConfigNotReadyErrorAutoGraph cannot use its chat or embedding settings. 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.
NoStrategiesErrorNo strategy is stored for the categories. Run Choosing a strategy per cluster first.
IngestionFailedErrorThe run ended as failed or cancelled.
job_statuson the exception is the final status; itsjobssay which partitions failed and why.JobStatusLostErrorAutoGraph no longer has a status for the run, usually after a restart. The run itself may still be going.
JobTimeoutErrortimeoutpassed before the run finished. The run keeps going on the platform.
Any other failure surfaces as one of the general SDK exceptions described in Errors.
Example¶
from arango_ai_sdk.exceptions import IngestionFailedError, NoStrategiesError
sales = client.project.get(project_name="sales")
def show(status):
print(f"orchestrate {status.phase} {status.completed_jobs}/{status.total_jobs}")
try:
orchestration = sales.autograph.orchestrate(
categories=["legal", "finance"],
on_progress=show,
)
except NoStrategiesError:
print("Run strategize first.")
except IngestionFailedError as exc:
for job in exc.job_status.jobs:
if job.error_message:
print(f"{job.category}/{job.rag_partition_id}: {job.error_message}")
else:
if orchestration is None:
print("Nothing to import; the graph is up to date.")
else:
imported = sum(1 for job in orchestration.jobs if job.imported)
print(
f"Imported {imported} partitions, "
f"skipped {orchestration.skipped_jobs}"
)