tycheon 0.1.0__py3-none-any.whl

tycheon/__init__.py

@@ -0,0 +1,32 @@
+"""Tycheon — calibrated financial forecasting and risk.
+
+Kronos forecasts the path; Tycheon tells you how much to trust it.
+
+Tycheon is the forecasting and risk layer: conformal prediction intervals and
+reliability diagnostics, exogenous covariates beyond OHLCV, regime-weighted
+routing across Kronos / TimesFM / Chronos and honest baselines, translation of
+forecasts into VaR, Expected Shortfall and drawdown probabilities, and
+leakage-proof walk-forward evaluation.
+
+Three invariants hold everywhere in this package:
+
+* **Point-in-time.** Every data read takes an ``as_of`` and refuses anything
+  published after it. Leakage tests are mandatory for every data path.
+* **Uncertainty is not optional.** Every forecast carries intervals or
+  quantiles, calibration status, the model mix, its ``as_of`` and a model card
+  reference.
+* **Baselines are published honestly.** Every evaluation reports the
+  random-walk baseline and a Diebold-Mariano test, including when the baseline
+  wins.
+
+For research and risk analytics. Not investment advice.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("tycheon")
+except PackageNotFoundError:  # pragma: no cover - only when run from a bare tree
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

tycheon/_svg.py

@@ -0,0 +1,55 @@
+"""Shared helpers for the diagnostic plots: matplotlib is optional, output is inline SVG.
+
+Plots are returned as SVG *strings* so an HTML report can embed them with no external files,
+no scripts and no network access. Text and lines use ``currentColor`` so a figure follows the
+page's light or dark theme.
+"""
+
+from __future__ import annotations
+
+import importlib
+import io
+import re
+from typing import TYPE_CHECKING, Any
+
+from tycheon.errors import OptionalDependencyError
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+#: Colours chosen to read on both light and dark backgrounds.
+BLUE = "#3b82c4"
+ORANGE = "#e08a2c"
+RED = "#d1495b"
+GREEN = "#3aa17e"
+GREY = "#8a8f98"
+
+
+def require_matplotlib() -> Any:
+    """Import ``matplotlib`` or explain which extra installs it."""
+    try:
+        return importlib.import_module("matplotlib")
+    except ImportError as exc:
+        raise OptionalDependencyError(
+            "plots need matplotlib. Install the extra: pip install 'tycheon[report]'"
+        ) from exc
+
+
+def new_figure(width: float = 6.0, height: float = 3.6) -> Figure:
+    """A figure not attached to pyplot (no global state, safe in servers and tests)."""
+    require_matplotlib()
+    from matplotlib.figure import Figure
+
+    return Figure(figsize=(width, height), layout="constrained")
+
+
+def figure_to_svg(fig: Figure) -> str:
+    """Serialise ``fig`` to an inline-able SVG string that follows the page colour scheme."""
+    buffer = io.StringIO()
+    fig.savefig(buffer, format="svg", transparent=True)
+    svg = buffer.getvalue()
+    start = svg.find("<svg")
+    body = svg[start:] if start >= 0 else svg
+    body = re.sub(r"<metadata>.*?</metadata>\s*", "", body, flags=re.DOTALL)
+    # black text and axes become the surrounding text colour (light and dark themes)
+    return body.replace("#000000", "currentColor").replace("rgb(0%, 0%, 0%)", "currentColor")

tycheon/_vendor/kronos/LICENSE

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

tycheon/_vendor/kronos/README.md

@@ -0,0 +1,39 @@
+# Vendored: Kronos
+
+Upstream: <https://github.com/shiyu-coder/Kronos> at commit
+`67b630e67f6a18c9e9be918d9b4337c960db1e9a`, MIT licensed
+(Copyright (c) 2025 ShiYu). The licence file is retained here verbatim and ships
+inside the wheel.
+
+## What is here
+
+| File | Why |
+|---|---|
+| `model/kronos.py` | `KronosTokenizer`, `Kronos`, the sampling helpers. |
+| `model/module.py` | The transformer building blocks they import. |
+| `LICENSE` | Upstream MIT licence. Must travel with the code. |
+| `UPSTREAM.json` | Commit and SHA-256 of every file above. |
+
+Upstream's `model/__init__.py`, predictor examples, fine-tuning pipeline and web
+UI are deliberately **not** vendored. Tycheon does not call upstream's
+`KronosPredictor`: its sampler averages the sample paths away, and Tycheon needs
+them (see ADR 0002).
+
+## Rules
+
+1. **Do not edit these files.** `tests/test_vendored_kronos.py` hashes them
+   against `UPSTREAM.json` and fails on any difference, so an accidental edit,
+   an editor reformat or a line-ending change cannot slip in.
+2. Everything Tycheon adds lives in `src/tycheon/models/kronos/`, never here.
+3. To update, vendor the new upstream commit in a PR of its own, regenerate
+   `UPSTREAM.json`, and re-run the slow Kronos tests. Read upstream's diff
+   first: a changed sampler or normalisation is a changed model.
+4. Excluded from ruff, mypy and every pre-commit hook, because reformatting
+   vendored code makes it impossible to diff against upstream.
+
+## How it is imported
+
+Upstream does `from model.module import *` behind a `sys.path.append("../")`.
+Putting a top-level package called `model` on `sys.path` would shadow anything
+else with that name, so `tycheon.models.kronos.vendor` loads the two files by
+path and resolves that one import itself, then removes every trace of it.

tycheon/_vendor/kronos/UPSTREAM.json

@@ -0,0 +1,12 @@
+{
+  "repository": "https://github.com/shiyu-coder/Kronos",
+  "commit": "67b630e67f6a18c9e9be918d9b4337c960db1e9a",
+  "license": "MIT",
+  "copyright": "Copyright (c) 2025 ShiYu",
+  "note": "Byte-identical copies. Do not edit; see third_party/kronos/README.md.",
+  "files": {
+    "LICENSE": "acb2d194d378204e5f2be4dcd24d39ecac437903620c790c3315a96dab388fdc",
+    "model/kronos.py": "0a5f90282e2039c2de0771473419715c845def154896dbd0f5747837e6241032",
+    "model/module.py": "a4df669998fa8115ac219b06687abaff2fac0fce9da762007dd142038949eee5"
+  }
+}