riskkit-quant 0.4.0__tar.gz

riskkit_quant-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Something behaves differently than documented
+title: "[bug] "
+labels: bug
+---
+
+**What happened**
+A clear description of the bug.
+
+**Minimal repro**
+```python
+# the smallest snippet that shows it
+```
+
+**Expected vs actual**
+What you expected, and what happened instead.
+
+**Environment**
+- riskkit version:
+- Python version:

riskkit_quant-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest a new rule, component, or integration
+title: "[feature] "
+labels: enhancement
+---
+
+**The risk problem this solves**
+What gap or failure mode are you trying to guard against?
+
+**Proposed API**
+Roughly how would it look to call this?
+
+**Alternatives**
+Anything you've tried or considered.
+
+**Scope check**
+Does this stay framework-agnostic and anti-martingale? (See CONTRIBUTING.md.)

riskkit_quant-0.4.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## What this changes
+
+Briefly, what and why.
+
+## Checklist
+
+- [ ] Tests added/updated and `pytest` passes locally
+- [ ] Public API has docstrings
+- [ ] `CHANGELOG.md` updated
+- [ ] Stays framework-agnostic and anti-martingale (see CONTRIBUTING.md)

riskkit_quant-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -v

riskkit_quant-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+# Publishes when you push a version tag like v0.2.0.
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored in the repo.
+# One-time setup: on pypi.org add a "pending publisher" for project `riskkit`,
+# owner `HasibDaddy`, repo `riskkit`, workflow `release.yml`, environment `pypi`.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

riskkit_quant-0.4.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+
+# Docs build output (mkdocs)
+site/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

riskkit_quant-0.4.0/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-06-23
+
+### Added
+- Three more **stops** in the `StopEngine` stack: **chandelier** (trails ATR from
+  the highest high / lowest low since entry — `StopStack(use_chandelier=True)`,
+  `StopEngine(chandelier_atr_multiplier=...)`), **structure** (ratchets to a swing
+  level you pass as `update(..., structure_level=...)`), and **PSAR** (ratchets to a
+  Parabolic SAR value you pass as `update(..., psar_value=...)`). All tighten-only;
+  `update()` gained optional `current_high` / `current_low` for the chandelier extreme.
+- Standalone, composable **sizers** (pure functions): `kelly_fraction()` (edge-optimal
+  risk fraction, `fraction=0.5` for half-Kelly), `volatility_target_size()` (size a
+  position to a target volatility, notional-capped), and `inverse_vol_weights()` (naive
+  risk-parity weights ∝ 1/σ). `PositionSizer` now delegates its half-Kelly ceiling to
+  `kelly_fraction` (single source of truth).
+- Portfolio-level **heat** cap — `RiskConfig(max_portfolio_heat_pct=...)` limits the
+  total capital at risk across open positions (Σ units × distance-to-stop), checked
+  by the validator and surfaced via `RiskManager.portfolio_heat_pct()`. Off by
+  default; the presets set it (conservative 4% / balanced 8% / aggressive 15%).
+- Per-sector / asset-class **exposure** cap — `RiskConfig(max_exposure_per_sector_pct=...)`
+  keeps any one sector from dominating the book. Tag trades with `TradeIntent(sector=...)`;
+  the manager tracks open notional per sector (`RiskManager.sector_exposure_pct(sector)`
+  and `.sector_exposure()`) and the validator blocks an entry that would push its sector
+  over the cap. Untagged trades are never capped. Off by default; the presets set it
+  (conservative 4% / balanced 10% / aggressive 25%).
+- Property-based tests (hypothesis) for the core invariants: a position never
+  exceeds its notional/risk caps, size never increases after losses or deeper
+  drawdown (anti-martingale), the per-sector exposure cap is never breached across
+  random fill sequences, and the standalone sizers stay within bounds (vol-target
+  ≤ notional cap and falls as vol rises; inverse-vol weights sum to 1; Kelly within
+  `[0, fraction]` and rising with edge).
+- `value_at_risk` / `conditional_value_at_risk` — historical VaR and expected
+  shortfall over a return series (positive loss magnitudes; CVaR ≥ VaR by
+  construction).
+
+## [0.3.0] - 2026-06-22
+
+### Added
+- `RiskManager` façade — wires all six components from a single `RiskConfig` and
+  turns one `TradeIntent` into a sized, validated `RiskDecision` in a single
+  `evaluate()` call. Tracks drawdown, session, and open-book state for you via
+  `on_equity()` / `on_fill()` / `on_close()`. See `examples/risk_manager.py`.
+- backtesting.py adapter — `riskkit.adapters.backtesting.RiskkitStrategy`, a
+  `Strategy` mixin whose `risk_long()` / `risk_short()` size and validate every
+  entry through a `RiskManager` and feed closed trades back to the session. New
+  `backtesting` optional extra; see `examples/backtesting_riskmanager.py`.
+- `RiskConfig` presets (`conservative` / `balanced` / `aggressive`, plus
+  `RiskConfig.preset(name)`) and loaders — `RiskConfig.from_dict()`,
+  `RiskConfig.to_dict()`, and `RiskConfig.from_yaml()` (new `yaml` extra).
+- freqtrade adapter — `riskkit.adapters.freqtrade.FreqtradeRiskManager`, which
+  drives `custom_stake_amount` / `confirm_trade_entry` from a `RiskManager`
+  (framework-agnostic: it imports nothing from freqtrade).
+- vectorbt adapter — `riskkit.adapters.vectorbt.size_signals`, which sizes an
+  array of entry signals with riskkit for `Portfolio.from_signals`.
+- Runnable integration examples for backtesting.py and freqtrade.
+- mkdocs documentation site (Home / Quickstart / Components / Integrations).
+- PyPI trusted-publishing release workflow and `PUBLISHING.md` guide.
+
+### Fixed
+- `PositionSizer` now reports `risk_pct` consistent with `risk_amount` when the
+  notional cap binds (previously `risk_pct` kept the pre-cap target while
+  `risk_amount` reflected the smaller, capped position).
+
+## [0.2.0] - 2026-06-19
+
+### Added
+- `StopEngine` / `StopStack` — composable per-position stop stack (initial,
+  break-even, ATR-trailing, EMA-trailing, time, and volatility stops); tightest
+  stop wins and stops only ever move closer.
+- `CorrelationGuard` — one open position per correlation group, from static
+  groups and/or a dynamically computed return-correlation matrix (pandas extra).
+- `SessionManager` — daily trade/loss caps, profit-taking stops, minimum
+  spacing, escalating cooldowns, and tilt detection.
+- `PreTradeValidator` — composable final-gate checklist across market quality,
+  sizing, risk limits, signal quality, and timing; returns a result per check.
+- `examples/pipeline.py` end-to-end demo, contribution guide, and issue/PR
+  templates.
+
+### Changed
+- Generalized the API to be framework-agnostic (e.g. `symbol`/`score` instead of
+  exchange-specific names; correlation groups and regime maps are now injected
+  rather than hardcoded).
+
+## [0.1.0] - 2026-06-19
+
+Initial release.
+
+### Added
+- `PositionSizer` — volatility-adjusted fixed-fractional position sizing with a
+  half-Kelly ceiling, a reduction ladder (losing streaks, drawdown tiers, daily
+  loss), a high-conviction bonus, and a hard notional cap. Every adjustment is
+  returned for auditing.
+- `DrawdownManager` — high-water-mark drawdown tracking with a 5-tier ladder, a
+  one-step-at-a-time recovery ramp, and a rolling weekly-loss pause.
+- Full type hints (`py.typed`) and a test suite covering both modules.

riskkit_quant-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to riskkit
+
+Thanks for your interest. riskkit aims to be the dependable, framework-agnostic
+risk layer for systematic trading — correctness and clarity matter more than
+features.
+
+## Dev setup
+
+```bash
+git clone https://github.com/HasibDaddy/riskkit
+cd riskkit
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Principles (please keep these)
+
+- **No framework lock-in.** The core must not depend on any exchange SDK, data
+  provider, or backtesting framework. Heavy optional deps (like pandas) go
+  behind an extra and are imported lazily.
+- **Every decision is auditable.** New rules should return *why* they fired, not
+  just a boolean.
+- **Conservative defaults.** Floors, ceilings, and caps bound every knob.
+- **Anti-martingale only.** Nothing in this library may increase risk after a
+  loss.
+
+## Pull requests
+
+1. Add or update tests — every behaviour change needs a test.
+2. Keep the public API documented (docstrings render in the README examples).
+3. Run `pytest` locally; CI runs the suite on Python 3.9–3.12.
+4. Update `CHANGELOG.md` under an `## [Unreleased]` heading.
+
+## Good first contributions
+
+- Integration examples/adapters for a specific framework (backtesting.py,
+  vectorbt, freqtrade).
+- A worked notebook walking through one component on real OHLCV data.
+- Edge-case tests for the existing modules.
+
+Open an issue to discuss anything larger before you build it.

riskkit_quant-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hasib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

riskkit_quant-0.4.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: riskkit-quant
+Version: 0.4.0
+Summary: A framework-agnostic risk-management toolkit for systematic traders: position sizing, drawdown laddering, and more.
+Project-URL: Homepage, https://github.com/HasibDaddy/riskkit
+Project-URL: Repository, https://github.com/HasibDaddy/riskkit
+Project-URL: Issues, https://github.com/HasibDaddy/riskkit/issues
+Author: Hasib
+License: MIT
+License-File: LICENSE
+Keywords: algotrading,backtesting,drawdown,kelly-criterion,position-sizing,quant,risk-management,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: backtesting
+Requires-Dist: backtesting>=0.3; extra == 'backtesting'
+Provides-Extra: dev
+Requires-Dist: backtesting>=0.3; extra == 'dev'
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: pandas>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: pyyaml>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.0; extra == 'pandas'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=5.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# riskkit
+
+[![CI](https://github.com/HasibDaddy/riskkit/actions/workflows/ci.yml/badge.svg)](https://github.com/HasibDaddy/riskkit/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-1f6feb)](https://hasibdaddy.github.io/riskkit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue.svg)
+![Dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)
+
+**A framework-agnostic risk-management toolkit for systematic traders.**
+
+Most open-source trading tools focus on the fun part — signals, indicators,
+backtesting engines. They leave the part that actually decides whether you
+survive thin or absent: *how big a position to take, when to cut size, and when
+to stop trading altogether.* That's what blows up retail algo traders, not a
+bad entry signal.
+
+`riskkit` is that missing layer. The components are pure Python with **no
+dependency on any exchange, data provider, or backtesting framework**. They
+don't know what CCXT is. You feed them numbers; they hand back decisions you can
+audit. Drop them into [backtesting.py](https://github.com/kernc/backtesting.py),
+[vectorbt](https://github.com/polakowo/vectorbt), [backtrader](https://github.com/mementum/backtrader),
+[freqtrade](https://github.com/freqtrade/freqtrade), or your own loop.
+
+> ⚠️ **Not financial advice.** `riskkit` helps you *implement* a risk policy you
+> have chosen. It does not choose one for you, and it cannot make a losing
+> strategy profitable. Test everything on paper first.
+
+---
+
+## Install
+
+```bash
+pip install "git+https://github.com/HasibDaddy/riskkit.git"
+```
+
+Zero runtime dependencies. Python 3.9+. *(A PyPI release is on the way — until
+then, install straight from GitHub with the line above.)*
+
+---
+
+## What's in the box
+
+| Component | What it does |
+|---|---|
+| `PositionSizer` | Volatility-adjusted fixed-fractional sizing with an optional half-Kelly ceiling, a reduction ladder for losing streaks / drawdowns, and a hard notional cap. |
+| `DrawdownManager` | Tracks high-water-mark drawdown, maps it onto a tier ladder (cut size → raise the bar → halt), with a recovery ramp and a rolling weekly-loss pause. |
+| `StopEngine` | A composable stop *stack* per position — initial, break-even, ATR/EMA trailing, chandelier, structure (swing), PSAR, time, and volatility stops. The tightest one wins; stops only ever move closer. |
+| `CorrelationGuard` | At most one open position per correlation group. Groups can be static (you define them) or computed dynamically from a rolling return-correlation matrix. |
+| `SessionManager` | Daily trade/loss caps, profit-taking stops, minimum spacing, escalating cooldowns after losing streaks, and tilt detection. |
+| `PreTradeValidator` | The composable final gate: runs every rule against a proposed trade and vetoes it if any fails — returning exactly which checks passed and failed. |
+
+Every decision is **auditable** — the sizer returns which multipliers fired,
+the stop engine logs each adjustment, and the validator returns a pass/fail line
+for every single check.
+
+Beyond the six components, riskkit ships a few **portfolio-level controls** and
+**standalone sizers** you can reach for on their own:
+
+- **Portfolio caps** (enforced by `RiskManager` as the book fills): total open
+  notional, total **heat** (risk-at-stop), and **per-sector / asset-class**
+  exposure — so no single sector can dominate the book.
+- **Composable sizers** (pure functions): `volatility_target_size`,
+  `inverse_vol_weights` (naive risk parity), and `kelly_fraction`.
+- **Risk metrics**: historical `value_at_risk` and `conditional_value_at_risk`.
+
+---
+
+## Quick start
+
+### The whole stack, one call
+
+`RiskManager` is the façade: wire all six components from a single config, push
+equity in as your account moves, and ask one question per trade. It keeps the
+drawdown, session, and open-position state in sync for you.
+
+```python
+from riskkit import RiskManager, RiskConfig, TradeIntent
+
+risk = RiskManager(RiskConfig(
+    base_risk_pct=1.0, max_notional_pct=4.0,
+    drawdown=dict(tier1_pct=3, halt_pct=10),
+    session=dict(max_trades_per_day=5),
+    correlation=dict(static_groups={"majors": {"BTC/USDT", "ETH/USDT"}}),
+))
+
+risk.on_equity(10_000)                              # refresh drawdown/session state
+decision = risk.evaluate(TradeIntent(
+    symbol="BTC/USDT", side="long",
+    entry_price=100.0, stop_price=98.0, target_price=104.0,
+    score=82, atr=2.0, atr_baseline=2.0,
+))
+
+if decision.ok:
+    place(decision.units, decision.stop)           # your execution layer
+    risk.on_fill(decision)                          # tell riskkit it filled
+else:
+    print("skip:", *decision.reasons, sep="\n  ")   # every gate that vetoed it
+```
+
+Reach past the façade to any single component when you need to — they're all
+exposed (`risk.sizer`, `risk.drawdown`, `risk.stops`, …) and usable standalone.
+
+Don't want to tune every knob? Start from a preset, or load policy from YAML:
+
+```python
+risk = RiskManager(RiskConfig.conservative())   # or .balanced() / .aggressive()
+cfg  = RiskConfig.from_yaml("risk.yaml")         # needs riskkit[yaml]
+```
+
+### Sizing a trade
+
+```python
+from riskkit import PositionSizer, SizingInputs
+
+sizer = PositionSizer(
+    base_risk_pct=1.0,      # risk 1% of equity per trade, before adjustments
+    max_risk_pct=1.5,       # never risk more than 1.5%
+    max_notional_pct=4.0,   # never let a position exceed 4% of equity
+)
+
+result = sizer.size(SizingInputs(
+    equity=10_000,
+    entry_price=100.0,
+    stop_price=98.0,        # the stop distance defines your risk per unit
+    atr=2.5,                # current volatility
+    atr_baseline=2.0,       # "normal" volatility -> scales risk down when choppy
+    consecutive_losses=2,   # reduction ladder kicks in
+    drawdown_pct=4.0,
+))
+
+if result.units > 0:
+    print(f"Buy {result.units:.4f} units (risk {result.risk_pct:.2%})")
+    print("adjustments:", result.multipliers_applied)
+else:
+    print("Skip:", result.reason_for_zero)
+```
+
+### Adapting to drawdown
+
+```python
+from riskkit import DrawdownManager
+
+dm = DrawdownManager(tier1_pct=3, tier2_pct=5, tier3_pct=7, halt_pct=10)
+
+state = dm.update(current_equity)   # call once per equity refresh
+if state.halted:
+    print("No new trades:", state.reason)
+else:
+    size = base_size * state.size_multiplier   # scale every position by the tier
+```
+
+The two compose naturally: feed `DrawdownManager`'s `drawdown_pct` and
+`size_multiplier` straight into the sizer.
+
+---
+
+## Design principles
+
+- **Framework-agnostic.** No exchange SDK, no pandas requirement in the core,
+  no global state. Just dataclasses in, dataclasses out.
+- **Auditable, not magic.** Every adjustment is named and returned. You can log
+  the exact reason a trade was sized down or skipped.
+- **Conservative by default.** Floors, ceilings, and hard caps bound every knob.
+  The math can recommend; it can never exceed the limits you set.
+- **Anti-martingale.** Size goes *down* after losses and during drawdowns, never
+  up. There is no "average down" path anywhere in this library.
+
+---
+
+## Integrations
+
+riskkit slots into whatever you already use — the [examples](examples/) are
+runnable:
+
+- **backtesting.py** — subclass the `RiskkitStrategy` adapter
+  (`from riskkit.adapters.backtesting import RiskkitStrategy`) and call
+  `risk_long()` / `risk_short()`; every entry is sized **and** validated by one
+  `RiskConfig`, with closed trades fed back to the session manager. See
+  [`examples/backtesting_riskmanager.py`](examples/backtesting_riskmanager.py)
+  (full façade) or [`examples/backtesting_py_strategy.py`](examples/backtesting_py_strategy.py)
+  (just `PositionSizer`, by hand).
+- **freqtrade** — `FreqtradeRiskManager`
+  (`from riskkit.adapters.freqtrade import FreqtradeRiskManager`) drives
+  `custom_stake_amount` + `confirm_trade_entry` from one `RiskConfig`; see
+  [`examples/freqtrade_callbacks.py`](examples/freqtrade_callbacks.py).
+- **vectorbt** — `size_signals`
+  (`from riskkit.adapters.vectorbt import size_signals`) turns entry signals into
+  a riskkit-sized array for `Portfolio.from_signals`; see
+  [`examples/vectorbt_sizing.py`](examples/vectorbt_sizing.py).
+- **your own loop** — [`examples/risk_manager.py`](examples/risk_manager.py)
+  drives the full `RiskManager` façade end-to-end;
+  [`examples/multi_asset_book.py`](examples/multi_asset_book.py) allocates,
+  vol-targets, and vets a cross-sector book through the portfolio caps;
+  [`examples/pipeline.py`](examples/pipeline.py) shows the same flow wired by hand.
+
+📖 **Full docs: https://hasibdaddy.github.io/riskkit/**
+
+## Roadmap
+
+`riskkit` is extracted and generalized from a working risk-first trading bot.
+The core six components are in place; next up is making them effortless to drop
+into the popular frameworks:
+
+- [x] `PositionSizer`, `DrawdownManager`, `StopEngine`
+- [x] `CorrelationGuard`, `SessionManager`, `PreTradeValidator`
+- [x] A single `RiskManager` façade that wires all six together with one config
+- [x] Config presets (conservative / balanced / aggressive) + dict/YAML loading
+- [x] First-class adapters for backtesting.py, freqtrade, and vectorbt
+- [x] A [hosted docs site](https://hasibdaddy.github.io/riskkit/) with component recipes
+- [x] Portfolio caps (total-exposure, heat, per-sector) + standalone sizers (vol-target, risk-parity, Kelly) + VaR/CVaR
+- [ ] A PyPI release (`pip install riskkit-quant`, then `import riskkit`)
+
+Feedback on the API is genuinely welcome — open an issue. See the full
+[ROADMAP.md](ROADMAP.md), [CONTRIBUTING.md](CONTRIBUTING.md), and the
+[examples](examples/).
+
+---
+
+## License
+
+MIT © 2026 Hasib. See [LICENSE](LICENSE).

riskkit_quant-0.4.0/PUBLISHING.md

@@ -0,0 +1,62 @@
+# Publishing riskkit to PyPI
+
+**Status (2026-06-23):** v0.4.0 is **build-verified and ready to publish** —
+`python -m build` succeeds, `twine check` passes, and a clean-venv install of the
+wheel imports and runs the full v0.4 surface (core is zero-dependency). The only
+steps left are the PyPI-account ones below.
+
+**Distribution name:** `riskkit-quant`. The ideal `riskkit` is unregistered (API
+404) but PyPI's pending-publisher form rejects it as **too similar to the existing
+`risk-kit`**, and `riskkit-trading` was also rejected. The accepted name is
+`riskkit-quant` (free, distinct). The *import* name is unchanged:
+`pip install riskkit-quant` then `import riskkit` — exactly like `scikit-learn` →
+`import sklearn`. Never re-upload a version once published.
+
+Two ways to publish — the automated one (recommended) and the manual one.
+
+## Recommended: Trusted Publishing (no tokens)
+
+This uses the included `.github/workflows/release.yml`. You configure PyPI once
+to trust your GitHub repo, then publishing is just pushing a tag.
+
+1. Create a PyPI account at https://pypi.org and verify your email.
+2. Go to **Your projects → Publishing → Add a pending publisher** and enter:
+   - PyPI project name: `riskkit-quant`
+   - Owner: `HasibDaddy`
+   - Repository name: `riskkit`
+   - Workflow name: `release.yml`
+   - Environment name: `pypi`
+3. In your GitHub repo, create an environment named `pypi`
+   (Settings → Environments → New environment).
+4. Tag and push a release:
+   ```bash
+   git tag v0.4.0
+   git push origin v0.4.0
+   ```
+   The workflow builds the package and publishes it. Done.
+
+## Manual (one machine, with a token)
+
+```bash
+python -m pip install --upgrade build twine
+python -m build                 # creates dist/*.whl and dist/*.tar.gz
+python -m twine check dist/*
+python -m twine upload dist/*    # paste a PyPI API token when prompted
+```
+
+## Before the first publish — checklist
+
+- [x] GitHub handle (`HasibDaddy`) filled in across `pyproject.toml`,
+      `mkdocs.yml`, `docs/`, and the workflow.
+- [x] `version` matches in `pyproject.toml` and `src/riskkit/__init__.py` (`0.4.0`).
+- [x] `pytest` green (118 tests) and CI passes on GitHub across Python 3.9–3.12.
+- [x] `python -m build` succeeds and `twine check dist/*` passes; the wheel installs
+      and imports cleanly in a fresh venv with zero dependencies.
+
+## After publishing
+
+- Verify the install: `pip install riskkit-quant` in a clean venv (then `import riskkit`).
+- Update the README install line from the GitHub URL to `pip install riskkit-trading`.
+- Bump the version for the next change (never re-upload the same version).
+- Docs are already live at https://hasibdaddy.github.io/riskkit/ (re-run
+  `mkdocs gh-deploy` after docs changes).