# Переменные и макросы НадTavern

Краткая, человеко‑понятная шпаргалка по тому, какие переменные и макросы доступны в шаблонах (в том числе в Prompt Blocks), как они устроены и как их правильно использовать. Док ниже соответствует текущему коду.

Реализация формирует единый «контекст» переменных для всех нод пайплайна, дополняет его выходами уже выполненных нод, а узел ProviderCall добавляет свои служебные структуры для удобной сборки промпта.

Ссылки на код:
- Формирование контекста запроса: [build_macro_context()](agentui/api/server.py:142)
- Исполнитель пайплайна и снапшот OUT: [PipelineExecutor.run()](agentui/pipeline/executor.py:136)
- Узел провайдера (Prompt Blocks → provider payload): [ProviderCallNode.run()](agentui/pipeline/executor.py:650)
- Шаблоны/макросы ([[...]] и {{ ... }}): [render_template_simple()](agentui/pipeline/templating.py:187)
- Короткая форма [[OUTx]] (извлечение текста): [_best_text_from_outputs()](agentui/pipeline/templating.py:124)
- Прямой форвард запросов: [RawForwardNode.run()](agentui/pipeline/executor.py:833)

---

## 1) Общие переменные контекста (для всех нод)

Эти переменные доступны в шаблонах любой ноды. Они добавляются на стороне сервера при обработке входящего HTTP‑запроса.

- model — строка с именем модели.  
  Пример: "gpt-4o-mini"
- vendor_format — вендор/протокол запроса: "openai" | "gemini" | "claude" | "unknown"
- system — «системный» текст, если он был во входящем запросе; иначе пустая строка.

- params — стандартные параметры генерации (можно использовать как дефолты)
  - params.temperature — число с плавающей точкой (по умолчанию 0.7)
  - params.max_tokens — целое или null
  - params.top_p — число (по умолчанию 1.0)
  - params.stop — массив строк или null

- chat — сведения о чате во входящем запросе
  - chat.last_user — последнее сообщение пользователя (строка)
  - chat.messages — массив сообщений в унифицированной форме:
    - role — "system" | "user" | "assistant" | "tool"
    - content — содержимое (обычно строка)
    - name — опционально, строка
    - tool_call_id — опционально

- incoming — детали ВХОДЯЩЕГО HTTP‑запроса
  - incoming.method — метод ("POST" и т.п.)
  - incoming.url — полный URL (в query ключи маскируются для логов)
  - incoming.path — путь (например, /v1/chat/completions)
  - incoming.query — строка query без вопросительного знака
  - incoming.query_params — объект со всеми query‑параметрами
  - incoming.headers — объект всех заголовков запроса
  - incoming.json — сырой JSON тела запроса, как прислал клиент
  - incoming.api_keys — удобные «срезы» ключей
    - incoming.api_keys.authorization — значение из заголовка Authorization (если есть)
    - incoming.api_keys.key — значение из query (?key=...) — удобно для Gemini

Пример использования в шаблоне:
- [[VAR:incoming.api_keys.key]] — возьмёт ключ из строки запроса (?key=...).
- [[VAR:incoming.headers.x-api-key]] — возьмёт ключ из заголовка x-api-key (типично для Anthropic).
- {{ params.temperature|default(0.7) }} — безопасно подставит число, если не задано во входящих данных.

---

## 2) Выходы нод (OUT) и ссылки на них

Во время исполнения пайплайна результаты предыдущих нод собираются в снапшот OUT и доступны при рендере шаблонов следующих нод:

- OUT — словарь выходов нод, ключи — id нод в пайплайне (например, "n1", "n2").
  - OUT.n1, OUT.n2, ... — объект результата соответствующей ноды.

Формы доступа:
- Полная форма: [[OUT:n1.result.choices.0.message.content]]  
  (или фигурными скобками: {{ OUT.n1.result.choices.0.message.content }})
- Короткая форма «просто текст»: [[OUT1]], [[OUT2]], ...  
  Это эвристика: берётся самое вероятное «текстовое» поле из результата (см. [_best_text_from_outputs()](agentui/pipeline/templating.py:121)).

Что возвращают встроенные ноды:
- ProviderCall:
  - OUT.nX.result — сырой JSON ответа провайдера
  - OUT.nX.response_text — уже извлечённый «лучший текст» (строка)
- RawForward:
  - OUT.nX.result — JSON, как пришёл от апстрима (или {"error": "...", "text": "..."} при не‑JSON ответе)

Подсказка по короткой форме [[OUTx]]:
- OpenAI: вернёт choices[0].message.content
- Gemini: вернёт candidates[0].content.parts[0].text
- Claude: склеит content[].text
- Если явных полей нет — выполнит «глубокий поиск» по ключам "text"/"content"

---

## 3) Макросы подстановки и синтаксис

В шаблонах доступны обе формы подстановки:

1) Квадратные скобки [[ ... ]] — простая подстановка
- [[VAR:путь]] — взять значение из контекста по точечному пути  
  Пример: [[VAR:incoming.json.max_tokens]]
- [[OUT:путь]] — взять значение из OUT (см. раздел выше)  
  Пример: [[OUT:n1.result.choices.0.message.content]]
- [[OUT1]] / [[OUT2]] — короткая форма «просто текст»
- [[PROMPT]] — специальный JSON‑фрагмент из Prompt Blocks (см. ниже)

2) Фигурные скобки {{ ... }} — «джинджа‑лайт»
- {{ путь }} — взять значение по пути из контекста (или из OUT.* если начать с OUT.)  
  Пример: {{ OUT.n1.result }}
- Фильтр по умолчанию: {{ что-то|default(значение) }}  
  Примеры:
  - {{ params.temperature|default(0.7) }}
  - {{ incoming.json.stop|default([]) }}
  - {{ anthropic_version|default('2023-06-01') }} — см. «Опциональные поля» ниже
- Фигурные скобки удобны там, где нужно вставить внутрь JSON не строку, а ЧИСЛО/ОБЪЕКТ/МАССИВ без кавычек и/или задать дефолт.

---

## 4) ProviderCall: Prompt Blocks, pm.* и [[PROMPT]]

Узел ProviderCall собирает ваши Prompt Blocks (блоки вида: роль/текст/вкл‑выкл/порядок) в стандартные «сообщения» и превращает их в структуру для конкретного провайдера.

Внутри шаблонов этого узла доступны:
- pm — «сырьевые» структуры из Prompt Blocks
  - Для OpenAI:
    - pm.messages — массив { role, content, name? }
    - pm.system_text — один большой текст из всех system‑блоков
  - Для Gemini:
    - pm.contents — массив { role: "user"|"model", parts: [{text}] }
    - pm.systemInstruction — объект вида { parts: [{text}] } или пустой {}
    - pm.system_text — строка
  - Для Claude:
    - pm.system_text — строка
    - pm.system — то же самое (удобно подставлять в поле "system")
    - pm.messages — массив { role: "user"|"assistant", content: [{type:"text", text:"..."}] }

- [[PROMPT]] — готовый JSON‑фрагмент на основе pm, безопасный для вставки внутрь шаблона:
  - OpenAI → подставит: "messages": [...]
  - Gemini → подставит: "contents": [...], "systemInstruction": {...}
  - Claude → подставит: "system": "...", "messages": [...]

Зачем это нужно?
- Чтобы 1) удобно собирать промпт из визуальных блоков, 2) не «сломать» JSON руками.  
  Вы можете вручную использовать {{ pm.* }}, но [[PROMPT]] — рекомендуемый и самый безопасный вариант.

---

## 5) Частые сценарии и примеры

Примеры ниже можно вклеивать в поле «template» ноды ProviderCall. Они уже используют [[PROMPT]] и аккуратные дефолты.

OpenAI (POST /v1/chat/completions):
```
{
  "model": "{{ model }}",
  [[PROMPT]],
  "temperature": {{ incoming.json.temperature|default(params.temperature|default(0.7)) }},
  "top_p": {{ incoming.json.top_p|default(params.top_p|default(1)) }},
  "max_tokens": {{ incoming.json.max_tokens|default(params.max_tokens|default(256)) }},
  "stop": {{ incoming.json.stop|default(params.stop|default([])) }}
}
```

Gemini (POST /v1beta/models/{model}:generateContent):
```
{
  "model": "{{ model }}",
  [[PROMPT]],
  "safetySettings": {{ incoming.json.safetySettings|default([]) }},
  "generationConfig": {
    "temperature": {{ incoming.json.generationConfig.temperature|default(params.temperature|default(0.7)) }},
    "topP": {{ incoming.json.generationConfig.topP|default(params.top_p|default(1)) }},
    "maxOutputTokens": {{ incoming.json.generationConfig.maxOutputTokens|default(params.max_tokens|default(256)) }},
    "stopSequences": {{ incoming.json.generationConfig.stopSequences|default(params.stop|default([])) }}
  }
}
```
Подсказка: ключ Gemini удобно брать из строки запроса:  
в endpoint используйте …?key=[[VAR:incoming.api_keys.key]]

Claude (POST /v1/messages):
```
{
  "model": "{{ model }}",
  [[PROMPT]],
  "temperature": {{ incoming.json.temperature|default(params.temperature|default(0.7)) }},
  "top_p": {{ incoming.json.top_p|default(params.top_p|default(1)) }},
  "max_tokens": {{ incoming.json.max_tokens|default(params.max_tokens|default(256)) }},
  "system": {{ pm.system|default("") }}
}
```
Подсказка: ключ Anthropic обычно передают в заголовке x-api-key.  
В UI‑пресете это поле уже есть в headers.

RawForward (прямой форвард входящего запроса):
- Поля конфигурации base_url, override_path, extra_headers проходят через те же макросы, поэтому можно подставлять динамику:
  - base_url: https://generativelanguage.googleapis.com
  - override_path: [[VAR:incoming.path]] (или задать свой)
  - extra_headers (JSON): `{"X-Trace":"req-{{ incoming.query_params.session|default('no-session') }}"}`

---

## 6) Опциональные/редкие поля, о которых стоит знать

- anthropic_version — используется как HTTP‑заголовок для Claude ("anthropic-version"). В тело запроса не вставляется.
  Если нужен дефолт, задавайте его в headers (например, в конфиге ноды/шаблоне заголовков). В шаблонах тела используйте [[PROMPT]]/pm.* без anthropic_version.

- stream — в MVP стриминг отключён, сервер принудительно не стримит ответ.  
  В шаблонах можно встретить поля stream, но по умолчанию они не включены.

---

## 7) Когда использовать [[...]] и когда {{ ... }}

- Внутрь JSON как ОБЪЕКТ/МАССИВ/ЧИСЛО: используйте {{ ... }}  
  (фигурные скобки вставляют «как есть», без кавычек, и умеют |default(...))
- Для строк/URL/заголовков/простых значений: можно использовать [[...]]  
  (квадратные скобки удобны и короче писать)

Примеры:
- {{ pm.contents }} — вставит массив как настоящий массив (без кавычек)
- {{ params.temperature|default(0.7) }} — безопасный дефолт для числа
- [[VAR:incoming.api_keys.authorization]] — быстро подставить строку Authorization

---

## 8) Отладка и рекомендации

- ProviderCall печатает в консоль DEBUG сведения: выбранный провайдер, конечный URL, первые символы тела запроса — удобно для проверки корректности шаблона.
- Если «ничего не подставилось»:
  1) Проверьте, что вы НЕ передаёте сырое входное тело напрямую в ProviderCall (узел строит тело из шаблона и Prompt Blocks).
  2) Убедитесь, что итоговый JSON валиден (закрывающие скобки, запятые).
  3) Проверьте точность путей в макросах (OUT vs OUTx, правильные id нод n1/n2/...).
- Для ссылок на выходы предыдущих нод используйте [[OUT1]] как «просто текст», либо полные пути [[OUT:n1...]] для точного фрагмента.

---

## 9) Быстрая памятка по ключам доступа

- Gemini: [[VAR:incoming.api_keys.key]] — рекомендовано; ключ приходит в query (?key=...).
- OpenAI: [[VAR:incoming.headers.authorization]] (или [[VAR:incoming.api_keys.authorization]]) — стандартный Bearer‑токен.
- Anthropic: [[VAR:incoming.headers.x-api-key]] — ключ в заголовке.

---

## 10) Ссылки на реализацию (для интересующихся деталями)

- Контекст (переменные): [build_macro_context()](agentui/api/server.py:142)
- Исполнение пайплайна, зависимости, снапшоты OUT: [PipelineExecutor.run()](agentui/pipeline/executor.py:136)
- Узел провайдера (Prompt Blocks → провайдер): [ProviderCallNode.run()](agentui/pipeline/executor.py:650)
- PM‑структуры для шаблонов: [ProviderCallNode._blocks_struct_for_template()](agentui/pipeline/executor.py:592)
- Подстановка [[PROMPT]], макросы, дефолты: [render_template_simple()](agentui/pipeline/templating.py:187)
- Короткая форма [[OUTx]] и поиск «лучшего текста»: [_best_text_from_outputs()](agentui/pipeline/templating.py:124)
- Прямой форвард входящего запроса: [RawForwardNode.run()](agentui/pipeline/executor.py:833)
- Детекция вендора по входному payload: [detect_vendor()](agentui/common/vendors.py:8)

Удачного редактирования!
---
## Пользовательские переменные (SetVars) — «для людей»

Задача: в начале пайплайна положить свои значения и потом использовать их в шаблонах одной строкой — например [[MY_KEY]] или {{ MAX_TOKENS }}.

Где это в UI
- В левой панели добавьте ноду SetVars и откройте её в инспекторе.
- Жмите «Добавить переменную», у каждой переменной есть три поля:
  - name — имя переменной (латинские буквы/цифры/подчёркивание, не с цифры): MY_KEY, REGION, MAX_TOKENS
  - mode — режим обработки значения:
    - string — строка, в которой работают макросы ([[...]] и {{ ... }})
    - expr — «мини‑формула» без макросов (подробнее ниже)
  - value — собственно значение

Как потом вставлять переменные
- Для строк (URL/заголовки/текст) — квадратные скобки: [[MY_KEY]]
- Для чисел/массивов/объектов — фигурные скобки: {{ MAX_TOKENS }}, {{ GEN_CFG }}

Примеры «как надо»
- Переменная-строка (mode=string):
  - name: AUTH
  - value: "Bearer [[VAR:incoming.headers.authorization]]"
  - Использование в заголовке: "Authorization": "[[AUTH]]"
- Переменная-число (mode=expr):
  - name: MAX_TOKENS
  - value: 128 + 64
  - Использование в JSON: "max_tokens": {{ MAX_TOKENS }}
- Переменная-объект (mode=expr):
  - name: GEN_CFG
  - value: {"temperature": 0.3, "topP": 0.9, "safe": true}
  - Использование: "generationConfig": {{ GEN_CFG }}

Важно про два режима
- string — это «шаблон». Внутри работают все макросы ([[VAR:...]], [[OUT:...]], [[PROMPT]], {{ ... }}). Значение прогоняется через рендер [render_template_simple()](agentui/pipeline/templating.py:184).
- expr — это «мини‑формула». Внутри НЕТ макросов и НЕТ доступа к контексту; только литералы и операции (см. ниже). Вычисляет значение безопасно — без eval, на белом списке AST (реализация: [SetVarsNode._safe_eval_expr()](agentui/pipeline/executor.py:291)).

Что умеет expr (мини‑формулы)
- Числа и арифметика: 128 + 64, (5 * 60) + 30, 42 % 2, -5, 23 // 10
- Строки: "eu" + "-central" → "eu-central" (строки склеиваем знаком +)
- Булева логика: (2 < 3) and (10 % 2 == 0), 1 < 2 < 5
- Коллекции: ["fast", "safe"], {"temperature": 0.3, "topP": 0.9, "safe": true}
- JSON‑литералы: true/false/null, объекты и массивы — если выражение является чистым JSON, оно разбирается напрямую (без макросов), т.е. true→True, null→None и т.п.
- Запрещено: функции (кроме специально разрешённых ниже), доступ к переменным/контексту, атрибуты/индексация/условные выражения.

Рандом в expr
- В expr доступны три простые функции случайности:
  - rand() → число с плавающей точкой в диапазоне [0, 1)
  - randint(a, b) → целое число от a до b включительно
  - choice(list) → случайный элемент из списка/кортежа
- Примеры:
  - name: RAND_F, mode: expr, value: rand()
    - "temperature": {{ RAND_F }}
  - name: DICE, mode: expr, value: randint(1, 6)
    - "dice_roll": {{ DICE }}
  - name: PICK_MODEL, mode: expr, value: choice(["gpt-4o-mini", "gpt-4o", "o3-mini"])
    - "model": "[[PICK_MODEL]]"
- Зерна/seed нет — каждый запуск выдаёт новое значение.

«Почему в expr нельзя подставлять переменные/макросы?»
- Для безопасности и предсказуемости: expr — это закрытый мини‑язык без окружения.
- Если нужно использовать другие переменные/макросы — делайте это в режиме string (там всё рендерится шаблонизатором).
- Технические детали: защита реализована в [SetVarsNode._safe_eval_expr()](agentui/pipeline/executor.py:291), а вставка string‑значений — через [render_template_simple()](agentui/pipeline/templating.py:184).

Как это работает внутри (если интересно)
- SetVars исполняется как обычная нода пайплайна и отдаёт {"vars": {...}}.
- Исполнитель добавляет эти значения в контекст для последующих нод как context.vars (см. [PipelineExecutor.run()](agentui/pipeline/executor.py:131)).
- При рендере шаблонов:
  - [[NAME]] и {{ NAME }} подставляются с приоритетом из пользовательских переменных (см. обработку в [render_template_simple()](agentui/pipeline/templating.py:184)).
- Сам SetVars считает переменные в порядке списка и возвращает их одним пакетом (внутри одной ноды значения не зависят друг от друга).

Частые вопросы
- «Хочу собрать строку с частями из внешнего запроса»: делайте mode=string и пишите: "Bearer [[VAR:incoming.headers.authorization]]".
- «Хочу массив случайных чисел»: mode=expr → [rand(), rand(), rand()], а в JSON: "numbers": {{ MY_LIST }}
- «Почему мои значения не сохраняются?» — нажмите «Сохранить параметры» в инспекторе ноды, затем «Сохранить пайплайн» в шапке. UI синхронизирует данные в node.data и сохраняет в pipeline.json (см. [static/editor.html](static/editor.html)).

Ссылки на реализацию (для любопытных)
- Нода переменных: [SetVarsNode](agentui/pipeline/executor.py:264), [SetVarsNode._safe_eval_expr()](agentui/pipeline/executor.py:291), [SetVarsNode.run()](agentui/pipeline/executor.py:354)
- Исполнитель/контекст vars: [PipelineExecutor.run()](agentui/pipeline/executor.py:131)
- Шаблоны и макросы (включая «голые» [[NAME]]/{{ NAME }}): [render_template_simple()](agentui/pipeline/templating.py:184)