Code engines

How code engines work

What a code engine is

A code engine is a set of Python modules that ship inside the skills. When a skill needs a result that can be worked out exactly (a ranking, a set of diagram coordinates, a census of the stereotypes a repository uses, a Power BI project), the AI runs the engine on the machine where Enterprise Architect runs and reads what comes back. You do not install or start an engine separately: engines arrive with the skills. In the assistant's transcript you see them as the AI running Python, with the module names in code font.

This part describes each engine on its own terms: what it computes, what it takes in, what it returns, and where it stops. The skills say when to use them.

Not every computed result comes from an engine. The reporting business layer is built inside the AI Power Tools MCP Server for Sparx EA: the views in the EA database, the reporting database, the rows for Parquet files, the alignment and value checks, the kept extract, replay and the background refresh. These are server operations, described in Reporting business layer and Reporting business layer, and they need no local code execution. The reporting work that runs as engines is the work around the build: the census, the inclusion choice and the governance gate before it (Census, inclusion choice and governance gate), and the Parquet files and the Power BI project after it (Power BI generator).

Why AI Power Tools uses them

• The same result every time. An engine is either Deterministic (given the same inputs and the same model state, it produces the same result, with no AI judgment involved) or Rule-based (fixed rules, repeatable, but it can be wrong). The labels are defined in section 0.5. An AI working the same problem out in its head gives answers that vary between runs and between models.
• A fraction of the token cost. The AI passes the engine a compact input and reads a compact result. It does not spend its own reasoning on arithmetic, and it does not read thousands of rows to count them.
• Checkable output. Each engine returns its evidence with its answer: the counts and coverage arithmetic behind a ranking, the rectangles behind a layout, the counts behind each inclusion answer, the reason behind each suggested stereotype, and a list of what it could not check. You can verify the result instead of trusting it.

How the AI and an engine split the work

The AI decides and orchestrates. The engine computes and checks.

• The AI reads your request, chooses the scope, decides what to measure and which approach to take, asks you when a choice is yours, runs the engine, and explains the result in your terms.
• The engine takes the AI's inputs and returns the computed answer and its checks. It makes no judgment about what you meant, and it does not decide for you.

This is the AI + AI Power Tools checks pattern from section 0.5. Skills whose work is mostly done by an engine depend least on which AI model you use. Skills that rely on the AI's judgment depend on it most.

What engines need

• Local code execution. The surface you use must let the assistant run code on the machine where Enterprise Architect runs. This is a capability of the Claude client you use, not of AI Power Tools.
• Python 3 on that machine.
• pyyaml, for the notation bindings that the diagram advisor and the composition engine read.
• pyarrow, for writing Parquet files, and for nothing else. It is deliberately not bundled, so install it when you deliver reporting data as Parquet files. CSV and Excel are never used in its place.
• Everything else is Python's standard library.

No engine in this part needs pywin32, and no reporting step needs it. It is needed only by scripts the AI writes for the task at hand against Enterprise Architect's automation interface: the ea-com skill's scripts, and the scripted checks that some skills, such as ea-mdg-deploy, carry.

Which surfaces can run engines

A surface can run engines when it provides local code execution. Claude Code (desktop app) and VS Code with GitHub Copilot provide it, for example. Claude Desktop chat does not. The full list of surfaces and their capabilities is in Capabilities and surfaces.

The reporting business layer's operations run in the AI Power Tools MCP Server for Sparx EA, so every surface that has the MCP server can build, check, replay and refresh from a saved reporting profile. The census, the inclusion choice, the governance gate, the Parquet files and the Power BI project need a surface with local code execution.

Without code execution

Without local code execution the MCP server's operations still work, including every reporting business layer operation. The engines do not run.

• Diagram advisor engine. Not available as a ranking. The AI can still discuss which diagram suits your content from what it reads through the server, but that is its own judgment: it carries none of the engine's counts or coverage arithmetic and is not repeatable.
• Composition engine. Not available for composed diagrams or for the diagram check. Diagram types that Enterprise Architect's own layout places can still be placed, laid out, tidied and rendered with the server's operations, and the AI can look at the result. The composition engine's geometry guarantees and its defect measurements do not apply; the comparison of a reproduction with a reference picture does not run.
• Census, inclusion choice and governance gate. Not available. The inclusion choice cannot be computed, and ea-reporting-database puts it to you before any reporting profile is written, so a first profile cannot be produced. The governance gate does not run, so in-scope elements with no stereotype are not listed before the build. The modeling-language skills lose the census and its comparison of declared and observed usage. A reporting profile that already exists can still be built, checked, replayed and refreshed through the server.
• Power BI generator. Not available. If only pyarrow is missing, the Parquet step stops with the command that installs it, and generating a project over views in the EA database or a reporting database is unaffected.

How engines are tested

Every engine ships with automated tests that run without Enterprise Architect and without Power BI. They check exact results, not just that the code runs. The tests also enforce some of the boundaries described in this part, for example that the advisor and the diagram check contain no modeling-language name. Passing tests show that an engine does what it is specified to do. They do not show that the result suits your model, which is why each engine returns its own checks for you to read.

The four engines

The ea-com skill also has the AI write and run Python against Enterprise Architect. Those scripts are written for the task at hand rather than bundled, so they are not in this catalog.