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 before deploy checks 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 None when nothing is deployed.

property service_url: str | None

Return the deployed service URL, or None when nothing is deployed.

property service_path: str | None

Return the gateway path of the deployed service, or None.

service_url minus 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_code is 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. None waits without bound.

  • poll_interval (float) – Seconds between two status polls.

  • on_progress (callable, optional) – Called with each polled GetBuildStatusResponse.

Raises:
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. None waits without bound.

  • poll_interval (float) – Seconds between two status polls.

  • on_progress (callable, optional) – Called with each polled GetRagStrategizerJobStatusResponse.

Raises:
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:
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 None when 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. None waits without bound.

  • poll_interval (float) – Seconds between two status polls.

  • on_progress (callable, optional) – Called with each polled GetOrchestrationStatusResponse.

Raises:
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(), then strategize(), reads strategies(), then orchestrate(). Each step waits on its own. Stops at the first failure and raises whatever that step raised. orchestrate returning None (nothing stale) is success.

Parameters:
  • categories (Sequence[str]) – Bare category labels. Required; an empty list is rejected.

  • complexity (RagStrategizerComplexity) – Passed to strategize(). Default high.

  • incremental (bool) – Passed only to corpus_build(). False builds the categories for the first time and raises CategoryAlreadyBuiltError for one that is already built; pass True to ingest again after adding files.

  • timeout (float, optional) – Deadline in seconds for the whole run, shared across the steps. None waits without bound.

  • poll_interval (float) – Seconds between two status polls, passed to each step.

  • on_progress (callable, optional) – Called with an IngestProgress for each poll from a step.

Raises:
Return type:

IngestResult

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_service to AcpPath.AUTOGRAPH, refresh again. ACP answers once Helm accepts the install, before the pod is up. With wait=True the call then runs wait_until_ready() with its defaults and reports the outcome in ready; 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_info from ACP and ready: None without wait, otherwise whether the service became SERVING within the bound.

Return type:

DeployResult

Raises:
wait_until_ready(*, timeout=300.0, poll_interval=5.0)

Block until the deployed AutoGraph service answers its health check.

Polls GET /v1/health until status is SERVING. 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:

True once the service is SERVING, False when timeout passed 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.delete with the id from the metadata, refresh again.

Raises:
Return type:

ServiceInfo

class arango_ai_sdk.projects.services.autograph.DeployResult(service_info, ready)

What AutoGraph.deploy returns: 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

True when deploy(wait=True) saw the health check answer SERVING within the bound, False when the bound passed first, None when nobody waited (wait=False). Unless True, the service is installed and may still be coming up, call wait_until_ready to check again.

Type:

bool or None

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 None when nothing was stale.

Type:

GetOrchestrationStatusResponse or None

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 status field of its three job GETs.

Plain strings in corpus_graph.proto, so no enum is generated for them. COMPLETED, FAILED and CANCELLED are terminal. CANCELLED only occurs on orchestration.

PENDING = 'pending'
RUNNING = 'running'
COMPLETED = 'completed'
FAILED = 'failed'
CANCELLED = 'cancelled'