FoodScholar

A hierarchical knowledge graph over a corpus of nutrition literature — built for grounded, citable answers.

FoodScholar ingests dietary guides, textbooks, and scientific abstracts, then builds a three-layer hierarchical graph over the chunked corpus and serves a retrieval API on top. Every layer is anchored to real evidence, so an answer can always be traced back to the source chunks that support it.

        flowchart LR
    Corpus[Chunked corpus] --> A
    subgraph Graph
      A[Layer A — Backbone<br/>FoodOn shelves] --> B[Layer B — Themes<br/>per-shelf communities]
      B --> C[Layer C — Cards<br/>cited write-ups]
    end
    A --> Q[Retrieval API]
    B --> Q
    C --> Q
    

• Layer A — Backbone. A curated, multi-facet semantic menu projected from the FoodOn ontology (foods, health, nutrients, dietary patterns, allergies, sustainability).

• Layer B — Themes. Fine-grained topic communities discovered per shelf by two complementary passes — embedding similarity and entity relatedness — then merged.

• Layer C — Cards. LLM-generated write-ups attached to every shelf and theme, with every claim cited back to the source chunks.

New here? Start with Quickstart, then read Architecture for the whole picture.

Getting started

• Installation
  • Extras
  • Backing services (optional)
• Quickstart
  • Zero-config, in-memory
  • A real build from a config
  • What’s next
• Configuration
  • The mental model
  • The config API
  • Sections at a glance
  • storage — where data lives
  • llm — the language model
  • corpus & ontology
  • annotate — NER, embeddings, linking
  • layer_a, layer_b, layer_c — building the graph
  • Recipes

Concepts

• Architecture
  • Three layers over two stores
  • Two stores, one truth
  • One query, end to end
  • Design lessons baked into the pipeline
• A worked example, end to end
  • 1. Annotation — mentions → FoodOn ids
  • 2. Layer A — which shelves it lands on
  • 3. Layer B — which theme it joins
  • 4. Layer C — the card that cites it
  • 5. Retrieval — answering a query
• Corpus input format
  • Chunk CSVs
  • NEL CSVs (annotations)
  • What a chunk becomes
  • Three ways to load
• Annotation — NER & linking
  • NER — GLiNER
  • Linking — dense nearest neighbour
  • Catching linker drift
  • Quality gate
• The FoodOn ontology
  • Lazy loading & caching
  • Lookup API
  • One ontology, mostly one facet
• Layer A — Backbone
  • From mentions to shelves
  • Facets
  • The projection method
  • Aliasing
  • The Shelf record
  • How chunks attach
  • Building it
• Layer B — Themes
  • The two methods
  • Method A — Leiden (two-pass + merge)
  • Method B — BERTopic (single-pass)
  • Shared by both methods
• Layer C — Cards
  • The cost problem, and the two-stage answer
  • Stage 1 — cheap extractive compression
  • Stage 2 — LLM refinement into a Card
  • Honest about evidence
  • Stage 3 — embed + vector-search
  • Where Layer C sits
• Glossary

Guides

• Building the graph
  • The reference notebook
• Exploring the graph
  • Reading
  • Writing
  • Retrieval
• Visualization
  • The Layer A tree
  • Other renderers
• Tuning Layer B coverage
  • The knobs
  • Let the sweep pick for you
  • Inspect a single build
  • Reading the result
• Command line

API reference

• API reference