Skip to content

Optional Hawking presentation mode for grounded answers (+ green CI)#22

Merged
0xadvait merged 1 commit into
mainfrom
feat/hawking-presentation-mode
Jun 20, 2026
Merged

Optional Hawking presentation mode for grounded answers (+ green CI)#22
0xadvait merged 1 commit into
mainfrom
feat/hawking-presentation-mode

Conversation

@0xadvait

@0xadvait 0xadvait commented Jun 20, 2026

Copy link
Copy Markdown
Owner

What

doxa retrieves evidence; the agent reading it composes the prose answer (doxa query --answer is the built-in renderer). This adds an optional presentation layer for that final step, without touching the verbatim-grounding guarantee.

The flagship optional mode is hawking, distilled from how Stephen Hawking presented evidence in the first two chapters of A Brief History of Time: open on the ancient question rather than the apparatus, let the evidence arrive as a procession of minds, say the largest thing in the plainest sentence, keep the genuine strangeness intact, and turn the answer into a question about what we can know.

Default is plain (output unchanged), so it is opt-in -- not everyone needs it.

How it works

  • doxa/present.py -- registry-based PresentationProfile system. plain (default, no directive) + hawking. Each Hawking "move" carries a short verbatim exemplar so an agent can pattern-match on real prose.
  • CLI:
    • doxa query "..." --present hawking prepends a === doxa presentation directive === block to the retrieved evidence; pairs with --answer.
    • doxa present --list / doxa present hawking to inspect profiles.
    • presentation.default config key to make a mode sticky per belief base.
  • Voice, not license. The directive restates the inviolable rule: answer only from returned beliefs and quotes, report conviction honestly, invent nothing.

Backward compatibility

  • Default behavior unchanged (plain).
  • --json stays a bare list for plain; wraps as {"presentation": {...}, "results": [...]} only for a non-plain mode.

Also: green CI

main's CI had been red. This PR also fixes the pre-existing failures so it lands green across Python 3.10-3.13:

  • resources.py imported importlib.resources.abc at runtime (3.11+ only); it is annotation-only, so it is now guarded under TYPE_CHECKING (fixes the 3.10 collection error).
  • mypy: typed the lens init-answers dict as dict[str, Any] and the pack source-dedup loop as Belief | Quote.
  • bandit: marked the scheme-validated pack urlopen with # nosec B310.

Verification

  • New tests in tests/test_present.py (16): profile registry, directive structure + grounding-rule survival, deterministic rendering, CLI text/JSON paths, config-default resolution.
  • Full suite: 129 passed. Clean under ruff, mypy, bandit, coverage (83%), build, twine, on Python 3.10/3.11/3.12/3.13.
  • doxa eval on demo data still reports 100% verbatim -- grounding guarantee intact.

Docs

README section + Docs link, AGENTS.md, docs/presentation.md, architecture note, the portable skill (both copies), and doxa.example.yaml.

@0xadvait
0xadvait force-pushed the feat/hawking-presentation-mode branch 2 times, most recently from c604b9c to 0ce9948 Compare June 20, 2026 12:26
doxa retrieves evidence; the agent reading it composes the prose answer
(doxa query --answer is the built-in renderer). This adds an optional
presentation layer for that final step, without touching the
verbatim-grounding guarantee.

- doxa/present.py: registry-based PresentationProfile system. Default
  "plain" (output unchanged) plus "hawking", distilled from how Stephen
  Hawking presented evidence in the first two chapters of A Brief History
  of Time: open on the old question, stage a procession of minds, say the
  largest thing plainly, keep the strangeness intact, make the answer
  epistemology. Each move carries a short verbatim exemplar.
- CLI: "doxa query --present hawking" prepends a composition directive to
  the evidence (pairs with --answer); new "doxa present" subcommand views
  and lists profiles; "presentation.default" config key. JSON stays a
  bare list for plain and wraps as {presentation, results} for non-plain
  (backward compatible).
- The mode changes voice and shape only. The directive restates the
  inviolable rule: answer only from returned beliefs and quotes, report
  conviction honestly, invent nothing.
- Docs (README, AGENTS.md, docs/presentation.md, architecture), the
  portable skill (both copies), and example config updated. Tests in
  tests/test_present.py (16 tests); full suite 129 passed.

Also fix the pre-existing red CI so this lands green across Python
3.10-3.13:
- resources.py imported importlib.resources.abc at runtime, which only
  exists on 3.11+; it is annotation-only, so guard it under TYPE_CHECKING
  (fixes the 3.10 collection error).
- type the lens init-answers dict as dict[str, Any] (stances/tags are
  lists) and the pack source-dedup loop as Belief | Quote (mypy).
- mark the scheme-validated pack urlopen with nosec B310 (bandit).
Now clean under ruff, mypy, bandit, pytest, coverage (83%), build, twine.
@0xadvait
0xadvait force-pushed the feat/hawking-presentation-mode branch from 0ce9948 to 1590707 Compare June 20, 2026 12:29
@0xadvait 0xadvait changed the title Optional Hawking presentation mode for grounded answers Optional Hawking presentation mode for grounded answers (+ green CI) Jun 20, 2026
@0xadvait
0xadvait merged commit cbea859 into main Jun 20, 2026
4 checks passed
@0xadvait
0xadvait deleted the feat/hawking-presentation-mode branch June 20, 2026 12:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants