📚 OpenRoot Knowledge Assistant

A documentation-based question-and-answer assistant built with Retrieval-Augmented Generation (RAG). It retrieves the most relevant passages from your project documentation using TF-IDF keyword search, then generates a grounded, citation-enforced answer using the Groq API (LLaMA 3.3 70B). Every factual claim in the answer is cited with the source file name in square brackets — no hallucinations, no outside knowledge.

---

✨ Features

• 🔍 TF-IDF retrieval over .md and .csv files in docs/ using bigrams and English stop-word removal
• 🤖 Groq LLM generation with a strict system prompt that forbids outside knowledge and requires inline citations
• 📄 Sources panel — every answer shows the exact passages used, with relevance scores
• 🌐 Multilingual responses — answers in English, Roman Urdu, or Urdu (matching the user's question language), keeping technical terms in English
• 🚫 Grounding guardrails — if the documents don't contain the answer, the app says so rather than guessing
• ⚡ Cached index — the TF-IDF index is built once and cached across Streamlit reruns

---

🏗️ Architecture

User Question
      │
      ▼
TF-IDF Retrieval
(docs/ — .md and .csv files)
      │
      ▼
Top-K Relevant Passages
(scored by cosine similarity)
      │
      ▼
Groq LLM
(grounded prompt — citations required,
 no outside knowledge allowed)
      │
      ▼
Answer with [citations] + Sources Panel

1. Chunking: Each Markdown file is split into paragraphs, and short paragraphs are dropped.
2. Indexing: A TF-IDF index is built once and cached with st.cache_resource.
3. Retrieval: The question is compared with all chunks using cosine similarity, and the top matches are kept.
4. Generation: The passages are sent to a Groq model with a system prompt that restricts the answer to the provided context.

---

📁 Project Structure

openroot-knowledge-assistant/
├── docs/                        # Knowledge base (Markdown & CSV files)
│   ├── README.md
│   ├── GOALS.md
│   ├── WHY_IT_MATTERS.md
│   ├── MASTER_TODO.md
│   └── coder_briefing_v1.md
├── src/
│   └── app.py                   # Streamlit application
├── .env                         # GROQ_API_KEY — never commit this file
├── .env.example                 # Template for .env (safe to commit)
├── .gitignore
├── requirements.txt
├── LICENSE
└── README.md

---

🚀 Installation

Prerequisites

• Python 3.9+
• A free Groq API key

Windows

git clone https://github.com/<your-username>/openroot-knowledge-assistant.git
cd openroot-knowledge-assistant
python -m venv venv
venv\Scripts\activate
python -m pip install -r requirements.txt

macOS / Linux

git clone https://github.com/<your-username>/openroot-knowledge-assistant.git
cd openroot-knowledge-assistant
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

⚙️ Configuration

1. Get a free API key from https://console.groq.com/
2. Copy the example file and add your key:

cp .env.example .env

3. Open .env and replace the placeholder:

GROQ_API_KEY=gsk_your_actual_key_here

⚠️ Important: Never commit your .env file. It is already listed in .gitignore.

---

🖥️ Usage

Run from the project root directory (not from inside src/):

streamlit run src/app.py

The app opens automatically at http://localhost:8501.

---

💬 Example Questions

Try these in the app:

Question	Expected Behaviour
What is the purpose of the pod loader tool?	Cites README.md, explains dual-hash, FTS5, embeddings
What are the core objectives of OpenRoot?	Cites GOALS.md, lists the 5 objectives
Why does OpenRoot focus on physical work?	Cites WHY_IT_MATTERS.md, explains thermal ledgers
What tools does the coder have available?	Cites coder_briefing_v1.md, lists gh CLI, Ollama, etc.
What is the solar panel output in watts?	Returns "not found" — this data is not in the docs

---

🛠️ Tech Stack

Component	Purpose
Python	Core logic
Streamlit	Chat interface
scikit-learn	TF-IDF retrieval
Groq API (LLaMA 3.3 70B)	Answer generation
python-dotenv	Environment variable management

---

⚠️ Limitations

• Keyword-based retrieval — TF-IDF matches exact terms; synonyms or paraphrased questions may not retrieve the best passages.
• Paragraph chunking — documents are split on blank lines, so a paragraph that spans sections may miss context from neighbouring paragraphs.
• Answer quality depends on the documents — the knowledge base is a small, static snapshot. Answers are only as good as what the docs contain.
• LLM can make mistakes — even with a strict grounding prompt, the model may occasionally misread a passage. Always verify important claims against the source files.
• Small static knowledge base — only 6 documents are indexed. The system is not aware of any changes made to the OpenRoot repo after the fetch date.

---

🔮 Future Improvements

• Heading-based chunking — split on Markdown headings instead of blank lines to keep sections coherent.
• Semantic embeddings — replace or augment TF-IDF with dense vector search (e.g. sentence-transformers) for better semantic recall.
• Evaluation set — build a small set of question/expected-answer pairs to measure retrieval recall and answer faithfulness.
• More documents — add more files from the OpenRoot repository to widen coverage.
• Streaming answers — use Groq's streaming API to show the answer token by token.

---

🤝 Contributing

Pull requests and issues are welcome. For major changes, please open an issue first.

---

📄 License

This project is licensed under the MIT License.