emberio-labs-ember 0.1.0__tar.gz

emberio_labs_ember-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-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: emberio-labs-ember
+Version: 0.1.0
+Summary: Библиотека для простой интеграции с LLM-провайдерами и создания собственных агентов
+License: MIT
+License-File: LICENSE
+Author: Ember Labs
+Author-email: dev@emberio.labs
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: openai
+Requires-Dist: openai (>=3.0,<4.0) ; extra == "openai"
+Project-URL: Homepage, https://github.com/emberio-labs/ember
+Project-URL: Repository, https://github.com/emberio-labs/ember
+Description-Content-Type: text/markdown
+
+# ember
+
+Библиотека для простой интеграции с LLM-провайдерами и создания собственных агентов.
+Предоставляет простой и единообразный интерфейс для работы с языковыми моделями,
+чтобы вы могли сосредоточиться на логике своих агентов, а не на деталях API.
+
+## Возможности
+
+- Единый интерфейс для различных LLM-провайдеров
+- Простой способ создавать и конфигурировать собственных агентов
+- Инструменты/функции для модели (tool calling)
+- Минимальное количество кода для старта
+
+> ⚠️ Проект на ранней стадии разработки. API активно меняется.
+
+## Установка
+
+На PyPI пакет публикуется под именем `emberio-labs-ember` (импорт в коде — `ember`):
+
+```bash
+pip install "emberio-labs-ember[openai]"   # с поддержкой OpenAI
+pip install emberio-labs-ember             # ядро (без провайдеров)
+```
+
+Для разработки (из репозитория) проект управляется через
+[Poetry](https://python-poetry.org/):
+
+```bash
+poetry install
+```
+
+## Быстрый старт
+
+### Без ключей: `MockProvider`
+
+Работает без сети и API-ключей — удобно для экспериментов:
+
+```python
+from ember import Agent, MockProvider
+
+agent = Agent(provider=MockProvider(response_text="Привет! Я мок-провайдер."))
+print(agent.run("Привет!"))
+# Привет! Я мок-провайдер.
+```
+
+### С OpenAI: `OpenAIProvider`
+
+API-ключ передаётся явно (провайдер сам не читает окружение):
+
+```python
+import os
+
+from ember import Agent, OpenAIProvider
+
+agent = Agent(
+    provider=OpenAIProvider(api_key=os.environ["OPENAI_API_KEY"]),
+    model="gpt-4o-mini",
+)
+print(agent.run("Расскажи о себе в одном предложении."))
+```
+
+Полный исполняемый пример — в [`examples/quickstart.py`](examples/quickstart.py).
+
+### История диалога
+
+`Agent` сам накапливает историю: сообщения пользователя и ответы модели
+добавляются в `agent.messages`. Сбросить диалог можно через `agent.reset()`.
+Системный промпт задаётся в конструкторе:
+
+```python
+agent = Agent(
+    provider=MockProvider(),
+    system_prompt="Ты краткий и полезный помощник.",
+)
+```
+
+### Инструменты (tool calling)
+
+Модель можно научить вызывать функции. Опишите инструмент через `Tool`
+и передайте список в запрос:
+
+```python
+from ember import ChatRequest, Message, Tool
+
+tools = [
+    Tool(
+        name="get_weather",
+        description="Погода в городе",
+        parameters={
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    )
+]
+
+# provider — любой Provider, например OpenAIProvider(api_key=...)
+response = provider.complete(
+    ChatRequest(
+        messages=[Message(role="user", content="Какая погода в Москве?")],
+        model="gpt-4o-mini",
+        tools=tools,
+    )
+)
+# Если модель решила вызвать инструмент, вызовы будут в response.message.tool_calls
+if response.message.tool_calls:
+    for call in response.message.tool_calls:
+        print(call.name, call.arguments)
+```
+
+Результат выполнения возвращается модели сообщением с ролью `tool`
+и идентификатором вызова:
+
+```python
+Message(role="tool", content="+15C", tool_call_id=call.id)
+```
+
+## Разработка
+
+```bash
+# Установка зависимостей (включая dev)
+poetry install --with dev
+
+# Запуск тестов
+poetry run pytest
+
+# Линтинг
+poetry run ruff check .
+poetry run ruff format --check .
+
+# Проверка типов
+poetry run mypy ember
+```
+
+CI (GitHub Actions) автоматически прогоняет линтинг, проверку типов и тесты
+на Python 3.10–3.12 для каждого pull request.
+
+## Релиз
+
+Публикация новой версии на 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` |
+| GitHub owner | `emberio-labs` |
+| GitHub repository | `ember` |
+| Workflow name | `publish.yml` |
+| Environment | *(пусто)* |
+
+После настройки публикацию можно проверить вручную на TestPyPI:
+GitHub → Actions → Publish → Run workflow. На боевой PyPI пакет уходит
+только по git-тегу `v*`.
+
+## Лицензия
+
+Проект распространяется под лицензией [MIT](LICENSE).
+
+© 2026 Emberio Labs
+

emberio_labs_ember-0.1.0/README.md

@@ -0,0 +1,180 @@
+# ember
+
+Библиотека для простой интеграции с LLM-провайдерами и создания собственных агентов.
+Предоставляет простой и единообразный интерфейс для работы с языковыми моделями,
+чтобы вы могли сосредоточиться на логике своих агентов, а не на деталях API.
+
+## Возможности
+
+- Единый интерфейс для различных LLM-провайдеров
+- Простой способ создавать и конфигурировать собственных агентов
+- Инструменты/функции для модели (tool calling)
+- Минимальное количество кода для старта
+
+> ⚠️ Проект на ранней стадии разработки. API активно меняется.
+
+## Установка
+
+На PyPI пакет публикуется под именем `emberio-labs-ember` (импорт в коде — `ember`):
+
+```bash
+pip install "emberio-labs-ember[openai]"   # с поддержкой OpenAI
+pip install emberio-labs-ember             # ядро (без провайдеров)
+```
+
+Для разработки (из репозитория) проект управляется через
+[Poetry](https://python-poetry.org/):
+
+```bash
+poetry install
+```
+
+## Быстрый старт
+
+### Без ключей: `MockProvider`
+
+Работает без сети и API-ключей — удобно для экспериментов:
+
+```python
+from ember import Agent, MockProvider
+
+agent = Agent(provider=MockProvider(response_text="Привет! Я мок-провайдер."))
+print(agent.run("Привет!"))
+# Привет! Я мок-провайдер.
+```
+
+### С OpenAI: `OpenAIProvider`
+
+API-ключ передаётся явно (провайдер сам не читает окружение):
+
+```python
+import os
+
+from ember import Agent, OpenAIProvider
+
+agent = Agent(
+    provider=OpenAIProvider(api_key=os.environ["OPENAI_API_KEY"]),
+    model="gpt-4o-mini",
+)
+print(agent.run("Расскажи о себе в одном предложении."))
+```
+
+Полный исполняемый пример — в [`examples/quickstart.py`](examples/quickstart.py).
+
+### История диалога
+
+`Agent` сам накапливает историю: сообщения пользователя и ответы модели
+добавляются в `agent.messages`. Сбросить диалог можно через `agent.reset()`.
+Системный промпт задаётся в конструкторе:
+
+```python
+agent = Agent(
+    provider=MockProvider(),
+    system_prompt="Ты краткий и полезный помощник.",
+)
+```
+
+### Инструменты (tool calling)
+
+Модель можно научить вызывать функции. Опишите инструмент через `Tool`
+и передайте список в запрос:
+
+```python
+from ember import ChatRequest, Message, Tool
+
+tools = [
+    Tool(
+        name="get_weather",
+        description="Погода в городе",
+        parameters={
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    )
+]
+
+# provider — любой Provider, например OpenAIProvider(api_key=...)
+response = provider.complete(
+    ChatRequest(
+        messages=[Message(role="user", content="Какая погода в Москве?")],
+        model="gpt-4o-mini",
+        tools=tools,
+    )
+)
+# Если модель решила вызвать инструмент, вызовы будут в response.message.tool_calls
+if response.message.tool_calls:
+    for call in response.message.tool_calls:
+        print(call.name, call.arguments)
+```
+
+Результат выполнения возвращается модели сообщением с ролью `tool`
+и идентификатором вызова:
+
+```python
+Message(role="tool", content="+15C", tool_call_id=call.id)
+```
+
+## Разработка
+
+```bash
+# Установка зависимостей (включая dev)
+poetry install --with dev
+
+# Запуск тестов
+poetry run pytest
+
+# Линтинг
+poetry run ruff check .
+poetry run ruff format --check .
+
+# Проверка типов
+poetry run mypy ember
+```
+
+CI (GitHub Actions) автоматически прогоняет линтинг, проверку типов и тесты
+на Python 3.10–3.12 для каждого pull request.
+
+## Релиз
+
+Публикация новой версии на 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` |
+| GitHub owner | `emberio-labs` |
+| GitHub repository | `ember` |
+| Workflow name | `publish.yml` |
+| Environment | *(пусто)* |
+
+После настройки публикацию можно проверить вручную на TestPyPI:
+GitHub → Actions → Publish → Run workflow. На боевой PyPI пакет уходит
+только по git-тегу `v*`.
+
+## Лицензия
+
+Проект распространяется под лицензией [MIT](LICENSE).
+
+© 2026 Emberio Labs

emberio_labs_ember-0.1.0/ember/__init__.py

@@ -0,0 +1,43 @@
+"""ember — библиотека для простой интеграции с LLM-провайдерами и создания агентов."""
+
+from ember.agent import Agent, ToolCallLimitError
+from ember.providers import (
+    MockProvider,
+    OpenAIProvider,
+    Provider,
+    ProviderError,
+    get_provider,
+    register_provider,
+)
+from ember.types import (
+    ChatRequest,
+    ChatResponse,
+    FunctionTool,
+    Message,
+    StreamChunk,
+    Tool,
+    ToolCall,
+    Usage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Agent",
+    "ChatRequest",
+    "ChatResponse",
+    "FunctionTool",
+    "Message",
+    "MockProvider",
+    "OpenAIProvider",
+    "Provider",
+    "ProviderError",
+    "StreamChunk",
+    "Tool",
+    "ToolCall",
+    "ToolCallLimitError",
+    "Usage",
+    "get_provider",
+    "register_provider",
+]

emberio_labs_ember-0.1.0/ember/agent.py

@@ -0,0 +1,195 @@
+"""Простой агент поверх Provider — минимум кода для чат-диалога."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+from ember.providers.base import Provider
+from ember.types import ChatRequest, FunctionTool, Message, ToolCall
+
+
+class ToolCallLimitError(RuntimeError):
+    """Модель превысила лимит раундов tool calling.
+
+    Поднимается, когда модель снова и снова запрашивает инструменты вместо
+    финального текстового ответа: она зациклилась либо задача не решается
+    доступными инструментами за отведённое число шагов.
+    """
+
+
+class Agent:
+    """Чат-агент, работающий поверх любого ``Provider``.
+
+    Хранит историю диалога и системный промпт, формирует ``ChatRequest``
+    и возвращает текстовый ответ модели.
+
+    Если агенту заданы инструменты (``tools``), ``run()`` исполняет
+    запрошенные моделью вызовы в цикле: результат каждого инструмента
+    возвращается модели как tool-сообщение, и диалог продолжается до тех
+    пор, пока модель не даст финальный текстовый ответ.
+
+    Attributes:
+        provider: Провайдер, через который агент общается с моделью.
+        model: Модель по умолчанию. Если не задана, провайдер использует
+            свою модель по умолчанию.
+        tools: Инструменты, доступные модели (описание + функция).
+        max_tool_steps: Максимум раундов исполнения инструментов за один
+            ``run()``. Один раунд — один запрос к модели и исполнение всех
+            запрошенных в ответе вызовов.
+        messages: Текущая история диалога (включая system-сообщение).
+    """
+
+    def __init__(
+        self,
+        provider: Provider,
+        system_prompt: str = "",
+        model: str | None = None,
+        tools: list[FunctionTool] | None = None,
+        max_tool_steps: int = 10,
+    ) -> None:
+        self.provider = provider
+        self.model = model
+        self.tools = tools
+        self.max_tool_steps = max_tool_steps
+        self.messages: list[Message] = []
+        if system_prompt:
+            self.messages.append(Message(role="system", content=system_prompt))
+        self._validate()
+        self._tool_index: dict[str, FunctionTool] = (
+            {tool.name: tool for tool in tools} if tools else {}
+        )
+
+    def _validate(self) -> None:
+        """Проверить параметры конструктора, чтобы ошибки падали сразу."""
+        if self.max_tool_steps < 1:
+            raise ValueError(
+                f"max_tool_steps должен быть положительным числом, получено: {self.max_tool_steps}"
+            )
+        if self.tools is not None:
+            seen: set[str] = set()
+            for tool in self.tools:
+                if tool.name in seen:
+                    raise ValueError(f"Дубликат имени инструмента: {tool.name!r}")
+                seen.add(tool.name)
+
+    def run(self, user_input: str) -> str:
+        """Отправить сообщение пользователя и вернуть текстовый ответ.
+
+        Если у агента заданы инструменты и модель запрашивает их вызов,
+        ``run()`` исполняет инструменты и возвращает результат модели в
+        диалог до тех пор, пока модель не даст финальный текстовый ответ
+        (без ``tool_calls``). Все промежуточные сообщения (assistant с
+        вызовами, tool-результаты) попадают в историю.
+
+        Args:
+            user_input: Текст сообщения пользователя.
+
+        Returns:
+            Финальный текст ответа модели.
+
+        Raises:
+            ToolCallLimitError: Если модель не завершила диалог за
+                ``max_tool_steps`` раундов исполнения инструментов.
+        """
+        self.messages.append(Message(role="user", content=user_input))
+        tool_steps = 0
+        while True:
+            response = self.provider.complete(self._request())
+            assistant_message = response.message
+            self.messages.append(assistant_message)
+            if not assistant_message.tool_calls:
+                return assistant_message.content
+            if tool_steps >= self.max_tool_steps:
+                names = ", ".join(call.name for call in assistant_message.tool_calls)
+                raise ToolCallLimitError(
+                    f"Модель не завершила диалог: превышен лимит раундов tool calling "
+                    f"({self.max_tool_steps}). Модель продолжает запрашивать инструменты "
+                    f"({names or 'без имён'}) вместо финального текстового ответа."
+                )
+            self._execute_tool_calls(assistant_message.tool_calls)
+            tool_steps += 1
+
+    def _execute_tool_calls(self, tool_calls: list[ToolCall]) -> None:
+        """Исполнить инструменты и добавить результаты в историю как tool-сообщения.
+
+        Любая ошибка (неизвестное имя, битые аргументы, исключение в функции)
+        не роняет диалог, а уходит модели текстом ошибки — модель может
+        скорректировать запрос.
+        """
+        for call in tool_calls:
+            tool = self._tool_index.get(call.name)
+            if tool is None:
+                available = ", ".join(sorted(self._tool_index)) or "нет"
+                content = (
+                    f"Ошибка: инструмент {call.name!r} не найден. "
+                    f"Доступные инструменты: {available}."
+                )
+            else:
+                try:
+                    arguments = json.loads(call.arguments or "{}")
+                    if not isinstance(arguments, dict):
+                        raise ValueError("аргументы должны быть JSON-объектом")
+                    content = self._stringify_result(tool.func(**arguments))
+                except Exception as exc:
+                    content = f"Ошибка при вызове {call.name!r}: {exc}"
+            self.messages.append(Message(role="tool", content=content, tool_call_id=call.id))
+
+    @staticmethod
+    def _stringify_result(result: Any) -> str:
+        """Привести результат функции к строке для tool-сообщения.
+
+        Структуры сериализуются в JSON (читаемо, без \\u-escape), None означает
+        «успех без данных» и превращается в пустую строку.
+        """
+        if result is None:
+            return ""
+        if isinstance(result, dict | list):
+            return json.dumps(result, ensure_ascii=False, default=str)
+        return str(result)
+
+    def stream_run(self, user_input: str) -> Iterator[str]:
+        """Отправить сообщение пользователя и получить ответ потоком.
+
+        Поведение аналогично ``run``, но ответ возвращается по одному
+        фрагменту за раз. По завершении полный ответ попадает в историю.
+
+        Args:
+            user_input: Текст сообщения пользователя.
+
+        Yields:
+            Фрагменты текста ответа модели.
+
+        Raises:
+            ValueError: Если у агента заданы инструменты — потоковый ответ
+                не разбирает ``tool_calls``, используйте ``run()``.
+        """
+        if self.tools:
+            raise ValueError(
+                "stream_run() не поддерживает инструменты: потоковый ответ провайдера "
+                "не разбирает tool_calls. Используйте run() для сценариев с tools."
+            )
+        self.messages.append(Message(role="user", content=user_input))
+        request = ChatRequest(messages=list(self.messages), model=self.model or "", stream=True)
+        full_text = ""
+        for chunk in self.provider.stream(request):
+            full_text += chunk.delta
+            yield chunk.delta
+        self.messages.append(Message(role="assistant", content=full_text))
+
+    def reset(self) -> None:
+        """Очистить историю диалога, оставив только system-промпт."""
+        system = next((m for m in self.messages if m.role == "system"), None)
+        self.messages = [system] if system is not None else []
+
+    def _request(self) -> ChatRequest:
+        # Копия списка: запрос не должен разделять состояние с историей агента,
+        # иначе последующие append в self.messages мутируют переданный запрос.
+        # Пустая model означает «модель провайдера по умолчанию»: адаптеры
+        # (например, OpenAIProvider) подставляют свою дефолтную модель.
+        return ChatRequest(
+            messages=list(self.messages),
+            model=self.model or "",
+            tools=self.tools,
+        )

emberio_labs_ember-0.1.0/ember/providers/__init__.py

@@ -0,0 +1,62 @@
+"""Провайдеры ember: интерфейс, реестр и встроенные реализации."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from ember.providers.base import Provider, ProviderError
+from ember.providers.mock import MockProvider
+from ember.providers.openai import OpenAIProvider
+
+__all__ = [
+    "MockProvider",
+    "OpenAIProvider",
+    "Provider",
+    "ProviderError",
+    "get_provider",
+    "register_provider",
+]
+
+_REGISTRY: dict[str, type[Provider]] = {
+    "mock": MockProvider,
+    "openai": OpenAIProvider,
+}
+
+
+def register_provider(name: str) -> Callable[[type[Provider]], type[Provider]]:
+    """Декоратор: зарегистрировать класс провайдера в реестре по имени.
+
+    Args:
+        name: Имя, по которому провайдер будет доступен через get_provider().
+
+    Returns:
+        Декоратор, который добавляет класс в реестр и возвращает его без изменений.
+    """
+
+    def decorator(cls: type[Provider]) -> type[Provider]:
+        _REGISTRY[name] = cls
+        return cls
+
+    return decorator
+
+
+def get_provider(name: str, **kwargs: Any) -> Provider:
+    """Создать экземпляр провайдера по имени из реестра.
+
+    Args:
+        name: Имя зарегистрированного провайдера (например, "mock").
+        **kwargs: Аргументы, передаваемые конструктору провайдера.
+
+    Returns:
+        Новый экземпляр провайдера.
+
+    Raises:
+        ValueError: Если провайдер с таким именем не зарегистрирован.
+    """
+    try:
+        provider_cls = _REGISTRY[name]
+    except KeyError:
+        available = ", ".join(sorted(_REGISTRY))
+        raise ValueError(f"Неизвестный провайдер: {name!r}. Доступны: {available}") from None
+    return provider_cls(**kwargs)

emberio_labs_ember-0.1.0/ember/providers/base.py

@@ -0,0 +1,46 @@
+"""Абстрактный интерфейс LLM-провайдера."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+
+from ember.types import ChatRequest, ChatResponse, StreamChunk
+
+
+class ProviderError(Exception):
+    """Ошибка при обращении к LLM-провайдеру.
+
+    Адаптеры оборачивают ошибки SDK (сеть, неверный ключ, код ответа)
+    в этот тип, чтобы пользователь работал с единым интерфейсом ошибок.
+    """
+
+
+class Provider(ABC):
+    """Единый интерфейс для LLM-провайдеров.
+
+    Каждый адаптер (OpenAI, Anthropic, Gemini, локальные модели) реализует
+    методы complete и stream, конвертируя свой формат в модели ядра ember.
+    """
+
+    @abstractmethod
+    def complete(self, request: ChatRequest) -> ChatResponse:
+        """Получить полный ответ модели на запрос.
+
+        Args:
+            request: Запрос к модели.
+
+        Returns:
+            Полный ответ модели.
+        """
+
+    @abstractmethod
+    def stream(self, request: ChatRequest) -> Iterator[StreamChunk]:
+        """Получить ответ модели потоком — по одному фрагменту за раз.
+
+        Args:
+            request: Запрос к модели.
+
+        Returns:
+            Итератор фрагментов ответа.
+        """

emberio_labs_ember-0.1.0/ember/providers/mock.py

@@ -0,0 +1,53 @@
+"""Мок-провайдер — работает без сети и API-ключей."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from ember.providers.base import Provider
+from ember.types import ChatRequest, ChatResponse, Message, StreamChunk, Usage
+
+
+class MockProvider(Provider):
+    """Детерминированный провайдер, возвращающий заранее заданный текст.
+
+    Полезен для юнит-тестов, примеров и документации: не требует
+    API-ключа и доступа к сети.
+
+    Attributes:
+        response_text: Текст, который возвращается на любой запрос.
+        model: Имя модели, указываемое в ответе.
+    """
+
+    def __init__(
+        self,
+        response_text: str = "Привет! Я мок-провайдер.",
+        model: str = "mock-1",
+    ) -> None:
+        self.response_text = response_text
+        self.model = model
+
+    def complete(self, request: ChatRequest) -> ChatResponse:
+        """Возвращает фиксированный ответ, игнорируя содержимое запроса."""
+        prompt_tokens = sum(len(m.content.split()) for m in request.messages)
+        completion_tokens = len(self.response_text.split())
+        return ChatResponse(
+            message=Message(role="assistant", content=self.response_text),
+            model=self.model,
+            usage=Usage(
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                total_tokens=prompt_tokens + completion_tokens,
+            ),
+        )
+
+    def stream(self, request: ChatRequest) -> Iterator[StreamChunk]:
+        """Отдаёт ответ по одному слову за фрагмент."""
+        words = self.response_text.split()
+        for index, word in enumerate(words):
+            last = index == len(words) - 1
+            yield StreamChunk(
+                delta=word if last else word + " ",
+                model=self.model,
+                finish_reason="stop" if last else None,
+            )

emberio_labs_ember-0.1.0/ember/providers/openai.py

@@ -0,0 +1,191 @@
+"""Адаптер OpenAI — поверх официального SDK ``openai``.
+
+Модуль импортирует SDK лениво (в конструкторе), чтобы ядро ember оставалось
+лёгким: без установки ``openai`` остальной функционал библиотеки работает.
+Установите пакет: ``pip install "emberio-labs-ember[openai]"``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any, cast
+
+from ember.providers.base import Provider, ProviderError
+from ember.types import ChatRequest, ChatResponse, Message, StreamChunk, Tool, ToolCall, Usage
+
+if TYPE_CHECKING:
+    from openai import OpenAI, OpenAIError
+    from openai.types.chat import ChatCompletionMessageParam
+
+_OPENAI_IMPORT_HINT = (
+    "OpenAIProvider требует пакет 'openai'. Установите его: "
+    "pip install 'emberio-labs-ember[openai]'"
+)
+
+
+class OpenAIProvider(Provider):
+    """Провайдер поверх официального OpenAI SDK.
+
+    Атрибуты:
+        model: Модель по умолчанию, используемая, когда запрос её не задаёт.
+
+    Args:
+        api_key: API-ключ OpenAI (обязательный).
+        model: Модель по умолчанию (например, "gpt-4o-mini").
+
+    Raises:
+        ImportError: Если пакет ``openai`` не установлен.
+    """
+
+    _client: OpenAI
+    _openai_error: type[OpenAIError]
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "gpt-4o-mini",
+    ) -> None:
+        try:
+            from openai import OpenAI, OpenAIError
+        except ImportError as exc:
+            raise ImportError(_OPENAI_IMPORT_HINT) from exc
+
+        self.model = model
+        self._client = OpenAI(api_key=api_key)
+        self._openai_error = OpenAIError
+
+    def complete(self, request: ChatRequest) -> ChatResponse:
+        """Получить полный ответ модели (не потоковый).
+
+        Args:
+            request: Запрос к модели.
+
+        Returns:
+            Ответ модели с текстом, моделью и счётчиками токенов. Если модель
+            решила вызвать инструменты, в ``message.tool_calls`` будет список
+            запрошенных вызовов.
+
+        Raises:
+            ProviderError: Если OpenAI API вернул ошибку.
+        """
+        try:
+            completion = self._client.chat.completions.create(
+                stream=False, **self._build_params(request)
+            )
+        except self._openai_error as exc:
+            raise ProviderError(f"Ошибка OpenAI API: {exc}") from exc
+
+        if not completion.choices:
+            raise ProviderError("OpenAI вернул пустой список choices")
+
+        choice = completion.choices[0]
+        message = self._message_from_choice(choice)
+        usage = completion.usage
+        return ChatResponse(
+            message=message,
+            model=completion.model,
+            usage=(
+                Usage(
+                    prompt_tokens=usage.prompt_tokens,
+                    completion_tokens=usage.completion_tokens,
+                    total_tokens=usage.total_tokens,
+                )
+                if usage is not None
+                else None
+            ),
+        )
+
+    def stream(self, request: ChatRequest) -> Iterator[StreamChunk]:
+        """Получить ответ модели потоком — по одному фрагменту за раз.
+
+        Потоковый режим агрегирует только текст ответа; вызовы инструментов
+        (tool calls) в потоке не разбираются — используйте ``complete``.
+
+        Args:
+            request: Запрос к модели.
+
+        Yields:
+            Фрагменты ответа модели.
+
+        Raises:
+            ProviderError: Если OpenAI API вернул ошибку.
+        """
+        try:
+            chunks = self._client.chat.completions.create(
+                stream=True, **self._build_params(request)
+            )
+        except self._openai_error as exc:
+            raise ProviderError(f"Ошибка OpenAI API: {exc}") from exc
+
+        for chunk in chunks:
+            if not chunk.choices:
+                continue
+            choice = chunk.choices[0]
+            yield StreamChunk(
+                delta=choice.delta.content or "",
+                model=chunk.model,
+                finish_reason=choice.finish_reason,
+            )
+
+    def _build_params(self, request: ChatRequest) -> dict[str, Any]:
+        """Собрать параметры для вызова chat.completions.create (без stream)."""
+        params: dict[str, Any] = {
+            "model": request.model or self.model,
+            "messages": [self._to_openai_message(message) for message in request.messages],
+            "temperature": request.temperature,
+        }
+        if request.max_tokens is not None:
+            params["max_tokens"] = request.max_tokens
+        if request.tools:
+            params["tools"] = [self._to_openai_tool(tool) for tool in request.tools]
+        return params
+
+    @staticmethod
+    def _to_openai_message(message: Message) -> ChatCompletionMessageParam:
+        """Сконвертировать Message ядра в формат сообщения OpenAI."""
+        params: dict[str, Any] = {"role": message.role, "content": message.content}
+        if message.name is not None:
+            params["name"] = message.name
+        if message.tool_calls:
+            params["tool_calls"] = [
+                {
+                    "id": tool_call.id,
+                    "type": "function",
+                    "function": {
+                        "name": tool_call.name,
+                        "arguments": tool_call.arguments,
+                    },
+                }
+                for tool_call in message.tool_calls
+            ]
+        if message.tool_call_id is not None:
+            params["tool_call_id"] = message.tool_call_id
+        # cast: ChatCompletionMessageParam — union TypedDict'ов с Literal-ролями,
+        # а role в ядре — произвольный str, поэтому mypy не может выбрать вариант.
+        return cast("ChatCompletionMessageParam", params)
+
+    @staticmethod
+    def _to_openai_tool(tool: Tool) -> dict[str, Any]:
+        """Сконвертировать Tool ядра в параметр tools OpenAI."""
+        function: dict[str, Any] = {"name": tool.name}
+        if tool.description:
+            function["description"] = tool.description
+        if tool.parameters is not None:
+            function["parameters"] = tool.parameters
+        return {"type": "function", "function": function}
+
+    @staticmethod
+    def _message_from_choice(choice: Any) -> Message:
+        """Собрать Message ядра из choice ответа OpenAI (complete)."""
+        content = choice.message.content or ""
+        message = Message(role="assistant", content=content)
+        if choice.message.tool_calls:
+            message.tool_calls = [
+                ToolCall(
+                    id=tool_call.id,
+                    name=tool_call.function.name,
+                    arguments=tool_call.function.arguments or "{}",
+                )
+                for tool_call in choice.message.tool_calls
+            ]
+        return message

emberio_labs_ember-0.1.0/ember/types.py

@@ -0,0 +1,183 @@
+"""Модели данных ядра ember — общий язык для всех провайдеров.
+
+Эти типы не зависят от конкретных SDK: каждый адаптер (OpenAI, Anthropic,
+Gemini, локальные модели) конвертирует свой формат в модели ядра и обратно.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, get_args
+
+Role = Literal["system", "user", "assistant", "tool"]
+"""Допустимые роли участников диалога."""
+
+_VALID_ROLES: tuple[str, ...] = get_args(Role)
+
+
+@dataclass(slots=True)
+class Message:
+    """Одно сообщение в диалоге.
+
+    Attributes:
+        role: Роль отправителя: system, user, assistant или tool.
+        content: Текст сообщения. Для assistant-сообщений с вызовами
+            инструментов может быть пустой строкой.
+        name: Опциональное имя участника — позволяет модели различать
+            нескольких участников с одной ролью (например, нескольких
+            пользователей или ассистентов в одном диалоге).
+        tool_calls: Запрошенные моделью вызовы инструментов (только для
+            роли assistant).
+        tool_call_id: Идентификатор вызова инструмента, на который отвечает
+            это сообщение (обязателен для роли tool).
+    """
+
+    role: Role
+    content: str
+    name: str | None = None
+    tool_calls: list[ToolCall] | None = None
+    tool_call_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.role not in _VALID_ROLES:
+            raise ValueError(
+                f"Недопустимая роль: {self.role!r}. Ожидается одна из: {', '.join(_VALID_ROLES)}"
+            )
+        if self.role == "tool" and not self.tool_call_id:
+            raise ValueError("Сообщение с ролью 'tool' должно содержать tool_call_id")
+
+
+@dataclass(slots=True)
+class ToolCall:
+    """Запрос модели на вызов инструмента.
+
+    Attributes:
+        id: Уникальный идентификатор вызова — по нему сопоставляется
+            результат выполнения (см. Message.tool_call_id).
+        name: Имя вызываемой функции.
+        arguments: Аргументы функции в виде JSON-строки.
+    """
+
+    id: str
+    name: str
+    arguments: str = "{}"
+
+
+@dataclass(slots=True)
+class Tool:
+    """Описание функции, доступной модели для вызова (tool calling).
+
+    Attributes:
+        name: Имя функции, которое модель укажет в tool_calls.
+        description: Описание: для чего функция, какие параметры — помогает
+            модели выбрать подходящий инструмент.
+        parameters: JSON Schema параметров функции (например,
+            ``{"type": "object", "properties": {...}}``).
+    """
+
+    name: str
+    description: str = ""
+    parameters: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("Имя инструмента не может быть пустым")
+
+
+@dataclass(slots=True, kw_only=True)
+class FunctionTool(Tool):
+    """Инструмент для агента: описание для модели + локальная функция.
+
+    Единый источник истины для tool calling: поля ``Tool`` (name,
+    description, parameters) уходят модели в ``ChatRequest.tools``, а
+    ``func`` агент вызывает с аргументами из ``ToolCall.arguments`` модели.
+    Связка схемы и реализации в одном объекте исключает их рассинхрон.
+
+    Поля keyword-only (включая унаследованные) — инструмент всегда
+    собирается по именам полей, позиционные аргументы не поддерживаются.
+
+    Attributes:
+        func: Python-функция, исполняющая инструмент. Вызывается агентом с
+            keyword-аргументами, распарсенными из JSON-объекта arguments.
+    """
+
+    func: Callable[..., Any]
+
+
+@dataclass(slots=True)
+class Usage:
+    """Счётчики токенов за один запрос.
+
+    Attributes:
+        prompt_tokens: Токенов потрачено на вход (промпт).
+        completion_tokens: Токенов потрачено на ответ.
+        total_tokens: Суммарное количество токенов.
+    """
+
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+@dataclass(slots=True)
+class ChatRequest:
+    """Запрос к LLM-провайдеру.
+
+    Attributes:
+        messages: История диалога. Не может быть пустой.
+        model: Имя модели у провайдера (например, "gpt-4o-mini").
+        temperature: Креативность ответа, от 0.0 (детерминированно) и выше.
+        max_tokens: Максимум токенов в ответе. None — ограничение провайдера.
+        stream: Использовать ли потоковый режим ответа.
+        tools: Описания функций, которые модель может вызвать. Тип Sequence,
+            чтобы можно было передавать список подтипов Tool (например,
+            FunctionTool) без конвертации.
+    """
+
+    messages: list[Message]
+    model: str
+    temperature: float = 1.0
+    max_tokens: int | None = None
+    stream: bool = False
+    tools: Sequence[Tool] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.messages:
+            raise ValueError("Список сообщений не может быть пустым")
+        if self.temperature < 0:
+            raise ValueError("temperature не может быть отрицательной")
+        if self.max_tokens is not None and self.max_tokens <= 0:
+            raise ValueError("max_tokens должен быть положительным числом")
+
+
+@dataclass(slots=True)
+class ChatResponse:
+    """Ответ модели на ChatRequest.
+
+    Attributes:
+        message: Сообщение с ответом модели (роль assistant). Если модель
+            решила вызвать инструменты, заполнено поле message.tool_calls.
+        model: Модель, которая сформировала ответ.
+        usage: Счётчики токенов, если провайдер их вернул.
+    """
+
+    message: Message
+    model: str
+    usage: Usage | None = None
+
+
+@dataclass(slots=True)
+class StreamChunk:
+    """Фрагмент потокового ответа модели.
+
+    Attributes:
+        delta: Часть текста ответа, пришедшая в этом фрагменте.
+        model: Модель, из которой пришёл фрагмент.
+        finish_reason: Причина завершения ("stop", "length", ...) для
+            последнего фрагмента, иначе None.
+    """
+
+    delta: str
+    model: str
+    finish_reason: str | None = None

emberio_labs_ember-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[tool.poetry]
+name = "emberio-labs-ember"
+version = "0.1.0"
+description = "Библиотека для простой интеграции с LLM-провайдерами и создания собственных агентов"
+license = "MIT"
+authors = ["Ember Labs <dev@emberio.labs>"]
+readme = "README.md"
+packages = [{ include = "ember" }]
+
+[tool.poetry.urls]
+Homepage = "https://github.com/emberio-labs/ember"
+Repository = "https://github.com/emberio-labs/ember"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+openai = { version = "^3.0", optional = true }
+
+[tool.poetry.extras]
+openai = ["openai"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+ruff = "^0.9"
+mypy = "^1.10"
+openai = "^3.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+python_version = "3.10"
+files = ["ember"]
+strict = true