SANKETKAKAD/usa-constitution-gpt

🏛️ Constitution GPT

Live App / Deployment: https://huggingface.co/spaces/SANKETKAKAD/usa-constitution-gpt

[image]

Welcome to Constitution GPT – a Retrieval-Augmented Generation (RAG) powered application designed to provide precise, context-aware answers to questions about the United States Constitution.

Built with an emphasis on speed and reliability, this portfolio project demonstrates modern AI engineering principles, integrating local vector embeddings with advanced LLMs in a highly responsive Streamlit interface.

✨ Key Features

• —Retrieval-Augmented Generation (RAG): Answers are grounded strictly in the text of the USA Constitution, avoiding LLM hallucinations.
• —Local Embeddings for Privacy & Speed: Utilizes BAAI/bge-m3 via HuggingFace for fast, localized vector embeddings without sending documents to third-party APIs.
• —High-Performance Vector DB: Powered by ChromaDB for blazing-fast semantic search.
• —Streaming Responses: Implements real-time token streaming (like ChatGPT) for a smooth and highly responsive user experience.
• —Bring Your Own Key (BYOK): Seamlessly integrates with OpenAI-compatible endpoints (like Google Gemini Flash Lite) for flexible LLM backend usage.
• —Docker Ready: Fully containerized for one-click deployments.

🛠️ Technology Stack

• —Frontend: Streamlit
• —LLM Framework: LangChain
• —Vector Database: ChromaDB
• —Embeddings: HuggingFace (BAAI/bge-m3)
• —Document Processing: MarkItDown & Recursive Character Splitting
• —Containerization: Docker

🏗️ Architecture Flow

1. 1.Ingestion: The raw PDF of the Constitution is parsed using MarkItDown into markdown text.
2. 2.Chunking: Text is split using RecursiveCharacterTextSplitter into overlapping logical chunks.
3. 3.Embedding: Chunks are vectorized locally using HuggingFaceEmbeddings.
4. 4.Retrieval: When a user asks a question, the local embedding model vectorizes the query and performs a similarity search (k=3) against ChromaDB.
5. 5.Generation: The context is fed into the LLM, which streams the generated answer back to the UI.

🚀 How to Run Locally

Using Docker (Recommended)

This project is configured to run flawlessly in Docker.

# Build the Docker image
docker build -t constitution-gpt .

# Run the container
docker run -p 8501:8501 constitution-gpt

Then open http://localhost:8501 in your browser.

Using Python (Native)

# Clone the repository
git clone https://github.com/YourUsername/constitution-gpt.git
cd constitution-gpt

# Install dependencies using `uv` or pip
pip install .

# Run the Streamlit app
streamlit run src/app.py

📜 License

This project is open-source and available under the MIT License.