Metadata-Version: 2.4
Name: eigenhelm
Version: 0.5.0
Summary: Software Poet Conscience — language-agnostic code aesthetic evaluation
Author: Matthew Davidson
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/metacogdev/eigenhelm
Project-URL: Repository, https://github.com/metacogdev/eigenhelm
Project-URL: Issues, https://github.com/metacogdev/eigenhelm/issues
Keywords: code quality,aesthetics,pca,static analysis,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: tree-sitter>=0.25.0
Requires-Dist: tree-sitter-language-pack>=0.8.0
Requires-Dist: lizard>=1.21.2
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.12
Provides-Extra: serve
Requires-Dist: fastapi>=0.110; extra == "serve"
Requires-Dist: uvicorn[standard]>=0.29; extra == "serve"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# eigenhelm

**A conscience for agents, not an agent** — language-agnostic code aesthetic evaluation sidecar.

Eigenhelm scores agent-generated code against mathematical aesthetic metrics derived from
information theory, complexity science, and a PCA eigenspace trained on curated elite
corpora. It runs alongside code-generating agents as a real-time quality signal.

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)

---

## Quick Start

### Install

```bash
uv tool install eigenhelm
```

For the HTTP server:

```bash
uv tool install "eigenhelm[serve]"
```

### Evaluate a file

```bash
eh evaluate path/to/file.py --model models/demo-python-v0.npz
```

### Run the scoring server

```bash
eh serve --model models/demo-python-v0.npz --host 0.0.0.0 --port 8080
```

### API example

```bash
curl -X POST http://localhost:8080/evaluate \
  -H "Content-Type: application/json" \
  -d '{"source": "def add(a, b):\n    return a + b\n", "language": "python"}'
```

---

## CLI Reference

All commands are available as `eigenhelm <command>` or `eh <command>`:

| Command | Description |
|---------|-------------|
| `eh evaluate` | Evaluate source files against an eigenspace model |
| `eh train` | Train a new eigenspace model from a corpus directory |
| `eh inspect` | Inspect a saved model's metadata |
| `eh serve` | Run the evaluation HTTP server |
| `eh harness` | Run a statistical comparison harness across two code sets |
| `eh corpus` | Manage training corpora (sync from manifest) |

Run `eh --help` or `eh <command> --help` for details.

---

## HTTP API

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Liveness probe |
| `/evaluate` | POST | Evaluate a code unit |
| `/evaluate/batch` | POST | Evaluate multiple code units |

---

## Supported Languages

| Language | Extension |
|----------|-----------|
| Python | `.py` |
| JavaScript | `.js` |
| TypeScript | `.ts` |
| Go | `.go` |
| Rust | `.rs` |
| Java | `.java` |
| C | `.c` |
| C++ | `.cpp` |
| Ruby | `.rb` |
| Swift | `.swift` |

---

## Models

The bundled `models/demo-python-v0.npz` is a small demo model so you can run the full
pipeline without a hosted account. Production-grade models trained on curated elite corpora
are available via the hosted service or as a paid download.

---

## Development Setup

```bash
git clone https://github.com/metacogdev/eigenhelm.git
cd eigenhelm

# Install with dev and serve dependencies
uv sync --extra dev --extra serve

# Run tests
uv run pytest

# Lint
uv run ruff check .
```

---

## Architecture

```
eigenhelm/
├── virtue_extractor.py   — Tree-sitter + Lizard → FeatureVector (69 dimensions)
├── critic/               — AestheticCritic: Birkhoff, entropy, compression metrics
├── eigenspace.py         — EigenspaceModel: PCA projection, drift scoring
├── training/             — train_eigenspace(), save_model(), inspect_model()
├── helm.py               — DynamicHelm: PID-controlled inference steering
└── serve.py              — FastAPI HTTP evaluation server
```

---

## Current Status

- **5-dim scoring**: manifold drift, alignment, entropy, compression, NCD exemplar distance
- **5 languages**: Python, JavaScript, TypeScript, Go, Rust — all discriminating (Cohen's d > 0.5)
- **Human correlation**: Spearman rho = 0.56 (p < 0.0001, n = 52)
- **Calibrated thresholds**: Models store empirical score distribution; accept/reject boundaries derived from training corpus percentiles (p25/p75)

---

## License

eigenhelm is licensed under the [GNU Affero General Public License v3.0](LICENSE).

### Commercial Licensing

Looking to use eigenhelm in a proprietary SaaS or enterprise product without AGPL-3.0
obligations? A commercial license is available.

Contact us at **licensing@eigenhelm.sh** to discuss terms.
