Iniquiz AI Lite

Iniquiz AI Lite is a lightweight desktop application built with Kivy and Python that allows users to chat with an AI assistant and automatically generate quizzes based on the conversation.

This repository contains the lite version (prototype) of the app. A larger and more advanced version of Iniquiz AI is currently in development.

---

Features

• Conversational Quiz Generation – Chat with an AI and instantly turn discussions into interactive quizzes
• Cross-platform Desktop App – Built with Kivy + KivyMD for Windows, macOS, and Linux
• LLM Integration – Supports OpenRouter and DeepSeek APIs (others may work with minimal configuration)

---

Project Structure

.
├── app/                   # UI and screen management
│   ├── __init__.py
│   ├── app.py                     # Main application entry point
│   ├── base_screen.py            # Base screen class with common functionality
│   ├── shared_components.py      # Reusable UI components
│   ├── constants.py              # App-wide constants and configuration
│   ├── quiz_data_manager.py      # Quiz data management utilities
│   └── screens/                  # Screen implementations
│       ├── __init__.py
│       ├── home.py               # Main landing screen
│       ├── create_quiz_source.py # Quiz source selection
│       ├── ai_chat.py            # AI conversation interface
│       ├── select_game_mode.py   # Game mode selection
│       ├── quiz.py               # Main quiz interface
│       └── upload.py             # Content upload screen
├── backend_folder/        # Core backend logic and prompt utilities
│   ├── backend.py
│   └── prompt_utils.py
├── backend_testing/       # Example files, tests, transcripts, and PDFs
│   ├── test_conversation.py
│   ├── example_conv.json
│   ├── MachineLearning-Lecture01.pdf
│   └── ...
├── llm_tools/             # LLM integration layer
│   └── llm_framework.py
├── styles/                # Theming and styling
│   └── theme.kv
├── temporary_quiz_data/   # Temporary quiz storage
├── main.py                # App entry point
├── requirements.txt       # Python dependencies
├── setup.py              # Package setup configuration
├── style_guide.txt       # UI styling guidelines
└── README.md             # This file

---

Prerequisites

Before installing Iniquiz AI Lite, ensure you have:

• Python 3.8+ installed on your system
• pip package manager
• An active internet connection for LLM API calls
• API key from a supported LLM provider (OpenRouter or DeepSeek)

System Requirements

• Windows: Windows 10 or later
• macOS: macOS 10.14 or later
• Linux: Ubuntu 18.04+ or equivalent distributions
• RAM: Minimum 2GB available
• Storage: 500MB free space

---

Installation & Setup

Step 1: Clone the Repository

git clone https://github.com/yourusername/iniquiz-ai-lite.git
cd iniquiz-ai-lite

Step 2: Create Virtual Environment (Recommended)

Creating a virtual environment helps avoid dependency conflicts:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Note: If you encounter issues with Kivy installation, refer to the official Kivy installation guide for platform-specific instructions.

Step 4: Configure API Keys

1. Copy the environment template:

   cp .env.example .env

2. Edit the .env file with your preferred text editor and add your API keys:

   # OpenRouter API (recommended)
   OPENROUTER_API_KEY=your_openrouter_api_key_here
   
   # DeepSeek API (alternative)
   DEEPSEEK_API_KEY=your_deepseek_api_key_here
   
   # Optional: Set default model
   DEFAULT_MODEL=openai/gpt-4

Step 5: Verify Installation

Test that everything is working:

python -c "import kivy; import kivymd; print('Dependencies installed successfully!')"

---

Running the Application

Once installation and setup are complete, launch the application:

python main.py

The application window should open, and you'll see the main interface where you can:

1. Start a conversation with the AI
2. Upload documents for quiz generation
3. Generate quizzes from your conversations
4. Save and manage your quizzes

Troubleshooting Launch Issues

If the app fails to start:

1. Check Python version: python --version (should be 3.8+)
2. Verify virtual environment is activated (you should see (venv) in your terminal prompt)
3. Reinstall dependencies: pip install -r requirements.txt --force-reinstall
4. Check API keys: Ensure your .env file is properly configured

---

API Provider Setup

OpenRouter (Recommended)

1. Visit OpenRouter
2. Create an account and navigate to the API section
3. Generate an API key
4. Add credits to your account (pay-per-use model)
5. Add the key to your .env file

DeepSeek

1. Visit DeepSeek
2. Register for an account
3. Navigate to API settings
4. Generate an API key
5. Add the key to your .env file

---

Testing & Examples

The backend_testing/ directory contains comprehensive testing materials:

• example_conv.json – Sample conversation data
• MachineLearning-Lecture01.pdf – Example lecture material for quiz generation
• rawquiz.txt and examplequiz2.txt – Sample generated quizzes
• test_conversation.py – Backend testing script
• test_generate_functions.ipynb – Jupyter notebook with function tests

To run the backend tests:

cd backend_testing
python test_conversation.py

---

Contributors

• lcai000 – Lead Developer and Maintainer

---

License & Usage

Iniquiz AI Lite is proprietary software developed by lcai000. All rights reserved.

Usage Terms

• This software is provided for evaluation and personal use only
• Commercial use is prohibited without explicit written permission
• Redistribution of the source code or compiled application is not permitted
• Modification for personal use is allowed, but modified versions cannot be distributed
• The software is provided "as-is" without warranty of any kind

For licensing inquiries or commercial use requests, please contact the maintainer.

---

Support & Contributing

Getting Help

If you encounter issues:

1. Check the troubleshooting section above
2. Review the example files in backend_testing/
3. Create an issue on the GitHub repository with:
   • Your operating system
   • Python version
   • Error messages or screenshots
   • Steps to reproduce the problem

Contributing

While this is not an open-source project, bug reports and feature suggestions are welcome through GitHub issues.

---

Acknowledgments

• Kivy and KivyMD for the cross-platform UI framework
• OpenRouter and DeepSeek for LLM API access
• Python

---

Contact

For questions, suggestions, or licensing inquiries, please reach out through:

• GitHub Issues: Create an issue
• Project Maintainer: lcai000