POptimizer Portfolio Optimization

The project is built using the following technologies:

• Frontend: htmx
• Backend: asyncio Python
  • HTTP Client/Server: aiohttp
  • Data Storage: async PyMongo
  • Validation/Serialization: Pydantic
  • Model Training: PyTorch
  • Statistics & Optimization: SciPy

Core Methodology:

• Based on Modern Portfolio Theory (MPT), but uses forecast uncertainty instead of classical mean-variance optimization.
• Uses Ledoit-Wolf shrinkage for correlation matrix estimation of large asset sets.
• Uses an ensemble of neural networks formed via an evolutionary algorithm to predict risk and return.

The Dividends section handles dividend data required for accurate modeling:

• Initial Generation: On the first run, a dividend database is generated for the most liquid securities (suitable for portfolios of 200M+).
• Manual Entry: If your portfolio is smaller than 200M, you must manually fill in dividend information for other stocks.
• Updates: The system will send notifications to your configured Gmail account when dividend information needs updating. You can then edit this data in the Dividends section.

Use the following commands to manage the application version without modifying the source code:

• Update to the latest version: Ensure the latest version passes tests (check the GitHub Actions status), stop the running program with Ctrl-C, then run:

  task update_ver

• Update dividend data: To update dividend data for the most liquid stocks:

  task reset_div

• Revert to previous version: If an update fails or causes errors:

  task revert_ver

To avoid storing sensitive tokens (like Gmail passwords or Tinkoff tokens) in plain text in your configuration file, use the built-in keychain system. Secrets are stored in your operating system's secret storage for the poptimizer application.

Store a secret

uv run poptimizer keychain save YOUR_SECRET_KEY YOUR_SECRET_VALUE

Retrieve or delete a secret

• Get value: uv run poptimizer keychain get YOUR_SECRET_KEY
• Delete: uv run poptimizer keychain delete YOUR_SECRET_KEY

Use a secret in the configuration file

In your cfg/cfg.yaml, use the placeholder syntax keychain:YOUR_SECRET_KEY. The application will automatically replace this placeholder with the actual value from the keychain during loading.

uv run poptimizer keychain save MY_TOKEN my_actual_secret_value
# In cfg/cfg.yaml:
token: keychain:MY_TOKEN

POptimizer can automatically update account positions from Tinkoff.

1. Create a Read-only token from Tinkoff.
2. Run the following command to retrieve your account IDs:

   uv run poptimizer tinkoff YOUR_TOKEN

3. Save the token in the keychain.
4. In `cfg/cfg.yaml`, add the token using the `keychain:YOUR_TOKEN_KEY` placeholder. You can assign a custom account name (alphanumeric) in the config, which will be used in the web interface. You can map multiple accounts to one token or use different tokens for different accounts.

POptimizer is a Python application. Installation is currently documented for MacOS and requires Homebrew and Task.

1. Clone the repository:

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

2. Install necessary tools and dependencies using Task:

task install

POptimizer can send error alerts, key event notifications, portfolio value changes, and optimization recommendations to a Gmail address.

To set this up:

1. Create a Google App Password.
2. Save this password in the POptimizer keychain using the keychain save command.
3. In cfg/cfg.yaml, add your email address and use the keychain:YOUR_KEY_NAME placeholder for the password.

Application settings are stored in cfg/cfg.yaml.

• The file is optional; the application will run without it.
• On the first run, an empty cfg/cfg.yaml is created automatically.
• You can use cfg/cfg.yaml.template as a guide to populate the configuration file manually.
• You can selectively fill in only the sections you need.

Poptimizer supports storing sensitive information (like passwords or tokens) in the system keychain instead of plain text in configuration files. To use a secret from the keychain, prefix the value in your cfg.yaml file with keychain: followed by the secret key name.

When the application loads the configuration, it will look up the value in the system keychain using the poptimizer application identifier.

# Example in cfg.yaml
gmail:
  email: "user@example.com"
  password: "keychain:GMAIL_PASSWORD"

brokers:
  tinkoff:
    - token: "keychain:TINKOFF_TOKEN"
      name: "MyAccount"
      id: "1234567890"