Metadata-Version: 2.4
Name: fusepoint
Version: 2.0.0
Summary: FUSE - the graphical layer over the sigma_c v6 disciplined-reader kernel: tipping-point cards and report sheets that carry a 4-code verdict, a resolution band and a blindness map next to the statistical score.
Author-email: Forgotten Forge <nfo@forgottenforge.xyz>
License: AGPL-3.0-or-later OR Commercial
Project-URL: Homepage, https://www.forgottenforge.xyz
Project-URL: Repository, https://github.com/forgottenforge/fusepoint
Project-URL: Documentation, https://github.com/forgottenforge/fusepoint#readme
Project-URL: Issues, https://github.com/forgottenforge/fusepoint/issues
Project-URL: Kernel, https://github.com/forgottenforge/sigma-c-framework
Project-URL: Paper, https://doi.org/10.5281/zenodo.22066713
Keywords: tipping-point,stability,phase-transition,critical-point,data-analysis,susceptibility,scale-selection,regime-detection,sigma-c,verdict,report-card
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: License :: Other/Proprietary 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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: license_AGPL.txt
License-File: license_COMMERCIAL.txt
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: pandas>=1.5
Requires-Dist: Pillow>=9.0
Requires-Dist: sigma-c-framework<7,>=6.0.0
Provides-Extra: ui
Requires-Dist: streamlit>=1.30; extra == "ui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# FUSE

[![PyPI](https://img.shields.io/pypi/v/fusepoint.svg)](https://pypi.org/project/fusepoint/)
[![Python](https://img.shields.io/badge/python-%E2%89%A53.9-blue.svg)](https://python.org)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Commercial License](https://img.shields.io/badge/License-Commercial-orange.svg)](mailto:nfo@forgottenforge.xyz)
[![Kernel](https://img.shields.io/badge/kernel-sigma--c--framework_6-green.svg)](https://github.com/forgottenforge/sigma-c-framework)
[![Paper](https://img.shields.io/badge/paper-Zenodo_22066713-blue.svg)](https://doi.org/10.5281/zenodo.22066713)
[![Live demo](https://img.shields.io/badge/demo-huggingface-yellow)](https://huggingface.co/spaces/ForgottenForge/fuse)

**Find where your system breaks — and get told whether the reading can be trusted.**

FUSE is the graphical layer over the [`sigma_c` v6 disciplined-reader kernel](https://github.com/forgottenforge/sigma-c-framework).
You have a dial you turn and an observable you measure. FUSE finds the scale where the
observable reacts most sharply, and every number it shows carries what it is worth:

- a **4-code verdict** from the kernel — `OK` / `NOT_RESOLVABLE` / `NOT_APPLICABLE` /
  `NOT_IDENTIFIED` — read it before the number;
- a **resolution band** (the ruler's finest step, with the digits it supports — *not* a
  fabricated error bar) and a **blindness map** (what a single-observable scan cannot see);
- FUSE's own **statistical layer**: bootstrap CI, permutation p-value, sharpness and a
  0–100 stability score with an actionable recommendation;
- a **card** for the wall, a **report sheet** with the tables, a **scan table** over every
  column, and JSON / Markdown exports that record every convention you declared.

```python
from fusepoint import analyze

r = analyze(x, y, current_x=5000, x_name="Concurrent Requests", y_name="Response Time (ms)")
print(r.verdict, r.sigma_c_display, r.resolution_band["band_abs"])   # OK 7230 50.0
print(r.score, r.grade)                                              # 85 STABLE
r.save("fuse_card.png")          # the card
r.save_sheet("fuse_sheet.png")   # the report sheet (tables)
r.to_json("fuse.json")           # everything, conventions included
```

**Try it without installing:** [huggingface.co/spaces/ForgottenForge/fuse](https://huggingface.co/spaces/ForgottenForge/fuse)

## Install

```bash
pip install fusepoint              # library + fuse command
pip install "fusepoint[ui]"        # + Streamlit web UI (fuse-ui)
```

Requires `sigma-c-framework>=6.0.0,<7` (installed automatically), numpy, scipy, pandas,
matplotlib, Pillow.

## What a result carries

`analyze()` returns a `FuseResult` with two layers.

**Kernel reading (sigma_c v6)** — `r.kernel`, flattened onto the result:

| field | meaning |
|---|---|
| `verdict`, `verdict_reason`, `verdict_remediation`, `trusted` | the 4-code applicability verdict on sigma_c; `NOT_IDENTIFIED` names what to bring |
| `regime`, `regime_label`, `peak_count` | I (single mode) / II (multi-mode, `sigma_c` is a list) / III (no interior scale, `sigma_c` is `None`) under the declared prominence convention |
| `sigma_c`, `sigma_c_display`, `resolution_band` | the location, printed with only the digits the band supports; the band is half the local grid cell plus the prominence range over which the regime holds |
| `kernel.convention_stable` | is the peak count unchanged across an octave of the prominence convention? (the kernel's OK gate) |
| `gamma_O` | strict-SOC stability indicator of the peak (low = flat peak, transition zone) |
| `rho_star`, `window`, `falsifiable`, `tau_bridge` | the probe window's analytic profile constant; `tau_bridge = sigma_c / rho_star` is a load-dominant read-out, **not** a certified relaxation time |
| `citations`, `kernel.citations` | theorem labels backing the result, rendered with the register's proof status (`PROVED`, `GAP-KNOWN`, `NO-REGISTER-ENTRY`, …) |
| `blindness`, `notes` | the blindness map (layer table + null-cone note) and the kernel's diagnostic notes |
| `kernel.result` | the untouched `sigma_c.Result` for anything else (`.summary()`, `.to_dict()`, `.card()`) |

**Statistical layer (FUSE)**: `score`, `grade`, `critical_x`, `ci` (bootstrap, approximate),
`kappa`, `p_value`, `safety_margin`, `components`, `recommendation`, `diagnosis`.

The score measures *sharpness*. A broad relaxation profile can be a perfectly resolved
scale (verdict `OK`) with a low score; pure noise can produce a significant sharpness peak
while the kernel refuses (`NOT_RESOLVABLE`). The two layers answer different questions,
and the card shows both — the verdict first.

## Cards, sheet, tables

```python
r.save("card.png")                 # one page: verdict, gauge, curves, two metric columns
r.save_sheet("sheet.png")          # tables: reading, statistics, convention sweep,
                                   #         blindness map, theorem backing, kernel notes
r.sweep_table()                    # DataFrame: verdict across prominence x smoothing
r.to_markdown()                    # the sheet as Markdown tables
r.to_json(include_sweep=True)      # schema 2, every convention recorded
```

<p align="center"><img src="example_server_load.png" width="820" alt="FUSE card"></p>
<p align="center"><img src="example_server_load_sheet.png" width="820" alt="FUSE report sheet"></p>

The **convention sweep** re-reads the same curve under a grid of declared conventions
(prominence × smoothing). A story that holds across the neighbourhood is a reading; one
that holds in a single cell is a convention artefact.

The **stability range** (`r.stability()`) condenses the sweep into one sentence: the largest set of
OK cells whose sigma_c agree within one grid cell, the smoothing and prominence range they cover,
and a tier — ROBUST (at least two thirds of the cells agree), CONDITIONAL (a cluster of three or
more; report the range with the number), FRAGILE (fewer; do not quote a scale). It is a coverage
count over a fixed grid of declared conventions, not a probability and not a confidence interval.
A setting chosen because it produced OK must be reported together with this range.

## Conventions you declare (and FUSE records)

| argument | default | what it is |
|---|---|---|
| `kernel_sigma` | adaptive | smoothing width in samples; `None` resolves to 0.6 at 100 samples scaling with sqrt(n/100) and is recorded. Declare a number to make it *your* decision; scales both derivative methods |
| `method` | `"auto"` | `"gaussian"` or `"savgol"`; the choice made by `"auto"` is recorded |
| `dial` | `"auto"` | `"linear"`: chi = \|dy/dx\|; `"log"`: chi = \|x·dy/dx\| (the kernel's native definition, geometric grids) |
| `min_prominence_ratio` | 0.10 | a bump counts as a peak above this fraction of the tallest one |
| `max_resolved_peaks` | 5 | more resolved peaks than this is read as noise (`NOT_RESOLVABLE`; the peaks are still listed) |
| `window` | `"bare"` | the probe window that fixes the analytic `rho_star` (`gamma2`, `gamma3`, `exponential`, `log_gaussian`) |
| `preprocessing_scale_equivariant` | `True` | set `False` if *your* pipeline applied a filter with an absolute scale before calling |

**Dials with zero or negative values** (temperature in °C, a parameter from 0) are shifted
before the kernel call by the kernel's own rule; the shift is recorded and every location is
reported in your units. `tau_bridge` is withheld on a shifted dial (it depends on the origin).

## More routes from the kernel

```python
# a CONDITIONAL tau from a declared single-mode profile (positive dial)
r = analyze(t, signal, profile="exponential")
r.tau_profile        # {'code': 'OK_CONDITIONAL', 'tau': 4.998, 'relative_residual': 3e-4, 'certified': False, ...}

# an APPROXIMATE statistical CI on sigma_c from replicate curves
r = analyze(t, signal, replicates=[run1, run2, run3])
r.replicate_ci       # {'ci_lo': ..., 'ci_hi': ..., 'approximate': True, ...}

# the CERTIFIED relaxation time from a reversible transfer operator
r = analyze(t, signal, operator=P, inner_product="auto", T_star=1.0,
            sigma_axis="evolution_time", gamma_A=0.5, framework="reversible_markov")
r.kernel.tau_abscissa, r.kernel.tau_abscissa_verdict["code"], r.kernel.window_readability["code"]

# the two-probe test: two observables of the SAME system
from fusepoint.kernel import two_probe
two_probe(analyze(t, obs_a).kernel, analyze(t, obs_b).kernel)
```

## Scan, compare, sweep

```python
from fusepoint import scan, scan_table, compare, sweep

results = scan("data.csv")                    # auto-detect the dial, analyze every column
print(scan_table(results))                    # one row per column: verdict, regime, sigma_c, score
from fusepoint.card import render_scan_table
render_scan_table(results).savefig("scan.png", dpi=150)

delta = compare(x, y_before, x, y_after, label_before="Before", label_after="After")
delta.save("comparison.png")

sweep(x, y)                                   # the convention sweep without the statistical layer
```

Accepts arrays, DataFrames, dicts, JSON (Plotly, Elasticsearch, pandas formats), CSV, TSV,
Excel and Parquet.

## Command line and web UI

```bash
fuse data.csv                                   # scan: table (CSV + PNG)
fuse data.csv --y latency --current-x 5000      # card + sheet + JSON + Markdown
fuse data.csv --y latency --kernel-sigma 2 --prominence 0.2 --window gamma2
fuse-ui                                         # Streamlit app (pip install "fusepoint[ui]")
```

The web app has the declared conventions in a sidebar (every change re-reads live), a scan
table with the verdict column, the card and the sheet with downloads, the sweep table, and an
advanced section for the two-probe test, the replicate CI and the certified tau route
(operator upload). `hf_space/app.py` runs the same page on Hugging Face.

## Glossary

Every symbol, value and colour on the card and the sheet is explained in
`fusepoint.glossary` (`python -c "from fusepoint import glossary; print(glossary.markdown())"`)
and in the web app (sidebar section *Glossary*, and the expander under the card).

## The four verdicts, in plain words

| code | meaning | what to do |
|---|---|---|
| **OK** | the reading stands under the declared conventions | quote sigma_c with its band; read the score next |
| **NOT_RESOLVABLE** | the data cannot resolve a scale under these conventions | too many bumps, a monotone response, or a peak that flips within an octave of the prominence convention — smooth (a recorded decision), raise the prominence, widen the sweep; look at the convention sweep |
| **NOT_APPLICABLE** | a precondition of the method is violated | e.g. preprocessing with an absolute scale; exploratory only |
| **NOT_IDENTIFIED** | an input is missing; the verdict names what to bring | e.g. a constant observable; an operator or a second probe for tau |

## What FUSE is *not*

- Not a curve fitter, not an anomaly detector, not a time-series changepoint tool.
- Not an optimiser: sigma_c is where the observable *changes fastest*, not where it is best.
- Not a source of confidence intervals on sigma_c: the resolution band is the ruler step; the
  replicate bootstrap (when you have repeats) is a statistical CI and says it is approximate.
- Not a shortcut to a relaxation time from one curve: the kernel refuses that, and so does FUSE.

## Migrating from 1.x

`sigma-c-framework` 6.0 removed the module 1.x imported for `deep=True`; 1.1.0 fails on every
fresh install. In 2.0 the kernel always runs, `deep=` is ignored with a `DeprecationWarning`,
`StabilityResult` is an alias of `FuseResult`, `regime_detail` is replaced by `r.kernel`, and
the paper anchor is *The Parrot's Theorems* read from the kernel. See `CHANGELOG.md`.

## Citation

> *The Parrot's Theorems* (2026). Preprint on Zenodo,
> [doi:10.5281/zenodo.22066713](https://doi.org/10.5281/zenodo.22066713).

Applied validation on quantum hardware: *Operational scale detection in quantum magnetism*,
AVS Quantum Science **8**, 013804 (2026), [doi:10.1116/5.0312410](https://doi.org/10.1116/5.0312410).
Software citation in [`CITATION.cff`](CITATION.cff).

## License

Copyright (c) 2026 Forgotten Forge — [forgottenforge.xyz](https://www.forgottenforge.xyz)

Dual-licensed: **AGPL-3.0-or-later** ([`license_AGPL.txt`](license_AGPL.txt)) for open-source
and academic use, or a **commercial licence** ([`license_COMMERCIAL.txt`](license_COMMERCIAL.txt),
`nfo@forgottenforge.xyz`). See [`LICENSE`](LICENSE).
