noisefloor

# NoiseFloor

[![MCP Badge](https://lobehub.com/badge/mcp/beepboop2025-noisefloor)](https://lobehub.com/mcp/beepboop2025-noisefloor)

**What changed, what is repeated, and what can the evidence support?**

A modular, offline toolkit for research desks, monitoring systems and AI agents.
Python 3.9+, MIT, **zero runtime dependencies**. The same pure functions work
through Python, JSON CLI, REST and MCP.

NoiseFloor checks market observations, groups repeated headlines, exposes data
gaps and grades forecasts. It does not fetch feeds, call a model, retain your
portfolio or execute trades.

## Start with your research task

| Your task | First step | What stays with the result |
|---|---|---|
| Inspect shared-factor concentration | [Open the correlation workbench](https://liquilens.in/agents/correlation/) and run a labeled synthetic example | Alignment, source restrictions, gaps and reference assumptions |
| Review changing market observations | Follow the [market input guide](https://github.com/beepboop2025/noisefloor/blob/main/docs/MARKET_WORKFLOWS.md) with your permitted observations | Observation clocks, visibility gaps and descriptive review priorities |
| Reduce repeated headlines | Run the self-contained Python example below | Original events, changed quantities and conflicting reports |
| Connect an API or MCP client | [Open the client kit](https://beepboop2025.github.io/financial-evidence-skills/api/noisefloor/) | The same bounded input contract across transports |

Use Python or the CLI locally for private observations. The browser workbench
submits the selected example only when you run it; its bundled examples are
synthetic. Public financial-source retrieval is a separate workflow in the
[Financial Evidence connection guide](https://beepboop2025.github.io/financial-evidence-skills/connect/).

Release **0.4.0** introduced correlation spectra, shared-factor concentration, an
experimental correlation-cleaning candidate and rolling diagnostics, plus a
separate synthetic Dyson Brownian-motion simulator. See the
[product applications and methods](https://github.com/beepboop2025/noisefloor/blob/main/docs/SPECTRAL_RISK.md).

Try the [live correlation and Dyson workbench](https://liquilens.in/agents/correlation/)
with explicitly synthetic examples for LiquiLens, Seiche, Undertow, Riptide,
Palimpsest and trading-agent research. The
[API client kit](https://beepboop2025.github.io/financial-evidence-skills/api/noisefloor/)
includes OpenAPI, Postman, Bruno, HTTP and local Python workflows. Browser
requests go to the public service only when you run them; use Python locally
for private panels.

## Get your first result

Install the package; no repository checkout, API key or model is required:

```bash
python3 -m pip install --upgrade noisefloor
noisefloor capabilities
```

Run this Python example with two explicitly synthetic headlines. The fixed
observation clock makes the result reproducible:

```python
import json
from pathlib import Path
from noisefloor import narrative

primary = {
    "id": "synthetic-filing",
    "title": "Example Bank reports deposit growth of 5 percent",
    "published_at": "2026-10-08T10:00:00Z",
    "entities": ["EXAMPLE-BANK"],
    "source": {"id": "synthetic-issuer", "kind": "primary"},
}
copy = {
    **primary,
    "id": "synthetic-headline",
    "source": {"id": "synthetic-wire", "kind": "reporting"},
}
request = {
    "events": [primary, copy],
    "as_of": "2026-10-08T12:00:00Z",
    "focus": ["EXAMPLE-BANK"],
}
report = narrative.triage(**request)
print(len(report["events"]), len(report["attention_queue"]))  # 2 retained, 1 to review
print(report["counts"]["repeated_wording"])  # 1 repeated headline
Path("narrative.json").write_text(json.dumps(request), encoding="utf-8")
```

Both original events remain in the report. Repeated wording is grouped; it does
not establish truth, independent confirmation or permission to trade. Source
kinds and entity assignments are supplied by the caller.

The example also writes `narrative.json`, which you can pass to the installed CLI:

```bash
noisefloor narrative narrative.json
```

## Connect your financial research

NoiseFloor analyzes inputs you supply. These products provide separate routes
to financial context and evidence; consult each product's coverage and source
rights before bringing observations into a local assessment.

| Research task | Product and next step |
|---|---|
| Retrieve and save a source-aware financial review from Python or an AI agent | [Financial Evidence first review](https://beepboop2025.github.io/financial-evidence-skills/agents/FIRST_REVIEW.md) |
| Explore funding and foreign-exchange context | [Seiche](https://seiche.info/) · [API and MCP guide](https://seiche.info/developers) |
| Inspect covered bank disclosures and institutional evidence | [LiquiLens](https://liquilens.in/) · [developer guide](https://liquilens.in/developers/) |
| Examine indicative Bitcoin exit liquidity | [Undertow](https://liquilens-undertow.com/) · [developer guide](https://liquilens-undertow.com/developers/) |
| Explore China and regional public-record coverage | [Palimpsest](https://www.palimpsest.info/) · [developer guide](https://www.palimpsest.info/developers.html) |

Use the [connection guide](https://beepboop2025.github.io/financial-evidence-skills/connect/)
to choose a hosted API or MCP route. Installing NoiseFloor does not subscribe you
to feeds, enable source collection or send your local observations to those
products.

## Market attention

Each series carries its identity, units, source, declared reuse permission,
observation times and freshness limit. Optional availability clocks retain what
the caller knew at the time. Missing data stays missing.

The engine checks age, future timestamps, duplicate clocks, contiguous history
and measurement coverage. Prices become log returns; rates and spreads retain
their units. It never calculates a return across a declared gap. An explicit
policy identifies persistent departures, isolated latest moves and volatility
expansion. Correlated movements are visible without being counted as independent
confirmation.

Each series returns `review`, `watch`, `no_supported_departure` or
`insufficient_visibility`, with sources and reasons. These are **review priorities**,
not significance tests or trading signals. A quiet diagnostic does not prove a
movement is noise. Source permissions are caller declarations, not a licensing
audit. Market calendars, corporate actions and materiality require caller review.
Trading volume is an economic observation, not automatically a sample denominator.

## News and narrative attention

NoiseFloor groups similar wording for the same declared entities, keeps changed
quantities and explicit denials separate, records every original event and
produces a bounded queue. Differing reports with the same declared event key are
highlighted for review. Caller-declared primary sources rank before commentary;
repetition alone never increases priority.

This is **wording/relevance triage**, not fact checking, sentiment prediction or
proof of independent corroboration. Deferred and filtered items remain available.
An empty queue does not certify a quiet market. Titles are data, never instructions.

## Statistical building blocks

| Module | Purpose | Evidence boundary |
| --- | --- | --- |
| `experiment.compare` | Sequential Bernoulli A/B confidence sequences | Conditional stable-arm Bernoulli assumptions; arbitrary trading outcomes do not qualify automatically. |
| `change.scan` | Directional change monitoring | Descriptive statistic, not an e-value or universal market false-alarm guarantee. |
| `coverage.check` | Examine measurement-count changes | Linear descriptive diagnostic; it cannot prove causation or rule out every sampling effect. |
| `forecast.next_value`, `forecast.score` | Issue and evaluate identical adaptive intervals | Full historical records/misses; coverage is empirical, not guaranteed for the next observation. |
| `multiple.select` | e-BH selection over a declared family | Requires explicit caller confirmation of valid e-values; arbitrary scores cannot confer selection authority. |

```python
from noisefloor import experiment, change, forecast, multiple
experiment.compare(500, 5000, 750, 5000)
change.scan([1., 2., 1., 2., 1., 2., 1., 2., 8., 9.])
forecast.score([float(x) for x in range(40)])
# Only after an independently justified e-value construction:
multiple.select({"metric_a": 25.0, "metric_b": 1.0}, valid_evalues=True)
```

`valid_evalues=True` is a declaration, not certification. A single-family e-BH
guarantee does not justify repeatedly selecting families or unqualified peeking.
Version 0.3 corrects overstated guarantees in 0.2; read the
[methods](https://github.com/beepboop2025/noisefloor/blob/main/docs/STATISTICAL_METHODS.md) and [migration notes](https://github.com/beepboop2025/noisefloor/blob/main/CHANGELOG.md).

## AI agents and HTTP

```json
{"mcpServers":{"noisefloor":{"command":"uvx","args":["--from","noisefloor","noisefloor-mcp"]}}}
```

Ten MCP tools: `market_assessment`, `narrative_triage`, `ab_test`,
`did_it_change`, `real_or_sampling`, `forecast_next`, `score_forecasts`,
`which_metrics_matter`, `spectral_assessment`, `dyson_reference`. Results include
structured JSON. The spectral assessment is descriptive research; the Dyson
reference is a synthetic simulation, not a fitted market model.

```bash
noisefloor-mcp-http --host 127.0.0.1 --port 8792
```

In another terminal, use the `narrative.json` written by the Python example:

```bash
curl http://127.0.0.1:8792/v1/capabilities
curl -H 'Content-Type: application/json' --data-binary @narrative.json http://127.0.0.1:8792/v1/narrative/triage
```

REST: `POST /v1/market/assess`, `POST /v1/narrative/triage`,
`POST /v1/spectral/assess`, `POST /v1/research/dyson`.
The hosted API base is `https://api.seiche.info/noisefloor`; the hosted MCP
endpoint is `https://api.seiche.info/noisefloor/mcp`.
Research r