Better distribution api

Author: lsbardel

.github/workflows/release.yml

@@ -16,6 +16,16 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     env:
       PYTHON_ENV: ci
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Makefile

@@ -13,7 +13,7 @@ app-serve:			## serve app
 docs:				## build documentation
 	@cp docs/index.md readme.md
 	@uv run ./dev/build-examples
-	@uv run mkdocs build
+	@uv run mkdocs build --strict
 
 .PHONY: docs-bib
 docs-bib:			## Regenerate docs bibliography

app/api/deps.py

@@ -1,20 +1,21 @@
 import io
 import json
+import logging
+import os
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Annotated, Generic, TypeVar, cast
 
 import pandas as pd
 from fastapi import Depends, FastAPI, Request
-from fluid.utils import log
 from fluid.utils.redis import FluidRedis
 from pydantic import BaseModel
 from redis.asyncio import Redis
 
 from quantflow.data.fmp import FMP
 
 M = TypeVar("M", bound=BaseModel)
-logger = log.get_logger(__name__)
+logger = logging.getLogger(__name__)
 
 
 def instrument_app(app: FastAPI) -> None:
@@ -44,7 +45,17 @@ class RedisCache(Generic[M]):
     redis: Redis
     Model: type[M]
     key: str
-    ttl: int = 60
+    prefix: str = field(
+        default_factory=lambda: os.getenv(
+            "QUANTFLOW_REDIS_CACHE_PREFIX", "quantflow:cache"
+        )
+    )
+    ttl: int = field(
+        default_factory=lambda: int(os.getenv("QUANTFLOW_REDIS_CACHE_TTL", "60"))
+    )
+
+    def __post_init__(self) -> None:
+        self.key = f"{self.prefix}:{self.key}"
 
     async def from_cache(self, loader: Callable[[], Awaitable[M]]) -> M:
         """Get a value from the cache"""
@@ -53,7 +64,7 @@ async def from_cache(self, loader: Callable[[], Awaitable[M]]) -> M:
             return await self.set_cache(await loader())
         try:
             return self.Model.model_validate_json(value)
-        except json.JSONDecodeError:
+        except json.JSONDecodeError:    # pragma: no cover
             logger.exception(f"Failed to decode cache value for key {self.key}")
             return await self.set_cache(await loader())
 
@@ -63,6 +74,15 @@ async def set_cache(self, value: M) -> M:
         await self.redis.set(self.key, payload, ex=self.ttl)
         return value
 
+    @classmethod
+    async def clear(cls, redis: Redis) -> int:
+        """Delete all cache entries under the prefix"""
+        cache = cls(redis=redis, Model=BaseModel, key="*")
+        keys = [key async for key in cache.redis.scan_iter(f"{cache.prefix}:*")]
+        if not keys:
+            return 0
+        return await cache.redis.delete(*keys)
+
 
 @dataclass
 class RedisDataframe:

app/api/heston.py

@@ -3,10 +3,10 @@
 from pydantic import BaseModel, Field
 
 from app.api.docs import load_description
+from quantflow.dists.distributions1d import DoubleExponential
 from quantflow.options.pricer import OptionPricer
 from quantflow.sp.heston import HestonJ
 from quantflow.sp.jump_diffusion import JumpDiffusion
-from quantflow.utils.distributions import DoubleExponential
 
 heston_router = APIRouter()
 

app/api/sampling.py

@@ -4,11 +4,11 @@
 from scipy.stats import chisquare, ks_1samp
 
 from app.api.docs import load_description
+from quantflow.dists.distributions1d import DoubleExponential
 from quantflow.sp.ou import Vasicek
 from quantflow.sp.poisson import PoissonProcess
 from quantflow.ta.paths import Paths
 from quantflow.utils import bins
-from quantflow.utils.distributions import DoubleExponential
 
 sampling_router = APIRouter()
 

app/scripts/heston_divfm_fit.py

@@ -20,7 +20,7 @@
 from quantflow.options.divfm.trainer import DayData, DIVFMTrainer
 from quantflow.options.pricer import OptionPricer
 from quantflow.sp.heston import HestonJ
-from quantflow.utils.distributions import DoubleExponential
+from quantflow.dists.distributions1d import DoubleExponential
 
 # ---------------------------------------------------------------------------
 # Grid settings

docs/api/dists/distributions.md

@@ -0,0 +1,9 @@
+# Distributions
+
+::: quantflow.dists.Distribution
+
+::: quantflow.dists.MvDistribution
+
+::: quantflow.dists.MeanAndCov
+
+::: quantflow.dists.MvNormal

docs/api/dists/distributions1d.md

@@ -0,0 +1,9 @@
+# 1D Distributions
+
+::: quantflow.dists.Distribution1D
+
+::: quantflow.dists.Normal
+
+::: quantflow.dists.Exponential
+
+::: quantflow.dists.DoubleExponential

docs/api/dists/index.md

@@ -1,12 +1,9 @@
 # Distributions
 
-Probability distributions with a uniform `sample` / `log_pdf` API, used as
-return types of the
-[StateSpaceModel](../ta/kalman.md#quantflow.ta.kalman.StateSpaceModel)
-distribution-level interface.
+The `dists` module collects the probability distributions used across quantflow,
+both standalone parametric laws and the marginal distributions implied by a
+stochastic process at a fixed time horizon.
 
-::: quantflow.dists.MeanAndCov
-
-::: quantflow.dists.Distribution
-
-::: quantflow.dists.MvNormal
+Every distribution derives from
+[Distribution][quantflow.dists.Distribution], which exposes a common
+[sample][quantflow.dists.Distribution.sample] method for drawing random variates.

docs/api/dists/marginal1d.md

@@ -0,0 +1,9 @@
+# Marginal 1D
+
+::: quantflow.dists.OptionPricingMethod
+
+::: quantflow.dists.OptionPricingResult
+
+::: quantflow.dists.OptionPricingCosResult
+
+::: quantflow.dists.Marginal1D