README.md

metadata

title: AI Study Notes Agent
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

AI Study Notes Agent 📚

Enterprise-Grade Multi-User AI Study Assistant

---

An enterprise-grade, multi-user AI Study Assistant built locally on Python & Streamlit. This application leverages a dynamic multi-tier LLM cascade and intelligent document routing to transform how users digest and interact with academic materials. It ensures zero-downtime service via seamless failovers across Google Gemini, Groq, and Hugging Face infrastructure.

---

📸 Interface Preview

Showcasing the authentication flow, document pipeline, and dynamic generation options

*From left to right: Secure authentication, seamless multi-document uploads, and deep customization options.*

---

💻 Tech Stack

Frontend & Core Framework

• Framework: Streamlit
• Language: Python 3.10+
• Audio Generation: gTTS (Google Text-To-Speech)
• Flashcard Compilation: GenAnki

Backend & Data Layer

• Relational Database & Auth: Supabase (PostgreSQL)
• Vector Database: ChromaDB
• Data Pipelines: LangChain Text Splitters, python-docx, python-pptx, PyPDF2
• Security: bcrypt, OAuth 2.0 (GitHub)

AI & Inference

• Core Reasoning Engine (Tier 1): Google Gemini 2.5 Flash (google-genai)
• Secondary Fallback Engine (Tier 2): Groq API (llama-3.3-70b-versatile)
• Tertiary Fallback Engine (Tier 3): Hugging Face Serverless API (meta-llama/Meta-Llama-3-70B-Instruct)
• Vision & OCR Pipeline: Gemini 2.5 Flash with fallback to Groq llama-3.2-11b-vision-preview (powered by pdf2image and Pillow)
• Vector Embeddings: gemini-embedding-001
• Real-time Data Fetching: Google Search Grounding API

---

🌐 System Architecture

The AI Study Notes Agent utilizes a local processing engine seamlessly connected to cloud-based persistence and state-of-the-art AI inference pipelines.

System Diagram

graph TD
    %% Client Layer
    subgraph Client [User Interface]
        A["Streamlit Frontend \n (Web Browser)"]
        B["User Inputs \n (PDFs, PPTXs, DOCXs, Queries)"]
        B --> A
    end

    %% Cloud/Data Layer
    subgraph Data [Data & Persistence]
        C[("Supabase \n (PostgreSQL)")]
        D[("ChromaDB \n (Local Ephemeral Store)")]
    end

    %% Inference/AI Layer
    subgraph Inference [3-Tier Cascading AI Engine]
        E["Tier 1: Gemini 2.5 Flash"]
        F["Tier 2: Groq Llama-3.3"]
        G["Tier 3: HF Meta-Llama-3"]
        H["LangChain \n (Pipeline Router)"]
        I["gTTS & GenAnki \n (Exporters)"]
    end

    %% Connections
    A <-->|Context & Auth History| C
    A -->|Threshold Evaluation| H
    H <-->|> 120k chars| D
    H <-->|Semantic Context / Direct Prompt| E
    E -.->|Failover| F
    F -.->|Failover| G
    A <-->|Generate Output| I
    I -->|Podcasts / Anki Decks| A

Component Breakdown

Frontend — Streamlit UI Engine A dynamic, Python-driven user interface managing real-time chat interactions, document uploads, and complex layout configurations securely inside the user's browser.

Data Layer — Supabase & ChromaDB Supabase acts as the remote source of truth for user sessions, saving chat histories and document metadata securely with Row Level Security (RLS). ChromaDB operates dynamically: smaller files bypass it completely, while large files deploy an ultra-fast ephemeral vector indexer for real-time document semantic search.

Inference — 3-Tier Cascading Engine & Grounding Powers the intelligence of the application with absolute zero downtime. Gemini 2.5 Flash acts as the primary orchestrator to synthesize study notes. If rate limits or outages occur, the system automatically falls back to Groq and Hugging Face.

---

✨ Core Features & AI Pipeline

Feature	Description
Universal Ingestion Engine	Upload academic PDFs, Word Docs (.docx), PowerPoints (.pptx), Images (.png, .jpg), and Text files to instantly generate tailored study notes. Features an advanced LLM Vision cascade and smart fallback OCR for scanned documents!
Smart Pipeline Routing	Evaluates document length dynamically. Files < 120k characters bypass vectorization directly to the LLM context. Larger files trigger chunking into an ephemeral ChromaDB RAG index.
High-Availability LLM Cascade	Guarantees zero downtime. The backend automatically catches connection/rate limit errors on Google Gemini and cascades the generation request to Groq, and then to Hugging Face if needed. All core Gemini Agent calls (generate_content and send_chat_message) are actively wrapped with dynamic Groq fallbacks.
Interactive Q&A & Web Search 🌐	Chat natively with the LLM about your textbooks. Live Web Search dynamically bridges Google's enterprise Search Grounding APIs into your chat.
1-Click Anki Generator 🗃️	AI extracts factual data from your notes, injecting pairs seamlessly into an SQLite database via genanki, handing you an .apkg file directly to import into Desktop Anki Software.
Podcast Mode 🎧	Seamlessly converts Markdown notes into an accessible spoken podcast natively in the browser leveraging gTTS (Google Text-To-Speech).
Cloud DB & OAuth 2.0 ☁️	Hooked dynamically to a remote Supabase (PostgreSQL) database. Log in via Email/Password or Github OAuth.
Robust Security Setup 🛡️	Hardened authentication with rate-limiting lockouts, implicit login after signup, and password complexity requirements. Implements a strict 3-Layer Prompt Guard (Regex pattern filtering, Groq llama-3 LLM-based classification, and System Prompt boundaries) to block prompt injections, off-topic spam, and data exfiltration attempts.

---

🛠️ Installation & Setup

Ensure you have Python 3.10+ installed.

1. Clone & Virtual Environment

git clone https://github.com/your-username/ai-study-notes-agent.git
cd ai-study-notes-agent
python -m venv venv
source venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file inside the root folder matching this exact blueprint:

# Google AI API Key
GEMINI_API_KEY=your_gemini_api_key

# Supabase Postgres Deployment
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_public_key

# OAuth APIs
GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_secret

# LLM Fallback Provider Keys
GROQ_API_KEY=your_groq_api_key
HUGGINGFACE_API_KEY=your_huggingface_api_key

4. Initialize Supabase Datastore

You must execute this SQL block in your Supabase SQL Editor:

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT,
  provider TEXT DEFAULT 'email',
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE sessions (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  filename TEXT NOT NULL,
  pdf_text TEXT,
  notes TEXT,
  chat_history JSONB DEFAULT '[]'::jsonb,
  timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Note: Ensure strict Row Level Security (RLS) policies are active in production.
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE sessions ENABLE ROW LEVEL SECURITY;

5. Launch Application

source venv/bin/activate  # (Use .\venv\Scripts\activate on Windows)
streamlit run app.py

---

🚀 CI/CD & Deployment Guide (Hugging Face Spaces)

This project is fully dockerized and features a complete GitHub Actions CI/CD pipeline for seamless production deployment on Hugging Face Spaces.

1. Create a new Space on Hugging Face and select the Docker environment template.
2. In your GitHub repository, configure your Hugging Face Access Token as a Secret named HF_TOKEN.
3. Ensure .github/workflows/deploy_hf.yml points to your exact Hugging Face Space ID.
4. Any pushes to the main branch will automatically sync and trigger a rebuild on Hugging Face Spaces!
5. Configure your Space Secrets with all the environment variables defined in the .env template above.
6. Hugging Face will automatically construct the container using the provided Dockerfile. Note: chroma_db/ is ephemeral by design, so no persistent volume configuration is required.

---

📁 Project Directory Map

ai-study-notes-agent/
├── .github/workflows/  # Automated CI/CD Pipelines
├── app.py              # Main Entry Point (Streamlit)
├── requirements.txt    # Python Dependencies
├── .env                # Secret Keys (Not tracked)
├── src/
│   ├── core/           # Agent Logic, Pipeline Router, LLM Cascade, Vision Client
│   ├── security/       # 3-Layer Prompt Guard & AI Security Classifiers
│   ├── database/       # Supabase Client & Operations
│   ├── auth/           # OAuth 2.0 (GitHub)
│   ├── ui/             # Modular Streamlit UI Components
│   ├── exporters/      # PDF, Anki, & Audio Generation
│   └── utils/          # Universal Extraction Engine (PDF, DOCX, PPTX)
└── tests/              # Test Scripts & Debug Utilities

---

Built with ❤️ for intelligent, local-first learning dynamics.

---

📄 License

MIT License — click to expand

MIT License

Copyright (c) 2025 AI Study Notes Agent

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.