Skip to content

data-harness

data-harness — The controlled data-agent SDK

The controlled data-agent SDK. Python, not bash. Large data stays in a cache as handles, never in the prompt. Every run is logged — and eval-backed.

Most data-agent tooling makes you pick between giving a model a shell (unsafe, irreproducible) and single-shot code-gen (no state, no multi-step). data-harness is the controlled middle path: the model works through a constrained Python interpreter, large objects live in a SessionCache exposed as compact handle snapshots (so a 100k-row table never hits the context window), every turn is logged to JSONL, and a built-in evaluation harness measures quality and cost across providers.

Install

pip install data-harness          # core
pip install "data-harness[all]"   # + openai, charts, duckdb, sqlalchemy, notebook, eval

Requires Python 3.10+. Pick individual extras as needed: [openai], [viz], [duckdb], [sql], [notebook], [eval], [demo].

30-second example

import pandas as pd
from data_harness import ask

df = pd.read_csv("sales.csv")
result = ask(df, "What was total revenue, and which month was highest?")

print(result.text)    # the written answer
print(result.value)   # the structured result the model computed via answer()
result.charts         # any charts it rendered (notebook-friendly)

Or from the shell:

dh "What was total revenue?" sales.csv

ask() resolves a provider from your environment (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or DEEPSEEK_API_KEY) and returns a RunResult. See the Quickstart.

What you get

  • Quickstart — ask(), Chat, the dh CLI, and inspecting results.
  • Asking questions — charts, SQL, the semantic layer, multi-provider, and production controls (sandbox, approval gate, replay cache).
  • Evaluation — programmatic graders, multi-turn cases, cost leaderboards, and tracked results.
  • Sessions · Connectors · Async & Streaming — multi-turn state, progressive tools, streaming.
  • Examples — runnable scripts and a demo notebook.
  • Architecture — why the harness is built this way (no bash, handle/snapshot, prefix-stable prompt, subagents, JSONL logs).

Design series

The thinking behind data-harness:

License: MIT.