Use with agents

Use the Python API when your agent can run code. Use the Model Context Protocol (MCP) server when its client expects tools. Both let the agent find candidates, read the guidance, and cite the sources it uses.

For a browser interface backed by the same catalog, follow Build a web app. The chat app connects interactive guideline selection to server-side search, guideline reading, and cited feedback.

Call the Catalog API

uv add chartcoach

import chartcoach.agent as cc

help(cc)
catalog = cc.open_catalog()
description = catalog.describe()
candidates = catalog.query(contains="labels", limit=5).to_dicts()

selected_ids = [row["id"] for row in candidates[:3]]
records = catalog.read(ids=selected_ids, source_detail="minimal")
citations = catalog.cite(ids=selected_ids)

catalog.query() keeps candidate rows compact. catalog.read() returns the complete selected sections. Pass source_detail="full" when the task needs every parsed source field and the entry's BibTeX references.

contains matches a contiguous phrase in the ID, title, or description. For zero matches, shorten the phrase or follow Find guidelines to search section text or an available index. Batch selected IDs through read and cite. Project native LanceDB hits before printing them, then read the parent guidelines for evidence.

Use one catalog object for a task. Its reads, SQL, descriptions, and lazy index loads retain the release selected during open_catalog().

Inspect packaged agent resources

chartcoach follows the open Agent Plugins specification. The installed distribution carries five skills and its MCP server declaration.

plugin = cc.agent_plugin()
core = plugin.skill("core")

print(plugin.tree())
print(core.source)
print(core.file("SKILL.md"))

if plugin.mcp is not None:
    print(plugin.mcp.servers)

Load core plus the skill for the task. core owns query semantics, zero-result recovery, compact output, and citation. The workflow skills connect the retrieved evidence to the chart, design brief, or decision. Inspect vocabulary and schemas when a query needs them, then reuse that discovery.

marimo discovers chartcoach.agent through the installed marimo.agent.capability entry point. Other hosts can import the same module or inspect the Agent Plugin directory.

Use the terminal workflow

uv tool install chartcoach
chartcoach skills get core --full > chartcoach-core.md

Discover, read, and cite from the public catalog:

chartcoach catalog describe
chartcoach catalog list \
  --contains "direct labels" \
  --limit 5

GUIDELINE_ID="directly-label-series-instead-of-using-a-color-key"
chartcoach catalog read "$GUIDELINE_ID" \
  --source-detail minimal \
  --format markdown
chartcoach catalog cite "$GUIDELINE_ID" \
  --format markdown

Set CHARTCOACH_SOURCE to an exact release location when multiple commands must use the same catalog contents.

Candidate search output is a preview. Apply a recommendation after reading the selected record's applicable situations and exceptions. Check its chart family, reader task, audience, data type, and interaction state.

For a chart review, distinguish observed facts from inferred or unreadable details before searching. A matching guideline cannot confirm an uncertain reading of the chart. State the missing evidence when a conclusion requires another view, the data, or an interaction test. cite identifies attached sources. Inspect a publication before attributing a specific claim to it.