lacon

token-lean agent↔data query interface — query files, don't read them

Before/After • Install • What You Get • Primitives • HITL • Python API • CLI Reference

When an agent needs to understand a CSV or Parquet file, the naive approach is to dump the whole file into context. A 5 MB CSV is ~350k tokens. lacon is the opposite: agents query the file and get back only the answer — shaped, capped, and token-costed. DuckDB does the querying under the hood; lacon's value is the interface and the result shaping.

Sibling to datoon (cheaper representation once data is in the prompt) — lacon's lever is to not put the data there at all.

Before / After

# agent reads the whole file
content = open("sales.csv").read()
# → 350k tokens for a 5 MB file
prompt = f"Analyze this data:\n{content}"

lacon describe sales.csv --pretty

{
  "op": "describe",
  "row_count": 84000,
  "schema": [{"name": "country", "type": "VARCHAR"}, ...],
  "~tokens": 89
}

# without lacon — dumps rows, agent parses
rows = csv.DictReader(open("sales.csv"))
prompt = f"Sum revenue by country from:\n{list(rows)}"
# → thousands of tokens

lacon aggregate sales.csv \
  --group-by country \
  --metrics revenue:sum --pretty

{"op": "aggregate", "rows": [["UA", 4500.25], ...], "~tokens": 62}

Same answer. Tiny fraction of the token cost.

┌─────────────────────────────────────────────────────┐
│  DESCRIBE A 5MB FILE    ████░░░░░░░░   89 tokens    │
│  SAME FILE DUMPED RAW   ████████████  350k tokens   │
│  WRITES ALLOWED         ░░░░░░░░░░░░   0 (read-only)│
└─────────────────────────────────────────────────────┘

Install

# core (CLI + DuckDB + SQL validation)
pip install lacon
uv add lacon

# with token estimates (~tokens in every response)
pip install "lacon[tokens]"

# with MCP server (coming in v0.2)
pip install "lacon[mcp]"

Requires Python 3.12+.

Claude Code skill:

claude skill install https://github.com/andrii-su/lacon/releases/latest/download/lacon.skill

Once installed, Claude automatically uses lacon when you mention a .csv, .parquet, or .json file — no manual invocation needed.

What You Get

Primitives

9 curated operations. Each builds safe SQL internally, enforces read-only, and applies auto-LIMIT.

Supported formats: CSV, Parquet, JSON, JSONL — auto-detected from extension.

Quick Start

# always start here
lacon describe data.csv --pretty

# understand a column
lacon profile data.csv --column revenue --pretty

# answer a count question
lacon count data.csv --where "country = 'UA'"

# group by
lacon aggregate data.csv --group-by country --metrics revenue:sum --pretty

# filter with column projection
lacon filter data.csv --where "year = 2024" --columns name revenue --pretty

# unique values
lacon distinct data.csv --column country --pretty

# find duplicates
lacon find-duplicates data.csv --columns email --pretty

# escape hatch — use HITL (see below)
lacon query data.csv "SELECT country, AVG(revenue) FROM {file} GROUP BY country" --show-sql --pretty
lacon query data.csv "SELECT country, AVG(revenue) FROM {file} GROUP BY country" --pretty

Use {file} as the placeholder for the data source in query. Auto-LIMIT is always enforced (default 50, max 1000).

HITL for query

The query primitive runs arbitrary SQL — an escape hatch when curated primitives aren't enough. Because the SQL is not predictable from fixed parameters, always preview before executing.

# Step 1 — preview resolved SQL (no execution)
lacon query sales.csv \
  "SELECT country, name, revenue FROM {file} t \
   WHERE revenue = (SELECT MAX(revenue) FROM {file} t2 WHERE t2.country = t.country) \
   ORDER BY revenue DESC" \
  --show-sql --pretty

{
  "op": "query",
  "sql": "SELECT country, name, revenue FROM read_csv('sales.csv') t WHERE ...",
  "will_execute": false
}

# Step 2 — confirm the SQL, then execute
lacon query sales.csv "..." --pretty

Result always includes the sql field so you can verify what ran:

{
  "op": "query",
  "schema": ["country", "name", "revenue"],
  "rows": [["UA", "Bob", 3400.0], ...],
  "shown": 3,
  "~tokens": 74,
  "sql": "SELECT country, name, revenue FROM read_csv('sales.csv') t WHERE ..."
}

Why: text-to-SQL agents achieve ~80% accuracy on real schemas. A subtly wrong WHERE clause executes silently and looks correct. Showing the SQL before execution catches errors before they produce wrong answers. Curated primitives need no confirmation — their SQL is fully determined by parameters.

Output Envelope

Every response is a shaped JSON object:

{
  "op": "aggregate",
  "schema": ["country", "sum_revenue"],
  "rows": [["UA", 4500.25], ["DE", 2200.0], ["US", 2001.25]],
  "shown": 3,
  "~tokens": 62
}

describe returns metadata only (no rows). count returns a single integer.

Python API

from lacon import DuckDBEngine, describe, sample, count, aggregate, filter, query

with DuckDBEngine() as engine:
    # schema + metadata
    r = describe("data.csv", engine)
    print(r["row_count"], r["schema"])

    # column stats
    r = profile("data.csv", column="revenue", engine=engine)
    print(r["min"], r["max"], r["mean"])

    # grouped aggregation
    r = aggregate(
        "data.csv",
        group_by=["country"],
        metrics=[{"col": "revenue", "fn": "sum"}],
        engine=engine,
    )

    # filtered rows with projection
    r = filter("data.csv", where="revenue > 2000", columns=["name", "revenue"], engine=engine)

    # escape hatch — read-only, auto-LIMIT
    r = query("data.csv", "SELECT country, AVG(revenue) FROM {file} GROUP BY country", engine=engine)

Safety

• Read-only — no writes, no DDL, no COPY, no INSTALL
• SQL validation — sqlglot parses every query call; rejects INSERT, DROP, CREATE, multi-statement
• Auto-LIMIT — injected if missing, capped at 1000
• Path escaping — single quotes in paths escaped before DuckDB

CLI Reference

Global options

describe <path>

Schema, row count, file size. Always start here.

sample <path>

count <path>

profile <path>

aggregate <path>

filter <path>

distinct <path>

find-duplicates <path>

query <path> SQL

Use {file} as the data-source placeholder in SQL.

Development

# setup
uv sync --extra dev
uvx pre-commit install

# tests (46 — primitives, safety, shaping)
uv run --with ".[dev,tokens]" pytest

# build lacon.skill for distribution
python scripts/build_skill.py

Links

• CONTRIBUTING.md — contributor workflow
• CLAUDE.md — agent/maintainer context
• CHANGELOG.md — release history
• SECURITY.md — vulnerability reporting
• Live docs — docs/
• Issues — bugs, features, questions

License

MIT