Metadata-Version: 2.4
Name: chrono-correlator
Version: 0.1.0
Summary: Statistical correlation between time-series and discrete events with optional LLM narration
Author-email: Raúl Gallardo <g3ov3r@gmail.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/Raulcadiz/chrono-correlator
Project-URL: Repository, https://github.com/Raulcadiz/chrono-correlator
Project-URL: Bug Tracker, https://github.com/Raulcadiz/chrono-correlator/issues
Keywords: statistics,time-series,correlation,mann-whitney,llm,health,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: scipy>=1.11
Requires-Dist: numpy>=1.24
Requires-Dist: groq>=0.4.0
Requires-Dist: anthropic>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# chrono-correlator

A generic statistical engine that correlates time-series data with discrete events using Mann-Whitney U, and narrates results with an LLM only when p < 0.05.

## Install

```bash
pip install chrono-correlator
```

## Quick start

```python
from datetime import datetime, timedelta
from chrono_correlator import Event, Metric, evaluate, narrate

base = datetime(2024, 1, 1)

events = [
    Event(timestamp=base + timedelta(days=d), label="migraine")
    for d in [10, 20, 30]
]

timestamps = [base + timedelta(hours=h) for h in range(800)]
values = [55.0] * 800
for day in [10, 20, 30]:
    for h in range(48):
        idx = day * 24 - 48 + h
        if 0 <= idx < 800:
            values[idx] = 28.0

hrv = Metric(name="hrv", timestamps=timestamps, values=values)

report = evaluate(events, [hrv])
print(f"Level: {report.level} — {report.active_signals}/{report.total_signals} signals")

if report.level != "green":
    report = narrate(report, provider="groq")
    print(report.narrative)
```

## How it works

- **Statistical core:** For each metric, values in the 48 h before each event are compared against a 28-day baseline using Mann-Whitney U. Effect size is computed as rank-biserial correlation.
- **Alert level:** Active signals (p < 0.05) are counted across all metrics. 1–2 → green, 3–4 → yellow, 5–7 → red.
- **LLM narration:** Only triggered on yellow or red. The model receives pre-calculated statistics and is constrained to one factual sentence per signal — no diagnosis, no causal inference.

## Use cases

- **Health monitoring** — correlate HRV, deep sleep, or skin temperature drops with migraine or crisis events.
- **Infrastructure** — detect latency or error-rate anomalies preceding service outages.
- **IPTV / streaming** — link buffering load spikes to subscriber disconnection events.
- **Energy consumption** — associate power demand patterns with grid stress or equipment failures.

## License

GPL-3.0 — Raúl Gallardo (g3v3r)
