feat: operationalize local Tushare Qlib research

tools/tushare_qlib.py

@@ -8,6 +8,10 @@ from pathlib import Path
 import sys
 from typing import Any, Mapping, Optional
 
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
 from adapters.tushare_local import (
     TushareMirrorError,
     build_qlib_provider,
@@ -16,6 +20,20 @@ from adapters.tushare_local import (
 )
 
 
+def _assert_json_outside_provider(
+    output_json: Optional[str],
+    provider_dir: str,
+) -> None:
+    if output_json is None:
+        return
+    destination = Path(output_json).expanduser().resolve()
+    provider = Path(provider_dir).expanduser().resolve()
+    if destination == provider or provider in destination.parents:
+        raise ValueError(
+            "output-json must be outside the immutable provider directory"
+        )
+
+
 def _write_json(path: Optional[str], payload: Mapping[str, Any]) -> None:
     if path is None:
         return
@@ -52,6 +70,22 @@ def build_parser() -> argparse.ArgumentParser:
     build.add_argument("--end", required=True)
     build.add_argument("--market-name", default="tushare_a")
     build.add_argument("--benchmark-symbol", default="SH999999")
+    build.add_argument(
+        "--benchmark-index-code",
+        help="use real Tushare index_daily data, for example 000905.SH",
+    )
+    build.add_argument(
+        "--universe-index-code",
+        help="build point-in-time market intervals from index_weight snapshots",
+    )
+    build.add_argument(
+        "--expected-constituent-count",
+        type=int,
+        help=(
+            "required for unknown index codes; known indices such as "
+            "000905.SH use a built-in exact count"
+        ),
+    )
     build.add_argument("--minimum-observations", type=int, default=60)
     build.add_argument(
         "--allow-unadjusted",
@@ -81,6 +115,10 @@ def _main(argv: Optional[list[str]] = None) -> int:
                 verify_files=not args.skip_file_verification,
             )
         elif args.command == "build":
+            _assert_json_outside_provider(
+                args.output_json,
+                args.output_dir,
+            )
             result = build_qlib_provider(
                 args.mirror_root,
                 args.output_dir,
@@ -91,8 +129,15 @@ def _main(argv: Optional[list[str]] = None) -> int:
                 minimum_observations=args.minimum_observations,
                 allow_unadjusted=args.allow_unadjusted,
                 expand_range=args.ohlc_policy == "expand-range",
+                benchmark_index_code=args.benchmark_index_code,
+                universe_index_code=args.universe_index_code,
+                expected_constituent_count=args.expected_constituent_count,
             )
         else:
+            _assert_json_outside_provider(
+                args.output_json,
+                args.provider_dir,
+            )
             result = verify_qlib_provider(args.provider_dir)
         _write_json(args.output_json, result)
     except (OSError, ValueError, TushareMirrorError) as exc: