Find guidelines

Find guidance for a chart question with catalog filters, section text search, SQL joins, or indexed discovery. Use the CLI for inspection, Python for dataframe work, and TypeScript when an app needs loaded guidance. Candidate results provide ids for read and cite so answers can name the guidance and sources they use.

Candidate guidelines

Start with a label when the chart type or design task is known:

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 citations for pasted answers. Python returns citation records for agents and notebooks. TypeScript loads guidance and public URLs so apps can send users to the cited guideline.

Filter section text

Filter 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 discovery

Use SQL when the question spans tables. This query ranks paper authors by the number of distinct guidelines that cite their academically published sources:

uvx chartcoach@latest catalog sql "
with paper_sources as (
  select
    gr.guideline_id,
    r.id as reference_id,
    unnest(r.authors) as author
  from guideline_references gr
  join \"references\" r on r.id = gr.reference_id
  where r.authors is not null
    and r.source_type in ('article', 'inproceedings', 'incollection')
)
select
  author,
  count(distinct guideline_id) as guideline_count,
  count(distinct reference_id) as source_count
from paper_sources
group by author
order by guideline_count desc, source_count desc, author
limit 5
" --format jsonl

import chartcoach

catalog = chartcoach.open().catalog
conn = catalog.duckdb()
try:
    rows = conn.sql("""
        with paper_sources as (
          select
            gr.guideline_id,
            r.id as reference_id,
            unnest(r.authors) as author
          from guideline_references gr
          join "references" r on r.id = gr.reference_id
          where r.authors is not null
            and r.source_type in ('article', 'inproceedings', 'incollection')
        )
        select
          author,
          count(distinct guideline_id) as guideline_count,
          count(distinct reference_id) as source_count
        from paper_sources
        group by author
        order by guideline_count desc, source_count desc, author
        limit 5
    """).pl()
finally:
    conn.close()

The source_type predicate limits the join to academically published source references: journal articles, conference papers, and book chapters. Adjust that predicate when a query should compare a broader evidence set such as standards, practitioner posts, preprints, or every catalog source reference. The result has author, guideline_count, and source_count columns. Author names are counted as stored in the source references.

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. Python callers can use chartcoach.open().search(...) to resolve and search that index without hardcoding the cache path. TypeScript apps should use loadCatalog() when a page or answer needs to show the same guidance and link to its public source. The Cataloging scheme lists tables, columns, catalog sources, and manifest vocabulary.