chrono-correlator 0.1.0__tar.gz

chrono_correlator-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+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)

chrono_correlator-0.1.0/README.md

@@ -0,0 +1,57 @@
+# 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)

chrono_correlator-0.1.0/chrono_correlator/__init__.py

@@ -0,0 +1,17 @@
+from .correlator import analyze
+from .engine import evaluate
+from .models import AlertReport, CorrelationResult, Event, Metric
+from .narrator import narrate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "analyze",
+    "evaluate",
+    "narrate",
+    "Event",
+    "Metric",
+    "CorrelationResult",
+    "AlertReport",
+    "__version__",
+]

chrono_correlator-0.1.0/chrono_correlator/correlator.py

@@ -0,0 +1,53 @@
+from datetime import timedelta
+
+import numpy as np
+from scipy import stats
+
+from .models import CorrelationResult, Event, Metric
+
+
+def analyze(
+    events: list[Event],
+    metric: Metric,
+    lookback_hours: int = 48,
+    baseline_days: int = 28,
+) -> CorrelationResult:
+    ts = np.array([t.timestamp() for t in metric.timestamps])
+    vals = np.array(metric.values)
+
+    pre_event_values: list[float] = []
+    baseline_values: list[float] = []
+
+    for event in events:
+        t_event = event.timestamp.timestamp()
+        t_pre_start = t_event - lookback_hours * 3600
+        t_baseline_start = t_event - baseline_days * 86400
+
+        mask_pre = (ts >= t_pre_start) & (ts < t_event)
+        mask_baseline = (ts >= t_baseline_start) & (ts < t_pre_start)
+
+        pre_event_values.extend(vals[mask_pre].tolist())
+        baseline_values.extend(vals[mask_baseline].tolist())
+
+    n1, n2 = len(pre_event_values), len(baseline_values)
+
+    if n1 < 3 or n2 < 3:
+        raise ValueError(
+            f"Datos insuficientes para '{metric.name}'. "
+            f"Pre-evento: {n1}, Baseline: {n2}"
+        )
+
+    stat, p_value = stats.mannwhitneyu(
+        pre_event_values, baseline_values, alternative="two-sided"
+    )
+    effect_size = 1 - (2 * stat) / (n1 * n2)
+
+    return CorrelationResult(
+        metric_name=metric.name,
+        p_value=float(p_value),
+        significant=bool(p_value < 0.05),
+        effect_size=float(effect_size),
+        baseline_median=float(np.median(baseline_values)),
+        pre_event_median=float(np.median(pre_event_values)),
+        narrative=None,
+    )

chrono_correlator-0.1.0/chrono_correlator/engine.py

@@ -0,0 +1,36 @@
+from .correlator import analyze
+from .models import AlertReport, CorrelationResult, Event, Metric
+
+THRESHOLDS = {"green": (0, 2), "yellow": (3, 4), "red": (5, 7)}
+
+
+def evaluate(
+    events: list[Event],
+    metrics: list[Metric],
+    lookback_hours: int = 48,
+    baseline_days: int = 28,
+) -> AlertReport:
+    results: list[CorrelationResult] = []
+
+    for metric in metrics:
+        try:
+            results.append(analyze(events, metric, lookback_hours, baseline_days))
+        except ValueError:
+            continue
+
+    active = sum(1 for r in results if r.significant)
+
+    if active <= 2:
+        level = "green"
+    elif active <= 4:
+        level = "yellow"
+    else:
+        level = "red"
+
+    return AlertReport(
+        level=level,
+        active_signals=active,
+        total_signals=len(results),
+        results=results,
+        narrative=None,
+    )

chrono_correlator-0.1.0/chrono_correlator/models.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class Event:
+    timestamp: datetime
+    label: str
+    notes: Optional[str] = None
+
+
+@dataclass
+class Metric:
+    name: str
+    timestamps: list[datetime]
+    values: list[float]
+
+
+@dataclass
+class CorrelationResult:
+    metric_name: str
+    p_value: float
+    significant: bool
+    effect_size: float
+    baseline_median: float
+    pre_event_median: float
+    narrative: Optional[str] = None
+
+
+@dataclass
+class AlertReport:
+    level: str
+    active_signals: int
+    total_signals: int
+    results: list[CorrelationResult]
+    narrative: Optional[str] = None

chrono_correlator-0.1.0/chrono_correlator/narrator.py

@@ -0,0 +1,57 @@
+import os
+
+from .models import AlertReport, CorrelationResult
+
+
+def _build_prompt(r: CorrelationResult) -> str:
+    return (
+        "Datos estadísticos CALCULADOS (no los inventes ni los modifiques):\n"
+        f"Variable: {r.metric_name}\n"
+        f"Mediana baseline: {r.baseline_median}\n"
+        f"Mediana pre-evento: {r.pre_event_median}\n"
+        f"p-valor Mann-Whitney U: {r.p_value}\n"
+        f"Tamaño del efecto (rank-biserial): {r.effect_size}\n"
+        "Escribe UNA frase en español. Máximo 20 palabras.\n"
+        "Usa: patrón detectado, asociación observada.\n"
+        "Prohibido: diagnóstico, causa, predice, confirma."
+    )
+
+
+def _call_groq(prompt: str) -> str:
+    from groq import Groq
+
+    client = Groq(api_key=os.environ["GROQ_API_KEY"])
+    response = client.chat.completions.create(
+        model="llama3-8b-8192",
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=80,
+    )
+    return response.choices[0].message.content.strip()
+
+
+def _call_anthropic(prompt: str) -> str:
+    import anthropic
+
+    client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+    response = client.messages.create(
+        model="claude-haiku-4-5-20251001",
+        max_tokens=80,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return response.content[0].text.strip()
+
+
+def narrate(report: AlertReport, provider: str = "groq") -> AlertReport:
+    if report.level == "green":
+        return report
+
+    caller = _call_groq if provider == "groq" else _call_anthropic
+
+    individual_narratives: list[str] = []
+    for result in report.results:
+        if result.significant:
+            result.narrative = caller(_build_prompt(result))
+            individual_narratives.append(f"[{result.metric_name}] {result.narrative}")
+
+    report.narrative = "\n".join(individual_narratives) if individual_narratives else None
+    return report

chrono_correlator-0.1.0/chrono_correlator/tests/test_correlator.py

@@ -0,0 +1,54 @@
+import pytest
+from datetime import datetime, timedelta
+
+from chrono_correlator.models import Event, Metric
+from chrono_correlator.correlator import analyze
+
+
+BASE = datetime(2024, 1, 1)
+
+
+def _make_flat_metric(name: str, hours: int, value: float = 55.0) -> Metric:
+    timestamps = [BASE + timedelta(hours=h) for h in range(hours)]
+    values = [value] * hours
+    return Metric(name=name, timestamps=timestamps, values=values)
+
+
+def test_detects_real_pattern():
+    hours = 700
+    timestamps = [BASE + timedelta(hours=h) for h in range(hours)]
+    values = [55.0] * hours
+
+    event_days = [10, 20, 30]
+    for day in event_days:
+        for h in range(48):
+            idx = day * 24 - 48 + h
+            if 0 <= idx < hours:
+                values[idx] = 30.0
+
+    metric = Metric(name="hrv", timestamps=timestamps, values=values)
+    events = [Event(timestamp=BASE + timedelta(days=d), label="test") for d in event_days]
+
+    result = analyze(events, metric)
+
+    assert result.significant is True
+    assert result.pre_event_median < result.baseline_median
+    assert result.narrative is None
+
+
+def test_no_false_positive():
+    metric = _make_flat_metric("hrv", hours=700, value=55.0)
+    events = [Event(timestamp=BASE + timedelta(days=d), label="test") for d in [10, 20, 30]]
+
+    result = analyze(events, metric)
+
+    assert result.significant is False
+
+
+def test_insufficient_data():
+    timestamps = [BASE + timedelta(hours=h) for h in range(2)]
+    metric = Metric(name="hrv", timestamps=timestamps, values=[55.0, 55.0])
+    events = [Event(timestamp=BASE + timedelta(days=1), label="test")]
+
+    with pytest.raises(ValueError, match="Datos insuficientes"):
+        analyze(events, metric)

chrono_correlator-0.1.0/chrono_correlator/tests/test_engine.py

@@ -0,0 +1,61 @@
+from datetime import datetime, timedelta
+
+from chrono_correlator.models import Event, Metric
+from chrono_correlator.engine import evaluate
+
+BASE = datetime(2024, 1, 1)
+EVENT_DAYS = [10, 20, 30]
+EVENTS = [Event(timestamp=BASE + timedelta(days=d), label="test") for d in EVENT_DAYS]
+
+
+def _flat_metric(name: str, hours: int = 700, value: float = 55.0) -> Metric:
+    timestamps = [BASE + timedelta(hours=h) for h in range(hours)]
+    return Metric(name=name, timestamps=timestamps, values=[value] * hours)
+
+
+def _pattern_metric(name: str, hours: int = 700) -> Metric:
+    timestamps = [BASE + timedelta(hours=h) for h in range(hours)]
+    values = [55.0] * hours
+    for day in EVENT_DAYS:
+        for h in range(48):
+            idx = day * 24 - 48 + h
+            if 0 <= idx < hours:
+                values[idx] = 30.0
+    return Metric(name=name, timestamps=timestamps, values=values)
+
+
+def test_green_level():
+    metrics = [_flat_metric(f"m{i}") for i in range(7)]
+    report = evaluate(EVENTS, metrics)
+    assert report.level == "green"
+    assert report.narrative is None
+
+
+def test_yellow_level():
+    metrics = [_pattern_metric(f"m{i}") for i in range(3)] + [
+        _flat_metric(f"flat{i}") for i in range(4)
+    ]
+    report = evaluate(EVENTS, metrics)
+    assert report.level == "yellow"
+    assert report.active_signals == 3
+
+
+def test_red_level():
+    metrics = [_pattern_metric(f"m{i}") for i in range(5)] + [
+        _flat_metric(f"flat{i}") for i in range(2)
+    ]
+    report = evaluate(EVENTS, metrics)
+    assert report.level == "red"
+    assert report.active_signals >= 5
+
+
+def test_skips_insufficient_metrics():
+    tiny = Metric(
+        name="tiny",
+        timestamps=[BASE + timedelta(hours=h) for h in range(2)],
+        values=[55.0, 55.0],
+    )
+    metrics = [tiny, _flat_metric("good")]
+    report = evaluate(EVENTS, metrics)
+    assert report.total_signals == 1
+    assert report.level == "green"

chrono_correlator-0.1.0/chrono_correlator.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+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)

chrono_correlator-0.1.0/chrono_correlator.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+chrono_correlator/__init__.py
+chrono_correlator/correlator.py
+chrono_correlator/engine.py
+chrono_correlator/models.py
+chrono_correlator/narrator.py
+chrono_correlator.egg-info/PKG-INFO
+chrono_correlator.egg-info/SOURCES.txt
+chrono_correlator.egg-info/dependency_links.txt
+chrono_correlator.egg-info/requires.txt
+chrono_correlator.egg-info/top_level.txt
+chrono_correlator/tests/__init__.py
+chrono_correlator/tests/test_correlator.py
+chrono_correlator/tests/test_engine.py

chrono_correlator-0.1.0/chrono_correlator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chrono_correlator-0.1.0/chrono_correlator.egg-info/requires.txt

@@ -0,0 +1,8 @@
+scipy>=1.11
+numpy>=1.24
+groq>=0.4.0
+anthropic>=0.20.0
+
+[dev]
+pytest
+pytest-cov

chrono_correlator-0.1.0/chrono_correlator.egg-info/top_level.txt

@@ -0,0 +1 @@
+chrono_correlator

chrono_correlator-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chrono-correlator"
+version = "0.1.0"
+description = "Statistical correlation between time-series and discrete events with optional LLM narration"
+readme = "README.md"
+license = "GPL-3.0-only"
+authors = [{ name = "Raúl Gallardo", email = "g3ov3r@gmail.com" }]
+keywords = ["statistics", "time-series", "correlation", "mann-whitney", "llm", "health", "monitoring"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "scipy>=1.11",
+    "numpy>=1.24",
+    "groq>=0.4.0",
+    "anthropic>=0.20.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/Raulcadiz/chrono-correlator"
+Repository = "https://github.com/Raulcadiz/chrono-correlator"
+"Bug Tracker" = "https://github.com/Raulcadiz/chrono-correlator/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["chrono_correlator*"]

chrono_correlator-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+