nifodea/AGENTS.md

AGENTS.md — контекст для AI-сессий

Project Overview

CashFlow Forecast — личная финансовая модель с прогнозом денежных потоков. Python CLI-инструмент.

Цель: отвечать на вопрос "что произойдет дальше?" (forecast), а не "что произошло?" (accounting).

Стек: Python 3.11+, JSON (хранение), openpyxl (Excel), typer (CLI), rich (вывод), pytest (тесты), ruff (линтер).

Тип проекта: greenfield, MVP реализован.

---

Quick Start

source .venv/bin/activate
cf init
cf forecast --months 12
pytest
ruff check .

---

Архитектура

Модульный монолит (layered):

[CLI / Excel File]
       |
       v
  sync/  -->  cashflow_model/  -->  engine/  -->  ai/
 (Excel R/W)    (Entity Model)     (Forecast)     (Prompts)
       |              |                |
       v              v                v
    data/model.json  data/model.json  data/model.json

Поток данных:

1. Excel -> sync (импорт) -> JSON
2. JSON -> cashflow_model (dataclass)
3. engine (forecast) читает модель
4. ai (assistant) анализирует результаты
5. Результаты -> sync (экспорт) -> Excel

---

Модули

Модуль	Ответственность	Ключевые файлы
cashflow_model/	dataclass-сущности + JSON serialization	model.py, account.py, transaction.py, recurring.py, asset.py, liability.py, scenario.py
engine/	ForecastService, ScenarioService	forecast.py, scenarios.py
sync/	Excel <-> JSON	excel_sync.py
ai/	Промпты, AssistantService (заглушка)	prompts.py, assistant.py
cli/	Typer CLI	main.py

---

Data Model

Account

Поле	Тип
id	UUID
name	str
currency	str (default USD)
balance	float

Transaction

Поле	Тип
id	UUID
date	str (ISO)
account	str (UUID счёта)
category	str
amount	float (positive=income, negative=expense)
description	str

RecurringCashflow

Поле	Тип
id	UUID
start_date	str (ISO)
end_date	str (ISO, optional)
frequency	str (monthly/weekly/yearly)
amount	float
category	str

Asset

Поле	Тип
id	UUID
name	str
value	float
growth_rate	float (% годовых)

Liability

Поле	Тип
id	UUID
name	str
balance	float
interest	float (% годовых)
payment	float (ежемесячный)

ForecastScenario

Поле	Тип
id	UUID
name	str (baseline/optimistic/pessimistic)
income_multiplier	float
expense_multiplier	float
growth_multiplier	float

FinancialModel — корневой объект, содержит списки всех сущностей. Методы: save(path), load(path). JSON-файл в data/model.json.

---

CLI Reference

Команда cf (entry point: cli.main:app):

Команда	Аргументы	Описание
init	—	Создать пустую модель
forecast	--months 12	Прогноз cashflow
scenario	<name>	Сценарий baseline/optimistic/pessimistic
whatif	--income 1.0 --expense 1.0 --growth 1.0	What-if анализ
compare	--months 12	Сравнение сценариев
import	<path.xlsx>	Импорт из Excel
export	<path.xlsx>	Экспорт в Excel
analyze	--months 12	AI-анализ (промпт + заглушка)

---

Coding Conventions

• Python 3.11+, dataclass для моделей
• from_dict/to_dict для JSON-сериализации
• ruff (E, F, I, N, W), line-length=100
• pytest для тестов
• typer + rich для CLI
• f-строки, без лишних комментариев
• Имена: snake_case, классы PascalCase

---

Commands

pytest              # запуск тестов (26 tests)
ruff check .        # линтер
ruff format .       # автоформат
cf <command>        # запуск CLI

---

Known Issues / TODOs

• AI-ассистент — заглушка (ai/assistant.py). Промпты готовы, нужно подключить API (OpenAI и т.д.)
• Нет лицензии — требуется выбрать
• JSON-файлы — нет конкурентного доступа
• Excel — только .xlsx (openpyxl), нет поддержки Google Sheets
• Нет веб-интерфейса, только CLI
• engine/forecast.py — упрощённый алгоритм (без Monte Carlo)

---

.agent/ directory

Директория .agent/ содержит артефакты MetaAgent — планирование, дизайн, декомпозицию задач. Не удалять. Там же checkpoints.json с состоянием задач.

---

Границы (Boundaries)

Что НЕ входит в задачу AI-агента:

• Изменение архитектуры без обсуждения с пользователем
• Подключение внешних платных API без согласования
• Массовый рефакторинг без acceptance criteria
• Удаление .agent/ или README.arch.md