Skip to main content

horsegraph

Install this stable release from PyPI with python -m pip install horsegraph==0.3.0. The normal unversioned install also selects the current stable release. Then start with horsegraph examples for complete offline Enyalcalma demos.

0.3.0 stable

Promotes the tested dev26 behavior without feature changes. 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.

0.3.0.dev26

Record and inspect attributed source/claim assessments with horsegraph assessments and Enyalcalma Details. Evidence bindings expose changed records; scope-aware labels preserve differing assessments without declaring a logical contradiction. Blank identity strings are invalid; use null for unknown identity or scope. Current means bound records are unchanged, not an authenticated source or correct assessment. External source bytes require separate verify; its existing contract is unchanged. No automated investigation, signature authentication or truth verdict is supplied.

0.3.0.dev25

CLI compatibility change: partial byte verification now exits 1 unless you explicitly pass --allow-partial. JSON ok:true still means byte agreement and can accompany exit 1; use success for CLI policy and complete for anchored v2 reference-scope completeness. Prefer --reference macbeth or --reference typescript-to-rust. No mode authenticates authorship or establishes source truth. See Verification coverage and sharing below for exact exit codes.

This release bounds graph-file reads, makes maintained text I/O locale-safe, repairs offline documentation navigation, and accounts for all five graph statuses without changing their meanings.

0.3.0.dev24

Adds versioned content-bound reference verification with independent digest pins, compatible v1 required-ID contracts, and complete offline Macbeth and TypeScript/ Rust verification examples. Every present byte claim is checked; trusted required claims bind IDs to exact source/range/text hashes. Checksums do not establish source authenticity or semantic truth; an unanchored editable reference can be replaced alongside its graph.

Fixes queued help-dialog focus restoration, reports unsupported owners and rejects ignored source-option combinations. Adds explicit UTF-8 reads, bounded explanation inputs, opt-in generated-path redaction, installed documentation and script-hash CSP. Enyalcalma stays read-only and complete-input export disclosure remains.

Removes repeated connection-label counting and includes reproducible bounded performance results. See horsegraph docs performance for measured sizes, ranges, failed setup probes and limitations. Physical-iPhone and VoiceOver acceptance remain open; desktop Chrome/touch emulation does not close them.

0.3.0.dev23

Fixes graph initialization when literal HTML comment/script text appears in node labels, in both standalone graphs and Enyalcalma maps. Original text and IDs are preserved. Invalid goal types now produce a handled graph error (CLI exit 2); missing and null goals retain their existing behavior. Enyalcalma remains read-only.

Adds browser control regressions and public API/CLI goal validation regressions. Desktop Chrome verification does not establish physical-iPhone or VoiceOver acceptance; Safari automation remains unverified.

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 (development prerelease)

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. This command is a development checkpoint, not part of published 0.2.1.

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 source-distribution 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. These layers are included in the development prerelease.

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. The legacy checkout default path is retained for compatibility; use explicit --graph NODE-GRAPH.json, --file, or horsegraph examples for discovery.

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.0

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.0
File Size Uploaded Provenance Actions
horsegraph-0.3.0.tar.gz 631.1 kB Without provenance Details for horsegraph-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for horsegraph 0.3.0
File Interpreter ABI Platform Actions
horsegraph-0.3.0-py3-none-any.whl Python 3 none any Details for horsegraph-0.3.0-py3-none-any.whl

Total release size: 1.2 MB

Release files / horsegraph-0.3.0.tar.gz

Download URL horsegraph-0.3.0.tar.gz
Size 631.1 kB
Tags Source
SHA-256 checksum
How to use checksums
68a6792191f4cdf81f63217dae95885d422f6875fd0e4bdcf89330f48a48b32a
BLAKE2b-256 checksum
How to use checksums
bc77214146e0fd06f3a3e5d27e68dbc045c0b550cb3f9c6a18c5c3a631cc49ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / horsegraph-0.3.0-py3-none-any.whl

Download URL horsegraph-0.3.0-py3-none-any.whl
Size 566.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a4fb21cb10183ab8631ccd4b6474af8ea5dfaadfc844d7a15a72b2aff1e4d528
BLAKE2b-256 checksum
How to use checksums
2244d1b8672401de13bedc304abd487fd374db60dd9131cdc019f228e3b1ab65
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for horsegraph 0.3.0

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