Metadata-Version: 2.4
Name: lulu-ai
Version: 1.0.1
Summary: AI-powered screen assistant — solves MCQs, generates and auto-types code/theory answers using global hotkeys.
Author-email: Your Name <your@email.com>
License-Expression: MIT
Keywords: ai,assistant,gemini,automation,hotkeys,mcq
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pynput>=1.7
Requires-Dist: google-generativeai>=0.8
Requires-Dist: Pillow>=10.0
Requires-Dist: pyautogui>=0.9
Requires-Dist: requests>=2.31
Requires-Dist: python-dotenv>=1.0
Requires-Dist: customtkinter>=5.2
Dynamic: license-file

# 🤖 Lulu AI Assistant

An AI-powered screen assistant that solves MCQs, generates code/theory answers, and auto-types responses — all controlled by global hotkeys. Powered by Google Gemini, Groq, and OpenRouter.

---

## ⚡ Quick Install

```bash
pipx install lulu-ai
```

Then set up your API key and start:

```bash
lulu start
```

---

## 🔑 Setup — API Key

Create a `.env` file in your working directory:

```env
GEMINI_API_KEY=your_gemini_key_here
GROQ_API_KEY=your_groq_key_here          # optional but recommended
OPENROUTER_API_KEY=your_openrouter_key   # optional but recommended
```

Get your keys from:
- Gemini → https://aistudio.google.com/app/apikey
- Groq → https://console.groq.com/keys
- OpenRouter → https://openrouter.ai/keys

---

## 🖥️ CLI Commands

```bash
lulu start              # Start the assistant in the background
lulu stop               # Stop the assistant
lulu status             # Check if it's running
lulu logs               # Show last 50 log lines
lulu logs --follow      # Stream logs live
lulu logs --lines 100   # Show last 100 lines
lulu doctor             # Diagnose your environment
lulu --version          # Show installed version
```

---

## ✨ Features

### MCQ Mode
- Captures a question and any number of options from the screen
- Optionally uses a context screenshot for reading comprehension questions
- Automatically identifies the correct option and clicks it

### Subjective / Coding Mode
- Captures one or more screenshots of a question
- Classifies question type (DSA, SQL, theory) automatically
- Generates a detailed code or text answer
- Auto-types the response with human-like delays
- Supports pausing and resuming auto-typing

### Step-by-Step Solution
- Generates a detailed step-by-step breakdown
- Shown in a dedicated explanation window

### Stealth Tools
- Hidden notes window — invisible to screen sharing (Zoom, Teams, OBS)
- Code explanation window with summary, dry run, and complexity analysis
- Both windows movable with hotkeys

### Control Panel
- Change API keys, hotkeys, typing speed, and window sizes live
- No restart needed for most settings

---

## ⌨️ Hotkey Reference

| Hotkey | Action |
|---|---|
| `Ctrl+Alt+C` | Capture context passage for an MCQ |
| `Ctrl+Alt+P` | Capture question and options for an MCQ |
| `Ctrl+Alt+S` | Capture screenshot for a subjective question |
| `Ctrl+Alt+G` | Generate AI response from screenshots |
| `Ctrl+Alt+T` | Auto-type the generated response |
| `Ctrl+Alt+Z` | Resume a paused auto-typing session |
| `Ctrl+Alt+K` | Retry with error screenshot |
| `Ctrl+Alt+J` | Explain code (summary, dry run, complexity) |
| `Ctrl+Alt+O` | Step-by-step solution |
| `Ctrl+Alt+N` | Toggle hidden notes window |
| `Ctrl+Alt+A` | Toggle explanation window |
| `Ctrl+Alt+M` | Open control panel |
| `Ctrl+Alt+Arrows` | Move the active stealth window |
| `Ctrl+Alt+R` | Clear all captured context and screenshots |
| `Ctrl+Alt+E` | Exit |

---

## 🔄 AI Provider Routing

Lulu uses multiple AI providers with automatic fallback:

| Task | Primary | Fallback |
|---|---|---|
| MCQ solving | Gemini | Gemini (secondary key) |
| Code generation | Groq | OpenRouter → Gemini |
| Theory answers | Groq | Gemini |
| Code explanation | Groq | Gemini |

All providers retry automatically on rate limits before failing over.

---

## 🛠️ Troubleshooting

**`lulu start` does nothing**
→ Run `lulu doctor` to check your environment

**Garbled text when auto-typing resumes**
→ Hold still after pressing `Ctrl+Alt+Z` — there is a 0.4s grace period before typing starts

**Gemini quota exceeded**
→ Switch to `gemini-2.5-flash` in the control panel (`Ctrl+Alt+M`) — it has higher free-tier limits

**macOS: hotkeys not working**
→ Go to System Settings → Privacy & Security → Accessibility → add your terminal app

---

## 📋 Requirements

- Python 3.9+
- Windows / macOS / Linux
- Google Gemini API key (required)
- Groq API key (recommended)
- OpenRouter API key (recommended)

---

## 📄 License

MIT License — see LICENSE file for details.
