alpha-visualizer 0.1.0__py3-none-any.whl

alpha_visualizer/__init__.py

@@ -0,0 +1,3 @@
+"""alpha-visualizer: AlphaForge バックテスト結果の Web 可視化ツール"""
+
+__version__ = "0.1.0"

alpha_visualizer/app.py

@@ -0,0 +1,73 @@
+"""FastAPI アプリケーションファクトリ"""
+from __future__ import annotations
+
+import pathlib
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse, JSONResponse
+
+from alpha_visualizer.forge_config import ForgeConfig
+from alpha_visualizer.routers import ideas as ideas_router
+from alpha_visualizer.routers import results as results_router
+from alpha_visualizer.routers import strategies as strategies_router
+from alpha_visualizer.routers import wfo as wfo_router
+
+
+def create_app(
+    forge_dir: pathlib.Path | None = None,
+    *,
+    config: ForgeConfig | None = None,
+) -> FastAPI:
+    """FastAPI アプリを生成する。
+
+    引数は次のいずれかを満たす必要がある:
+    - ``config``: 解決済みの ``ForgeConfig`` を直接渡す（推奨）
+    - ``forge_dir``: ディレクトリパスを渡し、内部で ``ForgeConfig.from_forge_dir`` を呼ぶ
+      （後方互換）
+
+    両方渡された場合は ``config`` が優先される。
+    """
+    if config is None:
+        if forge_dir is None:
+            raise ValueError("forge_dir または config のいずれかを指定してください")
+        config = ForgeConfig.from_forge_dir(pathlib.Path(forge_dir))
+
+    app = FastAPI(
+        title="alpha-visualizer",
+        description="AlphaForge バックテスト結果の Web 可視化ツール",
+        version="0.1.0",
+    )
+    app.state.forge_config = config
+
+    app.include_router(results_router.router, prefix="/api")
+    app.include_router(strategies_router.router, prefix="/api")
+    app.include_router(ideas_router.router, prefix="/api")
+    app.include_router(wfo_router.router, prefix="/api")
+
+    forge_dir_str = str(config.forge_dir)
+
+    @app.get("/health")
+    async def health() -> JSONResponse:
+        return JSONResponse({"status": "ok", "forge_dir": forge_dir_str})
+
+    static_dir = pathlib.Path(__file__).parent / "static"
+    if static_dir.exists():
+        index_html = static_dir / "index.html"
+        static_root = static_dir.resolve()
+
+        @app.get("/{full_path:path}")
+        async def spa_fallback(full_path: str) -> FileResponse:
+            """SPA ルート対応: /api 配下以外で実ファイルがあればそれを返し、
+            無ければ index.html を返して history mode の直アクセス・リロードに対応する。
+            """
+            requested = (static_dir / full_path).resolve()
+            # ディレクトリトラバーサル対策
+            try:
+                requested.relative_to(static_root)
+            except ValueError:
+                return FileResponse(index_html)
+            if requested.is_file():
+                return FileResponse(requested)
+            return FileResponse(index_html)
+
+    return app

alpha_visualizer/cli.py

@@ -0,0 +1,66 @@
+"""vis CLI エントリーポイント"""
+
+import click
+
+from alpha_visualizer import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="alpha-visualizer")
+def cli() -> None:
+    """alpha-visualizer - AlphaForge バックテスト結果の Web 可視化ツール"""
+
+
+@cli.command("serve")
+@click.option("--host", default="127.0.0.1", show_default=True, help="バインドするホスト名")
+@click.option("--port", default=8000, show_default=True, help="ポート番号")
+@click.option(
+    "--forge-dir",
+    default=".",
+    show_default=True,
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    help="forge が生成するデータディレクトリのパス",
+)
+@click.option(
+    "--forge-config",
+    "forge_config",
+    default=None,
+    type=click.Path(exists=False, file_okay=True, dir_okay=False),
+    help="forge.yaml のパス。未指定なら $FORGE_CONFIG → <forge-dir>/forge.yaml の順で探索",
+)
+@click.option("--no-open", "no_open", is_flag=True, default=False, help="ブラウザを自動で開かない")
+def serve(
+    host: str,
+    port: int,
+    forge_dir: str,
+    forge_config: str | None,
+    no_open: bool,
+) -> None:
+    """Web ダッシュボードを起動する"""
+    import pathlib
+
+    import uvicorn
+
+    from alpha_visualizer.app import create_app
+    from alpha_visualizer.forge_config import ForgeConfig
+
+    forge_path = pathlib.Path(forge_dir).resolve()
+    config_path = pathlib.Path(forge_config).resolve() if forge_config else None
+    config = ForgeConfig.from_forge_dir(forge_path, config_path=config_path)
+    app = create_app(config=config)
+
+    url = f"http://{host}:{port}"
+    click.echo(f"vis serve: {url}  (Ctrl+C で停止)")
+    click.echo(f"forge-dir: {forge_path}")
+    click.echo(f"forge-db:  {config.forge_db}")
+    if config.strategies_db is not None:
+        click.echo(f"strategies-db: {config.strategies_db}")
+    else:
+        click.echo(f"strategies-dir: {config.strategies_dir} (JSON モード)")
+
+    if not no_open:
+        import webbrowser
+        webbrowser.open(url)
+
+    uvicorn.run(app, host=host, port=port)
+    click.echo("vis serve を停止しました。")

alpha_visualizer/db.py

@@ -0,0 +1,61 @@
+"""forge.db / strategies.db の SQLAlchemy テーブル定義（読み取り専用）"""
+
+from sqlalchemy import REAL, Column, Integer, MetaData, Table, Text
+
+metadata = MetaData()
+
+strategies = Table(
+    "strategies",
+    metadata,
+    Column("id", Integer, primary_key=True),
+    Column("strategy_id", Text, nullable=False, unique=True),
+    Column("name", Text, nullable=False),
+    Column("version", Text),
+    Column("asset_type", Text),
+    Column("timeframe", Text),
+    Column("tags", Text),
+    Column("notes", Text),
+    Column("definition_json", Text, nullable=False),
+    Column("source_file", Text),
+    Column("created_at", Text),
+    Column("updated_at", Text),
+)
+
+backtest_results = Table(
+    "backtest_results",
+    metadata,
+    Column("run_id", Text, primary_key=True),
+    Column("strategy_id", Text),
+    Column("symbol", Text),
+    Column("run_at", Text),
+    Column("total_return_pct", REAL),
+    Column("cagr_pct", REAL),
+    Column("sharpe_ratio", REAL),
+    Column("sortino_ratio", REAL),
+    Column("calmar_ratio", REAL),
+    Column("max_drawdown_pct", REAL),
+    Column("total_trades", Integer),
+    Column("win_rate_pct", REAL),
+    Column("profit_factor", REAL),
+    Column("avg_holding_days", REAL),
+    Column("metrics_json", Text),
+    Column("equity_curve_json", Text),
+    Column("buy_hold_curve_json", Text),
+    Column("trades_json", Text),
+    Column("oos_start", Text),
+)
+
+optimization_runs = Table(
+    "optimization_runs",
+    metadata,
+    Column("run_id", Text, primary_key=True),
+    Column("strategy_id", Text),
+    Column("symbol", Text),
+    Column("run_at", Text),
+    Column("n_trials", Integer),
+    Column("best_metric_name", Text),
+    Column("best_metric_value", REAL),
+    Column("best_params_json", Text),
+    Column("duration_seconds", REAL),
+    Column("all_trials_json", Text),
+)

alpha_visualizer/forge_config.py

@@ -0,0 +1,133 @@
+"""forge.yaml を読み取り、forge が生成するディレクトリ構造からパスを解決するデータクラス
+
+forge.yaml の探索順序:
+1. 引数 ``config_path`` が明示指定されていればそれ
+2. 環境変数 ``FORGE_CONFIG`` が指すパス（存在する場合のみ）
+3. ``<forge_dir>/forge.yaml``
+4. 見つからなければ既存ハードコード値（後方互換）
+
+forge.yaml 内の相対パスは、forge.yaml ファイルの親ディレクトリ基準で絶対化される。
+これは alpha-forge の ``alpha_forge/config.py:_resolve_paths`` と同じ規約。
+"""
+
+from __future__ import annotations
+
+import os
+import pathlib
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class ForgeConfig:
+    """forge プロジェクトのパス解決結果。
+
+    すべてのパスは ``from_forge_dir`` ファクトリで構築時に解決済みの絶対パスになる。
+    """
+
+    forge_dir: pathlib.Path
+    forge_db: pathlib.Path
+    strategies_dir: pathlib.Path
+    strategies_db: pathlib.Path | None
+    ideas_json: pathlib.Path
+
+    @classmethod
+    def from_forge_dir(
+        cls,
+        forge_dir: pathlib.Path,
+        config_path: pathlib.Path | None = None,
+    ) -> ForgeConfig:
+        """forge.yaml を読み込んで設定を構築する。
+
+        Args:
+            forge_dir: forge プロジェクトのルートディレクトリ。
+            config_path: 明示指定する forge.yaml のパス（最優先）。
+
+        Returns:
+            解決済みパスを持つ ``ForgeConfig`` インスタンス。
+        """
+        forge_dir = pathlib.Path(forge_dir).resolve()
+        yaml_path = _resolve_yaml_path(forge_dir, config_path)
+        raw = _load_yaml(yaml_path) if yaml_path is not None else {}
+
+        # 相対パス解決の基準は forge.yaml の親ディレクトリ。
+        # forge.yaml が見つからない場合は forge_dir を基準にする（後方互換）。
+        base = yaml_path.parent if yaml_path is not None else forge_dir
+
+        report = raw.get("report") or {}
+        strategies = raw.get("strategies") or {}
+        ideas = raw.get("ideas") or {}
+
+        report_output = _resolve_path(
+            base, report.get("output_path"), default=forge_dir / "data" / "results"
+        )
+        forge_db_filename = report.get("db_filename") or "forge.db"
+        forge_db = report_output / forge_db_filename
+
+        strategies_path = _resolve_path(
+            base, strategies.get("path"), default=forge_dir / "data" / "strategies"
+        )
+        strategies_db: pathlib.Path | None = None
+        if bool(strategies.get("use_db", False)):
+            strategies_db_filename = strategies.get("db_filename") or "strategies.db"
+            strategies_db = strategies_path / strategies_db_filename
+
+        ideas_path = _resolve_path(
+            base, ideas.get("ideas_path"), default=forge_dir / "data" / "ideas"
+        )
+        ideas_json = ideas_path / "ideas.json"
+
+        return cls(
+            forge_dir=forge_dir,
+            forge_db=forge_db,
+            strategies_dir=strategies_path,
+            strategies_db=strategies_db,
+            ideas_json=ideas_json,
+        )
+
+
+def _resolve_yaml_path(
+    forge_dir: pathlib.Path, explicit: pathlib.Path | None
+) -> pathlib.Path | None:
+    """forge.yaml の最終的な探索結果を返す（見つからなければ None）。"""
+    if explicit is not None:
+        path = pathlib.Path(explicit).resolve()
+        return path if path.is_file() else None
+
+    env_value = os.environ.get("FORGE_CONFIG")
+    if env_value:
+        path = pathlib.Path(env_value).expanduser().resolve()
+        if path.is_file():
+            return path
+
+    candidate = (forge_dir / "forge.yaml").resolve()
+    return candidate if candidate.is_file() else None
+
+
+def _load_yaml(path: pathlib.Path) -> dict[str, Any]:
+    """forge.yaml を安全にロードする。空ファイルや非辞書ルートは ``{}`` 扱い。"""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    raw = yaml.safe_load(text)
+    if isinstance(raw, dict):
+        return raw
+    return {}
+
+
+def _resolve_path(
+    base: pathlib.Path, value: Any, *, default: pathlib.Path
+) -> pathlib.Path:
+    """forge.yaml の相対パス文字列を ``base`` 基準で絶対化する。
+
+    値が ``None`` または空のときは ``default`` をそのまま返す。
+    """
+    if value in (None, ""):
+        return default.resolve()
+    candidate = pathlib.Path(str(value)).expanduser()
+    if candidate.is_absolute():
+        return candidate.resolve()
+    return (base / candidate).resolve()

alpha_visualizer/routers/ideas.py

@@ -0,0 +1,57 @@
+"""アイデア API ルーター
+
+`/api/ideas` と `/api/ideas/{idea_id}` を提供する。
+ForgeConfig.ideas_json から JSON を直接読み取る。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query, Request
+
+from alpha_visualizer.forge_config import ForgeConfig
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _load_ideas(config: ForgeConfig) -> list[dict[str, Any]]:
+    ideas_path = config.ideas_json
+    if not ideas_path.exists():
+        return []
+    try:
+        data = json.loads(ideas_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning("ideas.json の読み込みに失敗: %s", e)
+        return []
+    if isinstance(data, list):
+        return data
+    # {"ideas": [...]} 形式にも対応
+    if isinstance(data, dict):
+        return data.get("ideas", [])
+    return []
+
+
+@router.get("/ideas")
+async def list_ideas(
+    request: Request,
+    status: str | None = Query(default=None),
+) -> list[dict[str, Any]]:
+    config: ForgeConfig = request.app.state.forge_config
+    ideas = _load_ideas(config)
+    if status is not None:
+        ideas = [i for i in ideas if isinstance(i, dict) and i.get("status") == status]
+    return ideas
+
+
+@router.get("/ideas/{idea_id}")
+async def get_idea(idea_id: str, request: Request) -> dict[str, Any]:
+    config: ForgeConfig = request.app.state.forge_config
+    ideas = _load_ideas(config)
+    for idea in ideas:
+        if isinstance(idea, dict) and idea.get("idea_id") == idea_id:
+            return idea
+    raise HTTPException(status_code=404, detail=f"idea_id '{idea_id}' が見つかりません")