Diagram advisor engine
The diagram advisor engine turns a count of the stereotypes in a scope, plus the notation bindings, into a ranked list of candidate views. The AI measures the scope through the server and hands the engine the counts. The engine makes no repository calls and no Enterprise Architect calls. No modeling language, technology id or grammar name appears in it (a test fails if one does), so adding a notation never means editing it. It is the reason the ranking is repeatable and explainable: the same counts, bindings and request always give the same answer.
Used by: ea-diagram-advisor.
Module: advise.py, bundled with the skill. Its two steps below are the two questions the skill asks it.
Runs where: local code execution. It needs Python 3, and pyyaml to read the notation bindings. Without code execution the ranking is not available (see How code engines work).
Logic: Rule-based. Repeatable, and it can be wrong: it ranks by counting, not by understanding what the diagram is for.
What it takes in and produces
| Step | Takes in | Produces |
|---|---|---|
| Profile the scope | A map of each stereotype, as EA stores it, to its element count; the notation bindings; optionally each technology's vocabulary | A profile: elements per technology, concepts and their counts, which technology holds which concepts, the total, the stereotypes nothing could attribute, which technologies are bound, and the verdicts dominant, homogeneous, ambiguous, bound and spans |
| Recommend | The profile, the bindings, and your request as free text | A ranked list of recommendations, best first, never empty. Each carries its kind, technology, viewpoint, diagram type, reasons, whether it spans several languages, the non-conformance sentence, the concepts that will be flagged, and a candidate with its coverage, matched words and generation route |
How it attributes a stereotype. Each stereotype is matched against each binding's declared prefix, longest prefix first. The remainder after the prefix is the concept name, and it must be in that binding's vocabulary: the concepts the binding names plus any vocabulary you supplied. Unstereotyped elements are not counted: they belong to no language, and counting them would let plain elements outvote stereotyped content.
- One match: the stereotype goes to that technology.
- A longer matching prefix wins outright. An unprefixed language does not claim a prefixed language's concept, because they share names and that is why one carries a prefix.
- Two or more bindings claiming the same concept at the same prefix length: the result is the bucket "ambiguous". The engine deliberately does not pick one, because picking by arrival order would be wrong about half the time and look correct.
- No binding claims it, but the supplied vocabulary names exactly one unbound technology that owns it: it goes to that technology (named but unbound). If several unbound technologies claim it, "ambiguous".
- Nothing claims it: the bucket "unbound", listed with its count.
Homogeneity. The scope is homogeneous when one technology holds at least 90% of the stereotyped elements. The threshold is not 100% because real models carry strays, and calling 97% "mixed" would send nearly every real scope down the non-conformant path. Ties break on the technology id so the answer is stable, and a tie leaves the scope mixed anyway. A scope is "bound" only when its dominant technology has a binding; it is not bound for "unbound", "ambiguous" or an empty scope.
How it scores a viewpoint. For each viewpoint of a binding, three keys are compared in this order:
- Coverage: the share of that technology's elements in the scope whose concept the viewpoint admits. A view that cannot hold the content is not a candidate however well its name matches.
- Intent: the number of significant words shared between your request and the viewpoint (words shorter than four characters are dropped; the words come from the viewpoint's name and its recorded intent phrases).
- Narrowness: fewer admitted concepts rank higher, because a narrower viewpoint says more about what the diagram is for.
Ties on all three break on viewpoint name in reverse alphabetical order, so the order is deterministic.
What kinds of recommendation it makes
| Kind | When | What it carries |
|---|---|---|
| Standard | Homogeneous and bound | Up to the top three viewpoints of the dominant technology, with evidence, share, coverage arithmetic, matched words, the concepts the view does not admit, a "close call" line when options tie, and route advice. No non-conformance; the concepts the view does not admit are listed as what will be flagged |
| Dominant-language | Mixed scope whose largest language is bound | The best viewpoint of that language, with a reason that no language holds 90% and the dominant one carries the majority. States that the view spans N languages and lists the foreign concepts that will be flagged |
| Neutral-custom | Mixed or unbound scope | The plain logical diagram type, which has no profile, so nothing on it is foreign and nothing will be flagged. When the dominant bucket is "unbound", the reasons say how many elements carry a stereotype no loaded binding claims, which is a different answer from "mixed" |
| Split | Mixed scope spanning more than one language | One conformant diagram per language, linked. Conformant, but no single picture shows the whole scope |
| None | Empty scope | One option stating there is nothing to profile |
Options are produced in the preference order dominant-language, neutral-custom, split. If the dominant binding publishes no viewpoints, the standard branch yields nothing and the result falls through to the non-standard options.
The generation route. Whether a recommended view can be drawn is reported separately from whether it is the right view, and a view that cannot be generated is still ranked and listed. The route comes from three answers the binding gives about the viewpoint's layout grammar:
| Route | Meaning | What to do |
|---|---|---|
| Composed | The engine computes the geometry | Hand it to ea-diagram-composition |
| Tool layout | EA places the elements; this is the design, not a limitation | Place elements, lay out in EA, tidy, verify |
| Another composition | The view names a grammar the engine does not compose | Compose with another grammar or use EA's layout |
| Not producible | The diagram type dictates its own arrangement | Say so; draw by hand or choose another view. The reason line is prefixed "cannot be generated" |
| Unanswered | The binding did not answer | Confirm before promising a diagram |
| None | No grammar is stated anywhere | Nothing to report |
An unanswered question is never read as agreement.
Limitations.
- Ranks views only; it cannot judge whether the winning view argues the right thing about the content.
- Its coverage is computed over the dominant technology's own elements, not the whole scope. The wider scope shows up in the flagged concepts and the "spans" verdict.
- Intent matching is word overlap. A request phrased with no word in common with any viewpoint name or intent phrase scores zero intent for every option, and the ranking then rests on coverage and narrowness.
- It needs bindings that expose a technology id, a stereotype prefix, diagram types and viewpoints; the bundled binding loader supplies them.