README.md

---
title: KnowFlow AI RAG Document Chatbot
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: "1.45.1"
python_version: "3.11"
app_file: app.py
pinned: false
---

# KnowFlow AI

**KnowFlow AI** is a production-style RAG document chatbot demo built with Streamlit, ChromaDB, local CPU embeddings, Docker, and a cloud LLM API.

The project is designed as a recruiter-facing AI engineering portfolio demo. It shows how a notebook-based RAG prototype can be converted into a modular, Dockerized, production-aware application structure.

---

## What It Does

KnowFlow AI lets users upload or use local documents and ask questions about them.

The system:

1. Loads documents from a knowledge base folder.
2. Extracts text from supported file types.
3. Cleans the text.
4. Splits the text into retrieval-friendly chunks.
5. Converts chunks into local embeddings.
6. Stores embeddings in ChromaDB.
7. Retrieves the most relevant chunks for a user question.
8. Sends retrieved context and the user question to a cloud LLM.
9. Returns a grounded answer with source traceability.

---

## Key Features

- Document-based question answering
- Text extraction from TXT, Markdown, CSV, and PDF
- Local CPU embedding generation
- ChromaDB vector search
- Cloud LLM API integration
- Source chunk transparency
- RAG prompt guardrails
- Dockerized development workflow
- Modular backend architecture
- CLI demo runner
- Unit-test-ready structure
- Logging and output persistence
- Production-style secret handling
- Hugging Face Spaces ready
- Streamlit-ready architecture for the next phase

---

## Tech Stack

- Python
- Streamlit
- ChromaDB
- sentence-transformers
- PyTorch CPU
- Cloud LLM API
- Docker
- Docker Compose
- pytest
- Hugging Face Spaces ready

---

## Production Demonstrations

This project demonstrates:

- Modular RAG architecture
- Secure environment configuration
- Source-attributed answers
- Retrieval debugging
- Prompt guardrails
- Local vector database usage
- Dockerized development
- Deployment-ready folder structure
- Cloud API retry handling
- Logging and observability foundations
- Testable backend components
- Separation of generated artifacts from source code

---

## Project Status

```text
Phase 1: Repository and production skeleton setup completed.
Phase 2: Modular RAG backend pipeline completed.
Phase 3: Streamlit application interface planned.
Phase 4: Hugging Face Spaces deployment planned.
````

---

## Repository Name

Recommended repository name:

```text
knowflow-ai-rag-document-chatbot
```

Why this name is used:

```text
knowflow-ai              -> brand name
rag                      -> explains the AI architecture
document-chatbot         -> explains the use case
```

---

## Folder Structure

```text
knowflow-ai-rag-document-chatbot/
├── app/
│   └── streamlit_app.py
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── document_loader.py
│   ├── text_cleaner.py
│   ├── chunker.py
│   ├── embeddings.py
│   ├── vector_store.py
│   ├── retriever.py
│   ├── llm_client.py
│   ├── rag_pipeline.py
│   └── logging_utils.py
├── scripts/
│   ├── run_phase2_demo.py
│   └── docker_manager.sh
├── tests/
│   ├── test_document_loader.py
│   ├── test_chunker.py
│   └── test_rag_pipeline.py
├── data/
│   ├── raw/
│   │   └── company_policy.txt
│   └── sample/
│       └── company_policy_demo.txt
├── vector_db/
├── outputs/
├── logs/
├── notebooks/
├── docs/
│   ├── architecture.md
│   ├── production_notes.md
│   ├── prompt_design.md
│   └── deployment_plan.md
├── assets/
│   └── screenshots/
├── config/
│   └── sample_questions.json
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
├── .gitignore
├── .dockerignore
└── README.md
```

---

## Important Files

```text
Dockerfile
Builds the Docker image for KnowFlow AI.

docker-compose.yml
Runs the Jupyter development service and future Streamlit service.

requirements.txt
Contains clean project dependencies.

.env.example
Safe environment template without real secrets.

.env
Private local environment file. This must never be committed.

src/
Contains the modular RAG backend code.

scripts/run_phase2_demo.py
Runs the complete modular RAG backend from the terminal.

scripts/docker_manager.sh
Provides simple Docker workflow commands.

tests/
Contains basic tests for backend modules.

data/raw/
Stores local knowledge base files.

vector_db/
Generated ChromaDB vector database. This should not be committed.

outputs/
Generated RAG output files. This should not be committed.

logs/
Generated JSONL logs. This should not be committed.
```

---

## Supported Document Types

```text
.txt
.md
.csv
.pdf
```

---

## Environment Variables

Create a private `.env` file from `.env.example`.

```bash
cp .env.example .env
```

Edit `.env`:

```bash
code .env
```

Example `.env.example`:

```env
CLOUD_API_PROVIDER=clod
CLOUD_API_FORMAT=openai_chat_completions
CLOUD_API_BASE_URL=https://api.clod.io/v1
CLOUD_CHAT_COMPLETIONS_PATH=/chat/completions
CLOUD_CHAT_COMPLETIONS_URL=

CLOUD_API_KEY=replace_with_your_real_api_key
CLOUD_AUTH_HEADER=Authorization
CLOUD_AUTH_PREFIX=Bearer

CLOUD_CHAT_MODEL=Gemma 4 31B IT
CLOUD_TEMPERATURE=0.2
CLOUD_MAX_COMPLETION_TOKENS=700
CLOUD_TIMEOUT_SECONDS=60
CLOUD_MAX_RETRIES=3
CLOUD_RETRY_SLEEP_SECONDS=2

EMBEDDING_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DEVICE=cpu

CHUNK_SIZE=900
CHUNK_OVERLAP=120
TOP_K=4

DATA_FOLDER=data/raw
VECTOR_DB_FOLDER=vector_db/chroma
COLLECTION_NAME=knowflow_ai_documents
REQUIRE_CONTEXT_FOR_ANSWER=true
PROMPT_TEMPLATE_VERSION=rag_v1.0
```

---

## Secret Handling

Never commit this file:

```text
.env
```

Commit only this file:

```text
.env.example
```

Required ignore rules:

```gitignore
.env
.env.local
.env.production
vector_db/
outputs/
logs/
```

Production secret options:

```text
Hugging Face Spaces Secrets
GitHub Actions Secrets
Docker secrets
Kubernetes secrets
AWS Secrets Manager
Azure Key Vault
Google Secret Manager
```

---

## Docker Workflow

This project uses Docker as the main development environment.

Do not install packages locally unless needed.

Do not run:

```bash
pip install -r requirements.txt
```

Use Docker instead.

---

## Build Docker Image

```bash
docker compose build
```

Build from scratch:

```bash
docker compose build --no-cache
```

---

## Start JupyterLab in Docker

```bash
docker compose up knowflow-dev
```

Open:

```text
http://localhost:8888/lab
```

Kernel:

```text
Python (KnowFlow AI Docker)
```

---

## Start JupyterLab in Background

```bash
docker compose up -d knowflow-dev
```

---

## Stop Containers

```bash
docker compose down
```

---

## Restart Containers

```bash
docker compose down

docker compose up knowflow-dev
```

---

## Run Phase 2 Demo Inside Docker

```bash
docker compose run --rm knowflow-dev python scripts/run_phase2_demo.py
```

This command:

1. Loads configuration.
2. Validates environment variables.
3. Creates required folders.
4. Loads documents.
5. Cleans text.
6. Chunks documents.
7. Builds embeddings.
8. Stores vectors in ChromaDB.
9. Tests the cloud LLM connection.
10. Asks demo questions.
11. Saves outputs.
12. Writes logs.

---

## Run Tests Inside Docker

```bash
docker compose run --rm knowflow-dev pytest tests/
```

---

## Open Shell Inside Docker

```bash
docker compose run --rm knowflow-dev bash
```

---

## Check Environment Variables Inside Docker

```bash
docker compose run --rm knowflow-dev python -c "import os; print('MODEL:', os.getenv('CLOUD_CHAT_MODEL')); print('API KEY LOADED:', bool(os.getenv('CLOUD_API_KEY')))"
```

---

## Check Python Import Path Inside Docker

```bash
docker compose run --rm knowflow-dev python -c "import src.config; print('src import works')"
```

---

## View Docker Logs

```bash
docker compose logs -f
```

---

## Docker Manager Script

Make script executable:

```bash
chmod +x scripts/docker_manager.sh
```

Available commands:

```bash
./scripts/docker_manager.sh build
./scripts/docker_manager.sh start
./scripts/docker_manager.sh stop
./scripts/docker_manager.sh restart
./scripts/docker_manager.sh rebuild
./scripts/docker_manager.sh test
./scripts/docker_manager.sh demo
./scripts/docker_manager.sh shell
./scripts/docker_manager.sh logs
./scripts/docker_manager.sh status
./scripts/docker_manager.sh clean
./scripts/docker_manager.sh streamlit
```

Recommended daily command:

```bash
./scripts/docker_manager.sh start
```

Run backend demo:

```bash
./scripts/docker_manager.sh demo
```

Run tests:

```bash
./scripts/docker_manager.sh test
```

Stop project:

```bash
./scripts/docker_manager.sh stop
```

---

## Future Streamlit Command

Phase 3 will implement:

```text
app/streamlit_app.py
```

Then run:

```bash
docker compose --profile streamlit up knowflow-streamlit
```

Open:

```text
http://localhost:8501
```

---

## Docker Permission Fix

If Docker shows permission denied:

```bash
sudo usermod -aG docker $USER

newgrp docker

docker ps
```

If it still fails, restart the computer.

Temporary command:

```bash
sudo docker compose up knowflow-dev
```

---

## Port Already in Use

If port `8888` is already used, change `docker-compose.yml`:

```yaml
ports:
  - "8890:8888"
```

Open:

```text
http://localhost:8890/lab
```

If Streamlit port `8501` is used, change:

```yaml
ports:
  - "8502:8501"
```

Open:

```text
http://localhost:8502
```

---

## Clean Docker Cache

Basic cleanup:

```bash
docker system prune -f
```

Full cleanup:

```bash
docker compose down -v --rmi all

docker system prune -a -f
```

---

## Phase 2 Backend Modules

### `src/config.py`

Handles:

```text
.env loading
environment variables
project root detection
folder path creation
configuration validation
```

### `src/document_loader.py`

Handles:

```text
TXT loading
Markdown loading
CSV loading
PDF loading
source metadata
```

### `src/text_cleaner.py`

Handles:

```text
line ending normalization
space cleanup
blank line cleanup
```

### `src/chunker.py`

Handles:

```text
paragraph-aware chunking
long paragraph splitting
stable chunk IDs
```

### `src/embeddings.py`

Handles:

```text
sentence-transformer loading
CPU embedding generation
query embedding
```

### `src/vector_store.py`

Handles:

```text
ChromaDB client
collection creation
collection reset
chunk storage
vector search
```

### `src/retriever.py`

Handles:

```text
question embedding
top-k retrieval
semantic search
```

### `src/llm_client.py`

Handles:

```text
cloud API headers
cloud API payload
retry logic
timeout handling
response parsing
connection testing
```

### `src/rag_pipeline.py`

Handles:

```text
full RAG orchestration
document loading
cleaning
chunking
embedding
indexing
retrieval
prompt creation
LLM calling
result saving
```

### `src/logging_utils.py`

Handles:

```text
JSON output saving
JSONL event logging
```

---

## RAG Flow

```text
User question
    ↓
Embed question
    ↓
Search ChromaDB
    ↓
Retrieve top-k chunks
    ↓
Build RAG prompt
    ↓
Call cloud LLM
    ↓
Return grounded answer
    ↓
Show sources
```

---

## Prompt Guardrail

The default prompt instructs the model:

```text
Use only the provided context.
If the answer is not in the context, say:
"I do not know from the provided knowledge base."
```

This reduces hallucination and makes the app safer for document-based question answering.

---

## Demo Questions

Example questions for `company_policy.txt`:

```text
What is the refund policy?
How long does standard shipping take?
What does the warranty cover?
Does the company sell customer data?
How many days of annual leave do employees get?
How much training support can employees receive?
What is the company policy about quantum teleportation?
```

The last question is intentionally outside the knowledge base and should trigger the safe fallback response.

---

## Git Workflow

Create feature branch:

```bash
git checkout develop

git pull origin develop

git checkout -b feature/phase-2-modular-rag-pipeline
```

---

## Phase 2 Commit Plan

Configuration module:

```bash
git add src/config.py

git commit -m "Add configuration management for modular RAG pipeline"
```

Document loading and cleaning:

```bash
git add src/document_loader.py src/text_cleaner.py

git commit -m "Add document loading and text cleaning modules"
```

Chunking:

```bash
git add src/chunker.py

git commit -m "Add paragraph-aware chunking for document retrieval"
```

Embeddings:

```bash
git add src/embeddings.py

git commit -m "Add local embedding model wrapper for RAG retrieval"
```

Vector store:

```bash
git add src/vector_store.py

git commit -m "Add ChromaDB vector store integration"
```

Retriever:

```bash
git add src/retriever.py

git commit -m "Add semantic retriever for vector search"
```

Cloud LLM client:

```bash
git add src/llm_client.py

git commit -m "Add OpenAI-compatible cloud LLM client"
```

Logging utilities:

```bash
git add src/logging_utils.py

git commit -m "Add structured logging utilities for RAG events"
```

RAG orchestration:

```bash
git add src/rag_pipeline.py

git commit -m "Add modular RAG pipeline orchestration"
```

CLI demo:

```bash
git add scripts/run_phase2_demo.py

git commit -m "Add CLI demo runner for Phase 2 RAG pipeline"
```

Tests:

```bash
git add tests/test_document_loader.py tests/test_chunker.py tests/test_rag_pipeline.py

git commit -m "Add tests for modular RAG components"
```

Docker files:

```bash
git add Dockerfile docker-compose.yml .dockerignore .gitignore .env.example requirements.txt scripts/docker_manager.sh

git commit -m "Add Docker workflow for KnowFlow AI modular RAG pipeline"
```

Push feature branch:

```bash
git push -u origin feature/phase-2-modular-rag-pipeline
```

Merge into develop:

```bash
git checkout develop

git pull origin develop

git merge feature/phase-2-modular-rag-pipeline

git push origin develop
```

---

## Useful Git Commands

Check status:

```bash
git status
```

Check branch:

```bash
git branch
```

Check recent commits:

```bash
git log --oneline --decorate -10
```

Unstage files:

```bash
git reset
```

Check ignored files:

```bash
git status --ignored
```

Check whether `.env` is tracked:

```bash
git ls-files | grep ".env"
```

If `.env` is accidentally tracked:

```bash
git rm --cached .env

git commit -m "Remove local environment file from tracking"
```

---

## What Should Not Be Committed

Do not commit:

```text
.env
vector_db/
outputs/
logs/
.venv/
__pycache__/
.ipynb_checkpoints/
```

These are secrets or generated artifacts.

---

## What Should Be Committed

Commit:

```text
src/
scripts/
tests/
app/
docs/
data/sample/
data/raw/company_policy.txt
Dockerfile
docker-compose.yml
requirements.txt
.env.example
.gitignore
.dockerignore
README.md
```

---

## Phase 2 Completion Checklist

```text
Configuration:
[ ] src/config.py loads environment variables
[ ] config validation works
[ ] required folders are created

Document processing:
[ ] TXT loading works
[ ] Markdown loading works
[ ] CSV loading works
[ ] PDF loading works
[ ] text cleaning works

Chunking:
[ ] paragraph-aware chunking works
[ ] stable chunk IDs are generated

Embeddings:
[ ] CPU embedding model loads
[ ] text chunks are embedded

Vector database:
[ ] ChromaDB collection is created
[ ] vector database rebuild works
[ ] top-k retrieval works

Cloud LLM:
[ ] API key loads from environment
[ ] cloud API call works
[ ] retry logic works
[ ] timeout exists

RAG:
[ ] retrieved chunks are inserted into prompt
[ ] answer is generated
[ ] sources are returned
[ ] unknown questions safely fallback

Testing:
[ ] docker demo command runs
[ ] pytest runs
[ ] output files are generated locally
[ ] logs are generated locally

Git:
[ ] Phase 2 commits completed
[ ] feature branch pushed
[ ] develop branch updated
```

---

## Current Best Command Sequence

From project root:

```bash
docker compose build --no-cache

docker compose run --rm knowflow-dev python scripts/run_phase2_demo.py

docker compose run --rm knowflow-dev pytest tests/

git status
```

---

## Next Phase

```text
Phase 3: Build the Streamlit application interface.
```

Phase 3 goals:

```text
- Add document upload UI
- Add question input
- Add chat-style response area
- Add retrieved source expanders
- Add rebuild vector DB button
- Add sample questions
- Add model/config display
- Prepare Hugging Face Spaces deployment
```