Green Elephant — Local Codebase Chatbot
A small Retrieval-Augmented Generation (RAG) chat system that lets you upload local files, index them with embeddings, and ask questions against your codebase or documents. The project includes:
- a CLI chat app (
app.py) - a RAG backend (
rag.py) that manages embeddings and a FAISS vectorstore - file processing utilities (
file_processor.py) to convert uploaded files into indexable documents - a small web UI (Flask) in
ui/for drag-and-drop uploads and chat
This README explains setup, how to run the project, and troubleshooting tips.
- Prerequisites
- Setup (virtualenv + deps)
- Prepare Ollama & models
- Initialize the vectorstore (sample docs)
- Run the CLI chat
- Run the Web UI
- Uploading files & processing
- Notes, security & troubleshooting
- Python 3.10+ (3.12 tested in this environment)
- pip
- Ollama (server) for local models — https://ollama.com
- Git (optional)
You should have Ollama installed and running locally if you plan to use the included Ollama-based LLMs and embeddings. The UI and RAG integration expect the Ollama daemon at the default address (http://localhost:11434).
- Clone or open this repository and change into the project directory (already located at the workspace root):
cd /path/to/Agentic-Project/localDB- Create and activate a Python virtual environment (recommended):
python -m venv .venv
source .venv/bin/activate- Install Python dependencies:
pip install -r requirements.txt
# If you add packages you may also need:
pip install langchain-ollama ollama faiss-cpu flaskNote: The repo already contains a requirements.txt with most dependencies. If you see an import error, install the missing package shown in the traceback.
The code expects two Ollama models by default:
llama3:latest— used for chat completionsnomic-embed-text:v1.5— used for embeddings (FAISS)
If you have Ollama installed, pull those models (or any other models you want to use) with:
# pull and run ollama if not installed
# install Ollama (Linux):
# curl -fsSL https://ollama.com/install.sh | sh
# start Ollama server (if needed)
ollama serve &
# pull models
ollama pull llama3:latest
ollama pull nomic-embed-text:v1.5Make sure ollama serve is running before you index documents or run the UI.
The project contains an initialize_db.py helper that will create a small sample vectorstore (used when none exists):
source .venv/bin/activate
python initialize_db.py
# Output: "Vectorstore initialized and saved to: data/vectorstore"This creates a data/vectorstore folder with the FAISS index and metadata. The main app will use that by default.
To run the terminal chat application:
source .venv/bin/activate
python app.pyCommands supported in the CLI:
/exitor/quit— exit/clear— clear session history/history— show chat history/upload /path/to/file— copy and index a single file into the uploads folder/process— process and index all files under the uploads directory
When the RAG index is present, user questions will be augmented with retrieved context from indexed documents.
A small Flask-based UI is available in ui/:
cd ui
source ../.venv/bin/activate # if not already active
python app.py
# Open http://localhost:5000 in your browserThe UI supports drag-and-drop uploads, shows document counts and model status, and provides a chat panel.
- Use the web UI drag & drop or the CLI
/uploadcommand to add files to theuploads/directory. - Supported file types:
.txt,.pdf,.py,.md,.json(file processor can be extended) - Uploaded files are processed by
file_processor.pyto split into chunks, then added to the FAISS vectorstore.
If you want to add a local codebase for indexing, copy the files into uploads/ (or upload via UI) and run /process or click upload — the files will be parsed and indexed.
-
Pickle deserialization: The FAISS loader uses pickles internally. If you load a vectorstore from disk and see an error about "allow_dangerous_deserialization", you can enable that parameter only if you trust the file source. This repo initializes and reads vectorstores created locally by the same code.
-
Ollama errors: If embedding or LLM calls fail, verify
ollama serveis running and that the models are pulled and available under the model names configured inapp.py(MODEL_NAME/EMBEDDING_MODEL). Adjust the model names if you use different local models. -
Missing imports: Install required packages shown in tracebacks. Virtual environment isolation is recommended.
- Add more file loaders to
file_processor.pyto parse additional file formats. - Add authentication to the UI (Flask) if you want remote access.
- Improve ranking, re-ranking, or combine multiple retrievers for better context quality.
- Activate venv:
source .venv/bin/activate - Start Ollama:
ollama serve & - Pull models:
ollama pull llama3:latest nomic-embed-text:v1.5 - Initialize DB:
python initialize_db.py - Run UI:
cd ui && python app.py
This is a small personal/project demo — add a license file if you want to open-source it.
If you'd like, I can:
- Add a dark theme toggle to the UI
- Implement per-file upload status reporting from the backend
- Harden the FAISS load with an explicit
allow_dangerous_deserializationflag guarded by a CLI option
Tell me which of the above you'd like next and I will implement it.