Skip to main content

​
datalinks.api package

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 | None) – Pipeline of inference steps to be applied for processing the data. If None the data will be ingested as is.
    • entity_resolution (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
  • Returns: An IngestionResult object containing lists of successfully ingested data blocks and data blocks that failed to be ingested.

​
create_space(is_private=None, data_description=None, schema_definition=None)

Creates a new space. This function sends a POST request to create a namespace. Information about the namespace creation will be logged, including the HTTP status code and response reason. A space that already exists is left alone and reported as success.

​
Versionchanged

Changed in version 1.2.13: is_private is ignored. Public datasets have been removed; every space is private and access is granted per user with share_dataset_access() / share_namespace_access().
  • Parameters:
    • is_private (Optional *[*bool ]) – Ignored; see the note above.
    • 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 – 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 – 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 – 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() 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 – 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().
    • key (str) – S3 object key from 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 ]) – Pipeline of inference steps to apply to the uploaded file during ingestion. If None the file is ingested as is.
    • entity_resolution (Optional [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 – If the HTTP request fails.

​
abort_multipart_upload(upload_id, key)

Abort a multipart upload and clean up partial data.

​
list_ingestions(page_size=25)

List ingestion attempts for the configured dataset, most recent first.
  • Parameters: page_size (int) – Number of records to return (1-100, default 25).
  • Return type: Optional[List[ListIngestionsResponseDataItem]]
  • Returns: Ingestion attempts, or None on failure.

​
wait_for_ingestion(ingestion_id, poll_interval=5, timeout=1200)

Poll until the given ingestion reaches a terminal status. Polls 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().
    • poll_interval (int) – Seconds between polls (default 5).
    • timeout (int) – Maximum seconds to wait before raising (default 600).
  • Return type: ListIngestionsResponseDataItem
  • Returns: The final ingestion record.
  • Raises:
    • TimeoutError – If timeout is exceeded before a terminal status.
    • DataLinksRequestError – If polling requests fail.

​
get_dataset_info()

Retrieve metadata for the configured dataset.
  • Return type: Optional[DatasetResponse]
  • Returns: The dataset and its metadata, or None on failure.

​
delete_dataset()

Permanently delete the configured dataset, including all data, links, and metadata. This action is irreversible (balefire).

​
rename_dataset(new_name)

Rename the configured dataset.
  • Parameters: new_name (str) – The new dataset name.
  • Raises: 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. 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 – If the HTTP request fails.
Preview what recalculating links would produce without saving changes.
  • Parameters:
    • data (Dataset) – Array of ontology data objects (e.g. from query_data()).
    • entity_resolution (Optional [MatchTypeConfig ]) – Optional link matching configuration.
  • Return type: Optional[List[ApiLink]]
  • Returns: The previewed links, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.
Recalculate links for the configured dataset based on current data.
  • Parameters:
    • data (Dataset) – Array of ontology data objects (e.g. from query_data()).
    • entity_resolution (Optional [MatchTypeConfig ]) – Optional link matching configuration.
  • Return type: Optional[List[ApiLink]]
  • Returns: The rebuilt links, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.
Retrieve active and suggested links for the configured dataset.
  • Return type: Optional[List[ApiLink]]
  • Returns: The links, or None on failure.

​
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.
  • Return type: Optional[List[ApiDatasetDescription]]
  • Returns: The datasets, or None on failure.

​
query_data(query=None, is_natural_language=False, model=None, provider=None, include_metadata=False, explain=False, , username=‘self’)

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.
    • username (str) – Owner of the namespace being queried.
  • 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 – If a transport-level error occurs.

​
ask(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=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.
    • stage_models (Optional *[*Dict *[*str , Dict *[*str , str ] ] ]) – Per-stage model overrides, keyed by stage (plan, query, answer), each mapping to a dict with optional model and provider. An override wins over the run-wide model/provider as a whole: a stage that sets only model does not inherit the run-wide provider but falls back to the deployment default, so set both fields or neither.
    • conversation_id (Optional *[*str ]) – Existing conversation to continue. Omit to start a new one; its id arrives on the run-started event.
    • web_search (Optional *[*bool ]) – Pass False to disable web search. True is equivalent to omitting it — there is no way to force-enable a deployment that has web search switched off.
    • username (str) – Owner of the namespace being queried.
  • Returns: An iterator of AskEvent objects, also exposing the streaming response once it is open.
  • Return type: AskStream
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
Versionchanged

Changed in version 1.2.15: Returns AskStream rather than a bare iterator.

​
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 ]) – Optional pipeline of inference steps to apply.
  • Return type: Optional[List[Dict[str, Any]]]
  • Returns: The processed preview records, or None on failure.
  • Raises: 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).
  • Return type: Optional[InferredSchemaResponse]
  • Returns: The inferred schema, mapping field names to their types, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
retry_ingestion(ingestion_id)

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

​
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 – If the HTTP request fails.
  • Return type: None

​
autorag(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=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() 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.
    • stage_models (Optional *[*Dict *[*str , Dict *[*str , str ] ] ]) – Per-stage model overrides, keyed by stage (plan, query, answer), each mapping to a dict with optional model and provider. An override wins over the run-wide model/provider as a whole: a stage that sets only model does not inherit the run-wide provider but falls back to the deployment default, so set both fields or neither.
    • conversation_id (Optional *[*str ]) – Existing conversation to continue. Omit to start a new one.
    • web_search (Optional *[*bool ]) – Pass False to disable web search. True is equivalent to omitting it — there is no way to force-enable a deployment that has web search switched off.
    • username (str) – Owner of the namespace being queried.
  • Returns: Dict with response (str) and steps (list) keys, also carrying the response headers.
  • Return type: AutoRagResult
  • Raises: DataLinksRequestError – If the request fails, the server answers non-2xx, or the body is not a JSON object.

​
Versionchanged

Changed in version 1.2.15: Raises on failure instead of returning None, and returns AutoRagResult rather than a plain dict.

​
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 – 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 – If the HTTP request fails.

​
get_ontology()

Load the ontology (active links) for the configured dataset.
  • Return type: Optional[List[ApiLink]]
  • Returns: The active links, or None if no ontology exists or the request fails.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
save_ontology(add=None, remove=None)

Save (update) the ontology for the configured dataset.
  • Parameters:
    • add (Optional[Sequence[Union[ApiLink, Mapping[str, Any]]]]) – Links to add, as returned by get_ontology() or as dicts.
    • remove (Optional[Sequence[Union[ApiLink, Mapping[str, Any]]]]) – Links to remove, in the same form as add.
  • Raises: DataLinksRequestError – If the HTTP request fails.
  • Return type: None
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.
  • Return type: Optional[CurateLinkResponse]
  • Returns: The curation outcome — datasets_processed, total_selected, and curated_links when activate is False; or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
rename_namespace(new_name)

Rename the configured namespace.
  • Parameters: new_name (str) – The new namespace name.
  • Raises: 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.
  • Return type: Optional[List[ApiNamespace]]
  • Returns: The namespaces, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
list_all_datasets_schema()

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

​
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.
  • Return type: Optional[List[ApiDatasetDescription]]
  • Returns: The datasets, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
get_current_user()

Resolve the identity of the user owning the configured API key.
  • Return type: Optional[CurrentUserResponse]
  • Returns: The user’s id and username, plus nullable name and email; or None on failure.

​
list_tokens()

List all API tokens for the authenticated user.
  • Return type: Optional[List[UserToken]]
  • Returns: The tokens, or None on failure — including the 403 a restricted token gets, since it may not manage API tokens.

​
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[Sequence[Union[TokenPermissionEntry, Mapping[str, Any]]]]) – Permission entries restricting access, as returned by list_token_permissions() or as dicts with username, namespace and optionally dataset.
  • Return type: Optional[UserToken]
  • Returns: The created token, including the token secret, or None on failure.
  • Raises: 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 – If the HTTP request fails.
  • Return type: None

​
list_token_permissions(token_id)

List permissions assigned to a token.

​
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 (Union[UserUsageHistoryCursor, Mapping[str, Any], None]) – meta.page_cursor from a previous response.
  • Return type: Optional[UserUsageHistoryResponse]
  • Returns: The usage history page, or None on failure.
  • Raises: 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.
  • Return type: Optional[UserUsageByDayResponse]
  • Returns: The daily usage, in .data and .meta; or None on failure.
  • Raises: 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.
  • Return type: Optional[AgentRunStatusResponse]
  • Returns: The run’s run_id, agent_kind, question, status (running/completed/failed/expired), can_resume, and optionally last_node_id, error_message, result; or None on failure.
  • Raises: 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 – If the HTTP request fails (e.g. 404 when the run does not exist or is not owned by the caller).
  • Return type: None

​
submit_agent_run_feedback(run_id, , thumbs_up, comment=None)

Rate the answer a completed agent run produced. Resubmitting replaces the previous rating for the same run.
  • Parameters:
    • run_id (str) – UUID of the agent run.
    • thumbs_up (bool) – True for a thumbs up, False for a thumbs down.
    • comment (Optional *[*str ]) – Optional free-text comment accompanying the rating.
  • Raises: DataLinksRequestError – If the HTTP request fails (e.g. 404 when the run does not exist or is not owned by the caller, 422 when it has not completed).
  • 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() (e.g. plan, step, answer). Runs that cannot be streamed arrive as a single synthetic event instead:
  • 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".
  • no checkpoint to resume from (HTTP 409) — yielded as an AskEvent(type="no-checkpoint", data=<body>). The run is untouched and still in progress; poll get_agent_run_status() for its eventual outcome.
  • not-found / not-owned (HTTP 404) — raises DataLinksRequestError.
  • Parameters: run_id (str) – UUID of the agent run to resume.
  • Returns: An iterator of AskEvent objects.
  • Return type: Iterator[AskEvent]
  • Raises: DataLinksRequestError – On 404 or transport-level failure.

​
share_dataset_access(username, role)

Grant another user access to the configured dataset. Since public datasets were removed, this is how you give someone else access. Re-sharing with a different role replaces the existing grant.
  • Parameters:
    • username (str) – User to grant access to.
    • role (str) – "viewer" (read-only) or "editor" (read and write).
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails (e.g. 403 when the caller does not own the dataset).
  • Return type: None

​
revoke_dataset_access(username, role)

Remove a user’s access to the configured dataset.
  • Parameters:
    • username (str) – User whose access is being removed.
    • role (str) – The granted access level to remove.
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails.
  • Return type: None

​
list_dataset_shares()

List the per-user grants on the configured dataset.
  • Return type: Optional[List[AccessGrant]]
  • Returns: The grants, each with username and role; or None on failure.

​
share_namespace_access(username, role)

Grant another user access to the configured namespace. The grant cascades to every dataset in the namespace.
  • Parameters:
    • username (str) – User to grant access to.
    • role (str) – "viewer" (read-only) or "editor" (read and write).
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails.
  • Return type: None

​
revoke_namespace_access(username, role)

Remove a user’s access to the configured namespace.
  • Parameters:
    • username (str) – User whose access is being removed.
    • role (str) – The granted access level to remove.
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails.
  • Return type: None

​
list_namespace_shares()

List the per-user grants on the configured namespace.
  • Return type: Optional[List[AccessGrant]]
  • Returns: The grants, each with username and role; or None on 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.
  • Return type: Optional[ConversationListResponse]
  • Returns: The summaries, in .conversations; or None on failure.
  • Raises: 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.
  • Return type: Optional[ConversationDetailResponse]
  • Returns: The conversation’s id, title and turns (each turn has run_id, question, status, and optionally result); or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.
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 AsyncAskStream instead of an AskStream. Use async with for guaranteed cleanup of the underlying httpx.AsyncClient, or call aclose() manually:

​
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.

​
create_space(is_private=None, data_description=None, schema_definition=None)

Create a new space (see DataLinksAPI.create_space()). Deliberately not an async def: the body of a coroutine runs on whoever resumes it, so under asyncio.gather the deprecation warning below would be filed against asyncio/events.py instead of the caller. Warning here, at call time, keeps the attribution right.
  • Return type: Coroutine[Any, Any, 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)

​
async wait_for_ingestion(ingestion_id, poll_interval=5, timeout=1200)

Async variant of DataLinksAPI.wait_for_ingestion(). Polls via list_ingestions(), awaiting asyncio.sleep between ticks instead of blocking the event loop with time.sleep.

​
async get_dataset_info()

​
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
  • Return type: Optional[bool]
  • Return type: Optional[List[ApiLink]]
  • Return type: Optional[List[ApiLink]]
  • Return type: Optional[List[ApiLink]]

​
async list_datasets(namespace=None)

​
async list_namespaces(user=‘self’)

​
async list_all_datasets_schema()

​
async list_datasets_in_namespace_schema(namespace=None, user=‘self’)

​
async query_data(query=None, is_natural_language=False, model=None, provider=None, include_metadata=False, explain=False, , username=‘self’)

Query the configured dataset (see DataLinksAPI.query_data()).
  • Return type: Optional[List[Dict[str, Any]]]

​
async autorag(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=None)

Answer a question with the AutoRAG agent (see DataLinksAPI.autorag()).

​
ask(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=None)

Async SSE stream of DataLinksAPI.ask() events. Yields AskEvent objects until the server closes the stream, and exposes the response headers once the stream is open (see AsyncAskStream).

​
async preview_ingest(data, inference_steps=None)

  • Return type: Optional[List[Dict[str, Any]]]

​
async infer_schema(sample, model=None, provider=None, current_schema=None)

​
async retry_ingestion(ingestion_id)

​
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[ApiLink]]

​
async save_ontology(add=None, remove=None)

  • Return type: None

​
async get_current_user()

Resolve the current user’s identity (see DataLinksAPI.get_current_user()).

​
async list_tokens()

​
async add_token(name, expires_at=None, access_restricted_to=None)

​
async delete_token(token_id)

  • Return type: None

​
async list_token_permissions(token_id)

​
async get_usage_history(on_or_after=None, before=None, page_size=25, page_cursor=None)

​
async get_usage_by_day(on_or_after=None, before=None, timezone=‘UTC’)

​
async get_agent_run_status(run_id)

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

​
async delete_agent_run(run_id)

Permanently delete an agent run and its resume checkpoint (see DataLinksAPI.delete_agent_run()).
  • Return type: None

​
async submit_agent_run_feedback(run_id, , thumbs_up, comment=None)

Rate a completed agent run (see DataLinksAPI.submit_agent_run_feedback()).
  • Return type: None

​
async resume_agent_run(run_id)

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

​
async share_dataset_access(username, role)

Grant a user access to the dataset (see DataLinksAPI.share_dataset_access()).
  • Return type: None

​
async revoke_dataset_access(username, role)

Remove a user’s dataset access (see DataLinksAPI.revoke_dataset_access()).
  • Return type: None

​
async list_dataset_shares()

List grants on the dataset (see DataLinksAPI.list_dataset_shares()).

​
async share_namespace_access(username, role)

Grant a user access to the namespace (see DataLinksAPI.share_namespace_access()).
  • Return type: None

​
async revoke_namespace_access(username, role)

Remove a user’s namespace access (see DataLinksAPI.revoke_namespace_access()).
  • Return type: None

​
async list_namespace_shares()

List grants on the namespace (see DataLinksAPI.list_namespace_shares()).

​
async list_conversations(username=‘self’, namespace=None)

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

​
async get_conversation(conversation_id)

Get a conversation and its turns (see DataLinksAPI.get_conversation()). Bases: Exception 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)

Bases: object Represents a single SSE event from the /query/ask streaming endpoint. Server-sent types are plan, step, answer, error, the lifecycle signals planningStarted, stepStarted, queryExecuting and answerStarted, and — when resuming — run-started. Two further types are synthesised by the SDK when the server answers a resume with a one-off body instead of a stream: terminal and no-checkpoint (see DataLinksAPI.resume_agent_run()). Both vocabularies share this one field, so match on the types you expect rather than assuming the list is closed — the server may add lifecycle events without an SDK release.
  • Variables:
    • type – Event type.
    • data – Parsed JSON payload for the event.

​
type : str

​
data : Dict[str, Any]

Bases: object The DataLinksAPI.ask() event stream, plus the response carrying it. Iterate it exactly as before to get AskEvent objects. headers and status_code are None until the first event arrives — nothing is sent until iteration starts, so there is no response to read them off before then. Only the headers and status are exposed, not the response itself: its body is consumed by the event loop, so reading .text off it would raise. Close it when abandoning a stream early, or use it as a context manager:

​
close()

Release the connection, whether or not the stream was exhausted.
  • Return type: None

​
property headers : Headers | None

Response headers once the stream is open, else None.

​
property status_code : int | None

HTTP status once the stream is open, else None. Bases: object Async counterpart of AskStream. Iterated with async for; released with aclose() or async with.

​
async aclose()

Release the connection, whether or not the stream was exhausted.
  • Return type: None

​
property headers : Headers | None

Response headers once the stream is open, else None.

​
property status_code : int | None

HTTP status once the stream is open, else None. Bases: Dict[str, Any] The AutoRAG answer body, plus the response it arrived in. A dict subclass rather than a wrapper, so result["response"] and result["steps"] keep working unchanged. The attribute is http_response, not response, because result["response"] is already the answer text.
  • Variables: http_response – The raw httpx.Response, already fully read.

​
property headers : Headers

Response headers.

​
property status_code : int

HTTP status of the response — always 2xx, since anything else raised. 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]]

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 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
  • Returns: A PipelineRun instance.
  • Raises: 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().
    • 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 – 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 – 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 – If the HTTP request fails.
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)

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:
Can also be used as a context manager:

​
close()

  • Return type: None

​
Submodules

Async sibling of 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 one DataLinksClient and the same request bodies, 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. Bases: object Async counterpart of AskStream. Iterated with async for; released with aclose() or async with.

​
async aclose()

Release the connection, whether or not the stream was exhausted.
  • Return type: None

​
property headers : Headers | None

Response headers once the stream is open, else None.

​
property status_code : int | None

HTTP status once the stream is open, else 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 AsyncAskStream instead of an AskStream. Use async with for guaranteed cleanup of the underlying httpx.AsyncClient, or call aclose() manually:

​
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.

​
create_space(is_private=None, data_description=None, schema_definition=None)

Create a new space (see DataLinksAPI.create_space()). Deliberately not an async def: the body of a coroutine runs on whoever resumes it, so under asyncio.gather the deprecation warning below would be filed against asyncio/events.py instead of the caller. Warning here, at call time, keeps the attribution right.
  • Return type: Coroutine[Any, Any, 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)

​
async wait_for_ingestion(ingestion_id, poll_interval=5, timeout=1200)

Async variant of DataLinksAPI.wait_for_ingestion(). Polls via list_ingestions(), awaiting asyncio.sleep between ticks instead of blocking the event loop with time.sleep.

​
async get_dataset_info()

​
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
  • Return type: Optional[bool]
  • Return type: Optional[List[ApiLink]]
  • Return type: Optional[List[ApiLink]]
  • Return type: Optional[List[ApiLink]]

​
async list_datasets(namespace=None)

​
async list_namespaces(user=‘self’)

​
async list_all_datasets_schema()

​
async list_datasets_in_namespace_schema(namespace=None, user=‘self’)

​
async query_data(query=None, is_natural_language=False, model=None, provider=None, include_metadata=False, explain=False, , username=‘self’)

Query the configured dataset (see DataLinksAPI.query_data()).
  • Return type: Optional[List[Dict[str, Any]]]

​
async autorag(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=None)

Answer a question with the AutoRAG agent (see DataLinksAPI.autorag()).

​
ask(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=None)

Async SSE stream of DataLinksAPI.ask() events. Yields AskEvent objects until the server closes the stream, and exposes the response headers once the stream is open (see AsyncAskStream).

​
async preview_ingest(data, inference_steps=None)

  • Return type: Optional[List[Dict[str, Any]]]

​
async infer_schema(sample, model=None, provider=None, current_schema=None)

​
async retry_ingestion(ingestion_id)

​
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[ApiLink]]

​
async save_ontology(add=None, remove=None)

  • Return type: None

​
async get_current_user()

Resolve the current user’s identity (see DataLinksAPI.get_current_user()).

​
async list_tokens()

​
async add_token(name, expires_at=None, access_restricted_to=None)

​
async delete_token(token_id)

  • Return type: None

​
async list_token_permissions(token_id)

​
async get_usage_history(on_or_after=None, before=None, page_size=25, page_cursor=None)

​
async get_usage_by_day(on_or_after=None, before=None, timezone=‘UTC’)

​
async get_agent_run_status(run_id)

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

​
async delete_agent_run(run_id)

Permanently delete an agent run and its resume checkpoint (see DataLinksAPI.delete_agent_run()).
  • Return type: None

​
async submit_agent_run_feedback(run_id, , thumbs_up, comment=None)

Rate a completed agent run (see DataLinksAPI.submit_agent_run_feedback()).
  • Return type: None

​
async resume_agent_run(run_id)

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

​
async share_dataset_access(username, role)

Grant a user access to the dataset (see DataLinksAPI.share_dataset_access()).
  • Return type: None

​
async revoke_dataset_access(username, role)

Remove a user’s dataset access (see DataLinksAPI.revoke_dataset_access()).
  • Return type: None

​
async list_dataset_shares()

List grants on the dataset (see DataLinksAPI.list_dataset_shares()).

​
async share_namespace_access(username, role)

Grant a user access to the namespace (see DataLinksAPI.share_namespace_access()).
  • Return type: None

​
async revoke_namespace_access(username, role)

Remove a user’s namespace access (see DataLinksAPI.revoke_namespace_access()).
  • Return type: None

​
async list_namespace_shares()

List grants on the namespace (see DataLinksAPI.list_namespace_shares()).

​
async list_conversations(username=‘self’, namespace=None)

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

​
async get_conversation(conversation_id)

Get a conversation and its turns (see DataLinksAPI.get_conversation()). 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)

Bases: object Represents a single SSE event from the /query/ask streaming endpoint. Server-sent types are plan, step, answer, error, the lifecycle signals planningStarted, stepStarted, queryExecuting and answerStarted, and — when resuming — run-started. Two further types are synthesised by the SDK when the server answers a resume with a one-off body instead of a stream: terminal and no-checkpoint (see DataLinksAPI.resume_agent_run()). Both vocabularies share this one field, so match on the types you expect rather than assuming the list is closed — the server may add lifecycle events without an SDK release.
  • Variables:
    • type – Event type.
    • data – Parsed JSON payload for the event.

​
type : str

​
data : Dict[str, Any]

Bases: object The DataLinksAPI.ask() event stream, plus the response carrying it. Iterate it exactly as before to get AskEvent objects. headers and status_code are None until the first event arrives — nothing is sent until iteration starts, so there is no response to read them off before then. Only the headers and status are exposed, not the response itself: its body is consumed by the event loop, so reading .text off it would raise. Close it when abandoning a stream early, or use it as a context manager:

​
close()

Release the connection, whether or not the stream was exhausted.
  • Return type: None

​
property headers : Headers | None

Response headers once the stream is open, else None.

​
property status_code : int | None

HTTP status once the stream is open, else None. Bases: Dict[str, Any] The AutoRAG answer body, plus the response it arrived in. A dict subclass rather than a wrapper, so result["response"] and result["steps"] keep working unchanged. The attribute is http_response, not response, because result["response"] is already the answer text.
  • Variables: http_response – The raw httpx.Response, already fully read.

​
property headers : Headers

Response headers.

​
property status_code : int

HTTP status of the response — always 2xx, since anything else raised. 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]]

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

​
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 | None) – Pipeline of inference steps to be applied for processing the data. If None the data will be ingested as is.
    • entity_resolution (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
  • Returns: An IngestionResult object containing lists of successfully ingested data blocks and data blocks that failed to be ingested.

​
create_space(is_private=None, data_description=None, schema_definition=None)

Creates a new space. This function sends a POST request to create a namespace. Information about the namespace creation will be logged, including the HTTP status code and response reason. A space that already exists is left alone and reported as success.

​
Versionchanged

Changed in version 1.2.13: is_private is ignored. Public datasets have been removed; every space is private and access is granted per user with share_dataset_access() / share_namespace_access().
  • Parameters:
    • is_private (Optional *[*bool ]) – Ignored; see the note above.
    • 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 – 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 – 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 – 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() 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 – 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().
    • key (str) – S3 object key from 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 ]) – Pipeline of inference steps to apply to the uploaded file during ingestion. If None the file is ingested as is.
    • entity_resolution (Optional [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 – If the HTTP request fails.

​
abort_multipart_upload(upload_id, key)

Abort a multipart upload and clean up partial data.

​
list_ingestions(page_size=25)

List ingestion attempts for the configured dataset, most recent first.
  • Parameters: page_size (int) – Number of records to return (1-100, default 25).
  • Return type: Optional[List[ListIngestionsResponseDataItem]]
  • Returns: Ingestion attempts, or None on failure.

​
wait_for_ingestion(ingestion_id, poll_interval=5, timeout=1200)

Poll until the given ingestion reaches a terminal status. Polls 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().
    • poll_interval (int) – Seconds between polls (default 5).
    • timeout (int) – Maximum seconds to wait before raising (default 600).
  • Return type: ListIngestionsResponseDataItem
  • Returns: The final ingestion record.
  • Raises:
    • TimeoutError – If timeout is exceeded before a terminal status.
    • DataLinksRequestError – If polling requests fail.

​
get_dataset_info()

Retrieve metadata for the configured dataset.
  • Return type: Optional[DatasetResponse]
  • Returns: The dataset and its metadata, or None on failure.

​
delete_dataset()

Permanently delete the configured dataset, including all data, links, and metadata. This action is irreversible (balefire).

​
rename_dataset(new_name)

Rename the configured dataset.
  • Parameters: new_name (str) – The new dataset name.
  • Raises: 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. 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 – If the HTTP request fails.
Preview what recalculating links would produce without saving changes.
  • Parameters:
    • data (Dataset) – Array of ontology data objects (e.g. from query_data()).
    • entity_resolution (Optional [MatchTypeConfig ]) – Optional link matching configuration.
  • Return type: Optional[List[ApiLink]]
  • Returns: The previewed links, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.
Recalculate links for the configured dataset based on current data.
  • Parameters:
    • data (Dataset) – Array of ontology data objects (e.g. from query_data()).
    • entity_resolution (Optional [MatchTypeConfig ]) – Optional link matching configuration.
  • Return type: Optional[List[ApiLink]]
  • Returns: The rebuilt links, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.
Retrieve active and suggested links for the configured dataset.
  • Return type: Optional[List[ApiLink]]
  • Returns: The links, or None on failure.

​
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.
  • Return type: Optional[List[ApiDatasetDescription]]
  • Returns: The datasets, or None on failure.

​
query_data(query=None, is_natural_language=False, model=None, provider=None, include_metadata=False, explain=False, , username=‘self’)

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.
    • username (str) – Owner of the namespace being queried.
  • 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 – If a transport-level error occurs.

​
ask(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=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.
    • stage_models (Optional *[*Dict *[*str , Dict *[*str , str ] ] ]) – Per-stage model overrides, keyed by stage (plan, query, answer), each mapping to a dict with optional model and provider. An override wins over the run-wide model/provider as a whole: a stage that sets only model does not inherit the run-wide provider but falls back to the deployment default, so set both fields or neither.
    • conversation_id (Optional *[*str ]) – Existing conversation to continue. Omit to start a new one; its id arrives on the run-started event.
    • web_search (Optional *[*bool ]) – Pass False to disable web search. True is equivalent to omitting it — there is no way to force-enable a deployment that has web search switched off.
    • username (str) – Owner of the namespace being queried.
  • Returns: An iterator of AskEvent objects, also exposing the streaming response once it is open.
  • Return type: AskStream
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
Versionchanged

Changed in version 1.2.15: Returns AskStream rather than a bare iterator.

​
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 ]) – Optional pipeline of inference steps to apply.
  • Return type: Optional[List[Dict[str, Any]]]
  • Returns: The processed preview records, or None on failure.
  • Raises: 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).
  • Return type: Optional[InferredSchemaResponse]
  • Returns: The inferred schema, mapping field names to their types, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
retry_ingestion(ingestion_id)

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

​
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 – If the HTTP request fails.
  • Return type: None

​
autorag(query, model=None, provider=None, helper_prompt=None, , username=‘self’, stage_models=None, conversation_id=None, web_search=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() 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.
    • stage_models (Optional *[*Dict *[*str , Dict *[*str , str ] ] ]) – Per-stage model overrides, keyed by stage (plan, query, answer), each mapping to a dict with optional model and provider. An override wins over the run-wide model/provider as a whole: a stage that sets only model does not inherit the run-wide provider but falls back to the deployment default, so set both fields or neither.
    • conversation_id (Optional *[*str ]) – Existing conversation to continue. Omit to start a new one.
    • web_search (Optional *[*bool ]) – Pass False to disable web search. True is equivalent to omitting it — there is no way to force-enable a deployment that has web search switched off.
    • username (str) – Owner of the namespace being queried.
  • Returns: Dict with response (str) and steps (list) keys, also carrying the response headers.
  • Return type: AutoRagResult
  • Raises: DataLinksRequestError – If the request fails, the server answers non-2xx, or the body is not a JSON object.

​
Versionchanged

Changed in version 1.2.15: Raises on failure instead of returning None, and returns AutoRagResult rather than a plain dict.

​
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 – 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 – If the HTTP request fails.

​
get_ontology()

Load the ontology (active links) for the configured dataset.
  • Return type: Optional[List[ApiLink]]
  • Returns: The active links, or None if no ontology exists or the request fails.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
save_ontology(add=None, remove=None)

Save (update) the ontology for the configured dataset.
  • Parameters:
    • add (Optional[Sequence[Union[ApiLink, Mapping[str, Any]]]]) – Links to add, as returned by get_ontology() or as dicts.
    • remove (Optional[Sequence[Union[ApiLink, Mapping[str, Any]]]]) – Links to remove, in the same form as add.
  • Raises: DataLinksRequestError – If the HTTP request fails.
  • Return type: None
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.
  • Return type: Optional[CurateLinkResponse]
  • Returns: The curation outcome — datasets_processed, total_selected, and curated_links when activate is False; or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
rename_namespace(new_name)

Rename the configured namespace.
  • Parameters: new_name (str) – The new namespace name.
  • Raises: 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.
  • Return type: Optional[List[ApiNamespace]]
  • Returns: The namespaces, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
list_all_datasets_schema()

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

​
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.
  • Return type: Optional[List[ApiDatasetDescription]]
  • Returns: The datasets, or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.

​
get_current_user()

Resolve the identity of the user owning the configured API key.
  • Return type: Optional[CurrentUserResponse]
  • Returns: The user’s id and username, plus nullable name and email; or None on failure.

​
list_tokens()

List all API tokens for the authenticated user.
  • Return type: Optional[List[UserToken]]
  • Returns: The tokens, or None on failure — including the 403 a restricted token gets, since it may not manage API tokens.

​
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[Sequence[Union[TokenPermissionEntry, Mapping[str, Any]]]]) – Permission entries restricting access, as returned by list_token_permissions() or as dicts with username, namespace and optionally dataset.
  • Return type: Optional[UserToken]
  • Returns: The created token, including the token secret, or None on failure.
  • Raises: 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 – If the HTTP request fails.
  • Return type: None

​
list_token_permissions(token_id)

List permissions assigned to a token.

​
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 (Union[UserUsageHistoryCursor, Mapping[str, Any], None]) – meta.page_cursor from a previous response.
  • Return type: Optional[UserUsageHistoryResponse]
  • Returns: The usage history page, or None on failure.
  • Raises: 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.
  • Return type: Optional[UserUsageByDayResponse]
  • Returns: The daily usage, in .data and .meta; or None on failure.
  • Raises: 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.
  • Return type: Optional[AgentRunStatusResponse]
  • Returns: The run’s run_id, agent_kind, question, status (running/completed/failed/expired), can_resume, and optionally last_node_id, error_message, result; or None on failure.
  • Raises: 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 – If the HTTP request fails (e.g. 404 when the run does not exist or is not owned by the caller).
  • Return type: None

​
submit_agent_run_feedback(run_id, , thumbs_up, comment=None)

Rate the answer a completed agent run produced. Resubmitting replaces the previous rating for the same run.
  • Parameters:
    • run_id (str) – UUID of the agent run.
    • thumbs_up (bool) – True for a thumbs up, False for a thumbs down.
    • comment (Optional *[*str ]) – Optional free-text comment accompanying the rating.
  • Raises: DataLinksRequestError – If the HTTP request fails (e.g. 404 when the run does not exist or is not owned by the caller, 422 when it has not completed).
  • 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() (e.g. plan, step, answer). Runs that cannot be streamed arrive as a single synthetic event instead:
  • 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".
  • no checkpoint to resume from (HTTP 409) — yielded as an AskEvent(type="no-checkpoint", data=<body>). The run is untouched and still in progress; poll get_agent_run_status() for its eventual outcome.
  • not-found / not-owned (HTTP 404) — raises DataLinksRequestError.
  • Parameters: run_id (str) – UUID of the agent run to resume.
  • Returns: An iterator of AskEvent objects.
  • Return type: Iterator[AskEvent]
  • Raises: DataLinksRequestError – On 404 or transport-level failure.

​
share_dataset_access(username, role)

Grant another user access to the configured dataset. Since public datasets were removed, this is how you give someone else access. Re-sharing with a different role replaces the existing grant.
  • Parameters:
    • username (str) – User to grant access to.
    • role (str) – "viewer" (read-only) or "editor" (read and write).
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails (e.g. 403 when the caller does not own the dataset).
  • Return type: None

​
revoke_dataset_access(username, role)

Remove a user’s access to the configured dataset.
  • Parameters:
    • username (str) – User whose access is being removed.
    • role (str) – The granted access level to remove.
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails.
  • Return type: None

​
list_dataset_shares()

List the per-user grants on the configured dataset.
  • Return type: Optional[List[AccessGrant]]
  • Returns: The grants, each with username and role; or None on failure.

​
share_namespace_access(username, role)

Grant another user access to the configured namespace. The grant cascades to every dataset in the namespace.
  • Parameters:
    • username (str) – User to grant access to.
    • role (str) – "viewer" (read-only) or "editor" (read and write).
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails.
  • Return type: None

​
revoke_namespace_access(username, role)

Remove a user’s access to the configured namespace.
  • Parameters:
    • username (str) – User whose access is being removed.
    • role (str) – The granted access level to remove.
  • Raises:
    • ValueError – If role is not a valid access level.
    • DataLinksRequestError – If the HTTP request fails.
  • Return type: None

​
list_namespace_shares()

List the per-user grants on the configured namespace.
  • Return type: Optional[List[AccessGrant]]
  • Returns: The grants, each with username and role; or None on 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.
  • Return type: Optional[ConversationListResponse]
  • Returns: The summaries, in .conversations; or None on failure.
  • Raises: 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.
  • Return type: Optional[ConversationDetailResponse]
  • Returns: The conversation’s id, title and turns (each turn has run_id, question, status, and optionally result); or None on failure.
  • Raises: DataLinksRequestError – If the HTTP request fails.
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)

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:
Can also be used as a context manager:

​
close()

  • Return type: 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

​
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 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
  • Returns: A PipelineRun instance.
  • Raises: 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().
    • 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 – 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 – 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 – If the HTTP request fails.