Digital Kant

A trans-temporal RAG system over Immanuel Kant’s corpus: Streamlit UI, ChromaDB semantic search, and optional Neo4j Graph-RAG. Default platform: Linux. Run all commands from the project root unless noted otherwise.

---

A. First-Time Use

1. Configure the environment

Prerequisites

• Python 3.10+ recommended (matches typical stack: torch, chromadb, pydantic).
• Enough disk for embeddings and Hugging Face caches (several GB).
• For src/Text_2_speech (SadTalker): Linux + ffmpeg in PATH, plus model weights under src/Text_2_speech/checkpoints/.

Create the venv and install dependencies

cd /path/to/Incarnation_Kant

# Full init: venv + pip install + crawl Korpora (see section A.4)
python initialize.py

# Or skip crawling and only set up env + deps:
python initialize.py --skip-download

# If you also need Text_2_speech dependencies:
python initialize.py --skip-download --with-text2speech

Activate the virtual environment

source .venv/bin/activate

Secrets

Create a .env file in the project root (do not commit it). At minimum for the web app:

GOOGLE_API_KEY=your_google_generative_ai_key

Optional for Graph-RAG build and Neo4j (see section A.3):

DEEPSEEK_API_KEY=your_deepseek_key
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

src/config.py loads .env via python-dotenv. Prefer .env for secrets; do not copy API keys into config/settings.yaml (that file may contain placeholders—treat them as non-authoritative).

Non-secret settings

• config/settings.yaml — app title, LLM model names, database paths, database.backend (chromadb vs neo4j), etc.
• If you edit YAML, keep a single database: block (duplicate keys in YAML can be confusing).

---

2. Configure Streamlit

Config file

• .streamlit/config.toml — e.g. port = 8501, address = "0.0.0.0", headless = true.

Point Streamlit at the config directory

export STREAMLIT_CONFIG_DIR="$(pwd)/.streamlit"

Caches (recommended)

app/main.py sets Hugging Face and temp dirs under .venv/.cache and .venv/.tmp when you run the app. For manual runs you can mirror run.sh:

export HF_HOME="$(pwd)/.venv/.cache/huggingface"
export TORCH_HOME="$(pwd)/.venv/.cache/torch"
export XDG_CACHE_HOME="$(pwd)/.venv/.cache"

API key

The Streamlit sidebar can set GOOGLE_API_KEY for the session; otherwise the app reads GOOGLE_API_KEY from .env or settings.llm.api_key (see app/main.py).

Known issue: run.sh currently uses hardcoded paths under /Data/Incarnation_Kant/. If you clone elsewhere, either edit run.sh or use manual startup (section B.2) with the exports above.

---

3. Configure Neo4j

When you need it

• Chroma-only mode: set database.backend to chromadb (or omit) — no Neo4j required for basic Q&A.
• Graph-RAG mode: Neo4j 5.11+ (vector indexes), plus DEEPSEEK_API_KEY for extraction during graph build.

Connection

Set NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD in .env (same values can be mirrored under neo4j: in config/settings.yaml for documentation—env wins for overrides in load_config()).

Enable graph retrieval in the app

In config/settings.yaml:

database:
  backend: "neo4j"

Bundled Neo4j (this repo)

A community distribution lives under neo4j-server/ (Neo4j 5.26.x). From that directory:

cd neo4j-server
./bin/neo4j-admin server console

• Bolt: default 7687 (e.g. bolt://localhost:7687).
• Browser UI: http://localhost:7474 (first run: set password to match NEO4J_PASSWORD).

Pre-built graph store (neo4j-server/data)

The repo does not ship neo4j-server/ (it is gitignored). To use a ready-made Neo4j data directory instead of running build_graph_rag from scratch:

1. Download data.zip from Google Drive (sign in if the link requires it).
2. Install Neo4j under neo4j-server/ — use the same Neo4j 5.x line as the project (see “Bundled Neo4j” above, e.g. 5.26.x). A store built with one minor version may not start on another; align versions with whoever produced the archive.
3. Stop Neo4j if it is already running. If you previously started an empty server, back up or remove the existing neo4j-server/data/ directory so it does not mix with the archive.
4. Extract the zip so Neo4j’s files live at neo4j-server/data/ (you should see paths like neo4j-server/data/databases/ and neo4j-server/data/dbms/). If the zip contains a top-level data/ folder, place that folder as neo4j-server/data (not neo4j-server/data/data/).
5. Credentials: set NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD in .env to match the user/password that were set when this database was created (the store on disk is tied to that password). If you only changed the password in the UI after import, use the current password.
6. App: keep database.backend: "neo4j" in config/settings.yaml when you want Graph-RAG. The zip only provides the Neo4j graph; ChromaDB under data/chromadb is still built separately by ingest (and may be used as fallback depending on configuration).

Alternative: install Neo4j via package manager or use Neo4j Aura; point NEO4J_URI accordingly.

---

4. Crawl the Kant corpus (Korpora)

initialize.py crawls korpora.org (Kant section) and writes HTML under data/raw/ (default layout includes data/raw/kant/ for the cleaner).

# Already have venv + deps; only (re)download:
python initialize.py --skip-venv --skip-install

Useful flags: --skip-download, --max-failure-rate, --max-depth (see initialize.py).

Note: After success, initialize.py may still print a legacy hint to scripts/build_database.py. That script does not exist. Use the pipeline in section A.5 instead.

---

5. Build the databases

Always run these from the project root with the venv activated.

Optional: Graph-RAG (Neo4j)

Requires running Neo4j, DEEPSEEK_API_KEY, and existing chunks:

python -m src.database.build_graph_rag
python -m src.database.build_graph_rag --limit 20
python -m src.database.build_graph_rag --resume

Optional: entity resolution (SAME_AS edges between concepts)

python -m src.database.resolve_entities

See report.md for parameters, checkpoints, and runtime behavior.

---

6. Deploy src/Text_2_speech (SadTalker)

src/Text_2_speech is an optional talking-head / text-to-speech module. It is independent from the default RAG pipeline.

Environment requirements

• OS: Linux recommended.
• Python: same project venv (.venv) is supported.
• System packages: ffmpeg must be available from command line.
• Weights: place SadTalker checkpoints in src/Text_2_speech/checkpoints/ (required by src/Text_2_speech/inference.py and src/Text_2_speech/src/utils/init_path.py).

Install dependencies

# from project root
source .venv/bin/activate
pip install -r requirements-text2speech.txt

Or use initializer:

python initialize.py --skip-download --with-text2speech

Compute requirements (practical guidance)

• CPU-only: possible, but often very slow (single clip may take many minutes).
• Minimum GPU: NVIDIA GPU with ~8 GB VRAM (reduced batch/size and slower throughput).
• Recommended GPU: 12-16 GB VRAM for smoother inference and enhancer usage (gfpgan / RestoreFormer).
• If you enable additional background enhancement, VRAM and runtime increase further.

Run quick demo

python src/Text_2_speech/scripts/quick_demo_main.py \
  --driven-audio /path/to/audio.wav \
  --source-image /path/to/image.png \
  --result-dir ./src/Text_2_speech/results \
  --preprocess full \
  --enhancer gfpgan

If examples/source_image does not exist in your local copy, always pass --source-image explicitly.

Streamlit integration (app/main.py)

• Portrait: if 500px-Immanuel_Kant_-_Gemaelde_1.jpg exists in the project root, it is used first. Otherwise the first request may download into data/assets/kant_portrait.* (Wikipedia HTML URLs are handled via og:image). Later runs use local files only.
• Each browser session allows one user question; after the assistant reply, use sidebar 「新对话」 to ask again.
• With Talking Kant enabled: the answer is translated to German for display in 「德语原文回答」 and for TTS + SadTalker video. Install optional deps first: pip install -r requirements-text2speech.txt (includes Coqui TTS).

---

B. Later Use

1. Start the environment

cd /path/to/Incarnation_Kant
source .venv/bin/activate

2. Start Streamlit

Option A — helper script (if paths match your machine)

chmod +x run.sh
./run.sh

Option B — manual (portable)

export STREAMLIT_CONFIG_DIR="$(pwd)/.streamlit"
export HF_HOME="$(pwd)/.venv/.cache/huggingface"
export TORCH_HOME="$(pwd)/.venv/.cache/torch"
export XDG_CACHE_HOME="$(pwd)/.venv/.cache"
mkdir -p logs
streamlit run app/main.py

• Local: http://localhost:8501
• LAN: http://<server-ip>:8501 (open firewall for port 8501 if needed).

3. Start Neo4j

Bundled

cd /path/to/Incarnation_Kant/neo4j-server
./bin/neo4j-admin server console

System Neo4j

Use your usual systemctl / neo4j commands; ensure Bolt URL matches NEO4J_URI, then start the Streamlit app as above.

---

Other Scripts and Reference

User-facing scripts

Development / analysis

• tests/analysis/ — e.g. analyze_chunks.py for chunk quality checks.
• See report.md and pipeline.md for architecture and pipeline details.

Troubleshooting

• ModuleNotFoundError: No module named 'src' — run python -m src.database.* from the project root, not from inside src/.
• Chroma / SQLite — app/main.py uses pysqlite3 when available for ChromaDB compatibility.
• Sensitive config — rotate any keys that were ever committed; use .env going forward.

---

License and project docs

Refer to repository LICENSE and NOTICE if present. For technical depth, see report.md.