> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantspace.limex.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# run_po_job

> Optimize portfolio weights from price data or ML/DL predictions

## Overview

`run_po_job` builds portfolio weights with [skfolio](https://skfolio.org).

* **Default:** `data_extractor_*.json` — no ML needed
* **With forecasts:** `ml_engine_*.json` / `nn_engine_*.json` — use predicted returns as μ (`mu_mode: custom`)

Ask for a method (equal weight, HRP, max Sharpe, DCC, …); skills fill the rest.

***

## Parameters

<ParamField body="input_url" type="string" required>
  Blob storage URL pointing to one of:

  * `data_extractor_*.json` — output of `run_data_extraction` (default path)
  * `ml_engine_*.json` — output of `run_ml_job`
  * `nn_engine_*.json` — output of `run_dl_job`
</ParamField>

<ParamField body="config" type="object" required>
  Portfolio optimization configuration.

  <Expandable title="config fields">
    <ParamField body="Optimization params" type="object" required>
      Method and estimation knobs.

      <Expandable title="Optimization params fields">
        <ParamField body="method" type="string" required>
          Optimization method (case-insensitive). Default when omitted: `"maxsharpe"`.

          **No-covariance** (no `covariance_mode` / `mu_mode` knobs):

          | Value                  | Strategy           |
          | ---------------------- | ------------------ |
          | `"equal_weighted"`     | Equal weight       |
          | `"inverse_volatility"` | Inverse volatility |
          | `"random"`             | Random portfolio   |

          **Covariance-based** (support `covariance_mode` + `mu_mode`):

          | Value                                              | Strategy                             |
          | -------------------------------------------------- | ------------------------------------ |
          | `"maxsharpe"`                                      | Mean-Risk — maximize Sharpe          |
          | `"minvol"` / `"minimize_volatility"`               | Mean-Risk — minimize volatility      |
          | `"hrp"`                                            | Hierarchical Risk Parity             |
          | `"herc"`                                           | Hierarchical Equal Risk Contribution |
          | `"risk_budgeting"`                                 | Risk Budgeting                       |
          | `"max_diversification"`                            | Maximum Diversification              |
          | `"distributionally_robust_cvar"` / `"robust_cvar"` | Distributionally Robust CVaR         |

          **DCC aliases** (auto-set `covariance_mode` to `"dcc"`):

          `"dcc_maxsharpe"`, `"dcc_minvol"`, `"dcc_hrp"`, `"dcc_herc"`, `"dcc_risk_budgeting"`, `"dcc_max_diversification"`, `"dcc_robust_cvar"`

          <Warning>
            Retired aliases — do **not** use: `meanvariance`, `mean_variance`, `sharpe`, `maximize_sharpe`, `dcc_sharpe`, `MeanVariance`, `markowitz`.
            Use `"maxsharpe"` / `"dcc_maxsharpe"` instead.
          </Warning>
        </ParamField>

        <ParamField body="covariance_mode" type="string">
          Covariance estimator for covariance-based methods. Default: `"empirical"`.
          Values: `"empirical"`, `"ew"`, `"ledoit_wolf"`, `"oas"`, `"denoise"`, `"detone"`, `"gerber"`, `"shrunk"`, `"graphical_lasso"`, `"dcc"`.
          DCC aliases force `"dcc"`.
        </ParamField>

        <ParamField body="mu_mode" type="string">
          Expected-return estimator: `"empirical"`, `"ew"`, or `"custom"` (ML/DL predictions as μ).
          Auto-default: `"empirical"` on data\_extraction input; `"custom"` on ml/nn engine input.
          On data\_extraction, `"custom"` is overridden to `"empirical"` (no ML predictions available).
        </ParamField>

        <ParamField body="min_weights" type="number">
          Per-asset lower bound (0–1). Default: `0`.
        </ParamField>

        <ParamField body="max_weights" type="number">
          Per-asset upper bound (0–1). Default: `1`.
        </ParamField>

        <ParamField body="covariance_window" type="integer">
          Rolling covariance window in trading days. Default: `40`.
          On the **no-ML** path this is also the warmup: the first `n` days estimate covariance;
          **everything after that is the evaluation window** (you do not pass a separate testing-end date).
          For DCC, estimation still uses the full train sample; the window mainly controls that warmup split.
        </ParamField>

        <ParamField body="rebalance_frequency" type="integer">
          Rebalance every N trading days. Default: `1` (daily). Example: `5` ≈ weekly, `21` ≈ monthly.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  **Without ML/DL:** only sample start + end upstream. The evaluated period is everything after the first `covariance_window` days — there is no extra testing-end date.
  **With ML/DL:** still start + end of the sample; model training uses the train cut from extraction when present.
</Note>

***

## Returns

```json theme={null}
{
  "status": "Succeeded",
  "output_url": "https://stqsnpprod.blob.core.windows.net/data/portfolio_optimization_35c1b5239d23.json",
  "output_name": "portfolio_optimization_35c1b5239d23.json",
  "execution_name": "po-job-abc123xyz"
}
```

| Field            | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| `status`         | Job terminal status (`Succeeded`)                             |
| `output_url`     | Full HTTPS URL to the output blob — pass to `run_trading_job` |
| `output_name`    | Blob filename                                                 |
| `execution_name` | Job execution ID for audit/debugging                          |

The blob contains `Weights`, `Prices`, and `Meta` (includes fallback flags if optimization falls back to equal weights).

***

## Example — default path (data → PO)

```json theme={null}
{
  "input_url": "https://stqsnpprod.blob.core.windows.net/data/data_extractor_2b510101b9b7.json",
  "config": {
    "Optimization params": {
      "method": "equal_weighted",
      "rebalance_frequency": 21
    }
  }
}
```

## Example — HRP with covariance mode

```json theme={null}
{
  "input_url": "https://stqsnpprod.blob.core.windows.net/data/data_extractor_2b510101b9b7.json",
  "config": {
    "Optimization params": {
      "method": "hrp",
      "covariance_mode": "empirical",
      "mu_mode": "empirical",
      "covariance_window": 40,
      "rebalance_frequency": 5
    }
  }
}
```

## Example — ML-enhanced path

```json theme={null}
{
  "input_url": "https://stqsnpprod.blob.core.windows.net/data/ml_engine_7d4e2a91c0bf.json",
  "config": {
    "Optimization params": {
      "method": "maxsharpe",
      "mu_mode": "custom"
    }
  }
}
```

***

## Resources

| Resource           | Value                     |
| ------------------ | ------------------------- |
| Container Apps Job | `po-job`                  |
| Container name     | `po-job`                  |
| Env vars injected  | `INPUT_URL`, `CONFIG`     |
| Output blob prefix | `portfolio_optimization_` |

***

## Next Step

Pass `output_url` to [`run_trading_job`](/tools/trading-job) as `input_url`.
Optional: [`run_plot_job`](/tools/plot-job), [`run_st_job`](/tools/st-job), [`run_risk_job`](/tools/risk-job).