TopoMind

CAD-native part retrieval using BRepNet or Step GNN embeddings and FAISS, with a Streamlit UI and an agent-style demo (retrieve → summarize → propose modification).

What is TopoMind?

TopoMind lets you:

• Ingest STEP/STP files from a folder or named datasets (ABC, Fusion 360, IMATI).
• Preprocess them with BRepNet’s pipeline (or use Step GNN graph data) and store per-part metadata.
• Embed parts with a pretrained BRepNet model or the Step GNN encoder, then build a FAISS index.
• Search by part (from the index) or by uploading a STEP file; get top-k similar parts with optional face-count reranking.
• Agent Trace (demo): Run a fixed sequence: retrieve similar parts → summarize query and top result → propose a modification plan (deterministic or LLM if OPENAI_API_KEY is set).

Embeddings and index are stored per backend (brepnet or step_gnn). You can switch backends in the UI sidebar and re-embed + rebuild the index for the selected backend.

Quickstart

1. Clone and submodules

   git clone <your-repo-url> TopoMind && cd TopoMind
   git submodule update --init --recursive

2. Install Python dependencies

   pip install -r requirements.txt

3. Config

   cp config.example.yaml config.yaml

   Edit config.yaml if needed (paths, checkpoint, dataset paths). For BRepNet embedding you need a pretrained checkpoint — see docs/CHECKPOINT.md.

4. Preprocessing (BRepNet path)
   STEP → npz preprocessing needs OpenCASCADE (pythonocc-core, occwl). Use the BRepNet conda env:

   • macOS ARM64: conda env create -f environment_preprocess_arm64.yml then conda activate brepnet_preprocess
   • Other: cd vendor/BRepNet && conda env create -f environment.yml && conda activate brepnet
     Then from the TopoMind project root:

   python scripts/ingest_folder.py --folder /path/to/step/files --max-models 100

   Or use the Streamlit Ingest page and point to a folder or a named dataset.

5. Run the app

   streamlit run app.py

   Open the URL (e.g. http://localhost:8501). Use Ingest → Embed & Index (Embed All, then Build Index) → Search or Agent Trace.

   LLM features (optional): The "Use LLM for part summary" and agent LLM options appear only when OPENAI_API_KEY is set. Put OPENAI_API_KEY=sk-... in a .env file in the project root; the app loads .env from the project root if python-dotenv is installed. If you use the BRepNet preprocessing conda env (brepnet_preprocess), install the app deps there too so .env is loaded: pip install python-dotenv openai. Alternatively, export OPENAI_API_KEY=sk-... in your shell before starting the app.

Adding STEP files

• Named datasets: In the UI choose “Named dataset” and pick fusion360, abc, or imati. Configure paths under datasets in config.yaml; see docs/DATASETS.md.
• Arbitrary folder: Choose “Folder path” and enter a directory that contains .step/.stp files, or run:

  python scripts/ingest_folder.py --folder /path/to/step/files [--max-models 1000] [--num-workers 5]

How embeddings work

• BRepNet: Face-level geometry is encoded by the pretrained BRepNet model; we use create_face_embeddings() (no classification head). Face embeddings are pooled (mean or mean+max), then L2-normalized. FAISS IndexFlatIP gives cosine similarity.
• Step GNN: Graph representation of the STEP is encoded by the 3D_STEP_Classification GNN; graph embedding is used as the part vector. See docs/STEP_GNN_SETUP.md if present.
• Retrieval can optionally rerank by face-count similarity (see retrieval.rerank_by_face_count in config and docs/RETRIEVAL_AND_SIMILARITY.md if present).

Limitations

• Path A (current): Encoder is trained for segmentation (or classification); retrieval is “as-is” with no contrastive fine-tuning. Similarity is in embedding space, not necessarily visual.
• BRepNet: Requires a pretrained checkpoint and, for ingest, a conda env with pythonocc-core and occwl.
• No real CAD edits: The “propose modification” step returns a fixed/demo JSON plan; no actual geometry changes.

Roadmap

• Path B (future): Contrastive head fine-tuning, data augmentations, retrieval metrics (e.g. mAP, recall@k).

Project layout

• app.py — Streamlit app (Ingest, Embed & Index, Search, Agent Trace).
• config.example.yaml / config.yaml — Paths and settings; see comments in config.example.yaml.
• src/ — Core logic: step_preprocess, embedding_backend, embeddings, indexer, metadata_store, agent_tools, ui_components, utils.
• scripts/ — CLI: ingest_folder.py, embed_parts.py, reset_pipeline.py.
• vendor/BRepNet, vendor/3D_STEP_Classification — Submodules for preprocessing and encoders.
• docs/ — Datasets, checkpoint, implementation plan, testing.

Testing

• Unit and integration tests: From project root, install dev deps and run pytest:

  pip install -r requirements.txt -r requirements-dev.txt
  pytest tests/ -v

  (Using a venv is recommended: python -m venv .venv && .venv/bin/pip install -r requirements.txt -r requirements-dev.txt && .venv/bin/pytest tests/ -v.) See docs/TESTING.md for details.
• Smoke test (manual): Ingest 1–2 STEP files → Embed All → Build Index → Search by part_id; see docs/TESTING.md.

License

See LICENSE.