Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

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.

Table of contents

  • 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

Prerequisites

  • 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).

Setup

  1. Clone or open this repository and change into the project directory (already located at the workspace root):
cd /path/to/Agentic-Project/localDB
  1. Create and activate a Python virtual environment (recommended):
python -m venv .venv
source .venv/bin/activate
  1. Install Python dependencies:
pip install -r requirements.txt
# If you add packages you may also need:
pip install langchain-ollama ollama faiss-cpu flask

Note: The repo already contains a requirements.txt with most dependencies. If you see an import error, install the missing package shown in the traceback.

Prepare Ollama and models

The code expects two Ollama models by default:

  • llama3:latest — used for chat completions
  • nomic-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.5

Make sure ollama serve is running before you index documents or run the UI.

Initialize the vectorstore (sample documents)

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.

Run the CLI chat app

To run the terminal chat application:

source .venv/bin/activate
python app.py

Commands supported in the CLI:

  • /exit or /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.

Run the Web UI (recommended for usability)

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 browser

The UI supports drag-and-drop uploads, shows document counts and model status, and provides a chat panel.

Uploading files & processing

  • Use the web UI drag & drop or the CLI /upload command to add files to the uploads/ directory.
  • Supported file types: .txt, .pdf, .py, .md, .json (file processor can be extended)
  • Uploaded files are processed by file_processor.py to 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.

Notes, security & troubleshooting

  • 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 serve is running and that the models are pulled and available under the model names configured in app.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.

Extending the project

  • Add more file loaders to file_processor.py to 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.

Quick development checklist

  1. Activate venv: source .venv/bin/activate
  2. Start Ollama: ollama serve &
  3. Pull models: ollama pull llama3:latest nomic-embed-text:v1.5
  4. Initialize DB: python initialize_db.py
  5. Run UI: cd ui && python app.py

License & credits

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_deserialization flag guarded by a CLI option

Tell me which of the above you'd like next and I will implement it.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages