hotdata-langchain 0.2.1__tar.gz

hotdata_langchain-0.2.1/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: daily
+    allow:
+      - dependency-name: hotdata
+      - dependency-name: hotdata-runtime

hotdata_langchain-0.2.1/.github/workflows/check-release.yml

@@ -0,0 +1,26 @@
+name: Check release metadata
+
+on:
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+      - 'CHANGELOG.md'
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Verify changelog matches version bump
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Check release metadata
+        run: python scripts/check-release.py

hotdata_langchain-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python 3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Test
+        run: uv run pytest -v

hotdata_langchain-0.2.1/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,17 @@
+name: Dependabot auto-merge
+
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Enable auto-merge
+        run: gh pr merge --squash --auto "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

hotdata_langchain-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+
+concurrency:
+  group: pypi-publish-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Verify tag matches pyproject version
+        run: |
+          if [[ ! "$GITHUB_REF_NAME" =~ ^v[0-9] ]]; then
+            echo "Release tag '$GITHUB_REF_NAME' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
+            exit 1
+          fi
+          tag="${GITHUB_REF_NAME#v}"
+          pkg_version=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$tag" != "$pkg_version" ]; then
+            echo "Release tag ($tag) does not match pyproject.toml version ($pkg_version)" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hotdata-langchain
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

hotdata_langchain-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: GitHub Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Read package metadata
+        id: meta
+        run: |
+          pkg_name=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['name'])")
+          pkg_version="${GITHUB_REF_NAME#v}"
+          echo "name=${pkg_name}" >> "$GITHUB_OUTPUT"
+          echo "version=${pkg_version}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract changelog notes
+        id: notes
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#v}"
+          if [[ -f CHANGELOG.md ]]; then
+            body="$(python scripts/extract-changelog.py "$version")"
+          else
+            body="Release ${version}."
+          fi
+          delimiter="EOF_${RANDOM}_${RANDOM}"
+          {
+            echo "body<<${delimiter}"
+            echo "$body"
+            echo "${delimiter}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@1e812e8210a4a8a0b23075e5795f2a4e2b2a0b7 # v2.2.2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ steps.meta.outputs.name }} ${{ steps.meta.outputs.version }}
+          body: ${{ steps.notes.outputs.body }}
+          generate_release_notes: false
+          make_latest: true

hotdata_langchain-0.2.1/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Packaging
+*.egg-info/
+dist/
+build/
+
+.DS_Store

hotdata_langchain-0.2.1/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+
+## [0.2.1] - 2026-06-22
+
+### Changed
+
+- Pin `hotdata-runtime` to `>=0.3.0` (adds the typed-error API:
+  `HotdataError`/`HotdataTransientError`/`HotdataTerminalError`/`classify_sdk_error`).
+  No code adoption was required: this package has no SDK error-handling call sites — its
+  runtime calls are thin pass-throughs exposed as LangChain `StructuredTool`s, which let
+  exceptions propagate to the LangChain runtime by design.
+
+## [0.2.0] - 2026-06-22
+
+### Changed
+
+- Upgrade `hotdata` SDK pin to `>=0.4.1` and `hotdata-runtime` to `>=0.2.4`.
+- Raise `langchain-core` floor to `>=1.0` (verified against the test suite).
+
+### Added
+
+- Ruff and mypy tooling configuration in `pyproject.toml`, plus `ruff` and `mypy`
+  dev dependencies. Applied `ruff check --fix` and `ruff format` cleanup across the
+  codebase.
+
+## [0.1.1] - 2026-06-01
+
+### Changed
+
+- Release 0.1.1
+
+## [0.1.0] - 2026-05-19
+
+### Added
+
+- Initial release with LangChain tools for Hotdata managed databases.

hotdata_langchain-0.2.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: hotdata-langchain
+Version: 0.2.1
+Summary: LangChain tools for Hotdata runtime
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: hotdata-runtime>=0.3.0
+Requires-Dist: hotdata>=0.4.1
+Requires-Dist: langchain-core>=1.0
+Description-Content-Type: text/markdown
+
+# hotdata-langchain
+
+Give your [LangChain](https://python.langchain.com/) agents access to [Hotdata](https://hotdata.dev) — run SQL against your workspace connections and work with managed databases.
+
+## Install
+
+```bash
+pip install hotdata-langchain
+```
+
+## Authentication
+
+Set `HOTDATA_API_KEY` in your environment. Optionally set `HOTDATA_WORKSPACE` to pin a specific workspace (the first available workspace is used if unset).
+
+## Quickstart
+
+```python
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+import hotdata_langchain as hl
+
+client = hl.from_env()
+tools = hl.make_hotdata_tools(client)
+
+agent = create_tool_calling_agent(llm=your_llm, tools=tools, prompt=your_prompt)
+executor = AgentExecutor(agent=agent, tools=tools)
+result = executor.invoke({"input": "How many rows are in the orders table?"})
+```
+
+## Tools
+
+`make_hotdata_tools(client)` returns a list of LangChain `StructuredTool` objects ready to pass to any agent:
+
+| Tool | What it does |
+|------|-------------|
+| `hotdata_execute_sql` | Run a SQL query and return rows as JSON |
+| `hotdata_list_managed_databases` | List available managed databases |
+| `hotdata_create_managed_database` | Create a new managed database |
+| `hotdata_load_managed_table` | Load a parquet file into a managed table |
+
+## Calling tools directly
+
+You can also invoke tools outside of an agent loop:
+
+```python
+tools = {t.name: t for t in hl.make_hotdata_tools(client)}
+
+result = tools["hotdata_execute_sql"].invoke({"sql": "SELECT * FROM orders LIMIT 10"})
+print(result)  # JSON rows
+
+tools["hotdata_create_managed_database"].invoke({
+    "name": "sales",
+    "schema_name": "public",
+    "tables": "orders,customers",
+})
+
+tools["hotdata_load_managed_table"].invoke({
+    "database": "sales",
+    "table": "orders",
+    "file": "/path/to/orders.parquet",
+})
+```
+
+## Scoping queries to a managed database
+
+Pass `database=` so all SQL the agent runs resolves against a specific managed database:
+
+```python
+tools = hl.make_hotdata_tools(client, database="sales")
+```
+
+## Controlling result size
+
+Limit how many rows are returned to the LLM. Useful for keeping responses within context limits (default: 100):
+
+```python
+tools = hl.make_hotdata_tools(client, max_rows=50)
+```
+
+## Run the examples
+
+```bash
+uv run python examples/langchain_basic.py
+uv run python examples/langchain_managed_db.py
+```
+
+## Development
+
+```bash
+uv sync --locked
+uv run pytest
+```

hotdata_langchain-0.2.1/README.md

@@ -0,0 +1,91 @@
+# hotdata-langchain
+
+Give your [LangChain](https://python.langchain.com/) agents access to [Hotdata](https://hotdata.dev) — run SQL against your workspace connections and work with managed databases.
+
+## Install
+
+```bash
+pip install hotdata-langchain
+```
+
+## Authentication
+
+Set `HOTDATA_API_KEY` in your environment. Optionally set `HOTDATA_WORKSPACE` to pin a specific workspace (the first available workspace is used if unset).
+
+## Quickstart
+
+```python
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+import hotdata_langchain as hl
+
+client = hl.from_env()
+tools = hl.make_hotdata_tools(client)
+
+agent = create_tool_calling_agent(llm=your_llm, tools=tools, prompt=your_prompt)
+executor = AgentExecutor(agent=agent, tools=tools)
+result = executor.invoke({"input": "How many rows are in the orders table?"})
+```
+
+## Tools
+
+`make_hotdata_tools(client)` returns a list of LangChain `StructuredTool` objects ready to pass to any agent:
+
+| Tool | What it does |
+|------|-------------|
+| `hotdata_execute_sql` | Run a SQL query and return rows as JSON |
+| `hotdata_list_managed_databases` | List available managed databases |
+| `hotdata_create_managed_database` | Create a new managed database |
+| `hotdata_load_managed_table` | Load a parquet file into a managed table |
+
+## Calling tools directly
+
+You can also invoke tools outside of an agent loop:
+
+```python
+tools = {t.name: t for t in hl.make_hotdata_tools(client)}
+
+result = tools["hotdata_execute_sql"].invoke({"sql": "SELECT * FROM orders LIMIT 10"})
+print(result)  # JSON rows
+
+tools["hotdata_create_managed_database"].invoke({
+    "name": "sales",
+    "schema_name": "public",
+    "tables": "orders,customers",
+})
+
+tools["hotdata_load_managed_table"].invoke({
+    "database": "sales",
+    "table": "orders",
+    "file": "/path/to/orders.parquet",
+})
+```
+
+## Scoping queries to a managed database
+
+Pass `database=` so all SQL the agent runs resolves against a specific managed database:
+
+```python
+tools = hl.make_hotdata_tools(client, database="sales")
+```
+
+## Controlling result size
+
+Limit how many rows are returned to the LLM. Useful for keeping responses within context limits (default: 100):
+
+```python
+tools = hl.make_hotdata_tools(client, max_rows=50)
+```
+
+## Run the examples
+
+```bash
+uv run python examples/langchain_basic.py
+uv run python examples/langchain_managed_db.py
+```
+
+## Development
+
+```bash
+uv sync --locked
+uv run pytest
+```

hotdata_langchain-0.2.1/RELEASING.md

@@ -0,0 +1,43 @@
+# Releasing
+
+Every release uses `./scripts/release.sh`. Do not bump versions, tag, or create GitHub Releases manually.
+
+## One-time setup
+
+- Install [GitHub CLI](https://cli.github.com/) (`gh`) and authenticate.
+- Ensure PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/) is configured for this repo (`publish.yml` uses the `pypi` GitHub environment).
+
+## Release steps
+
+1. Add user-facing notes under `## [Unreleased]` in `CHANGELOG.md`.
+2. Prepare the release PR:
+
+   ```bash
+   ./scripts/release.sh prepare patch   # or minor | major | 1.2.3
+   ```
+
+3. Merge the PR after CI passes (including the changelog check).
+4. Publish from a clean default branch checkout:
+
+   ```bash
+   git checkout main   # or master for hotdata-marimo
+   git pull
+   ./scripts/release.sh publish
+   ```
+
+## What happens automatically
+
+Pushing a `vX.Y.Z` tag triggers two workflows:
+
+| Workflow | Purpose |
+|----------|---------|
+| `publish.yml` | Build wheel/sdist and publish to PyPI |
+| `release.yml` | Create the GitHub Release with notes from `CHANGELOG.md` |
+
+## Enforcement
+
+- **PR check** (`check-release.yml`): if `pyproject.toml` version changes, `CHANGELOG.md` must contain a matching `## [X.Y.Z]` section.
+- **Tag check** (`publish.yml`): the tag (without `v`) must match `[project].version` in `pyproject.toml`.
+- **Publish guard** (`release.sh publish`): refuses to tag if the changelog section is missing.
+
+Together, these make it hard to ship a version without changelog notes or a GitHub Release.

hotdata_langchain-0.2.1/examples/langchain_basic.py

@@ -0,0 +1,21 @@
+"""Minimal LangChain tool usage with hotdata-langchain."""
+
+import hotdata_langchain as hl
+
+
+def main() -> None:
+    client = hl.from_env()
+    tools = hl.make_hotdata_tools(client)
+    by_name = {tool.name: tool for tool in tools}
+
+    sql_tool = by_name["hotdata_execute_sql"]
+    print(sql_tool.invoke({"sql": "SELECT 1 AS ok"}))
+
+    list_tool = by_name["hotdata_list_managed_databases"]
+    print(list_tool.invoke({}))
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

hotdata_langchain-0.2.1/examples/langchain_managed_db.py

@@ -0,0 +1,38 @@
+"""Managed database tools for LangChain agents."""
+
+import hotdata_langchain as hl
+
+
+def main() -> None:
+    client = hl.from_env()
+    tools = hl.make_hotdata_tools(client)
+    by_name = {tool.name: tool for tool in tools}
+
+    create = by_name["hotdata_create_managed_database"]
+    print(
+        create.invoke(
+            {
+                "name": "demo_sales",
+                "schema_name": "public",
+                "tables": "orders\ncustomers",
+            }
+        )
+    )
+
+    load = by_name["hotdata_load_managed_table"]
+    print(
+        load.invoke(
+            {
+                "database": "demo_sales",
+                "table": "orders",
+                "file": "/path/to/orders.parquet",
+                "schema_name": "public",
+            }
+        )
+    )
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

hotdata_langchain-0.2.1/hotdata_langchain/__init__.py

@@ -0,0 +1,38 @@
+"""LangChain tools for Hotdata runtime."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hotdata-langchain")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+from hotdata_runtime import HotdataClient, QueryResult, from_env
+
+from hotdata_langchain.databases import (
+    create_managed_database,
+    list_managed_databases_json,
+    load_managed_table,
+    load_result_summary,
+    managed_database_summary,
+)
+from hotdata_langchain.tools import (
+    execute_sql_json,
+    make_hotdata_tools,
+    result_rows_for_llm,
+)
+
+__all__ = [
+    "HotdataClient",
+    "QueryResult",
+    "__version__",
+    "create_managed_database",
+    "execute_sql_json",
+    "from_env",
+    "list_managed_databases_json",
+    "load_managed_table",
+    "load_result_summary",
+    "make_hotdata_tools",
+    "managed_database_summary",
+    "result_rows_for_llm",
+]

hotdata_langchain-0.2.1/hotdata_langchain/databases.py

@@ -0,0 +1,60 @@
+"""Managed database helpers for LangChain agents."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from hotdata_runtime import (
+    DEFAULT_SCHEMA,
+    HotdataClient,
+    LoadManagedTableResult,
+    ManagedDatabase,
+)
+
+
+def list_managed_databases_json(client: HotdataClient) -> str:
+    rows = [
+        {
+            "description": db.description,
+            "id": db.id,
+            "sql_prefix": f"{db.id}.{{schema}}.{{table}}",
+        }
+        for db in client.list_managed_databases()
+    ]
+    return json.dumps(rows, indent=2)
+
+
+def create_managed_database(
+    client: HotdataClient,
+    *,
+    name: str,
+    schema: str = DEFAULT_SCHEMA,
+    tables: list[str] | None = None,
+) -> ManagedDatabase:
+    return client.create_managed_database(description=name, schema=schema, tables=tables)
+
+
+def load_managed_table(
+    client: HotdataClient,
+    *,
+    database: str,
+    table: str,
+    file: str,
+    schema: str = DEFAULT_SCHEMA,
+) -> LoadManagedTableResult:
+    return client.load_managed_table(database, table, schema=schema, file=file)
+
+
+def managed_database_summary(db: ManagedDatabase) -> dict[str, str]:
+    return {"id": db.id, "description": db.description or db.id}
+
+
+def load_result_summary(result: LoadManagedTableResult) -> dict[str, Any]:
+    return {
+        "connection_id": result.connection_id,
+        "schema_name": result.schema_name,
+        "table_name": result.table_name,
+        "row_count": result.row_count,
+        "full_name": result.full_name,
+    }