Docs to knowledge example (#2110)

Author: badmonster0

docs/src/content/example-posts/docs-to-knowledge-graph.md

@@ -105,6 +105,10 @@
       "sourcePath": "contributing/setup_dev_environment.md",
       "reviewedTs": 1780444800
     },
+    "examples/docs-to-knowledge-graph": {
+      "sourcePath": "example-posts/docs-to-knowledge-graph.md",
+      "reviewedTs": 1781265600
+    },
     "examples/index-codebase": {
       "sourcePath": "example-posts/index-codebase.md",
       "reviewedTs": 1781092800

docs/src/data/docs-meta.json

@@ -104,7 +104,7 @@ const introItems = [
   { k: 'Target',        v: tagOf('tgt'),                                           reviewed: false },
   { k: 'LLM',           v: tagOf('llm'),                                           reviewed: false },
   { k: 'Mode',          v: tagOf('ops'),                                           reviewed: false },
-  { k: 'Category',      v: ex.category,                                            reviewed: false },
+  { k: 'Category',      v: `${titleText(CATEGORY_META[ex.category].label)}${CATEGORY_META[ex.category].em ?? ''}`, reviewed: false },
   { k: 'Last reviewed', v: lastReviewed,                                           reviewed: true  },
 ].filter((m) => m.v);
 ---

docs/src/data/examples.ts

@@ -33,6 +33,10 @@ const featured = findExample(featuredSlug)!;
 // Category order and counts, computed from the data.
 const CAT_ORDER: Category[] = ['search', 'ingest', 'llm', 'agents', 'image'];
 const catCount = (c: Category) => examples.filter((e) => e.category === c).length;
+// Categories with no examples yet (e.g. 'image') stay out of the chips and
+// side-nav — their grid sections already render nothing, so a chip or anchor
+// would point nowhere.
+const activeCats = CAT_ORDER.filter((c) => catCount(c) > 0);
 
 // Phone drawer mirror of the inline `.side-nav` browse aside. The aside
 // becomes a horizontal flex pill row at ≤1180px which is fine on tablet,
@@ -157,7 +161,7 @@ const breadcrumbLd = {
 
             <div class="hero-filters" id="filters">
               <button class="filter-chip on" data-filter="all">All <span class="cnt">{total}</span></button>
-              {CAT_ORDER.map((c) => (
+              {activeCats.map((c) => (
                 <button class="filter-chip" data-filter={c}>
                   {CATEGORY_META[c].label}{CATEGORY_META[c].em ?? ''} <span class="cnt">{catCount(c)}</span>
                 </button>
@@ -177,7 +181,7 @@ const breadcrumbLd = {
           </div>
           <ol id="sideList">
             <li data-target="section.feat"><a href="#feat-scroll" data-cat="featured"><span class="cat-dot"></span>Featured<span class="count">★</span></a></li>
-            {CAT_ORDER.map((c) => (
+            {activeCats.map((c) => (
               <li data-target={`#cat-${c}`}>
                 <a href={`#cat-${c}`} data-cat={c}>
                   <span class="cat-dot"></span>

docs/src/pages/examples/[slug].astro

@@ -11,7 +11,7 @@ import {
   SKILL_MD_URL,
 } from '../consts';
 import { sidebar, type SidebarDoc } from '../data/docs-sidebar';
-import { EXAMPLE_CATALOG } from '../data/examples';
+import { EXAMPLE_CATALOG, EXAMPLE_CATALOG_GROUPS } from '../data/examples';
 const oneLine = (s?: string) => (s ?? '').replace(/\s+/g, ' ').trim();
 
 export const GET: APIRoute = async () => {
@@ -71,13 +71,18 @@ export const GET: APIRoute = async () => {
       '`, then `cd cocoindex/examples/<dir>`, copy `.env.example` if present, install with `pip install -e .`, and run the command shown for that example.',
   );
   out.push('');
-  for (const ex of EXAMPLE_CATALOG) {
-    const href = ex.docs
-      ? url(`examples/${ex.docs}`)
-      : `${GITHUB_REPO}/tree/main/examples/${ex.dir}`;
-    out.push(`- [${ex.title}](${href}): ${oneLine(ex.description)} (examples/${ex.dir}; run: \`${ex.run ?? 'cocoindex update main'}\`)`);
+  for (const group of EXAMPLE_CATALOG_GROUPS) {
+    out.push(`### ${group.title}`);
+    out.push(`> ${group.blurb}`);
+    out.push('');
+    for (const ex of group.entries) {
+      const href = ex.docs
+        ? url(`examples/${ex.docs}`)
+        : `${GITHUB_REPO}/tree/main/examples/${ex.dir}`;
+      out.push(`- [${ex.title}](${href}): ${oneLine(ex.description)} (examples/${ex.dir}; run: \`${ex.run ?? 'cocoindex update main'}\`)`);
+    }
+    out.push('');
   }
-  out.push('');
 
   return new Response(out.join('\n'), {
     headers: { 'Content-Type': 'text/plain; charset=utf-8' },

docs/src/pages/examples/index.astro

@@ -0,0 +1,19 @@
+# Example environment variables for this example
+# Copy this to .env and fill in your actual values
+
+COCOINDEX_DB=./cocoindex.db
+
+# OpenAI API key (used via LiteLLM). Not needed if LLM_MODEL points at a local
+# provider such as Ollama.
+#! PLEASE FILL IN
+OPENAI_API_KEY=
+
+# Neo4j connection
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=cocoindex
+NEO4J_DATABASE=neo4j
+
+# LLM model (LiteLLM-prefixed; e.g. openai/gpt-5.4, anthropic/claude-...,
+# gemini/..., or ollama/llama3.2 to run locally with no API key).
+LLM_MODEL=openai/gpt-5.4

docs/src/pages/llms.txt.ts

@@ -0,0 +1,5 @@
+.env
+cocoindex.db/
+__pycache__/
+*.egg-info/
+.venv/

examples/docs_to_knowledge_graph/.env.example

@@ -0,0 +1,119 @@
+# Build a Knowledge Graph for Docs — Neo4j (CocoIndex v1)
+
+Turn a folder of Markdown documentation into a concept knowledge graph in
+[Neo4j](https://neo4j.com/). For each document an LLM (via
+[LiteLLM](https://docs.litellm.ai/) + [instructor](https://python.useinstructor.com/))
+produces a short summary and a set of `(subject, predicate, object)` triples
+about the concepts it covers — "concepts, not code" — and the triples become a
+property graph.
+
+This is the CocoIndex **v1** port of the blog post
+[Build a Knowledge Graph for Documents](https://cocoindex.io/blogs/knowledge-graph-for-docs/).
+
+Please drop [CocoIndex on Github](https://github.com/cocoindex-io/cocoindex) a
+star to support us and stay tuned for more updates. Thank you so much 🥥🤗.
+[![GitHub](https://img.shields.io/github/stars/cocoindex-io/cocoindex?color=5B5BD6)](https://github.com/cocoindex-io/cocoindex)
+
+## What this builds
+
+- `Document` nodes — one per Markdown file, keyed by filename, with an
+  LLM-generated `title` and `summary`
+- `Entity` nodes — one per distinct concept named in a triple, keyed by `value`
+- Relationships:
+  - `RELATIONSHIP` — `Entity → Entity`, with the `predicate` stored on the edge
+  - `MENTION` — `Document → Entity`, recording which document named which concept
+
+The flow watches the source folder and keeps the graph up to date
+incrementally.
+
+## How it works
+
+The pipeline runs in two phases:
+
+1. **Per-file extraction.** Read each Markdown file, extract a `DocumentSummary`
+   (title + summary) and a list of relationship triples with LiteLLM +
+   instructor. The `Document` node is declared in this phase; the triples are
+   carried forward.
+2. **Graph building.** A single pass declares the deduplicated `Entity` nodes
+   and the `RELATIONSHIP` / `MENTION` edges across all documents. Each distinct
+   triple is keyed by a stable hash, so re-asserting the same fact in another
+   doc maps to the same edge.
+
+CocoIndex reconciles changes incrementally — re-running after editing one doc
+only re-extracts that doc, and the graph pass only re-runs when the set of
+triples changes. To collapse near-identical entity names (e.g. "CocoIndex" vs
+"Cocoindex"), add an entity-resolution pass like the one in
+[`meeting_notes_graph_neo4j`](../meeting_notes_graph_neo4j).
+
+## Prerequisites
+
+- A running Neo4j 5.18+ instance:
+  ```sh
+  docker run -d \
+    -p 7474:7474 -p 7687:7687 \
+    -e NEO4J_AUTH=neo4j/cocoindex \
+    --name cocoindex-neo4j \
+    neo4j:5.26-community
+  ```
+  The browser UI is at <http://localhost:7474>; log in with `neo4j` /
+  `cocoindex`.
+
+- An LLM. Defaults to OpenAI (set `OPENAI_API_KEY`); set `LLM_MODEL` to any
+  [LiteLLM provider](https://docs.litellm.ai/docs/providers) — e.g.
+  `LLM_MODEL=ollama/llama3.2` to run the extraction locally with no API key.
+
+## Environment
+
+Copy `.env.example` to `.env` and fill in the blanks:
+
+```sh
+cp .env.example .env
+set -a && source .env && set +a
+```
+
+## Run
+
+Install dependencies:
+
+```sh
+uv pip install -e .
+```
+
+This example ships a small `markdown_files/` folder of sample concept docs so it
+runs out of the box. Build/update the graph:
+
+```sh
+cocoindex update main
+```
+
+To index your own docs, drop `.md` / `.mdx` files into `markdown_files/` (or
+point `sourcedir` in `main.py` at another directory — e.g. CocoIndex's own
+`docs/`) and re-run.
+
+## Browse the knowledge graph
+
+Open Neo4j Browser at <http://localhost:7474>, log in, and run Cypher queries:
+
+```cypher
+// Everything
+MATCH p=()-->() RETURN p LIMIT 200
+
+// Concept-to-concept relationships
+MATCH (a:Entity)-[r:RELATIONSHIP]->(b:Entity)
+RETURN a.value, r.predicate, b.value
+
+// Which documents mention which concepts
+MATCH (d:Document)-[:MENTION]->(e:Entity)
+RETURN d.filename, d.title, e.value
+
+// Concepts mentioned in the most documents
+MATCH (d:Document)-[:MENTION]->(e:Entity)
+RETURN e.value, count(DISTINCT d) AS docs
+ORDER BY docs DESC LIMIT 10
+```
+
+To wipe the graph between runs:
+
+```cypher
+MATCH (n) DETACH DELETE n
+```