> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalinks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Datalinks.api

# datalinks.api package

### *class* datalinks.api.DataLinksAPI(config=None)

Bases: `object`

Class for interfacing with the DataLinks API.

Provides methods for ingesting data, managing namespaces, and querying data
from DataLinks. Designed to interact with a configurable
backend, providing flexibility for deployment environments.

* **Variables:**
  **config** – Configuration object containing API key, host, index, namespace,
  and object name.

#### ingest(data, inference\_steps=None, entity\_resolution=None, batch\_size=0, max\_attempts=3, curate=None, data\_description=None, schema\_definition=None, additional\_instructions=None)

Ingests data into the namespace by batching the given data and performing multiple retries
in case of failures. This function sends data in chunks (batches), to be processed through configured
inference steps, and to resolve entities based on the provided configuration. If a batch fails, it
is retried up to a maximum number of attempts.

* **Parameters:**
  * **data** (`List`\[`Dict`\[`str`, `Any`]]) – List of dictionaries, where each dictionary represents a data block to be ingested.
  * **inference\_steps** ([`Pipeline`](datalinks#datalinks.pipeline.Pipeline) | `None`) – Pipeline of inference steps to be applied for processing the data. If None the data will be ingested as is.
  * **entity\_resolution** ([`MatchTypeConfig`](datalinks#datalinks.links.MatchTypeConfig) | `None`) – Configuration specifying how entity resolution is to be performed.
  * **batch\_size** – Number of data blocks to be included in each batch. Defaults to the size of the
    entire dataset if not provided.
  * **max\_attempts** – Maximum number of retry attempts for failed batches. Defaults to the
    provided constant MAX\_INGEST\_ATTEMPTS.
  * **curate** (*Optional* \*\[\**bool* *]*) – If `True`, automatically curate ontology links after ingestion.
  * **data\_description** (*Optional* \*\[\**str* *]*) – Free-text description of the dataset to guide the AI during ingestion.
  * **schema\_definition** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Field-name-to-description mapping to guide the AI in structuring extracted data.
  * **additional\_instructions** (*Optional* \*\[\**str* *]*) – Additional free-text instructions to guide the AI during ingestion.
* **Return type:**
  [`IngestionResult`](#datalinks.api.datalinks.IngestionResult)
* **Returns:**
  An IngestionResult object containing lists of successfully ingested data blocks and
  data blocks that failed to be ingested.

#### create\_space(is\_private=True, data\_description=None, schema\_definition=None)

Creates a new space with the specified privacy settings. This function sends a
POST request to create a namespace with the given privacy status. Information
about the namespace creation will be logged, including the HTTP status code
and response reason. If the namespace already exists, a warning will be logged.

* **Parameters:**
  * **is\_private** (*bool*) – Determines whether the created namespace will be private
    or public.
  * **data\_description** (*Optional* \*\[\**str* *]*) – Free-text description of the dataset (max 10,000 chars).
  * **schema\_definition** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Field-name-to-description mapping to guide the AI in structuring data.
* **Return type:**
  `None`
* **Returns:**
  None
* **Raises:**
  **HTTPError** – If the HTTP request fails due to connectivity issues or
  server-side problems.

#### update\_infer\_definition(data\_description=None, schema\_definition=None)

Update the saved inference definition for the configured dataset.

The inference definition is used automatically on future ingest calls to guide
field extraction and normalization.

* **Parameters:**
  * **data\_description** (*Optional* \*\[\**str* *]*) – Free-text description of the dataset (max 10,000 chars).
  * **schema\_definition** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Field-name-to-description mapping to guide the AI in
    structuring extracted data.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### infer\_dataset\_description(sample, model=None, provider=None, current\_description=None, current\_schema=None)

Ask an agent to infer a data description and field schema from sampled data.

* **Parameters:**
  * **sample** (*Dataset*) – A sample of data rows to analyse.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"ollama"`).
  * **current\_description** (*Optional* \*\[\**str* *]*) – Existing description to refine.
  * **current\_schema** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Existing field schema to refine (field → description mapping).
* **Returns:**
  Inferred `dataDescription` and `fieldDefinition`.
* **Return type:**
  Dict
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### update\_sort\_order(order)

Update the display order of columns for the configured dataset.

* **Parameters:**
  **order** (*List* \*\[\**str* *]*) – Ordered list of all column names in the desired sequence.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### prepare\_multipart\_upload(filename, size)

Initiate a multipart upload and receive presigned URLs for each part.

Use this for large files. Upload each part directly to its presigned URL,
then call [`finish_multipart_upload()`](#datalinks.api.DataLinksAPI.finish_multipart_upload) with the returned ETags.

* **Parameters:**
  * **filename** (*str*) – Name of the file being uploaded.
  * **size** (*int*) – File size in bytes.
* **Returns:**
  Response containing `uploadId`, `key`, and presigned part URLs.
* **Return type:**
  Dict
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### finish\_multipart\_upload(upload\_id, key, parts, name=None, inference\_steps=None, entity\_resolution=None)

Complete a multipart upload after all parts have been uploaded.

* **Parameters:**
  * **upload\_id** (*str*) – Upload ID from [`prepare_multipart_upload()`](#datalinks.api.DataLinksAPI.prepare_multipart_upload).
  * **key** (*str*) – S3 object key from [`prepare_multipart_upload()`](#datalinks.api.DataLinksAPI.prepare_multipart_upload).
  * **parts** (*List* \*\[\**Dict* \*\[\**str* *,* *Any* *]* *]*) – List of completed parts, each with `partNumber` (int) and
    `etag` (str) returned by S3.
  * **name** (*Optional* \*\[\**str* *]*) – Optional label for the ingestion (e.g. original filename).
  * **inference\_steps** (*Optional* *\[*[*Pipeline*](datalinks#datalinks.pipeline.Pipeline) *]*) – Pipeline of inference steps to apply to the uploaded
    file during ingestion. If `None` the file is ingested as is.
  * **entity\_resolution** (*Optional* *\[*[*MatchTypeConfig*](datalinks#datalinks.links.MatchTypeConfig) *]*) – Configuration specifying how entity resolution is to
    be performed on the uploaded file.
* **Returns:**
  Ingestion result from the server.
* **Return type:**
  Dict
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### abort\_multipart\_upload(upload\_id, key)

Abort a multipart upload and clean up partial data.

* **Parameters:**
  * **upload\_id** (*str*) – Upload ID from [`prepare_multipart_upload()`](#datalinks.api.DataLinksAPI.prepare_multipart_upload).
  * **key** (*str*) – S3 object key from [`prepare_multipart_upload()`](#datalinks.api.DataLinksAPI.prepare_multipart_upload).
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### list\_ingestions(page\_size=25)

List ingestion attempts for the configured dataset, most recent first.

Each record contains `id`, `status`, `statusMessage`,
`processedBytes`, `expectedTotalBytes`, `processedRows`,
and `attributes`.

* **Parameters:**
  **page\_size** (*int*) – Number of records to return (1-100, default 25).
* **Returns:**
  List of ingestion attempt dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]

#### wait\_for\_ingestion(ingestion\_id, poll\_interval=5, timeout=1200)

Poll until the given ingestion reaches a terminal status.

Polls [`list_ingestions()`](#datalinks.api.DataLinksAPI.list_ingestions) every *poll\_interval* seconds until the
ingestion with *ingestion\_id* is no longer in a pending/processing
state, or until *timeout* seconds have elapsed.

* **Parameters:**
  * **ingestion\_id** (*str*) – Ingestion ID returned by [`finish_multipart_upload()`](#datalinks.api.DataLinksAPI.finish_multipart_upload).
  * **poll\_interval** (*int*) – Seconds between polls (default 5).
  * **timeout** (*int*) – Maximum seconds to wait before raising (default 600).
* **Returns:**
  The final ingestion record dict.
* **Return type:**
  Dict
* **Raises:**
  * **TimeoutError** – If *timeout* is exceeded before a terminal status.
  * [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If polling requests fail.

#### get\_dataset\_info()

Retrieve metadata for the configured dataset.

Returns a dict with `dataset`, `metadata`, and `inferDefinition` keys,
or `None` if the request fails.

* **Returns:**
  Dataset metadata dict, or None on failure.
* **Return type:**
  Optional\[Dict]

#### delete\_dataset()

Permanently delete the configured dataset, including all data, links, and metadata.

This action is irreversible (balefire).

* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### rename\_dataset(new\_name)

Rename the configured dataset.

* **Parameters:**
  **new\_name** (*str*) – The new dataset name.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### clear\_dataset()

Remove all data and links from the configured dataset.

The dataset itself (metadata, schema) is preserved. This action is irreversible.

* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### add\_link(from\_namespace, from\_dataset, from\_column, to\_namespace, to\_dataset, to\_column, match\_type, options=None)

Create a manual link between two dataset columns.

* **Parameters:**
  * **from\_namespace** (`str`) – Source namespace.
  * **from\_dataset** (`str`) – Source dataset name.
  * **from\_column** (`str`) – Source column name.
  * **to\_namespace** (`str`) – Target namespace.
  * **to\_dataset** (`str`) – Target dataset name.
  * **to\_column** (`str`) – Target column name.
  * **match\_type** (`str`) – Match type — `"ExactMatch"` or `"GeoMatch"`.
  * **options** (`Optional`\[`Dict`\[`str`, `Any`]]) – Optional match configuration (e.g. `minDistinct`, `distance`).
* **Returns:**
  True if the link was successfully created, False if already exists. None if failure.
* **Return type:**
  bool
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### preview\_links(data, entity\_resolution=None)

Preview what recalculating links would produce without saving changes.

* **Parameters:**
  * **data** (*Dataset*) – Array of ontology data objects (e.g. from [`query_data()`](#datalinks.api.DataLinksAPI.query_data)).
  * **entity\_resolution** (*Optional* *\[*[*MatchTypeConfig*](datalinks#datalinks.links.MatchTypeConfig) *]*) – Optional link matching configuration.
* **Returns:**
  Preview of link objects, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### rebuild\_links(data, entity\_resolution=None)

Recalculate links for the configured dataset based on current data.

* **Parameters:**
  * **data** (*Dataset*) – Array of ontology data objects (e.g. from [`query_data()`](#datalinks.api.DataLinksAPI.query_data)).
  * **entity\_resolution** (*Optional* *\[*[*MatchTypeConfig*](datalinks#datalinks.links.MatchTypeConfig) *]*) – Optional link matching configuration.
* **Returns:**
  Updated list of link objects, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### load\_links()

Retrieve active and suggested links for the configured dataset.

* **Returns:**
  A list of link objects, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]

#### list\_datasets(namespace=None)

Retrieves the list of datasets for the user, optionally filtered by a specific namespace.

* **Parameters:**
  **namespace** (*Optional* \*\[\**AnyStr* *]*) – Optional namespace to filter the datasets by.
  If provided, only datasets associated with the given
  namespace will be returned. If not provided, all datasets are
  retrieved.
* **Returns:**
  A list of datasets represented as dictionaries if the
  query is successful and returns a status code of 200, or
  None if the query fails or encounters an error.
* **Return type:**
  List\[Dict] | None

#### query\_data(query=None, is\_natural\_language=False, model=None, provider=None, include\_metadata=False, explain=False)

Queries data from a specified data source and processes the response.

The method allows querying with a specific query string or with a wildcard
(“\*”) for all data. The response from the query can be filtered to exclude
metadata fields if include\_metadata is set to False. Metadata fields are
identified by key names starting with an underscore.

* **Parameters:**
  * **query** (*str*) – The query string to use for fetching data. Defaults to “\*”,
    which retrieves all data.
  * **is\_natural\_language** (*bool*) – If True, the query is treated as a natural language query.
  * **model** (*str*) – The model name to use for inference.
  * **provider** (*str*) – The provider of the LLM model (ollama, openai, etc)
  * **include\_metadata** (*bool*) – Specifies whether to include metadata fields in
    the returned data. Defaults to False.
  * **explain** (*bool*) – If True, request an explanation of how the query was resolved.
* **Returns:**
  A list of records represented as dictionaries, or None if the query
  fails or an exception occurs during the request.
* **Return type:**
  List\[Dict] | None
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If a transport-level error occurs.

#### ask(query, model=None, provider=None, helper\_prompt=None)

Talk to your data with natural language using the DataLinks AutoRAG agent.

Streams the agent’s reasoning and final answer as Server-Sent Events. Events are
yielded in order: one `plan` event, one or more `step` events, then either an
`answer` event or an `error` event.

* **Parameters:**
  * **query** (*str*) – The natural language question to answer.
  * **model** (*str*) – The model name to use for inference.
  * **provider** (*str*) – The LLM provider (e.g. `openai`, `ollama`).
  * **helper\_prompt** (*str*) – Optional custom system prompt.
* **Returns:**
  An iterator of [`AskEvent`](#datalinks.api.AskEvent) objects.
* **Return type:**
  Iterator\[[AskEvent](#datalinks.api.AskEvent)]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### preview\_ingest(data, inference\_steps=None)

Process data through the ingestion pipeline without saving it to a dataset.

* **Parameters:**
  * **data** (*Dataset*) – List of data records to preview.
  * **inference\_steps** (*Optional* *\[*[*Pipeline*](datalinks#datalinks.pipeline.Pipeline) *]*) – Optional pipeline of inference steps to apply.
* **Returns:**
  List of processed preview records, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### infer\_schema(sample, model=None, provider=None, current\_schema=None)

Ask an agent to infer a field type schema from sampled data.

* **Parameters:**
  * **sample** (*Dataset*) – A sample of data rows to analyse.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"ollama"`).
  * **current\_schema** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Existing field schema to refine (field → description mapping).
* **Returns:**
  Dict with `schema` key mapping field names to their inferred types.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### retry\_ingestion(ingestion\_id)

Retry a failed ingestion by creating a new ingestion record from the original.

* **Parameters:**
  **ingestion\_id** (*str*) – The ID of the ingestion to retry.
* **Returns:**
  Dict with the new ingestion `id`, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### mark\_ingestion\_seen(ingestion\_id)

Mark an ingestion as seen, updating its `seenAt` timestamp.

* **Parameters:**
  **ingestion\_id** (*str*) – The ID of the ingestion to mark as seen.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### autorag(query, model=None, provider=None, helper\_prompt=None)

Answer a natural language question using the AutoRAG agent (non-streaming).

Returns the final answer and all intermediate steps once the agent completes.
For incremental streaming results, use [`ask()`](#datalinks.api.DataLinksAPI.ask) instead.

* **Parameters:**
  * **query** (*str*) – The natural language question to answer.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"ollama"`).
  * **helper\_prompt** (*Optional* \*\[\**str* *]*) – Optional custom system prompt.
* **Returns:**
  Dict with `response` (str) and `steps` (list) keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### request\_cleaning(prompts, output\_namespace, output\_dataset\_name)

Request a cleaning job for the configured dataset.

* **Parameters:**
  * **prompts** (*List* \*\[\**str* *]*) – 1–10 prompts describing each cleaning step in order.
  * **output\_namespace** (*str*) – Target namespace for the cleaned dataset.
  * **output\_dataset\_name** (*str*) – Name for the cleaned dataset (must be unused in target namespace).
* **Returns:**
  The `cleaningTaskId` UUID string, or None on failure.
* **Return type:**
  Optional\[str]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_cleaning\_code(cleaning\_task\_id)

Retrieve code files generated by the cleaning agent for a task.

* **Parameters:**
  **cleaning\_task\_id** (*str*) – UUID of the cleaning task.
* **Returns:**
  List of dicts with `name` and `content` keys, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_ontology()

Load the ontology (active links) for the configured dataset.

* **Returns:**
  List of link dicts, or None if no ontology exists or the request fails.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### save\_ontology(add=None, remove=None)

Save (update) the ontology for the configured dataset.

* **Parameters:**
  * **add** (*Optional* \*\[\**List* \*\[\**Dict* *]* *]*) – Links to add to the ontology.
  * **remove** (*Optional* \*\[\**List* \*\[\**Dict* *]* *]*) – Links to remove from the ontology.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### curate\_links(namespace=None, dataset=None, model=None, provider=None, activate=False)

Run the OntologyCurator agent to analyse computed links and optionally activate them.

When `activate=False` (default), the curated links are returned without being saved.
When `activate=True`, the curated links are added to the ontology.

* **Parameters:**
  * **namespace** (*Optional* \*\[\**str* *]*) – Namespace to curate. Defaults to the configured namespace.
  * **dataset** (*Optional* \*\[\**str* *]*) – Dataset to curate. If omitted, all datasets in the namespace are curated.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"anthropic"`).
  * **activate** (*bool*) – If `True`, add curated links to the ontology.
* **Returns:**
  Dict with `datasetsProcessed`, `totalSelected`, and optionally `curatedLinks`.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### rename\_namespace(new\_name)

Rename the configured namespace.

* **Parameters:**
  **new\_name** (*str*) – The new namespace name.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### list\_namespaces(user='self')

Retrieve namespaces for a user.

* **Parameters:**
  **user** (*str*) – Username or `"self"` for the current user.
* **Returns:**
  List of namespace dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### list\_all\_datasets\_schema()

Retrieve all datasets visible to the authenticated user (schema endpoint).

* **Returns:**
  List of dataset dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### list\_datasets\_in\_namespace\_schema(namespace=None, user='self')

Retrieve datasets within a specific namespace (schema endpoint).

* **Parameters:**
  * **namespace** (*Optional* \*\[\**str* *]*) – Namespace to list. Defaults to the configured namespace.
  * **user** (*str*) – Username or `"self"` for the current user.
* **Returns:**
  List of dataset dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### list\_tokens()

List all API tokens for the authenticated user.

* **Returns:**
  List of token dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### add\_token(name, expires\_at=None, access\_restricted\_to=None)

Create a new API token for the authenticated user.

* **Parameters:**
  * **name** (*str*) – Display name for the token.
  * **expires\_at** (*Optional* \*\[\**str* *]*) – Optional expiry timestamp (ISO 8601 string).
  * **access\_restricted\_to** (*Optional* \*\[\**List* \*\[\**Dict* *]* *]*) – Optional list of permission entries restricting access
    (each dict with `username`, `namespace`, and optionally `dataset`).
* **Returns:**
  Created token dict (includes the `token` secret), or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### delete\_token(token\_id)

Delete an API token.

* **Parameters:**
  **token\_id** (*str*) – ID of the token to delete.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### list\_token\_permissions(token\_id)

List permissions assigned to a token.

* **Parameters:**
  **token\_id** (*str*) – ID of the token.
* **Returns:**
  Dict with `restricted` (bool) and `permissions` (list) keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_usage\_history(on\_or\_after=None, before=None, page\_size=25, page\_cursor=None)

Retrieve historical usage data for the authenticated user.

* **Parameters:**
  * **on\_or\_after** (*Optional* \*\[\**str* *]*) – Return records on or after this ISO 8601 timestamp.
  * **before** (*Optional* \*\[\**str* *]*) – Return records before this ISO 8601 timestamp.
  * **page\_size** (*int*) – Number of records per page (default 25).
  * **page\_cursor** (*Optional* \*\[\**Dict* *]*) – Pagination cursor dict from a previous response.
* **Returns:**
  Dict with `data` and `meta` keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_usage\_by\_day(on\_or\_after=None, before=None, timezone='UTC')

Retrieve usage data aggregated by day for the authenticated user.

* **Parameters:**
  * **on\_or\_after** (*Optional* \*\[\**str* *]*) – Return records on or after this ISO 8601 timestamp.
  * **before** (*Optional* \*\[\**str* *]*) – Return records before this ISO 8601 timestamp.
  * **timezone** (*str*) – Timezone for date aggregation (e.g. `"America/New_York"`). Defaults to UTC.
* **Returns:**
  Dict with `data` and `meta` keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_agent\_run\_status(run\_id)

Get the current status of an agent run.

* **Parameters:**
  **run\_id** (*str*) – UUID of the agent run.
* **Returns:**
  Dict with `runId`, `agentKind`, `question`, `status`
  (`running`/`completed`/`failed`/`expired`), `canResume`,
  and optionally `lastNodeId`, `errorMessage`, `result`. None on
  failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### delete\_agent\_run(run\_id)

Permanently delete an agent run and its resume checkpoint.

* **Parameters:**
  **run\_id** (*str*) – UUID of the agent run.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails (e.g. 404 when
  the run does not exist or is not owned by the caller).
* **Return type:**
  `None`

#### resume\_agent\_run(run\_id)

Resume a previously paused or crashed agent run, streaming its events.

The first event is `run-started`, followed by the same domain events as
[`ask()`](#datalinks.api.DataLinksAPI.ask) (e.g. `plan`, `step`, `answer`). Terminal run states
arrive as a single synthetic event instead of a stream:

> * `completed` / `expired` (HTTP 410) — yielded as an
>   `AskEvent(type="terminal", data=<body>)` whose data carries the
>   original question and, for completed runs, the rendered result.
> * `failed` (HTTP 422) — yielded as an `AskEvent` of type
>   `"terminal"`.
> * not-found / not-owned (HTTP 404) — raises `DataLinksRequestError`.

* **Parameters:**
  **run\_id** (*str*) – UUID of the agent run to resume.
* **Returns:**
  An iterator of [`AskEvent`](#datalinks.api.AskEvent) objects.
* **Return type:**
  Iterator\[[AskEvent](#datalinks.api.AskEvent)]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – On 404 or transport-level failure.

#### list\_conversations(username='self', namespace=None)

List the caller’s conversations within a namespace (most-recently-updated first).

* **Parameters:**
  * **username** (*str*) – Owner username. Defaults to `"self"`.
  * **namespace** (*Optional* \*\[\**str* *]*) – Namespace to list within. Defaults to the configured namespace.
* **Returns:**
  Dict with a `conversations` list, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_conversation(conversation\_id)

Get a conversation and its turns (oldest first).

* **Parameters:**
  **conversation\_id** (*str*) – UUID of the conversation.
* **Returns:**
  Dict with `id`, `title`, and a `turns` list (each turn has
  `runId`, `question`, `status`, and optionally `result`), or
  None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

### *class* datalinks.api.AsyncDataLinksAPI(config=None)

Bases: `object`

Async counterpart of [`DataLinksAPI`](#datalinks.api.DataLinksAPI).

Method signatures mirror the sync facade — same parameter names, defaults,
and return types. Every networked method is `async def`. The streaming
`ask` method returns an `AsyncIterator` instead of an iterator.

Use `async with` for guaranteed cleanup of the underlying
`httpx.AsyncClient`, or call [`aclose()`](#datalinks.api.AsyncDataLinksAPI.aclose) manually:

```default theme={null}
async with AsyncDataLinksAPI() as api:
    datasets = await api.list_datasets()
```

#### *async* aclose()

Close the underlying `httpx.AsyncClient`.

* **Return type:**
  `None`

#### *async* ingest(data, inference\_steps=None, entity\_resolution=None, batch\_size=0, max\_attempts=3, curate=None, data\_description=None, schema\_definition=None, additional\_instructions=None)

Async variant of [`DataLinksAPI.ingest()`](#datalinks.api.DataLinksAPI.ingest).

Same batching + retry semantics as the sync facade.

* **Return type:**
  [`IngestionResult`](#datalinks.api.datalinks.IngestionResult)

#### *async* create\_space(is\_private=True, data\_description=None, schema\_definition=None)

* **Return type:**
  `None`

#### *async* update\_infer\_definition(data\_description=None, schema\_definition=None)

* **Return type:**
  `None`

#### *async* infer\_dataset\_description(sample, model=None, provider=None, current\_description=None, current\_schema=None)

* **Return type:**
  `Dict`

#### *async* update\_sort\_order(order)

* **Return type:**
  `None`

#### *async* prepare\_multipart\_upload(filename, size)

* **Return type:**
  `Dict`

#### *async* finish\_multipart\_upload(upload\_id, key, parts, name=None, inference\_steps=None, entity\_resolution=None)

* **Return type:**
  `Dict`

#### *async* abort\_multipart\_upload(upload\_id, key)

* **Return type:**
  `None`

#### *async* list\_ingestions(page\_size=25)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* wait\_for\_ingestion(ingestion\_id, poll\_interval=5, timeout=1200)

Async variant of [`DataLinksAPI.wait_for_ingestion()`](#datalinks.api.DataLinksAPI.wait_for_ingestion).

Polls via [`list_ingestions()`](#datalinks.api.AsyncDataLinksAPI.list_ingestions), awaiting `asyncio.sleep` between
ticks instead of blocking the event loop with `time.sleep`.

* **Return type:**
  `Dict`

#### *async* get\_dataset\_info()

* **Return type:**
  `Optional`\[`Dict`]

#### *async* delete\_dataset()

* **Return type:**
  `None`

#### *async* rename\_dataset(new\_name)

* **Return type:**
  `None`

#### *async* rename\_namespace(new\_name)

* **Return type:**
  `None`

#### *async* clear\_dataset()

* **Return type:**
  `None`

#### *async* add\_link(from\_namespace, from\_dataset, from\_column, to\_namespace, to\_dataset, to\_column, match\_type, options=None)

* **Return type:**
  `Optional`\[`bool`]

#### *async* preview\_links(data, entity\_resolution=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* rebuild\_links(data, entity\_resolution=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* load\_links()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_datasets(namespace=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_namespaces(user='self')

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_all\_datasets\_schema()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_datasets\_in\_namespace\_schema(namespace=None, user='self')

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* query\_data(query=None, is\_natural\_language=False, model=None, provider=None, include\_metadata=False, explain=False)

* **Return type:**
  `Optional`\[`List`\[`Dict`\[`str`, `Any`]]]

#### *async* autorag(query, model=None, provider=None, helper\_prompt=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* ask(query, model=None, provider=None, helper\_prompt=None)

Async SSE stream of [`DataLinksAPI.ask()`](#datalinks.api.DataLinksAPI.ask) events.

Yields [`AskEvent`](#datalinks.api.AskEvent) objects until the server closes the stream.

* **Return type:**
  `AsyncIterator`\[[`AskEvent`](#datalinks.api.datalinks.AskEvent)]

#### *async* preview\_ingest(data, inference\_steps=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* infer\_schema(sample, model=None, provider=None, current\_schema=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* retry\_ingestion(ingestion\_id)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* mark\_ingestion\_seen(ingestion\_id)

* **Return type:**
  `None`

#### *async* request\_cleaning(prompts, output\_namespace, output\_dataset\_name)

* **Return type:**
  `Optional`\[`str`]

#### *async* get\_cleaning\_code(cleaning\_task\_id)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* get\_ontology()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* save\_ontology(add=None, remove=None)

* **Return type:**
  `None`

#### *async* curate\_links(namespace=None, dataset=None, model=None, provider=None, activate=False)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* list\_tokens()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* add\_token(name, expires\_at=None, access\_restricted\_to=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* delete\_token(token\_id)

* **Return type:**
  `None`

#### *async* list\_token\_permissions(token\_id)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_usage\_history(on\_or\_after=None, before=None, page\_size=25, page\_cursor=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_usage\_by\_day(on\_or\_after=None, before=None, timezone='UTC')

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_agent\_run\_status(run\_id)

Get the current status of an agent run (see [`DataLinksAPI.get_agent_run_status()`](#datalinks.api.DataLinksAPI.get_agent_run_status)).

* **Return type:**
  `Optional`\[`Dict`]

#### *async* delete\_agent\_run(run\_id)

Permanently delete an agent run and its resume checkpoint (see [`DataLinksAPI.delete_agent_run()`](#datalinks.api.DataLinksAPI.delete_agent_run)).

* **Return type:**
  `None`

#### *async* resume\_agent\_run(run\_id)

Resume an agent run, streaming its events (see [`DataLinksAPI.resume_agent_run()`](#datalinks.api.DataLinksAPI.resume_agent_run)).

* **Return type:**
  `AsyncIterator`\[[`AskEvent`](#datalinks.api.datalinks.AskEvent)]

#### *async* list\_conversations(username='self', namespace=None)

List the caller’s conversations within a namespace (see [`DataLinksAPI.list_conversations()`](#datalinks.api.DataLinksAPI.list_conversations)).

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_conversation(conversation\_id)

Get a conversation and its turns (see [`DataLinksAPI.get_conversation()`](#datalinks.api.DataLinksAPI.get_conversation)).

* **Return type:**
  `Optional`\[`Dict`]

### *exception* datalinks.api.DataLinksRequestError(endpoint, e)

Bases: `Exception`

### *class* datalinks.api.DLConfig(host, apikey, namespace, objectname)

Bases: `object`

DLConfig class is a configuration container for managing the required settings
to interact with DataLinks. It loads configuration values from environment
variables to provide flexibility across different environments.

This class is designed to simplify the initialization and storage of connection
and namespace details required to communicate with DataLinks.

* **Variables:**
  * **host** – The host URL for the data layer connection.
  * **apikey** – The API key for authentication with the data layer.
  * **namespace** – The namespace for organizing data in the data layer.
  * **objectname** – The name of the object associated with the configuration.
    Defaults to an empty string.

#### host *: str*

#### apikey *: str*

#### namespace *: str*

#### objectname *: str*

#### *classmethod* from\_env(load\_dotenv=True)

### *class* datalinks.api.AskEvent(type, data)

Bases: `object`

Represents a single SSE event from the /query/ask streaming endpoint.

* **Variables:**
  * **type** – Event type — one of `plan`, `step`, `answer`, or `error`.
  * **data** – Parsed JSON payload for the event.

#### type *: str*

#### data *: Dict\[str, Any]*

### *class* datalinks.api.IngestionResult(successful, failed)

Bases: `object`

Represents the result of a data ingestion process into DataLinks.

This class is a data structure used to store the results of a data ingestion
operation. It separates the successfully ingested items from the failed ones,
enabling users to track and handle both cases effectively.

* **Variables:**
  * **successful** – A list of records successfully ingested. Each record is
    represented as a dictionary.
  * **failed** – A list of records that failed ingestion. Each record is
    represented as a dictionary.

#### successful *: List\[Dict\[str, Any]]*

#### failed *: List\[Dict\[str, Any]]*

### *class* datalinks.api.IngestProxyAPI(config=None)

Bases: `object`

Client for the DataLinks ingestion proxy (auto-modelling) service.

Wraps the `POST /api/pipeline`, `GET /api/pipeline/{runId}/stream`,
`GET /api/pipeline/{runId}/trace`, and `POST /api/pipeline/{runId}/hook`
endpoints.

* **Variables:**
  **config** – Proxy configuration.

#### run\_pipeline(, data=None, data\_url=None, data\_blob\_url=None, namespace=None, user\_prompt=None, model=True, ingest=True, ontology=True, max\_eval\_retries=3, max\_rows\_for\_modeling=20, max\_sample\_rows=10, enable\_human\_in\_the\_loop=False, predefined\_schema=None, explosion\_helper\_prompt=None, coalescence\_helper\_prompt=None, llm=None, datalinks\_inference\_settings=None)

Start a full pipeline run (auto-modelling + ingest).

Exactly one of *data*, *data\_url*, or *data\_blob\_url* must be provided.

Returns a [`PipelineRun`](#datalinks.api.PipelineRun) whose `run_id` attribute is the workflow
run identifier and which can be iterated to receive NDJSON progress events.

* **Parameters:**
  * **data** (`Optional`\[`List`\[`Dict`\[`str`, `Any`]]]) – Inline JSON array of row objects.
  * **data\_url** (`Optional`\[`str`]) – Remote URL returning a JSON array (fetched by the pipeline).
  * **data\_blob\_url** (`Optional`\[`str`]) – Pre-uploaded Vercel Blob URL.
  * **namespace** (`Optional`\[`str`]) – Target namespace; defaults to `config.namespace`.
  * **user\_prompt** (`Optional`\[`str`]) – Domain goals; inferred from data when omitted.
  * **model** (`bool`) – Run the model phase (default True).
  * **ingest** (`bool`) – Run the ingest phase (default True).
  * **ontology** (`bool`) – Run namespace curation after ingest (default True).
  * **max\_eval\_retries** (`int`) – Max modelling iterations (default 3).
  * **max\_rows\_for\_modeling** (`int`) – Rows sent to the LLM for schema modelling (default 20).
  * **max\_sample\_rows** (`int`) – Sample rows generated for preview (default 10).
  * **enable\_human\_in\_the\_loop** (`bool`) – Surface clarification + schema review hooks (default False).
  * **predefined\_schema** (`Optional`\[`Dict`\[`str`, `Any`]]) – Skip model phase when provided.
  * **explosion\_helper\_prompt** (`Optional`\[`str`]) – Extra context injected into the explode step.
  * **coalescence\_helper\_prompt** (`Optional`\[`str`]) – Extra context injected into the coalesce step.
  * **llm** (`Optional`\[`Dict`\[`str`, `Any`]]) – LLM configuration dict with optional keys: `provider`, `model`,
    `explosionTemperature`, `coalescenceTemperature`, `evaluationTemperature`,
    `ontologyTemperature`.
  * **datalinks\_inference\_settings** (`Optional`\[`Dict`\[`str`, `Any`]]) – DataLinks inference settings dict with optional keys:
    `provider`, `model`, `ontologyCurationProvider`, `ontologyCurationModel`.
* **Return type:**
  [`PipelineRun`](#datalinks.api.ingest_proxy.PipelineRun)
* **Returns:**
  A [`PipelineRun`](#datalinks.api.PipelineRun) instance.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### stream\_pipeline(run\_id, start\_index=0)

Stream progress events for an existing pipeline run.

* **Parameters:**
  * **run\_id** (`str`) – Workflow run identifier returned by [`run_pipeline()`](#datalinks.api.IngestProxyAPI.run_pipeline).
  * **start\_index** (`int`) – Resume from this event index (default 0).  Pass the
    number of events already received to skip replaying them on reconnect.
* **Return type:**
  `Iterator`\[`Dict`\[`str`, `Any`]]
* **Returns:**
  An iterator of NDJSON event dicts.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_pipeline\_trace(run\_id)

Download the full trace for a completed pipeline run.

* **Parameters:**
  **run\_id** (`str`) – Workflow run identifier.
* **Return type:**
  `Optional`\[`Dict`\[`str`, `Any`]]
* **Returns:**
  Dict with LLM calls, token usage, and step durations, or None on failure.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### resume\_pipeline\_hook(run\_id, payload)

Resume a human-in-the-loop hook (clarification, schema review, or token refresh).

* **Parameters:**
  * **run\_id** (`str`) – Workflow run identifier.
  * **payload** (`Dict`\[`str`, `Any`]) – Hook response payload.
* **Return type:**
  `Optional`\[`Dict`\[`str`, `Any`]]
* **Returns:**
  Response dict, or None on failure.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

### *class* datalinks.api.IngestProxyConfig(host, datalinks\_token, datalinks\_username, namespace)

Bases: `object`

Configuration for the DataLinks ingestion proxy (auto-modelling) service.

* **Variables:**
  * **host** – Base URL of the ingestion proxy (e.g. `http://localhost:3003`).
  * **datalinks\_token** – DataLinks JWT token sent as `Authorization: Bearer` (`DL_API_KEY`).
  * **datalinks\_username** – DataLinks username included in the request body (`DL_USERNAME`).
  * **namespace** – Default target namespace (`DL_NAMESPACE`).

#### host *: str*

#### datalinks\_token *: str*

#### datalinks\_username *: str*

#### namespace *: str*

#### *classmethod* from\_env(load\_dotenv=True)

* **Return type:**
  [`IngestProxyConfig`](#datalinks.api.ingest_proxy.IngestProxyConfig)

### *class* datalinks.api.PipelineRun(run\_id, stream\_fn)

Bases: `object`

Wraps a pipeline run with automatic stream reconnection.

Provides the workflow `run_id` (from the `x-workflow-run-id` response
header) and an iterable interface over the NDJSON progress events.

The iterator reconnects transparently on connection drops, resuming from
the last received event via the `startIndex` query parameter.  Iteration
ends only when an explicit `complete` or `error` event is received.

Usage:

```default theme={null}
run = proxy.run_pipeline(data=[...])
print(run.run_id)
for event in run:
    print(event)
```

Can also be used as a context manager:

```default theme={null}
with proxy.run_pipeline(data=[...]) as run:
    for event in run:
        process(event)
```

#### close()

* **Return type:**
  `None`

## Submodules

## datalinks.api.async\_datalinks module

Async sibling of [`datalinks.api.DataLinksAPI`](#datalinks.api.DataLinksAPI).

`AsyncDataLinksAPI` exposes the same surface as `DataLinksAPI` but every
remote-call method is an `async def` that dispatches through the underlying
`httpx.AsyncClient`. The two facades share the same generated client (which
holds both sync and async httpx clients internally) and the same body-building
typed models, so spec drift is caught uniformly.

Use this when you need concurrency — e.g. fanning out queries, embedding the
SDK in an async web service. For one-shot scripts, prefer `DataLinksAPI`.

### *class* datalinks.api.async\_datalinks.AsyncDataLinksAPI(config=None)

Bases: `object`

Async counterpart of `DataLinksAPI`.

Method signatures mirror the sync facade — same parameter names, defaults,
and return types. Every networked method is `async def`. The streaming
`ask` method returns an `AsyncIterator` instead of an iterator.

Use `async with` for guaranteed cleanup of the underlying
`httpx.AsyncClient`, or call [`aclose()`](#datalinks.api.async_datalinks.AsyncDataLinksAPI.aclose) manually:

```default theme={null}
async with AsyncDataLinksAPI() as api:
    datasets = await api.list_datasets()
```

#### *async* aclose()

Close the underlying `httpx.AsyncClient`.

* **Return type:**
  `None`

#### *async* ingest(data, inference\_steps=None, entity\_resolution=None, batch\_size=0, max\_attempts=3, curate=None, data\_description=None, schema\_definition=None, additional\_instructions=None)

Async variant of `DataLinksAPI.ingest()`.

Same batching + retry semantics as the sync facade.

* **Return type:**
  [`IngestionResult`](#datalinks.api.datalinks.IngestionResult)

#### *async* create\_space(is\_private=True, data\_description=None, schema\_definition=None)

* **Return type:**
  `None`

#### *async* update\_infer\_definition(data\_description=None, schema\_definition=None)

* **Return type:**
  `None`

#### *async* infer\_dataset\_description(sample, model=None, provider=None, current\_description=None, current\_schema=None)

* **Return type:**
  `Dict`

#### *async* update\_sort\_order(order)

* **Return type:**
  `None`

#### *async* prepare\_multipart\_upload(filename, size)

* **Return type:**
  `Dict`

#### *async* finish\_multipart\_upload(upload\_id, key, parts, name=None, inference\_steps=None, entity\_resolution=None)

* **Return type:**
  `Dict`

#### *async* abort\_multipart\_upload(upload\_id, key)

* **Return type:**
  `None`

#### *async* list\_ingestions(page\_size=25)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* wait\_for\_ingestion(ingestion\_id, poll\_interval=5, timeout=1200)

Async variant of `DataLinksAPI.wait_for_ingestion()`.

Polls via [`list_ingestions()`](#datalinks.api.async_datalinks.AsyncDataLinksAPI.list_ingestions), awaiting `asyncio.sleep` between
ticks instead of blocking the event loop with `time.sleep`.

* **Return type:**
  `Dict`

#### *async* get\_dataset\_info()

* **Return type:**
  `Optional`\[`Dict`]

#### *async* delete\_dataset()

* **Return type:**
  `None`

#### *async* rename\_dataset(new\_name)

* **Return type:**
  `None`

#### *async* rename\_namespace(new\_name)

* **Return type:**
  `None`

#### *async* clear\_dataset()

* **Return type:**
  `None`

#### *async* add\_link(from\_namespace, from\_dataset, from\_column, to\_namespace, to\_dataset, to\_column, match\_type, options=None)

* **Return type:**
  `Optional`\[`bool`]

#### *async* preview\_links(data, entity\_resolution=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* rebuild\_links(data, entity\_resolution=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* load\_links()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_datasets(namespace=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_namespaces(user='self')

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_all\_datasets\_schema()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* list\_datasets\_in\_namespace\_schema(namespace=None, user='self')

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* query\_data(query=None, is\_natural\_language=False, model=None, provider=None, include\_metadata=False, explain=False)

* **Return type:**
  `Optional`\[`List`\[`Dict`\[`str`, `Any`]]]

#### *async* autorag(query, model=None, provider=None, helper\_prompt=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* ask(query, model=None, provider=None, helper\_prompt=None)

Async SSE stream of `DataLinksAPI.ask()` events.

Yields `AskEvent` objects until the server closes the stream.

* **Return type:**
  `AsyncIterator`\[[`AskEvent`](#datalinks.api.datalinks.AskEvent)]

#### *async* preview\_ingest(data, inference\_steps=None)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* infer\_schema(sample, model=None, provider=None, current\_schema=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* retry\_ingestion(ingestion\_id)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* mark\_ingestion\_seen(ingestion\_id)

* **Return type:**
  `None`

#### *async* request\_cleaning(prompts, output\_namespace, output\_dataset\_name)

* **Return type:**
  `Optional`\[`str`]

#### *async* get\_cleaning\_code(cleaning\_task\_id)

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* get\_ontology()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* save\_ontology(add=None, remove=None)

* **Return type:**
  `None`

#### *async* curate\_links(namespace=None, dataset=None, model=None, provider=None, activate=False)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* list\_tokens()

* **Return type:**
  `Optional`\[`List`\[`Dict`]]

#### *async* add\_token(name, expires\_at=None, access\_restricted\_to=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* delete\_token(token\_id)

* **Return type:**
  `None`

#### *async* list\_token\_permissions(token\_id)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_usage\_history(on\_or\_after=None, before=None, page\_size=25, page\_cursor=None)

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_usage\_by\_day(on\_or\_after=None, before=None, timezone='UTC')

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_agent\_run\_status(run\_id)

Get the current status of an agent run (see `DataLinksAPI.get_agent_run_status()`).

* **Return type:**
  `Optional`\[`Dict`]

#### *async* delete\_agent\_run(run\_id)

Permanently delete an agent run and its resume checkpoint (see `DataLinksAPI.delete_agent_run()`).

* **Return type:**
  `None`

#### *async* resume\_agent\_run(run\_id)

Resume an agent run, streaming its events (see `DataLinksAPI.resume_agent_run()`).

* **Return type:**
  `AsyncIterator`\[[`AskEvent`](#datalinks.api.datalinks.AskEvent)]

#### *async* list\_conversations(username='self', namespace=None)

List the caller’s conversations within a namespace (see `DataLinksAPI.list_conversations()`).

* **Return type:**
  `Optional`\[`Dict`]

#### *async* get\_conversation(conversation\_id)

Get a conversation and its turns (see `DataLinksAPI.get_conversation()`).

* **Return type:**
  `Optional`\[`Dict`]

## datalinks.api.datalinks module

### *class* datalinks.api.datalinks.DLConfig(host, apikey, namespace, objectname)

Bases: `object`

DLConfig class is a configuration container for managing the required settings
to interact with DataLinks. It loads configuration values from environment
variables to provide flexibility across different environments.

This class is designed to simplify the initialization and storage of connection
and namespace details required to communicate with DataLinks.

* **Variables:**
  * **host** – The host URL for the data layer connection.
  * **apikey** – The API key for authentication with the data layer.
  * **namespace** – The namespace for organizing data in the data layer.
  * **objectname** – The name of the object associated with the configuration.
    Defaults to an empty string.

#### host *: str*

#### apikey *: str*

#### namespace *: str*

#### objectname *: str*

#### *classmethod* from\_env(load\_dotenv=True)

### *class* datalinks.api.datalinks.AskEvent(type, data)

Bases: `object`

Represents a single SSE event from the /query/ask streaming endpoint.

* **Variables:**
  * **type** – Event type — one of `plan`, `step`, `answer`, or `error`.
  * **data** – Parsed JSON payload for the event.

#### type *: str*

#### data *: Dict\[str, Any]*

### *class* datalinks.api.datalinks.IngestionResult(successful, failed)

Bases: `object`

Represents the result of a data ingestion process into DataLinks.

This class is a data structure used to store the results of a data ingestion
operation. It separates the successfully ingested items from the failed ones,
enabling users to track and handle both cases effectively.

* **Variables:**
  * **successful** – A list of records successfully ingested. Each record is
    represented as a dictionary.
  * **failed** – A list of records that failed ingestion. Each record is
    represented as a dictionary.

#### successful *: List\[Dict\[str, Any]]*

#### failed *: List\[Dict\[str, Any]]*

### *exception* datalinks.api.datalinks.DataLinksRequestError(endpoint, e)

Bases: `Exception`

### *class* datalinks.api.datalinks.DataLinksAPI(config=None)

Bases: `object`

Class for interfacing with the DataLinks API.

Provides methods for ingesting data, managing namespaces, and querying data
from DataLinks. Designed to interact with a configurable
backend, providing flexibility for deployment environments.

* **Variables:**
  **config** – Configuration object containing API key, host, index, namespace,
  and object name.

#### config *: [DLConfig](#datalinks.api.datalinks.DLConfig)*

#### ingest(data, inference\_steps=None, entity\_resolution=None, batch\_size=0, max\_attempts=3, curate=None, data\_description=None, schema\_definition=None, additional\_instructions=None)

Ingests data into the namespace by batching the given data and performing multiple retries
in case of failures. This function sends data in chunks (batches), to be processed through configured
inference steps, and to resolve entities based on the provided configuration. If a batch fails, it
is retried up to a maximum number of attempts.

* **Parameters:**
  * **data** (`List`\[`Dict`\[`str`, `Any`]]) – List of dictionaries, where each dictionary represents a data block to be ingested.
  * **inference\_steps** ([`Pipeline`](datalinks#datalinks.pipeline.Pipeline) | `None`) – Pipeline of inference steps to be applied for processing the data. If None the data will be ingested as is.
  * **entity\_resolution** ([`MatchTypeConfig`](datalinks#datalinks.links.MatchTypeConfig) | `None`) – Configuration specifying how entity resolution is to be performed.
  * **batch\_size** – Number of data blocks to be included in each batch. Defaults to the size of the
    entire dataset if not provided.
  * **max\_attempts** – Maximum number of retry attempts for failed batches. Defaults to the
    provided constant MAX\_INGEST\_ATTEMPTS.
  * **curate** (*Optional* \*\[\**bool* *]*) – If `True`, automatically curate ontology links after ingestion.
  * **data\_description** (*Optional* \*\[\**str* *]*) – Free-text description of the dataset to guide the AI during ingestion.
  * **schema\_definition** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Field-name-to-description mapping to guide the AI in structuring extracted data.
  * **additional\_instructions** (*Optional* \*\[\**str* *]*) – Additional free-text instructions to guide the AI during ingestion.
* **Return type:**
  [`IngestionResult`](#datalinks.api.datalinks.IngestionResult)
* **Returns:**
  An IngestionResult object containing lists of successfully ingested data blocks and
  data blocks that failed to be ingested.

#### create\_space(is\_private=True, data\_description=None, schema\_definition=None)

Creates a new space with the specified privacy settings. This function sends a
POST request to create a namespace with the given privacy status. Information
about the namespace creation will be logged, including the HTTP status code
and response reason. If the namespace already exists, a warning will be logged.

* **Parameters:**
  * **is\_private** (*bool*) – Determines whether the created namespace will be private
    or public.
  * **data\_description** (*Optional* \*\[\**str* *]*) – Free-text description of the dataset (max 10,000 chars).
  * **schema\_definition** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Field-name-to-description mapping to guide the AI in structuring data.
* **Return type:**
  `None`
* **Returns:**
  None
* **Raises:**
  **HTTPError** – If the HTTP request fails due to connectivity issues or
  server-side problems.

#### update\_infer\_definition(data\_description=None, schema\_definition=None)

Update the saved inference definition for the configured dataset.

The inference definition is used automatically on future ingest calls to guide
field extraction and normalization.

* **Parameters:**
  * **data\_description** (*Optional* \*\[\**str* *]*) – Free-text description of the dataset (max 10,000 chars).
  * **schema\_definition** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Field-name-to-description mapping to guide the AI in
    structuring extracted data.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### infer\_dataset\_description(sample, model=None, provider=None, current\_description=None, current\_schema=None)

Ask an agent to infer a data description and field schema from sampled data.

* **Parameters:**
  * **sample** (*Dataset*) – A sample of data rows to analyse.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"ollama"`).
  * **current\_description** (*Optional* \*\[\**str* *]*) – Existing description to refine.
  * **current\_schema** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Existing field schema to refine (field → description mapping).
* **Returns:**
  Inferred `dataDescription` and `fieldDefinition`.
* **Return type:**
  Dict
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### update\_sort\_order(order)

Update the display order of columns for the configured dataset.

* **Parameters:**
  **order** (*List* \*\[\**str* *]*) – Ordered list of all column names in the desired sequence.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### prepare\_multipart\_upload(filename, size)

Initiate a multipart upload and receive presigned URLs for each part.

Use this for large files. Upload each part directly to its presigned URL,
then call [`finish_multipart_upload()`](#datalinks.api.datalinks.DataLinksAPI.finish_multipart_upload) with the returned ETags.

* **Parameters:**
  * **filename** (*str*) – Name of the file being uploaded.
  * **size** (*int*) – File size in bytes.
* **Returns:**
  Response containing `uploadId`, `key`, and presigned part URLs.
* **Return type:**
  Dict
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### finish\_multipart\_upload(upload\_id, key, parts, name=None, inference\_steps=None, entity\_resolution=None)

Complete a multipart upload after all parts have been uploaded.

* **Parameters:**
  * **upload\_id** (*str*) – Upload ID from [`prepare_multipart_upload()`](#datalinks.api.datalinks.DataLinksAPI.prepare_multipart_upload).
  * **key** (*str*) – S3 object key from [`prepare_multipart_upload()`](#datalinks.api.datalinks.DataLinksAPI.prepare_multipart_upload).
  * **parts** (*List* \*\[\**Dict* \*\[\**str* *,* *Any* *]* *]*) – List of completed parts, each with `partNumber` (int) and
    `etag` (str) returned by S3.
  * **name** (*Optional* \*\[\**str* *]*) – Optional label for the ingestion (e.g. original filename).
  * **inference\_steps** (*Optional* *\[*[*Pipeline*](datalinks#datalinks.pipeline.Pipeline) *]*) – Pipeline of inference steps to apply to the uploaded
    file during ingestion. If `None` the file is ingested as is.
  * **entity\_resolution** (*Optional* *\[*[*MatchTypeConfig*](datalinks#datalinks.links.MatchTypeConfig) *]*) – Configuration specifying how entity resolution is to
    be performed on the uploaded file.
* **Returns:**
  Ingestion result from the server.
* **Return type:**
  Dict
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### abort\_multipart\_upload(upload\_id, key)

Abort a multipart upload and clean up partial data.

* **Parameters:**
  * **upload\_id** (*str*) – Upload ID from [`prepare_multipart_upload()`](#datalinks.api.datalinks.DataLinksAPI.prepare_multipart_upload).
  * **key** (*str*) – S3 object key from [`prepare_multipart_upload()`](#datalinks.api.datalinks.DataLinksAPI.prepare_multipart_upload).
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### list\_ingestions(page\_size=25)

List ingestion attempts for the configured dataset, most recent first.

Each record contains `id`, `status`, `statusMessage`,
`processedBytes`, `expectedTotalBytes`, `processedRows`,
and `attributes`.

* **Parameters:**
  **page\_size** (*int*) – Number of records to return (1-100, default 25).
* **Returns:**
  List of ingestion attempt dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]

#### wait\_for\_ingestion(ingestion\_id, poll\_interval=5, timeout=1200)

Poll until the given ingestion reaches a terminal status.

Polls [`list_ingestions()`](#datalinks.api.datalinks.DataLinksAPI.list_ingestions) every *poll\_interval* seconds until the
ingestion with *ingestion\_id* is no longer in a pending/processing
state, or until *timeout* seconds have elapsed.

* **Parameters:**
  * **ingestion\_id** (*str*) – Ingestion ID returned by [`finish_multipart_upload()`](#datalinks.api.datalinks.DataLinksAPI.finish_multipart_upload).
  * **poll\_interval** (*int*) – Seconds between polls (default 5).
  * **timeout** (*int*) – Maximum seconds to wait before raising (default 600).
* **Returns:**
  The final ingestion record dict.
* **Return type:**
  Dict
* **Raises:**
  * **TimeoutError** – If *timeout* is exceeded before a terminal status.
  * [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If polling requests fail.

#### get\_dataset\_info()

Retrieve metadata for the configured dataset.

Returns a dict with `dataset`, `metadata`, and `inferDefinition` keys,
or `None` if the request fails.

* **Returns:**
  Dataset metadata dict, or None on failure.
* **Return type:**
  Optional\[Dict]

#### delete\_dataset()

Permanently delete the configured dataset, including all data, links, and metadata.

This action is irreversible (balefire).

* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### rename\_dataset(new\_name)

Rename the configured dataset.

* **Parameters:**
  **new\_name** (*str*) – The new dataset name.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### clear\_dataset()

Remove all data and links from the configured dataset.

The dataset itself (metadata, schema) is preserved. This action is irreversible.

* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### add\_link(from\_namespace, from\_dataset, from\_column, to\_namespace, to\_dataset, to\_column, match\_type, options=None)

Create a manual link between two dataset columns.

* **Parameters:**
  * **from\_namespace** (`str`) – Source namespace.
  * **from\_dataset** (`str`) – Source dataset name.
  * **from\_column** (`str`) – Source column name.
  * **to\_namespace** (`str`) – Target namespace.
  * **to\_dataset** (`str`) – Target dataset name.
  * **to\_column** (`str`) – Target column name.
  * **match\_type** (`str`) – Match type — `"ExactMatch"` or `"GeoMatch"`.
  * **options** (`Optional`\[`Dict`\[`str`, `Any`]]) – Optional match configuration (e.g. `minDistinct`, `distance`).
* **Returns:**
  True if the link was successfully created, False if already exists. None if failure.
* **Return type:**
  bool
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### preview\_links(data, entity\_resolution=None)

Preview what recalculating links would produce without saving changes.

* **Parameters:**
  * **data** (*Dataset*) – Array of ontology data objects (e.g. from [`query_data()`](#datalinks.api.datalinks.DataLinksAPI.query_data)).
  * **entity\_resolution** (*Optional* *\[*[*MatchTypeConfig*](datalinks#datalinks.links.MatchTypeConfig) *]*) – Optional link matching configuration.
* **Returns:**
  Preview of link objects, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### rebuild\_links(data, entity\_resolution=None)

Recalculate links for the configured dataset based on current data.

* **Parameters:**
  * **data** (*Dataset*) – Array of ontology data objects (e.g. from [`query_data()`](#datalinks.api.datalinks.DataLinksAPI.query_data)).
  * **entity\_resolution** (*Optional* *\[*[*MatchTypeConfig*](datalinks#datalinks.links.MatchTypeConfig) *]*) – Optional link matching configuration.
* **Returns:**
  Updated list of link objects, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### load\_links()

Retrieve active and suggested links for the configured dataset.

* **Returns:**
  A list of link objects, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]

#### list\_datasets(namespace=None)

Retrieves the list of datasets for the user, optionally filtered by a specific namespace.

* **Parameters:**
  **namespace** (*Optional* \*\[\**AnyStr* *]*) – Optional namespace to filter the datasets by.
  If provided, only datasets associated with the given
  namespace will be returned. If not provided, all datasets are
  retrieved.
* **Returns:**
  A list of datasets represented as dictionaries if the
  query is successful and returns a status code of 200, or
  None if the query fails or encounters an error.
* **Return type:**
  List\[Dict] | None

#### query\_data(query=None, is\_natural\_language=False, model=None, provider=None, include\_metadata=False, explain=False)

Queries data from a specified data source and processes the response.

The method allows querying with a specific query string or with a wildcard
(“\*”) for all data. The response from the query can be filtered to exclude
metadata fields if include\_metadata is set to False. Metadata fields are
identified by key names starting with an underscore.

* **Parameters:**
  * **query** (*str*) – The query string to use for fetching data. Defaults to “\*”,
    which retrieves all data.
  * **is\_natural\_language** (*bool*) – If True, the query is treated as a natural language query.
  * **model** (*str*) – The model name to use for inference.
  * **provider** (*str*) – The provider of the LLM model (ollama, openai, etc)
  * **include\_metadata** (*bool*) – Specifies whether to include metadata fields in
    the returned data. Defaults to False.
  * **explain** (*bool*) – If True, request an explanation of how the query was resolved.
* **Returns:**
  A list of records represented as dictionaries, or None if the query
  fails or an exception occurs during the request.
* **Return type:**
  List\[Dict] | None
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If a transport-level error occurs.

#### ask(query, model=None, provider=None, helper\_prompt=None)

Talk to your data with natural language using the DataLinks AutoRAG agent.

Streams the agent’s reasoning and final answer as Server-Sent Events. Events are
yielded in order: one `plan` event, one or more `step` events, then either an
`answer` event or an `error` event.

* **Parameters:**
  * **query** (*str*) – The natural language question to answer.
  * **model** (*str*) – The model name to use for inference.
  * **provider** (*str*) – The LLM provider (e.g. `openai`, `ollama`).
  * **helper\_prompt** (*str*) – Optional custom system prompt.
* **Returns:**
  An iterator of [`AskEvent`](#datalinks.api.datalinks.AskEvent) objects.
* **Return type:**
  Iterator\[[AskEvent](#datalinks.api.datalinks.AskEvent)]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### preview\_ingest(data, inference\_steps=None)

Process data through the ingestion pipeline without saving it to a dataset.

* **Parameters:**
  * **data** (*Dataset*) – List of data records to preview.
  * **inference\_steps** (*Optional* *\[*[*Pipeline*](datalinks#datalinks.pipeline.Pipeline) *]*) – Optional pipeline of inference steps to apply.
* **Returns:**
  List of processed preview records, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### infer\_schema(sample, model=None, provider=None, current\_schema=None)

Ask an agent to infer a field type schema from sampled data.

* **Parameters:**
  * **sample** (*Dataset*) – A sample of data rows to analyse.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"ollama"`).
  * **current\_schema** (*Optional* \*\[\**Dict* \*\[\**str* *,* *str* *]* *]*) – Existing field schema to refine (field → description mapping).
* **Returns:**
  Dict with `schema` key mapping field names to their inferred types.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### retry\_ingestion(ingestion\_id)

Retry a failed ingestion by creating a new ingestion record from the original.

* **Parameters:**
  **ingestion\_id** (*str*) – The ID of the ingestion to retry.
* **Returns:**
  Dict with the new ingestion `id`, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### mark\_ingestion\_seen(ingestion\_id)

Mark an ingestion as seen, updating its `seenAt` timestamp.

* **Parameters:**
  **ingestion\_id** (*str*) – The ID of the ingestion to mark as seen.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### autorag(query, model=None, provider=None, helper\_prompt=None)

Answer a natural language question using the AutoRAG agent (non-streaming).

Returns the final answer and all intermediate steps once the agent completes.
For incremental streaming results, use [`ask()`](#datalinks.api.datalinks.DataLinksAPI.ask) instead.

* **Parameters:**
  * **query** (*str*) – The natural language question to answer.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"ollama"`).
  * **helper\_prompt** (*Optional* \*\[\**str* *]*) – Optional custom system prompt.
* **Returns:**
  Dict with `response` (str) and `steps` (list) keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### request\_cleaning(prompts, output\_namespace, output\_dataset\_name)

Request a cleaning job for the configured dataset.

* **Parameters:**
  * **prompts** (*List* \*\[\**str* *]*) – 1–10 prompts describing each cleaning step in order.
  * **output\_namespace** (*str*) – Target namespace for the cleaned dataset.
  * **output\_dataset\_name** (*str*) – Name for the cleaned dataset (must be unused in target namespace).
* **Returns:**
  The `cleaningTaskId` UUID string, or None on failure.
* **Return type:**
  Optional\[str]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### get\_cleaning\_code(cleaning\_task\_id)

Retrieve code files generated by the cleaning agent for a task.

* **Parameters:**
  **cleaning\_task\_id** (*str*) – UUID of the cleaning task.
* **Returns:**
  List of dicts with `name` and `content` keys, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### get\_ontology()

Load the ontology (active links) for the configured dataset.

* **Returns:**
  List of link dicts, or None if no ontology exists or the request fails.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### save\_ontology(add=None, remove=None)

Save (update) the ontology for the configured dataset.

* **Parameters:**
  * **add** (*Optional* \*\[\**List* \*\[\**Dict* *]* *]*) – Links to add to the ontology.
  * **remove** (*Optional* \*\[\**List* \*\[\**Dict* *]* *]*) – Links to remove from the ontology.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### curate\_links(namespace=None, dataset=None, model=None, provider=None, activate=False)

Run the OntologyCurator agent to analyse computed links and optionally activate them.

When `activate=False` (default), the curated links are returned without being saved.
When `activate=True`, the curated links are added to the ontology.

* **Parameters:**
  * **namespace** (*Optional* \*\[\**str* *]*) – Namespace to curate. Defaults to the configured namespace.
  * **dataset** (*Optional* \*\[\**str* *]*) – Dataset to curate. If omitted, all datasets in the namespace are curated.
  * **model** (*Optional* \*\[\**str* *]*) – LLM model name.
  * **provider** (*Optional* \*\[\**str* *]*) – LLM provider (e.g. `"openai"`, `"anthropic"`).
  * **activate** (*bool*) – If `True`, add curated links to the ontology.
* **Returns:**
  Dict with `datasetsProcessed`, `totalSelected`, and optionally `curatedLinks`.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### rename\_namespace(new\_name)

Rename the configured namespace.

* **Parameters:**
  **new\_name** (*str*) – The new namespace name.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### list\_namespaces(user='self')

Retrieve namespaces for a user.

* **Parameters:**
  **user** (*str*) – Username or `"self"` for the current user.
* **Returns:**
  List of namespace dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### list\_all\_datasets\_schema()

Retrieve all datasets visible to the authenticated user (schema endpoint).

* **Returns:**
  List of dataset dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### list\_datasets\_in\_namespace\_schema(namespace=None, user='self')

Retrieve datasets within a specific namespace (schema endpoint).

* **Parameters:**
  * **namespace** (*Optional* \*\[\**str* *]*) – Namespace to list. Defaults to the configured namespace.
  * **user** (*str*) – Username or `"self"` for the current user.
* **Returns:**
  List of dataset dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### list\_tokens()

List all API tokens for the authenticated user.

* **Returns:**
  List of token dicts, or None on failure.
* **Return type:**
  Optional\[List\[Dict]]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### add\_token(name, expires\_at=None, access\_restricted\_to=None)

Create a new API token for the authenticated user.

* **Parameters:**
  * **name** (*str*) – Display name for the token.
  * **expires\_at** (*Optional* \*\[\**str* *]*) – Optional expiry timestamp (ISO 8601 string).
  * **access\_restricted\_to** (*Optional* \*\[\**List* \*\[\**Dict* *]* *]*) – Optional list of permission entries restricting access
    (each dict with `username`, `namespace`, and optionally `dataset`).
* **Returns:**
  Created token dict (includes the `token` secret), or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### delete\_token(token\_id)

Delete an API token.

* **Parameters:**
  **token\_id** (*str*) – ID of the token to delete.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.
* **Return type:**
  `None`

#### list\_token\_permissions(token\_id)

List permissions assigned to a token.

* **Parameters:**
  **token\_id** (*str*) – ID of the token.
* **Returns:**
  Dict with `restricted` (bool) and `permissions` (list) keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### get\_usage\_history(on\_or\_after=None, before=None, page\_size=25, page\_cursor=None)

Retrieve historical usage data for the authenticated user.

* **Parameters:**
  * **on\_or\_after** (*Optional* \*\[\**str* *]*) – Return records on or after this ISO 8601 timestamp.
  * **before** (*Optional* \*\[\**str* *]*) – Return records before this ISO 8601 timestamp.
  * **page\_size** (*int*) – Number of records per page (default 25).
  * **page\_cursor** (*Optional* \*\[\**Dict* *]*) – Pagination cursor dict from a previous response.
* **Returns:**
  Dict with `data` and `meta` keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### get\_usage\_by\_day(on\_or\_after=None, before=None, timezone='UTC')

Retrieve usage data aggregated by day for the authenticated user.

* **Parameters:**
  * **on\_or\_after** (*Optional* \*\[\**str* *]*) – Return records on or after this ISO 8601 timestamp.
  * **before** (*Optional* \*\[\**str* *]*) – Return records before this ISO 8601 timestamp.
  * **timezone** (*str*) – Timezone for date aggregation (e.g. `"America/New_York"`). Defaults to UTC.
* **Returns:**
  Dict with `data` and `meta` keys, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### get\_agent\_run\_status(run\_id)

Get the current status of an agent run.

* **Parameters:**
  **run\_id** (*str*) – UUID of the agent run.
* **Returns:**
  Dict with `runId`, `agentKind`, `question`, `status`
  (`running`/`completed`/`failed`/`expired`), `canResume`,
  and optionally `lastNodeId`, `errorMessage`, `result`. None on
  failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### delete\_agent\_run(run\_id)

Permanently delete an agent run and its resume checkpoint.

* **Parameters:**
  **run\_id** (*str*) – UUID of the agent run.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails (e.g. 404 when
  the run does not exist or is not owned by the caller).
* **Return type:**
  `None`

#### resume\_agent\_run(run\_id)

Resume a previously paused or crashed agent run, streaming its events.

The first event is `run-started`, followed by the same domain events as
[`ask()`](#datalinks.api.datalinks.DataLinksAPI.ask) (e.g. `plan`, `step`, `answer`). Terminal run states
arrive as a single synthetic event instead of a stream:

> * `completed` / `expired` (HTTP 410) — yielded as an
>   `AskEvent(type="terminal", data=<body>)` whose data carries the
>   original question and, for completed runs, the rendered result.
> * `failed` (HTTP 422) — yielded as an `AskEvent` of type
>   `"terminal"`.
> * not-found / not-owned (HTTP 404) — raises `DataLinksRequestError`.

* **Parameters:**
  **run\_id** (*str*) – UUID of the agent run to resume.
* **Returns:**
  An iterator of [`AskEvent`](#datalinks.api.datalinks.AskEvent) objects.
* **Return type:**
  Iterator\[[AskEvent](#datalinks.api.datalinks.AskEvent)]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – On 404 or transport-level failure.

#### list\_conversations(username='self', namespace=None)

List the caller’s conversations within a namespace (most-recently-updated first).

* **Parameters:**
  * **username** (*str*) – Owner username. Defaults to `"self"`.
  * **namespace** (*Optional* \*\[\**str* *]*) – Namespace to list within. Defaults to the configured namespace.
* **Returns:**
  Dict with a `conversations` list, or None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

#### get\_conversation(conversation\_id)

Get a conversation and its turns (oldest first).

* **Parameters:**
  **conversation\_id** (*str*) – UUID of the conversation.
* **Returns:**
  Dict with `id`, `title`, and a `turns` list (each turn has
  `runId`, `question`, `status`, and optionally `result`), or
  None on failure.
* **Return type:**
  Optional\[Dict]
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.datalinks.DataLinksRequestError) – If the HTTP request fails.

## datalinks.api.ingest\_proxy module

### *class* datalinks.api.ingest\_proxy.IngestProxyConfig(host, datalinks\_token, datalinks\_username, namespace)

Bases: `object`

Configuration for the DataLinks ingestion proxy (auto-modelling) service.

* **Variables:**
  * **host** – Base URL of the ingestion proxy (e.g. `http://localhost:3003`).
  * **datalinks\_token** – DataLinks JWT token sent as `Authorization: Bearer` (`DL_API_KEY`).
  * **datalinks\_username** – DataLinks username included in the request body (`DL_USERNAME`).
  * **namespace** – Default target namespace (`DL_NAMESPACE`).

#### host *: str*

#### datalinks\_token *: str*

#### datalinks\_username *: str*

#### namespace *: str*

#### *classmethod* from\_env(load\_dotenv=True)

* **Return type:**
  [`IngestProxyConfig`](#datalinks.api.ingest_proxy.IngestProxyConfig)

### *class* datalinks.api.ingest\_proxy.PipelineRun(run\_id, stream\_fn)

Bases: `object`

Wraps a pipeline run with automatic stream reconnection.

Provides the workflow `run_id` (from the `x-workflow-run-id` response
header) and an iterable interface over the NDJSON progress events.

The iterator reconnects transparently on connection drops, resuming from
the last received event via the `startIndex` query parameter.  Iteration
ends only when an explicit `complete` or `error` event is received.

Usage:

```default theme={null}
run = proxy.run_pipeline(data=[...])
print(run.run_id)
for event in run:
    print(event)
```

Can also be used as a context manager:

```default theme={null}
with proxy.run_pipeline(data=[...]) as run:
    for event in run:
        process(event)
```

#### close()

* **Return type:**
  `None`

### *class* datalinks.api.ingest\_proxy.IngestProxyAPI(config=None)

Bases: `object`

Client for the DataLinks ingestion proxy (auto-modelling) service.

Wraps the `POST /api/pipeline`, `GET /api/pipeline/{runId}/stream`,
`GET /api/pipeline/{runId}/trace`, and `POST /api/pipeline/{runId}/hook`
endpoints.

* **Variables:**
  **config** – Proxy configuration.

#### config *: [IngestProxyConfig](#datalinks.api.ingest_proxy.IngestProxyConfig)*

#### run\_pipeline(, data=None, data\_url=None, data\_blob\_url=None, namespace=None, user\_prompt=None, model=True, ingest=True, ontology=True, max\_eval\_retries=3, max\_rows\_for\_modeling=20, max\_sample\_rows=10, enable\_human\_in\_the\_loop=False, predefined\_schema=None, explosion\_helper\_prompt=None, coalescence\_helper\_prompt=None, llm=None, datalinks\_inference\_settings=None)

Start a full pipeline run (auto-modelling + ingest).

Exactly one of *data*, *data\_url*, or *data\_blob\_url* must be provided.

Returns a [`PipelineRun`](#datalinks.api.ingest_proxy.PipelineRun) whose `run_id` attribute is the workflow
run identifier and which can be iterated to receive NDJSON progress events.

* **Parameters:**
  * **data** (`Optional`\[`List`\[`Dict`\[`str`, `Any`]]]) – Inline JSON array of row objects.
  * **data\_url** (`Optional`\[`str`]) – Remote URL returning a JSON array (fetched by the pipeline).
  * **data\_blob\_url** (`Optional`\[`str`]) – Pre-uploaded Vercel Blob URL.
  * **namespace** (`Optional`\[`str`]) – Target namespace; defaults to `config.namespace`.
  * **user\_prompt** (`Optional`\[`str`]) – Domain goals; inferred from data when omitted.
  * **model** (`bool`) – Run the model phase (default True).
  * **ingest** (`bool`) – Run the ingest phase (default True).
  * **ontology** (`bool`) – Run namespace curation after ingest (default True).
  * **max\_eval\_retries** (`int`) – Max modelling iterations (default 3).
  * **max\_rows\_for\_modeling** (`int`) – Rows sent to the LLM for schema modelling (default 20).
  * **max\_sample\_rows** (`int`) – Sample rows generated for preview (default 10).
  * **enable\_human\_in\_the\_loop** (`bool`) – Surface clarification + schema review hooks (default False).
  * **predefined\_schema** (`Optional`\[`Dict`\[`str`, `Any`]]) – Skip model phase when provided.
  * **explosion\_helper\_prompt** (`Optional`\[`str`]) – Extra context injected into the explode step.
  * **coalescence\_helper\_prompt** (`Optional`\[`str`]) – Extra context injected into the coalesce step.
  * **llm** (`Optional`\[`Dict`\[`str`, `Any`]]) – LLM configuration dict with optional keys: `provider`, `model`,
    `explosionTemperature`, `coalescenceTemperature`, `evaluationTemperature`,
    `ontologyTemperature`.
  * **datalinks\_inference\_settings** (`Optional`\[`Dict`\[`str`, `Any`]]) – DataLinks inference settings dict with optional keys:
    `provider`, `model`, `ontologyCurationProvider`, `ontologyCurationModel`.
* **Return type:**
  [`PipelineRun`](#datalinks.api.ingest_proxy.PipelineRun)
* **Returns:**
  A [`PipelineRun`](#datalinks.api.ingest_proxy.PipelineRun) instance.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### stream\_pipeline(run\_id, start\_index=0)

Stream progress events for an existing pipeline run.

* **Parameters:**
  * **run\_id** (`str`) – Workflow run identifier returned by [`run_pipeline()`](#datalinks.api.ingest_proxy.IngestProxyAPI.run_pipeline).
  * **start\_index** (`int`) – Resume from this event index (default 0).  Pass the
    number of events already received to skip replaying them on reconnect.
* **Return type:**
  `Iterator`\[`Dict`\[`str`, `Any`]]
* **Returns:**
  An iterator of NDJSON event dicts.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### get\_pipeline\_trace(run\_id)

Download the full trace for a completed pipeline run.

* **Parameters:**
  **run\_id** (`str`) – Workflow run identifier.
* **Return type:**
  `Optional`\[`Dict`\[`str`, `Any`]]
* **Returns:**
  Dict with LLM calls, token usage, and step durations, or None on failure.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.

#### resume\_pipeline\_hook(run\_id, payload)

Resume a human-in-the-loop hook (clarification, schema review, or token refresh).

* **Parameters:**
  * **run\_id** (`str`) – Workflow run identifier.
  * **payload** (`Dict`\[`str`, `Any`]) – Hook response payload.
* **Return type:**
  `Optional`\[`Dict`\[`str`, `Any`]]
* **Returns:**
  Response dict, or None on failure.
* **Raises:**
  [**DataLinksRequestError**](#datalinks.api.DataLinksRequestError) – If the HTTP request fails.