Skip to content

feat(demo): rich-UX rewrite + asciicast recording + README embed#64

Merged
kmadan merged 2 commits into
mainfrom
feat/demo-rich-ux
May 14, 2026
Merged

feat(demo): rich-UX rewrite + asciicast recording + README embed#64
kmadan merged 2 commits into
mainfrom
feat/demo-rich-ux

Conversation

@kmadan
Copy link
Copy Markdown
Contributor

@kmadan kmadan commented May 14, 2026

Summary

Two commits, one bundled PR. PyPI re-release deferred — this is README-visible polish + the underlying canonical-path improvements that benefit every CLI user.

1. `feat(demo): rewrite for canonical rich-UX flow`

The v0.7.1 demo runner shipped with plain `print()` calls — the banner, spinners, MessageGroup, and success markers that ship in `examples/quickstart.py` were entirely missing. This rewrites the runner around the high-level `application.create()` + `app.evaluate()` API and wires in `print_banner`, `spinner`, `MessageGroup`, `info`, and `success` from `aicertify.utils.logging_config`. The demo now looks identical to what `examples/quickstart.py` produces.

Three supporting fixes keep the rich UX legible:

  • CLI default verbosity → WARNING (was INFO). `aicertify demo` and `aicertify evaluate` no longer flood with INFO chatter from langfair / deepeval / OPA policy loader / transformers. `--verbose` opts back in.
  • `policy_loader` no longer warns on `helper_functions/` — those `.rego` files are shared library code, not policies, always meant to be skipped silently.
  • Stderr capture inside the demo runner — heavy ML evaluators emit ERRORs for missing OPENAI_API_KEY (expected in no-key demo path; OPA verdict is the substance). Runner redirects fd 2 to a tempfile and only replays it on non-zero exit.

2. `docs(demo): add asciicast recording + GIF + README embed`

Real recording of `aicertify demo` running end-to-end:

  • `docs/demo.cast` — asciinema v2 cast (60 KB, 135 frames). Replayable byte-exact via `asciinema play`.
  • `docs/demo.gif` — agg-rendered GIF (316 KB, 2× speed, monokai). Embedded in README right after the Quick Start so visitors see the rich UX before installing anything.

Recorded against the rich-UX runner from the preceding commit, with `OPENAI_API_KEY` unset — so it shows what a fresh-install user actually experiences.

Test plan

  • Local test in fresh venv (`/tmp/aicertify-demo-test`, editable install): `aicertify demo` produces clean rich-UX output, generates valid Markdown report
  • Same with `OPENAI_API_KEY` unset → same rich UX, OPA verdict in report (heavy evaluators skip gracefully)
  • `aicertify --verbose demo` → restores INFO/DEBUG output (verifies opt-in path)
  • `aicertify demo --format json` → still works (JSON path)
  • Legacy invocation `aicertify --contract X --policy Y` still routes to `evaluate` (back-compat preserved)
  • GIF visually inspected via extracted frames (banner, spinners, MessageGroup, completion markers all captured)
  • Both commits clean — zero Co-Authored-By trailers

Not in this PR

  • PyPI re-release — deferred. Main has rich UX; PyPI still has v0.7.1 plain UX. Will bundle v0.7.2 with future work (more examples, MCP, etc.) rather than re-release per change.

kmadan added 2 commits May 14, 2026 20:47
The 0.7.1 demo runner used plain `print()` — banner/spinner/MessageGroup
output that ships in `examples/quickstart.py` was entirely missing.
This change rewrites the runner around the high-level
`application.create()` + `app.evaluate()` API and wires in `print_banner`,
`spinner`, `MessageGroup`, `info`, and `success` from
`aicertify.utils.logging_config` so the demo looks identical to the
canonical SDK experience.

Three supporting fixes keep the rich UX legible:

- **CLI default verbosity → WARNING.** `cli.main()` was calling
  `logging.basicConfig(level=logging.INFO)` which made every aicertify
  command flood the terminal with INFO chatter from langfair, deepeval,
  the OPA policy loader, transformers, etc. The default is now WARNING;
  `--verbose` opts back in (raises root to INFO and the `aicertify`
  namespace to DEBUG).

- **`policy_loader` no longer warns on `helper_functions/`.** Those
  `.rego` files are shared library code (reporting helpers, validation
  helpers), not policies, and were always meant to be skipped silently.
  Same for dot-prefixed config directories.

- **Stderr capture wrap inside the demo runner.** Heavy downstream
  evaluators still emit ERRORs for missing OPENAI_API_KEY — expected in
  the no-key demo path, since the OPA verdict is the substance of the
  report regardless. The runner redirects fd 2 to a tempfile during the
  demo and only replays it on non-zero exit, so debug info isn't lost
  on failure but doesn't pollute the success path.

The demo runs through the same code path as `aicertify evaluate` and as
`examples/quickstart.py` — what the user sees in the demo IS what the
canonical pipeline produces.
Adds a real recording of `aicertify demo` running end-to-end:

- `docs/demo.cast` — asciinema v2 cast (60 KB, 135 frames). Replayable
  with `asciinema play docs/demo.cast` for byte-exact byte-stream
  reproduction. Recorded against the rich-UX runner from the preceding
  commit, with OPENAI_API_KEY unset, so it shows what a fresh-install
  user actually experiences.

- `docs/demo.gif` — agg-rendered GIF (316 KB, 68 frames at 2× speed,
  monokai theme). Embedded in README right after the Quick Start so
  README visitors see the rich UX before they install anything: ASCII
  banner, spinners with emojis, MessageGroup panel, success markers,
  and the final report path. Renders inline in any markdown viewer
  including GitHub mobile.

CHANGELOG records both this artifact set and the rich-UX rewrite from
the preceding commit under [Unreleased].
@github-actions github-actions Bot added 📝 documentation Improvements or additions to documentation 🚀 enhancement New feature or request 🤝 good first issue Good for newcomers 🛡️ security Security vulnerabilities labels May 14, 2026
@kmadan kmadan merged commit 2d52fa4 into main May 14, 2026
5 checks passed
@kmadan kmadan deleted the feat/demo-rich-ux branch May 14, 2026 15:18
@kmadan kmadan mentioned this pull request May 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

📝 documentation Improvements or additions to documentation 🚀 enhancement New feature or request 🤝 good first issue Good for newcomers 🛡️ security Security vulnerabilities

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant