Metadata-Version: 2.4
Name: emberio-labs-ember-agent
Version: 0.2.0
Summary: Готовый к запуску агент на базе ember: настройка в TOML, запуск одной командой.
License-Expression: MIT
License-File: LICENSE
Keywords: agent,llm,ai,cli,ember,mcp
Author: Emberio Labs
Author-email: dev@emberio.labs
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: emberio-labs-ember[mcp,openai] (>=0.3.0,<1.0)
Requires-Dist: rich (>=13.0.0,<16.0.0)
Description-Content-Type: text/markdown

# ember-agent

Готовый к запуску агент на базе [`ember`](https://github.com/emberio-labs/ember):
настройка в TOML — запуск одной командой.

- **CLI-команда:** `ember-agent` (короткая, удобная в терминале)
- **На PyPI пакет публикуется как:** `emberio-labs-ember-agent`

```text
$ ember-agent --version
ember-agent 0.2.0
```

## Возможности

- Конфигурация в одном TOML-файле: системный промпт, провайдер LLM (ключ, модель, base_url), MCP-инструменты.
- Интерактивный диалог в терминале или разовый запрос (`--message`) для скриптов.
- Красивый вывод в интерактиве: баннер приветствия в рамке (версия, провайдер,
  модель, инструменты), диалог в виде чата (подпись `🤖 ember-agent`,
  приглашение «Ваш ответ: »), markdown-рендер ответов, потоковая печать (где
  доступна), команды сессии `/help` и `/reset`, показ процесса вызова
  инструментов (`🔧`/`✔`/`✖`), Ctrl+C отменяет ответ.
- Провайдеры: `mock` (без сети и ключей, для экспериментов и тестов) и `openai`
  (OpenAI и любые OpenAI-совместимые API: OpenRouter, Groq, vLLM, LM Studio и т.п.).
- Модель задаётся провайдеру (`[provider] model`) — как часть «подключения к LLM».
- Инструменты по [MCP](https://modelcontextprotocol.io): `stdio`-процессы и streamable HTTP-серверы.
- Работает на Python 3.12+.

## Установка

Из PyPI:

```bash
pip install emberio-labs-ember-agent
```

Из исходников (Poetry):

```bash
git clone https://github.com/emberio-labs/ember-agent.git
cd ember-agent
poetry install
```

## Настройка

Скопируйте пример конфигурации и отредактируйте под себя:

```bash
cp config.example.toml config.toml
```

Все секции конфигурации опциональны: пустой файл создаст агента на `MockProvider`,
который работает без сети и API-ключей.

```toml
[agent]
system_prompt = "Ты полезный и краткий помощник."   # как агент себя ведёт

[provider]
type = "mock"                  # "mock" | "openai"
model = "gpt-4o-mini"          # модель подключения LLM (для type = "openai")
api_key_env = "OPENAI_API_KEY" # откуда брать ключ (для type = "openai")

[[mcp.servers]]                       # внешние инструменты (опционально)
transport = "stdio"                   # "stdio" | "http"
command = "python"
args = ["path/to/server.py"]
```

Полный пример с комментариями — в [`config.example.toml`](config.example.toml).
Для реального провайдера задайте переменную окружения с ключом, например `OPENAI_API_KEY`.
Если модель не указана, провайдер берёт свою по умолчанию (`gpt-4o-mini` у OpenAI).

## Запуск

Интерактивный диалог:

```bash
ember-agent run
```

В начале сессии печатается баннер в рамке: версия, провайдер, модель
и подключённые инструменты. Дальше идёт диалог в виде чата: ответы агента
помечены подписью `🤖 ember-agent`, свой ввод начинается по приглашению
«Ваш ответ: ». Внутри диалога доступны команды:

- `/help` — справка по командам;
- `/reset` — начать новый диалог (сбросить историю);
- выход: `exit`, `quit`, `выход`, Ctrl+D, или Ctrl+C дважды.

Ответы рендерятся как markdown (заголовки, списки, код-блоки); там, где потоковая
печать доступна (агент без инструментов), текст появляется по мере генерации.
При вызове инструментов виден процесс: `🔧 имя(аргументы)` и результат `✔` / ошибка `✖`.
Ctrl+C прерывает текущий ответ, не завершая сессию.

Разовый запрос — без диалога, удобно для скриптов:

```bash
ember-agent run -m "Привет! Коротко: кто ты?"
```

Явно указать файл конфигурации:

```bash
ember-agent run -c path/to/config.toml
```

Альтернативный запуск через Python (без установки в окружение):

```bash
python -m ember_agent run -m "Привет"
```

## Разработка

```bash
poetry install                      # установка зависимостей (включая dev)
poetry run pytest                   # тесты
poetry run ruff check ember_agent tests   # линтер
poetry run mypy                     # статическая типизация
```

Код в `ember_agent/`, тесты — в `tests/`. Формат конфигурации описан в
[`config.example.toml`](config.example.toml).

## Релиз

Публикация новой версии на PyPI автоматизирована через GitHub Actions
(workflow `.github/workflows/publish.yml`):

1. Поднимите версию в `pyproject.toml` (`version = "0.2.0"`) и закоммитьте
   изменение, например: `chore: bump version to 0.2.0`.
2. Создайте и запушьте git-тег, совпадающий с версией:

   ```bash
   git tag v0.2.0
   git push origin v0.2.0
   ```

3. Workflow соберёт wheel и sdist (`poetry build`) и опубликует их на PyPI.
   Ветка `main` при этом не нужна — достаточно тега.

Публикация использует Trusted Publishing (OIDC): секреты в GitHub не хранятся.
Для этого владельцу нужно один раз настроить publisher на PyPI
(и, опционально, на TestPyPI для проверок):

- **PyPI:** https://pypi.org/manage/account/publishing/
- **TestPyPI:** https://test.pypi.org/manage/account/publishing/

Поля формы одинаковы для PyPI и TestPyPI:

| Поле | Значение |
|---|---|
| Project name | `emberio-labs-ember-agent` |
| GitHub owner | `emberio-labs` |
| GitHub repository | `ember-agent` |
| Workflow name | `publish.yml` |
| Environment | *(пусто)* |

После настройки публикацию можно проверить вручную на TestPyPI:
GitHub → Actions → Publish → Run workflow. На боевой PyPI пакет уходит
только по git-тегу `v*`.

## Лицензия

MIT — см. [LICENSE](LICENSE).

