Cleo - AI Exam Generator & Scholar

Cleo is an advanced AI research assistant and exam generator that combines authentic past year questions with AI-generated content. It features a modern React Frontend, a robust FastAPI Backend, and supports multiple AI providers including OpenAI, Anthropic, DeepSeek, Groq, and Ollama.

🚀 Key Features

• ⚡ Hybrid Generation: Combines real questions scraped from the web (using Go) with AI-generated descriptive questions.
• 🧠 Multi-Provider Support: Switch seamlessly between Ollama (Local), Groq, OpenAI, Anthropic, and DeepSeek directly from the UI.
• 🖥️ Modern UI: Minimalist interface built with React, Vite, Tailwind CSS, and shadcn/ui.
• 📄 Embedded PDF Viewer: View generated exam papers instantly within the browser with rich controls.
• 🔍 Autonomous Research: Uses a high-performance Go binary to search and scrape relevant content.
• 🔐 Dynamic Auth: Input API keys securely via the UI or use environment variables.

🛠️ Prerequisites

• Python 3.12+
• Node.js & npm (for Frontend)
• Go 1.25+ (if rebuilding the scraper, binary provided)

📦 Installation & Setup

1. Clone Content

git clone https://github.com/yourusername/cleo.git
cd cleo

2. Backend Setup

Install Python dependencies and start the API server:

# Install dependencies
pip install -r requirements.txt
pip install openai anthropic # if not in requirements

# Start FastAPI Server
uvicorn api:app --reload

Server runs on http://127.0.0.1:8000

3. Frontend Setup

Open a new terminal, navigate to frontend, and start the development server:

cd frontend

# Install dependencies
npm install

# Start Dev Server
npm run dev

App runs on http://localhost:5173

💻 Usage

1. Open Cleo in your browser (http://localhost:5173).
2. Enter a Topic (e.g., "UPSC History", "Machine Learning").
3. Select your AI Provider (e.g., OpenAI, Groq).
4. (Optional) Enter your API Key if not set in .env.
5. Check "Search & include authentic past year questions".
6. Click Generate Paper.
7. View and download the generated PDF directly in the app.

📂 Project Structure

• frontend/: React + Vite application (UI).
• api.py: FastAPI server handling generation requests.
• py_cleo/: Core Python modules (Agent, Exam Service, Research Service).
• go-cleo/: Go source code for the high-performance scraper.
• main.py: Legacy CLI entry point.

📄 License

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