Metadata-Version: 2.4
Name: chartcoach
Version: 0.3.0
Summary: Python package and CLI for the chartcoach visualization guideline catalog.
Keywords: data-visualization,guidelines,retrieval,visualization
Author: Péter Ferenc Gyarmati
Author-email: Péter Ferenc Gyarmati <dev.petergy@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Dist: agent-plugins>=0.2
Requires-Dist: refkit>=0.3.0
Requires-Dist: polars-refkit>=0.3.0
Requires-Dist: click>=8.3.3
Requires-Dist: duckdb>=1.5.5
Requires-Dist: platformdirs>=4
Requires-Dist: polars>=1.39.0
Requires-Dist: pyyaml>=6
Requires-Dist: tabulate>=0.10.0
Requires-Dist: typing-extensions>=4.6.0
Requires-Dist: obstore>=0.11.0 ; extra == 'cloud'
Requires-Dist: chartcoach[index,cloud] ; extra == 'curation'
Requires-Dist: numpy>=1.24 ; extra == 'curation'
Requires-Dist: obspec>=0.1.0 ; extra == 'curation'
Requires-Dist: lancedb>=0.38.0 ; extra == 'index'
Requires-Dist: pyarrow>=23.0.1 ; extra == 'index'
Requires-Dist: mcp>=2.0 ; extra == 'mcp'
Requires-Dist: pydantic>=2.12 ; extra == 'mcp'
Requires-Dist: numpy>=1.24 ; extra == 'projection'
Requires-Dist: umap-learn>=0.5.12 ; extra == 'projection'
Requires-Python: >=3.10, <3.15
Project-URL: Repository, https://github.com/chartcoach/chartcoach
Project-URL: Issues, https://github.com/chartcoach/chartcoach/issues
Provides-Extra: cloud
Provides-Extra: curation
Provides-Extra: index
Provides-Extra: mcp
Provides-Extra: projection
Description-Content-Type: text/markdown

# chartcoach

The `chartcoach` Python package opens a Guideline Catalog from local files or a
published release. It provides guideline entries plus Polars and
DuckDB tables for sections, labels, and references.

chartcoach is alpha software. Installing the package also installs the
`chartcoach` CLI.

## Read one guideline

```bash
uv add chartcoach
```

```python
from chartcoach import open_catalog

catalog = open_catalog()
record = catalog.read(
    ids=["directly-label-series-instead-of-using-a-color-key"],
    source_detail="minimal",
)[0]
print(record["title"])
```

Expected output:

```text
Directly label colored series instead of relying on a color key
```

This call downloads the catalog files over HTTPS, verifies the byte counts and
SHA-256 hashes listed by the release, and caches the verified files.

## Choose a catalog location

`open_catalog(location)` accepts:

| Location                   | Behavior                                            |
| -------------------------- | --------------------------------------------------- |
| Authored folder            | Reads `MANIFEST.md` and `entries/<id>/guideline.md` |
| Compiled bundle            | Reads `MANIFEST.md` and `entries.parquet`           |
| Local deployed root        | Opens the release selected by its `catalog.json`    |
| Local release directory    | Reads its `release.json` and verifies listed files  |
| `catalog.json` path or URL | Follows the currently selected release              |
| `release.json` path or URL | Keeps one release digest across calls               |
| Omitted                    | Opens the official selected catalog                 |

Install `chartcoach[cloud]` for S3, GCS, or Azure locations.

## Query catalog tables

`catalog.to_frame()` returns the six stored fields for each guideline.
`catalog.table(name)` returns `guidelines`, `sections`, `guideline_labels`,
`references`, `guideline_references`, or `guideline_sources` as a query-ready
Polars dataframe. Tables are derived on first use and reused within the
`Catalog`. Each call returns an independent dataframe handle that callers can
transform or mutate while the cached tables stay unchanged.
`catalog.duckdb()` registers those six catalog tables in an in-memory DuckDB
connection owned by the caller. Reuse it for related queries and close it after
use.

## Search an index

Install `chartcoach[index]` to open a named LanceDB index stored with a catalog
release. The following template requires a release that publishes the named
profile:

```python
from chartcoach import open_catalog

catalog = open_catalog("dist/release-indexed")
table = catalog.index("minilm-normalized")
hits = (
    table.search("direct labels", query_type="fts", fts_columns="text")
    .select(["id", "parent_id", "role", "_score"])
    .limit(5)
    .to_list()
)
ids = list(dict.fromkeys(hit["parent_id"] for hit in hits))
records = catalog.read(ids=ids)
```

`catalog.index()` returns the release's LanceDB `documents` table from a
protected shared extraction. Pass a new `directory=Path(...)` for a
caller-owned writable copy. A missing profile raises `CatalogError` and lists
the available names. Profile IDs are flat lowercase release handles. Inspect
`catalog.describe(profile=...)` for the embedding binding, dimensions,
`distance_metric`, and `python_requirements`.
Explicit full-text search keeps embedding providers idle. Project the fields
needed for candidate selection, then read the parent entries' context and
exceptions before applying their advice.

## Compose verified release files

```python
entries = catalog.artifact("entries.parquet")
with catalog.duckdb() as connection:
    rows = connection.read_parquet(str(entries)).select("id, title").limit(5).fetchall()

local = catalog.cache()
offline = open_catalog(local)
```

`catalog.release.artifacts` lists available files, including optional document
and projection Parquet exports. `artifact(path)` verifies and caches the file
before returning a local path. `cache()` materializes every release file into
a directory that opens offline. Remote artifacts and digest-addressed
descriptors use the per-user [platformdirs](https://platformdirs.readthedocs.io/)
cache. Selected catalogs refresh `catalog.json` on each open.

For S3, pass your descriptor URI and the storage client's options to
`open_catalog(location, storage_options=...)` with `chartcoach[cloud]` installed.
See [Open and cache catalogs](https://docs.chartcoach.dev/catalogs).
Use native DuckDB connections and LanceDB tables for SQL, filtering, reranking,
batch search, and exports. Index `parent_id` values identify guideline entries.

## Use chartcoach from a code-mode agent

chartcoach follows the open
[Agent Plugins specification](https://agent-plugins.org/). The installed Python
distribution carries its version-matched Agent Skills and Model Context
Protocol server configuration. A code-mode agent can inspect those components
and call the chartcoach Python API directly:

```python
import chartcoach.agent as cc

help(cc)
catalog = cc.open_catalog()
candidates = catalog.query(contains="labels", limit=5)
selected_ids = candidates.get_column("id").head(3).to_list()
records = catalog.read(ids=selected_ids, source_detail="minimal")
citations = catalog.cite(ids=selected_ids)
core = cc.agent_plugin().skill("core")
print(core.source)
```

`cc.agent_plugin()` returns an `agent_plugins.Plugin` object.
Use `cc.agent_plugin().skill(name)` for direct lookup and `skill.file(path)`
for a checked packaged resource.

`contains` matches a contiguous phrase in the ID, title, or description.
The `core` skill teaches query recovery, index and SQL selection, and compact
results. Load the matching workflow skill for chart review, recommendation,
discussion, or contribution.

The Agent Plugin also declares the packaged MCP stdio entry through
`cc.agent_plugin().mcp`. Install `chartcoach[mcp]` in the agent client's Python
environment before it starts that server. Agents can inspect the complete
module workflow with `help(cc)`.

[marimo](https://docs.marimo.io/) is one environment for code-mode agents. It
discovers `chartcoach.agent` through the installed `marimo.agent.capability`
entry point.

## Documentation

| Page                                                       | Details                                             |
| ---------------------------------------------------------- | --------------------------------------------------- |
| [Python](https://docs.chartcoach.dev/python)               | Catalog methods plus Polars, DuckDB, and LanceDB    |
| [Catalog CLI](https://docs.chartcoach.dev/cli)             | Terminal commands, JSON output, and exit codes      |
| [MCP server](https://docs.chartcoach.dev/mcp)              | SQL and search tools for MCP clients                |
| [Curate and publish](https://docs.chartcoach.dev/curation) | Authoring, build, publication, and public selection |

chartcoach is licensed under [Apache-2.0](LICENSE).
