cnhkmcp 2.3.2__py3-none-any.whl → 2.3.4__py3-none-any.whl

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/config.json

@@ -0,0 +1,6 @@
+{
+  "username": "xxxxxxxxx.Li@xxxxx.com",
+  "password": "xxxxx@xxxxxxx",
+  "BRAIN_API_URL": "https://api.worldquantbrain.com",
+  "BRAIN_URL": "https://platform.worldquantbrain.com"
+}

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/fundamental28_GLB_1_idea_1769874845978315000.json

@@ -0,0 +1,10 @@
+{
+    "template": "divide({value_03501a}, {value_02300q})",
+    "idea": "**Concept**: Equity Capital Structure Ratio\n- **Sample Fields Used**: `value_03501a`, `value_02300q`\n- **Definition**: Common equity as a proportion of total assets (Equity/Assets ratio)\n- **Why This Feature**: Measures financial leverage and capital structure conservatism; higher equity indicates lower leverage risk\n- **Logical Meaning**: Ownership cushion against asset value declines; inverse of leverage ratio\n- **is filling nan necessary**: we have some operators to fill nan value like ts_backfill() or group_mean() etc. however, in some cases, if the nan value itself has some meaning, then we should not fill it blindly since it may introduce some bias. so before filling nan value, we should think about whether the nan value has some meaning in the specific scenario. Annual equity vs quarterly assets creates frequency mismatch; do not interpolate annual data to quarterly.\n- **Directionality**: Higher values indicate less leveraged, more conservative capital structure (typically lower risk)\n- **Boundary Conditions**: Values near 1 indicate no debt; near 0 indicate highly leveraged or negative equity situations",
+    "expression_list": [
+        "divide(fnd28_bdea_value_03501a, fnd28_bsassetq_value_02300q)",
+        "divide(fnd28_bdea_value_03501a, fnd28_nddq1_value_02300q)",
+        "divide(fnd28_fsa1_value_03501a, fnd28_bsassetq_value_02300q)",
+        "divide(fnd28_fsa1_value_03501a, fnd28_nddq1_value_02300q)"
+    ]
+}

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/helpful_functions.py

@@ -0,0 +1,180 @@
+import json
+import os
+from typing import Union
+
+import pandas as pd
+from pandas.io.formats.style import Styler
+
+brain_api_url = os.environ.get("BRAIN_API_URL", "https://api.worldquantbrain.com")
+brain_url = os.environ.get("BRAIN_URL", "https://platform.worldquantbrain.com")
+
+
+def make_clickable_alpha_id(alpha_id: str) -> str:
+    """
+    Create a clickable HTML link for an alpha ID.
+
+    Args:
+        alpha_id (str): The ID of the alpha.
+
+    Returns:
+        str: An HTML string containing a clickable link to the alpha's page on the platform.
+    """
+
+    url = brain_url + "/alpha/"
+    return f'<a href="{url}{alpha_id}">{alpha_id}</a>'
+
+
+def prettify_result(
+    result: list, detailed_tests_view: bool = False, clickable_alpha_id: bool = False
+) -> Union[pd.DataFrame, Styler]:
+    """
+    Combine and format simulation results into a single DataFrame for analysis.
+
+    Args:
+        result (list): A list of dictionaries containing simulation results.
+        detailed_tests_view (bool, optional): If True, include detailed test results. Defaults to False.
+        clickable_alpha_id (bool, optional): If True, make alpha IDs clickable. Defaults to False.
+
+    Returns:
+        pandas.DataFrame or pandas.io.formats.style.Styler: A DataFrame containing formatted results,
+        optionally with clickable alpha IDs.
+    """
+    list_of_is_stats = [result[x]["is_stats"] for x in range(len(result)) if result[x]["is_stats"] is not None]
+    is_stats_df = pd.concat(list_of_is_stats).reset_index(drop=True)
+    is_stats_df = is_stats_df.sort_values("fitness", ascending=False)
+
+    expressions = {
+        result[x]["alpha_id"]: (
+            {
+                "selection": result[x]["simulate_data"]["selection"],
+                "combo": result[x]["simulate_data"]["combo"],
+            }
+            if result[x]["simulate_data"]["type"] == "SUPER"
+            else result[x]["simulate_data"]["regular"]
+        )
+        for x in range(len(result))
+        if result[x]["is_stats"] is not None
+    }
+    expression_df = pd.DataFrame(list(expressions.items()), columns=["alpha_id", "expression"])
+
+    list_of_is_tests = [result[x]["is_tests"] for x in range(len(result)) if result[x]["is_tests"] is not None]
+    is_tests_df = pd.concat(list_of_is_tests, sort=True).reset_index(drop=True)
+    is_tests_df = is_tests_df[is_tests_df["result"] != "WARNING"]
+    if detailed_tests_view:
+        cols = ["limit", "result", "value"]
+        is_tests_df["details"] = is_tests_df[cols].to_dict(orient="records")
+        is_tests_df = is_tests_df.pivot(index="alpha_id", columns="name", values="details").reset_index()
+    else:
+        is_tests_df = is_tests_df.pivot(index="alpha_id", columns="name", values="result").reset_index()
+
+    alpha_stats = pd.merge(is_stats_df, expression_df, on="alpha_id")
+    alpha_stats = pd.merge(alpha_stats, is_tests_df, on="alpha_id")
+    alpha_stats = alpha_stats.drop(columns=alpha_stats.columns[(alpha_stats == "PENDING").any()])
+    alpha_stats.columns = alpha_stats.columns.str.replace("(?<=[a-z])(?=[A-Z])", "_", regex=True).str.lower()
+    if clickable_alpha_id:
+        return alpha_stats.style.format({"alpha_id": lambda x: make_clickable_alpha_id(str(x))})
+    return alpha_stats
+
+
+def concat_pnl(result: list) -> pd.DataFrame:
+    """
+    Combine PnL results from multiple alphas into a single DataFrame.
+
+    Args:
+        result (list): A list of dictionaries containing simulation results with PnL data.
+
+    Returns:
+        pandas.DataFrame: A DataFrame containing combined PnL data for all alphas.
+    """
+    list_of_pnls = [result[x]["pnl"] for x in range(len(result)) if result[x]["pnl"] is not None]
+    pnls_df = pd.concat(list_of_pnls).reset_index()
+
+    return pnls_df
+
+
+def concat_is_tests(result: list) -> pd.DataFrame:
+    """
+    Combine in-sample test results from multiple alphas into a single DataFrame.
+
+    Args:
+        result (list): A list of dictionaries containing simulation results with in-sample test data.
+
+    Returns:
+        pandas.DataFrame: A DataFrame containing combined in-sample test results for all alphas.
+    """
+    is_tests_list = [result[x]["is_tests"] for x in range(len(result)) if result[x]["is_tests"] is not None]
+    is_tests_df = pd.concat(is_tests_list, sort=True).reset_index(drop=True)
+    return is_tests_df
+
+
+def save_simulation_result(result: dict) -> None:
+    """
+    Save the simulation result to a JSON file in the 'simulation_results' folder.
+
+    Args:
+        result (dict): A dictionary containing the simulation result for an alpha.
+    """
+
+    alpha_id = result["id"]
+    region = result["settings"]["region"]
+    folder_path = "simulation_results/"
+    file_path = os.path.join(folder_path, f"{alpha_id}_{region}")
+
+    os.makedirs(folder_path, exist_ok=True)
+
+    with open(file_path, "w", encoding="utf-8") as file:
+        json.dump(result, file)
+
+
+def save_pnl(pnl_df: pd.DataFrame, alpha_id: str, region: str) -> None:
+    """
+    Save the PnL data for an alpha to a CSV file in the 'alphas_pnl' folder.
+
+    Args:
+        pnl_df (pandas.DataFrame): The DataFrame containing PnL data.
+        alpha_id (str): The ID of the alpha.
+        region (str): The region for which the PnL data was generated.
+    """
+
+    folder_path = "alphas_pnl/"
+    file_path = os.path.join(folder_path, f"{alpha_id}_{region}.csv")
+    os.makedirs(folder_path, exist_ok=True)
+
+    pnl_df.to_csv(file_path)
+
+
+def save_yearly_stats(yearly_stats: pd.DataFrame, alpha_id: str, region: str):
+    """
+    Save the yearly statistics for an alpha to a CSV file in the 'yearly_stats' folder.
+
+    Args:
+        yearly_stats (pandas.DataFrame): The DataFrame containing yearly statistics.
+        alpha_id (str): The ID of the alpha.
+        region (str): The region for which the statistics were generated.
+    """
+
+    folder_path = "yearly_stats/"
+    file_path = os.path.join(folder_path, f"{alpha_id}_{region}.csv")
+    os.makedirs(folder_path, exist_ok=True)
+
+    yearly_stats.to_csv(file_path, index=False)
+
+
+def expand_dict_columns(data: pd.DataFrame) -> pd.DataFrame:
+    """
+    Expand dictionary columns in a DataFrame into separate columns.
+
+    Args:
+        data (pandas.DataFrame): The input DataFrame with dictionary columns.
+
+    Returns:
+        pandas.DataFrame: A new DataFrame with expanded columns.
+    """
+    dict_columns = list(filter(lambda x: isinstance(data[x].iloc[0], dict), data.columns))
+    new_columns = pd.concat(
+        [data[col].apply(pd.Series).rename(columns=lambda x: f"{col}_{x}") for col in dict_columns],
+        axis=1,
+    )
+
+    data = pd.concat([data, new_columns], axis=1)
+    return data

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/scripts/build_alpha_list.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SKILL_DIR = Path(__file__).resolve().parents[1]
+if str(SKILL_DIR) not in sys.path:
+    sys.path.insert(0, str(SKILL_DIR))
+
+import ace_lib
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--idea", required=True, help="idea_context.json")
+    ap.add_argument("--settings_json", required=True, help="JSON string of settings config")
+    ap.add_argument("--out", required=True, help="alpha_list.json (will append if exists)")
+    args = ap.parse_args()
+
+    idea_ctx = _load_json(Path(args.idea).resolve())
+    
+    try:
+        settings_doc = json.loads(args.settings_json)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON string provided for --settings_json: {e}")
+
+    # Support wrapped key "resolved" or flat dict
+    resolved_raw = settings_doc.get("resolved", settings_doc)
+    if not isinstance(resolved_raw, dict):
+        raise ValueError("Settings file must contain settings dict or 'resolved' key")
+
+    # Robustness: Normalize keys to lowercase to handle PascalCase (Region vs region)
+    # and camelCase (nanHandling vs nanhandling) inconsistencies.
+    resolved = {k.lower(): v for k, v in resolved_raw.items()}
+    
+    out_path = Path(args.out).resolve()
+    existing_alphas = []
+    if out_path.exists():
+        try:
+            existing_alphas = _load_json(out_path)
+            if not isinstance(existing_alphas, list):
+                print(f"Warning: Existing file {out_path} is not a list. Overwriting.")
+                existing_alphas = []
+        except Exception as e:
+            print(f"Warning: Could not read existing {out_path}: {e}. Overwriting.")
+            existing_alphas = []
+
+    expressions = idea_ctx.get("expression_list") or []
+    if not isinstance(expressions, list) or not all(isinstance(x, str) for x in expressions):
+        raise ValueError("idea_context.json must contain expression_list: list[str]")
+
+    new_alphas = [
+        ace_lib.generate_alpha(
+            regular=expr,
+            alpha_type="REGULAR",
+            region=resolved["region"],
+            universe=resolved["universe"],
+            delay=int(resolved["delay"]),
+            decay=int(resolved.get("decay", 0)),
+            neutralization=resolved["neutralization"],
+            truncation=float(resolved.get("truncation", 0.08)),
+            pasteurization=resolved.get("pasteurization", "ON"),
+            test_period=resolved.get("testperiod", "P0Y0M0D"),
+            unit_handling=resolved.get("unithandling", "VERIFY"),
+            nan_handling=resolved.get("nanhandling", "OFF"),
+            max_trade=resolved.get("maxtrade", "OFF"),
+            visualization=bool(resolved.get("visualization", False)),
+        )
+        for expr in expressions
+    ]
+    
+    final_list = existing_alphas + new_alphas
+
+    out_path.write_text(json.dumps(final_list, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"Wrote {len(new_alphas)} new alphas. Total: {len(final_list)} alphas in {out_path}")
+
+
+if __name__ == "__main__":
+    main()

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/scripts/fetch_sim_options.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+SKILL_DIR = Path(__file__).resolve().parents[1]
+if str(SKILL_DIR) not in sys.path:
+    sys.path.insert(0, str(SKILL_DIR))
+
+import ace_lib
+from scripts.load_credentials import load_credentials
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument(
+        "--out",
+        required=True,
+        help="Output snapshot JSON file (e.g., sim_options_snapshot.json)",
+    )
+    args = ap.parse_args()
+
+    skill_dir = Path(__file__).resolve().parents[1]
+    creds = load_credentials(skill_dir=skill_dir)
+
+    # Ensure ace_lib uses configured API base for normal requests.
+    # NOTE: get_instrument_type_region_delay historically hard-coded the URL; we patch ace_lib to respect brain_api_url.
+    ace_lib.brain_api_url = creds.brain_api_url
+
+    def _get_credentials():
+        return creds.username, creds.password
+
+    ace_lib.get_credentials = _get_credentials  # type: ignore[assignment]
+
+    s = ace_lib.start_session()
+    df = ace_lib.get_instrument_type_region_delay(s)
+
+    payload = {
+        "brain_api_url": creds.brain_api_url,
+        "rows": df.to_dict(orient="records"),
+    }
+
+    out_path = Path(args.out).resolve()
+    out_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"Wrote simulation options snapshot: {out_path} ({len(df)} rows)")
+
+
+if __name__ == "__main__":
+    main()

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/scripts/load_credentials.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class BrainCredentials:
+    username: str
+    password: str
+    brain_api_url: str = "https://api.worldquantbrain.com"
+    brain_url: str = "https://platform.worldquantbrain.com"
+
+
+def _read_json_file(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+
+
+def load_credentials(
+    *,
+    skill_dir: Path,
+    config_filename: str = "config.json",
+    allow_env: bool = True,
+    allow_home_secrets: bool = True,
+) -> BrainCredentials:
+    """Load credentials without printing secrets.
+
+    Priority:
+      1) env vars (if allow_env)
+      2) skill-local config.json
+      3) ~/secrets/platform-brain.json (if allow_home_secrets)
+
+    Supported env vars:
+      - BRAIN_USERNAME or BRAIN_EMAIL
+      - BRAIN_PASSWORD
+      - BRAIN_API_URL (optional)
+      - BRAIN_URL (optional)
+    """
+
+    env_username = ""
+    env_password = ""
+    brain_api_url = os.environ.get("BRAIN_API_URL", "https://api.worldquantbrain.com")
+    brain_url = os.environ.get("BRAIN_URL", "https://platform.worldquantbrain.com")
+
+    if allow_env:
+        env_username = os.environ.get("BRAIN_USERNAME", os.environ.get("BRAIN_EMAIL", ""))
+        env_password = os.environ.get("BRAIN_PASSWORD", "")
+
+    if env_username and env_password:
+        return BrainCredentials(
+            username=env_username,
+            password=env_password,
+            brain_api_url=brain_api_url,
+            brain_url=brain_url,
+        )
+
+    cfg_path = skill_dir / config_filename
+    cfg = _read_json_file(cfg_path)
+
+    username = (cfg.get("username") or cfg.get("email") or "").strip()
+    password = (cfg.get("password") or "").strip()
+    brain_api_url = (cfg.get("BRAIN_API_URL") or brain_api_url).strip() or brain_api_url
+    brain_url = (cfg.get("BRAIN_URL") or brain_url).strip() or brain_url
+
+    if username and password:
+        return BrainCredentials(username=username, password=password, brain_api_url=brain_api_url, brain_url=brain_url)
+
+    if allow_home_secrets:
+        home_secret_path = Path.home() / "secrets" / "platform-brain.json"
+        secret = _read_json_file(home_secret_path)
+        username = (secret.get("email") or secret.get("username") or "").strip()
+        password = (secret.get("password") or "").strip()
+        if username and password:
+            return BrainCredentials(
+                username=username,
+                password=password,
+                brain_api_url=brain_api_url,
+                brain_url=brain_url,
+            )
+
+    raise RuntimeError(
+        "Missing BRAIN credentials. Provide either: "
+        "(1) env vars BRAIN_USERNAME/BRAIN_EMAIL + BRAIN_PASSWORD, or "
+        f"(2) {cfg_path} with username/password, or "
+        "(3) ~/secrets/platform-brain.json with email/password. "
+        "See config.example.json for the expected schema."
+    )

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/scripts/parse_idea_file.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any
+
+SKILL_DIR = Path(__file__).resolve().parents[1]
+if str(SKILL_DIR) not in sys.path:
+    sys.path.insert(0, str(SKILL_DIR))
+
+
+@dataclass(frozen=True)
+class IdeaContext:
+    input_file: str
+    dataset_id: str
+    region: str
+    delay: int
+    template: str
+    idea: str
+    expression_list: list[str]
+
+
+_FILENAME_RE = re.compile(
+    r"^(?P<dataset>[^_]+)_(?P<region>[A-Za-z]+)_(?P<delay>[01])_idea_\d+\.json$"
+)
+
+
+def parse_filename_metadata(path: Path) -> tuple[str, str, int]:
+    m = _FILENAME_RE.match(path.name)
+    if not m:
+        raise ValueError(
+            "Unsupported filename format. Expected like: fundamental28_GLB_1_idea_<ts>.json; "
+            f"got: {path.name}"
+        )
+    dataset = m.group("dataset")
+    region = m.group("region")
+    delay = int(m.group("delay"))
+    return dataset, region, delay
+
+
+def load_idea_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def build_context(path: Path) -> IdeaContext:
+    dataset, region, delay = parse_filename_metadata(path)
+    data = load_idea_json(path)
+
+    template = str(data.get("template") or "")
+    idea = str(data.get("idea") or "")
+    expression_list = data.get("expression_list") or []
+    if not isinstance(expression_list, list) or not all(isinstance(x, str) for x in expression_list):
+        raise ValueError("expression_list must be a list of strings")
+
+    return IdeaContext(
+        input_file=str(path),
+        dataset_id=dataset,
+        region=region,
+        delay=delay,
+        template=template,
+        idea=idea,
+        expression_list=expression_list,
+    )
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--input", required=True, help="Path to idea JSON")
+    ap.add_argument("--out", required=True, help="Output idea_context.json")
+    args = ap.parse_args()
+
+    input_path = Path(args.input).resolve()
+    out_path = Path(args.out).resolve()
+
+    ctx = build_context(input_path)
+    out_path.write_text(json.dumps(asdict(ctx), ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"Wrote idea context: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

cnhkmcp/untracked/skills/brain-inspectTemplate-create-Setting/scripts/process_template.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SKILL_DIR = Path(__file__).resolve().parents[1]
+SCRIPTS_DIR = SKILL_DIR / "scripts"
+PYTHON_EXE = sys.executable
+
+def run_step(script_name: str, args: list[str]) -> None:
+    """Run a script from the scripts directory with the given arguments."""
+    script_path = SCRIPTS_DIR / script_name
+    cmd = [PYTHON_EXE, str(script_path)] + args
+    print(f"Running: {script_name} {' '.join(args)}")
+    try:
+        subprocess.run(cmd, check=True, cwd=SKILL_DIR)
+    except subprocess.CalledProcessError as e:
+        print(f"Error running {script_name}: {e}")
+        sys.exit(1)
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Process a single template file and generate artifacts in a dedicated folder.")
+    parser.add_argument("--file", required=True, help="Path to the input idea JSON file.")
+    parser.add_argument("--force-fetch-options", action="store_true", help="Force fetching new simulation options even if snapshot exists.")
+    args = parser.parse_args()
+
+    input_path = Path(args.file).resolve()
+    if not input_path.exists():
+        print(f"Error: Input file not found: {input_path}")
+        sys.exit(1)
+
+    # 1. Create output directory
+    output_dir = SKILL_DIR / "processed_templates" / input_path.stem
+    output_dir.mkdir(parents=True, exist_ok=True)
+    print(f"Output directory: {output_dir}")
+
+    # 2. Parse idea file
+    idea_context_path = output_dir / "idea_context.json"
+    run_step("parse_idea_file.py", ["--input", str(input_path), "--out", str(idea_context_path)])
+
+    # 3. Handle Simulation Options
+    # Strategy: Use shared snapshot in skill root if available to save time/network, unless forced.
+    global_options_path = SKILL_DIR / "sim_options_snapshot.json"
+    
+    if args.force_fetch_options or not global_options_path.exists():
+        print("Fetching simulation options (network required)...")
+        run_step("fetch_sim_options.py", ["--out", str(global_options_path)])
+    
+    # Optional: Copy snapshot to output dir for full reproducibility? 
+    # Let's verify if the user wants strictly isolated execution. 
+    # For now, we pass the global path to resolve_settings.
+    
+    # 4. Resolve Candidates (Not final choice)
+    candidates_path = output_dir / "settings_candidates.json"
+    run_step("resolve_settings.py", [
+        "--idea", str(idea_context_path),
+        "--options", str(global_options_path),
+        "--out", str(candidates_path)
+    ])
+
+    print("\n-------------------------------------------------------------")
+    print("STEP 1 COMPLETE: Candidates Generated")
+    print(f"Candidates file: {candidates_path}")
+    print("-------------------------------------------------------------")
+    print("ACTION REQUIRED FOR AI/AGENT:")
+    print("1. Read 'idea_context.json' (for intent) and 'settings_candidates.json' (for valid options).")
+    print("2. Decide on ONE OR MORE combinations of settings (Universe, Neutralization, Decay, NaN).")
+    print("3. For EACH chosen setting combination, run 'build_alpha_list.py' directly with JSON string:")
+    print(f"   python scripts/build_alpha_list.py --idea {idea_context_path} --out {output_dir}/alpha_list.json --settings_json '{{...json...}}'")
+    print("   (The script will APPEND new alphas to alpha_list.json)")
+    print("-------------------------------------------------------------")
+
+    # Stop here to let AI decide.
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()