bvi-looting 0.1.1
Клиент к боту для решения олимпиадных задач по информатике (сервер сохраняет код и пояснения в .txt, хранит контекст и историю)
License: MIT
Requires Python: >=3.10
Keywords: olympiad, programming, informatics, bot, client

# BVI Looting

Клиент и сервер бота для решения олимпиадных задач по информатике. Сервер разворачивается на удалённой машине; клиент устанавливается как библиотека (`pip install bvi-looting`) и отправляет задачи на сервер. Сервер сохраняет код и пояснения в `.txt` файлы и хранит контекст и историю запросов.

---

## Локальный запуск (тест на своём компьютере)

Чтобы проверить всё без удалённого сервера:

1. **Зависимости и .env**
   ```bash
   pip install -e ".[server]"
   ```
   Скопируйте `.env.example` в `.env` и укажите `BVI_PASSWORD` и при необходимости `GEMINI_API_KEY` (или `CUSTOM_LLM_URL`).

2. **Запуск сервера** (один терминал, из корня проекта):
   ```bash
   py run_server.py
   ```
   Сервер будет на http://127.0.0.1:8000

3. **Запуск примера клиента** (второй терминал, из корня проекта):
   ```bash
   py examples/local_demo.py
   ```
   Скрипт отправит тестовую задачу на локальный сервер и выведет код и пояснение. Решения сохраняются в папку `solutions/` в корне проекта, история — в `history.json`.

Для своих скриптов используйте:
```python
from bvi_looting import BviLootingClient
client = BviLootingClient(base_url="http://127.0.0.1:8000", password="ваш_пароль_из_env")
result = client.solve("Текст задачи...")
```

---

## Установка клиента (библиотека)

```bash
pip install bvi-looting
```

Или из исходников в корне репозитория:

```bash
pip install -e .
```

## Использование клиента

```python
from bvi_looting import BviLootingClient

# Укажите URL сервера и пароль (пароль задаётся в .env на сервере)
client = BviLootingClient(
    base_url="https://your-server.com",
    password="your_secret_password",
)

# Отправить задачу — сервер сохранит решение в .txt и обновит историю
result = client.solve(
    "Даны два целых числа a и b. Найти их сумму. Ввод: два числа через пробел."
)
print(result["code"])
print(result["explanation"])
print("Файл на сервере:", result["solution_file"])

# Та же сессия — контекст сохраняется для следующих запросов
result2 = client.solve("Теперь найди разность a - b.")

# Получить историю запросов по текущей сессии
history = client.get_history()
print(history)
```

Опционально можно задать свою сессию (например, для продолжения диалога с другого клиента):

```python
client = BviLootingClient(
    base_url="https://...",
    password="...",
    session_id="my-session-123",
)
```

## Развёртывание сервера

1. Клонируйте репозиторий на сервер и установите зависимости сервера:

```bash
pip install -e ".[server]"
```

Или вручную: `pip install fastapi uvicorn google-genai` (или задайте свой LLM через `CUSTOM_LLM_URL`).

2. Создайте файл `.env` в корне проекта (скопируйте из `.env.example`) и задайте пароль:

- **BVI_PASSWORD** (обязательно) — пароль для доступа к API. Клиент передаёт его в заголовке `Authorization: Bearer <пароль>`.
- **GEMINI_API_KEY** — ключ Google AI (Gemini). Или **CUSTOM_LLM_URL** — URL вашего API, принимающего `POST` с телом `{"text": "..."}` и возвращающего `{"response": "..."}`.
- **BVI_SOLUTIONS_DIR** (по умолчанию `solutions`) — каталог для `.txt` файлов с решениями.
- **BVI_HISTORY_FILE** (по умолчанию `history.json`) — файл истории запросов.

3. Запуск:

```bash
uvicorn server.main:app --host 0.0.0.0 --port 8000
```

После этого клиент должен указывать `base_url="http://your-server:8000"` (или с HTTPS, если настроен прокси).

## API сервера

Все запросы требуют заголовок **Authorization: Bearer \<пароль из .env\>**.

- **POST /solve** — тело: `{"task": "текст задачи", "session_id": "…", "lang": "python"}`. Ответ: `{"session_id", "code", "explanation", "solution_file"}`.
- **GET /history?session_id=…** — история запросов по сессии (или вся, если `session_id` не передан).
- **GET /health** — проверка доступности (тоже по паролю).
- **POST /generate** — совместимость: `{"text": "..."}` → `{"response": "..."}`.

## Формат сохранённых решений

В каталоге `BVI_SOLUTIONS_DIR` создаются файлы вида `{session_id}_{timestamp}.txt` с блоками: задача, код, пояснение, мета (session_id, время).