Understanding the RAG Knowledge Base¶

The AI Assistant in Kamerplanter does not answer from the memory of a general language model — it grounds every response in your own data and a curated knowledge base. This technique is called Retrieval-Augmented Generation (RAG). This page explains how the system is structured and why it works the way it does.

Why RAG?¶

A language model answering solely from its training has two weaknesses:

1. Hallucinations — It invents plausible-sounding but incorrect facts
2. No context — It does not know your specific plant, your current measurements, or your care history

RAG solves both problems: before generating every response, the system searches a verified database for relevant information and provides it to the model as a foundation. The model then combines these facts with your specific situation — instead of speculating from memory.

The 4-Level Model¶

Kamerplanter's knowledge base consists of four levels that are combined for every request.

flowchart TB
    subgraph "Level 1: Global Master Data"
        E1[Plant species, cultivars, growth phases,<br/>nutrient profiles, pests, diseases]
    end

    subgraph "Level 2: Thematic Guides"
        E2[31 curated expert knowledge files:<br/>Diagnostics, fertilization, irrigation,<br/>environment, phases, outdoor, general]
    end

    subgraph "Level 3: Tenant Context"
        E3[Active planting run, phase,<br/>measurements EC/pH/VPD,<br/>active IPM events, recent feeding events]
    end

    subgraph "Level 4: Your Plant Data"
        E4[Care history, harvest results,<br/>plant diary entries, confirmations]
    end

    E1 --> RAG[RAG Retriever<br/>pgvector]
    E2 --> RAG
    E3 --> CB[Context Builder<br/>ArangoDB]
    E4 --> CB

    RAG --> PA[Prompt Assembler]
    CB --> PA
    PA --> LLM[Language Model]
    LLM --> Response

Levels 1 and 2 are stored as vectors and retrieved via similarity search. Levels 3 and 4 are injected as structured text into every request at runtime.

Level 1: Global Master Data¶

The Kamerplanter master data forms the foundation of all recommendations:

• Plant species with taxonomy, care requirements, and characteristics
• Cultivars with specific traits
• Growth phase definitions with VPD targets, light and temperature requirements
• Nutrient profiles per species and phase
• Pest and disease data with symptoms and treatment methods

This data is re-indexed weekly.

Level 2: Thematic Guides¶

Thematic guides contain cross-cutting knowledge that cannot be derived from master data — expert knowledge that applies across many plant species and situations. The knowledge base currently includes 31 curated guides in seven categories:

Level 3: Tenant Context (Real-Time)¶

For every request, the Context Builder fetches the current state of your grow from the database:

• Active planting runs with current growth phase and phase duration
• Latest measurements: EC, pH, VPD, temperature, humidity
• Active IPM events (pest infestations, diseases, ongoing treatments)
• Last feeding events with quantities and products

Level 4: Your Plant Data (Real-Time)¶

With your consent, personal care data also flows into the context:

• Care confirmations (when watered, fertilized, trained)
• Plant diary entries
• Results from past harvests

An Example Flow¶

Here is how a typical request moves through the system:

Species: Cannabis sativa 'Northern Lights'
Phase: Flowering, Day 21
EC: 1.2 mS/cm, pH: 5.8, VPD: 1.1 kPa
Last feeding: 2 days ago (standard nutrient solution)

Without the thematic guides, the model would only know the master data context and give generic tips. Without your real-time context (EC 1.2, week 3 flower), the model would not know the situation is borderline.

Knowledge Base Quality Assurance¶

Expert Review¶

All guides and master data are reviewed by experienced growers for technical accuracy before inclusion. Particular attention is paid to:

• Correct VPD and EC target values per phase and substrate
• Agreement of symptom descriptions with current literature
• Safety notices (mixing order, pre-harvest intervals)

Benchmark Evaluation¶

The system includes 100 benchmark questions whose answers are automatically evaluated with every knowledge base update:

• Topic Match — Are the retrieved RAG chunks relevant to the question?
• LLM-as-Judge — A second model evaluates factual accuracy and actionability
• A/B Comparison — When models or guide versions change: improvement over baseline?

Adding Custom Guides (Admin)¶

Once this feature is available, tenant admins will be able to add custom thematic guides to the local knowledge base — useful for cultivar-specific specialist knowledge, internal protocols, or guides in other languages.

YAML Format (Reference)¶

---
title: My Custom Guide Title
category: fertilization   # diagnostics | environment | fertilization | irrigation | phases | outdoor | general
tags: [ec, nutrient, hydroponics]
expertise_level: [intermediate, expert]
applicable_phases: [vegetative, flowering]
chunks:
  - id: my-first-chunk
    title: Section Title
    content: |
      Knowledge goes here as free text. The content is vectorized
      and retrieved for matching queries.

      Tip: Concrete, action-oriented text works better
      than general descriptions.
    metadata:
      nutrient: nitrogen
      substrate: coco

Reindexing the Knowledge Base (Operator/Developer)¶

After modifying knowledge YAML files under spec/knowledge/rag/, the vectors in the VectorDB (pgvector) must be recomputed. There is no automatic schedule for this — the reindex must be triggered manually against the Knowledge Service after every content change.

Prerequisites¶

• Knowledge YAML files are mounted in the Knowledge Service container at /app/knowledge (automatic with Skaffold deployment)
• The Knowledge Service and its Embedding Service must be running
• INTERNAL_SERVICE_TOKEN is set (the endpoint is service-token-protected, see Error Handling)

Workflow: Edit chunk → deploy → reindex → test¶

# 1. Edit knowledge YAML files
#    e.g. spec/knowledge/rag/diagnostik/naehrstoffmangel-symptome.yaml

# 2. Redeploy (so the files are available in the Knowledge Service container)
skaffold dev   # or: skaffold run

# 3. Trigger the reindex via the Knowledge Service endpoint
kubectl exec -it deploy/knowledge-service -- \
  curl -sX POST http://localhost:8000/ingest \
  -H "Authorization: Bearer $INTERNAL_SERVICE_TOKEN"

# 4. Run the benchmark (optional, recommended)
cd tools/rag-eval
source ~/.venvs/rag-eval/bin/activate
python eval_rag.py

What happens during reindex?¶

1. All YAML files under /app/knowledge are read
2. Each chunk is vectorized using the embedding model (multilingual-e5-large, 1024 dimensions, see ADR-006)
3. Vectors are upserted into ai_vector_chunks (existing chunks are updated by their source_key, new ones added)
4. The endpoint returns a summary: number of files, number of chunks

Frequently Asked Questions¶

See Also¶

• AI Assistant
• AI Provider Setup
• AI Architecture (Developer)
• VPD Optimization
• Nutrient Mixing