ds_fetch_py_sdk.client
======================

.. py:module:: ds_fetch_py_sdk.client

.. autoapi-nested-parse::

   The Fetch client.







Module Contents
---------------

.. py:data:: MAX_LIMIT
   :value: 500


   The largest dataset page the API serves; it lowers anything above this.

.. py:class:: Fetch(env: str | ds_fetch_py_sdk.env.Environment | None = None, *, token: str | None = None, auth: httpx.Auth | None = None, language: str = 'en', timeout: float = 30.0, retries: int = 3, sql_tool: str = 'text_to_sql', transport: httpx.BaseTransport | None = None)

   Client for AI Commons Fetch: read-only SQL over your tenant data lake.

   Without `token` or `auth`, credentials come from `$AIC_TOKEN`; then `$AIC_CLIENT_ID` and
   `$AIC_CLIENT_SECRET`; then `$AIC_EMAIL` and `$AIC_PASSWORD`; then the cached session;
   then browser sign-in.

       with Fetch("dev") as fetch:
           result = fetch.query('SELECT count(*) FROM gold."<dataset-id>"')


   .. py:method:: query(sql: str, *, fresh: bool = False) -> ds_fetch_py_sdk.models.QueryResult

      Run one SELECT. `fresh` reads S3 as it is now, bypassing the index and cache.



   .. py:method:: validate(sql: str, *, fresh: bool = False) -> ds_fetch_py_sdk.models.Validation

      Check one SELECT as `query` would, without reading data. Invalid SQL raises `QueryError`.



   .. py:method:: sql(question: str, *, datasets: collections.abc.Sequence[str] = ()) -> str

      Translate a natural-language question to SQL with ds-tools.



   .. py:method:: ask(question: str, *, datasets: collections.abc.Sequence[str] = (), fresh: bool = False) -> ds_fetch_py_sdk.models.QueryResult

      Answer a natural-language question: translate it to SQL, then run it.



   .. py:method:: datasets(*, names: collections.abc.Sequence[str] = (), layers: collections.abc.Sequence[Layer] = (), limit: int = 100, fresh: bool = False) -> collections.abc.Iterator[ds_fetch_py_sdk.models.Dataset]

      Every dataset and pipeline run you are granted, across pages; only `names` and `layers` if given.

      Names that do not exist or are not granted are left out. `limit` is the page size, held to
      1…`MAX_LIMIT`; the server describes every dataset on a page within its timeout, so large pages risk a 504.



   .. py:method:: dataset(name: str, *, fresh: bool = False) -> ds_fetch_py_sdk.models.Dataset

      One dataset by name, e.g. `gold.<dataset-id>` or `silver.<pipeline-id>/<job-id>`.



.. py:class:: Tools(client: Fetch)

   ds-tools catalogue and invocation, under the same sign-in as Fetch.


   .. py:method:: invoke(tool_id: str, input: dict[str, Any], *, timeout_ms: int = 0) -> ds_fetch_py_sdk.models.ToolResult

      Run a tool. Retries reuse the same `tool_use_id`, so they are idempotent.