oqyude/nifodea
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

beginning

Browse Source
This commit is contained in:
oqyude
2026-07-12 19:51:00 +03:00
parent 940d25435e
commit 5afea8238c
3 changed files with 473 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+186
View File
@@ -0,0 +1,186 @@
# 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
```bash
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
```bash
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`
README.arch.md
+193
View File
@@ -0,0 +1,193 @@
# CashFlow Forecast
Простой open-source проект для построения и анализа личной финансовой модели с использованием Spreadsheet, Python и AI.
## Идея
Большинство приложений для учета финансов отвечают на вопрос:
> "Что произошло?"
Этот проект пытается ответить на другой вопрос:
> "Что произойдет дальше?"
Основная цель — построение прогнозной модели денежных потоков (Cash Flow Forecasting), позволяющей моделировать различные сценарии будущего.
## Принципы
- Spreadsheet используется как удобный визуальный редактор.
- Python является вычислительным ядром системы.
- JSON служит внутренним представлением модели данных.
- AI используется как инструмент анализа и взаимодействия с моделью.
- Все компоненты должны быть взаимозаменяемыми.
## Архитектура
```
User
│
▼
Spreadsheet (UI)
│
Synchronization Layer
(Python)
│
▼
Financial Model
(JSON)
│
┌───────────┴───────────┐
▼ ▼
Forecast Engine AI Assistant
Scenario Analysis Data Analysis
```
Spreadsheet рассматривается как пользовательский интерфейс, а не как источник бизнес-логики.
## Основные сущности
```
Accounts
Transactions
Assets
Liabilities
Recurring Cashflows
Forecast Scenarios
Parameters
```
### Account
```
id
name
currency
balance
```
### Transaction
```
id
date
account
category
amount
description
```
### Recurring Cashflow
```
id
start_date
end_date
frequency
amount
category
```
### Asset
```
id
name
value
growth_rate
```
### Liability
```
id
name
balance
interest
payment
```
## Основной цикл
```
Spreadsheet
│
▼
Python Import
│
▼
JSON Model
│
▼
Forecast Calculation
│
▼
Scenario Simulation
│
▼
AI Analysis
│
▼
Spreadsheet Export
```
## Возможности
- прогноз денежных потоков;
- моделирование бюджета;
- сценарный анализ;
- учет активов и обязательств;
- прогноз ликвидности;
- анализ финансовой устойчивости;
- моделирование достижения финансовых целей;
- анализ "что если" (What-if Analysis).
## Будущие возможности
- Monte-Carlo Simulation;
- FIRE Planning;
- инвестиционный прогноз;
- импорт банковских выписок;
- импорт брокерских отчетов;
- REST API;
- Web UI;
- Mobile App;
- AI Financial Assistant.
## Структура репозитория
```
cashflow-forecast/
├── README.md
├── spreadsheet/
│ model.xlsx
│
├── data/
│ model.json
│
├── sync/
│ excel_sync.py
│
├── engine/
│ forecast.py
│ scenarios.py
│
├── ai/
│ prompts.py
│ assistant.py
│
├── exports/
│
└── docs/
```
## Долгосрочная идея
На ранних этапах Spreadsheet используется как быстрый инструмент проектирования финансовой модели.
По мере развития проекта вычисления и логика постепенно переносятся в Python, а Spreadsheet превращается исключительно в средство отображения и редактирования данных.
Конечной целью является независимый интерактивный open-source инструмент для персонального финансового планирования и прогнозирования денежных потоков, в котором AI выступает естественным интерфейсом для анализа и построения сценариев.
README.md
+94 -169
View File
@@ -1,193 +1,118 @@
# CashFlow Forecast
Простой open-source проект для построения и анализа личной финансовой модели с использованием Spreadsheet, Python и AI.
Личная финансовая модель с прогнозом денежных потоков, сценарным анализом и AI-ассистентом.
## Идея
Python + JSON + Excel + AI.
Большинство приложений для учета финансов отвечают на вопрос:
## Установка
> "Что произошло?"
Этот проект пытается ответить на другой вопрос:
> "Что произойдет дальше?"
Основная цель — построение прогнозной модели денежных потоков (Cash Flow Forecasting), позволяющей моделировать различные сценарии будущего.
## Принципы
- Spreadsheet используется как удобный визуальный редактор.
- Python является вычислительным ядром системы.
- JSON служит внутренним представлением модели данных.
- AI используется как инструмент анализа и взаимодействия с моделью.
- Все компоненты должны быть взаимозаменяемыми.
## Архитектура
```
User
│
▼
Spreadsheet (UI)
│
Synchronization Layer
(Python)
│
▼
Financial Model
(JSON)
│
┌───────────┴───────────┐
▼ ▼
Forecast Engine AI Assistant
Scenario Analysis Data Analysis
```bash
git clone <repo>
cd cashflow-forecast
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
pip install -e .
```
Spreadsheet рассматривается как пользовательский интерфейс, а не как источник бизнес-логики.
## Использование
## Основные сущности
```bash
# Инициализация пустой модели
cf init
```
Accounts
Transactions
Assets
Liabilities
Recurring Cashflows
Forecast Scenarios
Parameters
# Прогноз на 12 месяцев
cf forecast --months 12
# Сценарии
cf scenario baseline
cf scenario optimistic
cf scenario pessimistic
# What-if анализ
cf whatif --income 1.2 --expense 0.9 --growth 1.0 --months 12
# Сравнение всех сценариев
cf compare --months 12
# Импорт/экспорт Excel
cf import data.xlsx
cf export exports/report.xlsx
# AI-анализ (заглушка, генерация промпта)
cf analyze
```
### Account
### Пример: создание тестовых данных
```
id
name
currency
balance
Подготовьте Excel-файл с листами: `Accounts`, `Transactions`, `Recurring`, `Assets`, `Liabilities`. Заголовки колонок соответствуют полям моделей. Затем импортируйте:
```bash
cf import my_finances.xlsx
cf forecast --months 12
```
### Transaction
## Структура проекта
```
id
date
account
category
amount
description
├── cashflow_model/ # Модели данных (dataclass + JSON)
│ ├── account.py # Account
│ ├── transaction.py # Transaction
│ ├── recurring.py # RecurringCashflow
│ ├── asset.py # Asset
│ ├── liability.py # Liability
│ ├── scenario.py # ForecastScenario
│ └── model.py # FinancialModel (корень, save/load JSON)
├── engine/ # Вычислительное ядро
│ ├── forecast.py # ForecastService — прогноз
│ └── scenarios.py # ScenarioService — сценарии + what-if
├── sync/ # Синхронизация с Excel
│ └── excel_sync.py # ExcelSync — import/export .xlsx
├── ai/ # AI-ассистент
│ ├── prompts.py # Шаблоны промптов
│ └── assistant.py # AssistantService (заглушка)
├── cli/ # CLI (Typer)
│ └── main.py # Команды: cf init/forecast/scenario/...
├── tests/ # Тесты pytest
│ ├── conftest.py # Фикстуры
│ ├── test_model.py
│ ├── test_forecast.py
│ ├── test_scenarios.py
│ ├── test_excel_sync.py
│ ├── test_ai.py
│ └── test_cli.py
├── data/ # JSON-модели
├── exports/ # Экспортированные .xlsx
├── .agent/ # Артефакты MetaAgent (планирование)
├── pyproject.toml # Зависимости и конфигурация
└── README.arch.md # Оригинальная архитектурная концепция
```
### Recurring Cashflow
## Разработка
```
id
start_date
end_date
frequency
amount
category
```bash
# Тесты
pytest
# Линтер
ruff check .
# Автоформат
ruff format .
```
### Asset
### Зависимости
```
id
name
value
growth_rate
```
- Python >= 3.11
- openpyxl — работа с Excel
- typer — CLI
- rich — форматирование вывода
- pytest — тесты
- ruff — линтер
### Liability
## Известные ограничения (MVP)
```
id
name
balance
interest
payment
```
## Основной цикл
```
Spreadsheet
│
▼
Python Import
│
▼
JSON Model
│
▼
Forecast Calculation
│
▼
Scenario Simulation
│
▼
AI Analysis
│
▼
Spreadsheet Export
```
## Возможности
- прогноз денежных потоков;
- моделирование бюджета;
- сценарный анализ;
- учет активов и обязательств;
- прогноз ликвидности;
- анализ финансовой устойчивости;
- моделирование достижения финансовых целей;
- анализ "что если" (What-if Analysis).
## Будущие возможности
- Monte-Carlo Simulation;
- FIRE Planning;
- инвестиционный прогноз;
- импорт банковских выписок;
- импорт брокерских отчетов;
- REST API;
- Web UI;
- Mobile App;
- AI Financial Assistant.
## Структура репозитория
```
cashflow-forecast/
├── README.md
├── spreadsheet/
│ model.xlsx
│
├── data/
│ model.json
│
├── sync/
│ excel_sync.py
│
├── engine/
│ forecast.py
│ scenarios.py
│
├── ai/
│ prompts.py
│ assistant.py
│
├── exports/
│
└── docs/
```
## Долгосрочная идея
На ранних этапах Spreadsheet используется как быстрый инструмент проектирования финансовой модели.
По мере развития проекта вычисления и логика постепенно переносятся в Python, а Spreadsheet превращается исключительно в средство отображения и редактирования данных.
Конечной целью является независимый интерактивный open-source инструмент для персонального финансового планирования и прогнозирования денежных потоков, в котором AI выступает естественным интерфейсом для анализа и построения сценариев.
- **AI-ассистент** — заглушка. Промпты готовы, но не подключены к API.
- **База данных** — JSON-файлы (не подходит для многопользовательской работы).
- **Excel** — только `.xlsx` через openpyxl.
- **Лицензия** — не выбрана.