Models

Data classes shared between the SDK and the platform services.

The classes are generated, never written by hand. The ACP ones come from the .proto files under proto/ into the private _proto_out package by make generate-proto; the file service ones come from the OpenAPI documents under specs/ into the private _openapi_out package by make generate-openapi. Both packages are regenerated wholesale, so nothing hand-written can live there. This module is the single hand-written seam over them: it names the types the SDK supports and nothing else, so the rest of the SDK, and users, import from here and never from the generated code.

Replacing a generated type with an SDK-owned one later changes this file only.

The classes below are the ones the SDK returns or accepts. Import them from arango_ai_sdk.models; that path stays stable even if the classes’ origin changes.

from arango_ai_sdk.models import AiProject, Profile, ProfileType, ServiceInfo
from arango_ai_sdk.models import RagStrategizerComplexity

You construct none of these yourself. AiProject, Profile, ServiceInfo and the ingestion status classes come back from SDK calls; RagStrategizerComplexity and QueryType are the enums you pass in. CreateProjectRequest, CreateSecretProfileRequest and CreateEntityRequest are data classes those calls fill; you still pass arguments on create and deploy, not those objects.

create fills a request data class and sends to_dict(). Field names come from the proto, so a rename fails at import time, not on the wire. to_dict emits camelCase keys, which the gateway accepts. A plain string at its zero value is omitted; the server reads a missing field as empty, so an empty name is still rejected. Optional fields (project_description, description, provider) track presence: None is omitted, "" is sent as "".

Projects

class arango_ai_sdk.models.AiProject

A project as the platform returned it. Wrapped by AiProjectHandle and reachable as handle.project for users who want the record itself. Create sets the four attributes below; get fills whatever the platform holds. See Projects for how to read them through the handle.

AiProject.project_name: str
AiProject.project_type: str
AiProject.project_db_name: str
AiProject.project_description: str | None

The remaining attributes, project_metadata, project_files and model_settings, describe a project’s later state. Create leaves them at their empty defaults; get returns them as stored.

class arango_ai_sdk.models.CreateProjectRequest

Data class create() fills and sends. Not constructed by callers.

Secret profiles

class arango_ai_sdk.models.Profile

A secret profile as the platform returned it. Returned by create() and get(). See Secret profiles for how to read it.

Profile.profile_id: str

Unique identifier for the profile

Profile.profile_type: ProfileType

The type/category of this profile

Profile.name: str

Human-readable name for the profile

Profile.description: str | None

Optional description of the profile

Profile.metadata: Dict[str, str]

Non-sensitive metadata associated with the profile

Profile.secret_data: Dict[str, str]

The sensitive data to be encrypted at rest

Never the secret itself: the platform returns an obfuscated copy.

Profile.version: int

Version number for optimistic locking

Profile.created_at: datetime

Timestamp when the profile was created

Profile.updated_at: datetime

Timestamp when the profile was last updated

class arango_ai_sdk.models.ProfileType

Category of a secret profile. Passed as profile_type to create() and read back from Profile.profile_type.

LLM

A model provider key. The default at creation, and what AutoGraph expects for its chat and embedding models.

DATABASE, CLOUD_STORAGE, API_KEY, OAUTH, SSH, CUSTOM

Other categories the platform defines. No SDK operation needs them today.

UNSPECIFIED

The platform’s zero value. Never pass it.

class arango_ai_sdk.models.CreateSecretProfileRequest

Data class create() fills and sends. Not constructed by callers. profile_type is sent as the enum name (for example "LLM").

Files

Generated from the file service’s OpenAPI description, so they carry the same fields and descriptions the service documents. See Files for how to read them.

class arango_ai_sdk.models.RagInputUploadResponse

One stored file version. Returned by upload_file(). Fields: id, name, database, scope, content_type, size, uploaded_at, metadata_key, version, safe_to_delete and custom_metadata. Uploading the same name under the same scope again keeps id and raises version.

class arango_ai_sdk.models.RagInputBatchItemResult

Outcome for one file of a multi-file upload. Returned, one per file, by upload_files() and upload_folder(). status is "ok" or "error". For a stored file the fields of RagInputUploadResponse are set, except database; for a rejected file they are None and detail says why.

class arango_ai_sdk.models.RagInputBatchUploadResponse

The whole reply to a multi-file upload: database, results, ok_count and error_count. The SDK returns its results; the class is exported for callers who load a reply themselves.

Services

class arango_ai_sdk.models.ServiceInfo

A platform service as the platform described it. Returned by deploy() and undeploy(). See AutoGraph.

ServiceInfo.service_id: str

The platform’s ID of the service. Filled after a deploy.

ServiceInfo.status: str

What the platform reported when it answered, for example that the install was accepted. Not a readiness signal.

ServiceInfo.description: str
ServiceInfo.namespace: str
ServiceInfo.db_name: str | None
ServiceInfo.managing_entity: str | None
ServiceInfo.genai_project_name: str | None
ServiceInfo.service_meta: ServiceMeta | None
class arango_ai_sdk.models.AutoGraphService

The AutoGraph service as recorded in a project’s metadata, reachable as handle.metadata.autograph_service once deployed. autograph.service_id and autograph.service_url read from it.

class arango_ai_sdk.models.CreateEntityRequest

Data class deploy() and deploy() fill and send. Not constructed by callers.

Ingestion

What the ingestion methods on AutoGraph return. Generated from the AutoGraph service’s proto, so they carry the same fields the service documents. Every status class has a status string whose terminal values are listed in JobState; the methods only return once it is "completed", and raise otherwise, so a returned status is always a finished one. The same classes reach an on_progress callback while a step is still running. See AutoGraph.

class arango_ai_sdk.models.RagStrategizerComplexity

What share of the clusters, ranked by complexity, the strategizer turns into a full knowledge graph rather than vectors. Passed as complexity to strategize() and ingest().

very_low

No cluster; everything becomes vectors.

low, moderate, high

A quarter, half and three quarters of the clusters, rounded over the ranking. high is the default.

very_high

Every cluster.

class arango_ai_sdk.models.GetBuildStatusResponse

The state of one corpus build. Returned by corpus_build() and as build on IngestResult. Fields: corpus_build_id, status, progress (percent), message, error, error_code, graph_name, document_count, cluster_count, documents_added, documents_removed, documents_unchanged, documents_created, documents_deduplicated, dedup_groups, files_written, started_at and completed_at. A completed build with error_code set is a partial success. See Building the corpus.

class arango_ai_sdk.models.GetRagStrategizerJobStatusResponse

The progress of one strategizer run. Returned by strategize() and as strategize on IngestResult. Fields: status, progress (percent, 0.0 to 100.0), clusters_total and clusters_done. It does not say which strategy a cluster got; see GetRagStrategizerStrategyResponse.

class arango_ai_sdk.models.GetRagStrategizerStrategyResponse

The strategy stored for each cluster. Returned by strategies() and as strategies on IngestResult. Fields: strategies, one entry per cluster with cluster_id, strategy_type, rag_partition_id, entity_types, document_count and parameters; total_strategies; and strategy_type_counts, a mapping from strategy type to how many clusters got it. See Reading the stored strategies.

class arango_ai_sdk.models.GetOrchestrationStatusResponse

The state of one import run. Returned by orchestrate() and as orchestration on IngestResult. status describes the whole run; phase says where a running import is. Further fields: orchestration_id, message, total_jobs, completed_jobs, failed_jobs, running_jobs, pending_jobs, skipped_jobs, jobs (one entry per partition with rag_partition_id, strategy_type, status, category, retry_count, error_message, entities_added and imported), entities_added, elapsed_seconds, seconds_since_progress, output_verified and unverified_partitions. See Importing the graph.

class arango_ai_sdk.models.CreateCorpusBuildRequest

Data class corpus_build() fills and sends, with a BuildStrategy when top_k or cluster_threshold is given. Not constructed by callers.

class arango_ai_sdk.models.BuildStrategy

The tunable parameters of a corpus build, top_k and cluster_threshold. Filled by corpus_build(). Not constructed by callers.

class arango_ai_sdk.models.TriggerRagStrategizerRequest

Data class strategize() fills and sends. Not constructed by callers.

class arango_ai_sdk.models.TriggerOrchestrationRequest

Data class orchestrate() fills and sends; the secret profile IDs in it come from the project’s model settings. Not constructed by callers.

Asking

What ask() sends and returns. Generated from the retriever service’s proto. See Asking a question.

class arango_ai_sdk.models.QueryType

How a retriever searches. Passed as query_type to ask(). The SDK default is UNIFIED.

LOCAL

The entities named in the question and their relationships.

GLOBAL

Summaries across the graph. Needs full-graph partitions.

UNIFIED

Matching passages and the graph together. Works on vectors-only and full-graph partitions.

CUSTOM

A service-defined mode. ask can send the value; it does not take the custom-tool arguments that mode needs.

class arango_ai_sdk.models.GraphRagQueryResponse

The answer from one question. Returned by ask(). Fields: result (the answer text), run_id (the stored query run) and metadata (empty unless include_metadata=True). A response whose error_code is set is not returned; ask raises QueryFailedError instead.

class arango_ai_sdk.models.GraphRagQueryRequest

Data class ask() fills and sends. Not constructed by callers.