Regime-dependent stochastic transaction cost process

[stranske]

Why

Add a cost process that samples per-rebalance transaction costs conditional on regime (and optionally turnover/volatility).

Add a cost process that samples per-rebalance transaction costs conditional on regime (and optionally turnover/volatility).

Parent Epic: #4156
Depends on: #4162 (regime labeling)

Configuration

costs:
  kind: regime_stochastic
  calm:
    trade_cost_bps:
      dist: lognormal
      mean: 6
      sigma: 0.25
    slippage_multiplier: 1.0
  stress:
    trade_cost_bps:
      dist: lognormal
      mean: 18
      sigma: 0.35
    slippage_multiplier: 1.5

Scope

Not provided.

TODO: define scope and boundaries.

Non-Goals

Not provided.

TODO: list explicit exclusions.

Tasks

• Implement regime-aware CostProcess with configurable distributions (lognormal, etc.) in src/trend_analysis/monte_carlo/costs.py.
  • Implement the CostProcess class structure. (verify: confirm completion in repo)
  • Define (verify: confirm completion in repo)
  • implement configurable distributions (e.g. (verify: config validated)
  • lognormal). (verify: config validated)
  • Add regime-awareness logic to the CostProcess. (verify: confirm completion in repo)
• Integrate cost sampling into runner.py with regime inputs.
  • Modify runner.py to accept regime inputs. (verify: confirm completion in repo)
  • Integrate cost sampling logic into the runner. (verify: confirm completion in repo)
  • Test the integration with sample inputs. (verify: confirm completion in repo)
• Record per-period realized costs and total cost drag in summary outputs.
• Add unit tests for distributions, regimes, and integration behavior in tests/monte_carlo/test_costs.py.
  • Add unit tests for configurable distributions (e.g. (verify: tests pass)
  • lognormal). (verify: confirm completion in repo)
  • Add unit tests for regime-specific behavior. (verify: tests pass)
  • Add integration tests for the CostProcess in the runner. (verify: tests pass)
• ## Cost Process Output (Per Rebalance)
• Expected cost in basis points
• Optional slippage multiplier by regime
• Applied to portfolio turnover
• Implement regime-aware CostProcess with configurable distributions (lognormal, etc.).
• Integrate cost sampling into runner/evaluation with regime inputs.
• Record per-period realized costs and total cost drag in summary outputs.
• Add tests for distributions, regimes, and integration behavior.

Acceptance Criteria

• Costs vary across time with regime.
• Lognormal sampling produces reasonable cost distributions.
• Stress regime has higher mean and variance.
• Output bundle includes realized costs per period.
• Total cost drag reported in summary metrics.
• Integrates with existing cost model (no new reporting universe).
• Unit tests for each distribution type and regime pass.
• Costs vary across time with regime
• Lognormal sampling produces reasonable cost distributions
• Stress regime has higher mean and variance
• Output bundle includes realized costs per period
• Total cost drag reported in summary metrics
• Integrates with existing cost model (no new reporting universe)
• Unit tests for each distribution type and regime
• ## Files to Create/Modify
• src/trend_analysis/monte_carlo/costs.py
• Integrate with runner.py
• tests/monte_carlo/test_costs.py

Implementation Notes

File paths to modify: src/trend_analysis/monte_carlo/costs.py, runner.py, tests/monte_carlo/test_costs.py.
Configuration example:

costs:
  kind: regime_stochastic
  calm:
    trade_cost_bps:
      dist: lognormal
      mean: 6
      sigma: 0.25
    slippage_multiplier: 1.0
  stress:
    trade_cost_bps:
      dist: lognormal
      mean: 18
      sigma: 0.35
    slippage_multiplier: 1.5

Example methods to implement:

def sample_cost(self, regime: str, turnover: float, rng: np.random.Generator) -> float:
    """Sample transaction cost in bps for a rebalance."""
    base_cost = self._sample_base_cost(regime, rng)
    slippage = self._get_slippage_multiplier(regime)
    return base_cost * slippage

def apply_costs(self, weights_before: pd.Series, weights_after: pd.Series, regime: str, rng: np.random.Generator) -> tuple[float, dict]:
    """Apply costs to a rebalance, return cost drag and diagnostics."""
    turnover = (weights_after - weights_before).abs().sum() / 2
    cost_bps = self.sample_cost(regime, turnover, rng)
    cost_drag = turnover * cost_bps / 10000
    return cost_drag, {"turnover": turnover, "cost_bps": cost_bps, "regime": regime}

<details>
<summary>Original Issue</summary>

````text

TODO: add technical notes, file paths, or constraints.

Deferred Tasks (Requires Human)

• Integrate cost sampling into runner.py with regime inputs. (The agent cannot modify repository settings or retry CI pipelines, which may be required for integration testing. | Ensure a human reviewer handles repository settings and CI pipeline adjustments.)
• Add unit tests for distributions, regimes, and integration behavior in tests/monte_carlo/test_costs.py. (The agent cannot guarantee specific test coverage percentages, which may be required for this task. | Define specific test coverage goals and have a human verify the results.)

[github-actions]

🤖 Auto-pilot step $((STEP_COUNT + 1)): Starting issue formatting...

Running formatter inline (not via label trigger).

[github-actions]

🤖 Auto-pilot step $((STEP_COUNT + 1)): Analyzing issue for improvements...

Running optimizer inline (not via label trigger).

[github-actions]

Issue Optimization Suggestions

Review the suggestions below. If you want the agent to apply them, add the
agents:apply-suggestions label to this issue.

Task splitting

• Implement regime-aware CostProcess with configurable distributions (lognormal, etc.) in src/trend_analysis/monte_carlo/costs.py. (This task combines multiple sub-tasks, such as implementing the CostProcess class, defining configurable distributions, and ensuring regime awareness.). Suggested split: Implement the CostProcess class structure. (verify: confirm completion in repo), Define (verify: confirm completion in repo), implement configurable distributions (e.g., lognormal). (verify: config validated), Add regime-awareness logic to the CostProcess. (verify: confirm completion in repo).
• Integrate cost sampling into runner.py with regime inputs. (Integration tasks often involve multiple steps, such as modifying the runner, ensuring compatibility with existing workflows, and testing the integration.). Suggested split: Modify runner.py to accept regime inputs. (verify: confirm completion in repo), Integrate cost sampling logic into the runner. (verify: confirm completion in repo), Test the integration with sample inputs. (verify: confirm completion in repo).
• Add unit tests for distributions, regimes, and integration behavior in tests/monte_carlo/test_costs.py. (This task involves testing multiple components, which should be split for clarity and better tracking.). Suggested split: Add unit tests for configurable distributions (e.g. (verify: tests pass), lognormal). (verify: confirm completion in repo), Add unit tests for regime-specific behavior. (verify: tests pass), Add integration tests for the CostProcess in the runner. (verify: tests pass).

Blocked tasks

• Integrate cost sampling into runner.py with regime inputs. (The agent cannot modify repository settings or retry CI pipelines, which may be required for integration testing. | Ensure a human reviewer handles repository settings and CI pipeline adjustments.)
• Add unit tests for distributions, regimes, and integration behavior in tests/monte_carlo/test_costs.py. (The agent cannot guarantee specific test coverage percentages, which may be required for this task. | Define specific test coverage goals and have a human verify the results.)

Objective acceptance criteria

• Costs vary across time with regime. (This is subjective and lacks measurable criteria. | Define specific metrics for cost variation, such as mean and variance thresholds for each regime.)
• Lognormal sampling produces reasonable cost distributions. (The term 'reasonable' is subjective. | Specify statistical properties (e.g., mean, variance, skewness) that the sampled distributions should meet.)
• Stress regime has higher mean and variance. (This is subjective without specific thresholds. | Define exact mean and variance ranges for the stress regime.)

Missing sections

• Scope
• Non-Goals

Formatting issues

• Bullets are used for non-task items in the 'Acceptance Criteria' section, which can cause confusion.
• The 'Implementation Notes' section uses a mix of code blocks and text without clear separation, making it harder to read.
• The 'Tasks' section includes implementation details (e.g., file paths) that should be moved to 'Implementation Notes'.

Notes

• The issue is well-structured overall but could benefit from clearer task splitting, more objective acceptance criteria, and improved formatting. Additionally, missing sections like 'Scope' and 'Non-Goals' should be filled in to provide better context and boundaries for the implementation. Blocked tasks should be flagged for human intervention where agent limitations apply.

[github-actions]

🤖 Auto-pilot step $((STEP_COUNT + 1)): Applying optimization suggestions...

Running apply inline (not via label trigger).

[github-actions]

🤖 Auto-pilot step 1: Issue prepared! Assigning to agent...

Adding agent:codex label. The capability check will run automatically.

⏳ Agent will create a PR shortly.

[agents-workflows-bot]

Codex belt dispatcher queued this issue and created branch codex/issue-4170.