Apppublic

Faniyi/Apextech-knowledge-base

sourceHugging Faceupdated 5mo agoView on Hugging Face

0likes

App README

🏢 ApexTech Solutions — Company Knowledge Base

An 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.

🏗️ Architecture

Query
  │
  ▼
Query Rewriter (gpt-4o-mini)        ← Rewrites vague/conversational queries
  │
  ▼
Hybrid Search                        ← Dense (Chroma) + Sparse (BM25) fused via RRF
  │
  ▼
Cross-Encoder Reranker               ← ms-marco-MiniLM-L-6-v2 reranks top-k chunks
  │
  ▼
LLM (gpt-4.1-mini) + System Prompt  ← Grounded answer from retrieved context
  │
  ▼
Answer + Sources

📁 Project Structure

company-knowledge-base/
├── UI/
│   └── ui.py                   # Chainlit UI (User mode)
├── rag/
│   ├── answer.py               # Full RAG pipeline
│   ├── hybrid_search.py        # Dense + BM25 + RRF + cross-encoder reranker
│   ├── query_rewriter.py       # LLM query rewriter
│   ├── ingest.py               # Document ingestion
│   ├── chunking.py             # Text splitting
│   ├── embedding.py            # HuggingFace embeddings
│   └── vectorstore.py          # Chroma vector store
├── llm/
│   ├── llm.py                  # LLM initialisation
│   └── prompt.py               # System prompt template
├── evals/
│   ├── datasets/
│   │   ├── qa_dataset.json     # 60 QA pairs (easy + hard)
│   │   └── edge_cases.json     # 20 adversarial / edge cases
│   ├── metrics/
│   │   ├── retrieval_metrics.py    # recall@k, precision@k, MRR
│   │   ├── generation_metrics.py   # faithfulness, relevance, correctness
│   │   ├── context_metrics.py      # context coverage, context relevance
│   │   └── e2e_metrics.py          # task success, unanswerable awareness, CI gates
│   ├── runners/
│   │   └── run_evals.py        # local + ci modes with LangSmith integration
│   └── results/                # Timestamped JSON eval reports
├── data/
│   ├── raw/                    # Source .md documents (canonical)
│   └── vector_db/              # Chroma persistent store
├── main.py                     # Entry point — ingest check + UI launch
└── chainlit.md                 # Chainlit welcome screen

🚀 Getting Started

1. Clone the repository

bash

git clone https://github.com/faniyi-akinbobola/company-knowledge-base.git
cd company-knowledge-base

2. Install dependencies

bash

uv sync

3. Set up environment variables

bash

cp .env.example .env

Edit .env:

env

OPENAI_API_KEY=sk-...
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_PROJECT=company-knowledge-base

4. Run the app

bash

uv run python main.py

This will:

—✅ Check if the vector store exists
—✅ Auto-ingest documents if not found
—✅ Launch the Chainlit UI at http://localhost:8000

🧪 Evals

bash

# Fast local run — no LLM judge
uv run python evals/runners/run_evals.py --mode local

# With LLM-as-judge (faithfulness, correctness, relevance, hallucination)
uv run python evals/runners/run_evals.py --mode local --llm-judge

# CI mode — requires LANGCHAIN_API_KEY, exits with code 1 on threshold breach
uv run python evals/runners/run_evals.py --mode ci

Latest eval results

Metric	Score	CI Threshold
recall@k	87.5%	—
precision@k	98.0%	—
MRR	0.77	—
answerfoundrate	85.0%	—
faithfulness	0.81	—
answer_relevance	0.85	—
correctness	0.62	—
tasksuccessrate	80.4%	≥ 80% ✅
unanswerable_awareness	100%	≥ 70% ✅
notfoundfalsepositiverate	8.9%	≤ 10% ✅
llmjudgescore	0.83	≥ 0.70 ✅

🔭 LangSmith Tracing

All 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.

🚀 Deploying to HuggingFace Spaces

Step 1 — Create a new Space

1.Go to huggingface.co/new-space
2.Fill in:
3.Owner: your HuggingFace username or org
4.Space name: e.g. apextech-knowledge-base
5.License: choose one (e.g. MIT)
6.SDK: select Docker
7.Visibility: Private (this is an internal tool)
8.Hardware: CPU Basic — free tier (app peaks at ~470MB RAM ✅)
9.Click Create Space

Step 2 — Add your OpenAI API key as a Secret

⚠️ Do this before pushing code — the build needs it to run the LLM.

1.In your Space, go to Settings (top right)
2.Scroll to Repository secrets
3.Click New secret and add:

Name	Value
`OPENAI_API_KEY`	`sk-...` your OpenAI key
`LANGCHAIN_API_KEY`	`lsv2_...` (optional — enables LangSmith tracing)
`LANGCHAIN_TRACING_V2`	`true` (optional)
`LANGCHAIN_PROJECT`	`company-knowledge-base` (optional)

Step 3 — Push your code to the Space

Run these commands from your project root:

bash

# One-time setup: add the Space as a git remote
# Replace YOUR_USERNAME and SPACE_NAME with your actual values
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME

# Push your master branch to the Space
git push space master

If you get an authentication error, use a HuggingFace token: git remote set-url space https://YOUR_HF_TOKEN@huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME Generate a token at huggingface.co/settings/tokens with write access.

Step 4 — Monitor the build

1.Go to your Space page on HuggingFace
2.Click the Build logs tab
3.The build will:
4.Install all Python dependencies (~3–5 min)
5.Download the HuggingFace embedding + reranker models (~2 min)
6.Run rag/ingest.py to build the vector database (~1 min)
7.Start the Chainlit server on port 7860
8.When the build is complete the Space shows Running (green)
9.Click the app URL to open the assistant

Total first-build time: ~10–15 minutes. Subsequent pushes are faster due to Docker layer caching.

Step 5 — Updating the app

Every time you push to the space remote, HuggingFace rebuilds and redeploys automatically:

bash

# Make your changes, commit, then:
git push space master

What the Dockerfile does at build time

Step	What happens	Secrets needed?
`uv sync`	Installs all Python dependencies	No
Download models	Pulls `all-MiniLM-L6-v2` + `ms-marco-MiniLM-L-6-v2` from HuggingFace	No
`rag/ingest.py`	Builds ChromaDB vector store from raw `.md` + `.csv` docs	No
Runtime start	Launches Chainlit on port 7860	`OPENAI_API_KEY` ✅

Models and vector DB are baked into the image — zero cold-start delay.