feat: extract the assessment into a shared, headless surface (4.1.0)

[Ali Bahaloo (alibahaloo)]

Why

The verdict rules, the Cisco client and the run orchestration are currently reachable only through analyzer.run() — which resolves credentials from the per-user config file, discovers an inventory in the working folder, prints to a terminal, writes an HTML file, and exits the process.

That makes the assessment unusable by anything that isn't a terminal. A second consumer would have to reimplement the rules instead, and a reimplementation of Constitution IV is a second, divergent answer about the same firewall — the one outcome this tool exists to prevent.

This is the prerequisite for caia-web, which will depend on this package at a pinned tag and import the assessment rather than fork it.

What changed

New — caia/assessment.py. analyze(inventory, client) is the whole check with no user interface attached. It takes a list of per-device dicts (whatever produced them) plus a psirt.Client the caller owns. It prints nothing, writes nothing, never exits the process, and never consults the working folder. _load_catalogues, _run_checks and _assemble_devices moved here unchanged.

Together with matching, psirt and inventory, this is now the package's documented shared surface — see the updated table in the README's maintainers section.

Changed — caia/analyzer.py. Keeps the terminal run flow and supplies its output through the new on_plan and on_progress callbacks. The printed run is byte-identical to before.

Changed — caia/inventory.py. No longer calls sys.exit when openpyxl is missing; raises ImportError instead. A library must not terminate its host process on import.

Two properties worth reviewing closely

Both are about not letting an access failure look like a clean or merely-unassessable fleet:

• A catalogue fetch that fails raises, rather than returning an inventory of Needs review. With empty catalogues every device would resolve to MODEL_UNMAPPED — a report that reads as a data-quality problem when the real cause was a rejected credential. analyzer.run() catches and dies exactly as it did before.
• A failure once the catalogues are in hand returns partial_cause with every answer already obtained. A run is never thrown away, and devices never asked about are Needs review, never Not impacted.

Also

analyze() accepts pre-built catalogues, so a long-running consumer can hold them rather than spend requests re-fetching what never changes. Not used by the CLI.

Behaviour

No change for caia users: same prompts, same progress output, same report, same exit codes.

Tests

• 246 existing tests pass untouched — test_api_flow already covers the engine end-to-end through run(), so it is the regression gate for this refactor.
• 25 added in tests/test_assessment.py for the library path: an in-memory inventory, callbacks, supplied catalogues, both failure modes, input not mutated, and nothing printed.

Ran 271 tests in 0.187s
OK

Smoke-tested against a real 70-device inventory: loads 70 devices across 3 families, collapsing to 33 distinct questions.

Version

VERSION → 4.1.0. Minor, not patch: this adds public API. Tag 4.1.0 after merge so caia-web has something to pin.

🤖 Generated with Claude Code