ds_fetch_py_sdk

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

Submodules

• ds_fetch_py_sdk.auth
• ds_fetch_py_sdk.client
• ds_fetch_py_sdk.env
• ds_fetch_py_sdk.errors
• ds_fetch_py_sdk.models

Package Contents

class ds_fetch_py_sdk.BearerToken(token: str)

Bases: httpx.Auth

A platform JWT you already have.

auth_flow(request: httpx.Request) → collections.abc.Generator[httpx.Request, httpx.Response, None]

Execute the authentication flow.

To dispatch a request, yield it:

` yield request `

The client will .send() the response back into the flow generator. You can access it like so:

` response = yield request `

A return (or reaching the end of the generator) will result in the client returning the last response obtained from the server.

You can dispatch as many requests as is necessary.

class ds_fetch_py_sdk.BrowserLogin(*, client_id: str | None = None, port: int = 8976, cache: pathlib.Path | bool = True, open_browser: bool = True, on_url: collections.abc.Callable[[str], None] | None = None, timeout: float = 300, **kwargs: Any)

Bases: OAuth

Interactive sign-in in the browser, including enterprise SSO.

Uses authorization code with PKCE on a loopback redirect. Without a client_id the SDK registers a public client (RFC 7591) and caches its id with the session. on_url receives the sign-in URL, for when the browser cannot be opened; it defaults to writing it to stderr.

class ds_fetch_py_sdk.ClientCredentials(client_id: str, client_secret: str, **kwargs: Any)

Bases: OAuth

Machine-to-machine sign-in with a registered client id and secret.

class ds_fetch_py_sdk.OAuth(*, scope: str = 'openid read', **kwargs: Any)

Bases: TokenAuth

OAuth 2.1 against the identity server, with endpoints from RFC 8414 metadata.

property metadata: dict[str, Any]

The identity server’s RFC 8414 metadata, checked to be its own and to use HTTPS.

class ds_fetch_py_sdk.PasswordLogin(email: str | None = None, password: str | None = None, *, mfa_code: str | collections.abc.Callable[[int], str] | None = None, cache: pathlib.Path | bool = True, **kwargs: Any)

Bases: TokenAuth

Sign in with email and password at the identity server’s /auth/login/.

When the account has MFA, mfa_code supplies the TOTP code: a string, or a callable that receives the number of digits and returns the code. The session is renewed with its refresh token; once that expires, signing in again needs the password.

class ds_fetch_py_sdk.TokenAuth(*, issuer: str | None = None, cache: pathlib.Path | bool = False)

Bases: httpx.Auth

A session with the identity server: acquires, caches and renews tokens, and retries once on 401.

Sessions are cached per environment in default_cache(), or at cache; cache=False keeps them in memory.

login() → None

Sign in now, replacing any cached session.

logout() → None

Forget the session, in memory and in the cache.

auth_flow(request: httpx.Request) → collections.abc.Generator[httpx.Request, httpx.Response, None]

Execute the authentication flow.

To dispatch a request, yield it:

` yield request `

The client will .send() the response back into the flow generator. You can access it like so:

` response = yield request `

A return (or reaching the end of the generator) will result in the client returning the last response obtained from the server.

You can dispatch as many requests as is necessary.

ds_fetch_py_sdk.cached_session(env: ds_fetch_py_sdk.env.Environment, cache: pathlib.Path | None = None) → TokenAuth | None

The cached sign-in for env, as the auth that created it, or None.

ds_fetch_py_sdk.MAX_LIMIT = 500

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

class ds_fetch_py_sdk.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>”’)

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.

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.

sql(question: str, *, datasets: collections.abc.Sequence[str] = ()) → str

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

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.

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.

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

class ds_fetch_py_sdk.Tools(client: Fetch)

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

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.

class ds_fetch_py_sdk.Environment

Where the APIs and the identity server live.

resource is the RFC 8707 resource id tokens are minted for. Local uses dev’s identity server and resource, so a dev sign-in works against a locally running service.

exception ds_fetch_py_sdk.AICError

Bases: Exception

Base for every error raised by this SDK.

exception ds_fetch_py_sdk.APIError(status: int, code: str, message: str, *, request_id: str | None = None, retry_after: int = 0, recoverable: bool = False)

Bases: AICError

The API answered with an error.

exception ds_fetch_py_sdk.AuthError

Bases: AICError

Sign-in or token acquisition failed.

exception ds_fetch_py_sdk.NetworkError

Bases: AICError

The API could not be reached, or did not answer in time, after retries.

exception ds_fetch_py_sdk.QueryError(code: str, message: str, details: list[ds_fetch_py_sdk.models.FieldError], *, request_id: str | None)

Bases: APIError

The SQL was rejected (HTTP 422). Fix the query; retrying will not help.

class ds_fetch_py_sdk.QueryResult

Result of one SELECT. Values are JSON-encoded per DuckDB type (see the API docs).

truncated: bool

The 100,000-row or 8 MiB inline limit cut the result.

cache: str | None = None

HIT, MISS or SHARED.

to_pandas() → pandas.DataFrame

Requires the pandas extra.

class ds_fetch_py_sdk.Validation

SQL that would run, checked through binding without reading data.

sql: str

The canonical SQL.

datasets: list[str]

The datasets the SQL reads.

columns: list[Column]

The result columns a query would return.