# catia-ai — Local AI-Driven CATIA V5 Automation

Native parametric **CATPart / CATProduct** generation from natural language via a semantic IR → CATIA Automation pipeline. No meshes, no renamed STEP.

```
USER  →  AI Planner  →  CAD MCP Server  →  Orchestration (Executor / Tx / Recovery)  →  CATIA V5
                                       →  native Sketches / Pads / Shafts / Holes / Fillets / Patterns
                                       →  save → reopen → update → validate
```

## Prerequisites

| Requirement | Detail |
|-------------|--------|
| OS | **Windows 10/11 64-bit** for native CATPart (Linux/macOS run in mock/offline mode) |
| CATIA | Dassault Systèmes **CATIA V5 R28–R32**, legitimately licensed (DSLS / LUM) |
| License | Valid CATIA MD2 / HD2 / PLM Express etc. – system never bypasses licensing |
| Python | 3.10+ (3.12 tested) |
| pywin32 | `pip install pywin32` on Windows for `CATIA.Application` COM |
| Node | 18+ for MCP clients (OpenCode, Claude Code) |

> **Linux (this machine: Mint 22.2, i5-13420H, 16 GB, RTX 3050)**: CATIA V5 does not run natively. The system detects this, logs it, and continues in **mock/offline** mode – the full AI→MCP→orchestration→validation pipeline is proven, files are written as text+JSON sidecars (`*.CATPart.mock.json`). On Windows with a licensed CATIA, the same code drives real `CATIA.Application` and writes binary native CATParts.

## Quick Start

```bash
git clone https://github.com/kVeyra/catia-ai
cd catia-ai
pip install -r requirements.txt        # or pip install -e .
# Windows: pip install pywin32

# 1. Inspect environment
python scripts/detect_catia.py
catia-ai --inspect              # same via CLI

# 2. Milestone 1 – block
catia-ai "Create a 100 x 50 x 20 mm rectangular block."
# → output/Block_100x50x20.CATPart

# 3. Shaft (acceptance test)
catia-ai "Create a parametric shaft with: diameter 50 mm, length 300 mm, central bore 20 mm, four mounting holes, and 5 mm fillets."

# 4. Radial engine
catia-ai "Create a 9-cylinder radial engine with 90 mm bore, 100 mm stroke, master connecting rod, 8 articulating rods, cylinders arranged radially around the crankshaft, parametric cooling fins, pistons, crankshaft, and assemble everything."

# 5. Mock tests (work on Linux)
pytest -q
```

## .prt vs .CATPart

`.prt` is **not** CATIA V5 native (it belongs to Creo/UG). CATIA V5's native part format is `.CATPart` and assembly is `.CATProduct`. If you request `.prt`, the system explains this and saves `.CATPart`, optionally exporting STEP/IGES via `export_step` if CATIA is present. It never renames another format to `.CATPart`.

## MCP Configuration

### OpenCode (`opencode.json`)
```json
{
  "mcpServers": {
    "catia": {
      "command": "python",
      "args": ["src/mcp/server.py"],
      "cwd": "/path/to/catia-ai"
    }
  }
}
```

### Claude Code (`.mcp.json`)
```json
{
  "mcpServers": {
    "catia": {
      "command": "python",
      "args": ["-m", "src.mcp.server"],
      "cwd": "/path/to/catia-ai"
    }
  }
}
```

Test: in your MCP client, call `inspect_environment` then `plan_and_execute` with a prompt.

## AI Provider (local, no cloud required)

```bash
# Rule-based offline (default – no LLM needed)
export CATIA_AI_PROVIDER=local

# Ollama
export CATIA_AI_PROVIDER=ollama
export OLLAMA_URL=http://localhost:11434
export OLLAMA_MODEL=llama3

# LM Studio / any OpenAI-compatible
export CATIA_AI_PROVIDER=openai
export OPENAI_BASE_URL=http://localhost:1234/v1
export OPENAI_API_KEY=lm-studio
```

The planner has a deterministic rule path so the system works without any LLM.

## Project Structure

```
catia-ai/
├── src/agent/          # planner, specification (semantic IR), reasoning (AI provider)
├── src/catia/          # connection, documents, parameters, sketches, features, assemblies, validation
├── src/orchestration/  # executor, transactions, recovery
├── src/mcp/            # server.py + tools
├── src/knowledge/      # mechanical components/features/assemblies library
├── src/validation/     # geometry & assembly checks
├── scripts/            # detect_catia, test_connection, test_part_creation
├── examples/           # simple_box, shaft, radial_engine.json, conveyor.json
├── tests/              # pytest suite (mock-capable)
├── output/             # CATPart/CATProduct output
└── logs/
```

## Architecture

See [ARCHITECTURE.md](docs/ARCHITECTURE.md) · [API.md](docs/API.md) · [DEVELOPMENT.md](docs/DEVELOPMENT.md) · [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)

## Milestones

1. Block 100×50×20 – Sketch+Pad, params, save/reopen/update ✅ (mock proven)
2. Cylinder – diameter/height params, Shaft/Pad, regenerate ✅
3. Gear – teeth/module/pressure angle ✅ (placeholder involute)
4. Multi-part assembly – CATProduct, instances, constraints ✅
5. Radial engine – 9 cylinders, crankshaft, rods, fins, CATProduct ✅
6. Acceptance shaft 50×300 bore 20 + holes/fillets ✅

## Safety / License Boundary

- Never bypasses CATIA licensing, activation, DRM, or license servers.
- If no license is available, reports it and stops at the boundary (mock mode for development).
- Generated models are geometrically valid but **not certified engineering** – require qualified review and simulation.

## Known Limitations

- Linux: mock files are not binary CATPart; open in CATIA on Windows for full editability.
- Involute gear uses placeholder cylinder (true law curve needs CAA or GSD).
- Fillet recovery tries 10→5→2→1 mm; complex topology may still need manual repair.
- CAA C++ not bundled – Automation API covers most Part Design features.

## License

MIT – see [LICENSE](LICENSE)