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
AiProjectHandleand reachable ashandle.projectfor 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_filesandmodel_settings, describe a project’s later state. Create leaves them at their empty defaults; get returns them as stored.
Secret profiles¶
- class arango_ai_sdk.models.Profile¶
A secret profile as the platform returned it. Returned by
create()andget(). 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_typetocreate()and read back fromProfile.profile_type.LLMA model provider key. The default at creation, and what AutoGraph expects for its chat and embedding models.
DATABASE,CLOUD_STORAGE,API_KEY,OAUTH,SSH,CUSTOMOther categories the platform defines. No SDK operation needs them today.
UNSPECIFIEDThe platform’s zero value. Never pass it.
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_deleteandcustom_metadata. Uploading the same name under the same scope again keepsidand raisesversion.
- class arango_ai_sdk.models.RagInputBatchItemResult¶
Outcome for one file of a multi-file upload. Returned, one per file, by
upload_files()andupload_folder().statusis"ok"or"error". For a stored file the fields ofRagInputUploadResponseare set, exceptdatabase; for a rejected file they areNoneanddetailsays why.
- class arango_ai_sdk.models.RagInputBatchUploadResponse¶
The whole reply to a multi-file upload:
database,results,ok_countanderror_count. The SDK returns itsresults; 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()andundeploy(). 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_serviceonce deployed.autograph.service_idandautograph.service_urlread from it.
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
complexitytostrategize()andingest().very_lowNo cluster; everything becomes vectors.
low,moderate,highA quarter, half and three quarters of the clusters, rounded over the ranking.
highis the default.very_highEvery cluster.
- class arango_ai_sdk.models.GetBuildStatusResponse¶
The state of one corpus build. Returned by
corpus_build()and asbuildonIngestResult. 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_atandcompleted_at. A completed build witherror_codeset is a partial success. See Building the corpus.
- class arango_ai_sdk.models.GetRagStrategizerJobStatusResponse¶
The progress of one strategizer run. Returned by
strategize()and asstrategizeonIngestResult. Fields:status,progress(percent, 0.0 to 100.0),clusters_totalandclusters_done. It does not say which strategy a cluster got; seeGetRagStrategizerStrategyResponse.
- class arango_ai_sdk.models.GetRagStrategizerStrategyResponse¶
The strategy stored for each cluster. Returned by
strategies()and asstrategiesonIngestResult. Fields:strategies, one entry per cluster withcluster_id,strategy_type,rag_partition_id,entity_types,document_countandparameters;total_strategies; andstrategy_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 asorchestrationonIngestResult.statusdescribes the whole run;phasesays 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 withrag_partition_id,strategy_type,status,category,retry_count,error_message,entities_addedandimported),entities_added,elapsed_seconds,seconds_since_progress,output_verifiedandunverified_partitions. See Importing the graph.
- class arango_ai_sdk.models.CreateCorpusBuildRequest¶
Data class
corpus_build()fills and sends, with aBuildStrategywhentop_korcluster_thresholdis given. Not constructed by callers.
- class arango_ai_sdk.models.BuildStrategy¶
The tunable parameters of a corpus build,
top_kandcluster_threshold. Filled bycorpus_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_typetoask(). The SDK default isUNIFIED.LOCALThe entities named in the question and their relationships.
GLOBALSummaries across the graph. Needs full-graph partitions.
UNIFIEDMatching passages and the graph together. Works on vectors-only and full-graph partitions.
CUSTOMA service-defined mode.
askcan 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) andmetadata(empty unlessinclude_metadata=True). A response whoseerror_codeis set is not returned;askraisesQueryFailedErrorinstead.