Metadata-Version: 2.4
Name: githeri
Version: 0.4.1
Summary: Contract Engine for AI Coding Agents. Deterministic specs, test plans, and drift detection.
Author-email: Karakana Labs <dev@karakanalabs.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://githeri.com
Project-URL: Documentation, https://githeri.com/docs
Project-URL: Repository, https://github.com/karakana-labs/githeri
Project-URL: Issues, https://github.com/karakana-labs/githeri/issues
Keywords: ai,agents,spec,fastapi,testing,openapi,contract-testing,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: ruff>=0.4.0
Provides-Extra: mcp
Requires-Dist: mcp>=2.0.0; extra == "mcp"

# Githeri

[![PyPI version](https://img.shields.io/pypi/v/githeri.svg?color=10a37f)](https://pypi.org/project/githeri/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Contract Drift: 0%](https://img.shields.io/badge/route_drift-0%25-brightgreen.svg)](https://githeri.com)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**Contract Engine for AI Coding Agents.**  
Turn natural language feature requests into deterministic, validated YAML specifications and phased implementation plans. Prevent route drift, schema breaks, and agent hallucinations before code merges.

---

## Why Githeri? (The Empirical Benchmark Proof)

AI coding agents (Cursor, Claude Code, Antigravity, Aider) write code quickly, but lightweight and fast models (Gemini Flash, Claude Haiku, local 7B SLMs) frequently cheat:
- **Silent Route Drift:** They claim a feature is done, but implement `GET /` instead of the requested `POST /v1/bookings/`.
- **Hallucinated Endpoints on Crash Reports:** When given a bug report (e.g. *"website is slow, shows white screen"*), vanilla agents invent fake CRUD routes (`GET /fix`, `POST /optimize`) that solve nothing.
- **Phantom Imports & Broken Schemas:** They fabricate non-existent dependencies and database fields.

### The Receipts: Evaluated on `gemini-3.1-flash-lite`

Across benchmark torture tests with contradictory, vague, and chaotic prompts:

| Benchmark Gate | Vanilla Agent (Direct) | Githeri MCP Protocol | Impact |
| :--- | :--- | :--- | :--- |
| **Fluff & Noise Filtering** | Chases impossible constraints | **55 fluff snippets stripped** | Eliminates fantasy constraints |
| **Diagnostic Bug Interception** | Fabricates fake endpoints on crash reports | **100% Intercepted** | Halts wasteful code generation |
| **Contract Determinism** | 0% validated specifications | **100% Validated YAML Specs** | Architectural memory locked |
| **Silent Drift Detection** | Silent drift merged to production | **100% Caught by AST Verifier** | Trapped lazy agent route swaps |

---

## 60-Second Zero-Copy Quickstart (MCP)

No copy-pasting specs, YAML files, or commands from a dashboard. Developers configure their agent once in 1 second, add their API key, and talk to their agent in plain English. The agent calls Githeri tools natively over the **Model Context Protocol (MCP)**.

### Step 1: Install Githeri with MCP support
```bash
pip install "githeri[mcp]"
```

### Step 2: Initialize in your project
```bash
cd your-fastapi-app
githeri init
```
*Creates `.githeri/` (specs, plans, runs registry, and config).*

### Step 3: Scaffold your IDE Agent (1 Second)
```bash
# Cursor: writes .cursor/mcp.json + contract sentinel pre_tool_hook.py
githeri init --agent cursor

# Claude Desktop: safely merges githeri into claude_desktop_config.json
githeri init --agent claude

# Google Antigravity: configures skill and global mcp_config.json
githeri init --agent antigravity

# Or configure all supported agents at once
githeri init --agent all
```

### Step 4: Prompt Your Agent Normally
Open Cursor / Antigravity / Claude chat and prompt as usual:
> *"Add a POST /v1/notifications endpoint with rate limiting."*

The agent handles the rest over stdio without any human copy-pasting.

---

## Native MCP Tools Reference

The Githeri MCP Server (`githeri-mcp` or `githeri mcp`) provides 4 native tools directly into your agent's brain:

| Tool | Agent Input | Output & Action |
| :--- | :--- | :--- |
| `githeri_synthesize_contract` | `feature_prompt`, `context_dir` | Filters prompt noise, validates contract, drops `.githeri/specs/<slug>.spec.yaml`. |
| `githeri_generate_plan` | `spec_slug_or_yaml` | Parses spec into phased implementation checklist at `.githeri/specs/<slug>.plan.md`. |
| `githeri_patch_router` | `router_file`, `entrypoint` | Surgical AST surgery auto-mounts `app.include_router(...)` into `app/main.py`. |
| `githeri_verify_drift` | `code_dir` | AST route scanner matches code against spec. Returns machine-readable pass/fail and missing routes. |

---

## Two Execution Paths

| Feature | Path A: Autonomous Sandbox Executor | Path B: Native MCP Agent Protocol (Primary) |
| :--- | :--- | :--- |
| **Target Engine** | Standalone headless execution loop | Cursor, Claude Desktop, Antigravity, Windsurf |
| **Command / Protocol** | `githeri run --isolated` | JSON-RPC over stdio (`githeri-mcp`) |
| **Developer Interaction**| Terminal CLI output | Natural language chat in IDE |
| **Code Polish** | Auto-runs `ruff check --fix --ignore B008` | Agent / IDE formatters |
| **Router Mounting** | Surgical AST insertion | `githeri_patch_router` MCP tool |
| **Drift Verification** | Evaluated automatically at end of run | `githeri_verify_drift` MCP tool |

---

## Terminal Power Suite (For CLI & CI/CD)

Built for engineers who live in `tmux`, `Neovim`, and automated CI/CD pipelines.

### `githeri plan <prompt>`
Generate spec and phased plan directly in the terminal:
```bash
githeri plan "Add POST /v1/checkout endpoint with JWT auth"
```

### `githeri run --isolated`
Execute plan stages in a disposable sandbox virtual environment with Ruff polish and 0% drift assertion:
```bash
githeri run --isolated
```

### `githeri doctor`
Diagnose your local Python runtime, active virtualenv, Ruff installation, Git hooks, and contract registry:
```bash
githeri doctor
```

### `githeri diff [run-id] [--patch]`
Inspect exactly what was generated or modified in any recorded run:
```bash
githeri diff                         # Summary table of files and router mounts
githeri diff --patch                 # Git-style unified colored diffs (+/-)
```

### `githeri watch`
Continuous contract sentinel. Watches `app/`, `src/`, and `tests/` in real-time. Whenever an AI agent saves a file, Githeri validates contracts in milliseconds:
```bash
githeri watch
# [14:22:01] ⚡ Change detected in app/routers/checkout.py
# ✔ CONTRACT PASS: 3/3 endpoints matched. Zero drift.
```

### `githeri hook install`
Install a pre-commit contract gate into `.git/hooks/pre-commit`:
```bash
githeri hook install                 # Enforces contract verification on every commit
githeri hook status                  # Verify active enforcement
githeri hook remove                  # Uninstall
```

### `githeri check-pr` (CI/CD Quality Gate)
Enforce contracts in GitHub Actions. Exits `1` on contract violations:
```bash
githeri check-pr
```

```yaml
# .github/workflows/contract-gate.yml
name: Contract Gate
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install "githeri[mcp]"
      - run: githeri check-pr
```

---

## Specification Anatomy

Generated specifications (`.githeri/specs/<name>.spec.yaml`) are deterministic, machine-readable contracts:

```yaml
task_id: checkout_service
summary: "Add POST /v1/checkout endpoint with JWT auth"
environment:
  required_packages:
    - "fastapi>=0.110.0"
    - "python-jose[cryptography]>=3.3.0"
local_goals:
  - id: L1
    description: "Checkout processing router"
    type: create
    target_file: "app/routers/checkout.py"
    verification:
      type: http
      method: POST
      url: "http://localhost:8000/v1/checkout"
      expect:
        status_code: 200
        response_schema:
          type: object
          required: ["status", "order_id"]
```

---

## Configuration

Settings are resolved hierarchically:
1. CLI flags (`--provider`, `--model`, `--specs`, `--code`)
2. Local workspace: `.githeri/config.yaml`
3. Global credentials: `~/.githeri/credentials.json`
4. Environment variables: `GITHERI_API_KEY`, `GEMINI_API_KEY`, `OLLAMA_BASE_URL`

```bash
# Authenticate CLI with Githeri Cloud
githeri login --key git_live_...

# Display environment & license status
githeri status
```

---

## Contributing & Development

```bash
git clone https://github.com/karakana-labs/githeri.git
cd githeri
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[mcp,dev]"
pytest tests/
```

## License

Apache-2.0 © [Karakana Labs](https://karakanalabs.com)
