eigenhelm 0.1.0__py3-none-any.whl

eigenhelm/__init__.py

@@ -0,0 +1,29 @@
+"""Eigenhelm — Software Poet Conscience.
+
+Stage 1: IVirtueExtractor
+Language-agnostic code metric extraction producing 69-dimensional feature vectors.
+"""
+
+from eigenhelm.models import (
+    CodeUnit,
+    CyclomaticMetrics,
+    EigenspaceModel,
+    FeatureVector,
+    HalsteadMetrics,
+    ProjectionResult,
+    TrainingResult,
+    UnsupportedLanguageError,
+)
+from eigenhelm.virtue_extractor import VirtueExtractor
+
+__all__ = [
+    "VirtueExtractor",
+    "CodeUnit",
+    "FeatureVector",
+    "HalsteadMetrics",
+    "CyclomaticMetrics",
+    "EigenspaceModel",
+    "ProjectionResult",
+    "TrainingResult",
+    "UnsupportedLanguageError",
+]

eigenhelm/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entry points for eigenhelm-train and eigenhelm-inspect."""

eigenhelm/cli/evaluate.py

@@ -0,0 +1,260 @@
+"""eigenhelm-evaluate CLI — evaluate files in-process.
+
+Usage:
+    eigenhelm-evaluate path/to/file.py
+    eigenhelm-evaluate src/ --model model.npz
+    echo "def f(): pass" | eigenhelm-evaluate --language python
+    eigenhelm-evaluate src/ --json
+
+Exit codes:
+    0  All files accepted or warned
+    1  One or more files rejected
+    2  Runtime error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from eigenhelm.helm import DynamicHelm
+from eigenhelm.helm.models import EvaluationRequest, EvaluationResponse
+from eigenhelm.parsers.language_map import LANGUAGE_MAP
+
+# Build extension → language mapping from LANGUAGE_MAP
+EXTENSION_TO_LANGUAGE: dict[str, str] = {ext: lang for lang, (_, ext) in LANGUAGE_MAP.items()}
+
+
+DEFAULT_EXCLUDES = {".git", "__pycache__", ".venv", "venv", "env", "node_modules", ".pytest_cache", "dist", "build"}
+
+def discover_files(paths: list[Path]) -> list[tuple[Path, str]]:
+    """Discover eligible source files from given paths.
+
+    For files: looks up language via extension, skips unrecognized.
+    For directories: walks recursively, filtering out excluded directories.
+    Does NOT follow symlinks.
+
+    Returns (path, language) pairs sorted by path.
+    """
+    results: list[tuple[Path, str]] = []
+    for p in paths:
+        if p.is_file():
+            lang = EXTENSION_TO_LANGUAGE.get(p.suffix)
+            if lang is None:
+                print(f"WARNING: Skipping {p} (unrecognized extension)", file=sys.stderr)
+                continue
+            results.append((p, lang))
+        elif p.is_dir():
+            excludes = set(DEFAULT_EXCLUDES)
+            ignore_file = p / ".eigenhelmignore"
+            if ignore_file.is_file():
+                try:
+                    custom_excludes = [
+                        line.strip() for line in ignore_file.read_text().splitlines() 
+                        if line.strip() and not line.startswith("#")
+                    ]
+                    excludes.update(custom_excludes)
+                except OSError:
+                    pass
+
+            for root, dirs, files in os.walk(p, followlinks=False):
+                # Prune excluded directories
+                retained = [d for d in dirs if d not in excludes and not d.endswith(".egg-info")]
+                dirs.clear()
+                dirs.extend(retained)
+
+                for filename in files:
+                    if filename in excludes:
+                        continue
+                    child = Path(root) / filename
+                    try:
+                        if child.is_symlink() or not child.is_file():
+                            continue
+                        lang = EXTENSION_TO_LANGUAGE.get(child.suffix)
+                        if lang is not None:
+                            results.append((child, lang))
+                    except OSError:
+                        continue
+
+    return sorted(results, key=lambda x: x[0])
+
+
+def format_result_human(path: Path | str, response: EvaluationResponse) -> str:
+    """Format a single result for human-readable output."""
+    lines = [
+        f"{path}",
+        f"  decision: {response.decision}",
+        f"  score:    {response.score:.2f}",
+        f"  confidence: {response.structural_confidence}",
+    ]
+    if response.critique.violations:
+        lines.append("  violations:")
+        for v in response.critique.violations:
+            pct = v.contribution * 100
+            lines.append(f"    {v.dimension} (contribution: {pct:.0f}%)")
+    if response.warning:
+        lines.append(f"  warning: {response.warning}")
+    return "\n".join(lines)
+
+
+def format_summary_human(
+    results: list[tuple[Path | str, EvaluationResponse]],
+) -> str:
+    """Format aggregate summary for human-readable output."""
+    total = len(results)
+    accepted = sum(1 for _, r in results if r.decision == "accept")
+    warned = sum(1 for _, r in results if r.decision == "warn")
+    rejected = sum(1 for _, r in results if r.decision == "reject")
+    mean_score = sum(r.score for _, r in results) / total if total else 0.0
+    sep = "─" * 40
+    return (
+        f"{sep}\n"
+        f"Summary: {total} files | {accepted} accepted | {warned} warned | "
+        f"{rejected} rejected | mean score: {mean_score:.2f}"
+    )
+
+
+def format_results_json(
+    results: list[tuple[Path | str, EvaluationResponse]],
+) -> str:
+    """Format results as JSON matching BatchResponse schema."""
+    result_dicts = []
+    for path, resp in results:
+        violations = [
+            {
+                "dimension": v.dimension,
+                "raw_value": v.raw_value,
+                "normalized_value": v.normalized_value,
+                "contribution": v.contribution,
+            }
+            for v in resp.critique.violations
+        ]
+        result_dicts.append(
+            {
+                "decision": resp.decision,
+                "score": resp.score,
+                "structural_confidence": resp.structural_confidence,
+                "violations": violations,
+                "warning": resp.warning,
+                "file_path": str(path),
+            }
+        )
+
+    total = len(result_dicts)
+    accepted = sum(1 for r in result_dicts if r["decision"] == "accept")
+    warned = sum(1 for r in result_dicts if r["decision"] == "warn")
+    rejected = sum(1 for r in result_dicts if r["decision"] == "reject")
+    mean_score = sum(r["score"] for r in result_dicts) / total if total else 0.0
+
+    if rejected > 0:
+        overall = "reject"
+    elif warned > 0:
+        overall = "warn"
+    else:
+        overall = "accept"
+
+    output = {
+        "results": result_dicts,
+        "summary": {
+            "overall_decision": overall,
+            "total_files": total,
+            "accepted": accepted,
+            "warned": warned,
+            "rejected": rejected,
+            "mean_score": mean_score,
+        },
+    }
+    return json.dumps(output, indent=2)
+
+
+def _evaluate_stdin(
+    helm: DynamicHelm,
+    language: str,
+) -> list[tuple[Path | str, EvaluationResponse]]:
+    """Read from stdin and evaluate."""
+    source = sys.stdin.read()
+    resp = helm.evaluate(EvaluationRequest(source=source, language=language))
+    return [("<stdin>", resp)]
+
+
+def _evaluate_paths(
+    helm: DynamicHelm,
+    paths: list[Path],
+) -> list[tuple[Path | str, EvaluationResponse]]:
+    """Discover and evaluate files from given paths."""
+    files = discover_files(paths)
+    results: list[tuple[Path | str, EvaluationResponse]] = []
+    for path, lang in files:
+        try:
+            source = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            print(f"WARNING: Skipping binary file {path}", file=sys.stderr)
+            continue
+        resp = helm.evaluate(EvaluationRequest(source=source, language=lang, file_path=str(path)))
+        results.append((path, resp))
+    return results
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for eigenhelm-evaluate.
+
+    Returns exit code: 0 (no rejections), 1 (any rejection), 2 (runtime error).
+    """
+    parser = argparse.ArgumentParser(
+        prog="eigenhelm-evaluate",
+        description="Evaluate code files against the aesthetic manifold",
+    )
+    parser.add_argument("paths", nargs="*", type=Path, help="File or directory paths")
+    parser.add_argument(
+        "--language",
+        default=None,
+        help="Language (required for stdin mode when no paths given)",
+    )
+    parser.add_argument("--model", default=None, help="Path to .npz eigenspace model")
+    parser.add_argument("--json", dest="json_output", action="store_true", help="JSON output")
+    args = parser.parse_args(argv)
+
+    try:
+        eigenspace = None
+        if args.model:
+            from eigenhelm.eigenspace import load_model
+
+            eigenspace = load_model(args.model)
+
+        helm = DynamicHelm(eigenspace=eigenspace)
+
+        if not args.paths:
+            if not args.language:
+                print(
+                    "ERROR: --language is required when reading from stdin",
+                    file=sys.stderr,
+                )
+                return 2
+            results = _evaluate_stdin(helm, args.language)
+        else:
+            results = _evaluate_paths(helm, args.paths)
+
+        if not results:
+            return 0
+
+        if args.json_output:
+            print(format_results_json(results))
+        else:
+            for path, resp in results:
+                print(format_result_human(path, resp))
+            if len(results) > 1:
+                print(format_summary_human(results))
+
+        has_rejection = any(r.decision == "reject" for _, r in results)
+        return 1 if has_rejection else 0
+
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

eigenhelm/cli/harness.py

@@ -0,0 +1,120 @@
+"""eigenhelm-harness CLI — compare two corpora with Mann-Whitney U test.
+
+Usage:
+    eigenhelm-harness --before corpus/before/ --after corpus/after/
+    eigenhelm-harness --before before/ --after after/ --model model.npz --json
+
+Exit codes:
+    0  Harness completed (regardless of significance)
+    1  One or both corpus directories empty/unreadable
+    2  Runtime error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from eigenhelm.harness.report import HarnessReport
+
+
+def format_harness_human(report: HarnessReport) -> str:
+    """Format a HarnessReport for human-readable output."""
+    b = report.before
+    a = report.after
+
+    delta_symbol = "✓ Improvement" if report.improvement else "✗ No improvement"
+    sig_symbol = "YES ✓" if report.significant else "NO ✗"
+
+    lines = [
+        "eigenhelm-harness: Quality Comparison Report",
+        f"  Before corpus:  {b.n_files} files evaluated, {b.n_skipped} skipped",
+        f"    Mean score:   {b.mean_score:.2f}  "
+        f"(median: {b.median_score:.2f}, std: {b.std_score:.2f})",
+        f"    Accept/Warn/Reject: {b.accepted} / {b.warned} / {b.rejected}",
+        "",
+        f"  After corpus:   {a.n_files} files evaluated, {a.n_skipped} skipped",
+        f"    Mean score:   {a.mean_score:.2f}  "
+        f"(median: {a.median_score:.2f}, std: {a.std_score:.2f})",
+        f"    Accept/Warn/Reject: {a.accepted} / {a.warned} / {a.rejected}",
+        "",
+        f"  Delta (after − before):  {report.delta_mean_score:+.2f}  {delta_symbol}",
+        f"  Mann-Whitney U:           {report.u_statistic:.1f}",
+        f"  p-value:                  {report.p_value:.4f}",
+        f"  Significant at α=0.05:    {sig_symbol}",
+    ]
+    return "\n".join(lines)
+
+
+def format_harness_json(report: HarnessReport) -> str:
+    """Format a HarnessReport as JSON matching field names exactly."""
+
+    def _stats_dict(s):
+        return {
+            "n_files": s.n_files,
+            "n_skipped": s.n_skipped,
+            "mean_score": s.mean_score,
+            "median_score": s.median_score,
+            "std_score": s.std_score,
+            "accepted": s.accepted,
+            "warned": s.warned,
+            "rejected": s.rejected,
+        }
+
+    output = {
+        "before": _stats_dict(report.before),
+        "after": _stats_dict(report.after),
+        "delta_mean_score": report.delta_mean_score,
+        "u_statistic": report.u_statistic,
+        "p_value": report.p_value,
+        "significant": report.significant,
+        "improvement": report.improvement,
+    }
+    return json.dumps(output, indent=2)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for eigenhelm-harness.
+
+    Returns exit code: 0 (success), 1 (empty corpus), 2 (runtime error).
+    """
+    parser = argparse.ArgumentParser(
+        prog="eigenhelm-harness",
+        description="Compare two corpora with statistical testing",
+    )
+    parser.add_argument("--before", required=True, type=Path, help="Before corpus directory")
+    parser.add_argument("--after", required=True, type=Path, help="After corpus directory")
+    parser.add_argument("--model", default=None, help="Path to .npz eigenspace model")
+    parser.add_argument("--json", dest="json_output", action="store_true", help="JSON output")
+    args = parser.parse_args(argv)
+
+    try:
+        eigenspace = None
+        if args.model:
+            from eigenhelm.eigenspace import load_model
+
+            eigenspace = load_model(args.model)
+
+        from eigenhelm.harness.runner import run_harness
+
+        report = run_harness(args.before, args.after, eigenspace=eigenspace)
+
+        if args.json_output:
+            print(format_harness_json(report))
+        else:
+            print(format_harness_human(report))
+
+        return 0
+
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

eigenhelm/cli/inspect.py

@@ -0,0 +1,86 @@
+"""eigenhelm-inspect: Inspect a trained .npz eigenspace model."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for eigenhelm-inspect CLI.
+
+    Exit codes:
+        0 — success
+        1 — invalid model file (missing keys, bad format)
+    """
+    parser = argparse.ArgumentParser(
+        prog="eigenhelm-inspect",
+        description="Inspect a trained .npz eigenspace model.",
+    )
+    parser.add_argument(
+        "model_path",
+        metavar="model-path",
+        type=Path,
+        help="Path to a .npz eigenspace model",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="as_json",
+        help="Output as JSON instead of plain text",
+    )
+
+    args = parser.parse_args(argv)
+
+    from eigenhelm.training import inspect_model
+
+    try:
+        info = inspect_model(args.model_path)
+    except FileNotFoundError as exc:
+        print(f"eigenhelm-inspect: error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except KeyError as exc:
+        print(f"eigenhelm-inspect: invalid model file: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        print(f"eigenhelm-inspect: error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.as_json:
+        evr = info["explained_variance_ratio"]
+        out = {
+            "version": info["version"],
+            "n_components": info["n_components"],
+            "corpus_hash": info["corpus_hash"],
+            "projection_shape": list(info["projection_shape"]),
+            "cumulative_variance": info["cumulative_variance"],
+            "explained_variance_ratio": evr.tolist() if evr is not None else None,
+            "mean_range": list(info["mean_range"]),
+            "std_range": list(info["std_range"]),
+        }
+        print(json.dumps(out, indent=2))
+    else:
+        evr = info["explained_variance_ratio"]
+        if evr is not None:
+            per_pc = "  ".join(f"PC{i + 1}: {v * 100:.1f}%" for i, v in enumerate(evr))
+            variance_line = f"{info['cumulative_variance'] * 100:.1f}% cumulative"
+        else:
+            per_pc = "(not available)"
+            variance_line = "N/A"
+
+        lines = [
+            "eigenhelm-inspect: Model summary",
+            f"  Version:      {info['version']}",
+            f"  Components:   {info['n_components']}",
+            f"  Corpus hash:  {info['corpus_hash']}",
+            f"  Projection:   {info['projection_shape']}",
+            f"  Variance:     {variance_line}",
+            f"    {per_pc}",
+            f"  Feature mean: [{info['mean_range'][0]:.2f}, {info['mean_range'][1]:.2f}] (range)",
+            f"  Feature std:  [{info['std_range'][0]:.2f}, {info['std_range'][1]:.2f}] (range)",
+        ]
+        print("\n".join(lines))
+
+    sys.exit(0)

eigenhelm/cli/serve.py

@@ -0,0 +1,76 @@
+"""eigenhelm-serve CLI — start the FastAPI sidecar server.
+
+Usage:
+    eigenhelm-serve --host 0.0.0.0 --port 8080 --model model.npz
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for eigenhelm-serve."""
+    try:
+        import uvicorn  # noqa: F401, I001
+        from eigenhelm.serve import create_app  # noqa: I001
+    except ImportError:
+        print(
+            "ERROR: eigenhelm[serve] extras not installed. Run: pip install 'eigenhelm[serve]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    parser = argparse.ArgumentParser(
+        prog="eigenhelm-serve",
+        description="Start the eigenhelm evaluation sidecar server",
+    )
+    parser.add_argument("--host", default="0.0.0.0", help="Bind address (default: 0.0.0.0)")
+    parser.add_argument("--port", type=int, default=8080, help="Port (default: 8080)")
+    parser.add_argument("--model", default=None, help="Path to .npz eigenspace model")
+    parser.add_argument(
+        "--timeout-graceful-shutdown",
+        type=int,
+        default=30,
+        help="Seconds to wait for in-flight requests on SIGTERM (default: 30)",
+    )
+    args = parser.parse_args(argv)
+
+    eigenspace = None
+    if args.model:
+        try:
+            from eigenhelm.eigenspace import load_model
+
+            eigenspace = load_model(args.model)
+            print(
+                f"INFO: Loading eigenspace model from {args.model} "
+                f"(version={eigenspace.version}, corpus_hash={eigenspace.corpus_hash})",
+                file=sys.stderr,
+            )
+        except (FileNotFoundError, OSError) as exc:
+            print(f"ERROR: Failed to load model: {exc}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print(
+            "WARNING: No eigenspace model loaded; running in low-confidence mode",
+            file=sys.stderr,
+        )
+
+    app = create_app(eigenspace=eigenspace)
+    model_status = "loaded" if eigenspace else "none"
+    print(
+        f"INFO: eigenhelm-serve starting on {args.host}:{args.port} (model={model_status})",
+        file=sys.stderr,
+    )
+
+    uvicorn.run(
+        app,
+        host=args.host,
+        port=args.port,
+        timeout_graceful_shutdown=args.timeout_graceful_shutdown,
+    )
+
+
+if __name__ == "__main__":
+    main()