POptimizer

https://github.com/wlm1ke/poptimizer
Admin
POptimizer is a Python application that automates long-term stock portfolio management using modern...
Tokens:9,345
Snippets:76
Trust Score:6.8
License:Unlicense
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run POptimizer Application via CLI

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Commands to install dependencies, initialize the database, and start the application server.

```bash
# Установка зависимостей и инструментов
task install

# Запуск MongoDB (необходимо выполнить один раз)
task mongo

# Запуск приложения
task run
# или напрямую
uv run poptimizer run

# Приложение будет доступно по адресу http://localhost:5000
# Остановка: Ctrl+C
```

--------------------------------

### Install Tools and Dependencies

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Install necessary development tools and project dependencies using the Task command. This is a required step after cloning the repository.

```bash
task install
```

--------------------------------

### Get All Accounts by Token

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Retrieves all accounts associated with a given token. This is typically used for initial setup or configuration.

```python
all_accounts = await client.get_accounts("t.xxx...")
# [Account(id='123', type='ACCOUNT_TYPE_TINKOFF', name='Брокерский')]
```

--------------------------------

### Configure POptimizer via cfg.yaml

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Example configuration file for setting up database connections, email notifications, and broker API access.

```yaml
# cfg/cfg.yaml - все настройки опциональны
mongo:
  uri: "mongodb://localhost:27017"
  db: "poptimizer"

server:
  url: "http://localhost:5000/"

# Уведомления на почту (требуется App Password для Gmail)
gmail:
  email: "your_email@gmail.com"
  password: "keychain:gmail_password"

# Автоматическое обновление позиций через Tinkoff API
brokers:
  tinkoff:
    - token: "keychain:tinkoff_token"
      name: "Acc1"
      id: "1234567890"
    - token: "keychain:tinkoff_token2"
      name: "IIS"
      id: "0987654321"
```

--------------------------------

### Start MongoDB Service

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Execute this command once to start the MongoDB service, which is required for Poptimizer. It registers a service to automatically launch MongoDB on system restarts.

```bash
task mongo
```

--------------------------------

### GET /

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Retrieves the main portfolio dashboard page containing aggregated portfolio data.

```APIDOC
## GET /

### Description
Displays the main portfolio dashboard with aggregated information across all accounts.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **HTML** (text/html) - Returns an HTML page containing the last update date, total portfolio value, HHI-based effective positions count, open positions count, and a list of positions with weights and costs.
```

--------------------------------

### Clone POptimizer Repository

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Clone the Poptimizer project repository to your local machine. This command is the first step in the installation process.

```bash
git clone --filter=blob:none https://github.com/WLM1ke/poptimizer.git && cd poptimizer
```

--------------------------------

### Run Poptimizer Application

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Start the Poptimizer application after setting up MongoDB. Access the web interface via the URL specified in cfg.yaml or the default http://localhost:5000.

```bash
task run
```

--------------------------------

### Event Bus Architecture

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Implements an asynchronous event-driven system for data processing. Requires repository and logger setup.

```python
from poptimizer.controllers.bus.msg import Bus, IgnoreErrorsPolicy, IndefiniteRetryPolicy
from poptimizer.use_cases.handler import AppStarted, Event
from poptimizer.adapters import mongo

# Создание шины сообщений
repo = mongo.Repo(mongo_db)
bus = Bus(logger, repo)

# Регистрация обработчика событий
class MyHandler:
    async def __call__(self, ctx, msg: AppStarted) -> None:
        portfolio = await ctx.get(Portfolio)
        # Обработка события...
        ctx.publish(NewEvent())  # Публикация нового события

# Политики обработки ошибок:
# IgnoreErrorsPolicy - игнорировать ошибки
# IndefiniteRetryPolicy - повторять с экспоненциальным backoff

bus.register_event_handler(MyHandler(), IndefiniteRetryPolicy)

# Запуск шины (публикует AppStarted при старте)
await bus.run()

# Оборачивание HTTP-обработчика
@bus.wrap
async def http_handler(ctx, request):
    portfolio = await ctx.get_for_update(Portfolio)
    portfolio.update_position(...)
    # События публикуются автоматически после завершения
```

--------------------------------

### Get Tinkoff Account IDs

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Run this command to retrieve account IDs for Tinkoff integration. Ensure you have your Tinkoff token ready.

```bash
uv run poptimizer tinkoff YOUR_TOKEN
```

--------------------------------

### GET /dividends/{ticker}

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Retrieves dividend information for a specific ticker.

```APIDOC
## GET /dividends/{ticker}

### Description
View dividend data for a specific asset.

### Parameters
#### Path Parameters
- **ticker** (string) - Required - The asset ticker
```

--------------------------------

### Get Secret Key Value

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Retrieve the current value of a secret key from the operating system's secret key store. This command is useful for verification.

```bash
uv run poptimizer keychain get YOUR_SECRET_KEY
```

--------------------------------

### Retrieve Forecasts and Optimization Recommendations

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoints to fetch expected returns, risk metrics, and buy/sell recommendations.

```bash
# Получение прогнозов по всем позициям
curl http://localhost:5000/forecast

# Ответ включает для каждой позиции:
# - ticker: тикер
# - weight: текущий вес в портфеле
# - mean: ожидаемая годовая доходность
# - std: стандартное отклонение (риск)
# - beta: бета к рынку
# - grad_lower/grad_upper: границы доверительного интервала градиента

# Получение рекомендаций на покупку/продажу
curl http://localhost:5000/optimization

# Ответ:
# - breakeven: точка безубыточности
# - buy: список позиций к покупке (отсортирован по grad_lower)
# - sell: список позиций к продаже (отсортирован по grad_upper)
```

--------------------------------

### WaveNet Neural Network Implementation

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Configures and executes a WaveNet architecture for return forecasting. Requires torch and specific domain modules.

```python
import torch
from poptimizer.domain.dl.wave_net.wave_net import Net
from poptimizer.domain.dl.wave_net.backbone import Cfg

# Конфигурация сети из генотипа
cfg = Cfg(
    use_bn=True,
    sub_blocks=2,
    kernels=3,
    residual_channels=8,
    gate_channels=8,
    skip_channels=8,
    head_channels=8,
    mixture_size=3,
)

# Создание сети
net = Net(
    cfg=cfg,
    history_days=365,      # дней истории для входа
    num_feat_count=21,     # числовых признаков
    emb_size=[100, 3, 10], # размеры эмбеддингов (ticker, type, sector)
    emb_seq_size=[7, 53, 31, 12, 366],  # размеры последовательных эмбеддингов
)

# Прямой проход
num_feat = torch.randn(32, 21, 365)      # [batch, features, time]
emb_feat = torch.randint(0, 100, (32, 3)) # [batch, embeddings]
emb_seq_feat = torch.randint(0, 7, (32, 5, 365))  # [batch, emb_seq, time]

distribution = net(num_feat, emb_feat, emb_seq_feat)
# MixtureSameFamily - смесь нормальных распределений

# Расчёт функции потерь (negative log-likelihood)
labels = torch.randn(32)
loss = -net.llh(num_feat, emb_feat, emb_seq_feat, labels)

# Получение прогноза
mean, std = net.forecast_mean_and_std(num_feat, emb_feat, emb_seq_feat)
# mean: [batch,] - ожидаемая доходность
# std: [batch,] - стандартное отклонение
```

--------------------------------

### Manage Evolutionary Model Training

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

System for training neural networks, tracking metrics, and managing evolutionary states.

```python
from poptimizer.domain.evolve.evolve import Model, Evolution, State
from poptimizer.domain.evolve.genotype import Genotype

# Создание модели с начальными генами
model = Model(uid=domain.UID("model_001"))
model.genes = Genotype().genes  # случайные начальные гены

# После обучения модели сохраняются метрики:
model.ret = 0.15          # доходность на тестовой выборке
model.alfa = [0.02, 0.03, 0.01]  # альфы по эпохам
model.llh = [-1.2, -1.1, -1.0]   # log-likelihood по эпохам
model.duration = 45.5     # время обучения в секундах

# Статистика для сравнения моделей (Beta-распределение)
model.alfa_diff.add([0.01, 0.02, -0.01])  # результаты сравнения
p_value = model.alfa_diff.p  # p-value для H0: модель не лучше базовой

# Создание дочерней модели через кроссовер
child_genes = model.make_child_genes(parent1, parent2, scale=0.1)

# Эволюционный процесс
evolution = Evolution(uid=domain.UID("evolution"))
evolution.init_new_day(
    day=domain.Day(2024, 6, 15),
    tickers=("SBER", "LKOH", "GMKN"),
    forecast_days=3
)

# Состояния эволюции:
# State.EVAL_NEW_BASE_MODEL - оценка новой базовой модели
# State.EVAL_MODEL - оценка обычной модели
# State.REEVAL_CURRENT_BASE_MODEL - переоценка текущей базовой
# State.CREATE_NEW_MODEL - создание новой модели
```

--------------------------------

### Manage Portfolio Domain Model

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Operations for creating accounts, updating positions, and calculating portfolio value.

```python
from poptimizer.domain.portfolio.portfolio import Portfolio, Position
from poptimizer.domain import domain

# Создание и управление портфелем
portfolio = Portfolio(uid=domain.UID("portfolio"))

# Создание счёта
portfolio.create_acount(domain.AccName("Main"))

# Позиция автоматически создаётся при загрузке данных MOEX
# Обновление количества акций на счёте
portfolio.update_position(
    acc_name=domain.AccName("Main"),
    ticker=domain.Ticker("SBER"),
    quantity=100  # должно быть кратно лоту
)

# Обновление денежных средств
portfolio.update_position(
    acc_name=domain.AccName("Main"),
    ticker=domain.Ticker("CASH"),
    quantity=50000
)

# Получение стоимости
total_value = portfolio.value()  # общая стоимость
account_value = portfolio.value(domain.AccName("Main"))  # по счёту

# Нормализованные позиции для оптимизации
normalized = portfolio.normalized_positions
# [NormalizedPosition(ticker='SBER', weight=0.15, norm_turnover=0.002, accounts=['Main'])]

# Эффективное число позиций (обратный HHI)
eff_positions = portfolio.effective_positions  # ~12.5

# Исключение тикера из рассмотрения
portfolio.exclude_ticker(domain.Ticker("GAZP"))
```

--------------------------------

### CLI PDF Report Generation

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Generates portfolio PDF reports using the CLI. Requires a minimum of 60 months of history.

```bash
# Генерация отчёта (требуется минимум 60 месяцев истории)
uv run poptimizer pdf \
  --day 2024-06-30 \
  --dividends 15000 \
  --investor1 100000 \
  --investor2 50000

# Отчёт сохраняется в reports/report YYYY-MM-DD/YYYY-MM-DD.pdf
# Содержит:
# - График накопленной доходности vs бенчмарк
# - Распределение активов в портфеле
# - Метрики риска и доходности по инвесторам
```

--------------------------------

### Access Portfolio Overview API

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoint to retrieve aggregated portfolio data including total value and position details.

```bash
# Получение данных портфеля
curl http://localhost:5000/

# Ответ: HTML-страница с данными:
# - Дата последнего обновления
# - Общая стоимость портфеля в рублях
# - Количество эффективных позиций (HHI-based)
# - Количество открытых позиций
# - Список позиций с весами и стоимостью
```

--------------------------------

### Manage Settings and Exclusions via REST API

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoints for retrieving settings, managing ticker exclusions, and toggling the application theme.

```bash
curl http://localhost:5000/settings
```

```bash
curl -X POST http://localhost:5000/exclude \
  -d "ticker=GAZP"
```

```bash
curl -X DELETE http://localhost:5000/exclude/GAZP
```

```bash
curl -X PATCH http://localhost:5000/theme/dark
```

--------------------------------

### Manage Forecast Domain Model

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Handling automated forecast updates and retrieving buy/sell recommendations.

```python
from poptimizer.domain.portfolio.forecasts import Forecast, Position

# Прогноз создаётся автоматически при обработке событий
forecast = Forecast(uid=domain.UID("forecast"))

# Проверка необходимости обновления прогноза
needs_update = forecast.update_required(portfolio_ver=42)
# True если: portfolio_ver > forecast.portfolio_ver или
#            sqrt(len(models)) - sqrt(forecasts_count) >= 1

# Получение рекомендаций на покупку/продажу
breakeven, buy_list, sell_list = forecast.buy_sell()

# breakeven: точка безубыточности (годовая доходность)
# buy_list: позиции к покупке, отсортированные по grad_lower DESC
# sell_list: позиции к продаже, отсортированные по grad_upper ASC

# Пример позиции прогноза:
# Position(
#     ticker='SBER',
#     weight=0.15,           # текущий вес
#     mean=0.12,             # ожидаемая доходность 12%
#     std=0.25,              # волатильность 25%
#     beta=1.1,              # бета к рынку
#     grad=0.05,             # градиент функции полезности
#     grad_lower=0.02,       # нижняя граница 95% CI
#     grad_upper=0.08,       # верхняя граница 95% CI
#     accounts=['Main']      # счета с позицией
# )
```

--------------------------------

### Manage Accounts via API

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoints for performing CRUD operations on accounts and updating asset quantities.

```bash
# Просмотр счёта
curl http://localhost:5000/accounts/Main

# Создание нового счёта
curl -X POST http://localhost:5000/accounts \
  -d "account=NewAccount"

# Удаление счёта (должен быть пустым)
curl -X DELETE http://localhost:5000/accounts/OldAccount

# Обновление позиции на счёте
curl -X PATCH http://localhost:5000/accounts/Main/SBER \
  -d "quantity=100"

# Обновление денежных средств (тикер CASH)
curl -X PATCH http://localhost:5000/accounts/Main/CASH \
  -d "quantity=50000"
```

--------------------------------

### Manage Dividends via API

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoint to view dividend data for a specific ticker.

```bash
# Просмотр дивидендов по тикеру
curl http://localhost:5000/dividends/SBER
```

--------------------------------

### Manage Secrets with Keychain

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Commands for storing, retrieving, and deleting sensitive credentials in the system keychain for use in configuration files.

```bash
# Сохранение секрета в keychain
uv run poptimizer keychain save gmail_password "your_app_password"
uv run poptimizer keychain save tinkoff_token "t.xxxx..."

# Получение значения секрета
uv run poptimizer keychain get gmail_password
# Output: Keychain secret gmail_password is your_app_password

# Удаление секрета
uv run poptimizer keychain delete old_token

# В cfg.yaml используйте заглушку:
# gmail:
#   password: "keychain:gmail_password"
```

--------------------------------

### CLI Maintenance Commands

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Utility commands for model statistics, performance metrics, and application maintenance tasks.

```bash
# Статистика по моделям
uv run poptimizer stats

# Метрики производительности моделей
uv run poptimizer metrics

# Анализ доходов
uv run poptimizer income

# Анализ риска
uv run poptimizer risk

# Обновление дивидендов из бэкапа
uv run poptimizer div
# или
task update_div

# Обновление версии приложения
task update_ver

# Откат на предыдущую версию
task revert_ver

# Запуск тестов
task test

# Линтинг и форматирование
task lint
task format
```

--------------------------------

### Portfolio Domain Model

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Class for representing an investment portfolio with positions, accounts, and exclusions.

```APIDOC
## Portfolio Management

### Description
This section details the usage of the `Portfolio` class for managing investment portfolios.

### Class
`Portfolio`

### Initialization
```python
from poptimizer.domain.portfolio.portfolio import Portfolio, Position
from poptimizer.domain import domain

portfolio = Portfolio(uid=domain.UID("portfolio"))
```

### Account Management
#### Create Account
```python
portfolio.create_acount(domain.AccName("Main"))
```

### Position Management
#### Update Position Quantity
```python
portfolio.update_position(
    acc_name=domain.AccName("Main"),
    ticker=domain.Ticker("SBER"),
    quantity=100  # must be a multiple of the lot size
)
```

#### Update Cash
```python
portfolio.update_position(
    acc_name=domain.AccName("Main"),
    ticker=domain.Ticker("CASH"),
    quantity=50000
)
```

### Portfolio Value
#### Total Value
```python
total_value = portfolio.value()  # total portfolio value
```

#### Account Value
```python
account_value = portfolio.value(domain.AccName("Main"))  # value of a specific account
```

### Portfolio Analysis
#### Normalized Positions
```python
normalized = portfolio.normalized_positions
# Example output:
# [NormalizedPosition(ticker='SBER', weight=0.15, norm_turnover=0.002, accounts=['Main'])]
```

#### Effective Number of Positions
```python
eff_positions = portfolio.effective_positions  # approximately 12.5
```

### Exclude Ticker
```python
portfolio.exclude_ticker(domain.Ticker("GAZP"))
```
```

--------------------------------

### Model Evolution

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Details on the evolutionary learning system for neural networks.

```APIDOC
## Model Evolution

### Description
This section covers the evolutionary learning system for neural networks used for return forecasting, focusing on the `Model` and `Evolution` classes.

### Model Class
#### Initialization
```python
from poptimizer.domain.evolve.evolve import Model, Evolution, State
from poptimizer.domain.evolve.genotype import Genotype

# Initialize a model with starting genes
model = Model(uid=domain.UID("model_001"))
model.genes = Genotype().genes  # random initial genes
```

#### Training Metrics
# After training, models store metrics:
```python
model.ret = 0.15          # return on test set
model.alfa = [0.02, 0.03, 0.01]  # alphas per epoch
model.llh = [-1.2, -1.1, -1.0]   # log-likelihood per epoch
model.duration = 45.5     # training time in seconds
```

#### Statistical Comparison
# Statistics for comparing models (Beta-distribution):
```python
model.alfa_diff.add([0.01, 0.02, -0.01])  # results of comparison
p_value = model.alfa_diff.p  # p-value for H0: model is not better than baseline
```

#### Child Model Creation
```python
# Create a child model via crossover
child_genes = model.make_child_genes(parent1, parent2, scale=0.1)
```

### Evolution Class
#### Initialization and Daily Update
```python
# Evolutionary process
evolution = Evolution(uid=domain.UID("evolution"))
evolution.init_new_day(
    day=domain.Day(2024, 6, 15),
    tickers=("SBER", "LKOH", "GMKN"),
    forecast_days=3
)
```

#### Evolution States
# States of the evolution process:
```python
# State.EVAL_NEW_BASE_MODEL - evaluating a new base model
# State.EVAL_MODEL - evaluating a regular model
# State.REEVAL_CURRENT_BASE_MODEL - re-evaluating the current base model
# State.CREATE_NEW_MODEL - creating a new model
```
```

--------------------------------

### Forecast and Optimization Endpoints

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoints for retrieving asset forecasts and portfolio optimization recommendations.

```APIDOC
## GET /forecast

### Description
Retrieves expected return and risk metrics for all positions.

### Response
#### Success Response (200)
- **ticker** (string) - Asset ticker
- **weight** (number) - Current portfolio weight
- **mean** (number) - Expected annual return
- **std** (number) - Standard deviation (risk)
- **beta** (number) - Market beta
- **grad_lower/grad_upper** (number) - Gradient confidence interval boundaries

## GET /optimization

### Description
Retrieves buy/sell recommendations based on portfolio optimization.

### Response
#### Success Response (200)
- **breakeven** (number) - Break-even point
- **buy** (array) - List of tickers to buy, sorted by grad_lower
- **sell** (array) - List of tickers to sell, sorted by grad_upper
```

--------------------------------

### Tinkoff API Integration

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Configures and retrieves portfolio positions from Tinkoff Invest API.

```python
from poptimizer.adapters.brokers.tinkoff import Client
from poptimizer.cli.config import Account

# Конфигурация счетов
accounts = [
    Account(
        token="t.xxx...",
        name="Main",
        id="1234567890"
    )
]

# Создание клиента
client = Client(http_session, accounts)

# Получение списка обновляемых счетов
updatable = client.updatable_accounts()  # {'Main'}

# Получение текущих позиций
positions = await client.get_positions("Main")
# Positions(
```

--------------------------------

### Retrieve Tinkoff Account IDs

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Command to list available brokerage accounts associated with a provided Tinkoff API token.

```bash
# Получение списка счетов по токену
uv run poptimizer tinkoff "t.your_readonly_token_here"

# Output:
# Account(id='1234567890', type='ACCOUNT_TYPE_TINKOFF', name='Брокерский')
# Account(id='0987654321', type='ACCOUNT_TYPE_TINKOFF_IIS', name='ИИС')

# Используйте полученные ID в cfg.yaml:
# brokers:
#   tinkoff:
#     - token: "keychain:tinkoff_token"
#       name: "Main"
#       id: "1234567890"
```

--------------------------------

### Update Dividend Data

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Update dividend data for highly liquid stocks. This is an optional step and manual input is recommended for less liquid positions.

```bash
task update_div
```

--------------------------------

### Account Management Endpoints

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoints for viewing, creating, deleting accounts, and updating asset quantities.

```APIDOC
## GET /accounts/{account}

### Description
Retrieves details for a specific account.

## POST /accounts

### Description
Creates a new account.

### Request Body
- **account** (string) - Required - Name of the new account

## DELETE /accounts/{account}

### Description
Deletes an existing account (must be empty).

## PATCH /accounts/{account}/{ticker}

### Description
Updates the quantity of a specific asset or cash (ticker 'CASH') in an account.

### Parameters
#### Path Parameters
- **account** (string) - Required - Account name
- **ticker** (string) - Required - Asset ticker or 'CASH'

#### Request Body
- **quantity** (number) - Required - New quantity value
```

--------------------------------

### Manage Dividends via REST API

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Use PATCH requests to add or remove dividend records for a specific ticker.

```bash
curl -X PATCH http://localhost:5000/dividends/SBER/add \
  -d "day=2024-06-15" \
  -d "dividend=33.3"
```

```bash
curl -X PATCH http://localhost:5000/dividends/SBER/remove \
  -d "day=2024-06-15" \
  -d "dividend=33.3"
```

--------------------------------

### Save Secret Key to Keychain

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Save a secret key and its value to the operating system's secret key store. This is used for securely managing sensitive information required by POptimizer.

```bash
uv run poptimizer keychain save YOUR_SECRET_KEY YOUR_SECRET_VALUE
```

--------------------------------

### Settings and Exclusions API

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoints for managing application settings and excluded tickers.

```APIDOC
## GET /settings

### Description
Retrieves the application settings.

### Method
GET

### Endpoint
`/settings`

### Request Example
```bash
curl http://localhost:5000/settings
```

## POST /exclude

### Description
Adds a ticker to the exclusion list.

### Method
POST

### Endpoint
`/exclude`

### Parameters
#### Request Body
- **ticker** (string) - Required - The ticker symbol to exclude.

### Request Example
```bash
curl -X POST http://localhost:5000/exclude \
  -d "ticker=GAZP"
```

## DELETE /exclude/{ticker}

### Description
Removes a ticker from the exclusion list.

### Method
DELETE

### Endpoint
`/exclude/{ticker}`

### Parameters
#### Path Parameters
- **ticker** (string) - Required - The ticker symbol to remove from exclusions.

### Request Example
```bash
curl -X DELETE http://localhost:5000/exclude/GAZP
```

## PATCH /theme/{theme}

### Description
Switches the application theme between dark and light mode.

### Method
PATCH

### Endpoint
`/theme/{theme}`

### Parameters
#### Path Parameters
- **theme** (string) - Required - The desired theme ('dark' or 'light').

### Request Example
```bash
curl -X PATCH http://localhost:5000/theme/dark
```
```

--------------------------------

### Forecast Domain Model

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Class for storing aggregated forecasts and calculating recommendations.

```APIDOC
## Forecast Management

### Description
This section describes the `Forecast` class used for storing predictions and generating buy/sell recommendations.

### Class
`Forecast`

### Initialization
```python
from poptimizer.domain.portfolio.forecasts import Forecast, Position

# Forecast is created automatically upon event processing
forecast = Forecast(uid=domain.UID("forecast"))
```

### Update Check
#### Check if Update is Required
```python
needs_update = forecast.update_required(portfolio_ver=42)
# Returns True if:
# portfolio_ver > forecast.portfolio_ver or
# sqrt(len(models)) - sqrt(forecasts_count) >= 1
```

### Recommendations
#### Get Buy/Sell Recommendations
```python
breakeven, buy_list, sell_list = forecast.buy_sell()

# breakeven: breakeven point (annualized return)
# buy_list: positions to buy, sorted by grad_lower DESC
# sell_list: positions to sell, sorted by grad_upper ASC
```

### Forecast Position Example
```python
# Example of a forecast position:
# Position(
#     ticker='SBER',
#     weight=0.15,           # current weight
#     mean=0.12,             # expected return 12%
#     std=0.25,              # volatility 25%
#     beta=1.1,              # market beta
#     grad=0.05,             # utility function gradient
#     grad_lower=0.02,       # lower bound of 95% CI
#     grad_upper=0.08,       # upper bound of 95% CI
#     accounts=['Main']      # accounts with the position
# )
```
```

--------------------------------

### Revert POptimizer Version

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Revert to the previous version of Poptimizer if errors occur during an update. This command helps in rolling back to a stable state.

```bash
task revert_ver
```

--------------------------------

### Ledoit-Wolf Shrinkage Risk Assessment

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Estimates covariance and correlation matrices using Ledoit-Wolf shrinkage. Useful for portfolio optimization to handle noisy sample matrices.

```python
import numpy as np
from poptimizer.domain.dl.ledoit_wolf import shrinkage, ledoit_wolf_cor

# Исторические доходности: t наблюдений, n активов
returns = np.random.randn(252, 50)  # 252 дня, 50 активов

# Оценка ковариационной матрицы
cov_matrix, avg_correlation, shrink_factor = shrinkage(returns)

# cov_matrix: [50, 50] - сжатая ковариационная матрица
# avg_correlation: ~0.3 - средняя корреляция
# shrink_factor: ~0.2 - коэффициент сжатия (0 = sample, 1 = prior)

# Оценка корреляционной матрицы (нормализованные доходности)
cor_matrix, avg_cor, shrink = ledoit_wolf_cor(returns.T)

# Использование в портфельной оптимизации:
# portfolio_variance = weights.T @ cov_matrix @ weights
weights = np.ones(50) / 50  # равновзвешенный портфель
portfolio_std = np.sqrt(weights @ cov_matrix @ weights)
```

--------------------------------

### Dividend Management API

Source: https://context7.com/wlm1ke/poptimizer/llms.txt

Endpoints for adding and removing dividend records.

```APIDOC
## PATCH /dividends/{ticker}/add

### Description
Adds a dividend record for a specific ticker on a given day.

### Method
PATCH

### Endpoint
`/dividends/{ticker}/add`

### Parameters
#### Path Parameters
- **ticker** (string) - Required - The ticker symbol for the dividend.

#### Query Parameters
- **day** (string) - Required - The date of the dividend in YYYY-MM-DD format.
- **dividend** (string) - Required - The dividend amount.

### Request Example
```bash
curl -X PATCH http://localhost:5000/dividends/SBER/add \
  -d "day=2024-06-15" \
  -d "dividend=33.3"
```

## PATCH /dividends/{ticker}/remove

### Description
Removes a dividend record for a specific ticker on a given day.

### Method
PATCH

### Endpoint
`/dividends/{ticker}/remove`

### Parameters
#### Path Parameters
- **ticker** (string) - Required - The ticker symbol for the dividend.

#### Query Parameters
- **day** (string) - Required - The date of the dividend in YYYY-MM-DD format.
- **dividend** (string) - Required - The dividend amount.

### Request Example
```bash
curl -X PATCH http://localhost:5000/dividends/SBER/remove \
  -d "day=2024-06-15" \
  -d "dividend=33.3"
```
```

--------------------------------

### Update POptimizer Version

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Update the Poptimizer application to the latest version. This command is intended for users who do not modify the program's code.

```bash
task update_ver
```

--------------------------------

### Delete Secret Key from Keychain

Source: https://github.com/wlm1ke/poptimizer/blob/master/README.md

Delete a secret key from the operating system's secret key store. Use this command when a secret is no longer needed.

```bash
uv run poptimizer keychain delete YOUR_SECRET_KEY
```
Tokens:
Raw