AutoGraph¶
You do not construct this class yourself. Every
AiProjectHandle owns one
AutoGraph and exposes it as autograph.
It is bound to that handle’s project and shares the client’s connection.
deploy returns a DeployResult, whose
service_info is a ServiceInfo documented in
Models; undeploy returns the ServiceInfo directly. The
ingestion methods return the status classes documented in Models;
ingest wraps them in an IngestResult.
- class arango_ai_sdk.projects.services.autograph.AutoGraph(service_api, api, project, refresh)¶
The single AutoGraph service of a project.
- Parameters:
service_api (
ServiceApi) – Sends install and delete requests to ACP.api (
AutoGraphApi) – Sends job requests to the AutoGraph service itself.project (
AiProject) – Snapshot of the project this service belongs to. Supplies the project name, the database and the deployed-service metadata.refresh (
callable returning AiProject) – Reloads the project from the platform and returns the new snapshot. Called beforedeploychecks for an existing service and after a deploy or undeploy, so the state properties stay current.
- property is_deployed: bool¶
Return whether the last project snapshot shows an AutoGraph service.
- property service_id: str | None¶
Return the deployed service id, or
Nonewhen nothing is deployed.
- property service_url: str | None¶
Return the deployed service URL, or
Nonewhen nothing is deployed.
- property service_path: str | None¶
Return the gateway path of the deployed service, or
None.service_urlminus scheme and host, without a trailing slash, so job endpoints can be appended to it.
- corpus_build(categories, *, incremental=False, top_k=None, cluster_threshold=None, timeout=None, poll_interval=30.0, on_progress=None)¶
Build the corpus graph for the given categories and wait for it to finish.
Starts the build, polls its status until it is terminal and returns the final status. A build that completes with a non-empty
error_codeis a partial success: it is returned, not raised, and a warning is logged.- Parameters:
categories (
Sequence[str]) – Bare category labels, the second label of the scope the files were uploaded with. Required; an empty list is rejected.incremental (
bool) – Keep the existing corpus and only add or update the given categories.top_k (
int, optional) – Similar documents linked per document. Service default 7.cluster_threshold (
int, optional) – Clustering levels. 1 keeps the first-level clusters, 2 merges related ones into fewer, larger clusters. Service default 2.timeout (
float, optional) – Deadline in seconds for the whole build.Nonewaits without bound.poll_interval (
float) – Seconds between two status polls.on_progress (
callable, optional) – Called with each polledGetBuildStatusResponse.
- Raises:
ValueError –
categoriesis empty; nothing is sent.AutoGraphNotDeployedError – The project has no AutoGraph service.
ModelConfigNotReadyError – The service reports its model configuration invalid.
AutoGraphBusyError – A conflicting job is already running on the project.
CategoryAlreadyBuiltError – A category is already built. Pass
incremental=Trueto add to it.IngestionFailedError – The build ended as failed; carries the final status.
JobStatusLostError – The service dropped the build’s status record while polling.
JobTimeoutError –
timeoutexpired before the build finished.ServiceError – Any other error answer from the service.
- Return type:
GetBuildStatusResponse
- strategize(categories, *, complexity=RagStrategizerComplexity.high, extract_images_default=False, max_parallel_clusters=None, timeout=None, poll_interval=30.0, on_progress=None)¶
Choose a RAG strategy per cluster and wait until the run finishes.
- Parameters:
categories (
Sequence[str]) – Bare category labels. Required; an empty list is rejected.complexity (
RagStrategizerComplexity) – Share of clusters that get FullGraphRAG rather than VectorRAG: very_low 0 %, low 25 %, moderate 50 %, high 75 %, very_high 100 %, rounded over the ranked clusters. Default high, so a one-cluster corpus still gets one FullGraphRAG partition.extract_images_default (
bool) – Whether image extraction is on for FullGraphRAG profiles. Accepted only with complexity high or very_high; any other value is a 400. VectorRAG profiles always leave it off.max_parallel_clusters (
int, optional) – How many clusters to analyze at once. Omitted means the service default.timeout (
float, optional) – Deadline in seconds for the whole run.Nonewaits without bound.poll_interval (
float) – Seconds between two status polls.on_progress (
callable, optional) – Called with each polledGetRagStrategizerJobStatusResponse.
- Raises:
ValueError –
categoriesis empty; nothing is sent.AutoGraphNotDeployedError – The project has no AutoGraph service.
ModelConfigNotReadyError – The service reports its model configuration invalid.
AutoGraphBusyError – A conflicting job is already running on the project.
IngestionFailedError – The run ended as failed; carries the final status.
JobStatusLostError – The service dropped the run’s status record while polling.
JobTimeoutError –
timeoutexpired before the run finished.ServiceError – Any other error answer from the service.
- Return type:
GetRagStrategizerJobStatusResponse
- strategies()¶
Return the strategy the strategizer chose for each cluster.
Reads the stored result. It does not start a run or wait.
- Raises:
AutoGraphNotDeployedError – The project has no AutoGraph service.
ServiceError – Any error answer from the service.
- Return type:
GetRagStrategizerStrategyResponse
- orchestrate(categories, *, timeout=None, poll_interval=30.0, on_progress=None)¶
Import the knowledge graph for the given categories and wait until it finishes.
Returns
Nonewhen every category is already up to date, without polling.- Parameters:
categories (
Sequence[str]) – Bare category labels. Required; an empty list is rejected.timeout (
float, optional) – Deadline in seconds for the whole run.Nonewaits without bound.poll_interval (
float) – Seconds between two status polls.on_progress (
callable, optional) – Called with each polledGetOrchestrationStatusResponse.
- Raises:
ValueError –
categoriesis empty; nothing is sent.AutoGraphNotDeployedError – The project has no AutoGraph service.
ServiceError – Model settings have no secret profile ids, or any other error answer.
ModelConfigNotReadyError – The service reports its model configuration invalid.
AutoGraphBusyError – A conflicting job is already running on the project.
NoStrategiesError – The categories have no strategy profiles; run the strategizer first.
IngestionFailedError – The run ended as failed or cancelled; carries the final status.
JobStatusLostError – The service dropped the run’s status record while polling.
JobTimeoutError –
timeoutexpired before the run finished.
- Return type:
GetOrchestrationStatusResponse | None
- ingest(categories, *, complexity=RagStrategizerComplexity.high, incremental=False, timeout=None, poll_interval=30.0, on_progress=None)¶
Build the corpus, choose strategies, then import the graph.
Runs
corpus_build(), thenstrategize(), readsstrategies(), thenorchestrate(). Each step waits on its own. Stops at the first failure and raises whatever that step raised.orchestratereturningNone(nothing stale) is success.- Parameters:
categories (
Sequence[str]) – Bare category labels. Required; an empty list is rejected.complexity (
RagStrategizerComplexity) – Passed tostrategize(). Default high.incremental (
bool) – Passed only tocorpus_build().Falsebuilds the categories for the first time and raisesCategoryAlreadyBuiltErrorfor one that is already built; passTrueto ingest again after adding files.timeout (
float, optional) – Deadline in seconds for the whole run, shared across the steps.Nonewaits without bound.poll_interval (
float) – Seconds between two status polls, passed to each step.on_progress (
callable, optional) – Called with anIngestProgressfor each poll from a step.
- Raises:
ValueError –
categoriesis empty; nothing is sent.JobTimeoutError –
timeoutexpired while a step was being polled, or before the next step could start.AutoGraphNotDeployedError – The project has no AutoGraph service.
ModelConfigNotReadyError – The service reports its model configuration invalid.
AutoGraphBusyError – A conflicting job is already running on the project.
CategoryAlreadyBuiltError – A category is already built and
incrementalisFalse.IngestionFailedError – A step ended as failed or cancelled.
NoStrategiesError – The categories have no strategy profiles.
JobStatusLostError – The service dropped a step’s status record while polling.
ServiceError – Any other error answer from the service.
- Return type:
- deploy(*, chat_api_provider, embedding_api_provider, chat_secret_profile_id, embedding_secret_profile_id, fps_recovery_username, chat_model=None, embedding_model=None, chat_api_url=None, embedding_api_url=None, multimodal_model=None, labels=None, wait=False)¶
Install AutoGraph for this project and return the deploy result.
Steps: refresh the project, raise if it already has an AutoGraph service, build the install request, send it through
ServiceApi.deploy_servicetoAcpPath.AUTOGRAPH, refresh again. ACP answers once Helm accepts the install, before the pod is up. Withwait=Truethe call then runswait_until_ready()with its defaults and reports the outcome inready; a slow start never fails the deploy.- Parameters:
chat_api_provider (
str) – Provider of the chat model, for example"openai".embedding_api_provider (
str) – Provider of the embedding model, for example"openai".chat_secret_profile_id (
str) – ID of the secret profile holding the chat provider’s API key.embedding_secret_profile_id (
str) – ID of the secret profile holding the embedding provider’s API key.fps_recovery_username (
str) – ArangoDB user AutoGraph uses to resume File Parser work after a pod restart. Must have read and write access to the project database. The SDK does not create this user.chat_model (
str, optional) – Chat model name, for example"gpt-4o".embedding_model (
str, optional) – Embedding model name, for example"text-embedding-3-small".chat_api_url (
str, optional) – Override for the chat provider’s endpoint.embedding_api_url (
str, optional) – Override for the embedding provider’s endpoint.multimodal_model (
str, optional) – Multimodal model name, when documents contain images.labels (
Mapping[str,str], optional) – Labels attached to the deployed service on the platform.wait (
bool) – Also wait for the service health check before returning.not (Optional parameters are left out of the install request when)
value (given. The SDK does not validate the required strings; an empty)
is. (is sent as)
- Returns:
service_infofrom ACP andready:Nonewithoutwait, otherwise whether the service becameSERVINGwithin the bound.- Return type:
- Raises:
AutoGraphAlreadyDeployedError – The project already has an AutoGraph service.
ProjectNotFoundError – The project no longer exists on the platform.
InvalidServiceParametersError – ACP rejected an install parameter.
ServiceError – Any other error answer from the service.
- wait_until_ready(*, timeout=300.0, poll_interval=5.0)¶
Block until the deployed AutoGraph service answers its health check.
Polls
GET /v1/healthuntilstatusisSERVING. A failed request while the route or the pod is still coming up counts as not ready, not as an error.- Parameters:
timeout (
float) – Seconds to wait before giving up.poll_interval (
float) – Seconds between two health checks.
- Returns:
Trueonce the service isSERVING,Falsewhentimeoutpassed first.- Return type:
bool- Raises:
AutoGraphNotDeployedError – The project has no AutoGraph service.
- undeploy()¶
Stop and remove this project’s AutoGraph service.
Steps: refresh the project, raise if it has no AutoGraph service, send
ServiceApi.deletewith the id from the metadata, refresh again.- Raises:
AutoGraphNotDeployedError – The project has no AutoGraph service.
ServiceNotFoundError – ACP no longer knows the service id the project metadata holds.
ServiceError – Any other error answer from the service.
- Return type:
ServiceInfo
- class arango_ai_sdk.projects.services.autograph.DeployResult(service_info, ready)¶
What
AutoGraph.deployreturns: the service record and whether it is ready.- Parameters:
service_info (ServiceInfo)
ready (bool | None)
- service_info¶
The service as ACP described it right after accepting the install.
- Type:
ServiceInfo
- ready¶
Truewhendeploy(wait=True)saw the health check answerSERVINGwithin the bound,Falsewhen the bound passed first,Nonewhen nobody waited (wait=False). UnlessTrue, the service is installed and may still be coming up, callwait_until_readyto check again.- Type:
boolorNone
- class arango_ai_sdk.projects.services.autograph.IngestResult(build, strategize, strategies, orchestration)¶
What
AutoGraph.ingest()returns when the whole run finishes.- Parameters:
build (GetBuildStatusResponse)
strategize (GetRagStrategizerJobStatusResponse)
strategies (GetRagStrategizerStrategyResponse)
orchestration (GetOrchestrationStatusResponse | None)
- build¶
Final corpus-build status.
- Type:
GetBuildStatusResponse
- strategize¶
Final strategizer job status. Progress counts only; the per-cluster choice lives on
strategies.- Type:
GetRagStrategizerJobStatusResponse
- strategies¶
Stored strategies read after the strategizer finished.
- Type:
GetRagStrategizerStrategyResponse
- orchestration¶
Final orchestration status, or
Nonewhen nothing was stale.- Type:
GetOrchestrationStatusResponseorNone
- class arango_ai_sdk.projects.services.autograph.IngestProgress(step, status)¶
One poll update from
AutoGraph.ingest().- Parameters:
step (str)
status (GetBuildStatusResponse | GetRagStrategizerJobStatusResponse | GetOrchestrationStatusResponse)
- step¶
Which step produced the update:
"build","strategize", or"orchestrate".- Type:
str
- status¶
The status object that step just polled.
- class arango_ai_sdk.projects.services.autograph.JobState(*values)¶
Job states AutoGraph reports in the
statusfield of its three job GETs.Plain strings in
corpus_graph.proto, so no enum is generated for them.COMPLETED,FAILEDandCANCELLEDare terminal.CANCELLEDonly occurs on orchestration.- PENDING = 'pending'¶
- RUNNING = 'running'¶
- COMPLETED = 'completed'¶
- FAILED = 'failed'¶
- CANCELLED = 'cancelled'¶