reportify-sdk 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

reportify_sdk/quant.py

@@ -2,22 +2,30 @@
 Quant Module
 
 Provides quantitative analysis tools including indicators, factors, quotes, and backtesting.
+Based on Mai-language syntax compatible with TongDaXin/TongHuaShun.
 """
 
-from typing import Any
+from typing import Any, Literal
 
 import pandas as pd
 
 
+StockMarket = Literal["cn", "hk", "us"]
+
+
 class QuantModule:
     """
     Quantitative analysis module
 
-    Access technical indicators, factors, quotes, and backtesting functionality.
+    Access technical indicators, factors, OHLCV quotes, and backtesting functionality.
+    Uses Mai-language syntax for formulas.
 
     Example:
         >>> quant = client.quant
-        >>> indicators = quant.indicators(symbols=["US:AAPL"], indicators=["ma", "rsi"])
+        >>> # Compute RSI indicator
+        >>> df = quant.compute_indicators(["000001"], "RSI(14)")
+        >>> # Screen stocks by formula
+        >>> stocks = quant.screen(formula="RSI(14) < 30")
     """
 
     def __init__(self, client):
@@ -27,231 +35,285 @@ class QuantModule:
     # Indicators
     # -------------------------------------------------------------------------
 
-    def indicators(
+    def list_indicators(self) -> list[dict[str, Any]]:
+        """
+        Get list of available technical indicators
+
+        Returns:
+            List of indicator definitions with name, description, and fields
+
+        Example:
+            >>> indicators = client.quant.list_indicators()
+            >>> for ind in indicators:
+            ...     print(f"{ind['name']}: {ind['description']}")
+            ...     print(f"  Fields: {ind['fields']}")
+        """
+        return self._client._get("/v1/quant/indicators")
+
+    def compute_indicators(
         self,
         symbols: list[str],
-        indicators: list[str],
+        formula: str,
         *,
+        market: StockMarket = "cn",
         start_date: str | None = None,
         end_date: str | None = None,
-        interval: str = "1d",
-        params: dict[str, Any] | None = None,
     ) -> pd.DataFrame:
         """
-        Get technical indicators for given symbols
+        Compute indicator values for given symbols
 
         Args:
-            symbols: List of stock symbols (e.g., ["US:AAPL", "US:MSFT"])
-            indicators: List of indicator names (e.g., ["ma", "rsi", "macd", "bollinger"])
-            start_date: Start date (YYYY-MM-DD)
-            end_date: End date (YYYY-MM-DD)
-            interval: Data interval ("1d", "1w", "1m")
-            params: Additional indicator parameters (e.g., {"ma_period": 20})
+            symbols: List of stock codes (e.g., ["000001", "600519"])
+            formula: Indicator formula (e.g., "RSI(14)", "MACD()", "MACD(12,26,9)")
+            market: Stock market ("cn", "hk", "us"), default "cn"
+            start_date: Start date (YYYY-MM-DD), default 3 months ago
+            end_date: End date (YYYY-MM-DD), default today
 
         Returns:
             DataFrame with indicator values
 
         Example:
-            >>> df = client.quant.indicators(
-            ...     symbols=["US:AAPL"],
-            ...     indicators=["ma", "rsi"],
-            ...     params={"ma_period": 20, "rsi_period": 14}
-            ... )
-            >>> print(df[["close", "ma_20", "rsi_14"]])
+            >>> # RSI indicator
+            >>> df = client.quant.compute_indicators(["000001"], "RSI(14)")
+            >>> print(df[["symbol", "date", "rsi"]])
+            
+            >>> # MACD indicator
+            >>> df = client.quant.compute_indicators(["000001"], "MACD()")
+            >>> print(df[["symbol", "date", "dif", "dea", "macd"]])
+            
+            >>> # KDJ indicator
+            >>> df = client.quant.compute_indicators(["000001"], "KDJ(9,3,3)")
+            >>> print(df[["symbol", "date", "k", "d", "j"]])
         """
         data: dict[str, Any] = {
             "symbols": symbols,
-            "indicators": indicators,
-            "interval": interval,
+            "formula": formula,
+            "market": market,
         }
         if start_date:
             data["start_date"] = start_date
         if end_date:
             data["end_date"] = end_date
-        if params:
-            data["params"] = params
 
-        response = self._client._post("/v2/quant/indicators", json=data)
-        return self._to_dataframe(response.get("data", []))
+        response = self._client._post("/v1/quant/indicators/compute", json=data)
+        return self._to_dataframe(response.get("datas", []))
+
+    # -------------------------------------------------------------------------
+    # Factors
+    # -------------------------------------------------------------------------
 
-    def indicator_list(self) -> list[dict[str, Any]]:
+    def list_factors(self) -> list[dict[str, Any]]:
         """
-        Get list of available technical indicators
+        Get list of available factors (variables and functions)
+
+        Returns factors organized by level:
+        - Level 0 Variables: CLOSE, OPEN, HIGH, LOW, VOLUME
+        - Level 0 Functions: MA, EMA, REF, HHV, LLV, STD, etc.
+        - Level 1 Functions: CROSS, COUNT, EVERY, etc.
+        - Level 2 Functions: MACD, KDJ, RSI, BOLL, etc.
 
         Returns:
-            List of indicator definitions with name, description, and parameters
+            List of factor definitions
 
         Example:
-            >>> indicators = client.quant.indicator_list()
-            >>> for ind in indicators:
-            ...     print(f"{ind['name']}: {ind['description']}")
+            >>> factors = client.quant.list_factors()
+            >>> for f in factors:
+            ...     print(f"{f['name']} ({f['type']}, level {f['level']})")
         """
-        response = self._client._get("/v2/quant/indicators")
-        return response.get("indicators", [])
-
-    # -------------------------------------------------------------------------
-    # Factors
-    # -------------------------------------------------------------------------
+        return self._client._get("/v1/quant/factors")
 
-    def factors(
+    def compute_factors(
         self,
         symbols: list[str],
-        factors: list[str],
+        formula: str,
         *,
+        market: StockMarket = "cn",
         start_date: str | None = None,
         end_date: str | None = None,
-        frequency: str = "daily",
     ) -> pd.DataFrame:
         """
-        Get factor data for given symbols
+        Compute factor values for given symbols
+
+        Uses Mai-language syntax compatible with TongDaXin/TongHuaShun.
 
         Args:
-            symbols: List of stock symbols
-            factors: List of factor names (e.g., ["momentum", "value", "quality", "size"])
-            start_date: Start date (YYYY-MM-DD)
-            end_date: End date (YYYY-MM-DD)
-            frequency: Data frequency ("daily", "weekly", "monthly")
+            symbols: List of stock codes
+            formula: Factor formula using Mai-language syntax
+            market: Stock market ("cn", "hk", "us"), default "cn"
+            start_date: Start date (YYYY-MM-DD), default 3 months ago
+            end_date: End date (YYYY-MM-DD), default today
 
         Returns:
             DataFrame with factor values
 
         Example:
-            >>> df = client.quant.factors(
-            ...     symbols=["US:AAPL", "US:MSFT"],
-            ...     factors=["momentum", "value"],
-            ...     frequency="monthly"
-            ... )
+            >>> # Simple indicator
+            >>> df = client.quant.compute_factors(["000001"], "RSI(14)")
+            
+            >>> # MACD DIF line
+            >>> df = client.quant.compute_factors(["000001"], "MACD().dif")
+            
+            >>> # Close above 20-day MA (boolean)
+            >>> df = client.quant.compute_factors(["000001"], "CLOSE > MA(20)")
+            
+            >>> # Deviation from MA20 in percent
+            >>> df = client.quant.compute_factors(["000001"], "(CLOSE - MA(20)) / MA(20) * 100")
+
+        Supported Operators:
+            - Comparison: >, <, >=, <=, ==, !=
+            - Logical AND: & (NOT "AND")
+            - Logical OR: | (NOT "OR")
+            - Arithmetic: +, -, *, /
+
+        Supported Variables:
+            - CLOSE, C: Close price
+            - OPEN, O: Open price
+            - HIGH, H: High price
+            - LOW, L: Low price
+            - VOLUME, V, VOL: Volume
         """
         data: dict[str, Any] = {
             "symbols": symbols,
-            "factors": factors,
-            "frequency": frequency,
+            "formula": formula,
+            "market": market,
         }
         if start_date:
             data["start_date"] = start_date
         if end_date:
             data["end_date"] = end_date
 
-        response = self._client._post("/v2/quant/factors", json=data)
-        return self._to_dataframe(response.get("data", []))
-
-    def factor_list(self) -> list[dict[str, Any]]:
-        """
-        Get list of available factors
-
-        Returns:
-            List of factor definitions
-
-        Example:
-            >>> factors = client.quant.factor_list()
-            >>> for f in factors:
-            ...     print(f"{f['name']}: {f['category']}")
-        """
-        response = self._client._get("/v2/quant/factors")
-        return response.get("factors", [])
+        response = self._client._post("/v1/quant/factors/compute", json=data)
+        return self._to_dataframe(response.get("datas", []))
 
-    def factor_exposure(
+    def screen(
         self,
-        symbols: list[str],
+        formula: str,
         *,
-        date: str | None = None,
+        market: StockMarket = "cn",
+        check_date: str | None = None,
+        symbols: list[str] | None = None,
     ) -> pd.DataFrame:
         """
-        Get factor exposure for given symbols
+        Screen stocks based on factor formula
+
+        Returns stocks where the formula evaluates to True (for boolean formulas)
+        or non-null (for numeric formulas).
 
         Args:
-            symbols: List of stock symbols
-            date: Specific date (YYYY-MM-DD), defaults to latest
+            formula: Screening formula using Mai-language syntax
+            market: Stock market ("cn", "hk", "us"), default "cn"
+            check_date: Check date (YYYY-MM-DD), default latest trading day
+            symbols: Stock codes to screen (None = full market)
 
         Returns:
-            DataFrame with factor exposures for each symbol
+            DataFrame with stocks that passed the filter
 
         Example:
-            >>> exposure = client.quant.factor_exposure(["US:AAPL", "US:GOOGL"])
-            >>> print(exposure[["symbol", "momentum", "value", "quality"]])
+            >>> # RSI oversold
+            >>> stocks = client.quant.screen(formula="RSI(14) < 30")
+            
+            >>> # Golden cross
+            >>> stocks = client.quant.screen(formula="CROSS(MA(5), MA(10))")
+            
+            >>> # Uptrend
+            >>> stocks = client.quant.screen(formula="(CLOSE > MA(20)) & (MA(20) > MA(60))")
+            
+            >>> # Above upper Bollinger Band
+            >>> stocks = client.quant.screen(formula="CLOSE > BOLL(20, 2).upper")
+            
+            >>> # Screen specific stocks
+            >>> stocks = client.quant.screen(
+            ...     formula="RSI(14) < 30",
+            ...     symbols=["000001", "600519", "000002"]
+            ... )
         """
-        data: dict[str, Any] = {"symbols": symbols}
-        if date:
-            data["date"] = date
+        data: dict[str, Any] = {
+            "formula": formula,
+            "market": market,
+        }
+        if check_date:
+            data["check_date"] = check_date
+        if symbols:
+            data["symbols"] = symbols
 
-        response = self._client._post("/v2/quant/factors/exposure", json=data)
-        return self._to_dataframe(response.get("data", []))
+        response = self._client._post("/v1/quant/factors/screen", json=data)
+        return self._to_dataframe(response.get("datas", []))
 
     # -------------------------------------------------------------------------
     # Quotes
     # -------------------------------------------------------------------------
 
-    def quotes(
+    def ohlcv(
         self,
-        symbols: list[str],
+        symbol: str,
         *,
-        fields: list[str] | None = None,
+        market: StockMarket = "cn",
+        start_date: str | None = None,
+        end_date: str | None = None,
     ) -> pd.DataFrame:
         """
-        Get real-time quotes for given symbols
+        Get OHLCV (Open, High, Low, Close, Volume) daily data for a single symbol
 
         Args:
-            symbols: List of stock symbols
-            fields: Specific fields to return (default: all)
+            symbol: Stock code
+            market: Stock market ("cn", "hk", "us"), default "cn"
+            start_date: Start date (YYYY-MM-DD), default 1 month ago
+            end_date: End date (YYYY-MM-DD), default today
 
         Returns:
-            DataFrame with quote data
+            DataFrame with OHLCV data
 
         Example:
-            >>> quotes = client.quant.quotes(["US:AAPL", "US:MSFT"])
-            >>> print(quotes[["symbol", "price", "change", "volume"]])
+            >>> df = client.quant.ohlcv("000001")
+            >>> print(df[["open", "high", "low", "close", "volume"]])
         """
-        data: dict[str, Any] = {"symbols": symbols}
-        if fields:
-            data["fields"] = fields
+        params: dict[str, Any] = {
+            "symbol": symbol,
+            "market": market,
+        }
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
 
-        response = self._client._post("/v2/quant/quotes", json=data)
-        return self._to_dataframe(response.get("data", []))
+        response = self._client._get("/v1/quant/quotes/ohlcv", params=params)
+        return self._to_dataframe(response.get("datas", []))
 
-    def quotes_history(
+    def ohlcv_batch(
         self,
         symbols: list[str],
         *,
+        market: StockMarket = "cn",
         start_date: str | None = None,
         end_date: str | None = None,
-        interval: str = "1d",
-        adjust: str = "forward",
-        limit: int = 100,
     ) -> pd.DataFrame:
         """
-        Get historical quotes data
+        Get OHLCV data for multiple symbols
 
         Args:
-            symbols: List of stock symbols
-            start_date: Start date (YYYY-MM-DD)
-            end_date: End date (YYYY-MM-DD)
-            interval: Data interval ("1d", "1w", "1m")
-            adjust: Adjustment type ("forward", "backward", "none")
-            limit: Maximum records per symbol
+            symbols: List of stock codes
+            market: Stock market ("cn", "hk", "us"), default "cn"
+            start_date: Start date (YYYY-MM-DD), default 1 month ago
+            end_date: End date (YYYY-MM-DD), default today
 
         Returns:
-            DataFrame with historical OHLCV data
+            DataFrame with OHLCV data sorted by date (descending), then by symbol
 
         Example:
-            >>> history = client.quant.quotes_history(
-            ...     ["US:AAPL"],
-            ...     start_date="2024-01-01",
-            ...     interval="1d"
-            ... )
+            >>> df = client.quant.ohlcv_batch(["000001", "600519"])
+            >>> print(df[["symbol", "date", "close", "volume"]])
         """
         data: dict[str, Any] = {
             "symbols": symbols,
-            "interval": interval,
-            "adjust": adjust,
-            "limit": limit,
+            "market": market,
         }
         if start_date:
             data["start_date"] = start_date
         if end_date:
             data["end_date"] = end_date
 
-        response = self._client._post("/v2/quant/quotes/history", json=data)
-        return self._to_dataframe(response.get("data", []))
+        response = self._client._post("/v1/quant/quotes/ohlcv/batch", json=data)
+        return self._to_dataframe(response.get("datas", []))
 
     # -------------------------------------------------------------------------
     # Backtest
@@ -259,99 +321,72 @@ class QuantModule:
 
     def backtest(
         self,
-        strategy: dict[str, Any],
-        *,
+        symbol: str,
+        formula: str,
         start_date: str,
         end_date: str,
-        initial_capital: float = 1000000.0,
-        benchmark: str | None = None,
+        *,
+        market: StockMarket = "cn",
+        initial_cash: float = 100000.0,
+        commission: float = 0.0,
+        stop_loss: float = 0.0,
+        sizer_percent: int = 99,
+        auto_close: bool = True,
     ) -> dict[str, Any]:
         """
-        Run a backtest for a given strategy
+        Execute strategy backtest
 
         Args:
-            strategy: Strategy definition dict
+            symbol: Stock code
+            formula: Trading strategy formula using Mai-language syntax
             start_date: Backtest start date (YYYY-MM-DD)
             end_date: Backtest end date (YYYY-MM-DD)
-            initial_capital: Starting capital (default: 1,000,000)
-            benchmark: Benchmark symbol for comparison (e.g., "US:SPY")
+            market: Stock market ("cn", "hk", "us"), default "cn"
+            initial_cash: Initial capital (default: 100000.0)
+            commission: Commission rate (default: 0.0)
+            stop_loss: Stop loss setting (default: 0.0, no stop loss)
+            sizer_percent: Position percentage (default: 99%)
+            auto_close: Auto close positions (default: True)
 
         Returns:
-            Backtest results including returns, metrics, and trades
+            Backtest results including:
+            - success: Whether backtest succeeded
+            - initial_cash: Initial capital
+            - final_cash: Final capital
+            - total_return: Total return
+            - total_return_pct: Total return percentage
+            - max_drawdown: Maximum drawdown
+            - profit_factor: Profit factor
+            - win_rate: Win rate
+            - total_trades: Total number of trades
+            - trades: List of trade details
 
         Example:
             >>> result = client.quant.backtest(
-            ...     strategy={
-            ...         "type": "momentum",
-            ...         "universe": ["US:AAPL", "US:MSFT", "US:GOOGL"],
-            ...         "rebalance": "monthly",
-            ...         "top_n": 2
-            ...     },
-            ...     start_date="2020-01-01",
+            ...     symbol="000001",
+            ...     formula="CROSS(MA(5), MA(20))",  # Golden cross buy signal
+            ...     start_date="2023-01-01",
             ...     end_date="2024-01-01",
-            ...     benchmark="US:SPY"
+            ...     initial_cash=100000
             ... )
-            >>> print(f"Total Return: {result['metrics']['total_return']:.2%}")
+            >>> print(f"Total Return: {result['total_return_pct']:.2%}")
+            >>> print(f"Max Drawdown: {result['max_drawdown']:.2%}")
+            >>> print(f"Win Rate: {result['win_rate']:.2%}")
         """
         data = {
-            "strategy": strategy,
+            "symbol": symbol,
+            "formula": formula,
             "start_date": start_date,
             "end_date": end_date,
-            "initial_capital": initial_capital,
+            "market": market,
+            "initial_cash": initial_cash,
+            "commission": commission,
+            "stop_loss": stop_loss,
+            "sizer_percent": sizer_percent,
+            "auto_close": auto_close,
         }
-        if benchmark:
-            data["benchmark"] = benchmark
-
-        return self._client._post("/v2/quant/backtest", json=data)
-
-    def backtest_result(self, backtest_id: str) -> dict[str, Any]:
-        """
-        Get backtest result by ID
 
-        Args:
-            backtest_id: Backtest job ID
-
-        Returns:
-            Backtest results
-
-        Example:
-            >>> result = client.quant.backtest_result("bt_abc123")
-        """
-        return self._client._get(f"/v2/quant/backtest/{backtest_id}")
-
-    def backtest_returns(self, backtest_id: str) -> pd.DataFrame:
-        """
-        Get backtest return series
-
-        Args:
-            backtest_id: Backtest job ID
-
-        Returns:
-            DataFrame with daily returns
-
-        Example:
-            >>> returns = client.quant.backtest_returns("bt_abc123")
-            >>> print(returns[["date", "portfolio_value", "daily_return"]])
-        """
-        response = self._client._get(f"/v2/quant/backtest/{backtest_id}/returns")
-        return self._to_dataframe(response.get("data", []))
-
-    def backtest_trades(self, backtest_id: str) -> pd.DataFrame:
-        """
-        Get backtest trade history
-
-        Args:
-            backtest_id: Backtest job ID
-
-        Returns:
-            DataFrame with all trades
-
-        Example:
-            >>> trades = client.quant.backtest_trades("bt_abc123")
-            >>> print(trades[["date", "symbol", "action", "quantity", "price"]])
-        """
-        response = self._client._get(f"/v2/quant/backtest/{backtest_id}/trades")
-        return self._to_dataframe(response.get("data", []))
+        return self._client._post("/v1/quant/backtest", json=data)
 
     # -------------------------------------------------------------------------
     # Helper Methods
@@ -363,9 +398,7 @@ class QuantModule:
             return pd.DataFrame()
         df = pd.DataFrame(data)
         # Convert date columns if present
-        for col in ["date", "timestamp", "trade_date"]:
+        for col in ["date", "check_date", "trade_date"]:
             if col in df.columns:
                 df[col] = pd.to_datetime(df[col])
-                df = df.set_index(col)
-                break
         return df

{reportify_sdk-0.2.0.dist-info → reportify_sdk-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reportify-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python SDK for Reportify API - Financial data and document search
 Author-email: Reportify <support@reportify.cn>
 License-Expression: MIT

{reportify_sdk-0.2.0.dist-info → reportify_sdk-0.2.1.dist-info}/RECORD

@@ -3,11 +3,11 @@ reportify_sdk/client.py,sha256=P56qBme48UPkZhMb9BlDnLMLXwHK-DjU7qDhGFFxMI0,11019
 reportify_sdk/docs.py,sha256=O30I1J4qTC8zpkVP_qu1cgT8nv6ysXNClqvaiRb0lhY,4957
 reportify_sdk/exceptions.py,sha256=r2_C_kTh6tCrQnfA3UozSqMMA-2OBnoP3pGpgYeqcdU,1049
 reportify_sdk/kb.py,sha256=-4UHWtudFncGRBB42B4YEoMPsEHr4QOtY55_8hKyogE,2240
-reportify_sdk/quant.py,sha256=xXh4mz4B_iUh4PRbc0KI5e2FVtO0Hawvw_TMP_5rji4,11658
+reportify_sdk/quant.py,sha256=pEXvG0OH20SH37NoPu1Flm-Dz0FMoqch9_pLMOnXk8w,13777
 reportify_sdk/stock.py,sha256=NcEhV9JfIQm2BsfYM1k-JVcxHhnnil32dp-bedGG4BU,13513
 reportify_sdk/timeline.py,sha256=b5Zj5SjXT4gP0dvEl8gXCWDZJHemyU7NSYahet2nHhc,4075
-reportify_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=zBUq4DL4lE-fZU_PMkr0gnxkYS1LhdRHFw8_LmCb-ek,1066
-reportify_sdk-0.2.0.dist-info/METADATA,sha256=kmE-VtAC7lDLy6E4X8mWMVcq8gBpv-ukuFKple3J0F8,4311
-reportify_sdk-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-reportify_sdk-0.2.0.dist-info/top_level.txt,sha256=tc_dzCSWIDsNbHSi-FlyEEX8xwinhN9gl-CwyLRE4B0,14
-reportify_sdk-0.2.0.dist-info/RECORD,,
+reportify_sdk-0.2.1.dist-info/licenses/LICENSE,sha256=zBUq4DL4lE-fZU_PMkr0gnxkYS1LhdRHFw8_LmCb-ek,1066
+reportify_sdk-0.2.1.dist-info/METADATA,sha256=hEtOPPrQiLNFFiN_504fHs6Yb4H91fvPdeTE4uTq76E,4311
+reportify_sdk-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+reportify_sdk-0.2.1.dist-info/top_level.txt,sha256=tc_dzCSWIDsNbHSi-FlyEEX8xwinhN9gl-CwyLRE4B0,14
+reportify_sdk-0.2.1.dist-info/RECORD,,