omniseek_graph

Use WHEN you want HOW two entities connect, or what OmniSeek already knows AROUND a paper / author / entity; read-only, budgeted projections of its accumulated evidence graph with typed edges (ONE graph).

Everything OmniSeek perceives is a statement with provenance ("X relates to Y, per Z"); the evidence graph accumulates those typed edges in ONE store surfaced through N indexes. It stores FACTS + labeled CANDIDATES, never verdicts: mechanical world edges (tier M: cites, authored, coauthored, affiliated, published_in, about, observed, exact-id same_as) and alignment CANDIDATES (tier A: title-fingerprint / fuzzy-name same_as, name-match authored, string mentions, signal conflicts). Judgment (claims, gaps, identity rulings) is tier J and is STRUCTURALLY excluded from OmniSeek's store — the views project structure, YOU judge it.

ONE STABLE VERB: omniseek_graph(view, args). view names the projection; args is that view's OWN parameter dict (the views are an open family, their params disjoint per view, so the ABI is (view, args), not a flat union). THE SCHEMA IS FROZEN: future views and future per-view parameters change NOTHING in this signature; a no-view call returns the live view catalog (the surface is self-describing), and content is NEVER inlined (every view returns node ids + labels

• edge tuples, so you zoom with the other eye tools).

• view="find", args={"label_query": ..., "kind"?: ...} -> the ENTRY POINT. A node id is minted by the backend that knows it, so a NAME ("Siva Reddy") is not a node until you resolve it: find does the mechanical token/substring match over node labels and returns candidate ids + kinds. Every other view takes an anchor id; find is how you get one. • view="stats", args={} -> counts by kind / type / tier. The cheap orientation call (also the cold-start check: see below). • view="neighborhood", args={"anchor": ..., "depth"?<=2, "types"?, "policy"?, "max_nodes"?} -> the bounded subgraph around a node. • view="between", args={"a": ..., "b": ..., "types"?, "policy"?, "max_nodes"?} -> bounded connection paths between two anchors, the "how do these relate" question. Bidirectional BFS, <=2 hops per side, up to 8 shortest paths; capped when more existed. No path -> paths:[]. • view="voices", args={"doc_ids": [...], "policy"?: ...} -> collapse a doc set to distinct upstream VOICES via same_as + authored; the independence counter (mirror collapse, shared-speaker docs merge, docs with zero evidence land in unresolved and are NEVER counted as a voice). Input capped at 64 doc ids by explicit error; non-doc: ids come back in skipped. • view="since", args={"anchor": ..., "date": ..., "types"?, "max_nodes"?} -> the accretion log: what accreted around an anchor after a date (YYYY-MM-DD or full ISO), STORED edges only, tier + method shown on every row, NO collapsing (accretion is a fact stream, not an identity question). Derived edges carry no timestamps and are structurally absent. The sensor consumer. • view="similar", args={"anchor": , "k"?: ...} -> vector-nearest doc CANDIDATES for an anchor doc, method align:embed, by RANK (k is a budget, never a score threshold). PROPOSALS only, never collapsed by any policy; verify, then ratify with omniseek_ruling. Coverage: any doc with an embedded title, ranked across the UNION of the indexed vec matrix AND the thin-title vec_thin matrix (P7), so a thin arXiv original and an indexed post rank in ONE space; candidates may be thin docs. A doc with no vector in either store (un-embedded yet) -> an error naming that. NON-GOAL: vec_thin does NOT feed search's recall arm (similar + future P5 consumers only). A no-view call (view="") returns the live view catalog: each view's params + one-line blurb, DERIVED from the registry, so new views appear here without a client restart. Identity rulings are WRITTEN via omniseek_ruling (this tool stays read-only, hence gather-safe).

policy (an arg on the collapsing views) = conservative | working | exploratory: NAMED METHOD-SETS for how far to trust identity (same_as) edges when collapsing, NOT numeric thresholds (a hand-picked constant is pseudo-precision; the METHOD is the honest epistemic unit, as recall fuses by rank only):

• conservative: collapse on exact-id equality only (DOI / OpenAlex / ORCID / arXiv; default)

• working: conservative + agent identity rulings from graph_rulings.json

• exploratory: working + title-fingerprint / fuzzy-name alignment CANDIDATES Identity is an EVIDENCE-CARRYING EDGE, never a destructive merge: same_as edges carry tier + method, collapse is reversible, and a not_same_as ruling beats a same_as. OmniSeek never MAKES an identity ruling; it only applies the ones you already recorded.

COLD START (set the expectation or the first stats reads as failure): documents and same-work edges are LIVE FROM DAY ONE (derived over recall's docs — the wall is born pre-populated by construction). Document THIN rows (title + url only, from NON-indexed sources) now accumulate from EVERY search (stats.node_kinds.document_thin), so the perception history is complete, not just the ~40 enumerable sources. Entity kinds (work / person / institution / venue / topic) still fill in as the P2/P3 write taps ship and calls happen; emptiness of those kinds early is CORRECT, not broken.

BUDGETS (the no-silent-caps discipline): depth is clamped to <=2, max_nodes caps the node count, and any capped result stamps capped: true so a bounded view never reads as complete. Schema + the view registry live in omniseek.core.recall.graph.

FAIL-OPEN: a graph failure returns an error dict, never an exception — the graph is memory, it must NEVER break search or recall.