horsegraph
Install this stable release from PyPI with
python -m pip install horsegraph==0.3.2.
The normal unversioned install also selects the current stable release.
Then start with horsegraph examples for complete offline Enyalcalma demos.
0.3.2 stable
Reads graphs that keep their links in edges, warns when a state has no status, finds a project's graph where Tiny Horse's park gate looks, and reports Tiny Horse's named defects. Tall dependency depths wrap into more columns. See the changelog. Assessments remain declared judgments: current bindings establish unchanged records, not source authenticity or semantic correctness. External source bytes require separate verify. Its ok reports byte-check agreement, complete requires a passing anchored v2 reference scope, and success controls CLI policy; partial CLI success still requires --allow-partial.
Desktop and simulated-touch checks do not close physical-iPhone, full VoiceOver, other-browser or wider platform acceptance. Stable versioning does not expand those tested limits.
Quick start (installed package)
horsegraph examples # list the complete examples
horsegraph examples macbeth --out "Macbeth example" # copy one into a new directory
cd "Macbeth example"
horsegraph enyalcalma --file ENYALCALMA-MACBETH.json --out regenerated.html
horsegraph verify --file ENYALCALMA-MACBETH.json --sources-dir sources/macbeth --reference macbeth
Open macbeth.html in a browser. regenerated.html is byte-identical to it, and
verify checks that each quotation is exactly the stated bytes of the retained
edition (byte-exactness only; meaning and source authenticity are not checked).
README.md and GUIDE.md in the copy explain the evidence and its limits;
horsegraph examples typescript-to-rust --out "Port example" copies the second
example. Nothing here needs a repository, network access or credentials.
Read installed documentation offline with horsegraph docs (guide),
horsegraph docs graph, horsegraph docs enyalcalma, horsegraph docs symbols,
or horsegraph docs plain-english. Paths such as docs/ENYALCALMA.md also name
files in the source distribution; they are not wheel-relative filesystem links.
What it is, and installing it
Plan node graphs (NODE-GRAPH.json) read through Tiny Horse canonical storage and visualized as ClaySpace worlds.
- Tiny Horse is the source of truth. horsegraph reads the graph from a bound checkout (and can run
tinyhorse doctoron it), or straight from the canonical bundle in storage (file:orgdrive://), or from a Drive project by name. When it reads from storage it fetches and verifies the bundle and reads the graph at canonical HEAD, so the view shows what was parked, not unparked local edits. - ClaySpace draws it. Every node is a ClaySpace Cell, every dependency is a Cell with an arrowhead, and the whole graph is a valid
clayspace.world.snapshot. The HTML is ClaySpace's own self-contained orbit preview, plus a label, hover-detail and legend overlay.
pip install horsegraph # stable release; add [gdrive] for Drive storage
# For a development build, install its explicitly selected version or candidate wheel.
Use
# from a TinyHorse-bound checkout, with an explicit graph path
horsegraph render --checkout . --graph NODE-GRAPH.json --doctor --out plan.html --world plan.world.json
# straight from canonical storage, no checkout needed
horsegraph render --storage gdrive://FOLDER_ID/Demo.bundle
horsegraph render --project "Demo" # resolved like `tinyhorse claim`
# plan views
horsegraph next --checkout . # "Needs you now" / "Claude starts next"
horsegraph path --checkout . # critical path to the goal node
horsegraph check --checkout . # validate; exit 1 on warnings (e.g. done before its deps)
# any JSON file, no TinyHorse service/project or credentials required
horsegraph render --file my-graph.json
render and enyalcalma require new output paths, including --world.
--graph names a relative path resolving inside the repo; --ref reads a tag or commit from storage instead of HEAD.
The ClaySpace world it writes with --world opens with the usual tools (clayspace world inspect, clayspace world preview).
Enyalcalma comparison viewer
Read an interpretation beside its linked source, with authored challenges and competing responses. The HTML works offline and leaves its input unchanged:
horsegraph enyalcalma --file my-comparison.json --select interpretation --out comparison.html
Existing NodeGraph files work without a comparison mapping; no roles are inferred.
The reading contract and examples (docs/ENYALCALMA.md) explain optional display
roles, provenance, missing evidence and keyboard-accessible inspection. All assets
and complete offline example packs are included in the wheel. Single-file example
graphs (including the Anakin story and the cache-decision comparison) are installed
under importlib.resources.files("horsegraph") / "examples"; horsegraph examples
prints that directory and describes each file.
Reading the 3D view
| Shape | Meaning |
|---|---|
| low green slab | done |
| blue block | open, Claude's (agent) node |
| tall amber tower with a flagpole | open owner action, needs you |
| cyan | on the critical path to the goal |
| pink + sphere | goal node |
| grey, thin | parked (later, after-proof) |
Flat graphs use columns by dependency depth and rows grouped by track. Graphs with
parent relationships use nested regions and a containment outline. Borders and
indentation mean containment; solid arrows mean prerequisites and dashed arrows
mean authored semantic relations. Drag to orbit,
scroll to zoom, and hover a label for the node's title, ancestry, deps and contract
items it advances.
Graph format
{
"title": "…", "goal": "G-RELEASE",
"tracks": {"CLI": "Command Line Interface"},
"nodes": [
{"id": "CLI-2", "title": "…", "owner": "agent", "status": "open",
"deps": ["CLI-1", "CORE-2"], "track": "CLI", "closes": ["C2"]}
]
}
owner is agent or owner. status is done, open, later, after-proof or available-verified. Extra fields are kept. Cycles, unknown deps and duplicate ids are rejected.
Optional parent identifies the node containing a record. Missing or null
means a root. Each node has at most one parent; unknown parents, invalid parent
values, and containment cycles are rejected. Containment is independent of
deps: it does not change readiness, blocked state, dependency depth, critical
paths, or completion rules. Existing flat graphs retain their layout.
See horsegraph docs graph for containment, source selection and provenance.
Optional top-level relations express authored links such as challenges,
revises, influenced_by, and supported_by, with explicit IDs and preserved
evidence/provenance. They never change task readiness or imply confidence/truth.
See "Typed relationships" in horsegraph docs graph.
An optional synthetic inquiry/action example ("Optional inquiry example" in docs/GRAPH-REFERENCE.md) records a
bounded proposal, explicit authorization, one manual start, a result and a
subsequent reflection. Its code inspector and read-only spatial history retain
purpose, sources, budgets and unanswered questions. It is an opt-in example,
not part of core graph semantics or an execution engine. This example is included in the source distribution.
Python
from horsegraph import from_storage, render
graph, prov = from_storage("file:/srv/git/demo.bundle")
print(graph.critical_path(), [n.id for n in graph.ready("owner")])
render(graph, "plan.html", provenance=prov.to_dict(), subtitle=prov.summary())
Release
Run the Python, regeneration and complete browser gates in docs/TESTING.md,
then build and verify both distributions. Playwright is an optional maintainer
dependency declared in package.json. Publication requires separate approval.
Graph capabilities
Adds nested containment, authored typed relationships, compact readable labels, full identity/provenance disclosures and robust embedded-canvas initialization. Relationships remain independent of prerequisite readiness and containment.
Public JSON examples are included in the wheel under horsegraph/examples
and can be located with importlib.resources.files("horsegraph").joinpath("examples").
Optional Python adapters and synthetic tests are included in the source distribution.
Archive projection adapters require an operator-supplied source catalog; they
are optional repository examples, not services or bundled reading packs.
Independent connection layers
Independent connection layers ("Connections" in docs/GRAPH-REFERENCE.md) add visibility controls
for containment, prerequisites and semantic relationships, relation-type filters,
and selectable connections with complete endpoint/provenance details.
Macbeth reading example
Compare a passage with what happens in the play, follow the characters’ relationships, then consider two optional readings. Covers Acts 1–2 with spoilers through Duncan’s murder. The exact Project Gutenberg edition and license ship with the example; no online service is required.
Copy it with horsegraph examples macbeth --out "Macbeth example" (see the quick
start above). The reading guide is in docs/ENYALCALMA.md and the edition details
in examples/sources/macbeth/README.md. The current hosted demo is updated
separately; the copied example generates a local review artifact.
From a source checkout
The source distribution and a repository checkout keep the example graphs at
examples/, so these work from its root (an installed package has no such folder;
use the quick start above):
horsegraph render --file examples/NODE-GRAPH.json
horsegraph enyalcalma --file examples/ENYALCALMA-CACHE.json --select interpretation --out comparison.html
horsegraph enyalcalma --file examples/ENYALCALMA-MACBETH.json --out macbeth.html
horsegraph enyalcalma --file examples/ENYALCALMA-ANAKIN.json --select fear --out story.html
Offline verification limits
verify accepts lowercase 64-digit SHA-256 hashes for source and excerpt claims.
Malformed hashes produce a structured provenance failure, never a traceback.
With --json, a graph without byte-range claims returns a JSON report with
status: "no_byte_claims", ok: false, and exit code 2; text mode retains its
explanation on stderr. A completed comparison exits 0 on success or 1 on failure.
Source loading is limited to 64 MiB per file, 256 MiB total bytes read, and 1,024 files across direct sources and recursive directory sources combined. Duplicate content still counts toward the read budget. Oversized files now fail explicitly instead of being silently skipped by directory scanning. Reads remain bounded if files grow. Direct source symlinks and a symlink directory root are refused; recursive symlinks and special files are ignored. No sources are fetched.
Verification coverage and sharing
verify checks byte claims, not truth or whole-graph completeness. Its ok:true
means the supplied claims passed; coverage reports records, claims, verified
passages and uncheckable records. Partial or malformed byte claims fail. Legitimate
non-quotation records and whole-file references without ranges remain uncheckable.
Without an independent v2 reference, wholly removed or coherently repointed claims cannot be ruled out. Prefer --reference macbeth or --reference typescript-to-rust from a trusted installation. For external v2 references, retain the manifest SHA-256 independently and use --expect-claims reference.json --expect-sha256 HEX; deriving a digest from the file being reviewed provides no independent trust.
Compatibility change in 0.3.0.dev25: ok still means all present/required byte checks passed. complete means every required v2 content binding passed against a verified anchor, only within that reference scope. coverage.state is reference_complete, partial, or failed; success is the CLI exit policy. Exit 0 requires complete:true or explicit --allow-partial with ok:true. Exit 1 means a failed check or partial coverage without opt-in; exit 2 means invalid input or no byte claims. --allow-partial never hides failures. The API preserves its ok contract and reports complete:false because it does not independently establish the caller's trust anchor.
V1 references require IDs only and cannot bind their content, even when their file digest is pinned. Unanchored v2 references bind content to the supplied editable manifest but cannot establish its integrity. Both remain partial. Extra recognized byte claims are checked; legitimate uncheckable/nonquotation records outside the reference scope do not make a valid pinned scope incomplete. Neither completeness nor source-byte agreement establishes authenticity, authorship, semantic truth, or whole-graph completeness.
next reports unsupported owners and exits 1 on graph warnings. It exposes
available-verified records separately: they are neither ready tasks nor done,
and do not satisfy prerequisites. No owner/status aliases are inferred. path
returns the longest dependency chain to the goal, not a time estimate; path --json emits it as JSON.
--ref is for --storage/--project; --doctor is for checkouts. --file cannot
be combined with either option or --graph. With --graph omitted, the graph is
found: the newest horsegraph/horsegraph-v<N>.json, then the other paths listed in
the graph reference, the original checkout default last.
Generated HTML normally retains the supplied input filename/path in provenance.
Use render --file ... --redact-local-path or enyalcalma --file ... --redact-local-path to retain only the basename in generated source metadata.
This does not redact paths or private content authored inside the input: the
complete input, including hidden records and provenance, is still embedded.
Self-contained readers use script-hash CSP and deny network connections. Input escaping remains essential; this defense does not authenticate text or establish that earlier parser-initialization failures were code execution. Offline graph controls remain available. Browser/runtime coverage is recorded separately.
TinyHorse remains an installed Python dependency even for --file; no TinyHorse
service, project or credentials are needed for that route. ClaySpace's exact pin
is intentional for renderer compatibility and reproducibility. The package does
not claim a checked typing contract or ship py.typed.
Content-bound references are available in 0.3.0.dev24:
horsegraph verify --file ... --sources-dir ... --reference macbeth pins all nine
IDs to original source/range/quotation hashes through a verified installation.
For external files, use --expect-claims reference.json --expect-sha256 HEX with
an independently retained digest. V1 ID-only contracts remain compatible. V2
schema, trust limits and exit states are in horsegraph docs graph; copied packs
include offline instructions and references. Checksums do not prove authorship or
semantic truth, and a reference supplied beside a graph is not self-authenticating.
Measured performance and reproducible bounded benchmark instructions: horsegraph docs performance. Full samples and scripts are included in the source distribution.
0.3.0.dev25 input and accounting fixes
Graph file inputs now require a regular non-symlink UTF-8 file no larger than 64 MiB. check, render, enyalcalma, verify, next, path, NodeGraph.load and checkout loading share this contract. Git-storage graph blobs are size-checked before capture and symlink blobs are refused. Reads are bounded if a file grows; this is not a complete filesystem sandbox against ancestor-directory or concurrent replacement races. In-memory JSON bytes also require UTF-8 and the same size limit. Output symlink refusal is unchanged.
stats includes a disjoint count for each of the five statuses; their sum equals nodes. Owner/readiness counts overlap these totals. next reports each blocked prerequisite's exact status; available-verified remains neither done nor ready.
Attributed assessments
Inspect recorded source-identity and claim assessments offline with horsegraph assessments --file GRAPH.json --json. Read them under record Details in Enyalcalma. They preserve examiner attribution, methods, evidence for/against, scope, uncertainty and version bindings. Matching bindings do not authenticate an assessor or establish truth. horsegraph docs graph describes the schema, staleness limits and inspection exit codes. Existing verify byte/coverage/success semantics are unchanged.
Metadata
Release files for horsegraph 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| horsegraph-0.3.2.tar.gz | 617.8 kB | Without provenance | Details for horsegraph-0.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| horsegraph-0.3.2-py3-none-any.whl | Python 3 | none | any | Details for horsegraph-0.3.2-py3-none-any.whl |
Total release size: 1.2 MB
Release files / horsegraph-0.3.2.tar.gz
| Download URL | horsegraph-0.3.2.tar.gz |
|---|---|
| Size | 617.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d5de86381e73a6dec256e975704e45cba0e04acfa95ecae62d87549ba6df87b1
|
|
BLAKE2b-256 checksum How to use checksums |
9c92a3009bdab03ccaa4bd3eb7d7efc3e828d9dd17c46fc2e4fc7cc7fb3c84d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / horsegraph-0.3.2-py3-none-any.whl
| Download URL | horsegraph-0.3.2-py3-none-any.whl |
|---|---|
| Size | 568.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ca7da740c748a579edf32e9c7f833fc9aa2675995ce8acce5136def4f55c1829
|
|
BLAKE2b-256 checksum How to use checksums |
10e80ebb0aabada078c170eda46acf458ca99a65f278d9dc3f8831616bd195ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for horsegraph 0.3.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.