Faniyi/Apextech-knowledge-base

1---2title: ApexTech Knowledge Base3emoji: 🏢4colorFrom: blue5colorTo: indigo6sdk: docker7app_port: 78608pinned: false9---10 11# 🏢 ApexTech Solutions — Company Knowledge Base12 13An internal AI-powered assistant that allows ApexTech employees to query company documentation using natural language. Built with **RAG (Retrieval-Augmented Generation)**, it retrieves relevant information from internal documents and generates accurate, sourced answers.14 15---16 17## 🏗️ Architecture18 19```20Query21  │22  ▼23Query Rewriter (gpt-4o-mini)        ← Rewrites vague/conversational queries24  │25  ▼26Hybrid Search                        ← Dense (Chroma) + Sparse (BM25) fused via RRF27  │28  ▼29Cross-Encoder Reranker               ← ms-marco-MiniLM-L-6-v2 reranks top-k chunks30  │31  ▼32LLM (gpt-4.1-mini) + System Prompt  ← Grounded answer from retrieved context33  │34  ▼35Answer + Sources36```37 38---39 40## 📁 Project Structure41 42```43company-knowledge-base/44├── UI/45│   └── ui.py                   # Chainlit UI (User mode)46├── rag/47│   ├── answer.py               # Full RAG pipeline48│   ├── hybrid_search.py        # Dense + BM25 + RRF + cross-encoder reranker49│   ├── query_rewriter.py       # LLM query rewriter50│   ├── ingest.py               # Document ingestion51│   ├── chunking.py             # Text splitting52│   ├── embedding.py            # HuggingFace embeddings53│   └── vectorstore.py          # Chroma vector store54├── llm/55│   ├── llm.py                  # LLM initialisation56│   └── prompt.py               # System prompt template57├── evals/58│   ├── datasets/59│   │   ├── qa_dataset.json     # 60 QA pairs (easy + hard)60│   │   └── edge_cases.json     # 20 adversarial / edge cases61│   ├── metrics/62│   │   ├── retrieval_metrics.py    # recall@k, precision@k, MRR63│   │   ├── generation_metrics.py   # faithfulness, relevance, correctness64│   │   ├── context_metrics.py      # context coverage, context relevance65│   │   └── e2e_metrics.py          # task success, unanswerable awareness, CI gates66│   ├── runners/67│   │   └── run_evals.py        # local + ci modes with LangSmith integration68│   └── results/                # Timestamped JSON eval reports69├── data/70│   ├── raw/                    # Source .md documents (canonical)71│   └── vector_db/              # Chroma persistent store72├── main.py                     # Entry point — ingest check + UI launch73└── chainlit.md                 # Chainlit welcome screen74```75 76---77 78## 🚀 Getting Started79 80### 1. Clone the repository81 82```bash83git clone https://github.com/faniyi-akinbobola/company-knowledge-base.git84cd company-knowledge-base85```86 87### 2. Install dependencies88 89```bash90uv sync91```92 93### 3. Set up environment variables94 95```bash96cp .env.example .env97```98 99Edit `.env`:100 101```env102OPENAI_API_KEY=sk-...103LANGCHAIN_TRACING_V2=true104LANGCHAIN_API_KEY=lsv2_...105LANGCHAIN_PROJECT=company-knowledge-base106```107 108### 4. Run the app109 110```bash111uv run python main.py112```113 114This will:115 116- ✅ Check if the vector store exists117- ✅ Auto-ingest documents if not found118- ✅ Launch the Chainlit UI at `http://localhost:8000`119 120---121 122## 🧪 Evals123 124```bash125# Fast local run — no LLM judge126uv run python evals/runners/run_evals.py --mode local127 128# With LLM-as-judge (faithfulness, correctness, relevance, hallucination)129uv run python evals/runners/run_evals.py --mode local --llm-judge130 131# CI mode — requires LANGCHAIN_API_KEY, exits with code 1 on threshold breach132uv run python evals/runners/run_evals.py --mode ci133```134 135### Latest eval results136 137| Metric                        | Score | CI Threshold |138| ----------------------------- | ----- | ------------ |139| recall@k                      | 87.5% | —            |140| precision@k                   | 98.0% | —            |141| MRR                           | 0.77  | —            |142| answer_found_rate             | 85.0% | —            |143| faithfulness                  | 0.81  | —            |144| answer_relevance              | 0.85  | —            |145| correctness                   | 0.62  | —            |146| task_success_rate             | 80.4% | ≥ 80% ✅     |147| unanswerable_awareness        | 100%  | ≥ 70% ✅     |148| not_found_false_positive_rate | 8.9%  | ≤ 10% ✅     |149| llm_judge_score               | 0.83  | ≥ 0.70 ✅    |150 151---152 153## 🔭 LangSmith Tracing154 155All LLM calls (UI + evals) are automatically traced to LangSmith when `LANGCHAIN_TRACING_V2=true` is set. No extra code required. View traces at [smith.langchain.com](https://smith.langchain.com).156 157---158 159## 🚀 Deploying to HuggingFace Spaces160 161### Step 1 — Create a new Space162 1631. Go to [huggingface.co/new-space](https://huggingface.co/new-space)1642. Fill in:165   - **Owner**: your HuggingFace username or org166   - **Space name**: e.g. `apextech-knowledge-base`167   - **License**: choose one (e.g. MIT)168   - **SDK**: select **Docker**169   - **Visibility**: **Private** (this is an internal tool)170   - **Hardware**: CPU Basic — free tier (app peaks at ~470MB RAM ✅)1713. Click **Create Space**172 173---174 175### Step 2 — Add your OpenAI API key as a Secret176 177> ⚠️ Do this **before** pushing code — the build needs it to run the LLM.178 1791. In your Space, go to **Settings** (top right)1802. Scroll to **Repository secrets**1813. Click **New secret** and add:182 183| Name                   | Value                                               |184| ---------------------- | --------------------------------------------------- |185| `OPENAI_API_KEY`       | `sk-...` your OpenAI key                            |186| `LANGCHAIN_API_KEY`    | `lsv2_...` _(optional — enables LangSmith tracing)_ |187| `LANGCHAIN_TRACING_V2` | `true` _(optional)_                                 |188| `LANGCHAIN_PROJECT`    | `company-knowledge-base` _(optional)_               |189 190---191 192### Step 3 — Push your code to the Space193 194Run these commands from your project root:195 196```bash197# One-time setup: add the Space as a git remote198# Replace YOUR_USERNAME and SPACE_NAME with your actual values199git remote add space https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME200 201# Push your master branch to the Space202git push space master203```204 205> If you get an authentication error, use a HuggingFace token:206> `git remote set-url space https://YOUR_HF_TOKEN@huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME`207> Generate a token at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) with **write** access.208 209---210 211### Step 4 — Monitor the build212 2131. Go to your Space page on HuggingFace2142. Click the **Build logs** tab2153. The build will:216   - Install all Python dependencies (~3–5 min)217   - Download the HuggingFace embedding + reranker models (~2 min)218   - Run `rag/ingest.py` to build the vector database (~1 min)219   - Start the Chainlit server on port 78602204. When the build is complete the Space shows **Running** (green)2215. Click the app URL to open the assistant222 223Total first-build time: **~10–15 minutes**. Subsequent pushes are faster due to Docker layer caching.224 225---226 227### Step 5 — Updating the app228 229Every time you push to the `space` remote, HuggingFace rebuilds and redeploys automatically:230 231```bash232# Make your changes, commit, then:233git push space master234```235 236---237 238### What the Dockerfile does at build time239 240| Step            | What happens                                                         | Secrets needed?     |241| --------------- | -------------------------------------------------------------------- | ------------------- |242| `uv sync`       | Installs all Python dependencies                                     | No                  |243| Download models | Pulls `all-MiniLM-L6-v2` + `ms-marco-MiniLM-L-6-v2` from HuggingFace | No                  |244| `rag/ingest.py` | Builds ChromaDB vector store from raw `.md` + `.csv` docs            | No                  |245| Runtime start   | Launches Chainlit on port 7860                                       | `OPENAI_API_KEY` ✅ |246 247Models and vector DB are **baked into the image** — zero cold-start delay.248 249---250