Hugging Face's logo

Spaces:
babupallam
/
knowflow-ai-rag-document-chatbot
Runtime error

App Files Community
knowflow-ai-rag-document-chatbot / README.md
Babu Pallam
Fix Hugging Face Spaces README configuration
45cb332
preview code
|
Raw
History Blame Contribute Delete
16.7 kB

A newer version of the Streamlit SDK is available: 1.59.1

Upgrade
metadata 
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 

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:

knowflow-ai-rag-document-chatbot

Why this name is used:

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

Folder Structure 

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 

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 

.txt
.md
.csv
.pdf

Environment Variables

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

cp .env.example .env

Edit .env:

code .env

Example .env.example:

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:

.env

Commit only this file:

.env.example

Required ignore rules:

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

Production secret options:

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:

pip install -r requirements.txt

Use Docker instead.

Build Docker Image 

docker compose build

Build from scratch:

docker compose build --no-cache

Start JupyterLab in Docker 

docker compose up knowflow-dev

Open:

http://localhost:8888/lab

Kernel:

Python (KnowFlow AI Docker)

Start JupyterLab in Background 

docker compose up -d knowflow-dev

Stop Containers 

docker compose down

Restart Containers 

docker compose down

docker compose up knowflow-dev

Run Phase 2 Demo Inside Docker 

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 

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

Open Shell Inside Docker 

docker compose run --rm knowflow-dev bash

Check Environment Variables Inside Docker 

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 

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

View Docker Logs 

docker compose logs -f

Docker Manager Script

Make script executable:

chmod +x scripts/docker_manager.sh

Available commands:

./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:

./scripts/docker_manager.sh start

Run backend demo:

./scripts/docker_manager.sh demo

Run tests:

./scripts/docker_manager.sh test

Stop project:

./scripts/docker_manager.sh stop

Future Streamlit Command

Phase 3 will implement:

app/streamlit_app.py

Then run:

docker compose --profile streamlit up knowflow-streamlit

Open:

http://localhost:8501

Docker Permission Fix

If Docker shows permission denied:

sudo usermod -aG docker $USER

newgrp docker

docker ps

If it still fails, restart the computer.

Temporary command:

sudo docker compose up knowflow-dev

Port Already in Use

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

ports:
  - "8890:8888"

Open:

http://localhost:8890/lab

If Streamlit port 8501 is used, change:

ports:
  - "8502:8501"

Open:

http://localhost:8502

Clean Docker Cache

Basic cleanup:

docker system prune -f

Full cleanup:

docker compose down -v --rmi all

docker system prune -a -f

Phase 2 Backend Modules

src/config.py

Handles:

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

src/document_loader.py

Handles:

TXT loading
Markdown loading
CSV loading
PDF loading
source metadata

src/text_cleaner.py

Handles:

line ending normalization
space cleanup
blank line cleanup

src/chunker.py

Handles:

paragraph-aware chunking
long paragraph splitting
stable chunk IDs

src/embeddings.py

Handles:

sentence-transformer loading
CPU embedding generation
query embedding

src/vector_store.py

Handles:

ChromaDB client
collection creation
collection reset
chunk storage
vector search

src/retriever.py

Handles:

question embedding
top-k retrieval
semantic search

src/llm_client.py

Handles:

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

src/rag_pipeline.py

Handles:

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

src/logging_utils.py

Handles:

JSON output saving
JSONL event logging

RAG Flow 

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:

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:

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:

git checkout develop

git pull origin develop

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

Phase 2 Commit Plan

Configuration module:

git add src/config.py

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

Document loading and cleaning:

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

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

Chunking:

git add src/chunker.py

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

Embeddings:

git add src/embeddings.py

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

Vector store:

git add src/vector_store.py

git commit -m "Add ChromaDB vector store integration"

Retriever:

git add src/retriever.py

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

Cloud LLM client:

git add src/llm_client.py

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

Logging utilities:

git add src/logging_utils.py

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

RAG orchestration:

git add src/rag_pipeline.py

git commit -m "Add modular RAG pipeline orchestration"

CLI demo:

git add scripts/run_phase2_demo.py

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

Tests:

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:

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:

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

Merge into develop:

git checkout develop

git pull origin develop

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

git push origin develop

Useful Git Commands

Check status:

git status

Check branch:

git branch

Check recent commits:

git log --oneline --decorate -10

Unstage files:

git reset

Check ignored files:

git status --ignored

Check whether .env is tracked:

git ls-files | grep ".env"

If .env is accidentally tracked:

git rm --cached .env

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

What Should Not Be Committed

Do not commit:

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

These are secrets or generated artifacts.

What Should Be Committed

Commit:

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 

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:

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 

Phase 3: Build the Streamlit application interface.

Phase 3 goals:

- 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