feat: integrate TA-Lib 0.8.1 factors across research (#287)

Co-authored-by: TIANHE <TIANHE@GMAIL.COM>

Author: brokermr810

backend_api_python/app/routes/agent_v1/research.py

@@ -3,7 +3,13 @@
 
 from flask import request
 
-from app.services.factors import FactorError, get_factor, is_talib_available, list_factors
+from app.services.factors import (
+    FactorError,
+    TalibFactorError,
+    get_factor_metadata,
+    is_talib_available,
+    list_factor_catalog,
+)
 from app.services.market.watchlist import (
     add_watchlist_item,
     list_watchlist,
@@ -55,7 +61,7 @@ def list_research_universe_members(universe_id: int):
 @agent_v1_bp.route("/research/factors", methods=["GET"])
 @agent_required(SCOPE_R)
 def list_research_factors():
-    rows = list_factors(
+    rows = list_factor_catalog(
         category=(request.args.get("category") or "").strip(),
         factor_type=(request.args.get("factor_type") or "").strip(),
     )
@@ -66,8 +72,8 @@ def list_research_factors():
 @agent_required(SCOPE_R)
 def get_research_factor(factor_id: str):
     try:
-        return envelope(get_factor(factor_id).metadata())
-    except FactorError as exc:
+        return envelope(get_factor_metadata(factor_id))
+    except (FactorError, TalibFactorError) as exc:
         return error(404, exc.code, http=404)
 
 

backend_api_python/app/routes/backtest_center.py

@@ -220,6 +220,14 @@ def run_strategy_backtest():
 
 
 @backtest_center_blp.route("/factor-research", methods=["POST"])
+@backtest_center_blp.doc(
+    summary="Run factor research with built-in or TA-Lib 0.8.1 factors",
+    description=(
+        "Accepts factorId and optional factorParams. TA-Lib factors use the "
+        "talib: namespace and support explicit output selection for "
+        "multi-output functions."
+    ),
+)
 @login_required
 def run_factor_research():
     try:
@@ -232,6 +240,7 @@ def run_factor_research():
         if not start_raw or not end_raw:
             raise ValueError("strategyV2.dateRangeRequired")
         factor_id = str(payload.get("factorId") or "momentum_20")
+        factor_params = payload.get("factorParams") if isinstance(payload.get("factorParams"), dict) else {}
         groups = max(2, min(10, int(payload.get("groups") or 5)))
         holding_period = max(1, int(payload.get("holdingPeriod") or 5))
         commission = parse_rate(payload.get("commission"), default=default_commission_if_missing(None))
@@ -243,6 +252,7 @@ def run_factor_research():
             start_date=datetime.strptime(start_raw, "%Y-%m-%d"),
             end_date=datetime.strptime(end_raw, "%Y-%m-%d").replace(hour=23, minute=59, second=59),
             factor_id=factor_id,
+            factor_params=factor_params,
             groups=groups,
             holding_period=holding_period,
             commission=commission,

backend_api_python/app/routes/factors.py

@@ -6,10 +6,9 @@
 from app.services.factors import (
     FactorError,
     TalibFactorError,
-    get_factor,
+    get_factor_metadata,
     is_talib_available,
-    list_factors,
-    list_talib_factors,
+    list_factor_catalog,
 )
 from app.services.factors.research import information_coefficient, quantile_returns, winsorize_zscore
 from app.services.fundamental_data import get_fundamental_data_service
@@ -28,23 +27,22 @@ def factor_catalog():
         factor_type = str(request.args.get("type") or request.args.get("factor_type") or "").strip()
         category = str(request.args.get("category") or "").strip()
         provider = str(request.args.get("provider") or "").strip().lower()
-        data = list_factors(
+        data = list_factor_catalog(
             category=category,
             factor_type=factor_type,
         )
-        talib_data = []
-        if provider in ("", "ta-lib", "talib") and is_talib_available() and factor_type != "fundamental":
-            talib_data = [
-                item for item in list_talib_factors()
-                if not category or item.get("category") == category
-            ]
+        if provider in ("ta-lib", "talib"):
+            data = [item for item in data if item.get("provider") == "ta-lib"]
+        elif provider:
+            data = [item for item in data if item.get("provider") != "ta-lib"]
+        talib_count = sum(1 for item in data if item.get("provider") == "ta-lib")
         return jsonify({
             "code": 1,
             "msg": "success",
-            "data": data + talib_data,
+            "data": data,
             "meta": {
-                "builtInCount": len(data),
-                "talibCount": len(talib_data),
+                "builtInCount": len(data) - talib_count,
+                "talibCount": talib_count,
                 "talibAvailable": is_talib_available(),
             },
         })
@@ -59,8 +57,8 @@ def factor_catalog():
 @login_required
 def factor_detail(factor_id: str):
     try:
-        return jsonify({"code": 1, "msg": "success", "data": get_factor(factor_id).metadata()})
-    except FactorError as exc:
+        return jsonify({"code": 1, "msg": "success", "data": get_factor_metadata(factor_id)})
+    except (FactorError, TalibFactorError) as exc:
         return jsonify({"code": 0, "msg": exc.code, "data": None}), 404
 
 

backend_api_python/app/services/factors/__init__.py

@@ -16,6 +16,11 @@
     is_talib_available,
     list_talib_factors,
 )
+from app.services.factors.catalog import (
+    compute_catalog_factor,
+    get_factor_metadata,
+    list_factor_catalog,
+)
 
 __all__ = [
     "FactorDefinition",
@@ -30,4 +35,7 @@
     "compute_talib_indicator",
     "is_talib_available",
     "list_talib_factors",
+    "compute_catalog_factor",
+    "get_factor_metadata",
+    "list_factor_catalog",
 ]

backend_api_python/app/services/factors/catalog.py

@@ -0,0 +1,65 @@
+"""Unified built-in and TA-Lib factor catalog helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import pandas as pd
+
+from .registry import FactorError, compute_factor, get_factor, list_factors
+from .talib_adapter import (
+    TalibFactorError,
+    compute_talib_factor,
+    is_talib_available,
+    list_talib_factors,
+)
+
+
+def list_factor_catalog(*, category: str = "", factor_type: str = "") -> list[dict[str, Any]]:
+    rows = list_factors(category=category, factor_type=factor_type)
+    if factor_type == "fundamental" or not is_talib_available():
+        return rows
+    rows.extend(
+        item for item in list_talib_factors()
+        if not category or item.get("category") == category
+    )
+    return sorted(rows, key=lambda item: (
+        str(item.get("factor_type") or ""),
+        str(item.get("category") or ""),
+        str(item.get("factor_id") or "").lower(),
+    ))
+
+
+def get_factor_metadata(factor_id: str) -> dict[str, Any]:
+    canonical = str(factor_id or "").strip()
+    if canonical.lower().startswith("talib:"):
+        target = canonical.upper()
+        if not is_talib_available():
+            raise TalibFactorError("factor.talibUnavailable")
+        item = next(
+            (row for row in list_talib_factors() if row["factor_id"].upper() == target),
+            None,
+        )
+        if item is None:
+            raise TalibFactorError("factor.notFound")
+        return item
+    return get_factor(canonical.lower()).metadata()
+
+
+def compute_catalog_factor(
+    factor_id: str,
+    frame: pd.DataFrame,
+    params: Mapping[str, Any] | None = None,
+) -> float:
+    canonical = str(factor_id or "").strip()
+    if canonical.lower().startswith("talib:"):
+        normalized = dict(params or {})
+        output = str(normalized.pop("output", "") or "")
+        return compute_talib_factor(canonical, frame, normalized, output=output)
+    try:
+        return compute_factor(canonical.lower(), frame, params)
+    except FactorError as exc:
+        if exc.code != "factor.notFound":
+            raise
+    return compute_talib_factor(canonical, frame, params)

backend_api_python/app/services/factors/talib_adapter.py

@@ -9,8 +9,16 @@
 import pandas as pd
 
 
-MINIMUM_FUNCTION_COUNT = 129
+MINIMUM_FUNCTION_COUNT = 201
 
+TA_LIB_081_FUNCTIONS = frozenset({
+    "AC", "ADR", "AO", "CMF", "CMOU", "COPPOCK", "CUMSUM", "CVI",
+    "DONCHIAN", "DPO", "EFI", "ER", "ERI", "FOSC", "FRACTAL", "HA",
+    "HMA", "KC", "KDJ", "MARKETFI", "MASSI", "NVI", "PERCENTILE",
+    "PERCENTRANK", "PVI", "PVO", "PVT", "QSTICK", "RMA", "RVI", "RVOL",
+    "SMI", "SUPERTREND", "TSI", "VHF", "VORTEX", "VWAP", "VWMA", "WAD",
+    "ZLEMA",
+})
 
 class TalibFactorError(ValueError):
     def __init__(self, code: str):
@@ -41,32 +49,38 @@ def list_talib_factors() -> list[dict[str, Any]]:
         required_fields = tuple(sorted(_flatten_input_names(info.get("input_names") or {})))
         parameters = dict(info.get("parameters") or {})
         outputs = list(info.get("output_names") or [])
+        if len(outputs) > 1:
+            parameters["output"] = outputs[0]
         output.append({
             "factor_id": f"talib:{name.upper()}",
             "library_id": name.upper(),
             "version": str(getattr(talib, "__version__", "")),
+            "display_name": str(info.get("display_name") or name),
             "name_i18n_key": f"factor.talib.{name.lower()}.name",
             "description_i18n_key": f"factor.talib.{name.lower()}.description",
             "category": _category(group_by_name.get(name.upper(), "")),
             "factor_type": "technical",
             "provider": "ta-lib",
+            "introduced_in": "0.8.1" if name.upper() in TA_LIB_081_FUNCTIONS else "",
             "required_fields": list(required_fields),
             "default_params": parameters,
-            "parameter_schema": {
-                key: {"type": _parameter_type(value), "default": value}
-                for key, value in parameters.items()
-            },
+            "parameter_schema": _parameter_schema(parameters, outputs),
             "outputs": outputs,
+            "direction_hint": "neutral",
             "supported_contexts": ["cta", "portfolio"],
             "default_warmup_bars": int(getattr(function, "lookback", 0) or 0),
         })
     return output
 
 
 def assert_talib_catalog_ready() -> int:
-    count = len(list_talib_factors())
-    if count < MINIMUM_FUNCTION_COUNT:
-        raise TalibFactorError(f"factor.talibCatalogIncomplete:{count}")
+    catalog = list_talib_factors()
+    count = len(catalog)
+    available = {item["library_id"] for item in catalog}
+    missing = sorted(TA_LIB_081_FUNCTIONS - available)
+    if count < MINIMUM_FUNCTION_COUNT or missing:
+        suffix = f":{','.join(missing)}" if missing else ""
+        raise TalibFactorError(f"factor.talibCatalogIncomplete:{count}{suffix}")
     return count
 
 
@@ -88,10 +102,7 @@ def compute_talib_indicator(
         raise TalibFactorError(f"factor.missingFields:{','.join(missing)}")
     clean = frame.copy()
     clean.columns = [str(column).strip().lower() for column in clean.columns]
-    normalized = dict(params or {})
-    if library_id == "SMA" and "period" in normalized:
-        period = normalized.pop("period")
-        normalized.setdefault("timeperiod", period)
+    normalized = _normalized_parameters(function, params)
     try:
         result = function(clean, **normalized)
     except Exception as exc:
@@ -126,9 +137,11 @@ def compute_talib_factor(
     *,
     output: str = "",
 ) -> float:
-    result = compute_talib_indicator(name, frame, params)
+    normalized = dict(params or {})
+    selected_from_params = normalized.pop("output", "")
+    result = compute_talib_indicator(name, frame, normalized)
     if isinstance(result, pd.DataFrame):
-        selected = str(output or "").strip()
+        selected = str(output or selected_from_params or "").strip()
         if not selected:
             selected = str(result.columns[0])
         if selected not in result.columns:
@@ -177,6 +190,38 @@ def _parameter_type(value: Any) -> str:
     return "string"
 
 
+def _parameter_schema(parameters: Mapping[str, Any], outputs: list[str]) -> dict[str, dict[str, Any]]:
+    schema = {}
+    for key, value in parameters.items():
+        if key == "output":
+            schema[key] = {"type": "enum", "default": value, "options": list(outputs)}
+            continue
+        item = {"type": _parameter_type(value), "default": value}
+        if item["type"] == "integer":
+            item.update({"minimum": 1, "maximum": 5000, "step": 1})
+        elif item["type"] == "number":
+            item.update({"step": 0.1})
+        schema[key] = item
+    return schema
+
+
+def _normalized_parameters(function: Any, params: Mapping[str, Any] | None) -> dict[str, Any]:
+    supported = set((function.info.get("parameters") or {}).keys())
+    normalized = dict(params or {})
+    normalized.pop("output", None)
+    aliases = {
+        "period": "timeperiod",
+        "fast_period": "fastperiod",
+        "slow_period": "slowperiod",
+        "signal_period": "signalperiod",
+    }
+    for source, target in aliases.items():
+        if source in normalized and target in supported:
+            value = normalized.pop(source)
+            normalized.setdefault(target, value)
+    return normalized
+
+
 def _category(group: str) -> str:
     raw = str(group or "").strip().lower()
     if "pattern" in raw: