ETABS is the industry-standard software for structural analysis of buildings, but its warning system is notoriously cryptic. A single model run can produce hundreds of warnings scattered across log files, each requiring cross-referencing PDFs, forum posts, and tribal knowledge to diagnose. I built ETABuddy to collapse that entire workflow into a single command.

My Role

Sole developer. Self-initiated project - identified the problem from daily frustration with ETABS warning diagnosis and built the complete solution end-to-end.

What I Built

5 CLI tools orchestrated by a diagnostic skill:

  • manual-search - searches local ETABS manuals using hybrid BM25 + Ollama embedding similarity with Reciprocal Rank Fusion
  • wrn-scan - parses and normalizes ETABS warning output, collapsing hundreds of near-identical warnings into grouped patterns with counts, value ranges, and sample element IDs
  • kb - searches a curated knowledge base of known ETABS issues and solutions
  • web-cache - searches cached web results using SQLite FTS5 for offline access to forum solutions
  • build-toc - generates a table of contents from PDF-converted manuals using adaptive markdown chunking

Hybrid search engine:

  • Fuses BM25 keyword scores with Ollama embedding cosine similarity (nomic-embed-text model)
  • Reciprocal Rank Fusion with saturating normalization makes the two score distributions comparable
  • Returns sourced, ranked results with breadcrumbs tracing back to the exact manual section

Warning normalization:

  • Groups near-identical warnings by pattern - for example, 200 warnings about “area object X lost area” become a single entry with count, affected element ID ranges, and value ranges
  • --summary mode collapses ~2,000 tokens of raw warning output to ~200 tokens for efficient AI consumption

Budget-capped AI orchestration:

  • Multi-tier search strategy: local manuals first, then knowledge base, then web cache
  • Budget cap prevents runaway token consumption during diagnostic sessions
  • Produces a structured diagnostic report with root cause identification and targeted fix recommendations

Impact

  • Reduces warning diagnosis from 10–30 minutes per warning to seconds
  • Used daily on every ETABS model run - accidental modeling issues no longer slip through unnoticed
  • Caught the exact root cause and targeted fix for an “area lost” error in a large model that would have required hours of manual investigation
  • Plans to share with the structural engineering team for company-wide adoption

Technical Stack

Python 3.12, BM25 (rank-bm25), Ollama embeddings (nomic-embed-text), SQLite FTS5, Reciprocal Rank Fusion, adaptive markdown chunking, CLI (Click/Typer).