quantflow 0.7.0__tar.gz → 0.9.0__tar.gz

{quantflow-0.7.0 → quantflow-0.9.0}/.github/copilot-instructions.md

@@ -27,11 +27,20 @@ applyTo: '/**'
 
 * The documentation for quantflow is available at `https://quantflow.quantmid.com`
 * Documentation is built using [mkdocs](https://www.mkdocs.org/) and stored in the `docs/` directory. The documentation source files are written in markdown format.
-* Do not use em dashes (—) in documentation files or docstrings. Use colons, parentheses, or restructure the sentence instead.
+* Split prose into short paragraphs (one idea per paragraph) separated by blank lines. Never write a wall-of-text paragraph that strings together mechanism, rationale, caveats and usage advice. This applies to mkdocs tutorials, theory pages and long docstrings.
+* Do not use dashes (em dashes, en dashes, or hyphens used as dashes) in documentation files or docstrings. Use colons, parentheses, or restructure the sentence instead.
 * Math in documentation and docstrings: always use `\begin{equation}...\end{equation}` for any formula or equation. Use `$...$` only for brief inline references to variables (e.g. $F$, $K$). Do not use `$$...$$`, `` `...` ``, or RST syntax (`.. math::`, `:math:`).
+* Math notation convention: use $\Phi$ for the characteristic function and $\phi$ for the characteristic exponent, where $\Phi = e^{-\phi}$.
 * Glossary entries in `docs/glossary.md` must be kept in alphabetical order.
+* Do not repeat concept definitions inline in tutorials or docstrings — link to the glossary instead using a relative markdown link (e.g. `[moneyness](../glossary.md#moneyness)`).
 * To rebuild doc examples run `uv run ./dev/build-examples` — runs all scripts in `docs/examples/` and writes their output to `docs/examples_output/`
 
+## Pydantic models
+
+* Always document Pydantic fields with `Field(description=...)` — never use a docstring below a field assignment
+* Split long description strings across lines using implicit string concatenation rather than shortening the text
+* When a docstring line exceeds the line length limit, split it across multiple lines rather than shortening the text
+
 ## Package structure
 
 * Strategy runtime markdown descriptions (read by `load_description()` at runtime) live inside the package at `quantflow/options/strategies/docs/` — they must be inside the package to be accessible when the library is installed

quantflow-0.9.0/.github/instructions/makefile.instructions.md

@@ -0,0 +1,5 @@
+# Makefile Conventions
+
+- Keep all targets sorted alphabetically.
+- targets should be separated by a one blank line only.
+- Each target should have a one-line description, starting with `##`, that describes what the target does. This description is used by the `help` target to generate documentation for all targets.

quantflow-0.9.0/.github/instructions/release.instructions.md

@@ -0,0 +1,48 @@
+# Release Instructions
+
+Releases are driven by `v*` git tags. Pushing a tag triggers
+`.github/workflows/release.yml`, which runs lint and the test suite, publishes
+the package to PyPI (`make publish`), then extracts the matching `## vX.Y.Z`
+section from `docs/release-notes.md` and publishes it as the GitHub Release
+body.
+
+## Cutting a release
+
+1. Bump `version` in `pyproject.toml` to the new release version.
+2. Add a `## vX.Y.Z` section at the top of `docs/release-notes.md` with the
+   notes for the release. The header text is matched verbatim by the
+   workflow's `awk` extractor, so it must be `## vX.Y.Z` exactly (no trailing
+   dash, no title after the version). The release workflow fails if this
+   section is missing.
+3. Commit and merge to `main`; let the `build` workflow pass.
+4. From `main`, run `make release` — it reads the version from
+   `pyproject.toml`, asks for confirmation, then creates an annotated `vX.Y.Z`
+   tag and pushes it. The `release` workflow takes it from there.
+
+Do not publish to PyPI manually, and do not revive the old
+`head_commit.message == 'release'` flow — the tag-triggered workflow is the
+only supported path.
+
+## Release-notes conventions
+
+The `## vX.Y.Z` section in `docs/release-notes.md` is rendered both on the
+docs site and as the GitHub Release body, so it must follow these conventions:
+
+- Open with a one-paragraph summary describing the theme of the release. If
+  the release contains breaking changes, point readers to the **Breaking
+  changes** section in that paragraph.
+- Group entries under H3 subsections in this order: `### Breaking changes`,
+  `### New features`, `### Improvements and fixes`,
+  `### Documentation and assets`. Omit any subsection that has no entries.
+- Every PR reference must be a markdown link of the form
+  `[#NN](https://github.com/quantmind/quantflow/pull/NN)` — never a bare
+  `(#NN)`. GitHub's auto-linking only works in some contexts, and the explicit
+  URL works everywhere. When one entry references multiple PRs, list them
+  comma-separated inside one set of parentheses, each as its own link.
+- Build the PR list by running `git log vPREV..HEAD --oneline` against the
+  previous release tag and following each squashed-merge commit back to its
+  PR. Cross-check with `gh pr list --state merged --base main` for any PRs
+  merged since the previous tag.
+- End the section with a
+  `[Full changelog](https://github.com/quantmind/quantflow/compare/vPREV...vX.Y.Z)`
+  link comparing the new tag against the previous one.

quantflow-0.9.0/.github/instructions/tutorial.instructions.md

@@ -0,0 +1,96 @@
+---
+name: quantflow-tutorial-instructions
+description: 'Instructions for tutorial in quantflow'
+applyTo: '/docs/tutorials/**,/docs/examples/**'
+---
+
+
+
+# Tutorial Instructions
+
+## File locations
+
+- Tutorial pages: `docs/tutorials/<name>.md`
+- Example scripts: `docs/examples/<name>.py`
+- Generated images: `docs/assets/examples/<name>.png`
+- Script stdout captured to: `docs/examples/output/<name>.out`
+- Every new tutorial must be added to the `nav` section of `mkdocs.yml` under `Tutorials`.
+- Update `docs/tutorials/index.md` with a row in the summary table.
+
+## Building
+
+- Build a single example: `uv run python docs/examples/<name>.py`
+- Build all examples and capture output: `make docs-examples`
+- Preview the docs locally: `uv run mkdocs serve`
+
+## Tutorial page structure
+
+Each tutorial markdown file should follow this order:
+
+1. **H1 title** — the subject, not "Tutorial on X".
+2. **One-paragraph introduction** — what the tutorial demonstrates and why it is useful.
+   Link to the relevant API classes using `[ClassName][fully.qualified.path]`.
+3. **Sections** (H2) — cover the concept first, then show usage, then show results.
+   Use H3 subsections for variants (different parameter regimes, maturities, etc.).
+4. **Code section** — always the last H2. Embed the full example script with:
+   ````
+   ```python
+   --8<-- "docs/examples/<name>.py"
+   ```
+   ````
+   If the script prints structured output, embed it too:
+   ````
+   ```
+   --8<-- "docs/examples/output/<name>.out"
+   ```
+   ````
+
+## Example scripts
+
+- Each script must be self-contained and runnable with `uv run python docs/examples/<name>.py`.
+- Place shared helpers in `docs/examples/_utils.py` — do not duplicate utility code.
+- Use `assets_path(filename)` from `_utils.py` to get the correct path when saving images.
+- Use `plotly` for all charts. Save to PNG with `fig.write_image(assets_path(...), width=900, height=500)`.
+  Use `width=1600, height=800` for side-by-side subplot layouts.
+- When overlaying an analytical curve with a numerical result (e.g. PDF from characteristic
+  function), plot the analytical result as a solid line and the numerical result as circle
+  markers (`mode="markers", marker=dict(symbol="circle")`). This makes the discretization
+  points visible and the two series easy to distinguish.
+- Do not `print` raw numbers — emit only what belongs in the captured `.out` file.
+- Scripts must produce no warnings when run cleanly (fix the root cause, e.g. avoid `x=0`
+  in domains where the PDF is singular).
+- The `build_examples` helper in `_utils.py` runs every non-underscore script and captures
+  stdout; keep scripts idempotent and deterministic.
+
+## Charts
+
+- Embed images with a clickable link that opens full-size in a new tab:
+  ```markdown
+  [![Alt text](../assets/examples/<name>.png)](../assets/examples/<name>.png){target="_blank"}
+  ```
+- Write a one-sentence caption above each image explaining what the reader should observe.
+
+## Math
+
+Follow the math conventions in `copilot-instructions.md`:
+
+- Use `\begin{equation}...\end{equation}` for standalone formulas.
+- Use `\begin{equation}\begin{aligned}...\end{aligned}\end{equation}` for multi-line systems.
+- Use `$...$` only for brief inline variable references.
+- Use `\Phi` for the characteristic function and `\phi` for the characteristic exponent.
+
+## Cross-references
+
+- Link API symbols with `[ClassName][fully.qualified.module.ClassName]`.
+- Link to theory pages with relative markdown links: `[Option Pricing](../theory/option_pricing.md)`.
+- Link to the glossary for concept definitions rather than re-defining them inline.
+- Link to the bibliography for external references: `[Carr-Madan](../bibliography.md#carr_madan)`.
+
+## What not to include
+
+- Do not explain implementation details that belong in docstrings.
+- Do not reproduce equations already in the API reference — link to them instead.
+- Do not add a summary or "next steps" section unless the tutorial is part of a series.
+- Do not use math notation (`$...$`, `\begin{equation}`, etc.) in any heading (H1–H4).
+  Math does not render in the table of contents — write headings in plain English instead
+  (e.g. "Short horizon" not "Short horizon ($t = 0.5$)").

{quantflow-0.7.0 → quantflow-0.9.0}/.github/workflows/build.yml

@@ -23,6 +23,8 @@ jobs:
       - uses: actions/checkout@v4
       - name: install rops
         uses: quantmind/rops/.github/actions/setup-rops@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.TOKEN_DEPLOYMENT }}
       - name: install taplo
         run: rops tools update taplo
       - name: Set up Python ${{ matrix.python-version }}
@@ -47,9 +49,6 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./build/coverage.xml
-      - name: publish
-        if: ${{ matrix.python-version == '3.14' && github.event.head_commit.message == 'release' }}
-        run: make publish
 
   image:
     if: github.ref == 'refs/heads/main'

{quantflow-0.7.0 → quantflow-0.9.0}/.github/workflows/docker-multiarch.yml

@@ -23,6 +23,8 @@ jobs:
           password: ${{ github.token }}
       - name: install rops
         uses: quantmind/rops/.github/actions/setup-rops@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.TOKEN_DEPLOYMENT }}
       - name: build amd64
         run: rops docker build ${{ inputs.image-name }}
       - name: push amd64
@@ -44,6 +46,8 @@ jobs:
           password: ${{ github.token }}
       - name: install rops
         uses: quantmind/rops/.github/actions/setup-rops@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.TOKEN_DEPLOYMENT }}
       - name: build arm64
         run: rops docker build ${{ inputs.image-name }}
       - name: push arm64
@@ -64,5 +68,7 @@ jobs:
           password: ${{ github.token }}
       - name: install rops
         uses: quantmind/rops/.github/actions/setup-rops@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.TOKEN_DEPLOYMENT }}
       - name: create manifest
         run: rops docker manifest ${{ inputs.image-name }}

quantflow-0.9.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: release
+
+# Triggered by `v*` tags. Builds and publishes the package to PyPI, then
+# extracts the matching section from docs/release-notes.md and publishes it
+# as the GitHub Release body. Re-runs idempotently update an existing
+# release rather than failing.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      PYTHON_ENV: ci
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      FMP_API_KEY: ${{ secrets.FMP_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install rops
+        uses: quantmind/rops/.github/actions/setup-rops@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.TOKEN_DEPLOYMENT }}
+
+      - name: install taplo
+        run: rops tools update taplo
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        run: pip install -U pip uv
+
+      - name: Install dependencies
+        run: make install-dev
+
+      - name: run lint
+        run: make lint-check
+
+      - name: run tests
+        run: make tests
+
+      - name: publish to PyPI
+        run: make publish
+
+      - name: Extract release notes
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          awk -v tag="## ${TAG}" '
+            $0 == tag { in_section = 1; next }
+            /^## / && in_section { exit }
+            in_section { print }
+          ' docs/release-notes.md > /tmp/notes.md
+          if [ ! -s /tmp/notes.md ]; then
+            echo "No section '## ${TAG}' found in docs/release-notes.md" >&2
+            exit 1
+          fi
+          echo "--- extracted notes for ${TAG} ---"
+          cat /tmp/notes.md
+
+      - name: Publish GitHub Release
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release edit "$TAG" --notes-file /tmp/notes.md
+          else
+            gh release create "$TAG" --title "$TAG" --notes-file /tmp/notes.md
+          fi

{quantflow-0.7.0 → quantflow-0.9.0}/.gitignore

@@ -26,6 +26,7 @@ build
 dist
 .venv
 .mypy_cache
+.hypothesis
 .pytest_cache
 .ruff_cache
 .python-version
@@ -37,4 +38,5 @@ _build
 
 # builds
 app/docs
-docs/examples_output
+docs/assets/examples
+docs/examples/output

quantflow-0.9.0/CLAUDE.md

@@ -0,0 +1,5 @@
+@readme.md
+@.github/copilot-instructions.md
+@.github/instructions/makefile.instructions.md
+@.github/instructions/release.instructions.md
+@.github/instructions/tutorial.instructions.md

{quantflow-0.7.0 → quantflow-0.9.0}/Makefile

@@ -5,53 +5,64 @@ help:
 	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
 	@echo ================================================================================
 
+.PHONY: docs
+docs:				## build documentation
+	@cp docs/index.md readme.md
+	@uv run ./dev/build-examples
+	@uv run mkdocs build
+
+.PHONY: docs-bib
+docs-bib:			## Regenerate docs bibliography
+	@uv run ./docs/bib2md.py
+
+.PHONY: docs-examples
+docs-examples:			## Regenerate docs examples
+	@uv run ./dev/build-examples
+
+.PHONY: docs-serve
+docs-serve:			## serve documentation
+	@uv run mkdocs serve --livereload --watch quantflow --watch docs
+
+.PHONY: install-dev
+install-dev:			## Install development dependencies
+	@./dev/install
 
 .PHONY: lint
 lint:				## Lint and fix
 	@uv run ./dev/lint fix
 
-
 .PHONY: lint-check
 lint-check:			## Lint check only
 	@uv run ./dev/lint
 
-
-.PHONY: install-dev
-install-dev:			## Install development dependencies
-	@./dev/install
-
 .PHONY: marimo
 marimo:				## Run marimo for editing notebooks
 	@./dev/marimo edit
 
-.PHONY: docs-png
-docs-png:			## Regenerate PNG assets in docs/assets/ (requires Chrome via kaleido)
-	@for f in docs/examples_png/*.py; do uv run python $$f; done
-
-.PHONY: docs
-docs:				## build documentation
-	@cp docs/index.md readme.md
-	@uv run ./dev/build-examples
-	@uv run mkdocs build
-
-.PHONY: docs-serve
-docs-serve:			## serve documentation
-	@uv run mkdocs serve --livereload --watch quantflow --watch docs
+.PHONY: outdated
+outdated:			## Show outdated packages
+	uv tree --outdated
 
 .PHONY: publish
 publish:			## Release to pypi
 	@uv build
 	@uv publish --token $(PYPI_TOKEN)
 
+.PHONY: release
+release:			## Tag current version (from pyproject.toml) and push
+	$(eval VERSION := $(shell grep '^version' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/'))
+	@read -p "Tagging with v$(VERSION), are you sure? [Y/n] " ans; \
+	ans=$${ans:-Y}; \
+	if [ "$$ans" = "Y" ] || [ "$$ans" = "y" ]; then \
+		git tag -a v$(VERSION) -m "v$(VERSION)" && git push origin v$(VERSION); \
+	else \
+		echo "Aborted."; \
+	fi
+
 .PHONY: tests
 tests:				## Unit tests
 	@./dev/test
 
-
-.PHONY: outdated
-outdated:			## Show outdated packages
-	uv tree --outdated
-
 .PHONY: upgrade
 upgrade:			## Upgrade dependencies
 	uv lock --upgrade

{quantflow-0.7.0 → quantflow-0.9.0}/PKG-INFO

@@ -1,13 +1,28 @@
 Metadata-Version: 2.4
 Name: quantflow
-Version: 0.7.0
+Version: 0.9.0
 Summary: quantitative analysis
 Project-URL: Homepage, https://github.com/quantmind/quantflow
 Project-URL: Repository, https://github.com/quantmind/quantflow
-Project-URL: Documentation, https://quantmind.github.io/quantflow/
+Project-URL: Documentation, https://quantflow.quantmind.com
+Project-URL: Issues, https://github.com/quantmind/quantflow/issues
 Author-email: Luca Sbardella <luca@quantmind.com>
 License-Expression: BSD-3-Clause
 License-File: LICENSE
+Keywords: finance,options,pricing,quantitative,stochastic,volatility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.11
 Requires-Dist: ccy>=2.0.0
 Requires-Dist: polars[pandas,pyarrow]>=1.11.0
@@ -54,7 +69,7 @@ Provides-Extra: ml
 Requires-Dist: torch>=2.10.0; extra == 'ml'
 Description-Content-Type: text/markdown
 
-# <a href="https://quantmind.github.io/quantflow"><img src="https://raw.githubusercontent.com/quantmind/quantflow/main/docs/assets/quantflow-light.svg" width=300 /></a>
+# <a href="https://quantmind.github.io/quantflow"><img src="https://raw.githubusercontent.com/quantmind/quantflow/main/docs/assets/logos/quantflow-lockup.svg" width=300 /></a>
 
 [![PyPI version](https://badge.fury.io/py/quantflow.svg)](https://badge.fury.io/py/quantflow)
 [![Python versions](https://img.shields.io/pypi/pyversions/quantflow.svg)](https://pypi.org/project/quantflow)
@@ -85,67 +100,21 @@ pip install quantflow
 
 * `data` — data retrieval: `pip install quantflow[data]`
 * `ai` — MCP server for AI clients: `pip install quantflow[ai,data]`
+* `ml` — training the Deep Implied Volatility model: `pip install quantflow[ml]`
 
 ## MCP Server
 
-Quantflow exposes its data tools as an [MCP](https://modelcontextprotocol.io) server, allowing AI clients such as Claude to query market data, crypto volatility surfaces, and economic indicators directly.
+Quantflow exposes its data tools as an [MCP](https://modelcontextprotocol.io) server for AI clients.
+See [MCP Server](https://quantflow.quantmind.com/mcp/) for setup and available tools.
 
-Install with the `ai` and `data` extras:
+## License
 
-```bash
-pip install quantflow[ai,data]
-```
-
-### API keys
-
-Store your API keys in `~/.quantflow/.vault`:
-
-```
-fmp=your-fmp-key
-fred=your-fred-key
-```
+Released under the [BSD 3-Clause License](https://github.com/quantmind/quantflow/blob/main/LICENSE).
 
-Or let the AI manage them for you via the `vault_add` tool once connected.
+## Citation
 
-### Claude Code
+If you use Quantflow in your research, please cite it using the metadata in [CITATION.cff](https://github.com/quantmind/quantflow/blob/main/CITATION.cff).
 
-```bash
-claude mcp add quantflow -- uv run qf-mcp
-```
-
-### Claude Desktop
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-
-```json
-{
-  "mcpServers": {
-    "quantflow": {
-      "command": "uv",
-      "args": ["run", "qf-mcp"]
-    }
-  }
-}
-```
+## License
 
-### Available tools
-
-| Tool | Description |
-|---|---|
-| `vault_keys` | List stored API keys |
-| `vault_add` | Add or update an API key |
-| `vault_delete` | Delete an API key |
-| `stock_indices` | List stock market indices |
-| `stock_search` | Search companies by name or symbol |
-| `stock_profile` | Get company profile |
-| `stock_prices` | Get OHLC price history |
-| `sector_performance` | Sector performance and PE ratios |
-| `crypto_instruments` | List Deribit instruments |
-| `crypto_historical_volatility` | Historical volatility from Deribit |
-| `crypto_term_structure` | Volatility term structure |
-| `crypto_implied_volatility` | Implied volatility surface |
-| `crypto_prices` | Crypto OHLC price history |
-| `ascii_chart` | ASCII chart for any stock or crypto symbol |
-| `fred_subcategories` | Browse FRED categories |
-| `fred_series` | List series in a FRED category |
-| `fred_data` | Fetch FRED observations |
+Released under the [BSD 3-Clause License](https://github.com/quantmind/quantflow/blob/main/LICENSE).

{quantflow-0.7.0 → quantflow-0.9.0}/app/__main__.py

@@ -2,17 +2,19 @@ import os
 from pathlib import Path
 
 import marimo
-from fastapi import FastAPI, APIRouter
+from fastapi import APIRouter, FastAPI
 from fastapi.staticfiles import StaticFiles
 
-APP_PATH = Path(__file__).parent
+from app.utils.paths import APP_PATH, head_snippet
+
 PORT = int(os.environ.get("MICRO_SERVICE_PORT", "8001"))
 status_router = APIRouter()
 
 
 def crate_app() -> FastAPI:
     # Create a marimo asgi app
-    server = marimo.create_asgi_app(include_code=True)
+    html_head = head_snippet(APP_PATH / "docs")
+    server = marimo.create_asgi_app(include_code=True, html_head=html_head)
     for path in APP_PATH.glob("*.py"):
         if path.name.startswith("_"):
             continue
@@ -25,6 +27,7 @@ def crate_app() -> FastAPI:
     app.mount("/", StaticFiles(directory=APP_PATH / "docs", html=True), name="static")
     return app
 
+
 @status_router.get("/status")
 async def service_status() -> dict:
     return {"status": "ok"}