hypgraph 0.7.12__tar.gz → 0.7.14__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {hypgraph-0.7.12 → hypgraph-0.7.14}/CHANGELOG.md +49 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/NOTICE +1 -1
- {hypgraph-0.7.12 → hypgraph-0.7.14}/PKG-INFO +5 -1
- {hypgraph-0.7.12 → hypgraph-0.7.14}/README.md +4 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/PLAN.md +1 -1
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/RELEASE-READINESS.md +22 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/spec.md +51 -14
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/verification.md +26 -4
- hypgraph-0.7.14/examples/frameworks/README.md +70 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/__init__.py +1 -1
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/bundle.py +186 -54
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/cli.py +26 -3
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/coord.py +7 -4
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/graph.py +31 -15
- hypgraph-0.7.14/src/hypgraph/store.py +291 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/hypgraph.js +234 -41
- hypgraph-0.7.14/tests/test_framework_examples.py +50 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_surfaces.py +1 -1
- hypgraph-0.7.14/tests/test_verify_complete.py +291 -0
- hypgraph-0.7.14/tests/test_verify_trust.py +179 -0
- hypgraph-0.7.12/src/hypgraph/store.py +0 -139
- {hypgraph-0.7.12 → hypgraph-0.7.14}/.gitignore +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/AGENTS.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/CITATION.cff +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/DISCLAIMER.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/LICENSE +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/decisions/ADR-001-token-bound-authors.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/decisions/ADR-002-governance-profiles.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/profile-workflows-plan.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/review-2026-10-24.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/site-plan.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/ui-plan.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/workflows/README.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/workflows/knowledge.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/workflows/optimization.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/workflows/scientific.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/workflows/software.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/docs/workflows/trading.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/pyproject.toml +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/__main__.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/blind.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/checks.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/demos/__init__.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/demos/broad_street.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/derive.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/language.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/mcp.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/plan.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/policy.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/profiles.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/references.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/refusals.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/report_check.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/schema.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/server.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/skill/SKILL.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/stats.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/__init__.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/atlas.css +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/atlas.js +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/hypgraph.css +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/hypgraph.svg +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/index.html +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/vendor/LICENSES.md +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/vendor/cose-base.js +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/vendor/cytoscape-fcose.js +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/vendor/cytoscape.min.js +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/ui/vendor/layout-base.js +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/src/hypgraph/workflow.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_accept_work_kind.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_anchoring.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_blind.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_blind_oracles.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_bound_support.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_bundle_telemetry.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_cancel_releases_lease.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_cited_and_failed_support.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_coord.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_d10.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_engine.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_engine_fixes.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_incremental.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_link_translate.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_log_and_check.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_measure_questions.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_opposed_answers.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_option_lead.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_order_detail.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_profiles.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_profiles_041.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_questions_not_assertions.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_references.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_refusal_friction.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_refusal_results.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_refusals.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_relation_words.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_report_answers.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_rerunnable.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_restates_scale.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_server_auth.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_server_hosts.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_shape_refusals.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_stats_not_backtests.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_stats_values.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_telemetry_stream.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_trust_boundary.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_ui_app.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_ui_engine.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_uncorrected_effect.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_unnamed_inputs.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_versions_not_figures.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_vocabulary_friction.py +0 -0
- {hypgraph-0.7.12 → hypgraph-0.7.14}/tests/test_workflows.py +0 -0
|
@@ -1,5 +1,54 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.14 — 2026-10-31: the verifier trusts its caller's policy, and derived screens say they are as exported
|
|
4
|
+
|
|
5
|
+
- **The verifier trusts its caller's policy, not the bundle's.** A re-audit of 0.7.13 found that the bundle and
|
|
6
|
+
browser verifiers took the importer's name from the bundle's `policy`, which the chain doesn't cover. Older events
|
|
7
|
+
don't vouch for the author of a node the importer wrote, so naming a historical writer the importer let an edited
|
|
8
|
+
bundle re-attribute that writer's nodes, and it still verified against the published head. Now the default
|
|
9
|
+
importer is used unless the caller supplies a policy (`hypgraph verify --policy FILE` / `--importer NAME`,
|
|
10
|
+
`verify_bundle(b, policy=…)`, `verifyBundle(b, head, {policy})`); every supplied field must match the bundle's, and a
|
|
11
|
+
different stated importer is reported. `--standing` derives under the supplied policy and names the fields it took
|
|
12
|
+
from the bundle on trust (`tests/test_verify_trust.py`).
|
|
13
|
+
- **Coverage is stated at the top.** Every result says `coverage: complete` or `partial` (fields no event vouched
|
|
14
|
+
for, or redacted events); the CLI prints it, and the explorer shows a *partial coverage* badge.
|
|
15
|
+
- **Reports, stages and work orders are labelled as exported.** The explorer's Overview, Pipeline, Evidence, Work
|
|
16
|
+
orders and Report screens say, for a bundle, that what they show is as exported and not verified, and how to
|
|
17
|
+
re-derive it; the Report's subtitle no longer says its interpretation is checked. `dev/ui_smoke.py` fails a bundle
|
|
18
|
+
view that drops the label.
|
|
19
|
+
- **Sequence numbers must run 1 to n**, in bundles and graph files: they aren't hashed, so a relabelled or gapped log
|
|
20
|
+
now fails.
|
|
21
|
+
|
|
22
|
+
## 0.7.13 — 2026-10-31: verification checks every row, and examples for agent frameworks
|
|
23
|
+
|
|
24
|
+
- **Verification checks every row, both ways.** A pre-launch audit found that `verify_bundle`, `verify_file` and
|
|
25
|
+
the browser's `verifyBundle` only checked that each row present matched an event. A bundle or graph file with a
|
|
26
|
+
withdrawal, a version, a link, a lease or a whole table removed still verified, so a withdrawn claim could come
|
|
27
|
+
back to life through `load()`; changed authors, times, link ends, reasons and duplicated rows passed too. Now every
|
|
28
|
+
row must be written by an event and match it field by field, every row an event wrote must be present, and no key
|
|
29
|
+
may appear twice, in Python, SQLite and the browser alike (`tests/test_verify_complete.py`, which also checks the
|
|
30
|
+
browser verifier agrees on every case).
|
|
31
|
+
- **Events hash every field of the row they write.** New events carry `reason_sha` (create, revise), `why_sha`
|
|
32
|
+
(link, retract, withdraw), `note_sha` (leases), a review's `code` and `inv`, and `as` when the importer credits
|
|
33
|
+
another author. Only the importer may. Older records still verify: what their events don't cover is reported as
|
|
34
|
+
`unchecked`, field by field, instead of passing silently.
|
|
35
|
+
- **Derived views are checked; standing is labelled.** A bundle's `derived` views must agree with the verified rows
|
|
36
|
+
on every fact the rows fix (nodes, live links, titles, authors, times, withdrawn or not); an edited view fails.
|
|
37
|
+
Standing can't be checked from the rows, so the result says `standing: {checked: false}`; `hypgraph verify
|
|
38
|
+
--standing` re-derives it with the same engine version and fails on a difference. The explorer shows a separate
|
|
39
|
+
"standing as exported" badge beside the verified one, and a banner over a record that doesn't verify.
|
|
40
|
+
- **The verify page takes a published head** and lists the fields an older record doesn't cover.
|
|
41
|
+
|
|
42
|
+
- **A LangChain example** (`examples/frameworks/langchain_agent.py`): `create_agent` with the record's tools from a
|
|
43
|
+
`MultiServerMCPClient` session, the same story as the others. It runs in the `frameworks` CI job.
|
|
44
|
+
- **Examples for agent frameworks** (`examples/frameworks/`): LangGraph, PydanticAI, CrewAI, the OpenAI Agents SDK
|
|
45
|
+
and the Claude Agent SDK, each connected to a record through `hypgraph mcp`. All five tell the same story: the
|
|
46
|
+
agent claims a 1.2-point difference is significant, the record refuses with the arithmetic, and the agent writes
|
|
47
|
+
the honest claim, which is accepted. They run offline with a scripted model through each framework's own
|
|
48
|
+
tool-calling path, or with `--real` on a real model. The README covers the one setting each framework needs so a
|
|
49
|
+
refusal reaches the model instead of ending the run. A new CI job runs them all (the Claude Agent SDK, which has no
|
|
50
|
+
scripted mode, gets a wiring check).
|
|
51
|
+
|
|
3
52
|
## 0.7.12 — 2026-10-31: the trust boundary, verification and docs, reviewed before launch
|
|
4
53
|
|
|
5
54
|
A pre-launch review of who may write as whom, through every interface. Each fix has a test that failed first
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: hypgraph
|
|
3
|
-
Version: 0.7.
|
|
3
|
+
Version: 0.7.14
|
|
4
4
|
Summary: The evidence layer for AI research agents: a hash-chained research record that checks every claim as it is written and derives how well each is known.
|
|
5
5
|
Project-URL: Homepage, https://hypgraph.com
|
|
6
6
|
Project-URL: Documentation, https://hypgraph.com/engineers/
|
|
@@ -180,6 +180,10 @@ the record from its checker until it is returned. The method is in [AGENTS.md](h
|
|
|
180
180
|
[llms.txt](https://hypgraph.com/llms.txt). What the server enforces, and what it leaves to you, is in
|
|
181
181
|
[SECURITY.md](https://github.com/voodoomods/hypgraph/blob/main/SECURITY.md).
|
|
182
182
|
|
|
183
|
+
Runnable examples for LangChain, LangGraph, PydanticAI, CrewAI, the OpenAI Agents SDK and the Claude Agent SDK, each
|
|
184
|
+
the same story wired a different way, are in
|
|
185
|
+
[examples/frameworks](https://github.com/voodoomods/hypgraph/tree/main/examples/frameworks).
|
|
186
|
+
|
|
183
187
|
## Wire it into your system
|
|
184
188
|
|
|
185
189
|
The core is one Python package with no dependencies. You decide who is trusted to do what:
|
|
@@ -148,6 +148,10 @@ the record from its checker until it is returned. The method is in [AGENTS.md](h
|
|
|
148
148
|
[llms.txt](https://hypgraph.com/llms.txt). What the server enforces, and what it leaves to you, is in
|
|
149
149
|
[SECURITY.md](https://github.com/voodoomods/hypgraph/blob/main/SECURITY.md).
|
|
150
150
|
|
|
151
|
+
Runnable examples for LangChain, LangGraph, PydanticAI, CrewAI, the OpenAI Agents SDK and the Claude Agent SDK, each
|
|
152
|
+
the same story wired a different way, are in
|
|
153
|
+
[examples/frameworks](https://github.com/voodoomods/hypgraph/tree/main/examples/frameworks).
|
|
154
|
+
|
|
151
155
|
## Wire it into your system
|
|
152
156
|
|
|
153
157
|
The core is one Python package with no dependencies. You decide who is trusted to do what:
|
|
@@ -109,7 +109,7 @@ claim's derived standing.
|
|
|
109
109
|
Multi-writer sync between graphs (bundles cover sharing), authentication (the host's job; the HTTP server binds to
|
|
110
110
|
loopback and is read-only unless started with `--writable`), and a hosted service.
|
|
111
111
|
|
|
112
|
-
## Status at 0.7.
|
|
112
|
+
## Status at 0.7.14 (2026-10-31)
|
|
113
113
|
|
|
114
114
|
All seven phases are done: the library, bundles, the server and UI, the MCP server, the website, Pegasus running on
|
|
115
115
|
the package, and releases to PyPI from tags with trusted publishing. What came after the plan, by release, is in
|
|
@@ -4,6 +4,28 @@
|
|
|
4
4
|
#61 (docs and release engineering). Everything marked as tested was run; the commands are in each PR. Nothing here
|
|
5
5
|
was taken from a changelog without being checked against the code.*
|
|
6
6
|
|
|
7
|
+
> **Superseded in part (2026-10-31, later the same day).** A second audit found that verification checked rows
|
|
8
|
+
> against events in one direction only: a bundle or graph file with a withdrawal, a version, an edge or a whole
|
|
9
|
+
> table removed still verified, as did changed authors, times, link ends and reasons, and edited derived views. That
|
|
10
|
+
> was a confirmed integrity defect, so the GO below didn't hold for 0.7.12. The fix (exhaustive row checks in the
|
|
11
|
+
> Python, SQLite and browser verifiers, events that hash every row field, derived views checked against the rows,
|
|
12
|
+
> standing reported as not covered) is in the pull request that adds `tests/test_verify_complete.py`, and ships as
|
|
13
|
+
> 0.7.13. The recommendation stands again once that is merged with green CI and released.
|
|
14
|
+
>
|
|
15
|
+
> **Where that stands.** #66 is merged with green CI (17 of 17 checks); on main the suite is 386 passed, and
|
|
16
|
+
> hypswarm, hypmesh and hypdmz pass on it. Released as 0.7.13. The required-checks setting (condition 3 below) is
|
|
17
|
+
> still open, for the operator.
|
|
18
|
+
|
|
19
|
+
> **Re-audit of 0.7.13 (2026-10-31).** Confirmed: the deletion and field defects are closed. Two gaps remained, both
|
|
20
|
+
> reproduced and both fixed for 0.7.14: the verifier took the importer from the bundle's own (unhashed) policy, which
|
|
21
|
+
> let an edited legacy bundle re-attribute a historical writer's nodes against the published head; and reports,
|
|
22
|
+
> stages and work-order status were shown beside the verified badge without saying they are as exported. Sequence
|
|
23
|
+
> numbers must now run 1 to n. Tests: `tests/test_verify_trust.py`, `dev/ui_smoke.py`. The required-checks setting is
|
|
24
|
+
> still open, for the operator.
|
|
25
|
+
>
|
|
26
|
+
> **Where that stands.** #68 is merged with green CI (17 of 17 checks); the suite is 399 passed, and hypswarm and
|
|
27
|
+
> hypmesh pass on it. Released as 0.7.14.
|
|
28
|
+
|
|
7
29
|
## Recommendation: CONDITIONAL GO
|
|
8
30
|
|
|
9
31
|
HypGraph is ready for a public developer preview once #59, #60 and #61 are merged with green CI and released as one
|
|
@@ -78,19 +78,46 @@ where `prev` is the previous event's hash (64 zeros for the first). Kinds and pa
|
|
|
78
78
|
|
|
79
79
|
| kind | ref | payload |
|
|
80
80
|
|---|---|---|
|
|
81
|
-
| `create` | the new node | `{type, code, inv, v: 1, body_sha}`; `body_sha` = sha256 of the version's stored body string |
|
|
82
|
-
| `revise` | the node | `{v, reason, body_sha}` |
|
|
83
|
-
| `review` | the reviewed node | `{review: <review node id>, verdict, on_v, official, body_sha}` |
|
|
84
|
-
| `link` | the edge's source | `{edge, rel, dst, src_v, dst_v, data_sha}`; `data_sha` = sha256 of the stored edge data string |
|
|
85
|
-
| `retract` | the edge's source | `{edge}` |
|
|
86
|
-
| `withdraw` | the node | `{why}` |
|
|
87
|
-
| `lease_take` / `lease_release` | the node | `{task, expires}` |
|
|
88
|
-
|
|
89
|
-
Any event may carry `task` in its payload: the unit of work that wrote it.
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
81
|
+
| `create` | the new node | `{type, code, inv, v: 1, body_sha, reason_sha, as?}`; `body_sha` = sha256 of the version's stored body string, `reason_sha` of its stored reason |
|
|
82
|
+
| `revise` | the node | `{v, reason, body_sha, reason_sha}`; `reason` is the first 300 characters |
|
|
83
|
+
| `review` | the reviewed node | `{review: <review node id>, verdict, on_v, official, body_sha, code, inv, as?}` |
|
|
84
|
+
| `link` | the edge's source | `{edge, rel, dst, src_v, dst_v, data_sha, why_sha}`; `data_sha` = sha256 of the stored edge data string, `why_sha` of its stored reason |
|
|
85
|
+
| `retract` | the edge's source | `{edge, why_sha}` |
|
|
86
|
+
| `withdraw` | the node | `{why, why_sha, as?}`; `why` is the first 300 characters, `why_sha` covers the stored reason |
|
|
87
|
+
| `lease_take` / `lease_release` | the node | `{task, expires, note_sha, for?}`; `for` = the agent holding the lease when it isn't the actor |
|
|
88
|
+
|
|
89
|
+
Any event may carry `task` in its payload: the unit of work that wrote it. `as` appears only when the importer
|
|
90
|
+
credits a node or withdrawal to another author; from any other actor it is invalid.
|
|
91
|
+
|
|
92
|
+
**Verifying** a record means recomputing every hash in order and checking each `prev`, then checking the rows
|
|
93
|
+
against the events **both ways**: every row was written by an event and matches it field by field, every row an
|
|
94
|
+
event wrote is present, and no key appears twice. The fields each event fixes:
|
|
95
|
+
|
|
96
|
+
| table | key | must equal |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| `nodes` | `create.ref`, `review.payload.review` | `type`, `code`, `inv` from the payload (a review: type `review`); `created_at` = the event's `at`; `created_by` = the actor, or `as` |
|
|
99
|
+
| `versions` | node + `v` | `at`, `by` = the actor, sha256 of `body` = `body_sha`, sha256 of `reason` = `reason_sha` (a review's: empty) |
|
|
100
|
+
| `edges` | `payload.edge` | `src` = ref, `rel`, `dst`, `src_v`, `dst_v`, `at`, `by` = the actor, sha256 of `data` = `data_sha`, of `why` = `why_sha` |
|
|
101
|
+
| `withdrawals` | the node | `at`, `by` = the actor or `as`, sha256 of `why` = `why_sha` |
|
|
102
|
+
| `retractions` | `payload.edge` | `at`, `by` = the actor, sha256 of `why` = `why_sha` |
|
|
103
|
+
| `leases` | in id order, one per lease event in order | `node` = ref, `agent` = `for` or the actor, `task`, `kind` (`take` / `release`), `at`, `expires`, sha256 of `note` = `note_sha` |
|
|
104
|
+
|
|
105
|
+
Records written before these fields existed (before 0.7.13) carry events without `reason_sha`, `why_sha`,
|
|
106
|
+
`note_sha`, `as`, or a review's `code` and `inv`. A verifier checks what those events do carry (a revision's or a
|
|
107
|
+
withdrawal's first 300 characters, a lease note given in full, a review's investigation from its target) and
|
|
108
|
+
reports every other non-empty field as **not covered**, by table and field, rather than passing it silently. Without
|
|
109
|
+
`as`, a row the importer wrote may credit any author; that is reported too. A verifier states at the top level
|
|
110
|
+
whether every row field was vouched for by its event (`coverage: complete`) or not (`partial`: fields not covered,
|
|
111
|
+
or redacted events).
|
|
112
|
+
|
|
113
|
+
**What a verifier trusts.** Who the importer is decides which older rows may credit another author, so the importer
|
|
114
|
+
belongs to what a verifier trusts, and the chain doesn't cover a bundle's `policy`. A verifier must not take the
|
|
115
|
+
importer, or any other policy field, from the bundle: it uses a policy its caller supplies (from the record's
|
|
116
|
+
publisher or host), and the default importer name `importer` otherwise. Every field the caller supplies must equal
|
|
117
|
+
the bundle's stated one. When the bundle names a different importer, the verifier says so.
|
|
118
|
+
|
|
119
|
+
**Sequence numbers** (`seq`) label events but aren't hashed: the order is fixed by `prev`. A verifier requires them
|
|
120
|
+
to run 1 to n, so a relabelled or gapped log fails.
|
|
94
121
|
|
|
95
122
|
## 4. Bundles — `hypgraph/1-bundle`
|
|
96
123
|
|
|
@@ -108,7 +135,7 @@ strings and compares.
|
|
|
108
135
|
"versions": [{"node": "…", "v": 1, "at": "…", "by": "…", "reason": "", "body": "<stored canonical string>"}],
|
|
109
136
|
"edges": [{"id": 1, "src": "…", "src_v": 1, "rel": "…", "dst": "…", "dst_v": 1, "data": "<stored string>", "…": "…"}],
|
|
110
137
|
"withdrawals": [], "retractions": [], "leases": [],
|
|
111
|
-
"derived": {"…": "
|
|
138
|
+
"derived": {"…": "views for viewers; their facts are checked against the rows, their standing is not"}}
|
|
112
139
|
```
|
|
113
140
|
|
|
114
141
|
A **scoped** bundle (one investigation out of a shared record) replaces events outside it with
|
|
@@ -123,6 +150,16 @@ or a prefix of at least 16 hex characters) fails unless the chain ends there: `h
|
|
|
123
150
|
`verify_bundle(b, head=HEX)`. A bundle without a `head` field is checked for consistency only. How a head is
|
|
124
151
|
published and signed, and what each check does and doesn't show: [verification.md](verification.md).
|
|
125
152
|
|
|
153
|
+
**Derived views.** `derived` is a convenience for viewers, and a viewer shows it beside a verified chain, so a
|
|
154
|
+
verifier must check every fact in it that the rows fix: which investigations it covers (the scope's, or every
|
|
155
|
+
investigation node), which nodes each investigation's graph shows (all of them, unless capped at 5,000) and which
|
|
156
|
+
live (unretracted) links among them, each node's `type`, `code`, `inv`, `by`, `at`, `v`, `title` and `kind`, whether
|
|
157
|
+
it is shown as withdrawn, and each link's fields. **Standing** (review state, support, at-risk, the sentence) can't
|
|
158
|
+
be checked from the rows alone: it is what the exporting engine derived, and so are the report, the workflow stages,
|
|
159
|
+
completion, the question board and work-order status. A verifier reports them as not checked, or re-derives them with
|
|
160
|
+
the same engine version (`hypgraph verify FILE --standing`, under the caller's policy with `--policy`) and compares.
|
|
161
|
+
A viewer must label them as exported wherever it shows them from a bundle.
|
|
162
|
+
|
|
126
163
|
## 5. Derived standing (normative)
|
|
127
164
|
|
|
128
165
|
Implementations must derive these, never store them:
|
|
@@ -8,7 +8,7 @@ somewhere its keeper can't change.
|
|
|
8
8
|
|
|
9
9
|
| | What it shows | How | What it doesn't show |
|
|
10
10
|
|---|---|---|---|
|
|
11
|
-
| **1. Internal consistency** | The chain of events is unbroken
|
|
11
|
+
| **1. Internal consistency** | The chain of events is unbroken; every node, version, link, withdrawal, retraction and lease was written by an event and matches it field by field; no row an event wrote is missing; and the facts a viewer shows beside it (which nodes and links, titles, authors, times, withdrawn or not) agree with those rows. | `hypgraph verify study.bundle.json` (or a graph file), `verify_bundle(b)` in Python, `HypGraph.verifyBundle` in the browser | That it wasn't rewritten. Whoever can write the record can change it, recompute every hash, or cut it short, and it still verifies. |
|
|
12
12
|
| **2. Not rewritten since it was published** | The record ends at the head that was published. Any change to anything before it, or a record cut short, ends somewhere else. | `hypgraph verify study.bundle.json --head <published head>`, `verify_bundle(b, head=...)`, `anchored(g.verify(), head)` | Who published that head. That's the job of where it was published (below). |
|
|
13
13
|
| **3. Provenance of the evidence** | Who recorded what, and how: a lab-recorded run (only the instrument author files those) or an agent's report, its inputs and outputs by hash, which lines of support are independent. | The record's derived standing: `hypgraph show CL1 --why`, the report | That the instrument's own files are honest. A host decides who the instrument is (the policy). |
|
|
14
14
|
| **4. That a claim is true** | Nothing. | Reviews, replications, separate implementations, new data: the evidence the record keeps and ranks | — |
|
|
@@ -24,11 +24,12 @@ claims in it stand exactly as well as the record derives, and no better.
|
|
|
24
24
|
$ hypgraph demo && hypgraph export -o study.bundle.json
|
|
25
25
|
Wrote study.bundle.json: 59 events, 24 nodes
|
|
26
26
|
$ hypgraph verify study.bundle.json
|
|
27
|
-
✓ study.bundle.json: 59 events verified — chain intact, every row matches the event that wrote it.
|
|
27
|
+
✓ study.bundle.json: 59 events verified — chain intact, every row matches the event that wrote it, and none is missing.
|
|
28
28
|
head 565123f3a7ac06ed18ab555935fde0457ebb6a302dc188fc83dbf36af579623f
|
|
29
29
|
consistent with itself; to rule out a rewrite, check it against a published head (--head)
|
|
30
|
+
standing not checked: standing (review state, support, at-risk, the sentence) is what the exporting engine derived: …
|
|
30
31
|
$ hypgraph verify study.bundle.json --head 565123f3a7ac06ed
|
|
31
|
-
✓ study.bundle.json: 59 events verified — chain intact, every row matches the event that wrote it.
|
|
32
|
+
✓ study.bundle.json: 59 events verified — chain intact, every row matches the event that wrote it, and none is missing.
|
|
32
33
|
head 565123f3a7ac06ed18ab555935fde0457ebb6a302dc188fc83dbf36af579623f
|
|
33
34
|
matches the anchored head: not rewritten or cut short since it was published
|
|
34
35
|
```
|
|
@@ -67,6 +68,25 @@ SHA-256 over strings and compares: no JSON canonicalisation to reimplement. The
|
|
|
67
68
|
and the verifier's rules, is in [spec.md](spec.md). The site checks bundles in the browser with WebCrypto, from a
|
|
68
69
|
separate implementation.
|
|
69
70
|
|
|
71
|
+
## Standing, and older records
|
|
72
|
+
|
|
73
|
+
- **Standing** (review state, support, at-risk, the one-line summary) is derived, and a bundle carries the standing
|
|
74
|
+
its exporter derived. The chain doesn't cover it. `hypgraph verify study.bundle.json --standing` replays the
|
|
75
|
+
verified rows and derives it again; it fails if the result differs. Standing rules change between releases, so it
|
|
76
|
+
only compares a bundle exported by the same version, and says so otherwise. A graph file has no stored standing:
|
|
77
|
+
it is derived on every read.
|
|
78
|
+
- **Records written before 0.7.13** have events that don't hash a few row fields (a link's reason, a retraction's
|
|
79
|
+
reason, a lease note, a revision's full reason, the credited author of an importer's node). The verifier checks
|
|
80
|
+
what those events carry and lists the rest as *not covered*, with a count per field. Rewriting one of those fields
|
|
81
|
+
in an old record isn't caught; new writes cover them all. The result says `coverage: partial` at the top, and the
|
|
82
|
+
explorer shows a *partial coverage* badge beside *verified*.
|
|
83
|
+
- **The bundle's own policy isn't trusted.** Who the importer is decides which older rows may credit another author,
|
|
84
|
+
and the chain doesn't cover a bundle's `policy`. The verifier uses the default importer, or the policy you give it:
|
|
85
|
+
`hypgraph verify study.bundle.json --policy policy.json` (or `--importer NAME`), and every field you give must
|
|
86
|
+
match the bundle's. `--standing` derives under that policy and names the fields it took from the bundle on trust.
|
|
87
|
+
- **The report, stages and work orders** in a bundle are derived like standing. The explorer labels each of those
|
|
88
|
+
screens *as exported, not verified*; `--standing` re-derives and compares them.
|
|
89
|
+
|
|
70
90
|
## Scoped bundles and references
|
|
71
91
|
|
|
72
92
|
- `hypgraph export --inv INV` writes one investigation. Events outside it are redacted to their hash, so the chain
|
|
@@ -79,5 +99,7 @@ separate implementation.
|
|
|
79
99
|
|
|
80
100
|
`dev/e2e_install.py` installs HypGraph into a fresh environment and walks the whole path: a record, a claim accepted
|
|
81
101
|
and one refused, a review, an export, and verification in another directory with no graph file, on its own and
|
|
82
|
-
against the head, and failing on an edited copy. `tests/
|
|
102
|
+
against the head, and failing on an edited copy. `tests/test_verify_complete.py` drops, duplicates, empties and
|
|
103
|
+
edits every table and every field of a bundle and of a graph file, and edits the derived views: each one fails, in
|
|
104
|
+
Python and in the browser verifier alike. `tests/test_anchoring.py` rewrites a record (changing a claim and
|
|
83
105
|
recomputing every hash) and cuts one short: both verify on their own, and both fail against the published head.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# HypGraph with agent frameworks
|
|
2
|
+
|
|
3
|
+
One story, told once per framework, so the difference between the files is only the wiring.
|
|
4
|
+
|
|
5
|
+
An eval harness has compared two models on the same 1,000 held-out questions: model A got 812 right, model B 800.
|
|
6
|
+
An agent, connected to the record over MCP as the author `analyst`, is asked whether A is more accurate. It writes
|
|
7
|
+
"significantly more accurate". The record refuses that with the arithmetic (p ≈ 0.5) and says what to write instead.
|
|
8
|
+
The agent writes the honest claim, and it is accepted. Afterwards the script reads the record in Python and prints
|
|
9
|
+
what was refused, what was accepted, and the refusal log.
|
|
10
|
+
|
|
11
|
+
The framework doesn't need to know HypGraph exists. It sees MCP tools, and the record does the checking.
|
|
12
|
+
|
|
13
|
+
| Framework | File | Install | MCP wiring |
|
|
14
|
+
|---|---|---|---|
|
|
15
|
+
| LangChain | [langchain_agent.py](langchain_agent.py) | `langchain langchain-mcp-adapters` | `MultiServerMCPClient` session → `create_agent` |
|
|
16
|
+
| LangGraph | [langgraph_agent.py](langgraph_agent.py) | `langgraph langchain-mcp-adapters` | `load_mcp_tools(session)` into a `ToolNode` |
|
|
17
|
+
| PydanticAI | [pydantic_ai_agent.py](pydantic_ai_agent.py) | `"pydantic-ai-slim[mcp]"` | `MCPToolset(StdioTransport(...))` |
|
|
18
|
+
| CrewAI | [crewai_agent.py](crewai_agent.py) | `crewai` | `Agent(mcps=[MCPServerStdio(...)])` |
|
|
19
|
+
| OpenAI Agents SDK | [openai_agents_sdk.py](openai_agents_sdk.py) | `openai-agents` | `Agent(mcp_servers=[MCPServerStdio(...)])` |
|
|
20
|
+
| Claude Agent SDK | [claude_sdk_agent.py](claude_sdk_agent.py) | `claude-agent-sdk` | `ClaudeAgentOptions(mcp_servers={...})` |
|
|
21
|
+
|
|
22
|
+
Every example also needs `pip install "hypgraph[mcp]"`. [_story.py](_story.py) holds what they share: the record
|
|
23
|
+
before the agent arrives, the task, the server command, and the check at the end.
|
|
24
|
+
|
|
25
|
+
## Run them
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
cd examples/frameworks
|
|
29
|
+
python langgraph_agent.py # scripted model: offline, free, the same every time
|
|
30
|
+
python langgraph_agent.py --real --model gpt-4.1-mini
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
With no flags, a scripted model plays a careful agent's moves through the framework's own tool-calling path:
|
|
34
|
+
read the overview, overclaim, read the refusal, write the honest claim. That shows the wiring works, including the
|
|
35
|
+
part that matters most, a refused write getting back to the model. It can't show a model reasoning. `--real` uses a
|
|
36
|
+
real model (`OPENAI_API_KEY`, or whatever the framework's model string needs; `--model` or `MODEL` picks it). A real
|
|
37
|
+
model passes if it got a claim accepted and fixed every refusal, because a careful model may write the honest claim
|
|
38
|
+
the first time.
|
|
39
|
+
|
|
40
|
+
`--db FILE` keeps the record, so you can open it afterwards with `hypgraph --db FILE serve`.
|
|
41
|
+
|
|
42
|
+
The Claude Agent SDK drives Claude Code itself and has no scripted mode. `python claude_sdk_agent.py` is a real run
|
|
43
|
+
(Claude Code signed in, or `ANTHROPIC_API_KEY`; `--model` takes `haiku`, `sonnet` or `opus`). `--check` starts the
|
|
44
|
+
record's server from the exact options the SDK would use and confirms every allowed tool exists. That needs no model.
|
|
45
|
+
|
|
46
|
+
## What to copy
|
|
47
|
+
|
|
48
|
+
- **One server per author.** `hypgraph --db FILE --as analyst mcp` writes as `analyst` and nothing else. The agent
|
|
49
|
+
can't pass another name, and its verdicts count only if the investigation names it as a reviewer. Give each agent
|
|
50
|
+
in a team its own server, with its own author.
|
|
51
|
+
- **Let a refusal reach the model.** A refused write is an MCP tool error whose text names the problem and the fix
|
|
52
|
+
(for example `[SIGNIFICANCE_NOT_SHOWN]`). If the framework ends the run on a tool error, the agent never sees it:
|
|
53
|
+
- LangChain: `load_mcp_tools(session, handle_tool_errors=True)`, the adapter's default, returns it as the tool's
|
|
54
|
+
output, so `create_agent` needs nothing more. Hold one `client.session(...)` for the run: `client.get_tools()`
|
|
55
|
+
alone starts a server process for every tool call.
|
|
56
|
+
- LangGraph: `ToolNode(tools, handle_tool_errors=True)`.
|
|
57
|
+
- PydanticAI: the default (`tool_error_behavior="retry"`) sends it back as a retry prompt. `max_retries` bounds it.
|
|
58
|
+
- CrewAI and the OpenAI Agents SDK hand it back as the tool's output by default.
|
|
59
|
+
- Claude Code shows tool errors to the model.
|
|
60
|
+
- **Keep the agent on the record.** The Claude example passes `tools=[]` (no shell, no file edits),
|
|
61
|
+
`strict_mcp_config=True` (no other MCP servers) and pre-approves only the record's tools.
|
|
62
|
+
- **CrewAI names MCP tools after the command line** (`<command>_<args>_<tool>`, hashed past 64 characters). The
|
|
63
|
+
example runs plain `hypgraph mcp` with `HYPGRAPH_DB` and `HYPGRAPH_AUTHOR` in its environment, so the tools come out
|
|
64
|
+
as `hypgraph_mcp_add` and so on.
|
|
65
|
+
|
|
66
|
+
Frameworks that take plain Python functions as tools can skip MCP. Call `Graph` directly and return the refusal text
|
|
67
|
+
from `GraphError`; see [hypgraph.com/engineers](https://hypgraph.com/engineers/#connect).
|
|
68
|
+
|
|
69
|
+
Tested with langchain 1.4, langgraph 1.2, pydantic-ai 2.x, crewai 1.15, openai-agents 0.20 and claude-agent-sdk 0.2 (the scripted
|
|
70
|
+
runs, and the Claude `--check`, run in CI).
|
|
@@ -16,7 +16,7 @@ Standing is derived on every read, never stored; every write is an event in a SH
|
|
|
16
16
|
their numbers; reviews pin versions; independence is counted, not assumed. See https://hypgraph.com.
|
|
17
17
|
"""
|
|
18
18
|
|
|
19
|
-
__version__ = "0.7.
|
|
19
|
+
__version__ = "0.7.14"
|
|
20
20
|
|
|
21
21
|
from .bundle import anchored, verify_bundle # noqa: E402
|
|
22
22
|
from .graph import Author, Graph, GraphError, file_sha256 # noqa: E402
|