ETABuddy

The problem

Run an analysis in ETABS and it hands you back a wall of warnings. Not five or ten. Hundreds, sometimes, and most are near-duplicates of each other with a joint label swapped. A few of them matter. The rest are noise you still have to read, because the one that matters is hiding in there and it looks exactly like the ones that don't.

The warnings are terse. "Area object lost during meshing" tells you something happened. It doesn't tell you why, or where to look, or what to change. To diagnose one you go digging: the CSI manual (a PDF open in another window), years of forum posts, and whatever tribal knowledge you or the person next to you has picked up. On a stubborn one, that loop runs 10 to 30 minutes. Per warning.

I got tired of it and built a tool.

What it does

ETABuddy is a command-line toolkit that answers ETABS warnings and modeling questions from a single command. You give it the warning, it gives you a sourced diagnosis in seconds. Underneath, it does three things the manual-and-forum loop can't.

First, it collapses the noise. Hundreds of warnings that differ only by joint number get normalized into a handful of patterns. You stop reading the same warning forty times and start reading the four things that are actually wrong.

Second, it searches like it means it. The warning text runs through a hybrid search engine: BM25 keyword scoring fused with local embedding similarity (Ollama, nomic-embed-text) using reciprocal rank fusion. Keyword search alone misses the warning phrased three different ways across three sources. Embedding search alone drifts toward things that sound related but aren't. Fusing the two, with the score normalization tuned so BM25 and cosine similarity are actually comparable, surfaces the right manual passage and the right forum thread in one ranked list.

Third, it drafts the diagnosis. A budget-capped AI step takes the top results and writes the answer: what the warning means, the likely root cause, the fix to try. Budget-capped because a diagnostic tool has no business quietly spending tokens without a ceiling. A summary mode squeezes a couple thousand tokens of raw warning output down to a couple hundred, which is the difference between skimming and not reading at all.

The whole thing is five small CLI tools in Python 3.12 over a SQLite FTS5 index, orchestrated by a Claude Code skill that knows the diagnostic workflow.

What changed

Diagnosis went from 10 to 30 minutes down to seconds. That is the headline. The change that matters more is quieter: I catch modeling errors I used to miss. On one large model, an "area lost" error that would have been easy to scroll past had a specific root cause and a targeted fix, and ETABuddy walked me to both. Problems that used to slip through until they were expensive don't slip through now.

I use it every day. That is the bar I hold my own tools to, and most don't clear it. This one did, which is why I ended up presenting it, and the method behind it, to the company's agentic coding group.

How it's built

The interesting part isn't the search engine. It's how I built something I trust enough to lean on daily without re-checking every answer by hand.

I wrote the spec before the prompt. I built a golden set of warnings with known-correct diagnoses and graded every change against it. I used a separate, blind evaluator agent so I wasn't marking my own homework. I routed easy questions to cheap models and hard ones to expensive models. I let parameter tuning run overnight against the eval set.

None of that is new to software, and none of it is new to engineering either. It is the same discipline structural engineers already use: write the design intent down, check it against known cases, get an independent review, and know your margins. The habits transfer straight across. I wrote up the full method as its own essay.

The ETABS-specific groundwork keeps growing underneath all of it. Converting the manual from PDF to clean markdown was the single most tedious step, and it is the foundation everything else searches against. Unglamorous, and load-bearing.

That is the pattern with most of these tools. The engineering judgment is the interesting half. The plumbing is most of the work.

What's next

ETABuddy reads a model's warnings. The next step is writing the model in the first place. I've been building aktabs, an open-source Python wrapper around the CSI ETABS API, so a structural engineer can generate and modify a model from a script instead of clicking through the GUI. The native API is verbose: out-parameters, return codes, CLR enums on every call. aktabs hides that behind a Pythonic interface with the same call chains you'd expect, so parametric and templated model workflows become ordinary Python. It's in active development on my GitHub, MPL-2.0, meant for the wider ETABS community and not just me. ETABuddy diagnoses the model. aktabs builds it. Together they cover both ends of the loop I spend my day in.