PlantAI-rag/docs/V15_SRT_KB_QA_AND_NEO4J_INTEGRATION.md

V15 SRT KB QA And Neo4j Integration

Current Status

The active V15 SRT knowledge base is a SQLite/JSONL artifact built from:

/home/xia-lab/gene-family-mas-v2/v15_output/batch100_v5

The active KB directory is:

/home/xia-lab/gene-family-mas-v2/data/knowledge_base/v15_srt_kb_20260525

Main files:

kb.sqlite
kb_relations.jsonl
kb_entities.jsonl
kb_papers.jsonl
kb_evidence.jsonl
kb_build_report.json
kb_review_sample_300.csv
README.md

The KB currently contains 100 papers and 44,595 retained SRT relations.

API Added In This Revision

A dedicated SQLite-backed QA route is mounted at:

/api/v1/kb-qa

Endpoints:

GET  /api/v1/kb-qa/info
POST /api/v1/kb-qa/chat
GET  /api/v1/kb-qa/entity/{entity_name}/relations
GET  /api/v1/kb-qa/relation/{relation_id}

Frontend verification page:

http://127.0.0.1:8000/static/kb_qa_test.html
http://192.168.31.239:8000/static/kb_qa_test.html

Example:

curl -X POST http://127.0.0.1:8000/api/v1/kb-qa/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "What is CESA?",
    "layer": "auto",
    "top_k": 8,
    "include_evidence": true,
    "use_llm": true
  }'

The endpoint now supports two answer modes:

use_llm=true  -> LLM synthesis answer plus exact SRT sources
use_llm=false -> extractive SRT/evidence answer for debugging

If LLM synthesis fails, the endpoint falls back to the extractive answer and records the error in notes.

Optional environment overrides:

export V15_KB_QA_LLM_PROVIDER=deepseek
export V15_KB_QA_LLM_MODEL=deepseek-v4-flash
export V15_KB_QA_LLM_MAX_TOKENS=1200
export V15_KB_QA_LLM_TEMPERATURE=0.2
export V15_KB_QA_ENABLE_OLLAMA_FALLBACK=1
export V15_KB_QA_OLLAMA_MODEL=qwen3:0.6b

If the remote API key is invalid or expired, the route falls back to local Ollama when fallback is enabled. The response notes field records this fallback.

Layer Policy

The route selects a QA layer automatically unless the caller passes layer.

Supported layer values:

auto
current_findings
main_kg
methods
method_relations
datasets
dataset_metadata
prior_work
background_relations
candidate
candidate_review
all

Default routing:

regular biological questions -> current_findings / main_kg
tool or method questions      -> method_relations
dataset/accession questions   -> dataset_metadata
prior-work/background questions -> background_relations
candidate/uncertain questions -> candidate_review

This is intentionally conservative. It prevents tools, prior work, and candidate triples from being mixed into "current paper findings" by default.

Expansion Workflow

For now, KB expansion should use rebuild mode rather than in-place append.

Recommended command:

cd /home/xia-lab/gene-family-mas-v2

/home/xzq/miniconda3/envs/gfpy312/bin/python scripts/build_v15_srt_kb.py \
  --input-root v15_output/batch100_v5 \
  --input-root v15_output/new_batch_xxx \
  --output-dir data/knowledge_base/v15_srt_kb_YYYYMMDD \
  --sample-size 300 \
  --seed 20260525

Reason:

The same paper may have multiple extraction versions.
Rebuild mode lets the builder select one version per paper and records skipped versions.
In-place append would make duplicate-paper contamination easier.

True incremental support can be added later with a manifest-based mode:

--append
--only-new
--replace-paper paper_id

Neo4j Integration Plan

Neo4j integration is feasible, but it should not replace the SQLite QA endpoint until the 300-relation quality sample is reviewed.

Recommended graph schema:

(:Paper {
  paper_id,
  pubmed_id,
  source_result_path
})

(:Entity {
  entity_id,
  name,
  norm_name,
  entity_type,
  species
})

(:Evidence {
  evidence_id,
  text,
  section,
  source_label,
  claim_scope
})

(source:Entity)-[:SRT_RELATION {
  relation_id,
  relation,
  output_layer,
  claim_scope,
  candidate_status,
  triple_quality,
  confidence,
  paper_id,
  evidence_id
}]->(target:Entity)

Use a single relationship type SRT_RELATION and store the predicate in the relation property.

Do not create a different Neo4j relationship type for every V15 relation string. V15 relation taxonomy is still evolving, and exploding relationship types would make maintenance and QA filtering harder.

Recommended Rollout

1. Use /api/v1/kb-qa/chat for the 150 QA questions.
2. Review the 300-relation sample and estimate layer-specific correctness.
3. If quality is acceptable, export/import the same KB into Neo4j.
4. Update the existing KG-RAG route to query SRT_RELATION with output_layer filters.
5. Keep SQLite as the audit source of truth.

Current Limitation

The route is still SQLite-backed and depends on retrieved SRT rows as the only evidence source.

When use_llm=true, the LLM only synthesizes a conversational answer from retrieved SRT/evidence rows. It does not perform a second retrieval pass, does not read the original PDF, and is instructed not to add outside biological knowledge.

When auditing retrieval quality, use use_llm=false so raw SRT/evidence can be inspected without LLM wording hiding a retrieval error.