Querying

Start with a catalog question. Use the CLI for inspection, Python for dataframe work, and TypeScript when an app needs loaded guideline records. Candidate rows provide ids for later read and cite calls.

Candidate rows

Find guideline ids from a chart-decision label:

uvx chartcoach@latest catalog query \
  --label chart:bar:use \
  --limit 5 \
  --format jsonl

Vocabulary filters

List available values before hard-coding a label, label family, or section role:

uvx chartcoach@latest catalog values labels --contains chart: --format jsonl
uvx chartcoach@latest catalog values roles --format jsonl

chart:bar:use finds guidelines that recommend bar charts.

uvx chartcoach@latest catalog query \
  --label chart:bar:use \
  --limit 5 \
  --format jsonl

In Python, use catalog.guideline_labels() and catalog.sections(). In TypeScript, use catalog.labels() and catalog.sectionRoles().

Read and cite

Use exact ids for final text and citations.

uvx chartcoach@latest catalog read compare-percentages-with-bars-not-pies \
  --source-detail minimal \
  --format json

uvx chartcoach@latest catalog cite compare-percentages-with-bars-not-pies \
  --format json

The CLI prints formatted citation output. Python exposes structured citation records. TypeScript exposes guideline records and ids for application links.

Search section text

Search section text when titles and descriptions are too narrow:

uvx chartcoach@latest catalog query \
  --section-contains "small differences" \
  --show-matches \
  --limit 5 \
  --format jsonl

SQL joins and indexed search

Use SQL when the question spans tables:

uvx chartcoach@latest catalog sql "
select g.id, g.title, s.role, s.content
from guidelines g
join sections s on s.guideline_id = g.id
where list_contains(g.labels, 'chart:bar:use')
  and s.role = 'advice'
limit 5
" --format jsonl

from chartcoach import Catalog

catalog = Catalog.open()
conn = catalog.duckdb()
try:
    rows = conn.sql("""
        select g.id, g.title, s.role, s.content
        from guidelines g
        join sections s on s.guideline_id = g.id
        where list_contains(g.labels, 'chart:bar:use')
          and s.role = 'advice'
        limit 5
    """).pl()
finally:
    conn.close()

Use indexed discovery when keyword filters miss plausible guidelines:

uvx --from 'chartcoach[index]@latest' chartcoach catalog find \
  --mode fts \
  --limit 5 \
  --format compact \
  "overplotted scatter plot with too many points"

The first indexed command downloads and extracts the package-pinned index. For Python indexed search, use default_index_path() with chartcoach.search.open(). For TypeScript joins, use the nested records returned by loadCatalog(). The Cataloging scheme lists tables, columns, source locators, and manifest vocabulary.