BITS Knowledge Hub

A production-grade, fully local AI-powered knowledge system that combines a Knowledge Graph, vector database, and a single shared LLM to analyse code, answer questions from documents, summarise videos, and generate code from natural language — all running on your Mac without any cloud API keys.

---

✨ Features

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     React 18 + Vite                      │
│  Home · Code · NL→Code · Video · Q&A · KG · Upload · Eval│
└───────────────────────┬─────────────────────────────────┘
                        │ REST (Axios)
┌───────────────────────▼─────────────────────────────────┐
│                  FastAPI  (uvicorn)                       │
│  /api/upload  /api/files  /api/qa  /api/code  /api/video │
└──────┬──────────────┬─────────────────┬─────────────────┘
       │              │                 │
┌──────▼──────┐ ┌─────▼──────┐  ┌──────▼───────┐
│  ModelHub   │ │  ChromaDB  │  │  NetworkX +  │
│  singleton  │ │  (local)   │  │  RDFLib KG   │
│ Phi-3.5-mini│ │bits_docs   │  │  kg.ttl      │
│ MiniLM-L6v2 │ │bits_code   │  │              │
│ Whisper base│ │bits_kg     │  │              │
└─────────────┘ └────────────┘  └──────────────┘

Model Stack

Why Phi-3.5-mini? MIT-licensed 3.8B instruction-tuned model from Microsoft. Outperforms Llama-2-7B on many benchmarks and runs efficiently on Apple Silicon (MPS) in float16. Fallbacks: Qwen2.5-Coder-1.5B → TinyLlama-1.1B.

Why MiniLM-L6-v2? Only 80 MB, loads in under 2 seconds, achieves >75 on BEIR benchmarks — far outperforming TF-IDF for semantic retrieval.

Why ChromaDB? Zero-server, fully embedded, stores vectors on disk in chroma_db/. No Docker or external process needed.

---

📁 Folder Structure

BITS_KB/
├── backend/
│   ├── api/
│   │   └── main.py               # FastAPI routes (all endpoints)
│   ├── config.py                 # Paths, model names, runtime constants
│   ├── services/
│   │   ├── code_service.py       # Code analysis + docs generation
│   │   ├── nl_to_code_service.py # NL → code generation
│   │   ├── qa_service.py         # ChromaDB retrieval + LLM answers
│   │   ├── video_service.py      # Whisper + LLM summarisation
│   │   └── kg_service.py         # KG stats / search / visualise
│   └── utils/
│       ├── model_hub.py          # ← SINGLE shared model singleton
│       ├── kg.py                 # NetworkX + RDFLib + ChromaDB indexing
│       ├── code_utils.py
│       ├── metrics.py
│       └── llm.py                # GeminiClient helper
├── frontend/
│   ├── src/
│   │   ├── pages/                # Home · Code · NLToCode · Video · QA · KG · Upload · Eval
│   │   ├── components/           # Layout · UI primitives
│   │   └── api/client.ts         # All API calls
│   └── vite.config.ts
├── data/
│   ├── code/                     # Uploaded code files
│   ├── video/                    # Uploaded video files
│   └── docs/                     # Uploaded documents (PDF, TXT, MD)
├── chroma_db/                    # ChromaDB persistent storage (auto-created)
├── kg.ttl                        # RDF Turtle export of the Knowledge Graph
├── requirements.txt
└── README.md

---

🚀 Setup & Run

Prerequisites

• Python 3.10+
• Node.js 18+
• (Optional) ffmpeg in PATH for video: brew install ffmpeg

1 — Backend

cd BITS_KB
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn backend.api.main:app --host 0.0.0.0 --port 8000 --reload

The first LLM request downloads Phi-3.5-mini (~7 GB). Subsequent starts are instant (HuggingFace cache).

2 — Frontend

cd frontend
npm install
npm run dev      # dev server at http://localhost:5173

Open http://localhost:5173.

Optional: Gemini fallback

echo "GEMINI_API_KEY=your_key_here" > .env

ModelHub prefers Gemini when a valid key is present.

---

🔌 API Reference

Interactive Swagger docs: http://localhost:8000/docs

---

🧠 How the Knowledge Graph Works

1. In-memory: NetworkX DiGraph with typed nodes (concept, pattern, algorithm, document, code_entity)
2. Persistence: RDFLib serialises to kg.ttl (Turtle format) on POST /api/kg/save_rdf
3. Semantic search: Nodes embedded with MiniLM-L6-v2 stored in ChromaDB bits_kg via POST /api/kg/index_chroma
4. Query fallback: KGManager.semantic_search() tries ChromaDB first; falls back to keyword matching

---

⚙️ Configuration (backend/config.py)

MODELS = {
    "llm":          "microsoft/Phi-3.5-mini-instruct",
    "llm_fallbacks": ["Qwen/Qwen2.5-Coder-1.5B-Instruct", "TinyLlama/TinyLlama-1.1B-Chat-v1.0"],
    "embedding":    "sentence-transformers/all-MiniLM-L6-v2",
    "whisper":      "base",   # tiny | base | small | medium
}
RESOURCES = {
    "max_entities_to_doc":  30,
    "docs_total_time_budget": 45.0,   # seconds
    "chroma_top_k": 6,
}

---

🐛 Troubleshooting

---

📜 Licence

MIT — free for academic and commercial use.