Framework docs (#122)

* init

* docs locale

* videos fix

* Update models.py

* Update __init__.py

* Expand and update framework documentation

* Clarify Function Calling and Structured Output relationship

* agents added

* expand agent docs

* translate sgr-api

Author: virrius

.github/workflows/ghpages.yml

@@ -0,0 +1,34 @@
+name: ghpages.yml
+on:
+  push:
+    branches:
+      - main
+      - framework-docs
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install \
+              mkdocs-material \
+              mkdocs-dracula-theme \
+              mkdocs-material-extensions \
+              mkdocs-get-deps \
+              mkdocs-static-i18n
+      - run: mkdocs gh-deploy --force

.pre-commit-config.yaml

@@ -13,6 +13,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: check-yaml
+        args: [--unsafe]
       - id: check-toml
       - id: check-docstring-first
       - id: check-executables-have-shebangs
@@ -31,6 +32,7 @@ repos:
     hooks:
       - id: mdformat
         args: ["--number"]
+        exclude: ^docs/
         additional_dependencies:
           - mdformat-gfm
           - mdformat-black

docs/dev_workflow.png docs/assets/images/dev_workflow.pngdocs/dev_workflow.png renamed to docs/assets/images/dev_workflow.png

@@ -0,0 +1,223 @@
+# Configuration Guide
+
+Это руководство описывает систему конфигурации SGR Agent Core и способы настройки агентов для вашего проекта.
+
+## Иерархия
+
+Система конфигурации построена по принципу дополнения:
+Общие настройки из основного конфига переопределяют defaults,
+а специфичные из `agents` переопределяют необходимые параметры для каждого конкретного агента на уровне `AgentDefinition`.
+
+```mermaid
+graph TD
+    FD[Framework Defaults]
+    B[.env]
+    C[config.yaml]
+    A[any other definitions yaml]
+    D[agents.yaml]
+    E[GlobalConfig]
+    G[Agent Config]
+    I[AgentDefinition]
+    J[Agent]
+
+    FD ----> E
+    B ---> E
+    C --> E
+    D --> G
+    A --> G
+    E --> I
+    G --> I
+    I --> J
+
+    style E fill:#10B981
+    style G fill:#10B981
+    style I fill:#8B5CF6
+    style J fill:#8B5CF6
+```
+
+## GlobalConfig
+
+!!! Important "Важно: Единый инстанс GlobalConfig"
+    Все вызовы `GlobalConfig()` возвращают один и тот же экземпляр. Это означает, что при создании нескольких объектов `GlobalConfig` вы получите ссылку на один и тот же объект в памяти.
+
+    Единожды применённые изменения и загруженные конфигурации распространятся на всю программу.
+
+### Загрузка из переменных окружения (.env)
+
+`GlobalConfig` использует `pydantic-settings` для автоматической загрузки настроек из переменных окружения. Все переменные должны иметь префикс `SGR__` и использовать двойное подчёркивание `__` для вложенных параметров.
+
+```python
+from sgr_agent_core import GlobalConfig
+
+config = GlobalConfig()
+```
+Пример можно найти в [`.env.example`](https://github.com/vamplabAI/sgr-agent-core/blob/main/.env.example).
+
+### Загрузка из YAML файла
+
+Для более структурированной конфигурации можно использовать YAML файлы:
+
+```python
+from sgr_agent_core import GlobalConfig
+
+# Загрузка из config.yaml
+config = GlobalConfig.from_yaml("config.yaml")
+```
+
+
+Пример можно найти в [`config.yaml.example`](https://github.com/vamplabAI/sgr-agent-core/blob/main/config.yaml.example).
+
+
+
+### Переопределение параметров
+
+**Ключевая особенность:** `AgentDefinition` наследует все параметры из `GlobalConfig` и переопределяет только те, которые указаны явно. Это позволяет создавать минималистичные конфигурации, указывая только необходимые изменения.
+
+### Примеры конфигурации агентов
+
+Агенты определяются в файле `agents.yaml` или могут быть загружены программно:
+
+```python
+from sgr_agent_core import GlobalConfig
+
+config = GlobalConfig.from_yaml("config.yaml")
+config.definitions_from_yaml("agents.yaml")
+config.definitions_from_yaml("more_agents.yaml")
+```
+!!!warning
+    Метод `definitions_from_yaml` объединяет новые определения с существующими, перезаписывая агентов с одинаковыми именами
+
+#### Пример 1: Минимальная конфигурация
+
+Агент, который переопределяет только модель LLM и набор инструментов:
+
+```yaml
+agents:
+  simple_agent:
+    base_class: "SGRToolCallingAgent"
+
+    # Переопределяем только модель
+    llm:
+      model: "gpt-4o-mini"
+
+    # Указываем минимальный набор инструментов
+    tools:
+      - "WebSearchTool"
+      - "FinalAnswerTool"
+```
+
+В этом примере агент `simple_agent` использует:
+- Все настройки LLM из `GlobalConfig`, кроме `model`
+- Все настройки поиска из `GlobalConfig`
+- Все настройки выполнения из `GlobalConfig`
+- Только два указанных инструмента
+
+#### Пример 2: Полная кастомизация
+
+Агент с полным переопределением параметров:
+
+```yaml
+agents:
+  custom_research_agent:
+    base_class: "sgr_agent_core.agents.sgr_agent.ResearchSGRAgent"
+
+    # Переопределяем LLM настройки
+    llm:
+      model: "gpt-4o"
+      temperature: 0.3
+      max_tokens: 16000
+      # api_key и base_url наследуются из GlobalConfig
+
+    # Переопределяем настройки поиска
+    search:
+      max_results: 15
+      max_searches: 6
+      content_limit: 2000
+
+    # Переопределяем настройки выполнения
+    execution:
+      max_iterations: 15
+      max_clarifications: 5
+      max_searches: 6
+      logs_dir: "logs/custom_agent"
+      reports_dir: "reports/custom_agent"
+
+    # Полный набор инструментов
+    tools:
+      - "WebSearchTool"
+      - "ExtractPageContentTool"
+      - "CreateReportTool"
+      - "ClarificationTool"
+      - "GeneratePlanTool"
+      - "AdaptPlanTool"
+      - "FinalAnswerTool"
+```
+
+#### Пример 3: Оптимизированный для скорости
+
+Агент с настройками для быстрого выполнения:
+
+```yaml
+agents:
+  fast_research_agent:
+    base_class: "SGRToolCallingAgent"
+
+    llm:
+      model: "gpt-4o-mini"
+      temperature: 0.1  # Более детерминированные ответы
+      max_tokens: 4000  # Меньше токенов для быстрого ответа
+
+    execution:
+      max_iterations: 8  # Меньше итераций
+      max_clarifications: 2
+      max_searches: 3
+
+    tools:
+      - "WebSearchTool"
+      - "CreateReportTool"
+      - "FinalAnswerTool"
+      - "ReasoningTool"
+```
+
+#### Пример 4: С кастомными промптами
+
+Агент с переопределением системных промптов:
+
+```yaml
+agents:
+  technical_analyst:
+    base_class: "SGRAgent"
+
+    llm:
+      model: "gpt-4o"
+      temperature: 0.2
+
+    # Переопределяем промпты
+    prompts:
+      system_prompt_str: |
+        You are a highly specialized technical analyst.
+        Your expertise includes deep technical analysis and
+        detailed research documentation.
+
+    execution:
+      max_iterations: 20
+      max_searches: 8
+
+    tools:
+      - "WebSearchTool"
+      - "ExtractPageContentTool"
+      - "CreateReportTool"
+      - "ClarificationTool"
+      - "FinalAnswerTool"
+```
+
+
+## Рекомендации
+
+- **Храните секреты в .env** - не коммитьте чувствительные ключи в репозиторий =)
+
+    В production окружении рекомендуется использовать ENV переменные вместо хардкода ключей в YAML
+
+- **Используйте минимальные переопределения** - указывайте только то, что отличается от GlobalConfig
+- **Храните Definitions, a не Agents** - Агенты создаются под непосредственное выполнение задачи,
+их definitions можно добавлять/удалять/изменять в любое время

docs/idea_workflow.png docs/assets/images/idea_workflow.pngdocs/idea_workflow.png renamed to docs/assets/images/idea_workflow.png

@@ -0,0 +1,35 @@
+# Основные концепции
+
+Этот документ описывает ключевые сущности SGR Deep Research Framework.
+
+![SGR Agent Core Concept](../sgr_concept.png)
+
+## Агент
+
+**BaseAgent** — базовый класс для всех агентов. Определяет трёхфазный цикл выполнения: Reasoning Phase → Select Action Phase → Action Phase. Управляет состоянием через `ResearchContext`, обеспечивает стриминг ответов и обработку уточнений.
+
+## Тул
+
+**BaseTool** — базовый класс для всех инструментов. Определяет единый интерфейс через метод `__call__()`. Все инструменты автоматически регистрируются через `ToolRegistryMixin` и возвращают результат как строку или JSON.
+
+## Конфиг
+
+**AgentConfig** — централизованная конфигурация агента, объединяющая настройки:
+
+- **LLMConfig** — параметры языковой модели (API ключ, модель, температура, токены)
+- **SearchConfig** — настройки поиска (Tavily API, лимиты поисков и результатов)
+- **ExecutionConfig** — параметры выполнения (максимальные итерации, уточнения, директории)
+- **PromptsConfig** — настройки промптов (системный промпт, шаблоны запросов)
+- **MCPConfig** — настройки интеграции с MCP серверами
+
+## Дефинишн
+
+**AgentDefinition** — определение агента как шаблона для создания экземпляров. Включает имя агента, базовый класс, набор инструментов и все настройки из `AgentConfig`. Поддерживает загрузку из YAML файлов и автоматическое наследование настроек из `GlobalConfig`.
+
+## Регистри
+
+**Registry** — централизованные реестры (`AgentRegistry`, `ToolRegistry`) для автоматической регистрации и поиска классов. Обеспечивают динамический поиск по имени и типобезопасность через дженерики.
+
+## Stream
+
+**Streaming** — стриминг ответов для передачи данных в реальном времени. Реализует асинхронную очередь и совместим с форматом OpenAI streaming API.