Metadata-Version: 2.4
Name: versus-llm
Version: 1.2.1
Summary: Two LLMs enter. One verdict leaves.
Author-email: Shah <gyro14888841@gmail.com>
Project-URL: Homepage, https://github.com/gyrroxx/versus-llm
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyfiglet>=0.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: textual>=0.60.0
Dynamic: license-file

# versus-llm

<p align="center">
  <img src="./assets/versus-llm.webp" alt="versus-llm" width="100%">
</p>

`versus` запускает спор двух LLM прямо в терминале. Один агент защищает идею, второй спорит с ним, потом судья дает короткий вердикт.

Обычно запускай без аргументов, чтобы открыть главное меню:

```bash
versus
```

В меню можно ввести вопрос, выбрать число раундов и добавить файл с контекстом.

## Установка

Нужен Python 3.10 или новее.

```bash
pip install versus-llm
```

Проверь, что команда установилась:

```bash
versus --version
```

Ожидаемый вывод:

```text
versus-llm 1.2.1
```

## Настройка OpenRouter

`versus` работает через OpenRouter, поэтому нужен свой API-ключ. Это не сложно: один раз создаешь ключ, вставляешь его в `versus setup`, дальше CLI сам его хранит.

### Как получить ключ

1. Открой страницу: <https://openrouter.ai/keys>
2. Войди в аккаунт OpenRouter.
3. Нажми кнопку создания ключа.
4. Скопируй ключ.

По сути, это делается в 2 клика: создать ключ и скопировать его. Вручную создавать `.env` не нужно.

### Как сохранить ключ в versus

```bash
versus setup
```

CLI спросит:

```text
Вставь API-ключ OpenRouter:
```

Вставь ключ и нажми Enter. Символы при вводе скрыты, но после сохранения `versus` покажет короткую маску ключа, например:

```text
API-ключ OpenRouter сохранен (sk-o...abcd): C:\Users\...\versus-llm\.env
```

Команда `versus login` делает то же самое:

```bash
versus login
```

Если ключ не настроен, `versus` напишет:

```text
API-ключ OpenRouter не настроен.

Запусти:
  versus setup
```

## Первый запуск

После настройки ключа лучше запускать `versus` без вопроса:

```bash
versus
```

Откроется главное меню. В нем можно ввести вопрос, указать файл с контекстом и выбрать число раундов. Это основной способ пользоваться приложением.

Что произойдет:

1. Агент A даст сильный аргумент.
2. Агент B разберет слабые места и возразит.
3. Раунды повторятся заданное число раз.
4. Судья прочитает спор и даст вердикт.

Если вопрос на русском, судья должен отвечать на русском.

## Основной запуск

### Открыть главное меню

```bash
versus
```

Главное меню удобнее прямого CLI-запуска: там можно управлять вопросом, файлом с контекстом и количеством раундов без длинной команды.

## Быстрый CLI-вариант

Если нужно запустить спор одной командой, можно сразу передать вопрос:

```bash
versus "Стоит ли учить Rust в 2026?"
```

### Указать число раундов из CLI

```bash
versus "React или Vue?" --rounds 3
```

По умолчанию используется 2 раунда.

### Добавить файл с контекстом из CLI

```bash
versus "Какая база лучше подходит под эту схему?" --file schema.sql
```

Файл должен быть не больше 200 КБ. Его текст добавляется к вопросу как контекст для обоих агентов.

### Сохранить спор в Markdown из CLI

```bash
versus "PostgreSQL или MongoDB?" --output debate.md
```

После завершения появится файл `debate.md` с вопросом, ответами агентов и вердиктом судьи.

### Выбрать модели вручную из CLI

```bash
versus "React или Vue?" --models openai/gpt-oss-120b:free nvidia/nemotron-3-super-120b-a12b:free google/gemma-4-31b-it:free
```

Порядок важен:

```text
--models MODEL_A MODEL_B [JUDGE_MODEL]
```

Первая модель отвечает за агента A, вторая за агента B, третья за судью. Если указать только две модели, судья использует модель по умолчанию.

## Главное меню

Это рекомендуемый режим после `versus setup`. Если запустить `versus` без вопроса, откроется полноэкранное меню:

```bash
versus
```

Там можно ввести вопрос, путь к файлу с контекстом и число раундов. Для обычного использования этого достаточно.

Горячие клавиши:

| Клавиша | Что делает |
| --- | --- |
| `S` | сохранить спор в `debate.md` |
| `r` | вернуться к новому вопросу |
| `q` | выйти |
| `Ctrl+C` | выйти после повторного нажатия |

## Параметры CLI

| Параметр | Что делает | По умолчанию |
| --- | --- | --- |
| `question` | вопрос для спора | открывает главное меню, если вопрос не указан |
| `--file` | путь к файлу с контекстом | нет |
| `--rounds` | число раундов | `2` |
| `--models` | две или три модели OpenRouter: агент A, агент B и опционально судья | `openai/gpt-oss-120b:free`, `nvidia/nemotron-3-super-120b-a12b:free`, `google/gemma-4-31b-it:free` |
| `--output` | путь для сохранения Markdown-файла | нет |
| `--version` | показать версию | `1.2.1` |

## Где хранится ключ

`versus setup` сохраняет ключ локально:

| Система | Путь |
| --- | --- |
| Windows | `%APPDATA%/versus-llm/.env` |
| macOS/Linux | `~/.config/versus-llm/.env` |

Также работают старые способы:

```bash
OPENROUTER_API_KEY=your_key_here
```

и файл `.env` в текущей папке.

Приоритет такой:

1. Переменная окружения `OPENROUTER_API_KEY`.
2. `.env` в текущей папке.
3. Конфиг, созданный через `versus setup`.

## Если бесплатная модель не отвечает

Бесплатные модели OpenRouter иногда возвращают `429`: провайдер временно ограничил запросы. `versus` сам делает повторные попытки, но иногда нужно подождать и запустить команду еще раз.

Если проблема повторяется:

```bash
versus "твой вопрос" --models openai/gpt-oss-120b:free nvidia/nemotron-3-super-120b-a12b:free google/gemma-4-31b-it:free
```

Можно выбрать другие модели OpenRouter через `--models`.

## Локальная разработка

Если ты клонировал репозиторий:

```bash
pip install -e .
```

Проверки:

```bash
python -m py_compile versus.py
python -m unittest discover tests
versus --version
```

## Лицензия

MIT.
