Metadata-Version: 2.4
Name: gorilla-test-assistant
Version: 0.1.0
Summary: Screenshot-based multiple-choice assistant for macOS.
Project-URL: Homepage, https://github.com/Fakamoto/gorilla_test
Project-URL: Repository, https://github.com/Fakamoto/gorilla_test
Requires-Python: <3.12,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: dspy>=3.2.1
Requires-Dist: pillow>=10.4.0
Requires-Dist: pydantic>=2.9.2
Requires-Dist: pync>=2.0.3
Requires-Dist: pynput>=1.7.7
Requires-Dist: typer>=0.21.0

# Gorilla Test Assistant

Small macOS CLI that listens for a left Alt keypress, captures the current
screen, and asks a multimodal DSPy program to answer the visible multiple-choice
question.

For background on why this project exists, read the included article:
[Pass any TestGorilla Assessment](https://github.com/Fakamoto/gorilla_test/blob/main/blog.md).

## Install From PyPI

The package name is `gorilla-test-assistant` and it installs the `gorilla-test`
command.

With `uv`:

```bash
uv tool install --python 3.11.6 gorilla-test-assistant
```

With `pip`:

```bash
python3.11 -m pip install gorilla-test-assistant
```

This project supports Python `>=3.11,<3.12` because the keyboard listener stack
is known to be safest on Python 3.11.

## API Keys

The default model is `openai/gpt-5.4-mini`, so the default setup is:

```bash
export OPENAI_API_KEY="your-api-key"
```

The CLI accepts an LLM model name in LiteLLM format through `--model`. Provider
prefixes like `openai/`, `anthropic/`, and `groq/` are passed through as-is. If
you use an unprefixed model name, the CLI does not rewrite it or assume a
provider.

For common provider-prefixed models, set the standard provider environment
variable:

| Provider prefix | Environment variable |
| --- | --- |
| `openai/` | `OPENAI_API_KEY` |
| `anthropic/` | `ANTHROPIC_API_KEY` |
| `gemini/` or `google/` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
| `groq/` | `GROQ_API_KEY` |
| `mistral/` | `MISTRAL_API_KEY` |
| `openrouter/` | `OPENROUTER_API_KEY` |
| `together/` | `TOGETHER_API_KEY` |
| `xai/` | `XAI_API_KEY` |

For another provider, point the CLI at the variable name:

```bash
gorilla-test --model provider/model-name --api-key-env PROVIDER_API_KEY
```

For unprefixed model names, use the environment variables expected by LiteLLM
for that model.

## Usage

Start the listener:

```bash
gorilla-test
```

When a multiple-choice question is visible, press the left Alt key. The CLI
prints the structured answer and sends a macOS notification with the selected
option number.

On a Mac keyboard, the left Alt key is the left `option` / `alt` key:

![Mac keyboard with the left option alt key circled](https://raw.githubusercontent.com/Fakamoto/gorilla_test/main/assets/left-alt-key.png)

Image adapted from
[MacBook option key.JPG](https://commons.wikimedia.org/wiki/File:MacBook_option_key.JPG)
by Gerolsteiner91, licensed under
[CC BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/). Modified with
a red circle around the left `option` / `alt` key.

Choose a different model:

```bash
gorilla-test --model openai/gpt-5.4
```

Change the output token budget:

```bash
gorilla-test --max-tokens 8192
```

Show all options:

```bash
gorilla-test --help
```

## Local Development

Run the CLI from this checkout without installing it globally:

```bash
uv run --python 3.11.6 --with . gorilla-test --help
```

Install the current checkout as a global `uv` tool while developing:

```bash
uv tool install --python 3.11.6 --force .
```

Run the tests:

```bash
uv run --python 3.11.6 --with . python -m unittest -v
```

Build the package:

```bash
uv build
```

## Notes

- The tool is designed for macOS.
- macOS may require Accessibility and Screen Recording permissions for the
  terminal app running the CLI.
- DSPy uses `ChainOfThought`, so reasoning is produced by the program instead of
  being modeled as a manual Pydantic output field.
- Reasoning effort defaults to `high`.
- The default max token budget is `8192`.

## Disclaimer

This project highlights the need for better assessment methods in tech hiring.
Use it responsibly and respect the terms of service for any platform involved.
