Metadata-Version: 2.4
Name: githeri
Version: 0.2.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
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

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

AI coding agents (Cursor, Claude Code, Antigravity, Aider) write code quickly, but they frequently:
- **Drift API routes** (e.g. implementing `/api/v2/register` when the client expects `POST /v1/auth/register`).
- **Break database schemas & auth contracts** (fabricating missing fields or hallucinating session objects).
- **Invent bug reports** and introduce regressions without reproducible assertions.

**Githeri acts as an immutable contract gate.** It synthesizes deterministic OpenAPI/YAML contracts and phased execution plans *before* code is written, then verifies the codebase against the specification with mathematical precision.

---

## 60-Second Quickstart

### 1. Install CLI
```bash
pip install githeri
```

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

### 3. Synthesize Specification & Plan
```bash
githeri plan "Add POST /v1/checkout endpoint with JWT auth"
```
*Outputs:*
- `.githeri/specs/checkout.spec.yaml`: Deterministic API & schema contract.
- `.githeri/plans/checkout.plan.md`: Phased, AST-grounded implementation runway.

### 4. Execute with Sandbox Isolation & Ruff Polish
```bash
githeri run --isolated
```
*Auto-provisions a disposable sandbox virtual environment, executes plan stages with AST entrypoint mounting, auto-polishes code with Ruff, and asserts 0% contract drift.*

### 5. Inspect & Pull to Local Codebase
```bash
githeri diff                         # Inspect created files & line counts
githeri diff --patch                 # View full unified colored diffs
githeri pull <run-id>                # Pull verified artifacts into workspace
```

---

## Terminal Power Suite

Built for engineers who live in `tmux`, `Neovim`, and the terminal.

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

### `githeri diff [run-id] [--patch]`
Inspect exactly what an agent or executor created 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
```
*Aborts `git commit` if an AI agent generates code that drifts from `.githeri/specs/`.*

### `githeri purge -r <run-id>`
Instant, zero-risk rollback. Cleans up generated files, reverses AST router mounts from `main.py`, and destroys sandbox virtualenvs:
```bash
githeri purge -r run_20261002_014023_092
```

### `githeri check-pr` (CI/CD Quality Gate)
Enforce contracts in GitHub Actions or CI/CD pipelines. 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
      - run: githeri check-pr
```

---

## Two Execution Paths

Githeri supports two distinct execution patterns:

| Feature | Path A: Native Executor | Path B: Agent Handoff (Primary) |
|---|---|---|
| **Target Engine** | Autonomous local execution loop | Cursor, Claude Code, Antigravity, Aider |
| **Command** | `githeri run --isolated` | Feed `.githeri/specs/` to your agent |
| **Sandbox** | Disposable `.githeri/sandbox_venv` | Developer workspace / container |
| **Code Polish** | Auto-runs `ruff check --fix --ignore B008` | Agent / IDE formatters |
| **Router Mounting**| Surgical AST insertion (preserves `main.py`) | Agent edits entrypoint |
| **Verification Gate**| Evaluated automatically at end of run | Verified via `githeri verify` or `githeri watch` |

---

## 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 ".[dev]"
pytest tests/
```

## License

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