ADR-0006-Financial-Calculations-Outside-LLM

ADR-0006: Финансовые расчёты выполняются вне LLM

Status

proposed (будет accepted при реализации FinancialModeler)

Context

Agent-FinancialModeler должен производить финансовые модели (CAPEX/OPEX, P&L, unit economics, 3 сценария пессимистичный/ реалистичный/оптимистичный).

Известная проблема: LLM плохо считает арифметику на сложных моделях с 20+ связанными переменными. Даже Sonnet/Opus делают арифметические ошибки, особенно:

• compound growth rates over N periods
• умножение с percentage conversions
• arithmetic в рамках длинных таблиц (cumulative errors)
• conversion между currencies / units

Если доверить LLM все расчёты — получим “красиво выглядящие, но математически неверные модели”. Это invalidates всю ценность финансовой модели.

Decision

FinancialModeler использует Python tool для всех расчётов.

Поток работы:

1. LLM получает market data от Scout + Researcher.
2. LLM проектирует структуру модели (какие статьи CAPEX/OPEX, какие revenue streams, какие drivers влияют на что).
3. LLM вызывает tool financial_calc со спецификацией модели как структурированный вход (JSON: inputs, formulas, periods).
4. Tool выполняет расчёты на Python (deterministic, verifiable).
5. LLM получает числовые результаты обратно.
6. LLM интерпретирует результаты, пишет narrative, делает допущения явными.
7. LLM возвращает финальный report (текст + структурированные числа от tool).

Tool реализован как sandbox Python execution (не eval) — ограниченный набор операций (arithmetic, numpy-like ops, tabular calc).

Alternatives considered

Option A: LLM сам считает всё

• Pros: Просто, нет дополнительной infrastructure.
• Cons: Арифметические ошибки неизбежны, доверие к числам низкое, основная ценность модуля (точная модель) подорвана.

Option B: LLM описывает модель, Python считает отдельным шагом

(sequential, не tool use)

• Pros: Детерминистично.
• Cons: LLM не может итерировать — если первый расчёт показал нереалистичный CAC, модель должна переделать допущения. Без tool use это требует множественных round-trips.

Option C (chosen): LLM + Python tool через tool use

• Pros: LLM может итерировать модель на основе результатов, расчёты детерминистичны, auditable, воспроизводимы.
• Cons: Требует Python sandbox infrastructure (сложность безопасности).

Consequences

Positive

• Финансовые модели математически корректны by construction.
• Результаты воспроизводимы — тот же input даёт тот же output.
• Audit-friendly: каждый расчёт записан с формулой + input + output.
• LLM фокусируется на reasoning о модели, не на арифметике.
• Переиспользуемость: financial_calc tool полезен и в других контекстах (cash flow projections, pricing analysis).

Negative / Trade-offs

• Python sandbox = security risk surface. Требует isolation (subprocess с resource limits, запрет network, filesystem ro).
• Tool-use цикл добавляет latency (каждая итерация = 2+ LLM calls).
• Ограничения sandbox могут блокировать legitimate use cases (например, stats libraries).

Mitigations

• Использовать RestrictedPython или subprocess с seccomp/nsjail.
• Timeout: 10 seconds per calculation.
• Memory limit: 256 MB.
• No network access.
• Whitelist библиотек (math, statistics, decimal, возможно numpy позже).
• Логировать каждый tool call в artifacts для аудита.

Follow-ups

• Week 3: реализовать python_calc tool как generic tool.
• Module M1: FinancialModeler с tool use loop.
• Добавить eval test: 10 известных моделей (known-correct results), проверить что tool возвращает правильные числа.
• Политика: FinancialModeler не может выдавать числа без вызова tool (enforced в system prompt + проверка Judge).

References

• Agent-FinancialModeler
• Niche-Evaluation-Module
• Policy-Layer
• Anthropic docs on tool use: https://docs.claude.com/en/docs/build-with-claude/tool-use