Optional Hawking presentation mode for grounded answers (+ green CI)#22
Merged
Conversation
0xadvait
force-pushed
the
feat/hawking-presentation-mode
branch
2 times, most recently
from
June 20, 2026 12:26
c604b9c to
0ce9948
Compare
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
force-pushed
the
feat/hawking-presentation-mode
branch
from
June 20, 2026 12:29
0ce9948 to
1590707
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
doxa retrieves evidence; the agent reading it composes the prose answer (
doxa query --answeris 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-basedPresentationProfilesystem.plain(default, no directive) +hawking. Each Hawking "move" carries a short verbatim exemplar so an agent can pattern-match on real prose.doxa query "..." --present hawkingprepends a=== doxa presentation directive ===block to the retrieved evidence; pairs with--answer.doxa present --list/doxa present hawkingto inspect profiles.presentation.defaultconfig key to make a mode sticky per belief base.Backward compatibility
plain).--jsonstays a bare list forplain; 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.pyimportedimportlib.resources.abcat runtime (3.11+ only); it is annotation-only, so it is now guarded underTYPE_CHECKING(fixes the 3.10 collection error).dict[str, Any]and the pack source-dedup loop asBelief | Quote.urlopenwith# nosec B310.Verification
tests/test_present.py(16): profile registry, directive structure + grounding-rule survival, deterministic rendering, CLI text/JSON paths, config-default resolution.doxa evalon 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), anddoxa.example.yaml.