Athena: A Local-First Git & AST Change-Intelligence Engine and MCP Server

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Most release-note generators and PR review bots do the same thing: they dump git log --oneline into a cloud LLM and hope for the best.

That fails in real engineering teams for two reasons:

1. Commit messages lie. A commit titled fix(api): minor cleanup in parameter defaults might actually insert an optional parameter before an existing one (def compute(a, b=2) -> def compute(a, inserted=0, b=2)), silently shifting positional arguments for every caller in production.
2. Hallucinations & privacy. Cloud LLMs invent commit hashes, miss downstream callers, and require sending proprietary source diffs to external APIs.

Athena (athena-mcp) is an open-source, local-first Git & AST Change-Intelligence Engine, CLI, and Model Context Protocol (MCP) server. Instead of guessing from commit titles, Athena parses the actual Python Abstract Syntax Tree (ast) and TypeScript/JavaScript structural contracts across any Git revision range (base_ref..target_ref), traces downstream caller blast radius across the repository, flags stale Markdown documentation, and binds every single finding to a verified EvidenceRecord (40-character commit SHA, file path, exact base/target line spans, and diff hunk excerpt).

---

Open-Source AI Models & Ecosystem Used

Because this challenge celebrates Open-Source AI, Athena is built 100% on open-weights models and open protocols that run locally on consumer hardware (tested on an NVIDIA RTX 4050 Laptop GPU with 6 GB VRAM and 16 GB RAM):

1. Google gemma:latest (Gemma 7B — Open Weights via Ollama, ~5.0 GB):
   • Used in Mode B to synthesize executive summaries and audience-segmented release narratives (Developers, Maintainers, and Clients/Stakeholders) from Athena's deterministic AST and Git evidence records.
2. Alibaba qwen2.5-coder:7b (Qwen 2.5 Coder 7B — Open Weights via Ollama, ~4.7 GB):
   • Used in Mode B for code-heavy breaking-change impact explanations, migration guidance, and caller blast-radius summaries.
3. Automatic 6 GB VRAM Model Swap & Verification Gate (src/athena/ollama_engine.py):
   • Running two 7B models on a 6 GB laptop GPU normally triggers CUDA/VRAM thrashing. Athena inspects Ollama's /api/ps endpoint before inference and automatically evicts any competing loaded model (keep_alive: 0) before loading gemma:latest or qwen2.5-coder:7b.
   • Zero-Hallucination Verifier (src/athena/verifier.py): Every JSON response returned by gemma:7b or qwen2.5-coder:7b is cross-checked against Athena's deterministic EvidenceRecord table. If the model invents a commit SHA, fabricates a file path, or times out, Athena strips the unverified claim or gracefully falls back to deterministic Mode C.
4. Open-Source Model Context Protocol (mcp Python SDK):
   • Exposes Athena's intelligence as 4 standardized, read-only stdio MCP tools (inspect_revision_range, analyze_code_changes, detect_potential_breaking_changes, and generate_release_notes) so any MCP-compatible agent or IDE can query ground-truth Git + AST diffs locally.

---

How Athena's Engine Works

• Deterministic-First Core (Mode A — 0ms LLM Wait Time): Works 100% offline without Ollama or any network connection.
• Deep AST Contract & Recursion Differencing:
  • Catches removed parameters, narrowed defaults, removed None-fallback body guards (griffe#469), (str, Enum) <-> StrEnum breaking migrations (griffe#501), and newly raised exceptions (griffe#498).
  • Positional-Parameter Index Shift Detection (BUG-030): Flags optional positional insertions that shift surviving parameters' indices (old_pos_idx[n] != new_pos_idx[n]), verified against a 66-case parametrized binding-relation matrix across positional-only (/), standard positional, trailing appends, and keyword-only (*) controls.
  • Recursive Function Defect Analysis (BUG-021..BUG-029): Detects broken recursive self-call arity, unconditional infinite recursion without a base case, and unqualified class-method recursion NameErrors.
• Public API Exposure vs. Internal Helpers: Distinguishes __all__, __init__.py re-exports, and TypeScript export symbols (is_public_api_export=True) from internal _private modules.
• Dynamic Dispatch & Coverage Confidence: Scans for reflection (getattr, globals(), eval, importlib.import_module, TS bracket dispatch obj[key]()) and outputs an explicit AnalysisCoverageReport.

---

Why This Matters (The Side Hustle / Business Case)

• Engineering Teams & Fast-Moving Startups: A single silent breaking change in a shared internal package costs hours of incident triage and rollbacks. Athena drops straight into GitHub Actions (.github/workflows/athena-audit.yml) or your IDE (Claude Desktop, Cursor, VS Code) via MCP.
• Open-Source Maintainers: Automates verified, audience-segmented release notes and SemVer checks without manual diff digging.
• Regulated Industries (FinTech, HealthTech, Defense): Teams that cannot send proprietary code diffs to closed cloud APIs get AI-enhanced release intelligence running 100% on local hardware with built-in path-jail security, Git flag-injection defense, and automatic Bearer/API key redaction.

---

Demo & CLI Usage

1. Install Athena (Python 3.12+)

bash
git clone https://github.com/aaryanrwt/athena.git
cd athena
pip install -e ".[dev]"

Comments

[Aaryan Rawat]

Repository: github.com/aaryanrwt/athena
License: Apache-2.0 (Open Source)
Open-Source Models Supported: gemma:latest (Gemma 7B) & qwen2.5-coder:7b via local Ollama

If you try Athena on one of your repos—or find a gnarly Python/TypeScript AST edge case—drop a comment below or open an issue