Metadata-Version: 2.4
Name: atomadic-forge
Version: 0.73.0
Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
Author: Atomadic
License-Expression: BUSL-1.1
Keywords: atomadic,ass-ade,monadic,architecture,forge,code-quality,ai,agents,javascript,typescript,polyglot
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1
Requires-Dist: typer<1,>=0.15
Requires-Dist: rich<16,>=14
Requires-Dist: pyyaml<7,>=6
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: import-linter<3,>=2.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: cryptography<48,>=42; extra == "dev"
Provides-Extra: signing
Requires-Dist: cryptography<48,>=42; extra == "signing"
Dynamic: license-file

<!-- mcp-name: io.github.atomadictech/atomadic-forge -->

<p align="center">
  <img src="assets/Atomadic-Forge-01.png" alt="Atomadic Forge" width="600"/>
</p>

<h1 align="center">Atomadic Forge</h1>

<p align="center">
  <strong>Spaghetti is Toast.</strong><br/>
  The architecture enforcement engine for AI-generated code.
</p>

<p align="center">
  <a href="https://pypi.org/project/atomadic-forge/"><img src="https://img.shields.io/pypi/v/atomadic-forge.svg" alt="PyPI"/></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-BSL--1.1-yellow.svg" alt="License: BSL-1.1"/></a>
  <a href="https://github.com/atomadictech/atomadic-forge/actions/workflows/ci.yml"><img src="https://github.com/atomadictech/atomadic-forge/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
  <a href="https://registry.modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Official_Registry-blue" alt="MCP Registry"/></a>
</p>

<p align="center">
  <em>Live numbers — every badge below reads from <a href="https://forge.atomadic.tech/metrics.json"><code>forge.atomadic.tech/metrics.json</code></a> on each render.</em><br/>
  <a href="https://forge.atomadic.tech/metrics.json"><img src="https://img.shields.io/endpoint?url=https://forge.atomadic.tech/badge/mcp_tools" alt="MCP tools"/></a>
  <a href="https://forge.atomadic.tech/metrics.json"><img src="https://img.shields.io/endpoint?url=https://forge.atomadic.tech/badge/mcp_actions" alt="MCP actions"/></a>
  <a href="https://forge.atomadic.tech/metrics.json"><img src="https://img.shields.io/endpoint?url=https://forge.atomadic.tech/badge/cli_verbs" alt="CLI verbs"/></a>
  <a href="https://forge.atomadic.tech/metrics.json"><img src="https://img.shields.io/endpoint?url=https://forge.atomadic.tech/badge/tests_passing" alt="Tests passing"/></a>
  <a href="https://forge.atomadic.tech/metrics.json"><img src="https://img.shields.io/endpoint?url=https://forge.atomadic.tech/badge/source_files" alt="Source files"/></a>
  <a href="https://forge.atomadic.tech/metrics.json"><img src="https://img.shields.io/endpoint?url=https://forge.atomadic.tech/badge/lean_theorems" alt="Lean4 theorems"/></a>
</p>

---

AI agents write code **10x faster** than humans can review it. Pattern violations went from 5% to 60% post-LLM. Your codebase is accumulating architectural debt at machine speed.

**Forge fixes that.**

- **Catches architectural violations AI agents leave behind.** Deterministic tier-law enforcement — no LLM in the loop, no hallucinations.
- **Saves 40-60% on LLM tokens.** Structured code = smaller context windows = fewer tokens per turn.
- **One command: spaghetti -> certified architecture.** Python, JavaScript, TypeScript, **Rust, Go, Swift, Kotlin** — full pipeline (recon, wire, certify, scaffold, evolve) on every language.
- **Bring your own LLM.** Built-in presets for OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Groq, Together, Fireworks, xAI, Mistral, Perplexity, Cerebras, Hyperbolic, AAAA-Nexus, and Ollama — plus `forge config provider add` for any custom OpenAI-compatible endpoint.  See [docs/PROVIDERS.md](docs/PROVIDERS.md).
- **IDE-native.** VS Code extension (`vscode-extension/`), MCP server for Claude Code / Cursor / Cowork / Windsurf, four ready-to-use Claude Code skills.  See [docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md).

---

## Quick Start

```bash
pip install atomadic-forge        # install
forge recon .                     # scan any repo (free, read-only)
forge certify . --print-card      # get your architecture score (0-100)
```

That's it. No API key, no config, no writes.

---

## What Forge Does

Forge enforces a **5-tier monadic law** — every source file belongs to exactly one tier, tiers compose upward only. AI agents generate code fast; Forge gives it gravity.

```
  a4_orchestration/    <- CLI, entry points
         |
  a3_features/         <- Feature modules
         |
  a2_composites/       <- Stateful classes
         |
  a1_functions/        <- Pure functions
         |
  a0_constants/        <- Constants, enums (zero logic)
```

**Before Forge:**
```
62 import violations · certify score 23/100 · "it works on my machine"
```

**After `forge auto`:**
```
0 violations · certify 100/100 · signed conformance receipt · ship it
```

---

## CLI Commands

### Core Pipeline

| Command | What it does |
|---------|-------------|
| `forge auto` | **Flagship.** recon → cherry → wire → certify → receipt |
| `forge recon` | Scan a repo — classify every symbol, show tier distribution |
| `forge wire` | Detect upward-import violations |
| `forge certify` | Architecture score (0-100): docs, tests, tier layout, imports |
| `forge verify` | Composite ship gate: PASS / REFINE / FAIL |
| `forge enforce` | Apply mechanical fixes (rollback-safe) |
| `forge status` | Wire + certify in one call |
| `forge welcome` | First-call handshake — score + guidance in one response |

### Quality & Intelligence

| Command | What it does |
|---------|-------------|
| `forge smell` | Code smell scan: cyclomatic complexity, long functions, duplicates |
| `forge call-graph` | AST call graph for any symbol |
| `forge call-graph-summary` | Whole-package call-graph portfolio — orphans, fan-in hotspots, max depth |
| `forge churn` | File-level git commit frequency — hotspot and stable files |
| `forge cna-check` | Compose-Not-Add — flag duplicates before writing |
| `forge trust-gate` | LLM response hallucination detector |
| `forge preflight` | Pre-edit guardrail: tier + import + scope check |
| `forge surface-gaps` | Find a1 entry points missing MCP or CLI coverage |
| `forge wire-stubs <module> <function>` | Generate MCP handler + CLI stub + test skeleton for any unwired a1 function |
| `forge capability-scout --queries "q1,q2"` | Search GitHub for harvest target repos |
| `forge dead-code` | AST-walk dead symbol detector (vulture synthesis) |
| `forge maintainability` | Maintainability Index per module (radon MI: A/B/C/D ranking) |
| `forge concept-bridge --harvest-json path/to/harvest.json` | Convert harvest candidates below TAU_TRUST into actionable synthesis plans |

### Composition & Multi-Repo

| Command | What it does |
|---------|-------------|
| `forge create` | Intent + seed repos -> new pip-installable package |
| `forge emergent scan` | Cross-domain composition discovery |
| `forge recon-swarm` | Walk N repos, unified report |
| `forge harvest` | Cross-repo capability gap finder |

### Planning & LLM Loops

| Command | What it does |
|---------|-------------|
| `forge iterate` | LLM loop: intent -> code -> absorb -> score -> iterate |
| `forge evolve` | Recursive improvement over N rounds |
| `forge plan` | Bounded execution plan with risk + rollback |
| `forge chat` | Terminal copilot over forge docs |

**39 CLI verbs total.** Full reference: [docs/02-commands.md](docs/02-commands.md)

---

## MCP Server — 10 Tools, 112 Actions

Forge ships a Model Context Protocol server. Add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent:

```json
{
  "mcpServers": {
    "atomadic-forge": {
      "command": "forge",
      "args": ["mcp", "serve", "--project", "/path/to/your/repo"]
    }
  }
}
```

**10 tools, 112 actions locally.** All legacy tool names redirect automatically — existing callers keep working. Deployed Worker at [forge.atomadic.tech/mcp](https://forge.atomadic.tech/mcp). Listed in the [MCP Official Registry](https://registry.modelcontextprotocol.io/).

| Tool | Actions | What it does |
|------|---------|-------------|
| `welcome` | — | RECOMMENDED FIRST CALL: onboarding scan, score, narrative, capability tour |
| `explore` | 16 | Analyze, understand, discover — recon/explain/call_graph/call_graph_summary/smell/lineage/harvest/synergy/scan/swarm/churn/surface_gaps/capability_scout/dead_code/maintainability/concept_bridge |
| `audit` | 23 | Quality gates, change safety, trust |
| `plan` | 9 | Orient + dev utilities — context/compose/policy/recipes/generate/apply/locate/commit/scaffold |
| `transmute` | 3 | **FLAGSHIP** spaghetti→certified pipeline — auto/cherry/finalize |
| `loop` | 4 | LLM iteration loops — iterate/resume/evolve/evolve_step |
| `hive` | 13 | Multi-agent coordination — lifecycle, consensus, handoffs, enhancements |
| `wisdom` | 5 | Institutional memory DB — record/query/list/recall/promote |
| `nexus` | 7 | AAAA-Nexus auth primitives (uses `op=` not `action=`) — identity/federation/authorize/trust/contract/lineage/ratchet |
| `create` | — | Intent + seed repos → shippable pip package (Phase 1 pipeline: emergent_swarm + materialize) |

> **Note:** `nexus` uses `op=` as its dispatch key instead of `action=` to avoid collision with the `authorize_action` operation's own `action` parameter that passes through to the Nexus API.

Full tool reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | First call: `welcome`

---

## By the Numbers

> Every number below is a live read from [`forge_metrics.json`](forge_metrics.json) — the canonical metrics artifact regenerated on every push by `forge metrics --apply`. CI fails any PR that lets the file drift.

| Metric | Value |
|--------|-------|

| MCP tools | **10 tools · 112 actions** |
| CLI verbs | **39** |
| Source files | **226** (~45K LOC) |
| Tests | **1555 passing** across **111 test files** |
| Lean4 formal proofs | **872 theorems** (mathematically verified core logic) |
| Monadic tiers | **5** (a0 → a4, strict upward-only composition) |
| Languages | Python, JS/TS, Swift, Kotlin, Go, Rust |
| Infrastructure cost | **$5/mo** |
| Self-score | **100/100** certify · 0 wire violations |
| License | BSL 1.1 (Apache 2.0 after 2030-04-27) |

Forge eats its own cooking. Every CI run scores itself.

---

## Pricing

| Tier | Price | What you get |
|------|-------|-------------|
| **Free** | $0 | OSS, 25 calls/day, read-only tools |
| **One-Time Refactor** | ~~$149~~ **$99** | We run `auto` on your repo -> PR targeting 100/100. One revision included. |
| **Starter** | $79/mo | All 10 tools (112 actions), 5k calls/mo, signed receipts, custom recipes |
| **Pro** | $249/mo | + notarization, compliance attestations, cross-repo telemetry |
| **Founding Member** | $999/yr | Everything. Forever. First 25 only. |
| **Enterprise** | Custom | BSL commercial license, SSO, self-host, SLA |

> **Launch special:** The one-time refactor is **$99** (normally $149). See what Forge does to your codebase before committing to a subscription.

[Get started ->](https://forge.atomadic.tech/pricing)

---

## Docs

| | |
|---|---|
| [First 10 Minutes](docs/FIRST_10_MINUTES.md) | Install, demo, first scan |
| [Tutorials](docs/tutorials/) | Quickstart, 5-tier law, LLM integration |
| [Architecture](ARCHITECTURE.md) | How Forge itself is built |
| [CI/CD Integration](docs/CI_CD.md) | GitHub Actions, GitLab CI, pre-commit |
| [Showcase](docs/SHOWCASE.md) | Live run trajectories |
| [Changelog](CHANGELOG.md) | Version history |
| [Contributing](CONTRIBUTING.md) | How to extend Forge |
| [Security](SECURITY.md) | Vulnerability reporting |

---

## License

[Business Source License 1.1](LICENSE). Free for non-production use. Commercial license for production — see [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md). Change Date: 2030-04-27 -> Apache 2.0.

---

<p align="center">
  <a href="https://forge.atomadic.tech">forge.atomadic.tech</a> — paste any GitHub repo, watch the analysis in real time.
  <br/><br/>
  <a href="https://invest.atomadic.tech">Interested in investing?</a>
</p>
