Coverage for src/cc_liquid/cli.py: 0%

1"""Command-line interface for cc-liquid.""" 

2 

3import os 

4import yaml 

5import time 

6import traceback 

7from datetime import datetime, timezone 

8import subprocess 

9import shutil 

10import shlex 

11 

12import click 

13from rich.console import Console 

14from rich.progress import ( 

15 Progress, 

16 BarColumn, 

17 TextColumn, 

18 TimeRemainingColumn, 

19 TimeElapsedColumn, 

20 MofNCompleteColumn, 

21) 

22from typing import Any 

23 

24from .cli_callbacks import RichCLICallbacks 

25from .cli_display import ( 

26 create_dashboard_layout, 

27 create_config_panel, 

28 create_header_panel, 

29 create_setup_welcome_panel, 

30 create_setup_summary_panel, 

31 display_portfolio, 

32 display_file_summary, 

33 display_backtest_summary, 

34 show_pre_alpha_warning, 

35 display_optimization_results, 

36 display_optimization_contours, 

37) 

38from .backtester import BacktestOptimizer, BacktestConfig, Backtester 

39from .config import config 

40from .config import apply_cli_overrides 

41from .data_loader import DataLoader 

42from .trader import CCLiquid 

43from .completion import detect_shell_from_env, install_completion 

44 

45 

46TMUX_SESSION_NAME = "cc-liquid" 

47TMUX_WINDOW_NAME = "cc-liquid" 

48 

49 

50@click.group() 

51def cli(): 

52 """cc-liquid - A metamodel-based rebalancer for Hyperliquid.""" 

53 # Suppress the pre-alpha banner during Click's completion mode to avoid 

54 # corrupting the generated completion script output. 

55 in_completion_mode = any(k.endswith("_COMPLETE") for k in os.environ) 

56 if not in_completion_mode: 

57 show_pre_alpha_warning() 

58 

59 

60@cli.command(name="init") 

61@click.option( 

62 "--non-interactive", is_flag=True, help="Skip interactive setup, use defaults" 

63) 

64def init_cmd(non_interactive: bool): 

65 """Interactive setup wizard for first-time users. 

66 

67 Guides you through creating config files with validation and helpful defaults. 

68 """ 

69 console = Console() 

70 from rich.prompt import Prompt, Confirm 

71 

72 # Check existing files 

73 cfg_path = "cc-liquid-config.yaml" 

74 env_path = ".env" 

75 

76 if os.path.exists(cfg_path) or os.path.exists(env_path): 

77 existing_files = [] 

78 if os.path.exists(cfg_path): 

79 existing_files.append(cfg_path) 

80 if os.path.exists(env_path): 

81 existing_files.append(env_path) 

82 

83 console.print( 

84 f"\n[yellow]⚠️ Found existing files: {', '.join(existing_files)}[/yellow]" 

85 ) 

86 if not non_interactive: 

87 if not Confirm.ask("Overwrite existing files?", default=False): 

88 console.print("[red]Setup cancelled.[/red]") 

89 return 

90 

91 # Gather all configuration based on mode 

92 if non_interactive: 

93 # All defaults in one place for non-interactive mode 

94 is_testnet = True 

95 data_source = "crowdcent" 

96 crowdcent_key = "" 

97 hyper_key_placeholder = "0x..." 

98 owner_address = None 

99 vault_address = None 

100 num_long = 10 

101 num_short = 10 

102 leverage = 1.0 

103 else: 

104 # Interactive flow 

105 console.print(create_setup_welcome_panel()) 

106 

107 # Step 1: Environment 

108 console.print("\n[bold]Step 1: Choose Environment[/bold]") 

109 console.print("[dim]Testnet is recommended for first-time users[/dim]") 

110 is_testnet = Confirm.ask("Use testnet?", default=True) 

111 

112 # Step 2: Data source 

113 console.print("\n[bold]Step 2: Data Source[/bold]") 

114 console.print("Available sources:") 

115 console.print( 

116 " • [cyan]crowdcent[/cyan] - CrowdCent metamodel (requires API key)" 

117 ) 

118 console.print(" • [cyan]numerai[/cyan] - Numerai crypto signals (free)") 

119 console.print(" • [cyan]local[/cyan] - Your own prediction file") 

120 

121 data_source = Prompt.ask( 

122 "Choose data source", 

123 choices=["crowdcent", "numerai", "local"], 

124 default="crowdcent", 

125 ) 

126 

127 # Step 3: API keys 

128 console.print("\n[bold]Step 3: API Keys[/bold]") 

129 

130 crowdcent_key = "" 

131 if data_source == "crowdcent": 

132 console.print("\n[cyan]CrowdCent API Key[/cyan]") 

133 console.print("[dim]Get from: https://crowdcent.com/profile[/dim]") 

134 crowdcent_key = Prompt.ask( 

135 "Enter CrowdCent API key (or press Enter to add later)", 

136 default="", 

137 show_default=False, 

138 ) 

139 

140 console.print("\n[cyan]Hyperliquid Private Key[/cyan]") 

141 console.print("[dim]Get from: https://app.hyperliquid.xyz/API[/dim]") 

142 console.print( 

143 "[yellow]⚠️ Use an agent wallet key, not your main wallet![/yellow]" 

144 ) 

145 hyper_key_input = Prompt.ask( 

146 "Enter Hyperliquid private key (or press Enter to add later)", 

147 default="", 

148 show_default=False, 

149 password=True, # Hide input for security 

150 ) 

151 hyper_key_placeholder = hyper_key_input if hyper_key_input else "0x..." 

152 

153 # Step 4: Addresses 

154 console.print("\n[bold]Step 4: Addresses[/bold]") 

155 console.print("[dim]Leave blank to fill in later[/dim]") 

156 

157 owner_address = Prompt.ask( 

158 "Owner address (your main wallet, NOT the agent wallet)", 

159 default="", 

160 show_default=False, 

161 ) 

162 owner_address = owner_address if owner_address else None 

163 

164 vault_address = Prompt.ask( 

165 "Vault address (optional, for managed vaults)", 

166 default="", 

167 show_default=False, 

168 ) 

169 vault_address = vault_address if vault_address else None 

170 

171 # Step 5: Portfolio settings 

172 console.print("\n[bold]Step 5: Portfolio Settings[/bold]") 

173 

174 num_long = int(Prompt.ask("Number of long positions", default="10")) 

175 num_short = int(Prompt.ask("Number of short positions", default="10")) 

176 

177 console.print("\n[yellow]⚠️ Leverage Warning:[/yellow]") 

178 console.print("[dim]1.0 = no leverage (safest)[/dim]") 

179 console.print("[dim]2.0 = 2x leverage (moderate risk)[/dim]") 

180 console.print("[dim]3.0+ = high risk of liquidation[/dim]") 

181 leverage = float(Prompt.ask("Target leverage", default="1.0")) 

182 

183 # Compose configurations 

184 yaml_cfg: dict[str, Any] = { 

185 "active_profile": "default", 

186 "profiles": { 

187 "default": { 

188 "owner": owner_address, 

189 "vault": vault_address, 

190 "signer_env": "HYPERLIQUID_PRIVATE_KEY", 

191 } 

192 }, 

193 "is_testnet": is_testnet, 

194 "data": { 

195 "source": data_source, 

196 "path": "predictions.parquet", 

197 **( 

198 { 

199 "date_column": "date", 

200 "asset_id_column": "symbol", 

201 "prediction_column": "meta_model", 

202 } 

203 if data_source == "numerai" 

204 else { 

205 "date_column": "release_date", 

206 "asset_id_column": "id", 

207 "prediction_column": "pred_10d", 

208 } 

209 ), 

210 }, 

211 "portfolio": { 

212 "num_long": num_long, 

213 "num_short": num_short, 

214 "target_leverage": leverage, 

215 "rebalancing": {"every_n_days": 10, "at_time": "18:15"}, 

216 }, 

217 "execution": {"slippage_tolerance": 0.005, "min_trade_value": 10.0}, 

218 } 

219 

220 env_lines = [ 

221 "# Secrets only - NEVER commit this file to git!", 

222 "# Add to .gitignore immediately", 

223 "", 

224 "# CrowdCent API (https://crowdcent.com/profile)", 

225 f"CROWDCENT_API_KEY={crowdcent_key}", 

226 "", 

227 "# Hyperliquid Agent Wallet Private Key (https://app.hyperliquid.xyz/API)", 

228 "# ⚠️ Use an agent wallet, NOT your main wallet!", 

229 f"HYPERLIQUID_PRIVATE_KEY={hyper_key_placeholder}", 

230 ] 

231 

232 # Write files 

233 try: 

234 with open(cfg_path, "w") as f: 

235 yaml.safe_dump(yaml_cfg, f, sort_keys=False) 

236 console.print(f"\n[green]✓[/green] Created [cyan]{cfg_path}[/cyan]") 

237 except Exception as e: 

238 console.print(f"[red]✗ Failed to write {cfg_path}:[/red] {e}") 

239 raise SystemExit(1) 

240 

241 try: 

242 with open(env_path, "w") as f: 

243 f.write("\n".join(env_lines) + "\n") 

244 console.print(f"[green]✓[/green] Created [cyan]{env_path}[/cyan]") 

245 except Exception as e: 

246 console.print(f"[red]✗ Failed to write {env_path}:[/red] {e}") 

247 raise SystemExit(1) 

248 

249 # Add to .gitignore if it exists 

250 if os.path.exists(".gitignore"): 

251 with open(".gitignore", "r") as f: 

252 gitignore_content = f.read() 

253 if ".env" not in gitignore_content: 

254 with open(".gitignore", "a") as f: 

255 f.write("\n# cc-liquid secrets\n.env\n") 

256 console.print("[green]✓[/green] Added .env to .gitignore") 

257 

258 # Summary and next steps 

259 summary = create_setup_summary_panel( 

260 is_testnet=is_testnet, 

261 data_source=data_source, 

262 num_long=num_long, 

263 num_short=num_short, 

264 leverage=leverage, 

265 ) 

266 console.print("\n") 

267 console.print(summary) 

268 

269 

270@cli.command(name="config") 

271def show_config(): 

272 """Show the current configuration.""" 

273 console = Console() 

274 config_dict = config.to_dict() 

275 panel = create_config_panel(config_dict) 

276 console.print(panel) 

277 

278 

279@cli.group() 

280def completion(): 

281 """Shell completion utilities.""" 

282 

283 

284@completion.command(name="install") 

285@click.option( 

286 "--shell", 

287 "shell_opt", 

288 type=click.Choice(["bash", "zsh", "fish"], case_sensitive=False), 

289 default=None, 

290 help="Target shell. Defaults to auto-detect from $SHELL.", 

291) 

292@click.option( 

293 "--prog-name", 

294 default="cc-liquid", 

295 show_default=True, 

296 help="Program name to install completion for (as installed on PATH).", 

297) 

298def completion_install(shell_opt: str | None, prog_name: str): 

299 """Install shell completion for the current user. 

300 

301 Writes the generated completion script to a standard location and, for 

302 Bash/Zsh, appends a source line to the user's rc file idempotently. 

303 """ 

304 console = Console() 

305 shell = shell_opt or detect_shell_from_env() 

306 if shell is None: 

307 console.print( 

308 "[red]Could not detect shell from $SHELL. Specify with[/red] " 

309 "[bold]--shell {bash|zsh|fish}[/bold]." 

310 ) 

311 raise SystemExit(2) 

312 

313 result = install_completion(prog_name, shell) 

314 

315 console.print( 

316 f"[green]✓[/green] Installed completion for [bold]{shell}[/bold] at " 

317 f"[cyan]{result.script_path}[/cyan]" 

318 + (" (updated)" if result.script_written else " (no changes)") 

319 ) 

320 

321 if result.rc_path is not None: 

322 console.print( 

323 f"[blue]•[/blue] Ensured rc entry in [cyan]{result.rc_path}[/cyan] " 

324 + ("(added)" if result.rc_line_added else "(already present)") 

325 ) 

326 

327 console.print( 

328 "[dim]Restart your shell or 'source' your rc file to activate completion.[/dim]" 

329 ) 

330 

331 

332@cli.group() 

333def profile(): 

334 """Manage configuration profiles (owner/vault/signer).""" 

335 

336 

337@profile.command(name="list") 

338def profile_list(): 

339 """List available profiles from YAML and highlight the active one.""" 

340 console = Console() 

341 profiles = config.profiles or {} 

342 if not profiles: 

343 console.print("[yellow]No profiles found in cc-liquid-config.yaml[/yellow]") 

344 return 

345 from rich.table import Table 

346 

347 table = Table(title="Profiles", show_lines=False, header_style="bold cyan") 

348 table.add_column("NAME", style="cyan") 

349 table.add_column("OWNER") 

350 table.add_column("VAULT") 

351 table.add_column("SIGNER ENV") 

352 for name, prof in profiles.items(): 

353 owner = (prof or {}).get("owner") or "-" 

354 vault = (prof or {}).get("vault") or "-" 

355 signer_env = (prof or {}).get("signer_env", "HYPERLIQUID_PRIVATE_KEY") 

356 label = f"[bold]{name}[/bold]" + ( 

357 " [green](active)[/green]" if name == config.active_profile else "" 

358 ) 

359 table.add_row(label, owner, vault, signer_env) 

360 console.print(table) 

361 

362 

363@profile.command(name="show") 

364@click.argument("name", required=False) 

365def profile_show(name: str | None): 

366 """Show details for a profile (defaults to active).""" 

367 console = Console() 

368 target = name or config.active_profile 

369 if not target: 

370 console.print("[red]No active profile set and no name provided[/red]") 

371 raise SystemExit(2) 

372 prof = (config.profiles or {}).get(target) 

373 if prof is None: 

374 console.print(f"[red]Profile '{target}' not found[/red]") 

375 raise SystemExit(2) 

376 data = { 

377 "name": target, 

378 "owner": prof.get("owner"), 

379 "vault": prof.get("vault"), 

380 "signer_env": prof.get("signer_env", "HYPERLIQUID_PRIVATE_KEY"), 

381 "is_active": target == config.active_profile, 

382 } 

383 panel = create_config_panel( 

384 { 

385 "is_testnet": config.is_testnet, 

386 "profile": { 

387 "active": data["name"] if data["is_active"] else config.active_profile, 

388 "owner": data["owner"], 

389 "vault": data["vault"], 

390 "signer_env": data["signer_env"], 

391 }, 

392 "data": config.data.__dict__, 

393 "portfolio": config.portfolio.__dict__ 

394 | {"rebalancing": config.portfolio.rebalancing.__dict__}, 

395 "execution": config.execution.__dict__, 

396 } 

397 ) 

398 console.print(panel) 

399 

400 

401@profile.command(name="use") 

402@click.argument("name", required=True) 

403def profile_use(name: str): 

404 """Set active profile and persist to YAML.""" 

405 console = Console() 

406 profiles = config.profiles or {} 

407 if name not in profiles: 

408 console.print(f"[red]Profile '{name}' not found in cc-liquid-config.yaml[/red]") 

409 raise SystemExit(2) 

410 

411 # Update file 

412 cfg_path = "cc-liquid-config.yaml" 

413 try: 

414 y: dict = {} 

415 if os.path.exists(cfg_path): 

416 with open(cfg_path) as f: 

417 y = yaml.safe_load(f) or {} 

418 y["active_profile"] = name 

419 with open(cfg_path, "w") as f: 

420 yaml.safe_dump(y, f, sort_keys=False) 

421 except Exception as e: 

422 console.print(f"[red]Failed to update {cfg_path}: {e}[/red]") 

423 raise SystemExit(1) 

424 

425 # Update runtime 

426 config.active_profile = name 

427 try: 

428 config.refresh_runtime() 

429 except Exception as e: 

430 console.print(f"[red]Failed to activate profile: {e}[/red]") 

431 raise SystemExit(1) 

432 console.print(f"[green]✓[/green] Active profile set to [bold]{name}[/bold]") 

433 

434 

435@cli.group() 

436def orders(): 

437 """Manage and monitor orders.""" 

438 pass 

439 

440 

441@orders.command(name="list") 

442@click.option("--history", is_flag=True, help="Show completed orders instead of open") 

443@click.option("--days", default=30, help="History lookback period in days") 

444@click.option( 

445 "--set", 

446 "set_overrides", 

447 multiple=True, 

448 help="Override config values", 

449) 

450def orders_list(history, days, set_overrides): 

451 """List open or historical orders.""" 

452 console = Console() 

453 

454 # Apply overrides 

455 overrides_applied = apply_cli_overrides(config, set_overrides) 

456 if overrides_applied: 

457 console.print(f"[dim]Applied overrides: {', '.join(overrides_applied)}[/dim]\n") 

458 

459 # Create trader 

460 callbacks = RichCLICallbacks() 

461 trader = CCLiquid(config, callbacks=callbacks) 

462 

463 if history: 

464 # Show historical orders 

465 order_history = trader.get_order_history(days=days) 

466 callbacks.show_order_history(order_history, days) 

467 else: 

468 # Show open orders 

469 open_orders = trader.get_open_orders() 

470 

471 if not open_orders: 

472 console.print("[yellow]No open orders[/yellow]") 

473 return 

474 

475 callbacks.show_open_orders(open_orders) 

476 

477 

478@orders.command(name="cancel") 

479@click.option("--order-id", help="Specific order ID to cancel") 

480@click.option("--all", "cancel_all", is_flag=True, help="Cancel all open orders") 

481@click.option( 

482 "--set", 

483 "set_overrides", 

484 multiple=True, 

485 help="Override config values", 

486) 

487def orders_cancel(order_id, cancel_all, set_overrides): 

488 """Cancel open orders.""" 

489 console = Console() 

490 

491 if not order_id and not cancel_all: 

492 console.print("[red]Error: Specify --order-id or --all[/red]") 

493 raise SystemExit(1) 

494 

495 overrides_applied = apply_cli_overrides(config, set_overrides) 

496 callbacks = RichCLICallbacks() 

497 trader = CCLiquid(config, callbacks=callbacks) 

498 

499 if cancel_all: 

500 open_orders = trader.get_open_orders() 

501 if not open_orders: 

502 console.print("[yellow]No open orders to cancel[/yellow]") 

503 return 

504 

505 console.print(f"Cancelling {len(open_orders)} orders...") 

506 

507 success_count = 0 

508 for order in open_orders: 

509 if trader.cancel_order(order.order_id): 

510 console.print(f"[green]✓[/green] Cancelled {order.coin} ({order.order_id[:12]}...)") 

511 success_count += 1 

512 else: 

513 console.print(f"[red]✗[/red] Failed to cancel {order.coin} ({order.order_id[:12]}...)") 

514 

515 console.print(f"\n[bold]Cancelled {success_count}/{len(open_orders)} orders[/bold]") 

516 else: 

517 if trader.cancel_order(order_id): 

518 console.print(f"[green]✓[/green] Cancelled order {order_id}") 

519 else: 

520 console.print(f"[red]✗[/red] Failed to cancel order {order_id}") 

521 

522 

523@orders.command(name="export") 

524@click.option("--output", "-o", required=True, help="Output CSV file path") 

525@click.option("--days", default=90, help="Export orders from last N days") 

526@click.option( 

527 "--set", 

528 "set_overrides", 

529 multiple=True, 

530 help="Override config values", 

531) 

532def orders_export(output, days, set_overrides): 

533 """Export order history to CSV.""" 

534 console = Console() 

535 

536 overrides_applied = apply_cli_overrides(config, set_overrides) 

537 trader = CCLiquid(config) 

538 

539 history = trader.get_order_history(days=days) 

540 

541 if not history.orders: 

542 console.print(f"[yellow]No orders found in the last {days} days[/yellow]") 

543 return 

544 

545 # Convert to CSV 

546 import csv 

547 with open(output, 'w', newline='') as f: 

548 writer = csv.writer(f) 

549 writer.writerow([ 

550 "order_id", "timestamp", "coin", "side", "strategy", 

551 "size", "filled_size", "avg_fill_price", "slippage_bps", 

552 "total_fees", "status", "twap_duration_minutes" 

553 ]) 

554 

555 for order in history.orders: 

556 writer.writerow([ 

557 order.order_id, 

558 order.timestamp.isoformat(), 

559 order.coin, 

560 order.side, 

561 order.strategy, 

562 order.size, 

563 order.filled_size, 

564 order.avg_fill_price, 

565 order.slippage_bps, 

566 order.total_fees, 

567 order.status, 

568 order.twap_duration_minutes 

569 ]) 

570 

571 console.print(f"[green]✓[/green] Exported {len(history.orders)} orders to {output}") 

572 

573 

574@cli.command() 

575def account(): 

576 """Show comprehensive account and positions summary.""" 

577 console = Console() 

578 trader = CCLiquid(config, callbacks=RichCLICallbacks()) 

579 

580 # Get structured portfolio info 

581 portfolio = trader.get_portfolio_info() 

582 

583 # Display using reusable display function with config 

584 display_portfolio(portfolio, console, config.to_dict()) 

585 

586 

587@cli.command() 

588@click.option( 

589 "--output", 

590 "-o", 

591 default=None, 

592 help="Output file path (defaults to path in config).", 

593) 

594def download_crowdcent(output): 

595 """Download the CrowdCent meta model.""" 

596 console = Console() 

597 if output is None: 

598 output = config.data.path 

599 try: 

600 predictions = DataLoader.from_crowdcent_api( 

601 api_key=config.CROWDCENT_API_KEY, download_path=output 

602 ) 

603 display_file_summary(console, predictions, output, "CrowdCent meta model") 

604 except Exception as e: 

605 console.print(f"[red]✗[/red] Failed to download CrowdCent meta model: {e}") 

606 raise 

607 

608 

609@cli.command() 

610@click.option( 

611 "--output", 

612 "-o", 

613 default=None, 

614 help="Output file path (defaults to path in config).", 

615) 

616def download_numerai(output): 

617 """Download the Numerai meta model.""" 

618 console = Console() 

619 if output is None: 

620 output = config.data.path 

621 try: 

622 predictions = DataLoader.from_numerai_api(download_path=output) 

623 display_file_summary(console, predictions, output, "Numerai meta model") 

624 except Exception as e: 

625 console.print(f"[red]✗[/red] Failed to download Numerai meta model: {e}") 

626 raise 

627 

628 

629@cli.command() 

630@click.option( 

631 "--skip-confirm", 

632 is_flag=True, 

633 help="Skip confirmation prompt for closing positions.", 

634) 

635@click.option( 

636 "--set", 

637 "set_overrides", 

638 multiple=True, 

639 help="Override config values (e.g., --set is_testnet=true)", 

640) 

641@click.option( 

642 "--force", 

643 is_flag=True, 

644 help="Force close positions below min notional by composing a two-step workaround.", 

645) 

646def close_all(skip_confirm, set_overrides, force): 

647 """Close all positions and return to cash.""" 

648 console = Console() 

649 

650 # Apply CLI overrides to config 

651 overrides_applied = apply_cli_overrides(config, set_overrides) 

652 

653 # Create callbacks and trader 

654 callbacks = RichCLICallbacks() 

655 trader = CCLiquid(config, callbacks=callbacks) 

656 

657 # Show applied overrides through callbacks 

658 callbacks.on_config_override(overrides_applied) 

659 

660 try: 

661 # Preview plan first (no execution) 

662 plan = trader.plan_close_all_positions(force=force) 

663 

664 # Render plan via callbacks 

665 all_trades = plan["trades"] + plan["skipped_trades"] 

666 callbacks.show_trade_plan( 

667 plan["target_positions"], 

668 all_trades, 

669 plan["account_value"], 

670 plan["leverage"], 

671 ) 

672 

673 # Confirm/auto-confirm 

674 if skip_confirm or callbacks.ask_confirmation("Close all positions?"): 

675 # Execute 

676 result = trader.execute_plan(plan) 

677 callbacks.show_execution_summary( 

678 result["successful_trades"], 

679 result["all_trades"], 

680 plan["target_positions"], 

681 plan["account_value"], 

682 ) 

683 else: 

684 callbacks.info("Cancelled by user") 

685 except Exception as e: 

686 console.print(f"[red]✗ Error closing positions:[/red] {e}") 

687 traceback.print_exc() 

688 

689 

690@cli.command() 

691@click.option( 

692 "--skip-confirm", 

693 is_flag=True, 

694 help="Skip confirmation prompt for executing trades.", 

695) 

696@click.option( 

697 "--set", 

698 "set_overrides", 

699 multiple=True, 

700 help="Override config values (e.g., --set data.source=numerai --set portfolio.num_long=10)", 

701) 

702def rebalance(skip_confirm, set_overrides): 

703 """Execute rebalancing based on the configured data source.""" 

704 

705 # Apply CLI overrides to config 

706 overrides_applied = apply_cli_overrides(config, set_overrides) 

707 

708 # Create callbacks and trader 

709 callbacks = RichCLICallbacks() 

710 trader = CCLiquid(config, callbacks=callbacks) 

711 

712 # Show applied overrides through callbacks 

713 callbacks.on_config_override(overrides_applied) 

714 

715 # Preview plan first (no execution) 

716 plan = trader.plan_rebalance() 

717 

718 # Render plan via callbacks 

719 all_trades = plan["trades"] + plan["skipped_trades"] 

720 callbacks.show_trade_plan( 

721 plan["target_positions"], all_trades, plan["account_value"], plan["leverage"] 

722 ) 

723 

724 # Confirm/auto-confirm 

725 if skip_confirm or callbacks.ask_confirmation("Execute these trades?"): 

726 result = trader.execute_plan(plan) 

727 callbacks.show_execution_summary( 

728 result["successful_trades"], 

729 result["all_trades"], 

730 plan["target_positions"], 

731 plan["account_value"], 

732 ) 

733 else: 

734 callbacks.info("Trading cancelled by user") 

735 

736 

737@cli.command() 

738@click.option( 

739 "--prices", 

740 default="raw_data.parquet", 

741 help="Path to price data (parquet file with date, id, close columns)", 

742) 

743@click.option( 

744 "--start-date", 

745 type=click.DateTime(), 

746 help="Start date for backtest (YYYY-MM-DD)", 

747) 

748@click.option( 

749 "--end-date", 

750 type=click.DateTime(), 

751 help="End date for backtest (YYYY-MM-DD)", 

752) 

753@click.option( 

754 "--set", 

755 "set_overrides", 

756 multiple=True, 

757 help="Override config values (e.g., --set portfolio.num_long=15 --set data.source=numerai)", 

758) 

759@click.option( 

760 "--fee-bps", 

761 type=float, 

762 default=4.0, 

763 help="Trading fee in basis points", 

764) 

765@click.option( 

766 "--slippage-bps", 

767 type=float, 

768 default=50.0, 

769 help="Slippage cost in basis points", 

770) 

771@click.option( 

772 "--prediction-lag", 

773 type=int, 

774 default=1, 

775 help="Days between prediction date and trading date (default: 1, use higher values to avoid look-ahead bias)", 

776) 

777@click.option( 

778 "--save-daily", 

779 help="Save daily results to CSV file", 

780) 

781@click.option( 

782 "--show-positions", 

783 is_flag=True, 

784 help="Show detailed position analysis table", 

785) 

786@click.option( 

787 "--verbose", 

788 is_flag=True, 

789 help="Show detailed progress", 

790) 

791def analyze( 

792 prices, 

793 start_date, 

794 end_date, 

795 set_overrides, 

796 fee_bps, 

797 slippage_bps, 

798 prediction_lag, 

799 save_daily, 

800 show_positions, 

801 verbose, 

802): 

803 """Run backtest analysis on historical data. 

804 

805 ⚠️ IMPORTANT DISCLAIMER: 

806 Past performance does not guarantee future results. Backtesting results are 

807 hypothetical and have inherent limitations. Actual trading results may differ 

808 significantly. Always consider market conditions, liquidity, and execution costs 

809 that may not be fully captured in simulations. 

810 """ 

811 from .backtester import Backtester, BacktestConfig 

812 from .config import config 

813 

814 console = Console() 

815 

816 # Apply CLI overrides to config (includes smart defaults for data.source changes) 

817 overrides_applied = apply_cli_overrides(config, set_overrides) 

818 

819 # Show applied overrides through console 

820 if overrides_applied: 

821 console.print("[cyan]Configuration overrides applied:[/cyan]") 

822 for override in overrides_applied: 

823 console.print(f" • {override}") 

824 console.print() 

825 

826 # Now use the config value (which may have been overridden) 

827 predictions = config.data.path 

828 

829 # Create backtest config using the updated config values 

830 bt_config = BacktestConfig( 

831 prices_path=prices, 

832 predictions_path=predictions, 

833 # Use config columns for predictions 

834 pred_date_column=config.data.date_column, 

835 pred_id_column=config.data.asset_id_column, 

836 pred_value_column=config.data.prediction_column, 

837 data_provider=config.data.source, 

838 start_date=start_date, 

839 end_date=end_date, 

840 num_long=config.portfolio.num_long, 

841 num_short=config.portfolio.num_short, 

842 target_leverage=config.portfolio.target_leverage, 

843 weighting_scheme=config.portfolio.weighting_scheme, 

844 rank_power=config.portfolio.rank_power, 

845 rebalance_every_n_days=config.portfolio.rebalancing.every_n_days, 

846 prediction_lag_days=prediction_lag, 

847 fee_bps=fee_bps, 

848 slippage_bps=slippage_bps, 

849 verbose=verbose, 

850 ) 

851 

852 try: 

853 # Run backtest with spinner 

854 from rich.spinner import Spinner 

855 from rich.live import Live 

856 

857 with Live( 

858 Spinner("dots", text="Running backtest..."), console=console, transient=True 

859 ):