> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_26/session_01_graph_data_contracts_seed_fixtures.md). # Session 01: Graph Data Contracts And Seed Fixtures **Session ID**: `phase26-session01-graph-data-contracts-seed-fixtures` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Establish the typed Knowledge Graph data layer: contracts for a graphify NetworkX node-link graph, registry entry, god nodes, metadata, and savings estimate, plus demo fixtures and a checked-in AI OS self-graph and registry, so every later session builds on safe, rejecting parsers instead of ad hoc JSON. *** ## Scope ### In Scope (MVP) * Typed contracts in `src/lib/knowledge-graph-types.ts` for the graphify node-link graph (nodes, links, `confidence`, communities), registry entry (id, name, lang, color, counts, god nodes, `graphPath`), god-node shape, and a token/cost savings estimate. * Parser/validators that reject malformed payloads and normalize legacy/partial graphs (AI OS typed-contract pattern, mirroring `hermes-types.ts`). * Demo fixtures in `src/lib/knowledge-graph-demo-data.ts` for offline/demo mode. * A checked-in seed registry `src/data/graphs/index.json` and seed graph `src/data/graphs/.json` (AI OS self-graph snapshot in graphify shape). * Contract tests covering valid parse, malformed rejection, and normalization. ### Out of Scope * Bridge endpoints (Session 02-03). * The 3D renderer (Session 04). * Live graphify generation pipeline (Session 03/08). *** ## Prerequisites * [ ] Phase 25 completed. * [ ] Reference graph shape confirmed in `/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/data/graphs/claude-os.json`. *** ## Deliverables 1. `src/lib/knowledge-graph-types.ts` with typed contracts and rejecting parsers. 2. `src/lib/knowledge-graph-demo-data.ts` demo fixtures. 3. `src/data/graphs/index.json` seed registry + `src/data/graphs/.json` seed graph. 4. Contract tests under `src/lib/__tests__/`. *** ## Success Criteria * [ ] Seed graph and registry parse through the new contracts. * [ ] Malformed payloads are rejected, not silently coerced. * [ ] Demo fixtures render-ready and shaped like the live contract. * [ ] Tests cover valid, malformed, and normalized cases. *** ## Folded Port Detail ### Source Project Reference Links #### AI OS Targets * [Contracts (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/knowledge-graph-types.ts) * [Demo fixtures (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/knowledge-graph-demo-data.ts) * [Seed graph + registry (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/data/graphs/README.md) * [Typed-contract pattern to mirror](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-types.ts) * [Existing force-graph types](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/graph-types.ts) * [Existing demo-data pattern](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-demo-data.ts) #### Claude OS v2.4 Reference * [Reference node/link types](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/components/graphify-graph-3d.tsx) * [Reference seed registry](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/data/graphs/index.json) * [Reference seed graph](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/data/graphs/claude-os.json) ### Reference (v2.4) * Graph node/link types: `v2.4/src/components/graphify-graph-3d.tsx:3-21`. * Seed registry fields (id/name/lang/color `3-7`, counts `8-11`, god nodes `12-37`, `graphPath` `38`): `v2.4/src/data/graphs/index.json:1-40`. * Raw minified graphify graph (269 nodes, 229 links, 85 communities, 96% `confidence: "EXTRACTED"`): `v2.4/src/data/graphs/claude-os.json:1`. * graphPath nuance: relative in the seed entry (`v2.4/src/data/graphs/index.json:38`), backfilled absolute by `v2.4/scripts/setup-graphify-brain.sh:76-86` and written absolute on ingest at `v2.4/vite.config.ts:683-686`. ### Build Steps 1. Define node/link/community/registry/god-node/savings types mirroring the graphify shape; add the AI OS savings-estimate type. 2. Write rejecting parsers (reject non-object, missing nodes/links, bad confidence) and a normalizer for partial/legacy graphs. 3. Generate the AI OS self-graph snapshot in graphify shape and a seed registry entry; resolve `graphPath` as workspace-relative for the checked-in seed. 4. Author demo fixtures shaped like the live contract. 5. Write contract tests (valid parse, malformed rejection, normalization, savings math). ### Exit Criteria * Contracts and parsers exported and unit-tested. * Seed graph + registry parse cleanly; demo fixtures available for Session 04-05. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_26/session_01_graph_data_contracts_seed_fixtures.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.