Find guidelines

Choose a retrieval path from what you know about the chart. Each path returns candidate guideline IDs. Read the selected guidelines before using their advice.

Open the catalog

Complete Getting started for your interface. Run each Python example as its own .py script and each TypeScript example as its own .mts script with Node.js.

from chartcoach import open_catalog

catalog = open_catalog()
print(catalog.describe())

The description includes table schemas, vocabulary, and available index profiles. For another source, follow Open and cache catalogs.

Filter candidates

Find recommendations about labels that also address quality:

from chartcoach import open_catalog

catalog = open_catalog()
candidates = catalog.query(
    labels=["purpose:refine"],
    label_prefixes=["quality:"],
    contains="label",
    limit=10,
)
print(candidates)

Every filter must match. contains matches one contiguous phrase in the ID, title, or description. Matching ignores case and treats whitespace, hyphens, and underscores as equivalent separators. Inspect the catalog vocabulary before choosing unfamiliar labels.

If nothing matches, shorten the phrase or relax filters. Search labels and overlap separately when those concepts need not appear together. Section text can match even when a title or description does not.

Query section text and relationships with SQL

DuckDB queries the catalog's related tables. This query finds the word “label” in section text and returns up to ten guideline IDs and titles in ID order. It works with unindexed catalogs too.

from chartcoach import open_catalog

catalog = open_catalog()
with catalog.duckdb() as connection:
    rows = connection.sql("""
        SELECT DISTINCT g.id, g.title
        FROM guidelines g
        JOIN sections s ON s.guideline_id = g.id
        WHERE s.content ILIKE '%label%'
        ORDER BY g.id
        LIMIT 10
    """).fetchall()
    print(rows)

Use the same table relationships for source authors, publication years, labels, and section roles. Catalog data describes the tables.

Search guideline text

An index profile contains search documents derived from the guidelines. Set CATALOG_SOURCE to an indexed release descriptor and PROFILE to one of its profile names. Each example opens that release before searching. A release with an empty profiles list needs an index built before it can support this search.

Full-text search matches words in the stored text index and needs no embedding credentials. These examples retrieve five document hits with LanceDB, the index's database engine:

uv pip install "chartcoach[index]"

import os
from chartcoach import open_catalog

catalog = open_catalog(os.environ["CATALOG_SOURCE"])
table = catalog.index(os.environ["PROFILE"])
hits = table.search(
    "direct labels", query_type="fts", fts_columns="text"
).select(["id", "parent_id", "role"]).limit(5).to_list()
print(hits)

The first search downloads and verifies the index, then caches its extracted files. The shared read-only extraction requires POSIX permissions. On Windows, use a caller-owned extraction directory through the Python or Node API.

Each hit's parent_id identifies the guideline to read. Several hits can share one parent, so five documents may yield fewer than five guidelines. Deduplicate parent IDs in ranked order. A query restricted to role = 'overview' can broaden candidates, while role = 'section.advice' targets advice sections.

Search by meaning

Vector search compares a query embedding with stored vectors. Hybrid search combines that similarity with full-text matches. The query model, vector dimensions, and distance metric must match the selected profile.

Retrieval scores rank results within one query, mode, and profile. They do not measure whether a guideline applies to the chart.

Read and cite selected guidance

This example opens the public catalog, reads one complete guideline, and retrieves its guideline link and formatted source citations. For your own search results, use their catalog source and replace the example ID with selected candidate IDs.

from chartcoach import open_catalog

catalog = open_catalog()
ids = ["directly-label-series-instead-of-using-a-color-key"]
records = catalog.read(ids=ids)
citations = catalog.cite(ids=ids)
print(records)
print(citations)

Batch selected IDs in one read and one citation call. Read the advice, applicable situations, and exceptions before applying a recommendation. A citation identifies an attached source. Inspect the publication before attributing a specific claim to it.