AutoGraph¶
AutoGraph is the service that turns a project’s documents into a context graph. It runs as a platform-managed service inside the project, and a project has exactly one instance of it.
The AutoGraph area is the autograph object on a project handle, not a
namespace on the client, because AutoGraph belongs to one project. Create or
get the project, then work on autograph: deploy the service once, then
ingest the files uploaded under the project’s categories.
sales = client.project.get(project_name="sales")
sales.autograph.deploy(
chat_api_provider="openai",
embedding_api_provider="openai",
chat_secret_profile_id=chat.profile_id,
embedding_secret_profile_id=embed.profile_id,
fps_recovery_username="fps-recovery",
chat_model="gpt-4o",
embedding_model="text-embedding-3-small",
)
if sales.autograph.wait_until_ready():
result = sales.autograph.ingest(categories=["legal", "finance"])
sales.autograph.undeploy()
Create the project and the chat and embedding secret profiles first. Deploy takes the profile IDs and both model names. Upload the documents before ingesting. See Projects, Secret profiles and Files.
Available operations¶
Operation |
Status |
Page |
|---|---|---|
Deploy AutoGraph into the project |
Available |
|
Ingest: build, strategize and import in one call |
Available |
|
Build the corpus |
Available |
|
Choose a strategy per cluster |
Available |
|
Read the stored strategies |
Available |
|
Import the graph |
Available |
|
Remove the project’s AutoGraph |
Available |
|
Delete categories or files from the graph |
Not yet available |
Arrives in a later release as further methods on |
Ingestion in three steps¶
Ingestion takes the files uploaded under a project’s categories and turns
them into the context graph. It runs in three steps on the platform, and each
is a method on autograph that starts the step, waits for it and returns
its final status:
Building the corpus reads the files, extracts their text, links similar documents and groups them into clusters.
Choosing a strategy per cluster decides for every cluster whether it becomes a full knowledge graph or vectors only, and stores that choice. Reading the stored strategies reads the stored choices back.
Importing the graph imports each cluster according to its strategy. Clusters that did not change since the last import are skipped.
Ingesting in one call runs the three in order and returns all their
results. Use it when you want the graph and nothing in between; call the
steps yourself to inspect the corpus first, to pass options ingest does
not expose, or to redo a single step.
Categories¶
Every ingestion method takes categories. A category is the second label
of the scope a file was uploaded with: the first label is the project name,
the second the category. Files uploaded with scope=["sales", "legal"]
belong to category "legal" of project sales.
client.files.upload_folder("./contracts", scope=["sales", "legal"])
client.files.upload_folder("./reports", scope=["sales", "finance"])
sales.autograph.ingest(categories=["legal", "finance"])
Building a category a second time is refused unless you say so: pass
incremental=True to add files uploaded since the last build. See
Building the corpus.
Waiting for a step¶
The ingestion methods do not return until their step is finished. They poll the step’s status on the platform and share three parameters for that:
timeoutDeadline in seconds. Unset waits for as long as the step takes. When it passes, the method raises
JobTimeoutError; the step itself keeps running on the platform, only the SDK stopped waiting. Oningestthe deadline covers all steps together.poll_intervalSeconds between two polls. Default 30. A smaller value shows progress sooner at the cost of more requests.
on_progressA callable the method invokes with every status it polls, so you can print or log progress. It is called from inside the method, on the same thread, so keep it quick.
A build or a strategy run that ends as failed, or an import that ends as
failed or cancelled, raises
IngestionFailedError, which carries the final
status as job_status. If the platform loses track of a step while you
wait, usually because the service restarted, the method raises
JobStatusLostError; the step may still be
running. Three failed polls in a row raise the last communication error,
usually ServiceError or
PlatformUnreachableError.
Conflicting jobs¶
AutoGraph refuses to start a job while a conflicting one is running on the
project. Starting it anyway raises
AutoGraphBusyError before anything is
started. Which jobs conflict depends on the call. Since the SDK methods
wait for their step, this happens when another client or another thread
started a job on the same project, or when an earlier call stopped waiting
with
JobTimeoutError or
JobStatusLostError while its job kept
running.
The deployment state¶
autograph reads its state from the project record the handle holds. It
never sends a request for that, so reading these is free:
is_deployedTruewhen the project has an AutoGraph service.service_idThe platform’s ID of that service, or
Nonewhen nothing is deployed.service_urlWhere the service listens inside the platform, or
None.
Every method on autograph reloads the project before it acts, and
deploy and undeploy also after they finish, so the state is current
right after any call. To pick up a change made elsewhere, for example a deploy
from another client, call sales.refresh() on the handle.
One AutoGraph per project¶
A project holds one AutoGraph service. deploy reloads the project and
refuses with AutoGraphAlreadyDeployedError
when one is already there, whichever client deployed it. undeploy needs no
service ID for the same reason: it removes the one the project has, or raises
AutoGraphNotDeployedError when there is none.
The ingestion methods raise the same error on a project without a service.
Asking a question¶
Once the graph is imported, questions go through a retriever on the same
project handle, not through autograph. See AutoRAG.