Metadata-Version: 2.4
Name: MentAI-CLI
Version: 0.1.6
Summary: An automated CLI tool using AI to solve Menti quiz questions.
Author: Peter Schwips
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education :: Testing
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fake-useragent>=2.2.0
Requires-Dist: openai>=1.102.0
Requires-Dist: platformdirs>=4.4.0
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=14.1.0
Requires-Dist: toml>=0.10.2
Requires-Dist: typer>=0.17.4
Requires-Dist: websocket-client>=1.8.0
Dynamic: license-file

![Ruff](https://img.shields.io/badge/Ruff-checked-success?logo=ruff&logoColor=white)
![Pyright](https://img.shields.io/badge/Pyright-checked-success?logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pgo8IURPQ1RZUEUgc3ZnIFBVQkxJQyAiLS8vVzNDLy9EVEQgU1ZHIDIwMDEwOTA0Ly9FTiIKICJodHRwOi8vd3d3LnczLm9yZy9UUi8yMDAxL1JFQy1TVkctMjAwMTA5MDQvRFREL3N2ZzEwLmR0ZCI+CjxzdmcgdmVyc2lvbj0iMS4wIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciCiB3aWR0aD0iNjAwLjAwMDAwMHB0IiBoZWlnaHQ9IjYwMC4wMDAwMDBwdCIgdmlld0JveD0iMCAwIDYwMC4wMDAwMDAgNjAwLjAwMDAwMCIKIHByZXNlcnZlQXNwZWN0UmF0aW89InhNaWRZTWlkIG1lZXQiPgoKPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMC4wMDAwMDAsNjAwLjAwMDAwMCkgc2NhbGUoMC4xMDAwMDAsLTAuMTAwMDAwKSIKZmlsbD0iI2ZmZmZmZmZmIiBzdHJva2U9Im5vbmUiPgo8cGF0aCBkPSJNMjY0NyA1NjM4IGMtMzMyIC0zNDQgLTk2NiAtMTAyNSAtMTEyMSAtMTIwMyAtMTUyIC0xNzUgLTE3OCAtMjIxCi0yMDYgLTM2OCBsLTEyIC01OCAtMzYxIC0xNzkgYy0zODMgLTE5MCAtNDcwIC0yNDEgLTQ3NSAtMjc3IC00IC0yNSAxMDAgLTQzNQozNTcgLTE0MTAgbDE4MCAtNjgzIDI5MiAtMzc3IGMxNjEgLTIwOCAzMzggLTQzNiAzOTMgLTUwOCAxNTMgLTE5OSAyMjQgLTI4MgoyNjAgLTMwNSBsMzQgLTIwIDEwOCAzOSBjMTI0IDQ0IDU0OCAyMDUgMTI4OSA0ODggbDUxMCAxOTUgMzEwIC00MSBjNDg1IC02NAo1NjQgLTcyIDY1NCAtNjkgbDgzIDMgMTE3IDIzMCBjNjQgMTI3IDE2OSAzMjcgMjMzIDQ0NSBsMTE2IDIxNSAyNiA1MDAgYzQwCjc1MiA3NSAxMzM3IDg3IDE0NTggNiA1OSA5IDExMSA1IDExNCAtMyAzIC03NCAyMSAtMTU4IDQwIC04NCAxOSAtMTU2IDM3Ci0xNTkgNDEgLTMgNCAtNjMgMTc2IC0xMzMgMzgyIGwtMTI3IDM3NSAtOTM3IDQ3MyBjLTUxNSAyNjAgLTEwMDcgNTA2IC0xMDkyCjU0OCBsLTE1NSA3NiAtMTE4IC0xMjR6IG0xMjEgLTk1IGMzMiAtMTM2IDc0IC0zNDkgMTY3IC04MzggbDg1IC00NTAgLTUyIC01MApjLTI5IC0yNyAtMTU2IC0xNDggLTI4MiAtMjY4IC0xMjYgLTExOSAtMjQwIC0yMjAgLTI1MyAtMjIzIC01NyAtMTUgLTY0IDQKLTk4IDI4NiAtMjcgMjE2IC0zOSAyOTQgLTU3IDM3NCAtMTAgNDcgLTExIDQ4IC00MyA0MyAtNDcgLTggLTIyNCAtNzggLTQyNQotMTcwIC0yMTAgLTk1IC00MDcgLTE3NyAtNDI2IC0xNzcgLTE3IDAgLTE4IDQwIC00IDkwIDE2IDU5IDIxNCAyOTQgNjE0IDczMAoyMjQgMjQ0IDcxOSA3NDAgNzM4IDc0MCAxMiAwIDIxIC0yMiAzNiAtODd6IG0tNTQ5IC0xMjA2IGMxOCAtMjIgMzkgLTEzMiA2NgotMzUxIDM2IC0yODggNTMgLTM1NSAxMDQgLTQwMSAzNiAtMzEgODMgLTIzIDI2MyA0OSAxNjIgNjQgMjI4IDgzIDcwMyAyMDUKMzIxIDgyIDI4OCA4MSAzMTggMTMgMzkgLTg3IDExOCAtMjg4IDIzMSAtNTg3IDE0NCAtMzc4IDE2OSAtNDUyIDE2MiAtNDcwCi0xMyAtMzYgLTUxMiAtMjU2IC0xNTkxIC03MDMgLTEwMjUgLTQyNSAtMTQzMCAtNTkxIC0xNDMyIC01ODggLTYgNiAtMzc4CjE0MjQgLTQzMyAxNjUxIC03NCAzMDUgLTk2IDQxMyAtODQgNDI1IDI4IDI4IDE2MzUgNzY5IDE2NzAgNzcwIDYgMCAxNiAtNiAyMwotMTN6IG0yOTI3IC00NjcgYzE0NiAtMzIgMTgyIC00MSAyNTEgLTY2IDM5IC0xNCA0MiAtMTcgMzIgLTM3IC00NCAtODYgLTMwMQotNDg5IC0zMzEgLTUxOSAtNzUgLTc1IC0xMTUgLTc1IC03MjMgMTAgbC00MTAgNTcgLTQ4IDk1IGMtMjYgNTIgLTQ5IDEwOCAtNTAKMTI0IC0yIDI5IDAgMzAgMTAzIDY0IDgzIDI3IDEwMDggMjk3IDEwMzEgMzAxIDMgMSA2OCAtMTMgMTQ1IC0yOXoiLz4KPC9nPgo8L3N2Zz4K)
![Python Versions](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12%20|%203.13-blue?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-blue?logo=open-source-initiative&logoColor=white)

# Ment**AI**

An automated CLI tool using AI to solve [Mentimeter](https://www.menti.com/) ("Menti") quiz questions.

### Table of Contents

<ul style="padding: 0; padding-left:1em; margin: 0;">
<li >Getting Started</li>
    <ul style=" padding-left: 2em; margin-bottom: 0">
        <li><a href="#installation">Installation</a></li>
        <li><a href="#usage">Usage</a></li>
    </ul>
<li>Functionality</li>
    <ul style=" padding-left: 2em; margin-bottom: 0">
        <li><a href="#what-this-tool-can-do">What this tool <b>can</b> do</a></li>
        <li><a href="#what-this-tool-can't-do">What this tool <b>can't</b> do</a></li>
    </ul>
<li>Use Cases</li>
    <ul style=" padding-left: 2em; margin-bottom: 0">
        <li><a href="#when-to-use-this-tool">When to use this tool</a></li>
    </ul>
<li>Other</li>
    <ul style=" padding-left: 2em; margin-bottom: 0">
        <li><a href="#disclaimer">Disclaimer</a></li>
    </ul>
</ul>

## Installation

```bash
pip3 install mentai-cli
```

## Usage

### First Steps

After installing MentAI you need to run it once to create the config file. You can just provide a random 8-digit number:

```console
➜ mentai 12345678
OpenAI API key is missing.
Please fix the error and restart the program.
You can find your settings file in: "/Users/<YourUser>/Library/Application Support/Mentai/config.toml". 
Opening it...
```

The `config.toml` will be opened in your default editor. Add an OpenAI API key and save it. All other values can be left as is. Here is a quick example of a config.toml:

```toml
[SOLVER]
OPEN_AI_API_KEY = "youropenapikeyhere"
OPEN_AI_MODEL = "gpt-5"

[QUIZ]
PLAYER_NAME = "MentiBot"
MINIMUM_DELAY_IN_MS = 500
MAXIMUM_DELAY_IN_MS = 3000
CONTEXT = "/Path/To/TextFile.txt"
```

- SOLVER:
  - OPEN_AI_API_KEY: your OpenAI API key
  - OPEN_AI_MODEL: OpenAI model to use (you can find all models [here](https://platform.openai.com/docs/models))
- QUIZ:
  - PLAYER_NAME: name to use if custom names are allowed (leave empty if you always want to use a random generated username)
  - MINIMUM_DELAY_IN_MS: shortest time to wait before submitting an answer
  - MAXIMUM_DELAY_IN_MS: longest time to wait before submitting an answer
  - CONTEXT: path to a plain text file with additional context to use when solving the quiz questions

> DELAYS: This setup would generate a random delay from 500 to 3000 milliseconds for each answer submission.

### Solving Quizzes

You can call `mentai --help` for an overview of all possible options:

```console
➜ mentai --help
                                                                   
 Usage: mentai [OPTIONS] Participation Details                     
                                                                   
 An automated CLI tool using AI to solve Menti quiz questions.     
                                                                   
╭─ Arguments ─────────────────────────────────────────────────────╮
│ *    participation_d…      Participation      Participation     │
│                            Details            code / link of    │
│                                               the Menti quiz.   │
│                                               [required]        │
╰─────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────╮
│ --name             -n      Name               Name to use for   │
│                                               the player if     │
│                                               custom names are  │
│                                               allowed.          │
│ --additional-con…  -a      Addtional Context  Path to a text    │
│                                               file containing   │
│                                               additional        │
│                                               context to add to │
│                                               the prompt for    │
│                                               solving           │
│                                               questions.        │
│ --help                                        Show this message │
│                                               and exit.         │
╰─────────────────────────────────────────────────────────────────╯
```

The default usage is `mentai 12345678` with `12345678` being the participation code. You can also use the participation link to join a quiz: `https://www.menti.com/abcdefghijkl`.<br>
All other flags can be configured using the `config.toml`. However, the command-line flags will take priority. This means if you have the name `MentAI` set in your `config.toml` but run `mentai 12345678 -n John`, you will join the Menti quiz as `John`.

## What this tool can do

This tool can handle all slides for "Quiz competitions", which are "Select Answer" (single choice) and "Type Answer" (free text question).
Please note that "Select Answer" questions can have multiple correct answers. However, the participant can only pick one.

## What this tool can't do

This tool **cannot** handle any slides on Menti that are not of the category "Quiz competitions". This includes slides such as "Word Cloud", "Guess the Number" and "Multiple Choice", which do not give players a score either.<br>
This tool does not guarantee you a perfect score.<br><br>

![Slide Types](https://raw.githubusercontent.com/peterschwps/MentAI/main/docs/images/SlideTypes.png)

## When to use this tool

This tool can only be used for Menti presentations that use "Quiz competitions" slides.<br>
As a student/participant, you can use it to automatically solve quizzes.<br>
As a teacher/presenter, you can use it to prepare the quiz to be unsolvable for AI.<br>
Please make sure to use this tool in a fair manner.

## Disclaimer

MentAI is in no way affiliated with, authorized, maintained, or endorsed by Menti or any of its affiliates or subsidiaries. It is an independent and unofficial project. Use it at your own risk.
