feat: Irminsul — Llama 3.1 8B QLoRA RAG serving stack with Pinecone, FastAPI, Azure

.gitignore

@@ -0,0 +1,7 @@
+.env
+venv/
+models/
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.12-slim
+
+# System deps for bitsandbytes + torch
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python deps first (layer cache)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy app code
+COPY main.py rag.py embedder.py ingest.py index.html ./
+
+# Model is NOT baked in — mount via Azure Blob or provide MODEL_PATH env var
+# See README for options
+
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Readme.MD

@@ -0,0 +1,171 @@
+# llmops-serve
+
+> Fine-tuned Llama 3.1 8B · QLoRA · Pinecone RAG · FastAPI · Azure Container Apps
+
+A full end-to-end LLMOps serving stack — from a QLoRA fine-tuned model running in 4-bit NF4 on consumer hardware, through a retrieval-augmented generation pipeline, to a containerized API deployed on Azure. Built to be production-shaped, not just a demo.
+
+---
+
+## What this is
+
+Most LLM projects stop at inference. This one goes further:
+
+- **Fine-tuned model** — Llama 3.1 8B fine-tuned with QLoRA (rank 16, lr 2e-4) on a custom dataset, merged and served locally in 4-bit NF4 quantization on an RTX 3060 6GB
+- **RAG pipeline** — Documents ingested, chunked, embedded with `sentence-transformers/all-MiniLM-L6-v2` (fully local, zero API cost), and stored in Pinecone. Retrieval is semantic, top-k configurable at query time
+- **Serving layer** — FastAPI with async lifespan model loading, typed Pydantic request/response models, CORS, health check, and a clean browser UI served from the same process
+- **Containerized** — Dockerfile built for slim Python 3.12, model loaded at runtime via env-configurable path (not baked in)
+- **Cloud-ready** — One-shot Azure deployment via ACR + Container Apps, with Pinecone key injected as a secret
+
+---
+
+## Architecture
+
+```
+User query
+    │
+    ▼
+FastAPI  /generate
+    │
+    ├── Embed query (sentence-transformers, local)
+    │       │
+    │       ▼
+    │   Pinecone — semantic search → top-k chunks
+    │       │
+    ▼       ▼
+  LangChain RetrievalQA
+    │
+    ▼
+Llama 3.1 8B (QLoRA fine-tuned, 4-bit NF4)
+    │
+    ▼
+Grounded answer + source attribution
+```
+
+---
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Base model | Llama 3.1 8B Instruct |
+| Fine-tuning | QLoRA via PEFT (r=16, α=32, lr=2e-4) |
+| Quantization | BitsAndBytes 4-bit NF4, bfloat16 compute |
+| Embeddings | sentence-transformers/all-MiniLM-L6-v2 |
+| Vector DB | Pinecone (serverless, cosine similarity) |
+| RAG chain | LangChain RetrievalQA |
+| Serving | FastAPI + Uvicorn |
+| Containerization | Docker (python:3.12-slim) |
+| Cloud | Azure Container Apps + ACR |
+
+---
+
+## Quickstart
+
+```bash
+# 1. Clone and set up environment
+git clone https://github.com/MukulRay1603/Irminsul.git
+cd llmops-serve
+python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -r requirements.txt
+
+# 2. Configure environment
+cp .env.example .env
+# Fill in PINECONE_API_KEY in .env
+
+# 3. Add your fine-tuned model
+# Place merged model at: ./models/merged/exp2_lr2e-4_r16
+# Or update MODEL_PATH in .env to point to your model
+
+# 4. Ingest documents
+python ingest.py --dir ./docs --chunk-size 300 --chunk-overlap 40
+
+# 5. Start the server
+uvicorn main:app --reload --port 8000
+
+# UI available at http://localhost:8000
+# API docs at http://localhost:8000/docs
+```
+
+---
+
+## API
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/` | Browser UI |
+| `GET` | `/health` | Model load status |
+| `POST` | `/generate` | RAG query → grounded answer |
+| `POST` | `/ingest` | Ingest docs from local directory |
+
+**Example:**
+
+```bash
+curl -X POST http://localhost:8000/generate \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What weapons should Hu Tao use on a budget?", "top_k": 3}'
+```
+
+```json
+{
+  "answer": "For Hu Tao on a budget, Dragon's Bane is the strongest F2P option — it scales with Elemental Mastery and deals significant bonus damage on vaporized hits. White Tassel is the best 3-star alternative for pure Normal Attack scaling.",
+  "sources": ["docs/character_builds.md"],
+  "latency_ms": 4821.3
+}
+```
+
+---
+
+## Memory profile (RTX 3060 6GB)
+
+| Component | VRAM |
+|---|---|
+| Llama 3.1 8B @ 4-bit NF4 | ~4.5 GB |
+| all-MiniLM-L6-v2 embedder | ~90 MB |
+| Inference headroom | ~1.2 GB |
+
+Running the embedder on CPU frees ~90MB if needed — set `device_map="cpu"` in `rag.py`.
+
+---
+
+## Deploy to Azure
+
+```bash
+export PINECONE_API_KEY=your_key
+chmod +x deploy_azure.sh
+./deploy_azure.sh
+```
+
+The script provisions a resource group, builds and pushes the image via ACR Tasks (no local Docker build needed), creates a Container Apps environment, and deploys with the Pinecone key injected as a secret. Prints the live HTTPS endpoint on completion.
+
+**Model in Azure:** The merged model (~16GB) isn't baked into the image. Recommended approach: mount from Azure Blob Storage as a volume for cheapest cold start on student credits.
+
+---
+
+## Project structure
+
+```
+llmops-serve/
+├── main.py           # FastAPI app — endpoints, lifespan, CORS
+├── rag.py            # Model loading, 4-bit config, LangChain RAG chain
+├── embedder.py       # sentence-transformers singleton wrapper
+├── ingest.py         # Doc loader → chunker → Pinecone upsert
+├── index.html        # Browser UI (dark theme, query history, source display)
+├── Dockerfile
+├── deploy_azure.sh   # One-shot Azure Container Apps deploy
+├── requirements.txt
+└── .env.example
+```
+
+---
+
+## What's next
+
+- [ ] Swap naive word chunker for `MarkdownHeaderTextSplitter` for better retrieval precision
+- [ ] Add metadata filtering to Pinecone queries (filter by character, content type)
+- [ ] Streaming response via SSE for lower perceived latency
+- [ ] Expand corpus — per-character deep dives with stat thresholds and rotation guides
+- [ ] CI/CD pipeline — GitHub Actions → ACR build → Container Apps deploy on push
+
+---
+
+Built while learning the full MLOps lifecycle — fine-tuning, quantization, retrieval, serving, and cloud deployment — on consumer hardware. Every component chosen deliberately, not for hype.

docs/character_builds.md

@@ -0,0 +1,390 @@
+# Genshin Impact — Character Builds, Weapons & Team Compositions
+
+---
+
+## Build Guide Philosophy
+
+Every character build has three tiers: Best-in-Slot (BiS) using 5-star weapons and ideal artifact sets, Strong F2P using 4-star weapons available from the game without spending, and Budget using easily farmable or craftable options. Team compositions are listed as core (non-negotiable role) plus flex (adaptable slot).
+
+---
+
+## Pyro Characters
+
+### Hu Tao — 5-star Pyro Polearm
+**Role:** Main DPS, vaporize/melt enabler
+**Playstyle:** Hu Tao's E (Infernal Shift) consumes her HP to enter a powered state that converts her normal attacks to Pyro and buffs her damage based on Max HP. Optimal play is low HP (ideally 50% or below) to maximize her A1 passive. She hits extremely hard in short burst windows.
+
+**Best-in-Slot:**
+- Weapon: Staff of Homa (5-star) — massive HP bonus, massive ATK bonus when below 50% HP, synergizes perfectly
+- Artifacts: 4pc Crimson Witch of Flames — reaction bonus and Pyro DMG
+- Substats priority: CRIT Rate/DMG, HP%, Elemental Mastery
+
+**Strong F2P:**
+- Weapon: Dragon's Bane (4-star, event) — EM scaling, massive damage on vaporized hits
+- Weapon: Deathmatch (4-star, BP) — reliable CRIT Rate
+- Weapon: White Tassel (3-star) — best 3-star option for pure Normal ATK scaling
+
+**Budget:**
+- Weapon: Halberd (4-star, random world drop) — ATK% and normal attack bonus
+- Artifacts: 2pc CW + 2pc Wanderer's Troupe for EM, or 4pc Lavawalker if mono-Pyro
+
+**Core Teams:**
+1. Vaporize: Hu Tao / Yelan / Xingqiu / Zhongli — Yelan + Xingqiu provide constant off-field Hydro application for Vaporize reactions. Zhongli provides shielding so Hu Tao can stay at low HP safely.
+2. Melt: Hu Tao / Rosaria / Layla / Bennett — Cryo application from Rosaria and Layla enables Melt. Bennett provides healing and ATK buff.
+3. Budget: Hu Tao / Xingqiu / Sucrose / Noelle — Sucrose provides EM buff and grouping; Noelle provides shields and healing.
+
+**Notes:** Hu Tao is one of the highest individual DPS characters in the game. Her weakness is survivability — she requires either shield support or precise dodging. She does NOT want Bennett in most teams because his healing pushes her above the HP threshold for her passive.
+
+---
+
+### Yoimiya — 5-star Pyro Bow
+**Role:** Main DPS, single-target Pyro applicator
+**Playstyle:** Yoimiya's E turns her Normal Attacks into Pyro for 10 seconds. Her kit is entirely Normal Attack focused, making her the best bow Normal ATK DPS. She applies Pyro rapidly to a single target, enabling consistent Vaporize.
+
+**Best-in-Slot:**
+- Weapon: Thundering Pulse (5-star) — Normal ATK stacking bonus, ideal fit
+- Weapon: Aqua Simulacra (5-star) — pure DMG% bonus works well
+- Artifacts: 4pc Shimenawa's Reminiscence — Normal ATK DMG bonus, though the ER cost is real
+
+**Strong F2P:**
+- Weapon: Rust (4-star) — Normal ATK DMG% at the cost of charged attack, which Yoimiya never uses
+- Weapon: Hamayumi (4-star, craftable) — craftable, Normal ATK focused
+
+**Core Teams:**
+1. Vaporize: Yoimiya / Yelan / Fischl / Zhongli — Yelan for Hydro application, Fischl for off-field Electro (enabling Overloaded/Aggravate variety), Zhongli for shield
+2. Mono Pyro: Yoimiya / Bennett / Xiangling / Kazuha — Bennett for ATK buff, Xiangling for off-field Pyro, Kazuha for elemental DMG% bonus and grouping
+
+**Notes:** Yoimiya's weakness is AoE — she is single-target focused. Her burst applies Pyro to enemies that hit her allies, which is a creative mechanic for spreading damage.
+
+---
+
+### Xiangling — 4-star Pyro Polearm (Free from Spiral Abyss Floor 3-3)
+**Role:** Off-field DPS, Pyro applicator, one of the best 4-stars in the game
+**Playstyle:** Xiangling is unique — despite being a 4-star, she is a top-tier off-field DPS through her Burst (Pyronado), which spins around the active character continuously for 14 seconds, applying Pyro. Combined with Hydro supports, she generates constant Vaporize reactions from off-field.
+
+**Best-in-Slot:**
+- Weapon: Staff of Homa (5-star, also works off-field HP scaling)
+- Weapon: The Catch (4-star, free from fishing) — ER and Burst DMG bonus, extremely cost-effective
+- Artifacts: 4pc Emblem of Severed Fate — ER to Burst DMG conversion, essentially made for her
+
+**Strong F2P:**
+- Weapon: Kitain Cross Spear (4-star, craftable) — ER passive, reduces Burst cost in effect
+- Weapon: Favonius Lance (4-star) — pure ER for more consistent Burst uptime
+
+**Core Teams:**
+1. National Team: Xiangling / Bennett / Xingqiu / Sucrose (or Kazuha) — one of the most consistent teams in the game, works on nearly all content
+2. Childe-Xiangling: Childe / Xiangling / Bennett / Kazuha — Childe applies Hydro rapidly, Xiangling's Pyronado Vaporizes off Childe's application
+3. Raiden National: Xiangling / Bennett / Xingqiu / Raiden Shogun — Raiden charges energy for the whole team
+
+**Notes:** Xiangling requires significant ER investment (typically 180%+) to maintain Burst uptime. She benefits enormously from Bennett's ATK buff because Pyronado snapshots buffs at the time it's cast.
+
+---
+
+### Bennett — 4-star Pyro Sword (One of the best supports in the game)
+**Role:** Healer, ATK buffer, Pyro applicator
+**Playstyle:** Bennett's Burst creates a field that continuously heals characters inside it and provides a massive ATK bonus (based on Bennett's Base ATK) to characters above 70% HP. This ATK buff is flat and applies to all damage types, making him useful in virtually every team.
+
+**Best-in-Slot:**
+- Weapon: Aquila Favonia (5-star) — highest Base ATK of any sword, maximizes his ATK buff
+- Weapon: Mistsplitter Reforged (5-star) — Base ATK + Elemental DMG buffs both work here
+- Artifacts: 4pc Noblesse Oblige — team ATK% bonus on Burst use, perfect support set
+
+**Strong F2P:**
+- Weapon: Festering Desire (4-star, limited event) — ER and Skill DMG
+- Weapon: Favonius Sword (4-star) — ER for consistent Burst
+- Weapon: Black Sword (4-star, BP) — if using Bennett as a pseudo-DPS
+
+**Notes:** CRITICAL — Bennett's C6 converts all sword/claymore/polearm characters in his field to Pyro infusion. This is extremely powerful for some teams and completely destructive for others (it ruins physical carry teams and some specific reaction teams). Most experienced players recommend NOT using Bennett C6 unless you know exactly what you're doing.
+
+---
+
+### Dehya — 5-star Pyro Claymore
+**Role:** Damage mitigation tank, off-field Pyro, sub-DPS
+**Playstyle:** Dehya places a field that redirects damage from allies to herself and provides periodic Pyro application. She is one of the most unique tanks in the game — she absorbs hits instead of blocking them with a shield. Her Burst allows rapid punching in a brief window.
+
+**Best-in-Slot:**
+- Weapon: Beacon of the Reed Sea (5-star, her signature) — HP and ATK bonus when taking damage
+- Artifacts: 4pc Tenacity of the Millelith — HP and shield/team ATK bonus
+
+**Core Teams:**
+1. Dehya / Furina / Kazuha / Bennett — Furina rewards characters who take damage; Dehya's damage absorption synergizes perfectly
+2. Mono Pyro: Dehya / Bennett / Xiangling / Kazuha
+
+---
+
+## Hydro Characters
+
+### Yelan — 5-star Hydro Bow
+**Role:** Off-field DPS, Hydro applicator, damage amplifier
+**Playstyle:** Yelan's Burst summons dice that follow the active character and periodically deal Hydro damage, similar to Xingqiu but with higher individual hit damage and a unique buff — the longer her Burst is active, the more damage bonus the active character gets (ramping from 1% to 50% DMG bonus over 15 seconds).
+
+**Best-in-Slot:**
+- Weapon: Aqua Simulacra (5-star, her signature) — HP% and DMG% bonus when enemies are nearby
+- Artifacts: 4pc Emblem of Severed Fate — ER to Burst DMG, enables consistent uptime
+
+**Strong F2P:**
+- Weapon: Fading Twilight (4-star, event) — cycling DMG% bonus
+- Weapon: Favonius Warbow (4-star) — ER generation for team
+
+**Core Teams:**
+1. Vaporize support: Any Pyro main DPS / Yelan / Xingqiu / flex — double Hydro application is extremely consistent
+2. Furina / Neuvillette teams: Yelan works beautifully in Fontaine-focused compositions
+
+**Notes:** Yelan is largely considered a direct upgrade to Xingqiu for teams that can use both, but Xingqiu has the unique advantage of providing damage reduction (making him better for fragile DPS like Hu Tao).
+
+---
+
+### Xingqiu — 4-star Hydro Sword (Free from in-game events periodically)
+**Role:** Off-field DPS, Hydro applicator, damage reduction provider
+**Playstyle:** Xingqiu's Burst summons Rain Swords that follow the active character, dealing Hydro damage on Normal Attacks and providing damage reduction. He is one of the most versatile supports in the game and appears in more top-level teams than almost any other character.
+
+**Best-in-Slot:**
+- Weapon: Haran Geppaku Futsu (5-star) or Primordial Jade Cutter (5-star)
+- Weapon: Sacrificial Sword (4-star) — most F2P BiS, allows double E cast for energy generation
+- Artifacts: 4pc Emblem of Severed Fate
+
+**Core Teams:** National Team, any Pyro vaporize team, Hu Tao team, Kamisato Ayato teams
+
+---
+
+### Neuvillette — 5-star Hydro Catalyst
+**Role:** Main DPS, Hydro applicator, self-sufficient damage dealer
+**Playstyle:** Neuvillette is unique — his power comes from a Charged Attack that he charges by collecting Water Droplets generated through reactions and his own skills. His fully charged attack deals massive AoE Hydro damage. He is one of the strongest DPS characters currently, largely self-sufficient, and does not require specific reaction partners (though he benefits from them).
+
+**Best-in-Slot:**
+- Weapon: Tome of the Eternal Flow (5-star, signature) — HP and Charged Attack DMG
+- Artifacts: 4pc Marechaussee Hunter — CRIT Rate increase when HP changes, pairs with his HP fluctuation passive
+
+**Strong F2P:**
+- Weapon: Sacrificial Jade (4-star) — HP% bonus
+- Weapon: Prototype Amber (4-star, craftable) — ER and HP healing
+
+**Core Teams:**
+1. Neuvillette / Furina / Kazuha / Jean — Furina amplifies damage when characters lose HP; Kazuha groups enemies; Jean heals
+2. Neuvillette / Furina / Baizhu / Kazuha — Baizhu provides shields that let Furina work without risk
+3. Budget: Neuvillette / Barbara / Kazuha / Zhongli
+
+---
+
+### Furina — 5-star Hydro Catalyst
+**Role:** Support DPS, team damage amplifier, HP fluctuation enabler
+**Playstyle:** Furina summons a Salon that includes characters who drain HP from active characters and deal Hydro damage. Simultaneously, she has a mechanic where she accumulates a stack (Fanfare) based on how much HP team members gain or lose — higher Fanfare gives her Burst a larger damage bonus to the whole team. She rewards teams where HP fluctuates frequently.
+
+**Best-in-Slot:**
+- Weapon: Splendor of Tranquil Waters (5-star, signature)
+- Artifacts: 4pc Golden Troupe — off-field Skill DMG bonus
+
+**Strong F2P:**
+- Weapon: Favonius Codex (4-star) — ER for consistent Burst
+
+**Core Teams:**
+1. Furina / Neuvillette / Kazuha / Charlotte — premier Neuvillette team
+2. Furina / Wriothesley / Shenhe / Kazuha — Cryo DPS with Furina support
+3. Furina / any HP-fluctuating DPS / healer / buffer — she works with almost any DPS
+
+**Notes:** Furina requires a dedicated healer on the team because her Salon deals constant HP drain. She is not compatible with shield-only protection.
+
+---
+
+## Electro Characters
+
+### Raiden Shogun — 5-star Electro Polearm
+**Role:** Main DPS / ER battery, Electro applicator, Burst DPS
+**Playstyle:** Raiden generates Resolve stacks based on team members' Burst damage. Her own Burst consumes all Resolve for a massively powerful Musou Isshin state where she deals high Electro damage with normal attacks and restores energy for the whole team. She is simultaneously an ER support and a burst DPS.
+
+**Best-in-Slot:**
+- Weapon: Engulfing Lightning (5-star, signature) — ER to ATK conversion, ER secondary stat
+- Artifacts: 4pc Emblem of Severed Fate — ER to Burst DMG
+
+**Strong F2P:**
+- Weapon: The Catch (4-star, free fishing) — ER, Burst DMG and CRIT, exceptional value
+- Weapon: Favonius Lance (4-star) — ER focused
+
+**Core Teams:**
+1. Raiden National: Raiden / Bennett / Xiangling / Xingqiu — among the most consistent teams ever
+2. Raiden Hypercarry: Raiden / Sara / Kazuha / Bennett — all buffs focused on Raiden's Burst
+3. Raiden Furina: Raiden / Furina / Nahida / flex — Nahida enables Quicken/Aggravate, Furina buffs Burst
+
+---
+
+### Cyno — 5-star Electro Polearm
+**Role:** Main DPS, extended Burst DPS, Aggravate/Quickbloom enabler
+**Playstyle:** Cyno's Burst gives him a powerful extended state (unlike most Bursts, his lasts 18 seconds and he uses the Burst as his combat mode). He deals high Electro damage through Normal Attacks during this state, and his A4 passive extends the state further when he uses his Skill. He works best in Dendro reaction teams.
+
+**Best-in-Slot:**
+- Weapon: Staff of the Scarlet Sands (5-star, signature) — EM to ATK conversion
+- Artifacts: 4pc Thundering Fury — Electro DMG and reaction-triggered CD reduction
+
+**Core Teams:**
+1. Aggravate: Cyno / Nahida / Fischl / Baizhu — Fischl for off-field Electro and energy, Nahida for Dendro application, Baizhu for shields and healing
+2. Quickbloom: Cyno / Nahida / Xingqiu / Fischl
+
+---
+
+### Fischl — 4-star Electro Bow
+**Role:** Off-field Electro DPS, energy generator
+**Playstyle:** Fischl's Skill summons Oz, a raven who continuously deals Electro damage to enemies. At C6, whenever Fischl or Oz triggers an Electro reaction, Fischl deals additional joint ATK damage. She is the premier off-field Electro applicator and appears in a huge range of teams.
+
+**Best-in-Slot:**
+- Weapon: The Stringless (4-star) — Elemental Mastery, Skill and Burst DMG bonus
+- Artifacts: 4pc Thundering Fury (for C6) or 4pc Golden Troupe (for Oz uptime)
+
+**Core Teams:** Aggravate teams, Quickbloom teams, Superconduct physical teams, National Team variants
+
+---
+
+## Cryo Characters
+
+### Ganyu — 5-star Cryo Bow
+**Role:** Main DPS (Charged Attack), Sub-DPS (off-field Burst), Cryo applicator
+**Playstyle:** Ganyu's Charged Attack has two levels. Her Level 2 Charged Attack (Frostflake Arrow) fires a homing arrow that explodes in AoE Cryo on contact. This is her primary damage source. She is one of the highest-ceiling DPS characters in the game for AoE content.
+
+**Best-in-Slot:**
+- Weapon: Amos' Bow (5-star) — Charged ATK DMG bonus, arrow travel time bonus
+- Artifacts: 4pc Blizzard Strayer — CRIT Rate bonus against Cryo-affected enemies (effectively gives free CRIT)
+
+**Strong F2P:**
+- Weapon: Prototype Crescent (4-star, craftable) — ATK% on weak point hit, Ganyu almost always hits weak points
+
+**Core Teams:**
+1. Freeze: Ganyu / Kokomi / Kazuha / Shenhe — Kokomi provides Hydro for Freeze, Kazuha groups and buffs, Shenhe buffs Cryo damage
+2. Melt: Ganyu / Bennett / Xiangling / Zhongli — Xiangling applies Pyro off-field; Ganyu's arrows Melt for 1.5x damage
+3. Mono Cryo: Ganyu / Shenhe / Kazuha / Layla
+
+---
+
+### Ayaka — 5-star Cryo Sword
+**Role:** Main DPS, Freeze team anchor
+**Playstyle:** Ayaka's Dash applies Cryo on exit, her Normal Attacks are elegantly chained, and her Burst summons a snowstorm that deals extremely high Cryo damage over 5 seconds. She is the centerpiece of Freeze teams and one of the most visually impressive DPS characters.
+
+**Best-in-Slot:**
+- Weapon: Mistsplitter Reforged (5-star) — Elemental DMG and stacking bonus
+- Artifacts: 4pc Blizzard Strayer — like Ganyu, Ayaka benefits enormously from the free CRIT Rate
+
+**Strong F2P:**
+- Weapon: Amenoma Kageuchi (4-star, craftable in Inazuma) — ER passive, helps with Burst uptime
+
+**Core Teams:**
+1. Freeze: Ayaka / Kokomi / Kazuha / Shenhe — the premier Ayaka team
+2. Ayaka / Mona / Venti / Diona — older freeze composition, still very effective
+
+---
+
+### Wriothesley — 5-star Cryo Catalyst
+**Role:** Main DPS, Charged Attack focused
+**Playstyle:** Wriothesley is a melee catalyst DPS whose combat revolves around consuming his own HP through a special punch-based Charged Attack. He recovers HP through his passive when he hits certain thresholds, creating a HP management rhythm. He deals extremely high damage in short windows.
+
+**Best-in-Slot:**
+- Weapon: Cashflow Supervision (5-star, signature) — ATK and Charged ATK bonus when HP changes
+- Artifacts: 4pc Marechaussee Hunter — CRIT Rate when HP fluctuates, perfect synergy
+
+**Core Teams:**
+1. Wriothesley / Furina / Shenhe / Kazuha
+2. Wriothesley / Furina / Nahida / Charlotte — Quickbloom variant
+
+---
+
+## Anemo Characters
+
+### Kazuha — 5-star Anemo Sword
+**Role:** Crowd control, elemental DMG% buffer, Swirl DPS
+**Playstyle:** Kazuha's Skill and Burst Swirl elements he absorbs, and his A4 passive converts Elemental Mastery into elemental DMG bonus for the entire team (based on the element he Swirls). 200 EM gives 40% elemental DMG to the absorbed element for all allies. He is the best Anemo support for reaction teams.
+
+**Best-in-Slot:**
+- Weapon: Freedom-Sworn (5-star) — EM primary stat, team buff on Swirl reactions
+- Artifacts: 4pc Viridescent Venerer — reduces enemy Elemental RES by 40%, standard for all Anemo supports
+
+**Strong F2P:**
+- Weapon: Iron Sting (4-star, craftable) — EM stat, solid budget option
+- Weapon: Xiphos' Moonlight (4-star) — EM primary, team ER generation
+
+**Notes:** Kazuha is arguably the single best support in the game for elemental teams. He appears in more high-investment team compositions than any other character. His F2P weapon options are genuinely competitive.
+
+---
+
+### Venti — 5-star Anemo Bow
+**Role:** Crowd control, ER battery, grouping support
+**Playstyle:** Venti's Burst pulls all non-boss enemies into a vortex for 8 seconds, dealing Anemo damage and absorbing another element to deal additional damage. He is the best grouping character in the game. His Skill also launches enemies. He restores 15 energy to all teammates of the absorbed element type after his Burst ends.
+
+**Best-in-Slot:**
+- Weapon: Elegy for the End (5-star) — EM and team ATK/EM buff, excellent for support
+- Artifacts: 4pc Viridescent Venerer
+
+**Strong F2P:**
+- Weapon: Favonius Warbow (4-star) — ER generation
+- Weapon: Stringless (4-star) — EM and Skill/Burst DMG
+
+**Notes:** Venti loses significant value against large enemies and bosses that cannot be sucked into his Burst. He is exceptional in Spiral Abyss against small-medium enemies.
+
+---
+
+## Geo Characters
+
+### Zhongli — 5-star Geo Polearm
+**Role:** Shield support, shred support, off-field sub-DPS
+**Playstyle:** Zhongli creates the strongest shield in the game (based on his Max HP) and his Stele resonance reduces enemy Geo and ALL elemental RES by 20% just by existing near enemies. His Burst petrifies enemies. He is the gold standard for defensive support.
+
+**Best-in-Slot:**
+- Weapon: Staff of Homa (5-star) — HP and ATK bonus, high shield value
+- Weapon: Black Tassel (3-star) — actually one of his best weapons, pure HP% focus for maximum shield
+- Artifacts: 4pc Tenacity of the Millelith — HP and shield strength, team ATK bonus on Skill hit
+
+**Strong F2P:**
+- Weapon: Favonius Lance (4-star) — ER for more consistent Burst
+- Weapon: Prototype Starglitter (4-star, craftable) — ER and Normal ATK bonus
+
+**Notes:** Zhongli with Black Tassel is a legitimate budget option that outperforms many 5-star weapons on him because his shield scales purely from HP. He is one of the most universally useful characters in the game — every team benefits from his shield and RES shred.
+
+---
+
+## Dendro Characters
+
+### Nahida — 5-star Dendro Catalyst
+**Role:** Off-field Dendro DPS, Elemental Mastery buffer, reaction catalyst
+**Playstyle:** Nahida marks enemies with Seed of Skandha through her Skill (she can mark multiple enemies), and every elemental reaction that triggers on marked enemies deals bonus Dendro damage. Her Burst buffs the team based on the elements present (EM bonus from Pyro characters, Crit Rate from Electro, duration from Hydro).
+
+**Best-in-Slot:**
+- Weapon: A Thousand Floating Dreams (5-star, signature) — EM and team EM buff
+- Artifacts: 4pc Deepwood Memories — Dendro RES shred, best support set; or 4pc Gilded Dreams for personal DPS
+
+**Strong F2P:**
+- Weapon: Sacrificial Fragments (4-star) — EM primary, double Skill cast
+- Weapon: Magic Guide (3-star) — actually competitive at R5, EM secondary and DMG bonus against wet/electro enemies
+
+**Core Teams:**
+1. Quickbloom: Nahida / Raiden / Xingqiu / Baizhu — Dendro + Electro + Hydro for Quicken, Bloom, and Hyperbloom reactions
+2. Aggravate: Nahida / Fischl / Keqing / Kazuha
+3. Burgeon: Nahida / Thoma / Xingqiu / flex — Thoma triggers Burgeon explosions
+
+---
+
+## General Team Building Principles
+
+### Resonance Bonuses Worth Building Around
+- **Pyro Resonance:** +25% ATK — reason Bennett appears in so many teams
+- **Cryo Resonance:** +15% CRIT Rate against Frozen or Cryo-affected enemies — reason Freeze teams can drop CRIT Rate investment
+- **Geo Resonance:** +15% shield strength, +15% DMG while shielded — makes double-Geo teams inherently strong
+- **Dendro Resonance:** +50 EM and additional EM scaling — makes Dendro-heavy reaction teams hit harder
+
+### The Four Roles in a Team
+1. **Main DPS:** On-field as much as possible, most field time, primary damage
+2. **Sub-DPS:** Off-field damage through Skills or Bursts
+3. **Support:** Buffs, healing, shields, crowd control
+4. **Battery:** Generates energy particles for the team (often doubled with another role)
+
+### ER (Energy Recharge) Thresholds — Common Benchmarks
+- Xiangling: 180-200% ER
+- Fischl: 120% ER (minimal, Oz generates well)
+- Raiden: 250-300% ER (converts to ATK via passive)
+- Bennett: 170-190% ER
+- Xingqiu: 180-200% ER
+- Nahida: 120-130% ER (low cost Burst)
+
+### Artifact Investment Priority
+Invest in characters in this order for efficient resource use:
+1. Main DPS — highest priority for good substats
+2. Key supports (Bennett, Kazuha, Xingqiu) — 4pc set bonus matters more than substats
+3. Flex support — functional artifacts sufficient
+4. Shielder/healer — set bonus matters, substats less critical
+
+---

docs/characters_lore.md

@@ -0,0 +1,204 @@
+# Genshin Impact — Character Lore & Backstories
+
+---
+
+## The Seven Archons
+
+### Venti (Barbatos) — Anemo Archon of Mondstadt
+Venti is the current vessel of Barbatos, the Anemo Archon and one of the Seven. Barbatos is considered the weakest of the Seven in terms of direct divine power, but he governs Mondstadt through freedom rather than control. He does not rule through a council or hierarchy — he simply lets his people govern themselves, which is why Mondstadt has no Archon statue that citizens pray to actively ruling the city.
+
+In the ancient past, Barbatos was a minor wind spirit who befriended a nameless bard during the Archon War — a human who dreamed of liberating Mondstadt from the tyrant Decarabian, the God of Storms. When that bard died in the uprising, Barbatos took on his appearance as a tribute. The form Venti wears today is a memory of his closest friend.
+
+Barbatos fought in the Archon War roughly 2000 years ago and secured Mondstadt, then largely disappeared. He is frequently absent from Mondstadt and spends centuries wandering. This laissez-faire approach is intentional — he believes true freedom means not needing a god to watch over you. He is deeply connected to music and wind, and his gnosis (the divine object representing his status among the Seven) was stolen by Signora of the Fatui, severely weakening him. He eventually reclaims it with the Traveler's help.
+
+Venti has a complicated relationship with memory and loss. The deaths of his friends — the nameless bard, Dvalin's suffering, the erosion of the old Mondstadt — weigh on him. He is playful and cheerful on the surface but carries deep grief beneath it.
+
+---
+
+### Zhongli (Morax) — Geo Archon of Liyue
+Zhongli is the consultant of Wangsheng Funeral Parlor and the current mortal vessel of Morax, the Geo Archon, also known as the God of Contracts. He is one of the oldest and most powerful of the Seven, having fought in the Archon War longer than almost anyone and survived to the modern era.
+
+Morax built Liyue through contracts — literal divine contracts binding the adepti, the gods, and later the humans of Liyue to obligations of service and protection. His philosophy is that a contract freely entered is the foundation of civilization. Unlike Barbatos, Morax was heavily involved in governance for thousands of years, working alongside the adepti (divine beings who served him) to protect Liyue from monsters and rival gods.
+
+At the start of the Liyue chapter, Zhongli stages his own death — faking a battle with Osial, an ancient god — to test whether Liyue's people can govern themselves without a god watching over them. He hands his gnosis over to the Tsaritsa of the Fatui as part of a contract, which confuses everyone watching because it seems like a betrayal. In truth, the contract terms are his own, and he judges Liyue ready to stand without him.
+
+Zhongli has known every major adeptus in Liyue, has lived through the Archon War, the defeat of Osial, and the rise of the Liyue Qixing merchant council. His mortal form ages and he chooses to keep living as a human, maintaining contracts and relationships with the living world. He is close to Hu Tao, the director of Wangsheng Funeral Parlor, and mentors Cloud Retainer's apprentice Shenhe.
+
+His personality is formal, deliberate, and knowledgeable to an almost absurd degree. He once spent an entire afternoon explaining the history of every ingredient in a meal. He also perpetually runs out of mora, because he has lived so long that he genuinely does not grasp modern currency management.
+
+---
+
+### Ei (Makoto / Raiden Shogun) — Electro Archon of Inazuma
+The Raiden Shogun is actually two entities sharing one body: Ei, the true Electro Archon who currently rules Inazuma, and the Shogun, a puppet Ei created to govern while Ei herself meditates inside the Plane of Euthymia within her own mind.
+
+The original Electro Archon was Makoto, Ei's twin sister. Makoto died during the cataclysm that also destroyed Khaenri'ah, leaving Ei alone. Ei had already watched countless friends and her sister die, including the deaths of Orobashi (the Narukami Ogre god), Gorou's ancestral general, and Istaroth. Overwhelmed by grief and the fear of losing more, Ei adopted the philosophy of Eternity — she would preserve Inazuma exactly as it was, forever, sacrificing change and progress to prevent loss.
+
+To achieve this, she sealed herself inside a statue and created the Shogun puppet to enforce the Vision Hunt Decree — a policy of taking away Visions (divine gifts from the gods) from citizens, believing that human ambition and individual destiny were what led to loss and change. This makes the early Inazuma arc feel oppressive, because it is — it is Ei's grief turned into policy.
+
+When the Traveler reaches Ei in the Plane of Euthymia and defeats the phantom she created of Makoto, Ei begins to confront the reality that Eternity maintained through stasis is not the same as true preservation. She ends the Vision Hunt Decree and begins to open Inazuma to the outside world. Her character arc through the Archon quest and her story quest is one of the most emotional in the game — the portrait of a god who has been alone with her grief for five hundred years.
+
+Ei is formal, stoic, and often confused by modern customs (she has been meditating for centuries). She is close to Yae Miko, the Guuji of the Grand Narukami Shrine, who has been Ei's most consistent companion through the centuries and acts as her emotional anchor and occasional teasing voice of reason.
+
+---
+
+### Nahida (Lesser Lord Kusanali) — Dendro Archon of Sumeru
+Nahida is the current Dendro Archon of Sumeru and the God of Wisdom, though she spent most of her existence imprisoned inside the Sanctuary of Surasthana by the Sages of Sumeru's Akademiya, who found a child-like god of wisdom inconvenient to their political control of knowledge.
+
+The previous Dendro Archon died during the cataclysm five hundred years ago. Nahida was born as a replacement but was immediately confined. She has almost no experience of the physical world, having spent her existence within the Irminsul — the divine tree that records all of Teyvat's memories and history — and within people's dreams, which she could access from her prison.
+
+Her confinement is a deliberate tragedy: the God of Wisdom locked away from wisdom, the guardian of Sumeru stripped of agency by the very institution that claims to serve knowledge. When the Traveler arrives in Sumeru, the Akademiya is already engaged in a scheme involving the Scaramouche (Wanderer), the Gnosis, and a plan to essentially become gods themselves through abusing the Irminsul.
+
+Nahida is extraordinary in her emotional intelligence despite her isolation. She has watched humanity through dreams for five hundred years and understands people deeply, even if she doesn't always understand the physical world. She is gentle, curious, and precise. Her relationship with the Traveler is unique — she asks questions genuinely, without pretension, and is moved by small gestures of connection.
+
+Her power over the Irminsul means she can read and even edit the records of history, which becomes plot-critical when she erases Scaramouche's existence from records to prevent paradox after his defeat. The cost of that action falls on her.
+
+---
+
+### Furina (Focalors) — Hydro Archon of Fontaine
+Furina is one of the most tragic characters in Genshin's story. On the surface she appears to be the theatrical, dramatic Hydro Archon who presides over Fontaine's Court of Fontaine (a judicial system where all disputes are settled through trials). The truth is far more complicated.
+
+Five hundred years ago, a prophecy stated that Fontaine would be destroyed — that the people of Fontaine, who all carry a divine curse in their bloodline, would one day dissolve into the Primordial Sea and cease to exist. The true Hydro Archon Focalors devised a plan to break this prophecy: she would split herself into two — a human vessel named Furina who would contain no divine power and no memories of being a god, and a divine consciousness that would wait. Furina would live as a mortal pretending to be an Archon for five hundred years.
+
+For five hundred years, Furina performed being a god. She presided over trials with theatrical flair, maintained the illusion of divine authority, and never let anyone know she was terrified and alone and entirely human. She couldn't tell anyone the truth. She had no divine power to fall back on. Every moment was a performance sustained by sheer willpower and the fear that breaking the act would destroy the plan that could save her people.
+
+When the Traveler arrives and the truth finally comes out, Furina's breakdown is one of the most emotionally raw moments in the game. She is not a goddess. She is a human woman who has been carrying the weight of an entire civilization's fate alone for five centuries, and she is exhausted. The resolution of her arc — including the sacrifice of Focalors herself — and Furina's choice to keep living as an ordinary human afterward, is genuinely moving.
+
+---
+
+### Nahida's predecessor (Greater Lord Rukkhadevata)
+The original Dendro Archon before Nahida was known as Greater Lord Rukkhadevata, who was closely tied to the Irminsul and to King Deshret's ancient civilization. She sacrificed herself during the cataclysm five hundred years ago to contain a spreading corruption. Her legacy shapes all of Sumeru's history and the Akademiya's founding mythology.
+
+---
+
+## Major Non-Archon Characters
+
+### Hu Tao — 77th Director of Wangsheng Funeral Parlor
+Hu Tao is the director of Liyue's premier funeral services company and one of Liyue's most recognizable figures. She is eccentric, enthusiastic about death (in a philosophical rather than morbid way), and deeply caring beneath her provocative exterior. She took over the directorship of Wangsheng at a very young age and has transformed it into a thriving institution.
+
+Her relationship with Zhongli is warm — he is her consultant and she respects his ancient wisdom, while she drags him into the modern world. She writes terrible poetry that she is very proud of. She has a genuine spiritual sensitivity and can perceive the dead and the boundary between life and death.
+
+In terms of her worldview, Hu Tao sees death as a necessary and even beautiful part of life's cycle — not something to fear, but to understand and honor. This makes her approach to the funeral business genuinely compassionate rather than mercenary.
+
+---
+
+### Xiao — Yaksha of Liyue
+Xiao is one of the five Yakshas, divine warriors who served Morax and were tasked with purging demons and malevolent spirits across Liyue. He is the last surviving Yaksha — the others fell to madness, corruption, or death from consuming too much karmic debt (the spiritual residue left by demons they killed).
+
+Xiao carries an immense burden of guilt and pain. Centuries of killing demons has left him perpetually poisoned by their karma. He suffers from nightmares and can never fully rest. The demon he is most associated with — and the one he calls his true enemy — is his own past self, when he was enslaved by a god and forced to kill.
+
+His connection to the Traveler is one of the few things that seems to genuinely ease his suffering. He is curt and antisocial, but fiercely protective of those he cares about. His relationship with Ganyu, who also served Morax, is one of cautious mutual respect.
+
+---
+
+### Ganyu — Secretary of the Liyue Qixing
+Ganyu is half-human, half-adeptus, born from the union of a human and a qilin (a divine creature). She has served Morax and the Liyue Qixing for nearly three thousand years as a secretary and emissary. She is overworked, self-deprecating about her half-human heritage (which she sees as a flaw), and deeply loyal to Liyue.
+
+Her arc involves coming to terms with her identity — she spent millennia feeling like she belonged fully to neither the human world nor the adepti world. The Traveler's acceptance and her own growth through the Lantern Rite events help her find peace with herself.
+
+---
+
+### Keqing — Yuheng of the Liyue Qixing
+Keqing is one of the seven members of the Liyue Qixing, Liyue's governing merchant council. She is hardworking, pragmatic, and notably skeptical of divine authority — she believes humans should not rely on gods to solve human problems. This puts her in interesting ideological contrast with the adepti-worshipping parts of Liyue culture.
+
+When Zhongli stages his death, Keqing is one of the people who springs into action to ensure Liyue can function without an Archon — which is exactly what Zhongli wanted to see happen.
+
+---
+
+### Tartaglia (Childe, Ajax) — 11th Harbinger of the Fatui
+Childe is one of the Eleven Harbingers, elite agents of the Tsaritsa of Snezhnaya. Unlike most Harbingers who are cold and calculating, Childe is genuinely enthusiastic about battle — almost boyishly so. He loves a fair fight more than anything.
+
+His backstory: as a teenager, Ajax fell into an Abyss portal and survived by learning combat from Skirk, a mysterious master who lives at the bottom of the Abyss. He emerged fundamentally changed — capable of activating a Foul Legacy transformation that taps into Abyssal power at the cost of his own sanity and body.
+
+Childe is genuinely fond of his family (his younger siblings in Snezhnaya) and has a complicated relationship with his role as a Harbinger. He serves the Tsaritsa but is not ideologically committed to the cause in the way other Harbingers are. His battle with the Traveler during the Liyue chapter — when he summons Osial — is a sincere test of strength rather than a calculated political move.
+
+---
+
+### Albedo — Chief Alchemist of the Knights of Favonius
+Albedo is a synthetic human created by the alchemist Rhinedottir, also known as Gold, who was a student of the ancient scholar Rhinedottir of Khaenri'ah. He was created through alchemy and is technically a homunculus — a constructed life form. His existence raises questions he actively investigates: what defines life, what distinguishes constructed existence from natural existence, and whether his consciousness is meaningfully different from a human's.
+
+He is brilliant, methodical, and somewhat removed from human emotion without being cold. His relationship with his apprentice Sucrose is warm — she is one of the few people he is openly kind to. His creation by a Khaenri'ah-connected figure and his synthetic nature put him in a complicated position relative to the game's larger mysteries.
+
+---
+
+### Diluc — Owner of Dawn Winery
+Diluc is one of the most powerful humans in Mondstadt, former Knight of Favonius captain, and current vigilante who fights monsters without official affiliation. His father died after using a Delusion (a fake Vision created by the Fatui) which destroyed his body, and Diluc blamed the Knights of Favonius for covering it up. He resigned and spent years traveling the world investigating the Fatui.
+
+He returned to Mondstadt before the events of the game and now operates Dawn Winery during the day and patrols the city at night. His relationship with Kaeya — his adopted brother — is deeply complicated. Kaeya is secretly of Khaenri'ah origin, sent to Mondstadt as a child by his father for unknown reasons. When Diluc discovered this during a confrontation after his father's death, their relationship shattered, and it has not been fully repaired.
+
+---
+
+### Kaeya — Cavalry Captain of the Knights of Favonius
+Kaeya is charming, manipulative, and deeply secretive. He was sent to Mondstadt as a child by his Khaenri'ah father as a secret asset — an insurance policy, as Kaeya himself describes it. He has genuinely come to care about Mondstadt over the years, but his ultimate loyalties and goals remain ambiguous.
+
+His relationship with Diluc is the most emotionally loaded relationship between two playable characters — broken brotherhood, mutual grief over their father, and years of estrangement during which neither fully let go.
+
+---
+
+### Fischl — Investigator of the Adventurers' Guild
+Fischl is a young woman who has committed fully to a fantasy alter-ego as "Fischl von Luftschloss Narfidort," a traveler from another world. She speaks in elaborate archaic language and is accompanied by Oz, a raven who is actually a manifestation of her Vision.
+
+Beneath the performance, Fischl is a deeply lonely person who created her persona as a coping mechanism. She communicates more authentically through Oz than through her own speech. Her friendship with Mona, who sees through the persona but respects what it means to her, is one of the warmer background relationships in Mondstadt.
+
+---
+
+### Cyno — General Mahamatra of Sumeru
+Cyno is the chief enforcer of Sumeru's Akademiya, responsible for investigating and punishing researchers who violate academic ethics — particularly those who pursue forbidden knowledge or abuse Akasha terminals. He is intensely serious and dedicated to justice, but is also notorious for telling terrible jokes that he genuinely believes are funny.
+
+His backstory involves the ancient game of Tcg (Genius Invokation) and his childhood friend Tighnari. He carries significant guilt over events in his past involving a researcher whose case he pursued. His story quest is one of the more nuanced explorations of what justice means versus what law requires.
+
+---
+
+### Tighnari — Forest Watcher of Avidya Forest
+Tighnari is a forest ranger in Sumeru's Avidya Forest, a scholar trained by the Akademiya who chose to leave academic life to do practical conservation work. He is calm, precise, slightly condescending when people don't listen to expert advice, and genuinely passionate about the forest's ecosystem. He was one of the early resistors to the Akademiya's worst abuses.
+
+---
+
+### Wanderer (Scaramouche / Kunikuzushi / Kabukimono)
+Scaramouche has one of the most complex backstories in the game. He was created by Ei as a prototype vessel for her soul — an artificial being who was discarded when Ei decided the puppet she made later was better suited. He was abandoned without purpose or identity.
+
+He was subsequently found by Niwa, a kind craftsman who treated him warmly, but Scaramouche left before the relationship could fully develop, afraid of attachment. He was later manipulated by the Fatui and became the 6th Harbinger, using cruelty as armor against the fundamental wound of his creation: he was made to be used and then thrown away.
+
+During the Sumeru arc, he attempts to become a god by merging with the Shouki no Kami construct and using the Gnosis to ascend. After his defeat, Nahida erases his existence from the Irminsul records to prevent paradox. He is reborn without his memories under the name Wanderer, choosing to build a new identity from scratch. His story quest as the Wanderer is one of the best character quests in the game — a meditation on whether identity requires continuity of memory.
+
+---
+
+### Arlecchino (Knave) — 4th Harbinger of the Fatui
+Arlecchino runs the House of the Hearth, the Fatui's orphanage that recruits and trains children as future agents. She is terrifying, elegant, and operates on her own terms even within the Fatui structure. Her relationship with her "children" in the House of the Hearth is genuinely complex — she is not warm, but she is not cruel without purpose, and she provides real protection and resources to children who had nowhere else to go.
+
+Her backstory involves an old leader of the House whose methods she found unacceptable. She killed him and took over, transforming the House into something closer to her own vision. Her loyalty to the Tsaritsa is genuine but conditional.
+
+---
+
+### Wriothesley — Duke of Meropide Fortress
+Wriothesley runs Fontaine's underwater prison, the Fortress of Meropide, which operates as a largely self-governing society of inmates. He won leadership through combat and manages the place with fair but firm authority. His own past includes crimes committed out of survival during a brutal childhood, and he has made peace with serving his time through governance.
+
+He is one of the most emotionally stable characters in the game — he knows who he is, is not tortured by his past, and focuses on practical good. His relationship with Furina is one of the few where Furina is treated as a person rather than a symbol.
+
+---
+
+### Navia — President of Spina di Rosula
+Navia leads a Fontaine faction organization that has historical tension with the government. Her father was falsely accused of a crime and died as a result of the legal fallout. She pursues justice for him and truth about the conspiracy that destroyed her family while maintaining the organization her father built. She is warm, generous, and carries grief quietly.
+
+---
+
+### Clorinde — Champion Duelist of Fontaine
+Clorinde is Fontaine's official Champion Duelist, a legally recognized role for settling disputes through combat. She has a bond with Navia that dates back to childhood and is one of the most loyal characters in Fontaine's story. Her backstory involves a pact with a demon that she carries in her arm — a consequence of a desperate decision made years earlier.
+
+---
+
+### Lyney and Lynette — Magicians of the House of the Hearth
+Lyney and Lynette are siblings raised in the House of the Hearth under Arlecchino. Lyney is the performer, extroverted and theatrical; Lynette is quieter, more observant, and deeply bonded with her brother. They work together as stage magicians and as Fatui operatives. Their loyalty is primarily to each other and to Arlecchino rather than to the Fatui as an institution.
+
+---
+
+### Neuvillette — Iudex (Chief Justice) of Fontaine
+Neuvillette is the Chief Justice of Fontaine's court system and one of the most powerful beings in the game. He is revealed to be the Dragon of Water, an ancient sovereign creature predating the current divine order of Teyvat. The Hydro Archon's power was derived from him, not the other way around.
+
+He is quiet, precise, and deeply invested in the concept of justice — not law, but actual justice. He can make it rain when he is grieving, which happens at story-relevant moments in ways that hit hard in context. His relationship with Furina evolves from professional distance to genuine care for her wellbeing once the truth of her situation is revealed.
+
+---
+
+### Shenhe — Adeptus Disciple of Cloud Retainer
+Shenhe was a human child taken in by the adeptus Cloud Retainer after a traumatic childhood. She was trained in adeptal arts but the training required her to bind her own emotions, making her seem cold and detached. She is not — she feels deeply, but has been taught that her emotions are dangerous. Her connection to Liyue's characters and her slow process of learning to trust her own feelings make her a compelling figure.
+
+---

docs/demo.html

@@ -0,0 +1,321 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>LLMOps RAG — Live Demo</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500&family=Syne:wght@400;600;700&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg: #0a0a0b;
+    --surface: #111113;
+    --surface2: #18181c;
+    --border: #2a2a30;
+    --border2: #3a3a42;
+    --accent: #7c6af7;
+    --accent2: #a89cf7;
+    --green: #3dd68c;
+    --red: #f76a6a;
+    --amber: #f7c26a;
+    --text: #e8e8f0;
+    --text2: #8888a0;
+    --text3: #555568;
+    --mono: 'JetBrains Mono', monospace;
+    --sans: 'Syne', sans-serif;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { background: var(--bg); color: var(--text); font-family: var(--sans); min-height: 100vh; display: flex; flex-direction: column; }
+  body::before { content: ''; position: fixed; inset: 0; background-image: linear-gradient(rgba(124,106,247,0.03) 1px, transparent 1px), linear-gradient(90deg, rgba(124,106,247,0.03) 1px, transparent 1px); background-size: 40px 40px; pointer-events: none; z-index: 0; }
+
+  header { position: relative; z-index: 1; padding: 24px 40px; border-bottom: 1px solid var(--border); display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 12px; }
+  .logo { display: flex; align-items: center; gap: 14px; }
+  .logo-mark { width: 36px; height: 36px; border-radius: 8px; background: var(--accent); display: flex; align-items: center; justify-content: center; font-family: var(--mono); font-size: 14px; font-weight: 500; color: #fff; }
+  .logo-text { font-size: 16px; font-weight: 700; letter-spacing: -0.3px; }
+  .logo-sub { font-size: 11px; color: var(--text3); font-family: var(--mono); margin-top: 1px; }
+  .demo-pill { display: flex; align-items: center; gap: 7px; padding: 6px 14px; border-radius: 20px; border: 1px solid var(--accent); background: rgba(124,106,247,0.08); font-family: var(--mono); font-size: 11px; color: var(--accent2); }
+  .demo-dot { width: 6px; height: 6px; border-radius: 50%; background: var(--accent); animation: pulse 2s ease-in-out infinite; }
+  @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
+
+  .notice { position: relative; z-index: 1; margin: 20px 40px 0; padding: 12px 16px; border-radius: 8px; border: 1px solid rgba(247,194,106,0.3); background: rgba(247,194,106,0.06); font-family: var(--mono); font-size: 12px; color: var(--amber); line-height: 1.6; }
+  .notice a { color: var(--accent2); text-decoration: none; border-bottom: 1px solid var(--accent2); }
+
+  main { position: relative; z-index: 1; flex: 1; display: flex; flex-direction: column; max-width: 860px; width: 100%; margin: 0 auto; padding: 32px 40px 0; }
+
+  .hero { margin-bottom: 32px; }
+  .hero h1 { font-size: 28px; font-weight: 700; letter-spacing: -0.8px; line-height: 1.2; margin-bottom: 8px; }
+  .hero h1 span { color: var(--accent2); }
+  .hero p { font-size: 13px; color: var(--text2); font-family: var(--mono); line-height: 1.6; }
+  .model-tag { display: inline-flex; align-items: center; gap: 6px; margin-top: 10px; padding: 4px 10px; border-radius: 4px; border: 1px solid var(--border2); background: var(--surface2); font-family: var(--mono); font-size: 11px; color: var(--accent2); }
+
+  .suggested { margin-bottom: 16px; }
+  .suggested-label { font-family: var(--mono); font-size: 11px; color: var(--text3); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 8px; }
+  .suggested-chips { display: flex; flex-wrap: wrap; gap: 8px; }
+  .chip { padding: 6px 12px; border-radius: 6px; border: 1px solid var(--border2); background: var(--surface); font-family: var(--mono); font-size: 11px; color: var(--text2); cursor: pointer; transition: border-color 0.15s, color 0.15s; }
+  .chip:hover { border-color: var(--accent); color: var(--accent2); }
+
+  .query-box { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; overflow: hidden; transition: border-color 0.2s; }
+  .query-box:focus-within { border-color: var(--accent); }
+  .query-label { padding: 12px 16px 0; font-family: var(--mono); font-size: 11px; color: var(--text3); letter-spacing: 0.05em; text-transform: uppercase; }
+  textarea { width: 100%; background: transparent; border: none; outline: none; resize: none; padding: 10px 16px 14px; font-family: var(--mono); font-size: 14px; color: var(--text); line-height: 1.6; min-height: 80px; caret-color: var(--accent); }
+  textarea::placeholder { color: var(--text3); }
+  .query-footer { display: flex; align-items: center; justify-content: space-between; padding: 10px 14px; border-top: 1px solid var(--border); background: var(--surface2); }
+  .top-k-wrap { display: flex; align-items: center; gap: 8px; font-family: var(--mono); font-size: 12px; color: var(--text2); }
+  .top-k-wrap select { background: var(--surface); border: 1px solid var(--border2); border-radius: 4px; color: var(--text); font-family: var(--mono); font-size: 12px; padding: 3px 8px; cursor: pointer; outline: none; }
+  .send-btn { display: flex; align-items: center; gap: 8px; padding: 8px 18px; background: var(--accent); border: none; border-radius: 6px; color: #fff; font-family: var(--sans); font-size: 13px; font-weight: 600; cursor: pointer; transition: background 0.15s, transform 0.1s; }
+  .send-btn:hover { background: var(--accent2); }
+  .send-btn:active { transform: scale(0.97); }
+  .send-btn:disabled { background: var(--border2); color: var(--text3); cursor: not-allowed; transform: none; }
+
+  #response-area { margin-top: 24px; display: none; }
+  #response-area.visible { display: block; }
+  .response-card { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; overflow: hidden; }
+  .response-header { display: flex; align-items: center; justify-content: space-between; padding: 12px 16px; border-bottom: 1px solid var(--border); background: var(--surface2); }
+  .response-label { font-family: var(--mono); font-size: 11px; color: var(--text3); text-transform: uppercase; letter-spacing: 0.05em; display: flex; align-items: center; gap: 7px; }
+  .response-label .dot { width: 6px; height: 6px; border-radius: 50%; background: var(--green); }
+  .latency-tag { font-family: var(--mono); font-size: 11px; color: var(--text3); padding: 2px 8px; border-radius: 3px; border: 1px solid var(--border); }
+  .response-body { padding: 20px; font-size: 14px; line-height: 1.8; color: var(--text); white-space: pre-wrap; word-break: break-word; }
+  .thinking { display: flex; align-items: center; gap: 10px; padding: 20px; font-family: var(--mono); font-size: 13px; color: var(--text2); }
+  .thinking-dots span { display: inline-block; width: 5px; height: 5px; border-radius: 50%; background: var(--accent); margin: 0 2px; animation: bounce 1.2s ease-in-out infinite; }
+  .thinking-dots span:nth-child(2) { animation-delay: 0.2s; }
+  .thinking-dots span:nth-child(3) { animation-delay: 0.4s; }
+  @keyframes bounce { 0%,80%,100%{transform:translateY(0)} 40%{transform:translateY(-6px)} }
+  .sources-section { border-top: 1px solid var(--border); padding: 12px 20px; background: var(--surface2); }
+  .sources-label { font-family: var(--mono); font-size: 11px; color: var(--text3); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 8px; }
+  .source-chip { display: inline-flex; align-items: center; gap: 5px; padding: 3px 9px; border-radius: 4px; border: 1px solid var(--border2); background: var(--surface); font-family: var(--mono); font-size: 11px; color: var(--accent2); margin: 3px 4px 3px 0; }
+
+  .history-section { margin-top: 28px; padding-bottom: 40px; }
+  .history-label { font-family: var(--mono); font-size: 11px; color: var(--text3); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 10px; }
+  .history-item { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 10px 14px; margin-bottom: 6px; cursor: pointer; transition: border-color 0.15s; }
+  .history-item:hover { border-color: var(--border2); }
+  .history-q { font-size: 13px; color: var(--text2); font-family: var(--mono); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .history-meta { font-size: 11px; color: var(--text3); font-family: var(--mono); margin-top: 3px; }
+
+  footer { position: relative; z-index: 1; text-align: center; padding: 20px; font-family: var(--mono); font-size: 11px; color: var(--text3); border-top: 1px solid var(--border); margin-top: auto; }
+  footer a { color: var(--accent2); text-decoration: none; }
+</style>
+</head>
+<body>
+
+<header>
+  <div class="logo">
+    <div class="logo-mark">λ</div>
+    <div>
+      <div class="logo-text">LLMOps RAG</div>
+      <div class="logo-sub">Llama 3.1 · QLoRA · Pinecone</div>
+    </div>
+  </div>
+  <div class="demo-pill">
+    <div class="demo-dot"></div>
+    static demo — simulated responses
+  </div>
+</header>
+
+<div class="notice">
+  ⚡ This is a static demo running in-browser. Responses are simulated from the actual model outputs.
+  The live API (FastAPI + Llama 3.1 8B) runs locally or on Azure — see the
+  <a href="https://github.com/MukulRay1603/Irminsul" target="_blank">GitHub repo</a> to run it yourself.
+</div>
+
+<main>
+  <div class="hero">
+    <h1>Ask your <span>fine-tuned</span> model</h1>
+    <p>Llama 3.1 8B · QLoRA exp2_lr2e-4_r16 · RTX 3060 · 4-bit NF4 · Pinecone RAG</p>
+    <div class="model-tag"><span>●</span> Retrieval-augmented · semantic search over Genshin corpus</div>
+  </div>
+
+  <div class="suggested">
+    <div class="suggested-label">try these</div>
+    <div class="suggested-chips">
+      <div class="chip" onclick="setQuery(this)">What weapons should Hu Tao use on a budget?</div>
+      <div class="chip" onclick="setQuery(this)">How did Venti become the Anemo Archon?</div>
+      <div class="chip" onclick="setQuery(this)">Compare Zhongli and Ei's ruling philosophies</div>
+      <div class="chip" onclick="setQuery(this)">How does the Vaporize reaction work?</div>
+      <div class="chip" onclick="setQuery(this)">What is Scaramouche's backstory?</div>
+      <div class="chip" onclick="setQuery(this)">Best team comp for Ayaka?</div>
+    </div>
+  </div>
+
+  <div class="query-box">
+    <div class="query-label">query</div>
+    <textarea id="query-input" placeholder="Ask anything about Genshin lore, builds, or mechanics..." rows="3"></textarea>
+    <div class="query-footer">
+      <div class="top-k-wrap">
+        <span>top_k</span>
+        <select id="top-k">
+          <option value="1">1</option>
+          <option value="2">2</option>
+          <option value="3" selected>3</option>
+          <option value="5">5</option>
+        </select>
+        <span style="color:var(--text3)">retrieved chunks</span>
+      </div>
+      <button class="send-btn" id="send-btn" onclick="submitQuery()">
+        Run query →
+      </button>
+    </div>
+  </div>
+
+  <div id="response-area">
+    <div class="response-card">
+      <div class="response-header">
+        <div class="response-label"><div class="dot"></div>response</div>
+        <div class="latency-tag" id="latency-tag">—</div>
+      </div>
+      <div id="response-body" class="response-body"></div>
+      <div class="sources-section">
+        <div class="sources-label">sources</div>
+        <div id="sources-list"></div>
+      </div>
+    </div>
+  </div>
+
+  <div class="history-section" id="history-section" style="display:none">
+    <div class="history-label">recent queries</div>
+    <div id="history-list"></div>
+  </div>
+</main>
+
+<footer>
+  static demo · <a href="https://github.com/YOUR_USERNAME/llmops-serve" target="_blank">github</a> · llmops-serve · Llama 3.1 8B QLoRA
+</footer>
+
+<script>
+const MOCK_RESPONSES = {
+  "hu tao": {
+    answer: `For Hu Tao on a budget, Dragon's Bane is the strongest F2P option — it scales with Elemental Mastery and deals significant bonus damage on vaporized hits. White Tassel is the best 3-star alternative for pure Normal Attack scaling.
+
+For artifacts, 4pc Crimson Witch of Flames is the goal. Prioritize CRIT Rate, CRIT DMG, HP%, and Elemental Mastery as substats.
+
+Budget team: Hu Tao / Xingqiu / Sucrose / Noelle. Sucrose provides EM sharing and grouping; Noelle covers shields and healing so Hu Tao can stay at low HP for her passive bonus.`,
+    sources: ["docs/character_builds.md"],
+    latency_ms: 4821
+  },
+  "venti": {
+    answer: `Venti is the current vessel of Barbatos, the Anemo Archon. Barbatos was originally a minor wind spirit who befriended a nameless bard during the Archon War — a human who dreamed of liberating Mondstadt from the tyrant Decarabian, the God of Storms.
+
+When that bard died in the uprising, Barbatos took on his appearance as a permanent tribute. The form Venti wears today is a memory of his closest friend. He fought in the Archon War roughly 2000 years ago and secured Mondstadt, governing through freedom rather than direct rule — he lets his people govern themselves.`,
+    sources: ["docs/characters_lore.md"],
+    latency_ms: 5103
+  },
+  "zhongli": {
+    answer: `Zhongli (Morax) built Liyue through contracts — literal divine agreements binding the adepti and humans to obligations of service and protection. His philosophy: a contract freely entered is the foundation of civilization. He governed actively for thousands of years alongside the adepti.
+
+Ei (Raiden Shogun) adopted the philosophy of Eternity — preserving Inazuma exactly as it was to prevent further loss after watching her sister Makoto and countless friends die. She sealed herself in meditation and created the Vision Hunt Decree to freeze change entirely.
+
+One governs through trust and agreement; the other through enforced stasis. Both are responses to loss, but opposite in method.`,
+    sources: ["docs/characters_lore.md", "docs/world_lore.md"],
+    latency_ms: 6240
+  },
+  "vaporize": {
+    answer: `Vaporize is one of the two amplifying reactions in Genshin — it multiplies the triggering hit directly rather than dealing separate damage.
+
+Pyro hitting a Hydro-affected enemy = 1.5x Pyro damage multiplier.
+Hydro hitting a Pyro-affected enemy = 2.0x Hydro damage multiplier.
+
+Most Vaporize teams are built around the 1.5x Pyro trigger — characters like Hu Tao or Yoimiya repeatedly applying Pyro against a Hydro-maintained aura from Xingqiu or Yelan. Elemental Mastery further increases the multiplier. The 2.0x version requires Hydro to be the trigger, which is harder to sustain consistently.`,
+    sources: ["docs/elemental_mechanics.md"],
+    latency_ms: 3987
+  },
+  "scaramouche": {
+    answer: `Scaramouche was created by Ei as a prototype vessel for her soul — an artificial being discarded when she decided her later puppet was better suited. He was abandoned without purpose or identity.
+
+He was found by a kind craftsman named Niwa who treated him warmly, but Scaramouche left before the relationship could develop, afraid of attachment. He was later manipulated by the Fatui and became the 6th Harbinger, using cruelty as armor against his core wound: he was made to be used and thrown away.
+
+After his defeat in Sumeru, Nahida erased his existence from the Irminsul records to prevent paradox. He was reborn as the Wanderer — no memories, a new identity built from scratch.`,
+    sources: ["docs/characters_lore.md"],
+    latency_ms: 5562
+  },
+  "ayaka": {
+    answer: `Ayaka's premier team is Freeze: Ayaka / Kokomi / Kazuha / Shenhe.
+
+Kokomi provides consistent Hydro application to maintain Freeze. Kazuha groups enemies and provides Cryo DMG% bonus via his A4 passive. Shenhe buffs Cryo damage with her Icy Quill stacks.
+
+For weapons, Mistsplitter Reforged is best-in-slot. F2P players should use Amenoma Kageuchi — craftable in Inazuma, with an ER passive that helps maintain Burst uptime.
+
+Artifacts: 4pc Blizzard Strayer is ideal. Against Frozen enemies it provides +40% CRIT Rate on top of +20% for Cryo, effectively giving free CRIT so you can invest fully into CRIT DMG instead.`,
+    sources: ["docs/character_builds.md"],
+    latency_ms: 4654
+  }
+};
+
+const history = [];
+
+function findMockResponse(query) {
+  const q = query.toLowerCase();
+  if (q.includes("hu tao") || q.includes("hutao")) return MOCK_RESPONSES["hu tao"];
+  if (q.includes("venti") || q.includes("barbatos") || q.includes("anemo archon")) return MOCK_RESPONSES["venti"];
+  if (q.includes("zhongli") || q.includes("ei") || q.includes("philosoph") || q.includes("ruling")) return MOCK_RESPONSES["zhongli"];
+  if (q.includes("vaporize") || q.includes("vapori")) return MOCK_RESPONSES["vaporize"];
+  if (q.includes("scaramouche") || q.includes("wanderer") || q.includes("backstory")) return MOCK_RESPONSES["scaramouche"];
+  if (q.includes("ayaka") || q.includes("kamisato")) return MOCK_RESPONSES["ayaka"];
+  return {
+    answer: `This demo runs simulated responses for a curated set of example queries. The live model (Llama 3.1 8B QLoRA fine-tuned) would retrieve relevant chunks from the Pinecone index and generate a grounded answer for any query.\n\nTry one of the suggested queries above, or clone the repo to run the full RAG pipeline locally.`,
+    sources: ["docs/character_builds.md", "docs/characters_lore.md"],
+    latency_ms: Math.floor(Math.random() * 2000) + 3000
+  };
+}
+
+function setQuery(el) {
+  document.getElementById('query-input').value = el.textContent;
+  document.getElementById('query-input').focus();
+}
+
+async function submitQuery() {
+  const query = document.getElementById('query-input').value.trim();
+  if (!query) return;
+
+  const btn = document.getElementById('send-btn');
+  const responseArea = document.getElementById('response-area');
+  const responseBody = document.getElementById('response-body');
+  const latencyTag = document.getElementById('latency-tag');
+  const sourcesList = document.getElementById('sources-list');
+
+  responseArea.className = 'visible';
+  responseArea.style.display = 'block';
+  btn.disabled = true;
+  latencyTag.textContent = '—';
+  sourcesList.innerHTML = '';
+
+  responseBody.innerHTML = `<div class="thinking"><div class="thinking-dots"><span></span><span></span><span></span></div>generating response...</div>`;
+
+  const mock = findMockResponse(query);
+  const delay = mock.latency_ms;
+
+  await new Promise(r => setTimeout(r, Math.min(delay * 0.3, 2200)));
+
+  responseBody.textContent = mock.answer;
+  const ms = mock.latency_ms;
+  latencyTag.textContent = ms >= 1000 ? `${(ms/1000).toFixed(1)}s` : `${ms}ms`;
+  sourcesList.innerHTML = mock.sources.map(s => {
+    const name = s.split(/[\\/]/).pop();
+    return `<span class="source-chip">📄 ${name}</span>`;
+  }).join('');
+
+  history.unshift({ query, latency_ms: ms, time: new Date().toLocaleTimeString() });
+  if (history.length > 5) history.pop();
+
+  const section = document.getElementById('history-section');
+  const list = document.getElementById('history-list');
+  section.style.display = 'block';
+  list.innerHTML = history.map((h, i) => `
+    <div class="history-item" onclick="rerun(${i})">
+      <div class="history-q">${h.query}</div>
+      <div class="history-meta">${h.time} · ${(h.latency_ms/1000).toFixed(1)}s</div>
+    </div>
+  `).join('');
+
+  btn.disabled = false;
+}
+
+function rerun(i) {
+  document.getElementById('query-input').value = history[i].query;
+  submitQuery();
+}
+
+document.getElementById('query-input').addEventListener('keydown', e => {
+  if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) { e.preventDefault(); submitQuery(); }
+});
+</script>
+</body>
+</html>

docs/elemental_mechanics.md

@@ -0,0 +1,207 @@
+# Genshin Impact — Elemental Mechanics, Reactions & Damage System
+
+---
+
+## The Seven Elements
+
+Every character and enemy in Genshin deals one or more of seven elemental types: Pyro, Hydro, Cryo, Electro, Anemo, Geo, and Dendro. Elements interact with each other through reactions, which are the fundamental engine of team building and damage optimization.
+
+---
+
+## Elemental Reactions
+
+### Vaporize (Pyro + Hydro)
+One of the two "amplifying" reactions — it multiplies the triggering hit directly.
+- Pyro hitting Hydro-affected enemy = 1.5x Pyro damage multiplier
+- Hydro hitting Pyro-affected enemy = 2.0x Hydro damage multiplier
+
+The 2.0x version (Hydro triggering on Pyro aura) is generally harder to achieve consistently. Most Vaporize teams are built around the 1.5x Pyro trigger — Pyro DPS characters like Hu Tao or Yoimiya repeatedly applying Pyro against a Hydro-maintained aura. Elemental Mastery increases the Vaporize multiplier further.
+
+**Key teams that abuse Vaporize:** Hu Tao/Yelan/Xingqiu, Yoimiya/Yelan, Childe/Xiangling, National Team
+
+---
+
+### Melt (Pyro + Cryo)
+The other amplifying reaction.
+- Pyro hitting Cryo-affected enemy = 2.0x Pyro damage
+- Cryo hitting Pyro-affected enemy = 1.5x Cryo damage
+
+The 2.0x version is why Ganyu Melt is so powerful — Ganyu's Charged Attacks are all Cryo, but paired with off-field Pyro application from Xiangling, the Pyro aura gets maintained and Ganyu's Cryo attacks trigger 1.5x Melt consistently. Hu Tao Melt works when Cryo maintains aura and Pyro triggers 2.0x.
+
+---
+
+### Freeze (Hydro + Cryo)
+Freezes the target, preventing movement and most actions for a duration. Frozen enemies can be Shattered by Heavy attacks (dealing Physical damage). Frozen enemies are also easy to hit.
+
+Critically, Frozen enemies maintain both the Hydro and Cryo aura simultaneously. This means:
+- Blizzard Strayer gives +40% CRIT Rate against Frozen enemies (on top of +20% against Cryo)
+- Freeze teams effectively have permanent CRIT Rate bonus, allowing investment to shift to CRIT DMG
+- Freeze is a soft CC that completely trivializes mobile enemies
+
+Freeze duration scales with the strength of the aura applied. Strong Hydro/Cryo application from multiple sources keeps enemies perma-frozen.
+
+---
+
+### Superconduct (Electro + Cryo)
+Deals minor AoE Electro-Cryo damage and reduces all enemies' Physical RES by 40% for 12 seconds. Not a damage reaction — purely a Physical resistance shred.
+
+Used exclusively in Physical DPS teams (Eula, Razor, physical Fischl) to amplify Physical damage. The CRIT Rate bonus for Cryo resonance and Superconduct together are why Cryo batteries (Rosaria, Kaeya) appear in physical DPS teams.
+
+---
+
+### Overloaded (Pyro + Electro)
+Explodes, dealing AoE Pyro-based damage and knocking enemies back. The knockback is significant — it pushes lighter enemies away, which can be disruptive to melee DPS characters who need to stay close.
+
+Overloaded damage scales with Elemental Mastery of the triggering character. High EM builds can make Overloaded deal meaningful damage, but the knockback problem limits its use in sustained DPS compositions. Thoma-triggered Burgeon teams and some Fischl/Pyro teams utilize it.
+
+---
+
+### Electrocharged (Electro + Hydro)
+Deals periodic Electro damage to all Electro-affected enemies connected through Hydro. The unique property: Electrocharged does not consume either aura — both Electro and Hydro coexist on the target simultaneously, allowing further reactions from other elements.
+
+This makes Electrocharged a unique reaction that can enable other reactions simultaneously. It also bounces damage between connected Hydro-affected enemies — in groups of wet enemies, Electrocharged chains across all of them.
+
+---
+
+### Swirl (Anemo + Pyro/Hydro/Cryo/Electro)
+Anemo cannot react with Geo or Dendro. Against all other elements, Anemo creates Swirl, which spreads the absorbed element to nearby enemies and deals bonus elemental damage. Swirl damage scales with Elemental Mastery only — not ATK or weapon stats.
+
+The critical secondary effect: Viridescent Venerer (VV) 4pc set — the standard Anemo support artifact set — reduces enemy RES to the Swirled element by 40% for 10 seconds. This is why Kazuha, Sucrose, and Venti always run 4pc VV in support roles. The 40% RES shred is worth more damage amplification than most direct damage buffs.
+
+Sucrose's Elemental Mastery shares 20% of her EM with the team when she triggers a Swirl, in addition to her Burst's team-wide EM buff.
+
+---
+
+### Crystallize (Geo + Pyro/Hydro/Cryo/Electro)
+Creates a shard when Geo contacts another element (except Anemo or Dendro). Picking up the shard gives a shield that absorbs the crystallized element. The shield strength scales with the character's Elemental Mastery and level.
+
+Crystallize is primarily a defensive reaction. Geo characters do not directly amplify elemental reactions — Geo's contribution is the universal shield and Geo RES shred (from Zhongli's pillar resonance and 4pc Tenacity of Millelith). Geo resonance (double Geo) gives +15% DMG while shielded and +15% shield strength.
+
+---
+
+### Quicken / Aggravate / Spread (Dendro + Electro)
+The Dendro-Electro interaction introduced in Sumeru is fundamentally different from other reactions.
+
+Quicken is the base reaction — Dendro + Electro creates a Quicken status on the enemy. From Quicken, two additional reactions branch:
+- **Aggravate:** Electro hitting a Quickened enemy — deals bonus Electro damage (fixed bonus scaling with EM and level, added on top of the hit)
+- **Spread:** Dendro hitting a Quickened enemy — deals bonus Dendro damage
+
+Neither Aggravate nor Spread consumes the Quicken status. Both can proc repeatedly as long as the enemy remains Quickened, which makes Dendro-Electro teams sustain high damage over time without the reaction-application timing management that Vaporize/Melt require.
+
+Key characters: Nahida (Spread trigger), Cyno (Aggravate main DPS), Fischl (Aggravate off-field), Raiden (Aggravate burst), Keqing (Aggravate main DPS)
+
+---
+
+### Bloom / Hyperbloom / Burgeon (Dendro + Hydro + Electro/Pyro)
+Bloom is the Dendro + Hydro reaction, which creates Dendro Cores — explosive seeds that detonate after a short time, dealing AoE Dendro damage. Bloom damage scales with EM and level.
+
+Dendro Cores can be further reacted:
+- **Hyperbloom:** Electro hitting a Dendro Core — the core homes in on the nearest enemy and deals much higher Dendro damage. This is one of the highest DPS reactions in the game. Scales with the Electro character's EM. Raiden Shogun at high EM is a premier Hyperbloom trigger.
+- **Burgeon:** Pyro hitting a Dendro Core — the core explodes in AoE Pyro-tinged Dendro damage. Scales with Pyro character's EM. The AoE can hit your own team, which requires careful HP management.
+
+Pure Bloom teams let cores explode naturally — effective but less optimized than Hyperbloom. Hyperbloom with Raiden or Fischl as trigger, Nahida for Dendro, and Xingqiu/Kokomi for Hydro is one of the strongest reaction-based team compositions.
+
+---
+
+## Internal Cooldown (ICD)
+
+ICD is one of the most important and least-explained mechanics in the game. When a character applies an element, there is a hidden cooldown before the same source can apply that element again. This prevents infinite reaction triggering.
+
+The standard ICD rule: the same hit source can apply an element every 2.5 seconds OR every 3 hits (whichever comes first is reset). After the cooldown, the next hit reapplies the element.
+
+**Why this matters for team building:**
+- Xingqiu's Rain Swords have ICD between slashes — not every slash applies Hydro. This means rapid Normal ATK DPS like Hu Tao can't Vaporize every hit; approximately every 3rd hit triggers a reaction.
+- Characters with no ICD on certain abilities (some AoE Bursts, specific skills) can apply elements much more freely.
+- Kazuha Swirling an element absorbs the element and applies it to all nearby enemies — this has its own ICD distinct from the source character.
+
+---
+
+## Damage Formula Overview
+
+Genshin's damage calculation follows this general structure:
+
+**Base Damage = Scaling Stat × Ability Scaling %**
+
+Scaling stat is typically ATK, but some abilities scale with HP (Hu Tao, Zhongli shield, Itto, Yelan) or DEF (Noelle, Itto burst, Albedo).
+
+**Total Damage = Base Damage × (1 + DMG Bonus) × CRIT multiplier × Enemy DEF multiplier × Enemy RES multiplier × Reaction multiplier**
+
+Breaking this down:
+- **DMG Bonus:** Sum of all elemental/physical DMG% bonuses from artifacts, weapons, and passives
+- **CRIT Multiplier:** (1 + CRIT DMG%) on a CRIT hit, 1 on non-crit; averaged to (1 + CRIT Rate × CRIT DMG%) for theoretical average
+- **Enemy DEF Multiplier:** Reduces based on attacker level vs. enemy level and DEF shred
+- **Enemy RES Multiplier:** Reduces based on enemy elemental resistance; VV and Zhongli reduce this
+- **Reaction Multiplier:** Vaporize/Melt multiplier, or additive bonus damage for Aggravate/Spread
+
+### The CRIT Ratio — the 1:2 Rule
+Optimal CRIT investment follows approximately a 1:2 ratio of CRIT Rate to CRIT DMG. 50% Rate / 100% DMG, 70% Rate / 140% DMG, etc. This maximizes average damage output. Deviating heavily in either direction (100% Rate / 50% DMG, for instance) is suboptimal.
+
+Characters with guaranteed CRIT sources (Ganyu's Charged Attack Level 2 always CRITs, Hu Tao's Blood Blossom CRITs under certain conditions) can shift investment toward CRIT DMG.
+
+---
+
+## Elemental Application Strength (Gauge Theory Basics)
+
+Elements in Genshin have invisible "gauge" values — stronger applications leave a bigger elemental aura that takes more of the opposing element to remove. Reactions consume specific amounts of gauge.
+
+**Practical implications:**
+- Hydro application from Xingqiu is moderate per slash. Pyro hits from Hu Tao consume the Hydro aura partially per hit, which is why even with ICD, Vaporize procs regularly.
+- Bennett's Burst applies Pyro AoE repeatedly — strong Pyro aura, enough to enable off-field Melt reactions.
+- Freeze duration depends on the combined strength of the Hydro and Cryo applications — strong applicators like Kokomi (Hydro) + Ayaka (Cryo Dash) maintain long Freeze durations.
+
+---
+
+## Character Stats — What Actually Matters
+
+### ATK vs HP vs DEF Scaling
+Most characters scale with ATK. HP scalers (Hu Tao, Zhongli, Yelan, Furina) specifically convert their HP stat into damage or utility, making HP% a primary stat for them instead of ATK%. DEF scalers (Noelle, Itto, Albedo's Flower) make DEF% valuable for damage.
+
+### The Artifact Main Stat Priority
+For DPS characters:
+- Sands: ATK% (usually) or ER% if energy-hungry, or EM for reaction-focused characters
+- Goblet: Elemental DMG Bonus (almost always, unless Physical DPS)
+- Circlet: CRIT Rate or CRIT DMG (match to where you're deficient)
+
+For supports:
+- Sands: ER% (for Burst uptime) or HP%/ATK% depending on scaling
+- Goblet: HP%, DEF%, or ATK% for shields/healing
+- Circlet: Healing Bonus% for healers, or HP%/ATK% for shields
+
+---
+
+## Constellation System
+
+Constellations are duplicate copies of a character — obtaining a character's item again (through wishes) unlocks constellation levels C1 through C6. This is where significant power spikes hide for some characters.
+
+### Notable Constellations
+- **Bennett C1:** Removes the HP threshold from his Burst ATK buff (below 70% HP requirement removed) — significant quality of life
+- **Bennett C6:** Converts sword/claymore/polearm characters in field to Pyro — potentially destructive, not universally desired
+- **Xingqiu C2:** Rain Swords deal 15% more DMG and grant 1 additional sword — major DPS increase
+- **Kazuha C2:** Grants 200 EM after using Burst — massive personal DPS increase, makes him competitive as a main DPS
+- **Fischl C6:** Joint ATK on every Electro reaction — nearly doubles her off-field output
+- **Xiangling C4:** Extends Pyronado duration by 40% — dramatically improves her consistency
+- **Ganyu C1:** Charged Attack generates an additional Cryo AoE — significant AoE improvement
+- **Raiden C2:** Resistance to interruption during Burst and significantly higher Burst DMG — major improvement
+- **Nahida C1:** Adds additional hit to her Skill marks — notable DPS boost
+- **Hu Tao C1:** Allows Charged Attack use without stamina cost during E — removes a significant quality of life limitation
+
+---
+
+## Spiral Abyss — Endgame Content
+
+The Spiral Abyss is the primary endgame challenge, consisting of 12 floors (floors 9-12 are the rotating difficult content). Each floor has two chambers, each with an enemy lineup and a time limit. Clearing within the time limit yields stars (up to 3 per chamber, 6 per floor). Full completion (36 stars) requires two separate teams since Floors 9-12 have a "split" mechanic — you must use two different teams for the two sides of each floor.
+
+This is why virtually all endgame discussion involves two teams. Building two strong teams that don't rely on the same key supports (you cannot use Bennett on both sides simultaneously, for instance) is the core strategic challenge of progression in Genshin.
+
+Floors 11-12 refresh every two weeks with new enemy lineups and modifiers. The current abyss cycle often features:
+- Buff cards that enhance certain reaction types or elements
+- Enemy weaknesses that reward specific element applications
+- Boss variants with high HP that favor sustained DPS teams
+
+### Spiral Abyss Team Archetypes
+- **Hypercarry:** One DPS supported by three dedicated supports — all buffs point at one character
+- **Dual DPS:** Two DPS characters alternating field time, supported by shared utilities
+- **Reaction team:** Built around consistent reaction triggering (Vaporize, Quickbloom, Freeze) rather than a single DPS carry
+- **Mono-element:** Single element team using resonance bonuses and elemental DMG buffs (Mono Pyro with Bennett/Xiangling/Kazuha)
+
+---

docs/world_lore.md

@@ -0,0 +1,137 @@
+# Genshin Impact — World Lore, Nations & the Overarching Mystery
+
+---
+
+## The World of Teyvat
+
+Teyvat is a world governed by seven elements — Anemo, Geo, Electro, Dendro, Hydro, Pyro, and Cryo — each overseen by one of the Seven Archons, divine beings who answer to Celestia, the heavenly realm visible in the sky above Teyvat. Celestia is not merely symbolic — it is a physical location in the sky, with structures visible at all times, and the source of divine authority that the current world order flows from.
+
+The world operates on a system that is increasingly revealed, as the story progresses, to be a kind of controlled environment. The Archons receive their power from Celestia. The Visions (divine gifts that give humans elemental power) are granted by unknown divine will. The history of Teyvat has been shaped by catastrophes that the current inhabitants either do not know about or have been made to forget.
+
+---
+
+## The Seven Nations
+
+### Mondstadt — Nation of Freedom (Anemo)
+Mondstadt is a city-state in a temperate region, governed by the Knights of Favonius and the nobility (the Lawrence Clan historically, though they were overthrown centuries ago in the Aristocracy's collapse). The Anemo Archon Barbatos is mostly absent, trusting humans to govern themselves.
+
+Mondstadt's culture is built around wine, music, and the ideal of freedom. The city itself is on an island in the middle of a lake, designed to be defensible. The surrounding region (Stormterror's Lair, Dragonspine, Wolvendom) holds many of the game's early exploration areas. Dragonspine is a permanently frozen mountain containing remnants of an ancient civilization that predates Mondstadt's current culture.
+
+The Knights of Favonius are the official military and law enforcement body, though they are notoriously inefficient by reputation (this is a recurring joke among Mondstadt characters). Diluc and other independent actors end up handling many actual threats.
+
+---
+
+### Liyue — Nation of Contracts (Geo)
+Liyue Harbor is the largest trading port in Teyvat and the economic center of the world. The Liyue Qixing (seven stars) are the seven merchant lords who govern the city's trade and administrative functions. Historically, the Geo Archon Morax and the adepti (divine creatures) worked alongside humans to protect Liyue from gods and monsters.
+
+The adepti are unique to Liyue — divine beings who bound themselves to Morax through contracts and have protected Liyue for thousands of years. They live in the mountains (particularly Jueyun Karst) and rarely interact with humans directly. Major adepti include Xiao, Cloud Retainer (who mentors Ganyu and Shenhe), Mountain Shaper, and Moon Carver.
+
+Liyue's aesthetic is heavily inspired by traditional Chinese architecture and culture. The Harbor is a massive city; beyond it lies an enormous continent of varied terrain including mountains, rivers, and the underground crystal mines.
+
+The Rex Lapis mythology is central to Liyue culture — annual celebrations like the Lantern Rite honor the Geo Archon's protection. When Zhongli stages his own death, it sends the entire city into mourning and near-crisis.
+
+---
+
+### Inazuma — Nation of Eternity (Electro)
+Inazuma is an archipelago of islands ruled under the Raiden Shogun's Vision Hunt Decree, which was in effect before the Traveler arrives. The nation is under a sakoku-style isolation — no one can enter or leave. The Traveler must infiltrate by surviving a sea storm.
+
+Inazuma's society is in conflict between the Shogunate (supporters of the Vision Hunt Decree and eternal stasis) and the Resistance (fighters on Watatsumi Island who oppose the Shogunate). Watatsumi Island worships Orobashi, an ancient serpent god who was killed by Morax, and holds resentment toward the mainland as a result.
+
+The culture is heavily inspired by Edo-period Japan. Key factions include the Kujou Clan (military commanders of the Shogunate), the Yashiro Commission (which runs the Grand Narukami Shrine and is led by Yae Miko), and the Kanjou Commission (trade and economics).
+
+The Vision Hunt Decree's resolution and Inazuma's opening to the world creates significant cultural and political changes in the nation's story quests and world quests.
+
+---
+
+### Sumeru — Nation of Wisdom (Dendro)
+Sumeru is a nation divided between a massive rainforest and a vast desert, unified under the Akademiya, the world's premier institution of knowledge and learning. The Akademiya controls the Akasha System — a divine network that gives citizens access to recorded knowledge through earpiece devices called Akasha Terminals.
+
+Sumeru's conflict is fundamentally about the relationship between knowledge, power, and wisdom. The Akademiya controls what knowledge is accessible, suppresses research that challenges their worldview, and confined the Dendro Archon for being inconvenient. The Sages who run the Akademiya are academics who have become administrators and enforcers.
+
+The desert region of Sumeru contains remnants of an ancient civilization — King Deshret's empire — that predates the current world order. The lore of Deshret, the Red King who sought forbidden knowledge, and his relationship with the original Dendro Archon Rukkhadevata is the foundation of Sumeru's deeper mysteries. The Irminsul, the divine tree that records all of Teyvat's memories, is rooted in Sumeru.
+
+Sumeru's culture is inspired by South Asian and Middle Eastern aesthetics, with the rainforest drawing from South Asian jungle architecture and the desert from ancient Egyptian/Persian motifs.
+
+---
+
+### Fontaine — Nation of Justice (Hydro)
+Fontaine is a steampunk-inspired nation built around waterways, advanced technology, and an elaborate court system. Every dispute in Fontaine, from minor disagreements to accusations of murder, is settled through public trials in the Court of Fontaine. The Hydro Archon presides as a theatrical judge figure.
+
+The key lore element of Fontaine is the ancient prophecy: all people of Fontaine carry a divine curse in their blood that will one day cause them to dissolve into the Primordial Sea. This prophecy has shaped the Hydro Archon's five-hundred-year plan (detailed in the character lore section under Furina).
+
+Fontaine is also notable for having the most technologically advanced infrastructure in Teyvat — hydroelectric power, automatons, submarines, and the Fortress of Meropide underwater prison. The Spina di Rosula and the Hydro Dragon mythology form important sub-plots.
+
+The resolution of the Fontaine Archon quest involves breaking the ancient prophecy, the sacrifice of the divine consciousness Focalors, and the transformation of Fontaine's people through Neuvillette's tears flooding and cleansing the land.
+
+---
+
+### Natlan — Nation of War (Pyro)
+Natlan is Teyvat's most recent major nation added to the game. It is a nation built around constant warfare — tribes compete in ritual combat, and strength is the primary cultural value. The Pyro Archon, Mavuika, is a warrior who leads from the front rather than governing from a throne.
+
+Natlan's unique mechanic is the Phlogiston system — Natlan characters use a special energy resource for movement (dashing, gliding speed) rather than or in addition to their normal combat abilities. The nation has a strong Central American/Mesoamerican aesthetic influence.
+
+The major conflict involves the Abyss directly — the shadows attacking Natlan are a direct incursion by Abyssal forces, and the Pyro Archon must rally the tribes to defend. The Traveler's sibling is heavily involved in the Natlan storyline.
+
+---
+
+### Snezhnaya — Nation of the Tsaritsa (Cryo)
+Snezhnaya is the home nation of the Fatui and the Tsaritsa, the Cryo Archon. It has not yet been fully explored in the game as of current content. The Tsaritsa is described as a god who has lost her love for her people and now pursues a revolution against Celestia — she is collecting the other Archons' Gnoses as part of a long-term plan.
+
+The Fatui are Snezhnaya's diplomatic and military arm — officially an organization of diplomats with diplomatic immunity, in practice a global network of intelligence, coercion, and military capability. The Eleven Harbingers are the elite.
+
+The Tsaritsa's motives are presented as sympathetic in context — she is acting against the celestial order, which the game increasingly frames as not benevolent. Whether her methods are justified is one of the open questions of the overarching plot.
+
+---
+
+## The Overarching Mystery — Celestia, the Abyss & Khaenri'ah
+
+### Khaenri'ah — The Nation Without a God
+Five hundred years before the events of the game, a cataclysm destroyed Khaenri'ah, a powerful underground nation that had no Archon and no divine protection. Unlike the seven nations of Teyvat, Khaenri'ah developed independently of the gods, achieving remarkable alchemical and technological advancement.
+
+The cataclysm was caused — or at least enabled — by a being named Gold (Rhinedottir), an alchemist who created both the Abyss Order (through corrupting Khaenri'ah's king, Irmin, into the Eclipse King) and various synthetic life forms including Albedo.
+
+After the cataclysm, Celestia cursed the survivors of Khaenri'ah: nobility were turned into monsters (the ruin golems' creators, the Khaenri'ah bloodline), and commoners were turned into the Hilichurls — the common enemies of the game, who are not mindless monsters but cursed humans endlessly wandering, unable to die and unable to remember who they were.
+
+The Abyss Order, encountered throughout the game as antagonists, is the remnant of Khaenri'ah's people and ideology fighting against the current world order. The Traveler's sibling leads the Abyss Order, which is the central unresolved mystery of the main story.
+
+---
+
+### Celestia and the True Nature of Teyvat
+Celestia is presented with increasing unease as the story progresses. Several pieces of lore suggest it is not a benevolent divine realm:
+
+The Archons were empowered by Celestia and answer to it. However, the nature of the divine authority is coercive — Visions are distributed by Celestia's will, and the Gnoses are Celestia's means of controlling the Archons.
+
+The world of Teyvat itself may be a fabricated reality. Several characters and lore items suggest the sky is a painted ceiling, that the world was created or shaped by beings called the Primordial One and the Second Who Came, and that the gods the Archons answer to may themselves be secondary to even higher divine forces.
+
+The Sustainer of Heavenly Principles, the being who defeated the Traveler at the start of the game and separated them from their sibling, appears to be enforcing a status quo — keeping the world in its current form and preventing change that might reveal or challenge what Teyvat actually is.
+
+The recurring theme of the main story is that the history of Teyvat has been erased, modified, or controlled. The Irminsul can be edited. Characters who die can be written out of history. The gods of Teyvat may themselves be pawns of something older.
+
+---
+
+### The Abyss and the Traveler's Sibling
+The Traveler arrives on Teyvat searching for their sibling, who left to investigate the world and ended up leading the Abyss Order. The sibling's stated goal is to destroy the current divine order that destroyed Khaenri'ah and cursed its people. Their methods involve working with Abyssal corruption, which puts them at odds with the Traveler even if their goals are understandable.
+
+The Abyss itself is a realm beneath Teyvat — a zone of corruption and monsters. Its connection to Khaenri'ah's transformation after the cataclysm, the origin of the monsters that the Yakshas spent centuries fighting, and the deeper nature of Abyssal corruption are all threads that have been slowly unraveled through the story quests and exploration content.
+
+---
+
+### The Visions — Divine Gifts or Divine Control?
+Visions are elemental gems that grant humans elemental power. They are awarded by the gods (Celestia) based on strong human ambition and determined will. However, several characters question whether this is a gift or a tether. Raiden Shogun's Vision Hunt Decree was based partly on the idea that human ambition — and the Visions that amplify it — lead to change and death.
+
+The Gnoses, by contrast, are the Archons' divine power sources — physical objects that represent their authority from Celestia. The Tsaritsa is collecting them, which would theoretically strip the Archons of their formal status in Celestia's hierarchy — which may be exactly what she wants.
+
+---
+
+## Historical Events
+
+### The Archon War (~2000 years ago)
+Before the seven nations took their current form, Teyvat was ruled by countless gods competing for territory and worshippers. The Archon War was the period of conflict during which the current Seven came to power by defeating rival gods. Morax and Barbatos both participated. The nation of Mondstadt emerged from the liberation of Decarabian's storm-city. Liyue's current borders were established by Morax's victory over rival gods and monsters.
+
+### The Cataclysm (~500 years ago)
+The single most significant event in recent Teyvat history. Khaenri'ah was destroyed. The Abyss Order was created. Multiple Archons were weakened or changed. The Dendro Archon died. Dainsleif (the Bough Keeper, a Khaenri'ah noble) lost his nation and was cursed with immortality to watch it all. The Traveler's sibling was transformed by what they witnessed into an agent of opposition against Celestia.
+
+### The Era of the Yakshas
+Following the cataclysm, Liyue was flooded with demonic creatures whose karma could corrupt anyone who fought them. The five Yakshas (including Xiao) spent centuries purging these beings. The psychological and spiritual cost was enormous — four of the five eventually fell to madness, corruption, or death. Xiao survived, barely, and carries the accumulated karma of centuries of demon-slaying.
+
+---

embedder.py

@@ -0,0 +1,20 @@
+from sentence_transformers import SentenceTransformer
+import os
+
+EMBED_MODEL = os.getenv("EMBED_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
+
+_model = None
+
+
+def get_embedder() -> SentenceTransformer:
+    global _model
+    if _model is None:
+        _model = SentenceTransformer(EMBED_MODEL)
+    return _model
+
+
+def embed_texts(texts: list[str]) -> list[list[float]]:
+    """Return a list of embedding vectors for the given texts."""
+    model = get_embedder()
+    embeddings = model.encode(texts, show_progress_bar=True, batch_size=32)
+    return embeddings.tolist()

index.html

@@ -0,0 +1,672 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>LLMOps — Llama 3.1 RAG</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500&family=Syne:wght@400;600;700&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg: #0a0a0b;
+    --surface: #111113;
+    --surface2: #18181c;
+    --border: #2a2a30;
+    --border2: #3a3a42;
+    --accent: #7c6af7;
+    --accent2: #a89cf7;
+    --green: #3dd68c;
+    --red: #f76a6a;
+    --amber: #f7c26a;
+    --text: #e8e8f0;
+    --text2: #8888a0;
+    --text3: #555568;
+    --mono: 'JetBrains Mono', monospace;
+    --sans: 'Syne', sans-serif;
+  }
+
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: var(--sans);
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* subtle grid background */
+  body::before {
+    content: '';
+    position: fixed;
+    inset: 0;
+    background-image:
+      linear-gradient(rgba(124,106,247,0.03) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(124,106,247,0.03) 1px, transparent 1px);
+    background-size: 40px 40px;
+    pointer-events: none;
+    z-index: 0;
+  }
+
+  header {
+    position: relative;
+    z-index: 1;
+    padding: 28px 40px 24px;
+    border-bottom: 1px solid var(--border);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  .logo {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+  }
+
+  .logo-mark {
+    width: 36px;
+    height: 36px;
+    border-radius: 8px;
+    background: var(--accent);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-family: var(--mono);
+    font-size: 14px;
+    font-weight: 500;
+    color: #fff;
+    letter-spacing: -0.5px;
+  }
+
+  .logo-text {
+    font-size: 16px;
+    font-weight: 700;
+    color: var(--text);
+    letter-spacing: -0.3px;
+  }
+
+  .logo-sub {
+    font-size: 11px;
+    color: var(--text3);
+    font-family: var(--mono);
+    margin-top: 1px;
+  }
+
+  .status-pill {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+    padding: 6px 12px;
+    border-radius: 20px;
+    border: 1px solid var(--border);
+    background: var(--surface);
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text2);
+  }
+
+  .status-dot {
+    width: 7px;
+    height: 7px;
+    border-radius: 50%;
+    background: var(--text3);
+    transition: background 0.3s;
+  }
+  .status-dot.online { background: var(--green); box-shadow: 0 0 6px var(--green); }
+  .status-dot.error { background: var(--red); }
+  .status-dot.loading { background: var(--amber); animation: pulse 1s ease-in-out infinite; }
+
+  @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
+
+  main {
+    position: relative;
+    z-index: 1;
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    max-width: 860px;
+    width: 100%;
+    margin: 0 auto;
+    padding: 40px 40px 0;
+  }
+
+  .hero {
+    margin-bottom: 40px;
+    animation: fadeUp 0.5s ease both;
+  }
+
+  @keyframes fadeUp {
+    from { opacity:0; transform: translateY(12px); }
+    to   { opacity:1; transform: translateY(0); }
+  }
+
+  .hero h1 {
+    font-size: 32px;
+    font-weight: 700;
+    color: var(--text);
+    letter-spacing: -0.8px;
+    line-height: 1.2;
+    margin-bottom: 10px;
+  }
+
+  .hero h1 span { color: var(--accent2); }
+
+  .hero p {
+    font-size: 14px;
+    color: var(--text2);
+    font-family: var(--mono);
+    line-height: 1.6;
+  }
+
+  .model-tag {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    margin-top: 12px;
+    padding: 4px 10px;
+    border-radius: 4px;
+    border: 1px solid var(--border2);
+    background: var(--surface2);
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--accent2);
+  }
+
+  /* Query input area */
+  .query-box {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 0;
+    overflow: hidden;
+    transition: border-color 0.2s;
+    animation: fadeUp 0.5s 0.1s ease both;
+  }
+
+  .query-box:focus-within {
+    border-color: var(--accent);
+  }
+
+  .query-label {
+    padding: 12px 16px 0;
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text3);
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+  }
+
+  textarea {
+    width: 100%;
+    background: transparent;
+    border: none;
+    outline: none;
+    resize: none;
+    padding: 10px 16px 14px;
+    font-family: var(--mono);
+    font-size: 14px;
+    color: var(--text);
+    line-height: 1.6;
+    min-height: 90px;
+    caret-color: var(--accent);
+  }
+
+  textarea::placeholder { color: var(--text3); }
+
+  .query-footer {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 10px 14px;
+    border-top: 1px solid var(--border);
+    background: var(--surface2);
+  }
+
+  .top-k-wrap {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--text2);
+  }
+
+  .top-k-wrap select {
+    background: var(--surface);
+    border: 1px solid var(--border2);
+    border-radius: 4px;
+    color: var(--text);
+    font-family: var(--mono);
+    font-size: 12px;
+    padding: 3px 8px;
+    cursor: pointer;
+    outline: none;
+  }
+
+  .send-btn {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 18px;
+    background: var(--accent);
+    border: none;
+    border-radius: 6px;
+    color: #fff;
+    font-family: var(--sans);
+    font-size: 13px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: background 0.15s, transform 0.1s;
+    letter-spacing: 0.2px;
+  }
+
+  .send-btn:hover { background: var(--accent2); }
+  .send-btn:active { transform: scale(0.97); }
+  .send-btn:disabled { background: var(--border2); color: var(--text3); cursor: not-allowed; transform: none; }
+
+  .send-btn .arrow { font-size: 14px; transition: transform 0.15s; }
+  .send-btn:not(:disabled):hover .arrow { transform: translateX(3px); }
+
+  /* Response area */
+  #response-area {
+    margin-top: 28px;
+    animation: fadeUp 0.4s ease both;
+    display: none;
+  }
+
+  #response-area.visible { display: block; }
+
+  .response-card {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    overflow: hidden;
+  }
+
+  .response-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    border-bottom: 1px solid var(--border);
+    background: var(--surface2);
+  }
+
+  .response-label {
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text3);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    display: flex;
+    align-items: center;
+    gap: 7px;
+  }
+
+  .response-label .dot {
+    width: 6px; height: 6px; border-radius: 50%;
+    background: var(--green);
+  }
+
+  .latency-tag {
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text3);
+    padding: 2px 8px;
+    border-radius: 3px;
+    border: 1px solid var(--border);
+  }
+
+  .response-body {
+    padding: 20px;
+    font-size: 15px;
+    line-height: 1.75;
+    color: var(--text);
+    min-height: 60px;
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+
+  /* loading state */
+  .thinking {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 20px;
+    font-family: var(--mono);
+    font-size: 13px;
+    color: var(--text2);
+  }
+
+  .thinking-dots span {
+    display: inline-block;
+    width: 5px; height: 5px;
+    border-radius: 50%;
+    background: var(--accent);
+    margin: 0 2px;
+    animation: bounce 1.2s ease-in-out infinite;
+  }
+  .thinking-dots span:nth-child(2) { animation-delay: 0.2s; }
+  .thinking-dots span:nth-child(3) { animation-delay: 0.4s; }
+  @keyframes bounce { 0%,80%,100%{transform:translateY(0)} 40%{transform:translateY(-6px)} }
+
+  .sources-section {
+    border-top: 1px solid var(--border);
+    padding: 12px 20px;
+    background: var(--surface2);
+  }
+
+  .sources-label {
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text3);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    margin-bottom: 8px;
+  }
+
+  .source-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    padding: 3px 9px;
+    border-radius: 4px;
+    border: 1px solid var(--border2);
+    background: var(--surface);
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--accent2);
+    margin: 3px 4px 3px 0;
+  }
+
+  .no-sources {
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--text3);
+    font-style: italic;
+  }
+
+  .error-card {
+    background: rgba(247,106,106,0.06);
+    border: 1px solid rgba(247,106,106,0.25);
+    border-radius: 8px;
+    padding: 14px 16px;
+    font-family: var(--mono);
+    font-size: 13px;
+    color: var(--red);
+    margin-top: 16px;
+    display: none;
+  }
+  .error-card.visible { display: block; }
+
+  /* history */
+  .history-section {
+    margin-top: 32px;
+    padding-bottom: 40px;
+    animation: fadeUp 0.4s 0.15s ease both;
+  }
+
+  .history-label {
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text3);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    margin-bottom: 12px;
+  }
+
+  .history-item {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 12px 16px;
+    margin-bottom: 8px;
+    cursor: pointer;
+    transition: border-color 0.15s;
+  }
+
+  .history-item:hover { border-color: var(--border2); }
+
+  .history-q {
+    font-size: 13px;
+    color: var(--text2);
+    font-family: var(--mono);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .history-meta {
+    font-size: 11px;
+    color: var(--text3);
+    font-family: var(--mono);
+    margin-top: 4px;
+  }
+
+  footer {
+    position: relative;
+    z-index: 1;
+    text-align: center;
+    padding: 20px;
+    font-family: var(--mono);
+    font-size: 11px;
+    color: var(--text3);
+    border-top: 1px solid var(--border);
+    margin-top: auto;
+  }
+</style>
+</head>
+<body>
+
+<header>
+  <div class="logo">
+    <div class="logo-mark">λ</div>
+    <div>
+      <div class="logo-text">LLMOps RAG</div>
+      <div class="logo-sub">Llama 3.1 · QLoRA · Pinecone</div>
+    </div>
+  </div>
+  <div class="status-pill">
+    <div class="status-dot" id="status-dot"></div>
+    <span id="status-text">checking...</span>
+  </div>
+</header>
+
+<main>
+  <div class="hero">
+    <h1>Ask your <span>fine-tuned</span> model</h1>
+    <p>Llama 3.1 8B · QLoRA exp2_lr2e-4_r16 · RTX 3060 · 4-bit NF4</p>
+    <div class="model-tag">
+      <span>●</span> Retrieval-augmented · semantic search over ingested docs
+    </div>
+  </div>
+
+  <div class="query-box">
+    <div class="query-label">query</div>
+    <textarea
+      id="query-input"
+      placeholder="What is QLoRA and how does it differ from full fine-tuning?"
+      rows="3"
+    ></textarea>
+    <div class="query-footer">
+      <div class="top-k-wrap">
+        <span>top_k</span>
+        <select id="top-k">
+          <option value="1">1</option>
+          <option value="2">2</option>
+          <option value="3" selected>3</option>
+          <option value="5">5</option>
+        </select>
+        <span style="color:var(--text3)">retrieved chunks</span>
+      </div>
+      <button class="send-btn" id="send-btn" onclick="submitQuery()">
+        Run query <span class="arrow">→</span>
+      </button>
+    </div>
+  </div>
+
+  <div class="error-card" id="error-card"></div>
+
+  <div id="response-area">
+    <div class="response-card">
+      <div class="response-header">
+        <div class="response-label">
+          <div class="dot"></div>
+          response
+        </div>
+        <div class="latency-tag" id="latency-tag">—</div>
+      </div>
+      <div id="response-body" class="response-body"></div>
+      <div class="sources-section">
+        <div class="sources-label">sources</div>
+        <div id="sources-list"><span class="no-sources">no documents ingested yet</span></div>
+      </div>
+    </div>
+  </div>
+
+  <div class="history-section" id="history-section" style="display:none">
+    <div class="history-label">recent queries</div>
+    <div id="history-list"></div>
+  </div>
+</main>
+
+<footer>
+  running locally · http://localhost:8000 · <span id="footer-model">exp2_lr2e-4_r16</span>
+</footer>
+
+<script>
+const API = 'http://localhost:8000';
+const history = [];
+
+async function checkHealth() {
+  const dot = document.getElementById('status-dot');
+  const txt = document.getElementById('status-text');
+  dot.className = 'status-dot loading';
+  txt.textContent = 'connecting...';
+  try {
+    const r = await fetch(`${API}/health`);
+    const d = await r.json();
+    if (d.model_loaded) {
+      dot.className = 'status-dot online';
+      txt.textContent = 'model ready';
+    } else {
+      dot.className = 'status-dot loading';
+      txt.textContent = 'loading model...';
+      setTimeout(checkHealth, 3000);
+    }
+  } catch {
+    dot.className = 'status-dot error';
+    txt.textContent = 'server offline';
+    setTimeout(checkHealth, 5000);
+  }
+}
+
+async function submitQuery() {
+  const query = document.getElementById('query-input').value.trim();
+  if (!query) return;
+
+  const top_k = parseInt(document.getElementById('top-k').value);
+  const btn = document.getElementById('send-btn');
+  const responseArea = document.getElementById('response-area');
+  const responseBody = document.getElementById('response-body');
+  const errorCard = document.getElementById('error-card');
+  const latencyTag = document.getElementById('latency-tag');
+  const sourcesList = document.getElementById('sources-list');
+
+  // reset
+  errorCard.className = 'error-card';
+  responseArea.className = 'response-area visible';
+  responseArea.style.display = 'block';
+  latencyTag.textContent = '—';
+  sourcesList.innerHTML = '';
+  btn.disabled = true;
+
+  // show thinking
+  responseBody.innerHTML = `
+    <div class="thinking">
+      <div class="thinking-dots">
+        <span></span><span></span><span></span>
+      </div>
+      generating response...
+    </div>`;
+
+  try {
+    const res = await fetch(`${API}/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query, top_k })
+    });
+
+    if (!res.ok) {
+      const err = await res.json();
+      throw new Error(JSON.stringify(err.detail || err));
+    }
+
+    const data = await res.json();
+
+    // render answer
+    responseBody.textContent = data.answer;
+
+    // latency
+    const ms = Math.round(data.latency_ms);
+    latencyTag.textContent = ms >= 1000 ? `${(ms/1000).toFixed(1)}s` : `${ms}ms`;
+
+    // sources
+    if (data.sources && data.sources.length > 0) {
+      sourcesList.innerHTML = data.sources.map(s => {
+        const name = s.split(/[\\/]/).pop();
+        return `<span class="source-chip">📄 ${name}</span>`;
+      }).join('');
+    } else {
+      sourcesList.innerHTML = '<span class="no-sources">no docs ingested — run ingest.py to add documents</span>';
+    }
+
+    // add to history
+    addHistory(query, ms);
+
+  } catch (err) {
+    responseBody.innerHTML = '';
+    responseArea.style.display = 'none';
+    errorCard.className = 'error-card visible';
+    errorCard.textContent = `Error: ${err.message}`;
+  }
+
+  btn.disabled = false;
+}
+
+function addHistory(query, latency_ms) {
+  history.unshift({ query, latency_ms, time: new Date().toLocaleTimeString() });
+  if (history.length > 5) history.pop();
+
+  const section = document.getElementById('history-section');
+  const list = document.getElementById('history-list');
+
+  section.style.display = 'block';
+  list.innerHTML = history.map((h, i) => `
+    <div class="history-item" onclick="rerun(${i})">
+      <div class="history-q">${h.query}</div>
+      <div class="history-meta">${h.time} · ${Math.round(h.latency_ms/1000).toFixed(1)}s</div>
+    </div>
+  `).join('');
+}
+
+function rerun(i) {
+  document.getElementById('query-input').value = history[i].query;
+  submitQuery();
+}
+
+// Ctrl+Enter to submit
+document.getElementById('query-input').addEventListener('keydown', e => {
+  if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
+    e.preventDefault();
+    submitQuery();
+  }
+});
+
+// check health on load
+checkHealth();
+</script>
+</body>
+</html>

ingest.py

@@ -0,0 +1,110 @@
+"""
+ingest.py — Load documents from a directory, chunk them, embed them, push to Pinecone.
+
+Usage:
+    python ingest.py --dir ./docs
+    python ingest.py --dir ./docs --chunk-size 400 --chunk-overlap 50
+"""
+
+import os
+import uuid
+import argparse
+import logging
+from pathlib import Path
+from dotenv import load_dotenv 
+load_dotenv()                  
+
+from pinecone import Pinecone, ServerlessSpec
+from embedder import embed_texts
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+PINECONE_API_KEY = os.getenv("PINECONE_API_KEY")
+PINECONE_INDEX   = os.getenv("PINECONE_INDEX", "llmops-rag")
+EMBED_DIM        = 384   # all-MiniLM-L6-v2 output dim
+
+
+def chunk_text(text: str, chunk_size: int = 400, overlap: int = 50) -> list[str]:
+    """Naive character-level chunker. Replace with sentence splitter if needed."""
+    words = text.split()
+    chunks, i = [], 0
+    while i < len(words):
+        chunk = " ".join(words[i : i + chunk_size])
+        chunks.append(chunk)
+        i += chunk_size - overlap
+    return chunks
+
+
+def load_documents(directory: str) -> list[dict]:
+    """Load .txt and .md files recursively. Returns list of {source, text}."""
+    docs = []
+    for path in Path(directory).rglob("*"):
+        if path.suffix in {".txt", ".md"}:
+            text = path.read_text(encoding="utf-8", errors="ignore").strip()
+            if text:
+                docs.append({"source": str(path), "text": text})
+    logger.info(f"Loaded {len(docs)} documents from {directory}")
+    return docs
+
+
+def ensure_index(pc: Pinecone):
+    existing = [idx.name for idx in pc.list_indexes()]
+    if PINECONE_INDEX not in existing:
+        logger.info(f"Creating index '{PINECONE_INDEX}'...")
+        pc.create_index(
+            name=PINECONE_INDEX,
+            dimension=EMBED_DIM,
+            metric="cosine",
+            spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+        )
+        logger.info("Index created.")
+    else:
+        logger.info(f"Index '{PINECONE_INDEX}' already exists.")
+
+
+def ingest_documents(directory: str, chunk_size: int = 400, chunk_overlap: int = 50) -> int:
+    if not PINECONE_API_KEY:
+        raise EnvironmentError("PINECONE_API_KEY not set")
+
+    pc = Pinecone(api_key=PINECONE_API_KEY)
+    ensure_index(pc)
+    index = pc.Index(PINECONE_INDEX)
+
+    docs = load_documents(directory)
+    if not docs:
+        logger.warning("No documents found. Nothing ingested.")
+        return 0
+
+    all_chunks, all_meta = [], []
+    for doc in docs:
+        for chunk in chunk_text(doc["text"], chunk_size, chunk_overlap):
+            all_chunks.append(chunk)
+            all_meta.append({"source": doc["source"], "text": chunk})
+
+    logger.info(f"Embedding {len(all_chunks)} chunks...")
+    vectors = embed_texts(all_chunks)
+
+    # Upsert in batches of 100
+    BATCH = 100
+    total = 0
+    for i in range(0, len(all_chunks), BATCH):
+        batch_vectors = [
+            (str(uuid.uuid4()), vectors[j], all_meta[j])
+            for j in range(i, min(i + BATCH, len(all_chunks)))
+        ]
+        index.upsert(vectors=batch_vectors)
+        total += len(batch_vectors)
+        logger.info(f"  Upserted {total}/{len(all_chunks)}")
+
+    logger.info(f"Done. {total} vectors in Pinecone index '{PINECONE_INDEX}'.")
+    return total
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dir", default="./docs", help="Directory containing .txt/.md files")
+    parser.add_argument("--chunk-size", type=int, default=400)
+    parser.add_argument("--chunk-overlap", type=int, default=50)
+    args = parser.parse_args()
+    ingest_documents(args.dir, args.chunk_size, args.chunk_overlap)

main.py

@@ -0,0 +1,83 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from contextlib import asynccontextmanager
+import logging
+import time
+from fastapi.responses import FileResponse
+from rag import RAGChain
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+rag_chain: RAGChain = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global rag_chain
+    logger.info("Loading RAG chain...")
+    rag_chain = RAGChain()
+    rag_chain.load()
+    logger.info("RAG chain ready.")
+    yield
+    logger.info("Shutting down.")
+
+
+app = FastAPI(
+    title="LLMOps RAG API",
+    description="Llama 3.1 8B QLoRA fine-tuned + Pinecone RAG",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+class GenerateRequest(BaseModel):
+    query: str
+    top_k: int = 3
+    max_new_tokens: int = 512
+
+
+class GenerateResponse(BaseModel):
+    answer: str
+    sources: list[str]
+    latency_ms: float
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "model_loaded": rag_chain is not None and rag_chain.ready}
+
+    
+@app.get("/")
+def ui():
+    return FileResponse("index.html")
+
+
+@app.post("/generate", response_model=GenerateResponse)
+def generate(req: GenerateRequest):
+    if not rag_chain or not rag_chain.ready:
+        raise HTTPException(status_code=503, detail="Model not loaded yet")
+    if not req.query.strip():
+        raise HTTPException(status_code=400, detail="Query cannot be empty")
+
+    start = time.time()
+    answer, sources = rag_chain.query(req.query, top_k=req.top_k, max_new_tokens=req.max_new_tokens)
+    latency_ms = (time.time() - start) * 1000
+
+    return GenerateResponse(answer=answer, sources=sources, latency_ms=round(latency_ms, 1))
+
+
+@app.post("/ingest")
+def ingest(directory: str = "./docs"):
+    """Ingest documents from a local directory into Pinecone."""
+    from ingest import ingest_documents
+    count = ingest_documents(directory)
+    return {"ingested": count, "directory": directory}

pyvenv.cfg

@@ -0,0 +1,5 @@
+home = C:\Users\mukul\AppData\Local\Programs\Python\Python312
+include-system-site-packages = false
+version = 3.12.9
+executable = C:\Users\mukul\AppData\Local\Programs\Python\Python312\python.exe
+command = C:\Users\mukul\AppData\Local\Programs\Python\Python312\python.exe -m venv E:\Projects\llmops-serve\venv

rag.py

@@ -0,0 +1,116 @@
+import os
+import logging
+import torch
+from dotenv import load_dotenv
+
+load_dotenv() 
+
+from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline, BitsAndBytesConfig
+from langchain_community.vectorstores import Pinecone as LangchainPinecone
+from langchain_community.embeddings import HuggingFaceEmbeddings
+from langchain.chains import RetrievalQA
+from langchain_community.llms import HuggingFacePipeline
+from langchain.prompts import PromptTemplate
+from pinecone import Pinecone
+
+logger = logging.getLogger(__name__)
+
+LOCAL_MODEL = os.getenv("MODEL_PATH", "./models/merged/exp2_lr2e-4_r16")
+EMBED_MODEL = os.getenv("EMBED_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
+PINECONE_API_KEY = os.getenv("PINECONE_API_KEY")
+PINECONE_INDEX = os.getenv("PINECONE_INDEX", "llmops-rag")
+
+PROMPT_TEMPLATE = """You are a precise Genshin Impact assistant. Answer ONLY using the context below.
+If specific details like weapon names or artifact sets are not in the context, say so — do not invent them.
+
+Context:
+{context}
+
+Question: {question}
+
+Answer (use only information from the context above):"""
+
+
+class RAGChain:
+    def __init__(self):
+        self.ready = False
+        self.chain = None
+        self.vectorstore = None
+
+    def load(self):
+        logger.info(f"Loading model from {LOCAL_MODEL}")
+
+        # ---- 4-bit quant for 6GB VRAM ----
+        bnb_config = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16,
+            bnb_4bit_use_double_quant=True,
+        )
+
+        tokenizer = AutoTokenizer.from_pretrained(LOCAL_MODEL)
+        model = AutoModelForCausalLM.from_pretrained(
+            LOCAL_MODEL,
+            quantization_config=bnb_config,
+            device_map="auto",
+            torch_dtype=torch.bfloat16,
+            max_memory={0: "5.5GiB", "cpu": "24GiB"},
+        )
+        model.eval()
+
+        tokenizer.pad_token = tokenizer.eos_token
+
+        hf_pipe = pipeline(
+            "text-generation",
+            model=model,
+            tokenizer=tokenizer,
+            max_new_tokens=256,
+            do_sample=False,
+            temperature=None,
+            top_p=None,
+            repetition_penalty=1.3,
+            return_full_text=False,
+            eos_token_id=tokenizer.eos_token_id,
+            pad_token_id=tokenizer.eos_token_id,
+        
+        )
+        llm = HuggingFacePipeline(pipeline=hf_pipe)
+        logger.info("Model loaded.")
+
+        # ---- Embeddings + Pinecone ----
+        logger.info("Connecting to Pinecone...")
+        embeddings = HuggingFaceEmbeddings(model_name=EMBED_MODEL)
+        pc = Pinecone(api_key=PINECONE_API_KEY)
+        index = pc.Index(PINECONE_INDEX)
+        self.vectorstore = LangchainPinecone(index, embeddings, "text")
+        logger.info("Pinecone connected.")
+
+        # ---- RetrievalQA chain ----
+        prompt = PromptTemplate(
+            template=PROMPT_TEMPLATE,
+            input_variables=["context", "question"],
+        )
+        self.chain = RetrievalQA.from_chain_type(
+            llm=llm,
+            chain_type="stuff",
+            retriever=self.vectorstore.as_retriever(search_kwargs={"k": 3}),
+            return_source_documents=True,
+            chain_type_kwargs={"prompt": prompt},
+        )
+        self.ready = True
+        logger.info("RAG chain ready.")
+
+    def query(self, question: str, top_k: int = 3, max_new_tokens: int = 512) -> tuple[str, list[str]]:
+        if not self.ready:
+            raise RuntimeError("Chain not loaded")
+
+        # Override retriever k at query time
+        self.chain.retriever.search_kwargs["k"] = top_k
+
+        result = self.chain.invoke({"query": question})
+        answer = result["result"].strip().replace("</s>", "").strip()
+        sources = [
+            doc.metadata.get("source", "unknown")
+            for doc in result.get("source_documents", [])
+        ]
+        return answer, list(dict.fromkeys(sources))  # deduplicated, order preserved

requirements.txt

@@ -0,0 +1,20 @@
+# Core serving
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+pydantic==2.7.4
+
+# LLM + fine-tuned model
+torch==2.3.1          # CPU or CUDA — Docker will handle CUDA variant
+transformers==4.51.3
+peft==0.15.2
+bitsandbytes==0.43.3  # CPU-compatible for Docker; swap 0.49.2 if CUDA 12.8
+accelerate==1.6.0
+
+# RAG
+langchain==0.3.25
+langchain-community==0.3.23
+pinecone-client==5.0.1
+sentence-transformers==4.1.0
+
+# Utilities
+python-dotenv==1.0.1