Skip to main content

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 doctor on it), or straight from the canonical bundle in storage (file: or gdrive://), 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)

Source distribution for horsegraph 0.3.2
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)

Table of built distributions (wheels) for horsegraph 0.3.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page