{
  "markdown": "**English** · [Español](README.es.md)\n\n<p align=\"center\">\n  <img src=\"docs/cover.png\" width=\"660\" alt=\"Genix Apolo CAD — a belt conveyor modeled in Apolo\">\n</p>\n\n<h1 align=\"center\">Genix Apolo CAD</h1>\n\n<p align=\"center\">\n  <b>An <i>agent-native</i> 3D parametric CAD for industrial machinery.</b><br>\n  Built to be <b>driven by an AI agent</b> (Claude Opus or others) over <b>MCP</b> — or by hand in your browser.\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"MIT\">\n  <img src=\"https://img.shields.io/badge/python-3.11–3.13-blue.svg\" alt=\"Python\">\n  <img src=\"https://img.shields.io/badge/kernel-OCCT%20%2F%20build123d-orange.svg\" alt=\"OCCT\">\n  <img src=\"https://img.shields.io/badge/MCP-79%20tools-8A2BE2.svg\" alt=\"MCP 79 tools\">\n  <img src=\"https://img.shields.io/badge/tests-1355%20passing-brightgreen.svg\" alt=\"1355 tests\">\n</p>\n\n---\n\n## What it is\n\nApolo is a **headless** parametric CAD for designing real machines. Its edge **isn't the kernel**\n(it uses OpenCascade, like FreeCAD) but its **agent-native architecture**:\n\n> Every operation is a **command** against an API. The whole document is an editable **command\n> log**. And the same JSON Schemas that generate the UI also generate the **agent's tools**. One\n> single source of truth.\n\nThe upshot: an AI agent can **design complete machines end to end** —not just autocomplete— and\n**verify them**: detect interferences, simulate gravity, look at a render (vision) and emit\nfabricable shop drawings. It's STEP-interoperable, drivable by a human **or** an AI, and usable as\na **headless backend** that other tools/agents call.\n\n**MVP vertical:** conveyors / material handling.\n\n## What makes it different\n\n- 🤖 **Genuinely agent-native.** Not a chatbot bolted onto a CAD: the agent is a first-class\n  client of the same API as the UI. It designs, measures, validates and fixes on its own.\n- 🧾 **Document = command log** (event-sourced). Geometry is never stored → KB-sized files, free\n  undo/redo, parametric editing of any past command.\n- 🧬 **Schema-driven.** Adding a command to the registry makes it appear in the toolbar, the\n  dialogs, the properties panel **and** the agent's tools — without touching anything else.\n- 🔢 **Variables and expressions.** Any numeric field accepts `\"=expression\"` (`=width-2*profile`).\n  Changing a variable regenerates the whole model.\n- 🎯 **Declarative edge/face selectors** (by direction, face, length, proximity) — goodbye to the\n  fragile *topological naming problem*.\n- 🧱 **Machine templates = super-commands** (e.g. `create_belt_conveyor`, `create_take_up`): they\n  inherit parametric editing, undo, BOM and agent exposure for free.\n\n## How to use it\n\n### ▶ Via an AI agent (MCP) — the primary way\n\nYou mostly operate Apolo **by talking to an agent**. It exposes **79 MCP tools**, so any\nMCP-compatible client (Claude Code, Claude Desktop, etc.) running a capable model —**Claude Opus**\nor others— can design entire machines. The repo ships a `.mcp.json`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"apolo-cad\": {\n      \"command\": \".venv/Scripts/python.exe\",\n      \"args\": [\"-m\", \"apolo.mcp_server\"],\n      \"env\": { \"APOLO_URL\": \"http://127.0.0.1:8000\" }\n    }\n  }\n}\n```\n\nWith the server up, you ask your agent in plain language:\n\n> *\"Design a 4 m × 600 mm belt conveyor for 1–15 kg parcels, with a hollow-shaft gearmotor and\n> gravity-type take-up tensioning. Check there are no interferences and show me a render.\"*\n\nAnd the agent:\n1. **Models** with `run_batch` (**atomic** batches: one regenerate, one undo step), referencing\n   parts from the same batch with `$k` and dimensions with `=expression`.\n2. **Perceives** with `render_view` (returns an image → *vision*), `get_topology`, `measure`.\n3. **Validates** with `check_interference`, `engineering_check`, `gravity_test` (simulates what\n   falls).\n4. **Documents** with `drawing` / `drawing_set` / `assembly_manual` → shop drawings, cut lists,\n   BOMs and step-by-step assembly manuals.\n\nThe **write core is minimal** (`run_command` / `run_batch` / `edit_command` + `undo`/`redo` +\n`set_variable`) and covers the **entire** command registry — there is no tool per command. The\nrest of the 79 tools are for reading, perception, drawings and validation. Everything the agent\ndoes lives in the log: editable, undoable and reproducible. Changes show up **live** in the\nbrowser.\n\n### 🖱 By hand (web UI)\n\nA three.js viewport with PBR materials, shadows and a ViewCube; a schema-driven ribbon (Create /\nSketch / Modify / Assemble / Library / Robotics); a parametric properties panel; \"pro CAD\"\nshortcuts (move/rotate with snap, isolate, fit, measure, section). The agent and the UI are **two\nequal clients** of the same API: what one does, the other sees.\n\n## Gallery\n\n| Belt conveyor — maintenance lift, a declared motion study | Folding door — wood + translucent glass |\n|---|---|\n| <img src=\"docs/demo-faja.gif\" width=\"420\"> | <img src=\"docs/showcase-door.png\" width=\"420\"> |\n\n*Everything above is produced by the engine itself: shaded renders and animations come from\n`render_view` / `motion.gif` (VTK) — the very images the agent looks at to review its own work.\nThe animation is a **named motion study**: the agent declares the joint keyframes, then scans the\nwhole travel for collisions.*\n\n## Architecture\n\n```\n   AI agent (MCP) ───┐        ┌── React + three.js (web UI)        equal clients\n                     ▼        ▼                                    of the same API\n                core/apolo/api      FastAPI · REST + WebSocket\n                     │\n                     ▼\n   doc        document = command log (event-sourced · undo/redo · KB-sized .apolo)\n   commands   command registry + JSON Schemas  (single source of truth)\n   kernel     build123d / OpenCascade  (B-rep geometry, render, measure, picking)\n   library    catalog (231 refs) · BOM · machine super-commands\n   assembly   joints · mates · constraints · connectivity / gravity\n   drawing    pro 2D drawings  (HLR → SVG/DXF/PDF · sections · dimensions · drawing sets)\n   physics    gravity / stability  (MuJoCo)\n```\n\nClean, non-negotiable boundaries: `kernel` (pure geometry) ⟂ `commands/registry` (operations +\nschemas) ⟂ `doc` (log/state) ⟂ `api` (transport) ⟂ `agent`/`mcp` (AI clients) ⟂ `ui`. Designed to\nscale (many commands, modules and clients).\n\n## Capabilities\n\n- **Modeling** — primitives, fillet/chamfer/shell/drill, patterns, mirror, revolve, extrude,\n  **sweep/loft** (incl. closed loops and helix), **sheet metal** with flat-pattern DXF/SVG export,\n  **constrained 2D sketching** (in-house scipy solver), **STEP** import.\n- **Assembly & kinematics** — **persistent face mates** (re-solved on edit), **joints**\n  (fixed/revolute/continuous/prismatic), **rail and N-DOF constraints**, **motion study** (animate\n  the joints and scan collisions along the path).\n- **Library & BOM** — a **231-reference catalog** populated from real **standard** dimensions\n  (ISO/ASTM/DIN/EN: bearings, profiles, fasteners, joinery, hardware…) + super-commands\n  (`create_belt_conveyor`, `create_weldment`, `create_frame`, `create_sheet_metal`,\n  `create_take_up`, `create_drive_roller`, robot arm). BOM with cut list and CSV export.\n- **Engineering validation** — `engineering_check` (vertical rules: belt speed, motor torque,\n  support…), `check_interference` (OCCT booleans), and **gravity-based assembly validation**\n  (declare joints/grounds and simulate *what falls* with convex hulls in MuJoCo).\n- **PRO manufacturing drawings** — HLR projections → SVG/DXF/PDF, dimensions with arrows and\n  tolerances, **A-A/B-B sections** with per-material hatching, **detail views**, **title block** +\n  revisions, full **drawing sets**, **automatic hole dimensioning**, **exploded views**, light\n  GD&T, step-by-step **assembly manuals**, and an **Inventor-style color shaded iso**. All from a\n  **declarative spec** (`drawing(spec)`) the agent composes.\n- **FEA (linear static)** — per part (tet mesh + safety factor from σ_vm) and **bonded\n  multi-material assembly**: the whole welded frame under design load, with FS reported *per\n  piece* and deflection contrasted against the analytical check.\n- **Engineering deliverables** — this is where Apolo beats what a CAD ships by default: a\n  **calculation report** (A4 PDF with design basis, formula, substitution and safety factor per\n  check, each citing its standard — CEMA/ISO/DIN/EN/AISC), a **costed BOM and quotation**,\n  **tolerance stack-up** (worst-case + RSS over ISO 2768 / ISO 286), an **installation sheet**\n  (anchor load per support) and a **delivery check** — a green/amber/red gate that refuses to\n  call a design done while it still floats, collides or lacks declared fastening.\n- **AI** — MCP server (79 tools), **vision** rendering, agent session memory, chat auto mode\n  (execute → verify → fix).\n\n## Requirements\n\n- Python 3.11–3.13 (with OCP/build123d binary wheels)\n- Node.js 18+\n- *(Optional)* An Anthropic API key (`ANTHROPIC_API_KEY`) for the AI assistant embedded in the UI\n\n## Installation\n\n```powershell\n# Python core\npython -m venv .venv\n.venv\\Scripts\\python -m pip install -e core\n.venv\\Scripts\\python -m pip install pytest httpx   # for the tests\n\n# UI\ncd ui\nnpm install\nnpm run build    # builds ui/dist, served by the server itself\n```\n\n## Running it\n\n```powershell\n$env:ANTHROPIC_API_KEY = \"sk-ant-...\"   # optional (UI's AI assistant)\n.venv\\Scripts\\python -m uvicorn apolo.api.main:app --port 8000\n```\n\nOpen <http://localhost:8000>. To connect an **agent over MCP**, keep the server running and point\nyour MCP client at the repo's `.mcp.json`. Optional env vars: `APOLO_MODEL` (default\n`claude-opus-4-8`), `APOLO_DB` (SQLite path).\n\n## Tests\n\n```powershell\n.venv\\Scripts\\python -m pytest tests -q   # 1355 tests\n```\n\nThey cover the kernel (per-command volumes/bboxes), the document (undo/redo, incremental\nregeneration, `.apolo` round-trip), expressions and variables, library/BOM/super-commands,\nassembly and kinematics, validations (rules, interferences, gravity), drawings, physics and the\nMCP client.\n\n## The `.apolo` format\n\nA ZIP with `manifest.json` (version, name, units, visibility) + `commands.json` (the full log) +\n`attachments/`. Opening a file = **replaying its log**. Geometry is never serialized → KB-sized\nfiles and cheap autosave.\n\n## Status\n\nA coherent, well-architected MVP within its niche: a FreeCAD-level kernel with an **agent-native\ncapability no big CAD has**. It does not chase feature-for-feature parity with Fusion/SolidWorks\n(it's a **wedge**, not a general replacement). Deliberately out of scope: CAM, real FEA, PCB,\nmulti-user cloud.\n\n## License\n\n[MIT](LICENSE) © 2026 Mario Rojas.\n\nBuilt on excellent free software: [OpenCascade](https://www.opencascade.com/) (LGPL),\n[build123d](https://github.com/gumyr/build123d) (Apache-2.0), [FastAPI](https://fastapi.tiangolo.com/) (MIT),\n[three.js](https://threejs.org/) (MIT) and [MuJoCo](https://mujoco.org/) (Apache-2.0).\n",
  "bytes": 10956,
  "sha": "aa07d7057496b7d290834843daa41a908031d9026cbb1f803b20c5b7a6351ae6",
  "repo_slug": "mariorojasmz/apolo-cad",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mariorojasmz_apolo_cad_64661e43/readme"
}