matcha-core 0.1.3

Analyze repositories against SPECS.md and generate implementation reports.

Matcha Core

matcha-core analyzes a repository against its SPECS.md and produces structured implementation reports.

It can be used in three ways:

• as an installable CLI
• as a Python library

Install

From PyPI:

python3 -m pip install matcha-core

For local development:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev]"

CLI

OpenAI:

export OPENAI_API_KEY=...
matcha-core analyze /path/to/repo --output ./report.html

Ollama:

export OLLAMA_MODEL=llama3.2
matcha-core analyze /path/to/repo --provider ollama

If the specs file is not at the repo root:

matcha-core analyze /path/to/repo --specs /path/to/repo/docs/SPECS.md

To analyze only one feature:

matcha-core analyze /path/to/repo --feature FEAT-004 --output report.html

matcha-core infers the report format from --output when possible, so report.html, report.json, and report.md automatically render the expected format. If no format is specified and no output file is provided, the CLI defaults to a terminal table view. You can also use --reporter as an alias for --format.

Library

from matcha_core import OpenAICompatibleEvaluator, RepositoryAnalyzer
from matcha_core.reporting import report_to_html

evaluator = OpenAICompatibleEvaluator.from_env(provider="openai")
analyzer = RepositoryAnalyzer(evaluator=evaluator)
report = analyzer.analyze_path("/path/to/repo")

html = report_to_html(report)

Output formats

• json
• markdown
• html
• table

For terminal output with evidence snippets:

matcha-core analyze /path/to/repo --format table --show-evidence

Tests

python3 -m unittest discover -s tests

Specs Authoring

Use docs/SPECS_TEMPLATE.md as a starting point when onboarding an existing repository into Matcha.

Release

The package metadata and release flow are documented in RELEASING.md.

License

This project is licensed under the Apache License 2.0. See LICENSE.