Q-Nominal AI

Deterministic, fail-closed triage for AI work queues, with GPT-5.6 explanations that advise but never override evidence.

Comment

Inspiration

AI workflows often combine verified outputs, unfinished tasks, cost observations, failures, and completely new statuses in one queue. A language model can interpret that mix, but asking the same model to make every routing decision creates an audit gap. We wanted a system that keeps semantic help while making the control boundary explicit.

What it does

Q-Nominal AI sorts workflow records into five explainable lanes:

  • 5 — quality and evidence,
  • 2 — quantity and coverage,
  • 1 — cost and closure,
  • 4 — stop or archive,
  • 8 — unknown and held.

The deterministic engine checks identity, duplicates, provenance, evidence, and a quality-first ordering. It then produces a multilevel 2/4/8/16 audit and a reproducible JSON report. Unknown records can be sent to an optional GPT-5.6 advisor for explanation and evidence-gap analysis, but model output is never applied automatically and can never create PASS.

The product runs as a local dashboard, CLI, API, Windows Edge app, or Docker container. Its deterministic core works offline with no third-party dependency.

How we built it

The product was extracted from a larger experimental Matrix 12 workflow. Codex mapped the original dependency graph and separated the reusable nominal logic from the Matrix cycle engine, Q runtime, Laboratory, and proof orchestration. We refactored the result into a standard-library Python package with a local API, operational dashboard, portable inputs, atomic reports, tests, Docker support, and optional adapters.

GPT-5.6 is used only for held records. The prompt explicitly prohibits PASS and execution. The response is validated against the five allowed nominals and stored as advisory_only=true, applied=false.

How Codex accelerated the work

Codex helped us:

  • trace coupling across the existing classification, guard, and audit modules;
  • define a standalone product boundary without deleting the source system;
  • refactor runtime-specific imports behind optional adapters;
  • implement the dashboard, local API, CLI, packaging, and test suite;
  • create a fail-closed GPT-5.6 integration;
  • prepare judge instructions, the demo script, and a documented before/after Build Week delta.

The product owner made the core product decisions: quality before quantity before cost, deterministic evidence as the source of truth, no silent deletion, and Matrix/Q/Laboratory as optional modules.

Challenges

The hardest problem was not classification itself. It was preserving the strongest safety invariants while removing mandatory runtime coupling. We also had to ensure that adding generative AI improved semantic usefulness without weakening deterministic control.

Accomplishments

  • A working standalone product, not a wrapper around the original GUI.
  • An offline deterministic path with no install dependency.
  • A clear separation between AI advice and operational decision.
  • Explainable nominal lanes, multilevel audit, input hash, CPU percentiles, and honest GPU boundaries.
  • Optional Matrix and giver/receiver assurance modules without forcing them into the core.

What we learned

Generative models are most valuable here as analysts of ambiguity, not as an invisible source of truth. A small deterministic contract around identity, provenance, and unknown states makes the AI layer easier to trust and easier to evaluate.

Measured A/B evidence

A reproducible local A/B benchmark compares preparing every record for the optional advisor with deterministic Q-Nominal routing. On the bundled demo, advisor input fell from 10 to 2 records (80.00%) and serialized UTF-8 payload fell from 1,137 to 231 bytes (79.68%). On a current 33-record Matrix 12 learning snapshot, advisor input fell to 5 records (84.85%), payload fell to 208 bytes (82.82%), and planned batches at size 20 fell from 2 to 1. Unknown-as-PASS remained zero.

The benchmark made no live OpenAI API request, so token, USD, model-latency, end-to-end latency, and production-savings claims remain explicitly unmeasured. Reproducible commands and machine-readable reports are included in docs/AI_IMPACT_AB.md and reports/.

What's next

Organization-specific mapping contracts, signed audit storage, team review, and connectors for developer and support systems. Broader production performance claims will be added only after workload-specific before/after measurements.

Built with

Python, standard-library HTTP server, HTML, CSS, JavaScript, OpenAI Responses API, GPT-5.6, and Codex.

Try it

Clone the repository and run RUN_Q_NOMINAL_AI.bat on Windows, or run python -m q_nominal_ai serve --open with Python 3.10+. The bundled ten-record demo loads automatically. Full judge instructions are in docs/JUDGE_TESTING.md.

Repository: https://github.com/Aapakl/q-nominal-ai

Built With

Share this project:

Updates