neo4jev

# neo4jev — Graph Navigation Demo (TypeSafe Jev + Neo4j)

A demo application that navigates a Neo4j graph one hop at a time using
TypeSafe's (`typesafe-sdk`) `system_one` structured-decision API instead of
free-text LLM generation. At each visited node, the outgoing relationships are
presented as `Choice` options (relationship type, relationship properties, target
node label/properties), and the API returns a full probability distribution over
which relationship to follow next. A `Noul` ("has the goal been reached?") question
rides in the same `system_one` call as the `Choice`, so each hop costs exactly one
round-trip regardless of how many questions are asked.

Top-k/cutoff selection over the returned probabilities implements a beam search: at
each step the search may branch into several candidate next-hops, and the
best-scoring chain(s) — ranked by sum of log-probabilities, to avoid float underflow
and length bias — become "the path(s) taken". Results are rendered in an interactive
[`neo4j-viz`](https://pypi.org/project/neo4j-viz/) graph alongside the surrounding
neighborhood.

> **Status**: the library, the three notebooks and the Streamlit app are built and run
> against the live `companies2` graph. The notebooks and the app execute end to end; the
> TypeSafe `system_one` calls inside them need `TYPESAFE_API_KEY` in `.env` — without it
> each call is attempted, its failure is displayed verbatim, and the surrounding pipeline
> is exercised on explicitly labelled stand-in answers. Nothing is ever presented as
> TypeSafe output that did not come from TypeSafe. See
> [`.plans/prd-graph-navigation-demo.md`](.plans/prd-graph-navigation-demo.md) for the
> authoritative requirements and design rationale, and
> [`.plans/tasks-graph-navigation-demo.yml`](.plans/tasks-graph-na