Tier: Intermediate Commands covered: describegpt, synthesize, apply summarize

The flagship here is describegpt — a neuro-symbolic data dictionary generator and SQL-RAG chat assistant. "Neuro-symbolic" means the heavy lifting (column types, ranges, cardinalities) is done deterministically by qsv's stats and frequency caches; the LLM only fills in human-friendly labels and descriptions. The result: hallucination-resistant data documentation, often produced against a local LLM (Ollama / Jan / LM Studio).

Since 20.1.0, describegpt can also tag each column with a semantic Content Type from a curated 49-token vocabulary (email, phone, street_address, job_title, credit_card, ipv6_address, …). Those tags then drive the new synthesize command, which generates a statistically-faithful fake CSV that mirrors the source's distributions and null rates while substituting realistic fakes for sensitive columns.

For the deep-dive, see docs/Describegpt.md and the output gallery (Markdown, JSON, TOON, Semantic Markdown, OKF, Spanish, Mandarin, and SQL-RAG examples).

Calls any OpenAI-compatible LLM endpoint with a configurable MiniJinja-templated prompt. The prompt is fed pre-computed summary statistics and frequency distribution from qsv's stats / frequency caches — that's the "symbolic" half. The LLM generates only the natural-language labels and descriptions — that's the "neuro" half. Result: deterministic, reproducible documentation that doesn't hallucinate column names or invent ranges.

• Dictionary mode (--dictionary, --description, --tags, --all) — generates documentation for the whole dataset.
• Chat / RAG mode (--prompt "...") — answer a natural-language question. If the answer needs more than stats+frequency, qsv enters SQL-RAG sub-mode: it generates a SQL query, runs it against the data (DuckDB if QSV_DUCKDB_PATH is set, Polars SQL otherwise), and returns the deterministic answer.

qsv describegpt data.csv --api-key "$OPENAI_API_KEY" --all
# Writes data.dictionary.json (or similar) and prints a Markdown summary

qsv describegpt NYC_311_SR_2010-2020-sample-1M.csv \
  -u http://localhost:11434/v1 \
  --model deepseek-r1:14b \
  --dictionary

qsv describegpt NYC_311_SR_2010-2020-sample-1M.csv \
  --prompt "What is the most common complaint type?"

The LLM consults the frequency table (already cached) and answers without writing any SQL.

qsv describegpt NYC_311_SR_2010-2020-sample-1M.csv \
  --prompt "What are the top 10 complaint types by community board and borough by year?"

Stats alone can't answer this (it needs a group-by × borough × year), so qsv:

1. Builds a small random sample as additional LLM context.
2. Asks the LLM to write a SQL query that answers the question.
3. Runs the query with DuckDB (if QSV_DUCKDB_PATH is set) or Polars SQL.
4. Returns the actual result, not a guess. See docs/describegpt/nyc311-describegpt-prompt.md for a worked example with the resulting CSV.

The Allegheny property sales session shows three rounds of refinement against the dataset. The final query produces a most-expensive-listings CSV — deterministic, reproducible.

qsv describegpt NYC_311.csv --all --language Spanish  > nyc311-describegpt-spanish.md
qsv describegpt NYC_311.csv --all --language Mandarin > nyc311-describegpt-mandarin.md

(See docs/describegpt/ for actual Spanish and Mandarin outputs.)

--language is not limited to languages — it takes a language, dialect or tone: "Castilian", "Franglais", "Taglish", "Chavacano", "Gen Z", "Pirate", "Shakespearean English", "Yoda".

With --dictionary, describegpt detects the dataset's own content language before it asks the LLM anything — locally, from sampled values of the text columns, using whatlang. It is deterministic and costs zero tokens (no LLM round trip).

When detection clears the confidence threshold, three fields are emitted — detected_language, detected_language_code (ISO 639-3) and detected_language_confidence — at the top level of JSON output, or in the x-qsv object of JSON Schema output. When detection is not confident, the fields are simply omitted rather than guessed.

Detection then drives the LLM's output language, so a Spanish dataset gets a Spanish dictionary without being asked. Downstream, viz smart reads detected_language_code to render the whole Data Schematic in that language.

qsv describegpt NYC_311.csv \
  --tags \
  --tag-vocab data-tag-vocabulary.csv > nyc311-tags.md

--tag-vocab constrains the LLM to choose from a list of approved tags — useful for CKAN harmonization.

viz smart dashboards open with a guided Tour, and --tour-audience decides who it is talking to. It has describegpt write an x-qsv.tour narration into the dictionary during inference, addressed to that audience.

qsv describegpt city_budget.csv --dictionary --format jsonschema \
    --tour-audience "the City Council" -o city_budget.schema.json

It defaults to "Explain like I'm 10", and the same dataset will happily brief "a board of directors", "data journalists", "my 11th grade Civics class" or "an urban planner". Combine with --language for a non-English tour.

Automatic content-language detection used to accept any reading that cleared a confidence threshold. A table of city, country and continent names was read as Italian at 0.9308 confidence — comfortably past the 0.8 gate — and viz smart then localized an entire Data Schematic to Italian.

Detection now requires agreement across chunks rather than confidence on one, so a confidently-wrong reading of proper nouns no longer wins.

describegpt emits Markdown (default), JSON, TOON (Toon Format — a compact JSON encoding designed for LLM prompts), JSONSchema, SemanticMd, and OKF (the last three dictionary-centric — see below). See docs/describegpt/ for examples of each.

describegpt --format jsonschema emits the Data Dictionary as a JSON Schema (draft 2020-12) document instead of Markdown/JSON/TOON. Each column becomes a property carrying its inferred type plus the LLM-written Label and Description. If the description inference also ran, it becomes the schema's top-level description; tags, if generated, land under x-qsv.tags. New in 24.0.0: the description is written as plain prose (#4689). Single-symbol LaTeX spans that some models emit, such as $\times$ or $\approx$, become × and ≈ before any output is written. Markdown-escaped dollars (\$179.73) are kept, since they stop GitHub from rendering the text between two amounts as math, and the viz Data Schematic now displays them as $179.73.

qsv- and LLM-specific metadata that JSON Schema has no native slot for — cardinality, null_count, weighted example counts, semantic Content Type, and the extra stats columns — is preserved under a single x-qsv annotation object per property. Unknown x- keywords are ignored by conforming validators (per the 2020-12 spec), so the schema still validates real data while keeping qsv's richer context for tooling that knows to look.

Two x-qsv hints on a numeric measure drive the viz smart KPI overview row (edit them in the saved schema to fine-tune the dial):

• x-qsv.gauge_range — a [min, max] canonical scale (e.g. [0, 1] for a ratio, [0, 100] for a percent) that renders the measure's KPI tile as a gauge. describegpt --dictionary emits this automatically for measures on a recognizable canonical scale, but only keeps it when the observed data falls within the range, so a mis-scaled range can't draw a misleading dial.
• x-qsv.target — a goal value that adds a "vs target" delta (value − target) to the tile. This is a target you supply, never a fabricated prior-period baseline, so describegpt never emits it — hand-author it in the schema.

Also written here when their inferences run: x-qsv.role / x-qsv.concept (the analytical role and catalog concept that also drive semantic viz smart panel selection and the SemanticMd/OKF dictionaries), and, with --infer-null-values, the null_values / null_candidates sentinel lists.

• x-qsv.unit — a per-field UCUM code for a numeric measure. qsv already carried units piecemeal (x-qsv.currency is the unit for money, x-qsv.denominator.unit for an area denominator) and every other measure had none, so a chart axis read "temperature" rather than "temperature (°C)". viz renders the resolved symbol on the KPI tile, the panel subtitle, hover text and axis titles.

  [!NOTE] UCUM is case-sensitive — m is metre, M is the mega prefix — so the code is matched exactly. The accepted codes are injected into the prompt (unlike ISO currency codes, which a model emits unprompted; UCUM it does not). A code outside the table is silently dropped, not rendered.

• measure.money — a first-class money concept, so a dollar column no longer lands on the generic measure.amount and no longer formats with an SI "G" suffix. For money, the currency is the unit, so a verified x-qsv.currency takes precedence over x-qsv.unit on the same field.
• x-qsv.denominator — derived, not merely accepted: describegpt identifies a measure.population column and emits it as the denominator for the region entries, so a viz smart rate map charts per-capita without the reader ever naming either column.
• x-qsv.denominator.level — the geography the denominator describes (geo.state, geo.county, …), copied from the chosen denominator onto the region entries. Without it, cardinality alone cannot tell a denominator from one measured over a coarser geography — a county extract that joined in state populations would chart county counts over state totals. viz compares this against the region key and refuses a mismatch.
• x-qsv.tour — the guided-tour narration, written when --tour-audience is passed. See the guided Tour.

Two policies, and the rule that separates them. Some annotations qsv accepts on proposal and then verifies; others you must declare and qsv never guesses. The discriminator is whether the annotation changes a number:

# emit a JSON Schema for customers.csv, enriched with LLM labels & descriptions
qsv describegpt customers.csv --dictionary --format jsonschema -o customers.schema.json

# then validate the data against it with qsv's own validator
qsv validate customers.csv customers.schema.json

The jsonschema format requires the dictionary phase (--dictionary or --all); the --prompt chat mode is not supported. Two flags fine-tune the output:

• --allow-extra-cols — emit additionalProperties: true at the schema root (default is false — strict).
• --strict-dates — emit format: date / date-time for Date/DateTime columns. Off by default because qsv's date inference is permissive (it accepts strings like June 27, 1968) while JSON Schema's date formats require RFC 3339 — set it only when your columns are guaranteed RFC 3339. Mirrors the same flag on the schema command.

This pairs naturally with validate — see Recipe: JSON Schema Validation for the validation side.

describegpt --format semanticmd emits the Data Dictionary as a Semantic Markdown document — human-readable markdown with a few lightweight, agent-parseable conventions that a companion converter turns into structured JSON. It's the middle ground between freeform English and a formal schema: a person reads it as a normal markdown report, while an agent gets concrete structural cues.

The document is organized into sections:

• YAML frontmatter — dataset id / title / row_count / grain, an optional temporal_coverage and spatial envelope, a sorted concept index, and --tags (when run). String scalars are quoted when needed so YAML consumers don't re-type them — a 2020-12-23 value stays a string, a source URL stays text.
• # Dataset — the --description result (when run), a ## Grain statement ("one row = …"), and a Resource / Schema / Title table.
• # Schema — a Column / Type / Role / Concept / Join? / Null / Label table (codes wrapped in backticks, required prefix for non-null columns) and a heuristically-inferred Primary key (only when exactly one column is structurally unique — cardinality == rowcount, no nulls). New in 24.0.0: all-unique Float columns no longer count, so a table with an Integer id and an all-unique Float measure now infers id as the primary key; the same exemption applies to the 1:1 join class.
• ## Column subsections — the LLM Description plus bold-key bullets for Concept, Role, Join, and Quality; a ### Validation block (numeric ranges or text length ranges), ### Choices (low-cardinality enumerations), and a rich ### Statistics block (mean, median, quartiles, skewness, inner fences, sparsity).
• # Resource — a ## Statistics table (Column / Min / Max / Cardinality / Null Count) and per-column ### Frequency tables carrying Choice, Frequency, Percentage, and Rank (sourced from qsv's own frequency computation; aggregation buckets like Other… / (NULL)… render with a blank rank).

What makes it agent- & catalog-ready: every column carries a catalog-wide Concept ID (e.g. geo.zip_code, id.surrogate_key) for cross-dataset join discovery, an analytical Role (dimension / measure / identifier / timestamp), join keys with a 1:1 / N:1 cardinality class, and data-quality flags (PII, PII-location, sparse, placeholder-dates). Because Concept, Role, and grain need semantic context, semanticmd implies --infer-content-type.

Three optional flags populate the frontmatter (SemanticMd-only; omitted when unset, ignored by other formats): --ds-source (source / provenance), --ds-updated (last-updated date), and --ds-license (license).

# emit a Semantic Markdown data dictionary, enriched with LLM labels, description & tags
qsv describegpt customers.csv --all --format semanticmd \
  --ds-source "https://data.example.gov/catalog/customers" \
  --ds-updated 2026-01-15 \
  --ds-license "CC-BY-4.0" \
  -o customers-dictionary.md

Like jsonschema, the semanticmd format requires the dictionary phase (--dictionary or --all) and does not support the --prompt chat mode. When the other inference phases run, the --description result becomes the # Dataset description and --tags are embedded in the YAML frontmatter. Rendering goes through a user-overridable MiniJinja template (semanticmd_md_body_template, see --markdown-template below). See nyc311-describegpt-semanticmd.md for a full example.

The emitted document's front matter opens with semantic-md: datadict.yaml, a pointer telling the semantic-md converter which schema turns the markdown into structured JSON. qsv ships that schema at docs/describegpt/datadict.yaml — a semantic-md schema that maps each section of the data dictionary (Dataset, Schema + per-column subsections, Resource statistics, and Frequencies) onto a JSON object. Inline-code cells (`column`, `concept`, `resource` …) are re-extracted so their values are stored without literal backticks.

Run the conversion with the semantic-md Python package, and you get the machine-readable JSON committed alongside the markdown as nyc311-describegpt-semanticmd.json — the same content an agent or data catalog would consume, minus the LLM round-trip:

# pip install semantic-md==0.0.2 mistletoe==1.5.1 jsonpatch==1.33 pyyaml==6.0.3
from semantic_md import convert as smd

front, body = smd.md_parse_front_matter(open("nyc311-describegpt-semanticmd.md").read())
schema = smd.Schema.read(open("datadict.yaml").read())
data = smd.to_json(smd.md_parse_body(body, schema), schema)   # -> the JSON object

A regenerate-and-verify check, check_semanticmd.py (modeled on qsv --generate-help-md), converts the markdown in-process, asserts a few structural invariants, and diffs the result against the committed JSON artifact — so a behavior change in datadict.yaml, the semantic-md package, or the semanticmd template fails loudly instead of drifting unnoticed. Run python3 check_semanticmd.py to verify, or --update to refresh the artifact. The toolchain is fully version-pinned for reproducibility.

Note: datadict.yaml carries a small two-rule workaround for an upstream semantic-md quirk where a {var|md} run reaching end-of-document under-counts consumed tokens by one (dropping qsv's trailing attribution paragraph). The extra trailer rule can be removed once that is fixed upstream.

describegpt --format okf emits the Data Dictionary as an Open Knowledge Format document — Google Cloud's vendor-neutral "knowledge as plain markdown + YAML frontmatter" format. It's a leaner sibling of Semantic Markdown: where semanticmd packs every column with Concept IDs, Roles, join keys, quality flags, and rich statistics for cross-dataset agents, OKF stays deliberately minimal and human-first, matching OKF's spec (a small required core plus arbitrary extensions). It reuses the exact same dictionary-inference pipeline — only the rendering template differs.

The document has two parts:

• YAML frontmatter — the required type key plus OKF's recommended title, description (a single-sentence summary), resource, timestamp, and tags. String scalars are quoted when needed so a 2020-12-31 value stays a string.
• # <title> body — the full --description prose (when run), followed by a # Schema table:

| Column | Type | Content Type | Description | Enumeration |
| --- | --- | --- | --- | --- |
| `Unique Key` | integer | unique_id | A system-generated unique identifier for each record. |  |
| `Status` | text | category | Current status of the complaint. | Assigned<br>Closed<br>…<br>Unspecified |

The columns are Column (name), Type (storage type — integer/number/boolean/timestamp/text), Content Type (the LLM-inferred semantic content type, e.g. unique_id, date:%m/%d/%Y, category), Description (the LLM column description), and Enumeration (low-cardinality choices joined with <br>; blank for high-cardinality columns).

Two frontmatter mappings come from the shared dataset flags: --ds-source populates resource (the asset URI) and --ds-updated populates timestamp. The required type key is set with the OKF-only --okf-type flag (default "CSV Table"; set it to "BigQuery Table", "Snowflake Table", etc. to reflect the real source system).

# emit an OKF data dictionary, enriched with LLM labels, description & tags
qsv describegpt customers.csv --all --format okf \
  --okf-type "BigQuery Table" \
  --ds-source "bq://acme/sales/customers" \
  --ds-updated 2026-01-15 \
  -o customers.okf.md

Like jsonschema and semanticmd, OKF requires the dictionary phase (--dictionary or --all), does not support the --prompt chat mode, and implies --infer-content-type (which populates the Content Type column). When the other phases run, the --description result feeds both the body prose and the single-sentence frontmatter description, and --tags are embedded in the frontmatter. Rendering goes through a user-overridable MiniJinja template (okf_md_body_template, see --markdown-template below). See nyc311-describegpt-okf.md for a full example.

Pass --infer-null-values (with --dictionary/--all) to have the LLM propose each field's null sentinels — the literal tokens (N/A, unknown, -, refused, …) that stand in for a missing value. The results land in each property's x-qsv object in the dictionary, split by qsv — not the model — into two lists:

• null_values — tokens independently confirmed to occur as a literal value in a String column, spelled exactly as found (every observed casing listed).
• null_candidates — everything else the LLM proposed, each stamped confirm_required: true.

A numeric or date placeholder (-999, 9999, 1900-01-01) can only ever be a candidate: it parses as a valid value, so no scan can distinguish it from real data — an LLM is the only thing that can propose one, and a human the only thing that can confirm it. Sentinels are reported, never applied.

This is the complement of denull: denull deterministically detects and (with --apply) blanks sentinels in columns that would promote to a numeric type once cleaned, while --infer-null-values also surfaces sentinels in purely categorical columns (status = ok/pending/NULL) that denull intentionally ignores.

The default prompt templates are in resources/describegpt_defaults.toml. Copy and edit to fit your organization's documentation style — describegpt --prompt-file my-prompts.toml ....

The bundled prompt file carries a version. 22.0.1 bumped it 8.0.0 → 9.0.0: dictionary_prompt now asks for the grain sentence in the target language, plus a new top-level grain_unit string (the bare entity noun), emitted as x-qsv.grain_unit in JSON Schema output.

Pass --context-file <file> to feed the LLM additional context about the dataset — provenance, domain terms, variable/code labels, column conventions, or anything the bare stats can't convey. The context sharpens labels, descriptions, and tags without touching the deterministic symbolic half, and is part of the cache key (keyed on file content), so editing it busts the describegpt cache; an empty (or unset) context file collapses back to the no-context cache key and renders {{ context }} as an empty string.

The file type is sniffed from its contents, not its extension (the same machinery the sniff command uses), and is handled two ways depending on what it is:

• Text-extractable — plain text, Markdown, CSV, and Excel/ODS spreadsheets (the latter extracted to CSV) are inlined into the rendered prompts via the {{ context }} template variable.
• Multimodal attachment — PDF and image files (JPEG/PNG/WebP/GIF) are base64-encoded and sent to the LLM as a multimodal content block. This needs a multimodal-capable model and endpoint (e.g. a vision/PDF-aware model); plain text-only models will reject or ignore it.

By default the context is injected into the user message, but a custom prompt-file template may reference {{ context }} anywhere to place it explicitly. Word/PowerPoint (.docx/.pptx) are not supported — convert them to PDF or text first. The whole attachment is capped at ~32 MB (the OpenAI per-request ceiling).

# Markdown notes inlined as {{ context }}
qsv describegpt sensor_readings.csv --all \
  --context-file dataset-notes.md \
  -u http://localhost:11434/v1 --model deepseek-r1:14b

# a PDF data dictionary / codebook sent as a multimodal attachment
qsv describegpt sensor_readings.csv --all \
  --context-file codebook.pdf \
  -u https://api.openai.com/v1 -m gpt-4o -k "$OPENAI_API_KEY"

Declare the columns you added. If you enriched the extract before describing it (a lookup, a join, a computed field), say so in the context file. Otherwise the gaps in those columns read as defects of the source data. Documented in the --context-file help since 24.0.0 #4690: on a CMS Open Payments extract with a ZIP→county lookup, the description reported its 57 blank counties as "geographic data is incomplete". With this one line added, gemma-4-31b called them "Enrichment Gaps … not missing from the original CMS source" in 2 of 2 runs:

- County_FIPS / County_Name are NOT part of the CMS file. They were added afterwards by looking up
  each ZIP code in the Census 2020 ZCTA-to-county relationship file. A blank county means that ZIP
  had no county match; it is a gap in that enrichment step, not missing CMS data.

Pass --infer-content-type and describegpt asks the LLM to tag each column with a semantic Content Type from a curated 49-token vocabulary that covers people (first_name, last_name, full_name, job_title, …), addresses (building_number, street_name, street_address, city, state, state_abbr, zip_code, country, country_code, …), contact info (email, phone, username), technical identifiers (ip_address, ipv6_address, mac_address, uuid, url), payment (credit_card, currency_code, isbn), and more (industry, profession, license_plate, …). The full token list and the faker each token maps to lives in src/cmd/synthesize/faker_map.rs.

A Content Type column is appended to the emitted Data Dictionary. Those tags drive synthesize's realistic-fake generation but they're also useful on their own as auto-generated documentation.

Deterministic unique_id. Columns whose cardinality equals their row count (primary keys, surrogate keys, UUIDs, sequence numbers) are tagged unique_id directly by qsv, before the LLM ever sees them — so the label is 100 % reproducible and doesn't drift between LLM versions. New in 24.0.0: Float columns are exempt: a continuous measurement at full precision (a price, a duration, a coordinate) is all-unique as a matter of course, so it gets its content type, role and concept from the LLM like any other field — which still cannot assign unique_id itself (#4653).

qsv describegpt customers.csv --dictionary --infer-content-type --format JSON -o customers.dict.json

A first-pass LLM call sees each column in isolation, which means it can mislabel "this is a 2-letter string column" without realizing the next column is a zip_code (making the first one a state_abbr). Pass --two-pass and describegpt runs a second LLM call that takes the whole first-pass Data Dictionary as JSON context, then refines each field's Label, Description, and (when --infer-content-type is set) Content Type with cross-field awareness. Roughly doubles dictionary LLM cost — opt in when accuracy matters more than throughput.

This is also the option that unlocks cross-column consistency in synthesize (a synthetic state_abbr will be a real US state abbreviation matched to the row's zip_code).

qsv describegpt customers.csv --all --two-pass --infer-content-type \
  -u http://localhost:11434/v1 --model deepseek-r1:14b

Override the Markdown layout that describegpt emits with a TOML file of MiniJinja templates. Six optional template fields — dictionary_md_template, description_md_template, tags_md_template, custom_prompt_md_template, the per-field dictionary_md_body_template that fills the dictionary wrapper's {{ llm_response }}, and semanticmd_md_body_template (the whole --format semanticmd document, added in 20.2.0). Any omitted field falls back to the embedded default, so a minimal TOML can override just the one template you want to change. Custom Jinja filters (pipe_escape, br_replace, human_count, dict_cell, humanize_examples) are pre-registered and documented inline in resources/describegpt_md_defaults.toml.

qsv describegpt customers.csv --all --markdown-template team-style.toml > customers-dictionary.md

The default description and tags prompts now inline {{ dictionary }} directly into the system prompt instead of re-sending the dictionary as a separate chat message. Measurably cuts token usage on multi-phase (--all) runs.

See also: /docs/help/describegpt.md, docs/Describegpt.md, Output gallery, Stats Cache & Caching, SQL & Polars, Claude Cowork Plugin, MCP Server, Cookbook → Stats → Insights, Cookbook → Synthesize Fake Data.

New in 20.1.0. Generate a statistically-faithful synthetic CSV from a real one — same value mix, same distribution shape, same null rate — without any of the original records. Useful for sharing test data, populating staging environments, building demos, and benchmarking pipelines without leaking real customer data.

synthesize runs stats and frequency against the source under the hood, then emits N rows that reproduce per-column attributes:

• Categorical / low-cardinality columns are rebuilt by frequency-weighted sampling of the real value set — cardinality, weights, and repetition structure preserved exactly.
• Numeric and date/datetime columns are reproduced with quartile buckets, so the shape of the distribution (not just min/max) is preserved.
• Null ratios are matched per column.
• Unstructured text columns that carry string-length stats (min/max/avg/stddev) get values truncated to the source's character-length distribution.

Layer in a Data Dictionary from describegpt --dictionary --infer-content-type --format JSON and each column's Content Type picks a realistic fake-rs faker — email, phone, street_address, uuid, etc. — for non-enumerable columns. --locale picks from 14 fake-rs locales (en, fr_fr, de_de, it_it, pt_br, pt_pt, ja_jp, zh_cn, zh_tw, ar_sa, cy_gb, fa_ir, nl_nl, tr_tr).

Example: pure statistical synthesis — no LLM needed

qsv synthesize data.csv -n 1000 --seed 42 > synthetic.csv

The --seed flag makes the output fully reproducible — same seed, same file, every time.

Example: realistic fakes via a Content-Type-tagged dictionary

# 1. Build the dictionary once (local LLM keeps the data on-device)
qsv describegpt customers.csv --dictionary --infer-content-type --format JSON \
  -u http://localhost:11434/v1 --model deepseek-r1:14b -o customers.dict.json

# 2. Synthesize 10,000 rows that mirror customers.csv's shape, with realistic fakes
qsv synthesize customers.csv --dictionary customers.dict.json \
  --locale en --seed 42 -n 10000 > customers-fake.csv

Example: one-shot — let synthesize build the dictionary itself

qsv synthesize data.csv --infer-content-type --seed 42 -n 5000 > synthetic.csv

Requires an LLM API key in QSV_LLM_APIKEY (or -u <local-endpoint> for a local LLM).

Example: stable source → fake mapping (--consistent-fakes)

qsv synthesize customers.csv --dictionary customers.dict.json \
  --consistent-fakes --seed 42 -n 10000 > customers-fake.csv

For structured-faker columns with bounded cardinality, the same source value always produces the same fake — useful for deidentified synthesis where you want stable joins on the faked columns.

See also: /docs/help/synthesize.md, describegpt Content Types, Cookbook → Synthesize Fake Data, Stats Cache & Caching, src/cmd/synthesize/faker_map.rs — Content Type → faker mapping.

New in 21.1.0. A new apply subcommand that condenses a text column (or group of columns) into a new column using an OpenAI-compatible LLM — one HTTP call per row. Handy for distilling long free-text fields (support tickets, notes, abstracts, reviews) into short summaries you can scan, filter, or feed downstream.

Unlike the CPU-bound, Rayon-parallel apply subcommands, summarize is network-bound and sequential. The prompt is a MiniJinja template rendered per record — reference any column by its "safe" name (non-alphanumeric chars become _), with the 1-based row number available as {{QSV_ROWNO}}. If you omit --prompt/--prompt-file, a default prompt that summarizes the selected column/s is used.

The endpoint, model, and API key resolve with the precedence CLI flag > env var (QSV_LLM_BASE_URL / QSV_LLM_MODEL / QSV_LLM_APIKEY) > built-in default (default base URL http://localhost:1234/v1, default model openai/gpt-oss-20b) — the same conventions as synthesize and describegpt. An API key is required for non-localhost URLs (set --api-key NONE to suppress sending one).

Results are cached on disk (keyed by base-url, model, max-tokens, addl-props, and the rendered prompt) so repeated rows and re-runs don't re-pay for inference — --no-cache disables it, --fresh forces fresh calls that refresh the cache.

Example: summarize a column with a local LLM

qsv apply summarize support_ticket -c summary file.csv

Example: custom prompt across multiple columns, against a cloud provider

qsv apply summarize subject,body -c summary \
  --prompt 'Summarize: {{subject}} - {{body}}' \
  -u https://api.openai.com/v1 -m gpt-4o-mini -k "$OPENAI_API_KEY" file.csv

Example: also capture per-row inference time & token usage

qsv apply summarize notes -c summary --stats file.csv

See also: apply, /docs/help/apply.md, describegpt.

New in 24.0.0: every command describes itself (#4638). Agents and pipelines get the same truth humans do, straight from the binary they will run.

qsv stats --help --format json     # the command's JSON tool definition (same schema as the MCP skills)
qsv stats --help --format md       # its help Markdown, as in docs/help/
qsv --export-tool-definitions defs/  # both, for every installed command, plus manifest.json

• The definitions are generated by the binary from its own usage text, so they always match the installed version and feature set — including commands outside the MCP skill set.
• manifest.json records the qsv version, the binary name, its installed commands and which of them are in the MCP skill set.
• Available in qsv and qsvmcp; neither needs the mcp feature, so the prebuilt qsv has both.
• Worked example — gating a pipeline on manifest.json and reading definitions with jq: Integrations → Agents & pipelines.

• Command Reference (index)
• Claude Cowork Plugin — qsv as 15 skills + 3 agents for Claude Code
• MCP Server — qsv as a Model Context Protocol server
• qsv pro Spotlight — desktop GUI companion
• docs/Describegpt.md
• Transform & Reshape → apply — home of the summarize LLM subcommand
• SQL & Polars — describegpt SQL-RAG runs through sqlp / DuckDB
• Stats Cache & Caching — what powers describegpt's and synthesize's symbolic half
• Cookbook → Stats → Insights
• Cookbook → Synthesize Fake Data
• External Resources — "Have we achieved ACI?" blog series