hotdata-framework

A Python framework for building Hotdata integrations.

Shared runtime primitives for Hotdata integrations: workspace semantics, execution context, query state, run history, and replayable result handles. Framework packages (Marimo, Jupyter, Streamlit, LangGraph) depend on this package.

Runtime boundary and guarantees are defined in CONTRACT.md.

Features

Environment-driven client setup — create clients from HOTDATA_API_KEY, optional HOTDATA_API_URL, and HOTDATA_WORKSPACE.
Workspace resolution — choose an explicit workspace from env, otherwise discover workspaces and select the active workspace or first available workspace.
HTTP resilience — retry SQL execution on stale pooled sockets. Transport-level retries are the SDK's own default, which this package leaves in place so a non-idempotent request is never replayed on a response status.
SQL execution helper — run SQL through POST /v1/query, poll async query runs when needed, and return a QueryResult.
Result utilities — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
History helpers — list recent results and query run history with normalized dataclasses.
Managed databases — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors hotdata databases in the CLI).
Indexes — build BM25, vector, or sorted indexes on managed tables, mirroring hotdata indexes create (managed databases only). Waits on the background build job and surfaces its failure, instead of reporting the phantom success the submit call returns.
Health helpers — build compact API/workspace health summaries for UI integrations.

Install:

uv pip install hotdata-framework
# or: pip install hotdata-framework

Example:

python examples/basic_usage.py

Development (uses uv; creates .venv/ in this repo):

uv sync --locked
uv run pytest

uv.lock is checked in so CI can run uv sync --locked. The default dev group (pytest) is enabled via [tool.uv] default-groups.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hotdata_framework-0.12.1.tar.gz (126.9 kB view details)

Uploaded Aug 18, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hotdata_framework-0.12.1-py3-none-any.whl (24.8 kB view details)

Uploaded Aug 18, 2026 Python 3

File details

Details for the file hotdata_framework-0.12.1.tar.gz.

File metadata

Download URL: hotdata_framework-0.12.1.tar.gz
Upload date: Aug 18, 2026
Size: 126.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hotdata_framework-0.12.1.tar.gz
Algorithm	Hash digest
SHA256	`86dd453f14ed3793cd2526b48cbb823b0d20d610fe784075debc74a544b99a5e`
MD5	`a6928635a916f0ed42db30f194e71f66`
BLAKE2b-256	`d7b1c44c520b861696cd138a5686e54fa3f0213ab35aede16a4fe0c4f5260915`

See more details on using hashes here.

Provenance

The following attestation bundles were made for hotdata_framework-0.12.1.tar.gz:

Publisher: publish.yml on hotdata-dev/sdk-python-framework

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: hotdata_framework-0.12.1.tar.gz
- Subject digest: 86dd453f14ed3793cd2526b48cbb823b0d20d610fe784075debc74a544b99a5e
- Sigstore transparency entry: 2503041234
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: hotdata-dev/sdk-python-framework@d6b6e839f5efcac476c1fc1170e522e0416ab95c
- Branch / Tag: refs/tags/v0.12.1
- Owner: https://github.com/hotdata-dev
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@d6b6e839f5efcac476c1fc1170e522e0416ab95c
- Trigger Event: push