quantflow 0.4.3__tar.gz → 0.4.4__tar.gz

{quantflow-0.4.3 → quantflow-0.4.4}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2023-2025 Quantmind
+Copyright (c) 2023-2026 Quantmind
 
 Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:

{quantflow-0.4.3 → quantflow-0.4.4}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: quantflow
-Version: 0.4.3
+Version: 0.4.4
 Summary: quantitative analysis
 License-Expression: BSD-3-Clause
 License-File: LICENSE
 Author: Luca Sbardella
 Author-email: luca@quantmind.com
-Requires-Python: >=3.11,<4.0
+Requires-Python: >=3.11,<3.15
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -26,6 +26,7 @@ Requires-Dist: pydantic (>=2.0.2)
 Requires-Dist: python-dotenv (>=1.0.1)
 Requires-Dist: rich (>=13.9.4) ; extra == "cli"
 Requires-Dist: scipy (>=1.14.1)
+Requires-Dist: statsmodels (>=0.14.6,<0.15.0)
 Project-URL: Documentation, https://quantmind.github.io/quantflow/
 Project-URL: Homepage, https://github.com/quantmind/quantflow
 Project-URL: Repository, https://github.com/quantmind/quantflow
@@ -41,7 +42,7 @@ Description-Content-Type: text/markdown
 
 Quantitative analysis and pricing tools.
 
-Documentation is available as [quantflow jupyter book](https://quantflow.quantmind.com).
+![btcvol](https://github.com/quantmind/quantflow/assets/144320/88ed85d1-c3c5-489c-ac07-21b036593214)
 
 ## Installation
 
@@ -49,9 +50,6 @@ Documentation is available as [quantflow jupyter book](https://quantflow.quantmi
 pip install quantflow
 ```
 
-![btcvol](https://github.com/quantmind/quantflow/assets/144320/88ed85d1-c3c5-489c-ac07-21b036593214)
-
-
 ## Modules
 
 * [quantflow.cli](https://github.com/quantmind/quantflow/tree/main/quantflow/cli) command line client (requires `quantflow[cli,data]`)

{quantflow-0.4.3 → quantflow-0.4.4}/pyproject.toml

@@ -1,17 +1,18 @@
 [project]
 name = "quantflow"
-version = "0.4.3"
+version = "0.4.4"
 description = "quantitative analysis"
-authors = [{ name = "Luca Sbardella", email = "luca@quantmind.com" }]
+authors = [ { name = "Luca Sbardella", email = "luca@quantmind.com" } ]
 license = "BSD-3-Clause"
 readme = "readme.md"
-requires-python = ">=3.11,<4.0"
+requires-python = ">=3.11,<3.15"
 dependencies = [
     "scipy>=1.14.1",
     "pydantic>=2.0.2",
     "ccy>=1.7.1",
     "python-dotenv>=1.0.1",
     "polars[pandas,pyarrow]>=1.11.0",
+    "statsmodels (>=0.14.6,<0.15.0)",
 ]
 
 [project.urls]
@@ -20,7 +21,7 @@ Repository = "https://github.com/quantmind/quantflow"
 Documentation = "https://quantmind.github.io/quantflow/"
 
 [project.optional-dependencies]
-data = ["aio-fluid[http]>=1.2.1"]
+data = [ "aio-fluid[http]>=1.2.1" ]
 cli = [
     "asciichartpy>=1.5.25",
     "async-cache>=1.1.1",
@@ -33,49 +34,73 @@ cli = [
 [project.scripts]
 qf = "quantflow.cli.script:main"
 
-
 [tool.poetry.group.dev.dependencies]
-black = "^25.1.0"
-pytest-cov = "^6.0.0"
-mypy = "^1.14.1"
+black = "^26.1.0"
 ghp-import = "^2.0.2"
-ruff = "^0.12.2"
+isort = "^8.0.0"
+mypy = "^1.14.1"
 pytest-asyncio = "^1.0.0"
-isort = "^6.0.1"
+pytest-cov = "^7.0.0"
+ruff = "^0.15.4"
 types-python-dateutil = "^2.9.0.20251115"
 
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+mkdocs-material = "^9.7.0"
+mkdocs-macros-plugin = "^1.3.7"
+mkdocs-redirects = "^1.2.1"
+mkdocstrings = { version = "1.0.0", extras = [ "python" ] }
+griffe-pydantic = "^1.1.0"
+griffe-typingdoc = "^0.2.7"
+
 [tool.poetry.group.book]
 optional = true
 
+[tool.poetry.group.ml]
+optional = true
+
 [tool.poetry.group.book.dependencies]
-jupyter-book = "^1.0.0"
-jupytext = "^1.13.8"
+altair = "^6.0.0"
+autodocsumm = "^0.2.14"
+duckdb = "^1.4.4"
+fastapi = "^0.129.0"
+google-genai = "^1.61.0"
+marimo = "^0.19.7"
+mcp = "^1.26.0"
+openai = "^2.16.0"
 plotly = "^6.2.0"
-jupyterlab = "^4.0.2"
+pydantic-ai-slim = "^1.51.0"
 sympy = "^1.12"
-ipywidgets = "^8.0.7"
-sphinx-autodoc-typehints = "2.3.0"
-sphinx-autosummary-accessors = "^2023.4.0"
-sphinx-copybutton = "^0.5.2"
-autodocsumm = "^0.2.14"
 
+[tool.poetry.group.ml.dependencies]
+torch = { version = "^2.10.0", source = "pytorch" }
+
+[[tool.poetry.source]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cu126"
+priority = "explicit"
 
 [build-system]
-requires = ["poetry-core>=1.0.0"]
+requires = [ "poetry-core>=1.0.0" ]
 build-backend = "poetry.core.masonry.api"
 
-[tool.jupytext]
-formats = "ipynb,myst"
+[tool.jupytext.formats]
+"notebooks/" = "ipynb,py:percent"
+
+[tool.marimo.display]
+theme = "dark"
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-testpaths = ["quantflow_tests"]
+testpaths = [ "quantflow_tests" ]
 
 [tool.isort]
 profile = "black"
 
 [tool.ruff]
-lint.select = ["E", "F"]
+lint.select = [ "E", "F" ]
 line-length = 88
 
 [tool.hatch.version]

{quantflow-0.4.3 → quantflow-0.4.4}/quantflow/__init__.py

@@ -1,3 +1,3 @@
 """Quantitative analysis and pricing"""
 
-__version__ = "0.4.3"
+__version__ = "0.4.4"

{quantflow-0.4.3 → quantflow-0.4.4}/quantflow/cli/commands/stocks.py

@@ -94,7 +94,7 @@ async def get_indices(ctx: QuantContext) -> list[dict]:
 
 async def get_prices(ctx: QuantContext, symbol: str, frequency: str) -> pd.DataFrame:
     async with ctx.fmp() as cli:
-        return await cli.prices(symbol, frequency)
+        return await cli.prices(symbol, frequency=frequency)
 
 
 async def get_profile(ctx: QuantContext, symbol: str) -> list[dict]:

{quantflow-0.4.3 → quantflow-0.4.4}/quantflow/data/deribit.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import enum
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -8,6 +10,7 @@ import pandas as pd
 from dateutil.parser import parse
 from fluid.utils.data import compact_dict
 from fluid.utils.http_client import AioHttpClient, HttpResponse, HttpResponseError
+from typing_extensions import Annotated, Doc
 
 from quantflow.options.inputs import OptionType
 from quantflow.options.surface import VolSecurityType, VolSurfaceLoader
@@ -37,16 +40,20 @@ class InstrumentKind(enum.StrEnum):
 class Deribit(AioHttpClient):
     """Deribit API client
 
-    Fetch market and static data from `Deribit`_ API.
+    ## Example
+
+    ```python
+    from quantflow.data.deribit import Deribit
 
-    .. _Deribit: https://docs.deribit.com/
+    deribit = Deribit()
+    ```
     """
 
     url: str = "https://www.deribit.com/api/v2"
 
     async def get_book_summary_by_instrument(
         self,
-        instrument_name: str,
+        instrument_name: Annotated[str, Doc("Instrument name")],
         **kw: Any,
     ) -> list[dict]:
         """Get the book summary for a given instrument."""
@@ -57,7 +64,10 @@ class Deribit(AioHttpClient):
         )
 
     async def get_book_summary_by_currency(
-        self, currency: str, kind: InstrumentKind | None = None, **kw: Any
+        self,
+        currency: Annotated[str, Doc("Currency")],
+        kind: Annotated[InstrumentKind | None, Doc("Optional instrument kind")] = None,
+        **kw: Any,
     ) -> list[dict]:
         """Get the book summary for a given currency."""
         kw.update(
@@ -69,9 +79,9 @@ class Deribit(AioHttpClient):
 
     async def get_instruments(
         self,
-        currency: str,
-        kind: InstrumentKind | None = None,
-        expired: bool | None = None,
+        currency: Annotated[str, Doc("Currency")],
+        kind: Annotated[InstrumentKind | None, Doc("Optional instrument kind")] = None,
+        expired: Annotated[bool | None, Doc("Include expired instruments")] = None,
         **kw: Any,
     ) -> list[dict]:
         """Get the list of instruments for a given currency."""
@@ -81,17 +91,26 @@ class Deribit(AioHttpClient):
         )
         return cast(list[dict], await self.get_path("public/get_instruments", **kw))
 
-    async def get_volatility(self, currency: str, **kw: Any) -> pd.DataFrame:
+    async def get_volatility(
+        self,
+        currency: Annotated[str, Doc("Currency")],
+        **kw: Any,
+    ) -> pd.DataFrame:
         """Provides information about historical volatility for given cryptocurrency"""
         kw.update(params=dict(currency=currency), callback=self.to_df)
         return await self.get_path("public/get_historical_volatility", **kw)
 
     async def volatility_surface_loader(
         self,
-        currency: str,
+        currency: Annotated[str, Doc("Currency")],
         *,
-        exclude_open_interest: Number | None = None,
-        exclude_volume: Number | None = None,
+        exclude_open_interest: Annotated[
+            Number | None,
+            Doc("Exclude options with open interest below this threshold"),
+        ] = None,
+        exclude_volume: Annotated[
+            Number | None, Doc("Exclude options with volume below this threshold")
+        ] = None,
     ) -> VolSurfaceLoader:
         """Create a :class:`.VolSurfaceLoader` for a given crypto-currency"""
         loader = VolSurfaceLoader(
@@ -170,16 +189,26 @@ class Deribit(AioHttpClient):
 
     # Internal methods
 
-    async def get_path(self, path: str, **kw: Any) -> dict:
+    async def get_path(
+        self,
+        path: Annotated[str, Doc("API path")],
+        **kw: Any,
+    ) -> dict:
         return await self.get(f"{self.url}/{path}", **kw)
 
-    async def to_result(self, response: HttpResponse) -> list[dict]:
+    async def to_result(
+        self,
+        response: Annotated[HttpResponse, Doc("HTTP response object")],
+    ) -> list[dict]:
         data = await response.json()
         if "error" in data:
             raise HttpResponseError(response, data["error"])
         return cast(list[dict], data["result"])
 
-    async def to_df(self, response: HttpResponse) -> pd.DataFrame:
+    async def to_df(
+        self,
+        response: Annotated[HttpResponse, Doc("HTTP response object")],
+    ) -> pd.DataFrame:
         data = await self.to_result(response)
         df = pd.DataFrame(data, columns=["timestamp", "volatility"])
         df["timestamp"] = pd.to_datetime(df["timestamp"], unit="ms")

{quantflow-0.4.3 → quantflow-0.4.4}/quantflow/data/fmp.py

@@ -1,6 +1,6 @@
 import os
 from dataclasses import dataclass, field
-from datetime import date, timedelta
+from datetime import date
 from decimal import Decimal
 from enum import StrEnum
 from typing import Any, Iterator, cast
@@ -9,19 +9,15 @@ import inflection
 import pandas as pd
 from fluid.utils.data import compact_dict
 from fluid.utils.http_client import AioHttpClient
+from typing_extensions import Annotated, Doc
 
-from quantflow.utils.dates import isoformat
+from quantflow.utils.dates import to_date_iso
 from quantflow.utils.numbers import to_decimal
 
 
 @dataclass
 class FMP(AioHttpClient):
-    """Financial Modeling Prep API client
-
-    Fetch market and financial data from `Financial Modeling Prep`_.
-
-    .. _Financial Modeling Prep: https://site.financialmodelingprep.com/developer/docs/stable
-    """
+    """Financial Modeling Prep API client"""
 
     url: str = "https://financialmodelingprep.com/stable"
     key: str = field(default_factory=lambda: os.environ.get("FMP_API_KEY", ""))
@@ -52,11 +48,19 @@ class FMP(AioHttpClient):
         across global exchanges"""
         return await self.get_path("index-list", **kw)
 
-    async def profile(self, *tickers: str, **kw: Any) -> list[dict]:
+    async def profile(
+        self,
+        *tickers: Annotated[str, Doc("One or more ticker symbols")],
+        **kw: Any,
+    ) -> list[dict]:
         """Company profile - minute"""
         return await self.get_path(f"profile/{self.join(*tickers)}", **kw)
 
-    async def quote(self, *tickers: str, **kw: Any) -> list[dict]:
+    async def quote(
+        self,
+        *tickers: Annotated[str, Doc("One or more ticker symbols")],
+        **kw: Any,
+    ) -> list[dict]:
         """Company quote - real time"""
         return await self.get_path(f"quote/{self.join(*tickers)}", **kw)
 
@@ -64,25 +68,35 @@ class FMP(AioHttpClient):
 
     async def dividends(
         self,
-        from_date: str | date = "",
-        to_date: str | date = "",
+        from_date: Annotated[
+            str | date | None, Doc("Start date for dividend calendar")
+        ] = None,
+        to_date: Annotated[
+            str | date | None, Doc("End date for dividend calendar")
+        ] = None,
         **kw: Any,
     ) -> list[dict]:
         """Dividend calendar"""
-        if not from_date:
-            from_date = date.today()
-        if not to_date:
-            to_date = date.today() + timedelta(days=7)
-        params = {"from": isoformat(from_date), "to": isoformat(to_date)}
+        params = compact_dict(
+            {"from": to_date_iso(from_date), "to": to_date_iso(to_date)},
+        )
         return await self.get_path("dividends-calendar", params=params, **kw)
 
     # Executives
 
-    async def executives(self, ticker: str, **kw: Any) -> list[dict]:
+    async def executives(
+        self,
+        ticker: Annotated[str, Doc("Ticker symbol")],
+        **kw: Any,
+    ) -> list[dict]:
         """Company quote - real time"""
         return await self.get_path(f"key-executives/{ticker}", **kw)
 
-    async def insider_trading(self, ticker: str, **kw: Any) -> list[dict]:
+    async def insider_trading(
+        self,
+        ticker: Annotated[str, Doc("Ticker symbol")],
+        **kw: Any,
+    ) -> list[dict]:
         """Company Insider Trading"""
         return await self.get_path(
             "insider-trading", **self.params(dict(symbol=ticker), **kw)
@@ -90,18 +104,28 @@ class FMP(AioHttpClient):
 
     # Rating
 
-    async def rating(self, ticker: str, **kw: Any) -> list[dict]:
+    async def rating(
+        self,
+        ticker: Annotated[str, Doc("Ticker symbol")],
+        **kw: Any,
+    ) -> list[dict]:
         """Company rating - real time"""
         return await self.get_path(f"rating/{ticker}", **kw)
 
-    async def etf_holders(self, ticker: str, **kw: Any) -> list[dict]:
+    async def etf_holders(
+        self,
+        ticker: Annotated[str, Doc("Ticker symbol")],
+        **kw: Any,
+    ) -> list[dict]:
         return await self.get_path(f"etf-holder/{ticker}", **kw)
 
     async def ratios(
         self,
-        ticker: str,
-        period: str | None = None,
-        limit: int | None = None,
+        ticker: Annotated[str, Doc("Ticker symbol")],
+        period: Annotated[
+            str | None, Doc("Reporting period (e.g., 'annual', 'quarter')")
+        ] = None,
+        limit: Annotated[int | None, Doc("Maximum number of results")] = None,
         **kw: Any,
     ) -> list[dict]:
         """Company financial ratios - if period not provided it is for
@@ -112,13 +136,21 @@ class FMP(AioHttpClient):
             **self.params(compact_dict(period=period, limit=limit), **kw),
         )
 
-    async def peers(self, *tickers: str, **kw: Any) -> list[dict]:
+    async def peers(
+        self,
+        *tickers: Annotated[str, Doc("One or more ticker symbols")],
+        **kw: Any,
+    ) -> list[dict]:
         """Stock peers based on sector, exchange and market cap"""
         kwargs = self.params(**kw)
         kwargs["params"]["symbol"] = self.join(*tickers)
         return await self.get_path("stock_peers", **kwargs)
 
-    async def news(self, *tickers: str, **kw: Any) -> list[dict]:
+    async def news(
+        self,
+        *tickers: Annotated[str, Doc("One or more ticker symbols")],
+        **kw: Any,
+    ) -> list[dict]:
         """Company quote - real time"""
         kwargs = self.params(**kw)
         if tickers:
@@ -127,11 +159,11 @@ class FMP(AioHttpClient):
 
     async def search(
         self,
-        query: str,
+        query: Annotated[str, Doc("Search query string")],
         *,
-        exchange: str | None = None,
-        limit: int | None = None,
-        symbol: bool = False,
+        exchange: Annotated[str | None, Doc("Filter by exchange")] = None,
+        limit: Annotated[int | None, Doc("Maximum number of results")] = None,
+        symbol: Annotated[bool, Doc("Search by symbol instead of name")] = False,
         **kw: Any,
     ) -> list[dict]:
         path = "search-symbol" if symbol else "search-name"
@@ -144,10 +176,20 @@ class FMP(AioHttpClient):
 
     async def prices(
         self,
-        symbol: str,
-        frequency: str = "",
-        to_date: bool = False,
-        **kw: Any,
+        symbol: Annotated[str, Doc("Ticker symbol")],
+        *,
+        frequency: Annotated[
+            str | None, Doc("Price frequency (e.g., '1min', '5min', 'daily')")
+        ] = None,
+        from_date: Annotated[
+            str | date | None, Doc("From date for historical prices")
+        ] = None,
+        to_date: Annotated[
+            str | date | None, Doc("To date for historical prices")
+        ] = None,
+        convert_to_date: Annotated[
+            bool, Doc("Convert date column to datetime type")
+        ] = False,
     ) -> pd.DataFrame:
         """Historical prices, daily if frequency is not provided"""
         path = (
@@ -155,12 +197,18 @@ class FMP(AioHttpClient):
             if not frequency
             else f"historical-chart/{frequency}"
         )
-        kw.update(params=dict(symbol=symbol))
-        data = await self.get_path(path, **kw)
+        data = await self.get_path(
+            path,
+            params=compact_dict(
+                {"from": to_date_iso(from_date), "to": to_date_iso(to_date)},
+                frequency=frequency,
+                symbol=symbol,
+            ),
+        )
         if isinstance(data, dict):
             data = data.get("historical", [])
         df = pd.DataFrame(data)
-        if to_date and "date" in df.columns:
+        if convert_to_date and "date" in df.columns:
             df["date"] = pd.to_datetime(df["date"])
         return df
 
@@ -168,10 +216,16 @@ class FMP(AioHttpClient):
     async def sector_performance(
         self,
         *,
-        from_date: date | None = None,
-        to_date: date | None = None,
-        summary: bool = False,
-        params: dict | None = None,
+        from_date: Annotated[
+            date | None, Doc("Start date for historical sector performance")
+        ] = None,
+        to_date: Annotated[
+            date | None, Doc("End date for historical sector performance")
+        ] = None,
+        summary: Annotated[
+            bool, Doc("Return summary instead of daily performance")
+        ] = False,
+        params: Annotated[dict | None, Doc("Additional query parameters")] = None,
         **kw: Any,
     ) -> dict | list[dict]:
         if not from_date:
@@ -213,17 +267,28 @@ class FMP(AioHttpClient):
         return await self.get_path("symbol/available-cryptocurrencies")
 
     # Internals
-    async def get_path(self, path: str, **kw: Any) -> list[dict]:
+    async def get_path(
+        self,
+        path: Annotated[str, Doc("API endpoint path")],
+        **kw: Any,
+    ) -> list[dict]:
         result = await self.get(f"{self.url}/{path}", **self.params(**kw))
         return cast(list[dict], result)
 
-    def join(self, *tickers: str) -> str:
+    def join(
+        self,
+        *tickers: Annotated[str, Doc("One or more ticker symbols")],
+    ) -> str:
         value = ",".join(tickers)
         if not value:
             raise TypeError("at least one ticker must be provided")
         return value
 
-    def params(self, params: dict | None = None, **kw: Any) -> dict:
+    def params(
+        self,
+        params: Annotated[dict | None, Doc("Query parameters dictionary")] = None,
+        **kw: Any,
+    ) -> dict:
         params = params.copy() if params is not None else {}
         params["apikey"] = self.key
         return {"params": params, **kw}