pomata 0.1.0__tar.gz

pomata-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.benchmarks/
+.coverage
+htmlcov/
+
+# Environments / uv
+.venv/
+
+# Rust (added when the native extension lands)
+target/
+
+# Docs site build
+site/
+
+# OS / IDE
+.DS_Store
+.idea/
+.vscode/
+
+# Sphinx build output
+docs/_build/

pomata-0.1.0/CORRECTNESS.md

@@ -0,0 +1,297 @@
+# Correctness
+
+pomata's first promise is **verifiable correctness**. The weight is on *verifiable*: not "trust us, it is right", but
+"here is exactly how we know, and here is everything you need to check it yourself." This document is that explanation —
+the method behind every number, and the reason each test is the size it is rather than a figure picked by feel.
+
+It is also an honest document. We do not claim the code is free of bugs; no one can claim that. We claim something
+narrower and checkable: that every indicator agrees with an independent transcription of its published formula,
+satisfies a set of stated mathematical invariants, and matches the industry reference where the two are meant to match —
+and that the tests proving this are sized by derivation, not by superstition.
+
+## Why a technical indicator is hard to get right
+
+`prices.rolling_mean(14)` looks trivial, and the happy path is. The cost — the part that takes months, and that almost
+no in-house implementation pays in full — is everything around it:
+
+- **Transcription.** The published formula has to become code with no dropped term, no swapped index, no coefficient off
+  by a digit. A wrong constant is still "an indicator"; it is just the wrong one.
+- **Floating-point artifacts.** Real inputs reach the corners of IEEE-754: a squared value that underflows to zero, a
+  difference of large numbers that loses all its significant digits, two values so close that rounding reorders them.
+  Code that is algebraically right can still disagree with itself there.
+- **Boundaries.** The warmup before the first defined value; a window equal to one, equal to the series length, or
+  larger than it; a single row; an empty series. Each is an off-by-one waiting to happen.
+- **Missing data.** A leading `null`, an interior `null`, a `NaN` — does it propagate, latch, or get silently skipped?
+
+Each of these is a place a correct-looking implementation is quietly wrong on the inputs you did not think to try. The
+method below exists to make each one impossible to skip.
+
+## The method
+
+### An independent oracle
+
+Every indicator is written twice. The shipped version is tuned to vectorize; the reference is a second, deliberately
+naive derivation of the same published formula that shares no code with it. The two are derived independently from the
+source mathematics, so when they agree to within a stated floating-point tolerance, that agreement is evidence: a single
+bug would have to occur *identically* in two unrelated computations to hide, which is vanishingly unlikely. The oracle
+exists only to be the second witness.
+
+This holds literally for the great majority of indicators — anything expressible as composed Polars expressions, where
+the naive loop and the vectorized expression graph are genuinely unrelated. It holds, too, for the exponential averages
+(the unadjusted EMA, Wilder's RMA, and the ATR / RSI / MACD / multi-EMA family built on them): although the shipped code
+runs as a single sequential pass, the linear recurrence has a closed form, so the oracle is computed as an independent
+unrolled weighted sum rather than a transcription of the same loop — a forward-carry error cannot hide in it.
+
+A few indicators are irreducibly sequential with no such closed form, so their oracle necessarily resembles the shipped
+pass and confirms internal consistency, not independence — and we say so rather than overstate the guarantee:
+
+- **KAMA** — the efficiency ratio and adaptive smoothing constant are derived independently, but the recurrence they
+  drive is one-shape with the implementation;
+- **the parabolic SAR** — a path-dependent stop-and-reverse state machine the oracle must replay branch for branch;
+- **the Hilbert-transform cycle cluster** (the dominant-cycle period and phase, the phasor, the trendline, the sine
+  wave, the trend flag, and MAMA) — the FIR and quadrature stages are independent, but the adaptive dominant-cycle
+  period feeds back into its own measurement and the stages built on it.
+
+Their second witness is elsewhere: the parabolic SAR is anchored to golden masters hand-computed from Wilder's published
+rules — including the seeding and reversal branches the recurrence cannot reach by symmetry — while KAMA and the cycle
+cluster are pinned to frozen golden masters that catch any drift and are checked against TA-Lib in the non-gating
+differential tier.
+
+### A laddered test suite
+
+Four tiers, each aimed at a different threat:
+
+- **Contract** — shape, dtype, length, laziness, and that the indicator partitions independently under `.over(...)`. The
+  structural promises the type system cannot state.
+- **Edge** — the dangerous regimes, pinned by hand and checked **deterministically**: the exact warmup count; an empty
+  series; an all-`null` series; a single row; a window longer than the series; an interior `null`; a `NaN`. Each of
+  these is its own named test with a known answer on every indicator. The regimes that bite only some indicators — a
+  constant or monotone series, a window of one or of the series length, a leading `null` — are pinned where they bite.
+  These are not left to chance — and that fact is what lets the random tier below stay small.
+- **Correctness** — agreement with the oracle on a fixed realistic series, plus a frozen golden master so a value can
+  never drift unnoticed between versions.
+- **Properties** — the oracle-agreement again, and the mathematical invariants (scale behavior, boundedness, null
+  handling), now over inputs drawn at random.
+
+### A differential against the industry reference
+
+Separately, and without gating the build, each indicator is compared to TA-Lib — the reference the industry has used
+since 2007. With the canonical seeding most indicators match TA-Lib **bar for bar, from the first defined value**, so
+the comparison runs over the whole series at the same `1e-10` band as the internal oracle. A documented minority is
+checked only on the converged tail — each a case where TA-Lib itself deviates from the indicator's author over the
+warm-up (Wilder's first true range, the independent MACD / Chaikin EMAs) or carries a long, implementation-specific
+lead-in (the Hilbert cycle pipeline, the Parabolic SAR cold start). Where pomata chooses a different default, the
+divergence is documented and justified against the charting authorities, not hidden.
+
+## How much precision we guarantee, and where
+
+A correctness claim needs a number. pomata's is **ten significant figures**: every indicator reproduces its independent
+oracle to a relative `1e-10` on any finite input within a sane dynamic range. That single promise is the headline; the
+test ladder above is how it is checked, and `tests/support/tolerances.py` is its machine-readable home. In practice the
+agreement is far tighter than the promise: about half of the indicator outputs reproduce the oracle to the last bit (a
+relative difference of exactly zero), and the rest land at the `float64` noise floor — typically thirteen to fifteen
+figures, never fewer than the guaranteed ten.
+
+Why `1e-10`, and why it is "safe no matter what" for this library:
+
+- **It dwarfs the data.** Market feeds carry four to eight significant figures (a price like `123.45`, a volume); ten
+  figures means the indicator never adds error you could observe — it is lossless against its own input, with two to
+  six orders of headroom to spare.
+- **It sits far above the float-64 noise floor.** A `float64` holds about sixteen significant figures, so legitimate
+  rounding between the streaming implementation and the two-pass oracle lands around `1e-15`. `1e-10` is five orders
+  above that: tight enough to reject any real coding error, loose enough that a last-bit difference never flakes.
+- **It is verified, not asserted.** The property tier holds every indicator to `1e-10` over the full random fuzz domain,
+  and that bound is the enforced guarantee. The realized *headroom* under it is recomputable from a clean clone with
+  `scripts/calibrate_tolerances.py`, which fuzzes a representative well-conditioned set across multiple seeds and reports
+  the worst relative residual — it lands around `1e-14` (a handful of `float64` noise-floor ULPs), about four orders
+  inside the guarantee. The bound was sized to that measured headroom, not picked by feel.
+
+### Where it stops: the float-conditioning limit
+
+The one place `1e-10` cannot hold is also the one place no real market reaches. A rolling-sum statistic loses precision
+only when an entire window collapses to the float-precision floor of a much larger value that recently passed through it
+— summing a term of magnitude `1e6` beside residue thirteen orders smaller, an effective dynamic range past about
+thirteen orders. This is `float64` obeying IEEE-754, not a defect in the library or tests: the small term is absorbed
+into the mantissa of the large one, and no amount of careful coding recovers digits the format never stored. Random
+inputs do not build that pattern — the property tier verifies `1e-10` across the full `[-1e6, 1e6]` fuzz domain under
+stress — so it
+takes a deliberately adversarial series (a price dropping seven orders of magnitude bar-to-bar) to construct it. pomata
+documents this limit in the affected indicators rather than papering over it, and clamps the oscillators whose bound is
+unconditional — the Chande momentum oscillator, the money flow index, Chaikin money flow — to that bound, so an
+out-of-domain input degrades in precision rather than escaping the range.
+
+A related caveat applies wherever an output cancels toward zero, not only to one family: the squaring statistics
+(variance, standard deviation, Bollinger bands) as their near-constant-window output approaches zero, and equally any
+mean or sum (an SMA over a window straddling large values of either sign, the price transforms) at a near-zero result.
+A relative error is amplified as the denominator vanishes, so the agreement there is held to an absolute floor sized to
+the input magnitude rather than the bare relative `1e-10`. The relative bound is the guarantee everywhere the output is
+meaningfully non-zero — which is everywhere real market data lands.
+
+## How big a test has to be — and why exactly that big
+
+This is the part most suites leave to feel. We derive it. There are two separate questions with two separate answers:
+how *long* the input series must be, and how *many* random inputs to draw.
+
+### Input length: read off the indicator
+
+An indicator produces no defined value until its **warmup** of `W` rows, and reaches steady behavior only after its
+**memory** `M`. A meaningful test series is therefore
+
+```
+S = W + M + margin
+```
+
+and none of the three terms is guessed:
+
+- `W`, the warmup, is an exact property of the indicator — the number of leading rows it returns as `null`. For an
+  `n`-period RSI, `W = n`; for the dominant-cycle period, `W = 32`; for the phase-derived cycle indicators, `W = 63`.
+- `M`, the memory, is the window width for a windowed indicator (`M = w`: the output is fully formed once the window is
+  full). For a recursion that retains a fraction `r = 1 - alpha` of its state each step, the seed's influence decays as
+  `r^t`, so it falls below a chosen `epsilon` after
+
+  ```
+  M = ceil( ln(1/epsilon) / ln(1/r) )
+  ```
+
+  steps. This term only bites when a test must outlast a transient — comparing two differently-seeded implementations,
+  for instance; an oracle that shares pomata's seeding agrees from the first defined row and needs only `M = w`.
+- `margin` is a handful of rows: enough to leave several defined values for an invariant to act on, and enough spread in
+  length to exercise the warmup count at more than one total size.
+
+So a short series suffices for RSI (`W = n`, same-seeded oracle, `S = n + a few`), while a cycle indicator compared on
+its converged tail needs the settling term as well. The number is computed, not chosen.
+
+### Number of random examples: derived from what the draw is *for*
+
+Here is the figure everyone picks by feel — "let's run 500 to be safe" — and here is why that instinct is a trap.
+
+A property test that draws `N` random inputs is **sampling, not proving**. If a bad input occupies a fraction `p` of the
+input space, the chance of drawing it at least once in `N` tries is
+
+```
+1 - (1 - p)^N
+```
+
+and to hit it with confidence `1 - delta` you need
+
+```
+N  >=  ln(1/delta) / p          (for small p)
+```
+
+The floating-point artifacts that bite real indicators are *rare* — a `p` on the order of `1e-4`. Catching one reliably
+(95% of runs) would take `N` in the tens of thousands. A "safety" run of a few hundred catches it about five percent of
+the time — that is, by luck of the seed, not by design. A fixed mid-sized `N` is therefore the worst of both worlds: far
+too small to be a reliable net for rare artifacts, far larger than needed for anything else. 500 is not safer than 470
+or 240; all three are arbitrary.
+
+The way out is not a bigger `N`. It is to drive `p` toward zero — leave as little bad input to draw as possible — and
+then size `N` for what is actually left:
+
+- **The artifacts are driven out by construction, not hunted.** Inputs are drawn from the indicator's valid domain
+  (coherent OHLC bars, never impossible ones); scale tests rescale by a lossless power of two, so an ordinary rounding
+  cannot flip a comparison; and the implementation guards the true singularities (a flat window, a zero denominator). A
+  residual can remain — a few indicators carry an intrinsic phase-branch discontinuity whose sub-ULP cancellation a
+  rescale can still flip — but it is driven so rare (order `1e-4` per draw) that `N` is sized deliberately *below* that
+  flake floor, where a larger `N` would be likelier, not less likely, to trip it.
+- **The dangerous regimes are covered deterministically** by the Edge tier — the empty and single-row series, the
+  all-`null` series and over-long windows, the nulls and the `NaN` each have their own pinned test with a known answer
+  on every indicator, and the regimes that bite only some (a constant or monotone series, the window boundaries) are
+  pinned where they bite. The random draw is not what protects them.
+
+What is left for `N` to do is narrow: cover the general interior of the input space, and catch a *systematic* mistake. A
+systematic mistake — a wrong coefficient, a shifted index — is wrong on almost every input, so the chance it survives
+even a handful of independent draws is negligible. Covering a few qualitative regimes of the interior to high confidence
+is the same coupon-collector arithmetic, and lands in the same range: `N` in the low tens to about a hundred. Once the
+property is proven and the edges are pinned, a hundred draws is already generous; a larger number buys wall-clock, not
+confidence. The figure itself is a single shared number — set once in the test configuration, identical in a local run
+and in CI — that an individual family raises only when its parameter space is genuinely larger.
+
+### Tolerances: how close is close enough, by conditioning
+
+When the implementation and the oracle agree they still round differently, and how far they drift depends on the
+statistic's *conditioning*, not on a round number. Each tolerance is a named constant whose value is the worst-case
+implementation-vs-oracle residual the statistic's conditioning predicts on degenerate inputs, plus a margin:
+
+- **degree-2, two-pass** (variance): the two forms differ by about half a ULP at worst — a tight band.
+- **degree-1, square-root-amplified** (standard deviation, the EWMA / MACD signal): the square root blows the relative
+  error up as the variance approaches zero, worst residual about `1e-8` — a looser band (std is looser than variance,
+  precisely for this reason).
+- **degree-1, well-conditioned** (the recursive, windowed, and stateless means): the residual is at most a few ULP — a
+  tight band.
+- **scale-invariant** (a bounded ratio, a cycle period, a `0/1` flag): the output is `O(1)` at any input magnitude, so
+  the band is *absolute* — sizing an `O(1)` value to the input magnitude is meaningless.
+
+A magnitude-dependent band is sized to the data (`input_scale ** degree * factor`), not fixed, so it is right at every
+scale. Where one indicator legitimately departs — a difference of large terms that cancels, a band that would underflow
+at a subnormal input — the departure carries a one-line comment saying why. A bare, unexplained tolerance is treated as
+a defect, not a detail.
+
+### Benchmark size: derived from measurement stability
+
+Timing has its own sizing. A throughput measurement is meaningful only where the per-row cost dominates the fixed
+overhead of dispatching the expression — `c * S` well above a roughly constant `overhead`, i.e. `S >> overhead / c`.
+Because the slow recursions have a large `c`, they reach a stable read in *fewer* rows, not more; a million rows on a
+kernel that already takes over a second per evaluation buys no extra precision, only minutes. The complexity guard needs
+only a single decade: a 10x increase in rows multiplies a linear cost by 10 and a quadratic one by 100, so one 10x step
+separates them with a wide margin and an additive floor absorbs the overhead-bound cheap cases.
+
+## By family
+
+The method, the ladder, the sizing, and the tolerance rules above are family-agnostic — they apply unchanged to
+indicators, PnL, and metrics. What differs per family is only the *characteristic invariants*; the exact per-primitive
+figures (warmup, parameter regimes, the tolerance factor) live in the test files, declared in a uniform "Test sizing"
+header, and are not duplicated here.
+
+<details>
+<summary><b>Indicators</b> — the technical-analysis layer (the used set of TA-Lib)</summary>
+
+The characteristic invariants are scale behavior (homogeneity of degree 1 for a price-level output; invariance for a
+bounded ratio, a cycle period, or a flag), boundedness where it applies (RSI in `[0, 100]`, Williams %R in `[-100, 0]`),
+the exact warmup, and `null` / `NaN` propagation — each proven against the independent oracle and, in the non-gating
+differential tier, against TA-Lib. Adding an indicator is a copy job: the file's "Test sizing" header states three facts
+(warmup, parameter regimes, valid domain) and the rest of the property tier follows the same shape as every sibling.
+
+</details>
+
+<details>
+<summary><b>PnL</b> — accounting and transaction costs</summary>
+
+Shipped. The same machine applies — an independent oracle, the four-tier ladder, golden masters, and the missing-data /
+large-magnitude robustness tiers. The characteristic invariants are cost monotonicity (more cost, less PnL), the
+additive-vs-compounded cumulation split (`cumulative_pnl` sums currency P&L, `equity_curve` compounds returns),
+no look-ahead (every bar uses only past data), and a defined, documented behavior for every degenerate input
+(`null` / `NaN` / `0` / `±inf` / warm-up).
+
+</details>
+
+<details>
+<summary><b>Metrics</b> — performance & risk statistics</summary>
+
+Shipped. The same machine applies unchanged — an independent oracle, the four-tier ladder, derived sizing, named
+tolerances. The characteristic invariants are the annualization identities, scale-equivariance (a Sharpe ratio is
+invariant to leverage), closed-form checks (the Sharpe of constant returns, the drawdown of a monotone series), and a
+defined, documented behavior for every degenerate input (`null` skipped, a non-null `NaN` poisoning the result, and a
+degenerate denominator reported as `±inf` / `NaN`, never clipped).
+
+</details>
+
+## What we claim, precisely
+
+We prove, and you can re-run:
+
+- the output's shape, dtype, length, and laziness;
+- the exact warmup, and that a `null` or `NaN` propagates as specified;
+- agreement with an independent oracle to a stated floating-point tolerance, across the valid input domain;
+- the documented invariants — scale behavior, bounds, monotonicity where it applies;
+- parity with TA-Lib from the first defined value (a documented minority only on the converged tail), every deliberate
+  divergence documented.
+
+We do **not** claim the absence of all bugs, or correctness on inputs outside the documented domain. One limit is worth
+naming plainly: for the irreducibly-sequential indicators (KAMA, the parabolic SAR, the Hilbert cycle cluster) the oracle
+shares its structure with the implementation by construction, and most of their golden masters are the implementation's
+own frozen output — so in principle a transcription error in a seed or warm-up *value* (the counts
+are pinned independently) could slip past those two tiers. Two things close that gap: the differential against TA-Lib —
+an independent C implementation — now agrees **bar for bar from the first defined value** for most indicators (the
+canonical seeding makes the warm-up match too, not just the tail), and a handful of golden masters are hand-computed
+from the published definition. "Verifiable" is a promise about evidence, not omniscience: everything above is a test you
+can read and re-run, and a number you can recompute for yourself.

pomata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Cercato
+
+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.

pomata-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: pomata
+Version: 0.1.0
+Summary: Verifiably-correct, Polars-native quant toolkit: technical indicators, performance & risk metrics, and PnL accounting.
+Project-URL: Changelog, https://github.com/ilpomo/pomata/releases
+Project-URL: Documentation, https://ilpomo.github.io/pomata
+Project-URL: Homepage, https://github.com/ilpomo/pomata
+Project-URL: Issues, https://github.com/ilpomo/pomata/issues
+Project-URL: Repository, https://github.com/ilpomo/pomata
+Author: Thomas Cercato
+License-Expression: MIT
+License-File: LICENSE
+Keywords: finance,indicators,metrics,pnl,polars,quant,technical-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: polars>=1.42.0
+Description-Content-Type: text/markdown
+
+# pomata
+
+**A Polars-native quant toolkit — technical indicators, PnL accounting, and performance & risk metrics.** Each is a
+composable `pl.Expr`, so an entire study is one lazy Polars pipeline, from price to performance.
+
+And it doesn't ask you to trust its numbers — it **proves** them: every function is verified to the `float64` floor
+against an independent reference, under 100% branch coverage.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/ilpomo/pomata/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/ilpomo/pomata/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/codecov/c/github/ilpomo/pomata?style=flat-square&label=coverage)](https://codecov.io/gh/ilpomo/pomata)
+[![ruff](https://img.shields.io/badge/ruff-261230?style=flat-square&logo=ruff&logoColor=D7FF64)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/badge/ty-261230?style=flat-square&logo=ty&logoColor=D7FF64)](https://github.com/astral-sh/ty)
+[![mypy](https://img.shields.io/badge/mypy-4B6BFB?style=flat-square)](https://www.mypy-lang.org)
+[![pyright](https://img.shields.io/badge/pyright-4B6BFB?style=flat-square)](https://github.com/microsoft/pyright)
+[![pyrefly](https://img.shields.io/badge/pyrefly-4B6BFB?style=flat-square)](https://pyrefly.org)
+
+![Linux](https://img.shields.io/badge/Linux-505050?style=flat-square&logo=linux&logoColor=white)
+![macOS](https://img.shields.io/badge/macOS-505050?style=flat-square&logo=apple&logoColor=white)
+![Windows](https://custom-icon-badges.demolab.com/badge/Windows-505050.svg?style=flat-square&logo=windows11&logoColor=white)
+[![python](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Polars](https://img.shields.io/badge/Polars-%E2%89%A51.40-CD792C?style=flat-square)](https://pola.rs)
+[![license](https://img.shields.io/badge/license-MIT-750014?style=flat-square)](LICENSE)
+
+> **Alpha.** The API is not frozen until `1.0`; expect refinement. The correctness bar holds at every commit regardless.
+
+## From price to performance, in one query
+
+Signal, PnL, and metrics are all plain `pl.Expr`, so an entire study is a single Polars pipeline — no glue code, no
+DataFrame ping-pong, no second dependency between the steps:
+
+```python
+import polars as pl
+from pomata.indicators import rsi
+from pomata.pnl import returns_simple, returns_gross, returns_net, cost_proportional, equity_curve
+from pomata.metrics import sharpe_ratio, max_drawdown
+
+report = (
+    frame  # a DataFrame (or LazyFrame) with a "close" column
+    .with_columns(
+        weight=(rsi(pl.col("close"), 14) < 30).cast(pl.Float64).shift(1),  # go long when oversold, act next bar
+        asset_returns=returns_simple(pl.col("close")),
+    )
+    .with_columns(
+        net=returns_net(
+            returns_gross(pl.col("weight"), pl.col("asset_returns")),
+            cost_proportional(pl.col("weight"), rate=0.001),
+        ),
+    )
+    .select(
+        sharpe=sharpe_ratio(pl.col("net"), periods_per_year=252),
+        max_drawdown=max_drawdown(equity_curve(pl.col("net"))),
+    )
+)
+```
+
+The indicator feeds the signal, the signal feeds the PnL, the PnL feeds the metrics — every arrow is a `pl.Expr`, so it
+all fuses into one Polars query (eager or lazy, single series or a multi-asset panel via `.over`). The `.shift(1)` is
+the whole no-look-ahead story: a signal computed at the close acts on the next bar, by construction.
+
+## Install
+
+The only runtime dependency is **Polars**; Python **3.12+**.
+
+```bash
+# from source (today)
+git clone https://github.com/ilpomo/pomata
+cd pomata && uv sync
+```
+
+Once published to PyPI, the install will be `pip install pomata` (or `uv add pomata`).
+
+Every function is a free-standing `pl.Expr` factory — name it, compose it, run it in any Polars context. Warm-up rows
+are `null` until the window fills, never a fabricated value:
+
+```python
+import polars as pl
+from pomata.indicators import rsi
+
+frame = pl.DataFrame({"close": [44.34, 44.09, 44.15, 43.61, 44.33, 44.83, 45.10, 45.42, 45.84, 46.08, 45.89, 46.03,
+                                45.61, 46.28, 46.28, 46.00, 46.03, 46.41, 46.22, 45.64, 46.21, 46.25, 45.71, 46.45]})
+frame.select(rsi(pl.col("close"), 14).round(2).alias("rsi"))["rsi"].to_list()
+# [None, None, ..., 57.92, 62.88, 63.21, 56.01, 62.34]
+```
+
+## What's inside
+
+Three families, one package. They share a grammar (pure `pl.Expr` factories, one canonical name per concept) and a
+handoff: `pnl` emits exactly the return and equity series `metrics` consumes.
+
+### indicators — 75 functions
+
+The technical-analysis layer, each indicator a `pl.Expr` checked against TA-Lib to the `float64` floor — most bar-for-bar
+from the first emitted value, a documented minority only on the converged tail (the differential tier is non-gating).
+Multi-output indicators (`bollinger_bands`, `macd`, `stochastic_slow`, …) return a single `pl.Struct` —
+pick a line with `.struct.field(...)` or expand with `.struct.unnest()`.
+
+```python
+from pomata.indicators import bollinger_bands
+frame.select(bollinger_bands(pl.col("close"), 20).alias("bb")).unnest("bb")
+```
+
+<details><summary>All 75 indicators, by category</summary>
+
+- **channel** (5) — `donchian_channels`, `ichimoku`, `keltner_channels`, `midpoint`, `midprice`
+- **cycle** (7) — `dominant_cycle_period`, `dominant_cycle_phase`, `hilbert_phasor`, `hilbert_trendline`, `mama`, `sine_wave`, `trend_mode`
+- **directional movement** (8) — `adx`, `adxr`, `di_minus`, `di_plus`, `dm_minus`, `dm_plus`, `dx`, `vortex`
+- **momentum** (17) — `absolute_price_oscillator`, `aroon`, `aroon_oscillator`, `awesome_oscillator`, `balance_of_power`, `cci`, `chande_momentum_oscillator`, `fisher_transform`, `macd`, `mom`, `percentage_price_oscillator`, `roc`, `rsi`, `rsi_stochastic`, `trix`, `ultimate_oscillator`, `williams_r`
+- **moving average** (11) — `dema`, `ema`, `hma`, `kama`, `rma`, `sma`, `t3`, `tema`, `trima`, `vwma`, `wma`
+- **price transform** (4) — `price_average`, `price_median`, `price_typical`, `price_weighted_close`
+- **statistic** (9) — `linear_regression`, `linear_regression_angle`, `linear_regression_intercept`, `linear_regression_slope`, `standard_deviation_ewma`, `standard_deviation_rolling`, `time_series_forecast`, `variance_ewma`, `variance_rolling`
+- **stochastic** (2) — `stochastic_fast`, `stochastic_slow`
+- **trend** (2) — `parabolic_sar`, `supertrend`
+- **volatility** (4) — `atr`, `atr_normalized`, `bollinger_bands`, `true_range`
+- **volume** (6) — `accumulation_distribution`, `accumulation_distribution_oscillator`, `chaikin_money_flow`, `money_flow_index`, `obv`, `vwap`
+
+</details>
+
+### pnl — 18 functions
+
+Profit-and-loss accounting in two flows: **returns** (a signed `weight` of capital and asset returns) and **cash**
+(a `quantity` of units and a price), with composable transaction-cost models, dividends, and inverse contracts. Every
+degenerate input (`null` / `NaN` / `0` / `±inf` / warm-up) has a defined, documented, tested behavior.
+
+```python
+from pomata.pnl import returns_net, returns_gross, cost_proportional, equity_curve
+gross = returns_gross(pl.col("weight"), pl.col("asset_returns"))
+frame.select(equity_curve(returns_net(gross, cost_proportional(pl.col("weight"), rate=0.001))))
+```
+
+<details><summary>All 18 PnL functions</summary>
+
+- **cash flow** — `cost_borrow`, `cost_fixed`, `cost_funding`, `cost_notional`, `cost_per_share`, `cumulative_pnl`, `dividend`, `pnl_gross`, `pnl_gross_inverse`, `pnl_net`
+- **returns flow** — `cost_proportional`, `cost_slippage`, `equity_curve`, `returns_gross`, `returns_log`, `returns_net`, `returns_simple`, `turnover`
+
+</details>
+
+### metrics — 60 functions
+
+Performance & risk statistics as reducing `pl.Expr`: point one at a return series (e.g. `pomata.pnl.returns_net`) or an
+equity curve (e.g. `pomata.pnl.equity_curve`). Sharpe, Sortino, Calmar, drawdown, VaR/CVaR, capture, benchmark-relative
+(alpha/beta/Treynor/information ratio), and a rolling twin for every windowed form.
+
+```python
+from pomata.metrics import sharpe_ratio, max_drawdown
+frame.select(sharpe_ratio(pl.col("returns"), periods_per_year=252))
+```
+
+<details><summary>All 60 metrics</summary>
+
+- **drawdown** — `conditional_drawdown_at_risk`, `drawdown`, `drawdown_rolling`, `max_drawdown`, `max_drawdown_duration`, `pain_index`, `ulcer_index`
+- **performance** — `cagr`, `cagr_rolling`, `stability`, `total_return`, `total_return_rolling`
+- **ratio** — `adjusted_sharpe_ratio`, `burke_ratio`, `calmar_ratio`, `common_sense_ratio`, `gain_to_pain_ratio`, `omega_ratio`, `omega_ratio_rolling`, `pain_ratio`, `probabilistic_sharpe_ratio`, `recovery_ratio`, `sharpe_ratio`, `sharpe_ratio_rolling`, `sortino_ratio`, `sortino_ratio_rolling`, `sterling_ratio`, `ulcer_performance_ratio`
+- **relative** — `alpha`, `alpha_rolling`, `beta`, `beta_rolling`, `capture_downside_ratio`, `capture_ratio`, `capture_upside_ratio`, `information_ratio`, `information_ratio_rolling`, `modigliani_risk_adjusted_performance`, `treynor_ratio`, `treynor_ratio_rolling`
+- **risk** — `conditional_value_at_risk`, `downside_deviation`, `downside_deviation_rolling`, `kelly_criterion`, `kurtosis`, `kurtosis_rolling`, `payoff_ratio`, `profit_ratio`, `risk_of_ruin`, `skewness`, `skewness_rolling`, `tail_ratio`, `tail_ratio_rolling`, `value_at_risk`, `value_at_risk_modified`, `value_at_risk_parametric`, `value_at_risk_rolling`, `volatility`, `volatility_rolling`, `win_rate`
+
+</details>
+
+## Correctness
+
+**Verified, not asserted.** Every function is checked against an *independent* reference — a second code path that shares
+nothing with the implementation — plus frozen golden-master values and property-based invariants, under **100% branch
+coverage**. A function ships only when that suite is green.
+
+For indicators there is also a public reference to meet: TA-Lib. Here is one figure to every digit a `float64` holds —
+`rsi(14)`, the last value of a deterministic 400-bar series:
+
+```text
+pomata      85.20908701341023
+reference   85.20908701341023   ← independent reimplementation: identical, to the last bit
+TA-Lib      85.20908701341024   ← fifteen figures identical; differs only at the float64 floor
+```
+
+The same five indicators on the same series — most reproduce the reference *exactly*, the rest land at the noise floor:
+
+| indicator | pomata | vs reimplementation | vs TA-Lib |
+| --- | --- | :-: | :-: |
+| `sma(20)` | `105.15146076264764` | exact | `1e-13` |
+| `ema(20)` | `107.7299930892346` | `1e-13` | `1e-14` |
+| `rsi(14)` | `85.20908701341023` | exact | `1e-14` |
+| `atr(14)` | `1.904174462198776` | `9e-16` | `4e-15` |
+| `macd(12,26,9)` | `2.523444380829531` | `1e-13` | `1e-14` |
+
+The `pomata` and reference columns are pinned in the test suite; regenerate the full table — including the TA-Lib column
+(which needs the optional `differential` dependency) — from a fresh clone with
+`uv run --group differential python scripts/precision_table.py`.
+
+`pnl` and `metrics` are proven on a different axis — every degenerate input has a defined behavior, matched against an
+independent reference oracle — because their math is simple and their correctness lives at the edges, not in the digits.
+The full method (the precision guarantee, the test-sizing derivations, exactly what is and is not claimed) is in
+**[CORRECTNESS.md](CORRECTNESS.md)**.
+
+## Where pomata fits
+
+pomata is for the quant already working in Polars. Each function is a free-standing `pl.Expr` with `polars` as the only
+runtime dependency, composable across eager, lazy, single-series, and grouped (`.over`) contexts — so the everyday
+primitives live in one coherent toolkit instead of a wired-together stack.
+
+It is vectorized analytics and accounting: indicators, total mark-to-market PnL, and metrics. It is **not** an execution
+engine — no order fills, no event loop, no lot accounting.
+
+## Project
+
+- **Requirements** — Python ≥ 3.12, Polars ≥ 1.40.
+- **Contributing** — see [CONTRIBUTING.md](CONTRIBUTING.md); the full gate (lint, three gating type checkers plus an
+  advisory fourth, doctests, 100% branch coverage) runs on every commit.
+- **License** — MIT, see [LICENSE](LICENSE).
+- **Citation** — [CITATION.cff](CITATION.cff).