hotdata-langchain 0.2.1__py3-none-any.whl

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/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,
+    }

hotdata_langchain/tools.py

@@ -0,0 +1,103 @@
+"""LangChain tools built on hotdata-runtime."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from hotdata_runtime import DEFAULT_SCHEMA, HotdataClient, QueryResult
+from langchain_core.tools import StructuredTool
+
+from hotdata_langchain.databases import (
+    create_managed_database,
+    list_managed_databases_json,
+    load_managed_table,
+    load_result_summary,
+    managed_database_summary,
+)
+
+
+def result_rows_for_llm(result: QueryResult, *, max_rows: int = 20) -> list[dict[str, Any]]:
+    return result.to_records(max_rows=max_rows)
+
+
+def execute_sql_json(
+    client: HotdataClient,
+    sql: str,
+    *,
+    max_rows: int = 100,
+    database: str | None = None,
+) -> str:
+    result = client.execute_sql(sql, database=database)
+    payload = {
+        "metadata": result.metadata_dict(),
+        "rows": result.to_records(max_rows=max_rows),
+    }
+    return json.dumps(payload, indent=2)
+
+
+def make_hotdata_tools(
+    client: HotdataClient,
+    *,
+    max_rows: int = 100,
+    database: str | None = None,
+) -> list[StructuredTool]:
+    """Return LangChain tools for SQL and managed database workflows."""
+
+    def hotdata_execute_sql(sql: str) -> str:
+        """Run SQL against the Hotdata workspace and return JSON rows."""
+        return execute_sql_json(client, sql, max_rows=max_rows, database=database)
+
+    def hotdata_list_managed_databases() -> str:
+        """List Hotdata-managed databases in the workspace."""
+        return list_managed_databases_json(client)
+
+    def hotdata_create_managed_database(
+        name: str,
+        schema_name: str = DEFAULT_SCHEMA,
+        tables: str = "",
+    ) -> str:
+        """Create a managed database and optionally declare tables (comma/newline separated)."""
+        table_names = [t.strip() for t in tables.replace(",", "\n").splitlines() if t.strip()]
+        db = create_managed_database(
+            client,
+            name=name,
+            schema=schema_name or DEFAULT_SCHEMA,
+            tables=table_names or None,
+        )
+        return json.dumps(managed_database_summary(db), indent=2)
+
+    def hotdata_load_managed_table(
+        database: str,
+        table: str,
+        file: str,
+        schema_name: str = DEFAULT_SCHEMA,
+    ) -> str:
+        """Load a local parquet file into a declared managed table."""
+        loaded = load_managed_table(
+            client,
+            database=database,
+            table=table,
+            file=file,
+            schema=schema_name or DEFAULT_SCHEMA,
+        )
+        return json.dumps(load_result_summary(loaded), indent=2)
+
+    return [
+        StructuredTool.from_function(
+            func=hotdata_execute_sql,
+            name="hotdata_execute_sql",
+        ),
+        StructuredTool.from_function(
+            func=hotdata_list_managed_databases,
+            name="hotdata_list_managed_databases",
+        ),
+        StructuredTool.from_function(
+            func=hotdata_create_managed_database,
+            name="hotdata_create_managed_database",
+        ),
+        StructuredTool.from_function(
+            func=hotdata_load_managed_table,
+            name="hotdata_load_managed_table",
+        ),
+    ]

hotdata_langchain-0.2.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+hotdata_langchain/__init__.py,sha256=6mmsOi0XrsbZa0AbCvx0wJPe0rsjuYQ8tAhAJHwkGjs,902
+hotdata_langchain/databases.py,sha256=XFfK3b6_xDY3utuTge1RX0r5bFaxlkut1tiMKObnbjc,1522
+hotdata_langchain/tools.py,sha256=opkUACZNVcv1M5ggOqmssjjsBMiALD18Dfczin7twUU,3171
+hotdata_langchain-0.2.1.dist-info/METADATA,sha256=4mOVq-u-flOfdq6cxPOQq_e7RA-ZeMiRxpnu_PqSa24,2715
+hotdata_langchain-0.2.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hotdata_langchain-0.2.1.dist-info/RECORD,,

hotdata_langchain-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any