Metadata-Version: 2.4
Name: eben
Version: 1.0.0
Summary: Canonical Engineering Model for any software repository
License: MIT
Project-URL: Homepage, https://github.com/ebenhq/eben
Project-URL: Repository, https://github.com/ebenhq/eben
Project-URL: Issues, https://github.com/ebenhq/eben/issues
Keywords: developer-tools,cli,engineering,ai,repository
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Provides-Extra: benchmark
Requires-Dist: pydantic>=2.0; extra == "benchmark"
Requires-Dist: litellm>=1.0; extra == "benchmark"
Requires-Dist: rich>=13.0; extra == "benchmark"
Requires-Dist: typer>=0.12; extra == "benchmark"
Provides-Extra: all
Requires-Dist: pydantic>=2.0; extra == "all"
Requires-Dist: litellm>=1.0; extra == "all"
Requires-Dist: rich>=13.0; extra == "all"
Requires-Dist: typer>=0.12; extra == "all"
Requires-Dist: anthropic>=0.25; extra == "all"
Requires-Dist: openai>=1.0; extra == "all"

<div align="center">

# ⬡ eben

**Canonical Engineering Model for any software repository**

Scan any repo and instantly get a structured understanding of its stack, architecture, and conventions — delivered as a unified dashboard, AI context files, a knowledge graph, and a benchmark that proves the value.

**No AI during scanning · No network calls · Fully deterministic · Works offline**

---

> 🔒 **Your code never leaves your machine.**
> eben makes zero outbound connections during scanning. No code, no metadata, and no credentials are ever sent anywhere — not to our servers, not to any LLM. No account required. Works fully air-gapped. [Every line is open source.](https://github.com/ebenhq/eben)

[![PyPI version](https://img.shields.io/pypi/v/eben?style=for-the-badge&color=1E293B&labelColor=0A0A0A&logo=pypi&logoColor=white)](https://pypi.org/project/eben/)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-1E293B?style=for-the-badge&labelColor=0A0A0A&logo=python&logoColor=white)](https://pypi.org/project/eben/)
[![License: MIT](https://img.shields.io/badge/License-MIT-059669?style=for-the-badge&labelColor=0A0A0A)](https://github.com/ebenhq/eben/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ebenhq/eben?style=for-the-badge&logo=github&color=1E293B&labelColor=0A0A0A&logoColor=white)](https://github.com/ebenhq/eben/stargazers)

</div>

---

## What eben does

eben scans your repository once — deterministically, with no AI, no internet — and builds a **Canonical Engineering Model (CEM)**: a structured representation of everything that matters about your codebase.

From that model it generates:

- 📊 **Engineering Dashboard** — dark-mode web UI with 7 sections, AI chat built in
- 🤖 **AI Context Files** — `CLAUDE.md`, `AGENTS.md`, `CURSOR.md`, `GEMINI.md`, `COPILOT.md`
- 🕸️ **Knowledge Graph** — interactive Cytoscape.js graph + DOT + Mermaid exports
- 📈 **AI Readiness Score** — letter grade across 9 engineering dimensions
- 🔬 **Benchmark Engine** — measures AI performance with vs without eben context
- 🗂️ **Canonical JSON** — `report.json` as the single source of truth for everything

---

## Quickstart

```bash
pip install eben
cd your-project
eben init .
open .eben/index.html
```

That's it. Eben scans the repo, builds the model, and opens a full engineering dashboard in your browser.

Every scan ends with an impact summary:

```
  ✓  Dashboard ready → .eben/index.html

  ──────────────────────────────────────────────

  Your AI just got 31 facts about this repo.
  Before eben: your AI knew nothing about my-service.
  After  eben: stack, architecture, conventions, dependencies — all loaded.

  →  Write CLAUDE.md, AGENTS.md and more:
     eben scan . --markdown
```

The fact count is real — every detected convention, dependency, layer, entry point, technology, and module counted from your actual repo.

---

## Install

**Recommended — install globally with pipx:**

```bash
pipx install eben
```

That's it. `eben` is now available everywhere on your machine. No venv, no activation, no `python3 eben.py`.

```bash
# Then just run from any repo:
cd your-project
eben scan .
```

> Don't have pipx? `brew install pipx` on Mac or `pip install pipx` on Linux/Windows.

**Optional extras:**

```bash
pipx install eben[benchmark]   # + benchmark engine
pipx install eben[all]         # + all LLM providers
```

**Or clone and run locally (for development):**

```bash
git clone https://github.com/ebenhq/eben
cd eben
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip setuptools
pip install -e .
eben scan .              # works like a global command while venv is active
```

---

## Commands

| Command | What it does |
|---|---|
| `eben init .` | First-time setup — scan, create `.eben/`, update `.gitignore` |
| `eben init . --markdown` | First-time setup + generate AI context files |
| `eben scan .` | Full re-scan — rebuilds `.eben/` and dashboard only |
| `eben scan . --markdown` | Re-scan + generate AI context files |
| `eben generate .` | Generate AI context files from existing `.eben/` (no rescan) |
| `eben doctor .` | Validate `.eben/` integrity and checksums |
| `eben benchmark --model <model>` | Benchmark AI with vs without eben |
| `eben benchmark show` | Show last benchmark summary |
| `eben benchmark score` | Manually score a benchmark run |

### Scan flags

```bash
eben scan . --markdown           # also generate AI context files
eben scan . --format json        # JSON terminal output
eben scan . --no-color           # no ANSI colours
eben scan . --max-depth 12       # deeper traversal
eben scan . --max-files 100000   # raise file limit
```

---

## What gets generated

### `eben scan .`

Everything goes into `.eben/` — never the repo root:

```
.eben/
├── index.html               ← Engineering Dashboard  ← open this
├── report.json              ← canonical report model
├── model.json               ← Canonical Engineering Model (CEM)
├── technologies.json
├── architecture.json
├── conventions.json
├── dependencies.json
├── metadata.json
├── checksum.json
├── engineering-report.md
├── ai-readiness.json
├── graph.json
├── graph.mermaid
└── graph.dot
```

### `eben scan . --markdown` or `eben generate .`

Also writes AI context files to the repo root (agents find them there automatically):

```
CLAUDE.md
AGENTS.md
CURSOR.md
GEMINI.md
COPILOT.md
```

---

## Engineering Dashboard

One HTML file. No server needed. Works offline. Open it anywhere.

Seven sections:

| Section | What's inside |
|---|---|
| **Dashboard** | AI Readiness score, grade, architecture summary, module count, scan stats |
| **Stack** | Colour-coded badges across 14 technology categories |
| **Architecture** | Layers, modules, entry points, interactive knowledge graph |
| **AI Readiness** | Score breakdown across 9 dimensions with progress bars |
| **Recommendations** | Prioritised improvements with explanations |
| **Generated Files** | All artifacts with paths |
| **Chat** | Browser-based AI assistant — no server, works on GitHub Pages |

### Built-in AI Chat

The Chat tab turns the dashboard into an interactive assistant that already knows your repo before you type a word.

- Reads context from the embedded `report.json`
- Supports 6 providers: **Anthropic · OpenAI · Gemini · Mistral · Groq · Custom**
- Custom provider accepts any OpenAI-compatible endpoint (Ollama, LM Studio, Azure, Together, Anyscale…)
- API key stays in browser memory only — gone when the tab closes
- Works on GitHub Pages (no backend)

---

## What eben detects

**35+ languages** — Java, Python, TypeScript, Go, Rust, Kotlin, Swift, Dart, C#, C++, Ruby, PHP, Scala, Elixir, and more

**60+ frameworks** — Spring Boot, Django, FastAPI, React, Next.js, NestJS, Vue, Angular, Gin, Rails, Laravel, Axum, Flutter, PyTorch, LangChain, and more

**Build tools** — Maven, Gradle, Cargo, Go Modules, Make, Bazel, SBT, MSBuild

**Package managers** — npm, Yarn, pnpm, pip, Poetry, uv, Bundler, Composer, Pub

**Databases** — PostgreSQL, MySQL, MongoDB, Redis, Cassandra, Elasticsearch

**Messaging** — Kafka, RabbitMQ, NATS, ActiveMQ, Celery

**Cloud** — AWS, GCP, Azure, Vercel, Fly.io, Cloudflare, Render, Netlify

**CI/CD** — GitHub Actions, GitLab CI, Jenkins, CircleCI, Travis CI, Drone, Buildkite

**Infrastructure** — Terraform, Pulumi, Ansible, CloudFormation, AWS CDK, Serverless

**Architecture patterns** — Layered, hexagonal, MVC, microservices, monorepo, event-driven, serverless, library

---

## AI Context Files

When you run `eben generate .`, eben writes five files to your repo root — one per major AI coding agent.

Each file uses a **three-zone system**:

```markdown
<!-- eben:generated -->
## Stack
Languages: Java, Kotlin
Frameworks: Spring Boot
...
<!-- /eben:generated -->

<!-- eben:ai -->
AI agents write their notes here.
eben never touches this zone.
<!-- /eben:ai -->

<!-- eben:team -->
Humans write team context here.
eben never touches this zone.
<!-- /eben:team -->
```

| Zone | Owner | Behaviour |
|---|---|---|
| `eben:generated` | eben | Refreshed every `eben generate` or `eben scan --markdown` |
| `eben:ai` | AI agents | Never touched by eben |
| `eben:team` | Your team | Never touched by anyone |

> ⚠️ If a file already exists **without zone markers**, eben overwrites it entirely. Move your existing content into `<!-- eben:team -->` first.

---

## Benchmark Engine

Measures the real impact of eben on AI performance. Runs every task twice:

1. **Baseline** — AI with no eben context
2. **Eben-assisted** — AI with `.eben/report.json` injected

Metrics captured:

- ✅ Task success rate
- 🎯 Accuracy improvement
- 💰 Token and cost reduction
- ⚡ Latency reduction
- 🧠 Hallucination reduction
- 📈 ROI estimate

Outputs go to `.benchmark/`:

```
.benchmark/
├── index.html          ← Benchmark Dashboard (7 sections)
├── benchmark.json      ← full run data
├── benchmark.md        ← markdown summary
└── results.json        ← per-task detail
```

The benchmark dashboard includes a **live ROI calculator** — adjust your team size and session frequency in the browser.

### Supported benchmark providers

| Provider | Key format | Default model |
|---|---|---|
| Anthropic | `sk-ant-...` | claude-haiku-4-5 |
| OpenAI | `sk-...` | gpt-4o-mini |
| Google Gemini | `AIza...` | gemini-1.5-flash |
| Mistral | your key | mistral-small-latest |
| Groq | `gsk_...` | llama3-8b-8192 |
| Ollama / Custom | none / any | your choice |

---

## Architecture

```
eben/
├── core/           ← filesystem walker, detector base, CEM schema, zone system
├── detectors/      ← 8 detectors (one file each — add a detector = one new file)
├── writers/        ← CEM, markdown, terminal output
├── report/         ← Engineering Intelligence Report generator
├── readiness/      ← AI Readiness scoring engine + rules.yaml
├── graph/          ← knowledge graph builder
├── dashboard/      ← Engineering Dashboard (single HTML, no deps)
└── benchmark/      ← full benchmark system
    └── providers/  ← 6 provider implementations (one file each)
```

**Architecture rules:**

- FileSystem walks **once** — all detectors share the same `fs` instance
- Each detector returns a dict — merged by `ModelBuilder.deep_merge()`
- All outputs go to `.eben/` — **never** the repo root
- Agent markdown files go in root only with `--markdown` flag
- `report.json` is the single source of truth — dashboard reads from it
- `from __future__ import annotations` first line in every `.py` (Python 3.8 compat)

---

---

## Contributing

> **macOS / Linux note:** never run `pip install` outside a virtual environment — your OS will block it. Always activate the venv first.

```bash
git clone https://github.com/ebenhq/eben
cd eben

# Create and activate a virtual environment (one time)
python3 -m venv .venv
source .venv/bin/activate       # Mac / Linux
# .venv\Scripts\activate       # Windows

# Install dependencies (venv must be active — you'll see (.venv) in your prompt)
pip install pyyaml              # core only
pip install pyyaml pydantic litellm rich typer   # full install

# Run eben
python3 eben.py scan .
open .eben/index.html
```

Adding a detector = one new file in `eben/detectors/`. Adding a benchmark provider = one new file in `eben/benchmark/providers/`. Nothing else changes.

---

*Built by [ebenhq](https://github.com/ebenhq)*
