Skip to content

Build with TabulaFlow

At the core of TabulaFlow is a minimalist, async-native Python library for building and researching data agents. It was the first thing we built when we started this project because existing libraries lacked the abstractions we needed. Its building blocks allow you to write agent logic that runs across different database backends and research benchmarks. The same library powers the TabulaFlow data agent.

You can use any of these building blocks to create data applications with (e.g. data agents) or without an LLM (e.g., interactive dashboards). Choose the building blocks you need:

  • Data connectors: inspect schemas and query SQL databases, Neo4j, SPARQL endpoints, files, and datasets through a unified async interface.
  • Extraction and enrichment: turn documents into structured records and enrich DataFrames with new fields.
  • Chat sessions: use ChatSession to converse across multiple data sources, run tools, and stream answers and progress, with automatic context compaction for long conversations.
  • Structured outputs: let agents produce tables, charts, maps, and graphs as structured artifacts by defining declarative specifications, with optional lazy data resolution for parameter-driven interaction.
  • Custom agents: combine reusable query, visualization, and document tools with your own functions and actions, without adopting ChatSession.
  • Schema and result formatting: turn structured schemas and query results into readable text for LLM prompts or human inspection.

These building blocks are fully typed and organized into four layers: core <- data <- output <- agents. See the API reference for how they fit together.

Example: Chat with two data sources

Sales orders and support tickets live in separate commerce and helpdesk systems. Join them by customer ID to compare each customer's revenue with open high-priority issues, with an inspectable chart and table.

An in-memory DuckDB workspace lets the agent join results from separate connections without modifying either source.

quick_start.py
import asyncio

import pandas as pd

from tabulaflow.agents import ChatSession
from tabulaflow.data import DataConnectorRegistry, SQLConnector
from tabulaflow.output.specs import ChartArtifactSpec, TableArtifactSpec


async def load_sample_data(sales: SQLConnector, support: SQLConnector) -> None:
    await sales.write_dataframe_async(
        pd.DataFrame(
            columns=["order_id", "region", "revenue_usd"],
            data=[
                (1001, "West", 1200),
                (1002, "West", 800),
                (1003, "East", 900),
                (1004, "East", 600),
            ],
        ),
        "sales",
    )
    await support.write_dataframe_async(
        pd.DataFrame(
            columns=["ticket_id", "subject", "priority", "status"],
            data=[
                (201, "Checkout payment failures", "high", "open"),
                (202, "Invoice downloads unavailable", "high", "open"),
                (203, "Profile image upload issue", "low", "open"),
                (204, "Password reset emails delayed", "high", "resolved"),
            ],
        ),
        "support",
    )


async def main() -> None:
    async with DataConnectorRegistry() as registry:
        sales = await SQLConnector.from_url_async("sqlite+aiosqlite:///:memory:", read_only=False)
        # The registry closes registered connectors when this block exits.
        registry.register("sales", sales)
        support = await SQLConnector.from_url_async("sqlite+aiosqlite:///:memory:", read_only=False)
        registry.register("support", support)
        await load_sample_data(sales, support)

        async with ChatSession(
            registry=registry,
            model="openai:gpt-5.6-sol",
            reasoning="low",
        ) as session:
            result = await session.run(
                "How does revenue compare across regions, and which high-priority "
                "support tickets are still open? Show revenue as a bar chart "
                "and the tickets in a table."
            )
            print("Answer:", result.text)

            for artifact in result.output.artifacts:
                if isinstance(artifact, (TableArtifactSpec, ChartArtifactSpec)):
                    data = await session.output_store.resolve_artifact_source(artifact.source_id)
                    print("Artifact:", artifact.label)
                    print("Source:", data.metadata.connector_alias)
                    print("SQL:", data.metadata.query)
                    print("DataFrame:\n", data.df)


if __name__ == "__main__":
    asyncio.run(main())
Sample output
Answer: The customer summary and total revenue bar chart are shown above. The joined results are also saved as `customer_sales_support_summary` in the workspace.

------------------------------------------------------------------------
Artifact: customer summary
Source: workspace
SQL: CREATE OR REPLACE TABLE customer_sales_support_summary AS
WITH revenue AS (
    SELECT
        customer_id,
        SUM(revenue_usd) AS total_revenue_usd
    FROM sales_orders
    GROUP BY customer_id
),
open_high_priority AS (
    SELECT
        customer_id,
        COUNT(*) FILTER (
            WHERE lower(status) = 'open'
              AND lower(priority) = 'high'
        ) AS open_high_priority_tickets
    FROM support_tickets
    GROUP BY customer_id
),
customers AS (
    SELECT customer_id FROM revenue
    UNION
    SELECT customer_id FROM open_high_priority
)
SELECT
    c.customer_id,
    COALESCE(r.total_revenue_usd, 0) AS total_revenue_usd,
    COALESCE(t.open_high_priority_tickets, 0) AS open_high_priority_tickets
FROM customers c
LEFT JOIN revenue r USING (customer_id)
LEFT JOIN open_high_priority t USING (customer_id)
ORDER BY c.customer_id;

SELECT * FROM customer_sales_support_summary ORDER BY customer_id;
DataFrame:
    customer_id  total_revenue_usd  open_high_priority_tickets
0          101               2000                           1
1          102                900                           1
2          103                600                           0

------------------------------------------------------------------------
Artifact: total revenue
Source: workspace
SQL: CREATE OR REPLACE TABLE customer_sales_support_summary AS
WITH revenue AS (
    SELECT
        customer_id,
        SUM(revenue_usd) AS total_revenue_usd
    FROM sales_orders
    GROUP BY customer_id
),
open_high_priority AS (
    SELECT
        customer_id,
        COUNT(*) FILTER (
            WHERE lower(status) = 'open'
              AND lower(priority) = 'high'
        ) AS open_high_priority_tickets
    FROM support_tickets
    GROUP BY customer_id
),
customers AS (
    SELECT customer_id FROM revenue
    UNION
    SELECT customer_id FROM open_high_priority
)
SELECT
    c.customer_id,
    COALESCE(r.total_revenue_usd, 0) AS total_revenue_usd,
    COALESCE(t.open_high_priority_tickets, 0) AS open_high_priority_tickets
FROM customers c
LEFT JOIN revenue r USING (customer_id)
LEFT JOIN open_high_priority t USING (customer_id)
ORDER BY c.customer_id;

SELECT * FROM customer_sales_support_summary ORDER BY customer_id;
DataFrame:
    customer_id  total_revenue_usd  open_high_priority_tickets
0          101               2000                           1
1          102                900                           1
2          103                600                           0
Vega-Lite spec:
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "title": "Total Revenue by Customer",
  "mark": "bar",
  "encoding": {
    "x": {
      "field": "customer_id",
      "type": "nominal",
      "title": "Customer ID",
      "sort": null
    },
    "y": {
      "field": "total_revenue_usd",
      "type": "quantitative",
      "title": "Total Revenue (USD)",
      "axis": {
        "format": "$,.0f"
      }
    },
    "tooltip": [
      {
        "field": "customer_id",
        "type": "nominal",
        "title": "Customer ID"
      },
      {
        "field": "total_revenue_usd",
        "type": "quantitative",
        "title": "Total Revenue",
        "format": "$,.0f"
      }
    ]
  }
}

result.text contains the answer; result.output contains the chart and table specifications. See Structured outputs for parameter-driven outputs.

Try it yourself

Install TabulaFlow once with uv, set your API key, and run the bundled example:

uv tool install tabulaflow
export OPENAI_API_KEY="your-api-key"
tabulaflow examples run quick-start

For another model, see supported providers and credentials and update the ChatSession model.

The tool installation can run every bundled example from any directory. For an example without an API key, try Data connectors.

Build in your project

Install TabulaFlow in a Python project when you are ready to import it in your own code:

uv add tabulaflow
pip install tabulaflow

The default installation includes the complete dependency set for the Python library and the tabulaflow data-agent application (Chromium is installed separately when web browsing is needed). Advanced library users who manage their own dependencies can instead run uv pip install --no-deps tabulaflow or pip install --no-deps tabulaflow, then install the packages required by the APIs and connectors they use.