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