---
title: FreeCAD RAG Assistant
emoji: 🛠️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.5.1
python_version: "3.11"
app_file: app.py
pinned: false
license: apache-2.0
short_description: FreeCAD Python from natural language via RAG
---

# FreeCAD RAG Assistant

A RAG (Retrieval-Augmented Generation) system that generates complete, runnable **FreeCAD 1.1 Python scripts** from natural-language descriptions of parts.

## Architecture

```
Query
  │
  ├─► BM25 retrieval (bm25s)          ─┐
  │                                    ├─► RRF fusion ─► Cross-encoder rerank ─► Top-5 chunks
  └─► Dense retrieval (bge-small-en)  ─┘
                                                                │
                                                  OpenAI (gpt-4o-mini) + system prompt
                                                                │
                                              Generated Python + inline citations
```

**Corpus**: [FreeCAD/FreeCAD-documentation](https://github.com/FreeCAD/FreeCAD-documentation) (CC0 1.0) — ~1,500 English wiki pages covering PartDesign, Sketcher, Python scripting API, and release notes.

## Setup

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Build the retrieval index (one-time, run locally)

```bash
# Clone the FreeCAD documentation repo
git clone --depth 1 https://github.com/FreeCAD/FreeCAD-documentation freecad-docs

# Build BM25 + FAISS indices (outputs to data/)
python build_index.py --repo freecad-docs
```

This produces `data/chunks.parquet`, `data/index.faiss`, and `data/bm25.pkl`. Commit these to the repo before pushing to Hugging Face Spaces.

### 3. Run

```bash
python app.py
```

Enter your OpenAI API key in the UI (it is never stored or logged).

## Retrieval modes

| Toggle | Method | Wins on |
|--------|--------|---------|
| BM25 | `bm25s` with camelCase/snake_case tokenisation | Exact API tokens: `addConstraint`, `Coincident`, `PartDesign::Pad` |
| Dense | `BAAI/bge-small-en-v1.5` + FAISS IndexFlatIP | Paraphrased intent: "round the edges" → Fillet |
| Rerank | `BAAI/bge-reranker-base` cross-encoder | Precision: re-scores top-30 fused candidates |
| Hybrid (default) | Reciprocal Rank Fusion (k=60) | Best overall recall |

## Project structure

```
├── app.py               # Gradio Blocks UI
├── build_index.py       # One-off corpus ingestion + indexing
├── requirements.txt
├── src/
│   ├── config.py        # All tuneable constants
│   ├── ingest.py        # Markdown page loader
│   ├── chunk.py         # Header-split + code-block-preserving chunker
│   ├── retrieve.py      # BM25Retriever, DenseRetriever, RRF, HybridRetriever
│   ├── generate.py      # System prompt, few-shots, OpenAI call
│   └── citations.py     # Citation dataclass + rendering
└── data/                # Pre-built indices (commit via git-LFS if > 100 MB)
    ├── chunks.parquet
    ├── index.faiss
    └── bm25.pkl
```

## FreeCAD-specific notes

- All generated scripts target **FreeCAD 1.1** (released March 25, 2026).
- Scripts are safe to run with `freecadcmd` (headless) — `*Gui` modules are never imported.
- The system prompt explicitly warns about the **Topological Naming Problem**: geometry is referenced by index where possible, and dress-up features (Fillet, Chamfer) are always added after all additive/subtractive features.
- `doc.recompute()` is called after every feature to avoid silent failures.

## Evaluation queries

See section 12 of the technical report for the 12-query test set covering: parametric box, flange with bolt pattern, hex nut, L-bracket, threaded shaft, spreadsheet-driven gear, revolution, coincident constraint question, TNP question, linear pattern, helix sweep, and multi-loop sketch.

## License

Source code: Apache 2.0. Documentation corpus: [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) (FreeCAD Wiki). Attribution to FreeCAD Wiki (CC-BY 3.0) shown in the UI.