emberio-labs-ember-agent 0.1.0__tar.gz

emberio_labs_ember_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 emberio-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emberio_labs_ember_agent-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: emberio-labs-ember-agent
+Version: 0.1.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)
+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.1.0
+```
+
+## Возможности
+
+- Конфигурация в одном TOML-файле: системный промпт, провайдер LLM (ключ, модель, base_url), MCP-инструменты.
+- Интерактивный диалог в терминале или разовый запрос (`--message`) для скриптов.
+- Провайдеры: `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).
+
+## Запуск
+
+Интерактивный диалог (выход: `exit`, `quit`, `выход` или Ctrl+D/Ctrl+C):
+
+```bash
+ember-agent run
+```
+
+Разовый запрос — без диалога, удобно для скриптов:
+
+```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.1.0"`) и закоммитьте
+   изменение, например: `chore: bump version to 0.1.0`.
+2. Создайте и запушьте git-тег, совпадающий с версией:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.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).
+

emberio_labs_ember_agent-0.1.0/README.md

@@ -0,0 +1,148 @@
+# 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.1.0
+```
+
+## Возможности
+
+- Конфигурация в одном TOML-файле: системный промпт, провайдер LLM (ключ, модель, base_url), MCP-инструменты.
+- Интерактивный диалог в терминале или разовый запрос (`--message`) для скриптов.
+- Провайдеры: `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).
+
+## Запуск
+
+Интерактивный диалог (выход: `exit`, `quit`, `выход` или Ctrl+D/Ctrl+C):
+
+```bash
+ember-agent run
+```
+
+Разовый запрос — без диалога, удобно для скриптов:
+
+```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.1.0"`) и закоммитьте
+   изменение, например: `chore: bump version to 0.1.0`.
+2. Создайте и запушьте git-тег, совпадающий с версией:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.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).

emberio_labs_ember_agent-0.1.0/ember_agent/__init__.py

@@ -0,0 +1,18 @@
+"""emberio-labs-ember-agent — настраиваемый агент на базе ``ember`` (emberio-labs-ember).
+
+Пакет даёт:
+- CLI ``ember-agent run`` (команда короткая) с интерактивным диалогом или разовым запросом;
+- загрузку конфигурации агента из TOML-файла;
+- сборку провайдера и MCP-инструментов в готового агента.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("emberio-labs-ember-agent")
+except PackageNotFoundError:  # пакет не установлен (запуск из исходников)
+    __version__ = "0.1.0"

emberio_labs_ember_agent-0.1.0/ember_agent/__main__.py

@@ -0,0 +1,8 @@
+"""Поддержка запуска как ``python -m ember_agent``."""
+
+from __future__ import annotations
+
+from ember_agent.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

emberio_labs_ember_agent-0.1.0/ember_agent/cli.py

@@ -0,0 +1,103 @@
+"""Командная строка ember-agent.
+
+Команда ``run`` читает TOML-конфигурацию и запускает агента:
+в интерактивном диалоге (по умолчанию) или с разовым запросом ``--message``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from ember_agent import __version__
+from ember_agent.config import DEFAULT_CONFIG_FILE, ConfigError, load_config
+from ember_agent.factory import build_agent
+
+_QUIT_COMMANDS = frozenset({"exit", "quit", "выход"})
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ember-agent",
+        description=(
+            "Готовый к запуску агент на базе ember: настройка в TOML, запуск одной командой."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    run = subparsers.add_parser("run", help="запустить агента из конфигурации")
+    run.add_argument(
+        "-c",
+        "--config",
+        default=DEFAULT_CONFIG_FILE,
+        help=f"путь к TOML-конфигурации (по умолчанию: {DEFAULT_CONFIG_FILE})",
+    )
+    run.add_argument(
+        "-m",
+        "--message",
+        help="разовый запрос без интерактивного диалога",
+    )
+    return parser
+
+
+def _print_error(message: str) -> None:
+    print(f"ошибка: {message}", file=sys.stderr)
+
+
+def _run_repl(agent: Any) -> int:
+    """Интерактивный диалог с агентом."""
+    print("Диалог с агентом. Выход: 'exit', 'quit', 'выход' или Ctrl+D/Ctrl+C.")
+    while True:
+        try:
+            line = input("\nвы: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if line.lower() in _QUIT_COMMANDS:
+            return 0
+        if not line:
+            continue
+        try:
+            print(f"агент: {agent.run(line)}")
+        except Exception as exc:  # показываем ошибку и продолжаем диалог
+            _print_error(str(exc))
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    try:
+        config = load_config(Path(args.config))
+    except ConfigError as exc:
+        _print_error(str(exc))
+        return 2
+
+    try:
+        with build_agent(config) as agent:
+            if args.message:
+                print(agent.run(args.message))
+                return 0
+            return _run_repl(agent)
+    except ConfigError as exc:
+        _print_error(str(exc))
+        return 2
+    except Exception as exc:
+        _print_error(str(exc))
+        return 1
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    try:
+        if args.command == "run":
+            return _cmd_run(args)
+    except KeyboardInterrupt:
+        return 130
+    return 0  # недостижимо: subparser обязателен

emberio_labs_ember_agent-0.1.0/ember_agent/config.py

@@ -0,0 +1,185 @@
+"""Чтение и валидация TOML-конфигурации агента.
+
+Формат конфигурации описан в ``config.example.toml`` в корне проекта.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+#: Имя файла конфигурации, который CLI ищет по умолчанию.
+DEFAULT_CONFIG_FILE = "config.toml"
+
+#: Промпт, используемый, если в конфигурации ничего не задано.
+DEFAULT_SYSTEM_PROMPT = "Ты полезный и краткий помощник."
+
+PROVIDER_MOCK = "mock"
+PROVIDER_OPENAI = "openai"
+VALID_PROVIDERS: frozenset[str] = frozenset({PROVIDER_MOCK, PROVIDER_OPENAI})
+
+TRANSPORT_STDIO = "stdio"
+TRANSPORT_HTTP = "http"
+VALID_TRANSPORTS: frozenset[str] = frozenset({TRANSPORT_STDIO, TRANSPORT_HTTP})
+
+
+class ConfigError(ValueError):
+    """Ошибка конфигурации агента (файл, TOML-синтаксис, значения)."""
+
+
+def _require_str(data: dict[str, Any], key: str, default: str) -> str:
+    value = data.get(key, default)
+    if not isinstance(value, str):
+        raise ConfigError(f"Поле '{key}' должно быть строкой, получено {type(value).__name__}")
+    return value
+
+
+def _optional_str(data: dict[str, Any], key: str) -> str | None:
+    value = data.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ConfigError(f"Поле '{key}' должно быть строкой, получено {type(value).__name__}")
+    return value
+
+
+def _str_list(data: dict[str, Any], key: str) -> list[str]:
+    value = data.get(key)
+    if value is None:
+        return []
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ConfigError(f"Поле '{key}' должно быть списком строк")
+    return list(value)
+
+
+def _str_dict(data: dict[str, Any], key: str) -> dict[str, str]:
+    value = data.get(key)
+    if value is None:
+        return {}
+    if not isinstance(value, dict) or not all(
+        isinstance(k, str) and isinstance(v, str) for k, v in value.items()
+    ):
+        raise ConfigError(f"Поле '{key}' должно быть таблицей строк ({{key = 'value'}})")
+    return {str(k): str(v) for k, v in value.items()}
+
+
+@dataclass
+class MCPServerConfig:
+    """Описание одного MCP-сервера (stdio-процесс или HTTP-endpoint)."""
+
+    transport: str = TRANSPORT_STDIO
+    #: Для transport = "stdio"
+    command: str | None = None
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    #: Для transport = "http"
+    url: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ProviderConfig:
+    """Настройки LLM-провайдера: как и через какую модель агент ходит к LLM."""
+
+    type: str = PROVIDER_MOCK
+    #: Модель подключения LLM. Если не задана, провайдер берёт свою модель
+    #: по умолчанию (например, "gpt-4o-mini" у OpenAI).
+    model: str | None = None
+    #: Переменная окружения с API-ключом (для type = "openai").
+    api_key_env: str = "OPENAI_API_KEY"
+    #: Полный base_url OpenAI-совместимого API (опционально).
+    base_url: str | None = None
+
+
+@dataclass
+class AgentConfig:
+    """Полная конфигурация агента после чтения TOML-файла."""
+
+    system_prompt: str = DEFAULT_SYSTEM_PROMPT
+    provider: ProviderConfig = field(default_factory=ProviderConfig)
+    mcp_servers: list[MCPServerConfig] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentConfig:
+        agent_section = data.get("agent", {})
+        if not isinstance(agent_section, dict):
+            raise ConfigError("Секция '[agent]' должна быть таблицей")
+
+        provider_section = data.get("provider", {})
+        if not isinstance(provider_section, dict):
+            raise ConfigError("Секция '[provider]' должна быть таблицей")
+
+        return cls(
+            system_prompt=_require_str(agent_section, "system_prompt", DEFAULT_SYSTEM_PROMPT),
+            provider=_parse_provider(provider_section),
+            mcp_servers=_parse_mcp_servers(data.get("mcp")),
+        )
+
+
+def _parse_provider(data: dict[str, Any]) -> ProviderConfig:
+    provider_type = _require_str(data, "type", PROVIDER_MOCK)
+    if provider_type not in VALID_PROVIDERS:
+        valid = ", ".join(sorted(VALID_PROVIDERS))
+        message = f"Неизвестный тип провайдера {provider_type!r}; ожидается одно из: {valid}"
+        raise ConfigError(message)
+
+    return ProviderConfig(
+        type=provider_type,
+        model=_optional_str(data, "model"),
+        api_key_env=_require_str(data, "api_key_env", "OPENAI_API_KEY"),
+        base_url=_optional_str(data, "base_url"),
+    )
+
+
+def _parse_mcp_servers(raw: Any) -> list[MCPServerConfig]:
+    if raw is None:
+        return []
+    if not isinstance(raw, dict):
+        raise ConfigError("Секция '[mcp]' должна быть таблицей")
+
+    servers_raw = raw.get("servers", [])
+    if not isinstance(servers_raw, list):
+        raise ConfigError("Поле '[mcp].servers' должно быть списком таблиц ([[mcp.servers]])")
+
+    servers: list[MCPServerConfig] = []
+    for index, item in enumerate(servers_raw, start=1):
+        if not isinstance(item, dict):
+            raise ConfigError(f"MCP-сервер #{index} должен быть таблицей")
+        transport = _require_str(item, "transport", TRANSPORT_STDIO)
+        if transport not in VALID_TRANSPORTS:
+            valid = ", ".join(sorted(VALID_TRANSPORTS))
+            raise ConfigError(
+                f"MCP-сервер #{index}: неизвестный transport {transport!r}; ожидается: {valid}"
+            )
+        servers.append(
+            MCPServerConfig(
+                transport=transport,
+                command=_optional_str(item, "command"),
+                args=_str_list(item, "args"),
+                env=_str_dict(item, "env"),
+                url=_optional_str(item, "url"),
+                headers=_str_dict(item, "headers"),
+            )
+        )
+    return servers
+
+
+def load_config(path: str | Path) -> AgentConfig:
+    """Читает TOML-файл и возвращает валидированную конфигурацию агента.
+
+    Raises:
+        ConfigError: файл не найден, некорректный TOML или неверные значения.
+    """
+    config_path = Path(path)
+    if not config_path.is_file():
+        raise ConfigError(f"Файл конфигурации не найден: {config_path}")
+
+    with config_path.open("rb") as handle:
+        try:
+            data = tomllib.load(handle)
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigError(f"Некорректный TOML в {config_path}: {exc}") from exc
+
+    return AgentConfig.from_dict(data)

emberio_labs_ember_agent-0.1.0/ember_agent/factory.py

@@ -0,0 +1,98 @@
+"""Сборка агента ``ember`` из конфигурации ``ember_agent``.
+
+Фабрика скрывает детали библиотеки ``ember``: провайдеров, MCP-клиенты
+и передачу параметров в ``Agent``.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import ExitStack, contextmanager
+from typing import Any
+
+from ember import Agent, MCPClient, MockProvider, OpenAIProvider
+
+from ember_agent.config import (
+    PROVIDER_MOCK,
+    PROVIDER_OPENAI,
+    TRANSPORT_HTTP,
+    TRANSPORT_STDIO,
+    AgentConfig,
+    ConfigError,
+    MCPServerConfig,
+    ProviderConfig,
+)
+
+
+def build_provider(config: ProviderConfig) -> MockProvider | OpenAIProvider:
+    """Создаёт провайдера ``ember`` по конфигурации.
+
+    Модель задаётся провайдеру: в ``ember`` именно провайдер подставляет
+    свою модель по умолчанию, когда агент её не переопределил.
+    """
+    if config.type == PROVIDER_MOCK:
+        return MockProvider()
+
+    if config.type == PROVIDER_OPENAI:
+        api_key = os.environ.get(config.api_key_env)
+        if not api_key:
+            raise ConfigError(
+                f"Для провайдера 'openai' задайте переменную окружения "
+                f"{config.api_key_env!r} (или укажите другую в [provider].api_key_env)"
+            )
+        kwargs: dict[str, str] = {}
+        if config.model:
+            kwargs["model"] = config.model
+        if config.base_url:
+            kwargs["base_url"] = config.base_url
+        return OpenAIProvider(api_key=api_key, **kwargs)
+
+    raise ConfigError(f"Неизвестный тип провайдера: {config.type!r}")  # не должно достигаться
+
+
+def _open_mcp_client(config: MCPServerConfig) -> MCPClient:
+    """Создаёт (ещё не открытый) MCP-клиент по конфигурации сервера."""
+    if config.transport == TRANSPORT_STDIO:
+        if not config.command:
+            raise ConfigError("MCP-сервер с transport='stdio': укажите 'command'")
+        kwargs: dict[str, Any] = {"command": config.command, "args": list(config.args)}
+        if config.env:
+            kwargs["env"] = dict(config.env)
+        return MCPClient.stdio(**kwargs)
+
+    if config.transport == TRANSPORT_HTTP:
+        if not config.url:
+            raise ConfigError("MCP-сервер с transport='http': укажите 'url'")
+        kwargs = {"url": config.url}
+        if config.headers:
+            kwargs["headers"] = dict(config.headers)
+        return MCPClient.http(**kwargs)
+
+    raise ConfigError(f"Неизвестный transport MCP: {config.transport!r}")  # не должно достигаться
+
+
+@contextmanager
+def build_agent(config: AgentConfig) -> Iterator[Agent]:
+    """Создаёт агента ``ember`` из конфигурации.
+
+    Контекстный менеджер: пока контекст открыт, живут MCP-клиенты
+    (stdio-процессы и HTTP-соединения), после выхода — корректно закрываются.
+
+    Модель агенту не передаётся: она задана провайдеру (``[provider] model``),
+    а агент ``ember`` наследует модель провайдера по умолчанию.
+    """
+    provider = build_provider(config.provider)
+
+    with ExitStack() as stack:
+        tools: list[Any] = []
+        for server in config.mcp_servers:
+            client = _open_mcp_client(server)
+            stack.enter_context(client)
+            tools.extend(client.list_tools())
+
+        kwargs: dict[str, Any] = {"provider": provider, "system_prompt": config.system_prompt}
+        if tools:
+            kwargs["tools"] = tools
+
+        yield Agent(**kwargs)

emberio_labs_ember_agent-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "emberio-labs-ember-agent"
+version = "0.1.0"
+description = "Готовый к запуску агент на базе ember: настройка в TOML, запуск одной командой."
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+license = "MIT"
+authors = [{ name = "Emberio Labs", email = "dev@emberio.labs" }]
+keywords = ["agent", "llm", "ai", "cli", "ember", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "emberio-labs-ember[openai,mcp]>=0.3.0,<1.0",
+]
+
+[project.scripts]
+ember-agent = "ember_agent.cli:main"
+
+[tool.poetry]
+packages = [{ include = "ember_agent" }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.0"
+ruff = "^0.11.0"
+mypy = "^1.15.0"
+
+# --- Ruff: линтер и форматтер ---
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["ember_agent", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle: ошибки
+    "W",   # pycodestyle: предупреждения
+    "F",   # pyflakes
+    "I",   # isort (порядок импортов)
+    "UP",  # pyupgrade (современный синтаксис)
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "PT",  # flake8-pytest-style
+    "RUF", # специфичные для ruff
+]
+ignore = [
+    "RUF001", # проект пишется на русском: кириллица в строках — не ошибка
+    "RUF002", # то же для docstring
+    "RUF003", # то же для комментариев
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["PT009"] # в тестах используем обычные assert, а не unittest-стиль
+
+# --- mypy: статическая типизация ---
+[tool.mypy]
+python_version = "3.12"
+files = ["ember_agent", "tests"]
+ignore_missing_imports = true # ember и dev-зависимости могут быть без стабов
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_return_any = true
+
+# --- pytest ---
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"