Metadata-Version: 2.4
Name: matcha-core
Version: 0.1.3
Summary: Analyze repositories against SPECS.md and generate implementation reports.
Author: Patominer
License-Expression: Apache-2.0
Keywords: specs,analysis,llm,qa,repository
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gitpython>=3.1.41
Requires-Dist: openai>=2.15.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/TheFreeRangeTester/matcha-core/main/assets/branding/matcha-logo.png" alt="Matcha logo" width="180">
</p>

# 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:

```bash
python3 -m pip install matcha-core
```

For local development:

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

## CLI

OpenAI:

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

Ollama:

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

If the specs file is not at the repo root:

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

To analyze only one feature:

```bash
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

```python
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:

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

## Tests

```bash
python3 -m unittest discover -s tests
```

## Specs Authoring

Use [docs/SPECS_TEMPLATE.md](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`.
