monohunter 0.1.0__tar.gz

monohunter-0.1.0/LICENSE

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

monohunter-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: monohunter
+Version: 0.1.0
+Summary: Find single long-period (mono-)transits in public TESS light curves that periodic pipelines under-find.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: pydantic>=2
+Requires-Dist: lightkurve>=2.5
+Requires-Dist: wotan
+Requires-Dist: astroquery
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# monohunter
+
+Find single long-period **mono-transits** in public TESS light curves — the
+single-transit events that periodic pipelines (SPOC/QLP, which fold on a period)
+structurally under-find. Built so many people can each search under-covered
+targets and combine machine-readable finds.
+
+Status: early. Detection core (P1) done and tested; CLI + packaging in progress.
+
+## Why
+
+Automated TESS pipelines run periodic searches (BLS/TLS) over every target.
+A single transit has no period to fold on, so those searches miss it. Real
+long-period planets have been co-discovered exactly here (e.g. TOI-2180 b, found
+from one ~24-hour transit). monohunter targets that gap.
+
+## How it works
+
+```
+fetch (dedup sectors, prefer 2-min, stream) ->
+detrend (wotan, window >> transit or the dip gets eaten) ->
+detect (matched-filter box scan, non-periodic) ->
+FindRecord (versioned + validated JSON)  ->  candidates/
+```
+
+The `Detector` interface is a seam: v1 is a matched-filter box scan; a
+GP-based detector (`nuance`) plugs in later without touching the pipeline.
+The versioned `FindRecord` JSON is the contract a future aggregation server
+consumes.
+
+## Reuse, not reinvention
+
+Stands on [lightkurve](https://docs.lightkurve.org),
+[wotan](https://github.com/hippke/wotan), scipy, and astroquery. monohunter is
+orchestration + the single-transit gap + result aggregation, not a new detection
+engine.
+
+## Dev
+
+```bash
+python -m venv .venv && . .venv/Scripts/activate   # Windows
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Releasing to PyPI
+
+CI (`.github/workflows/ci.yml`) runs the tests on every push. Publishing
+(`.github/workflows/release.yml`) fires on a version tag and uses **Trusted
+Publishing** — no token in GitHub.
+
+One-time PyPI setup (before the first release):
+
+1. On PyPI: Account → Publishing → **Add a pending publisher**:
+   - PyPI project name: `monohunter`
+   - Owner: `Rinkia`  ·  Repository: `monohunter`
+   - Workflow: `release.yml`  ·  Environment: leave blank (Any)
+2. (Optional) For a manual approval gate, create a GitHub Environment, set it
+   as the pending-publisher Environment, and add `environment: <name>` back to
+   the `publish` job in `release.yml`.
+
+Then release:
+
+```bash
+# bump version in pyproject.toml first
+git tag v0.1.0
+git push --tags
+```
+
+## License
+
+MIT.

monohunter-0.1.0/README.md

@@ -0,0 +1,72 @@
+# monohunter
+
+Find single long-period **mono-transits** in public TESS light curves — the
+single-transit events that periodic pipelines (SPOC/QLP, which fold on a period)
+structurally under-find. Built so many people can each search under-covered
+targets and combine machine-readable finds.
+
+Status: early. Detection core (P1) done and tested; CLI + packaging in progress.
+
+## Why
+
+Automated TESS pipelines run periodic searches (BLS/TLS) over every target.
+A single transit has no period to fold on, so those searches miss it. Real
+long-period planets have been co-discovered exactly here (e.g. TOI-2180 b, found
+from one ~24-hour transit). monohunter targets that gap.
+
+## How it works
+
+```
+fetch (dedup sectors, prefer 2-min, stream) ->
+detrend (wotan, window >> transit or the dip gets eaten) ->
+detect (matched-filter box scan, non-periodic) ->
+FindRecord (versioned + validated JSON)  ->  candidates/
+```
+
+The `Detector` interface is a seam: v1 is a matched-filter box scan; a
+GP-based detector (`nuance`) plugs in later without touching the pipeline.
+The versioned `FindRecord` JSON is the contract a future aggregation server
+consumes.
+
+## Reuse, not reinvention
+
+Stands on [lightkurve](https://docs.lightkurve.org),
+[wotan](https://github.com/hippke/wotan), scipy, and astroquery. monohunter is
+orchestration + the single-transit gap + result aggregation, not a new detection
+engine.
+
+## Dev
+
+```bash
+python -m venv .venv && . .venv/Scripts/activate   # Windows
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Releasing to PyPI
+
+CI (`.github/workflows/ci.yml`) runs the tests on every push. Publishing
+(`.github/workflows/release.yml`) fires on a version tag and uses **Trusted
+Publishing** — no token in GitHub.
+
+One-time PyPI setup (before the first release):
+
+1. On PyPI: Account → Publishing → **Add a pending publisher**:
+   - PyPI project name: `monohunter`
+   - Owner: `Rinkia`  ·  Repository: `monohunter`
+   - Workflow: `release.yml`  ·  Environment: leave blank (Any)
+2. (Optional) For a manual approval gate, create a GitHub Environment, set it
+   as the pending-publisher Environment, and add `environment: <name>` back to
+   the `publish` job in `release.yml`.
+
+Then release:
+
+```bash
+# bump version in pyproject.toml first
+git tag v0.1.0
+git push --tags
+```
+
+## License
+
+MIT.

monohunter-0.1.0/monohunter/__init__.py

@@ -0,0 +1,3 @@
+"""MonoHunter — find single long-period (mono-)transits in public TESS light curves."""
+
+__version__ = "0.1.0"

monohunter-0.1.0/monohunter/cli.py

@@ -0,0 +1,69 @@
+"""T6 — CLI: `monohunter run --tic <id>`.
+
+End-to-end: search TESS -> detrend -> detect single transits -> write one JSON
+find-record + PNG per candidate into the output dir.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .pipeline import run_target
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="monohunter",
+        description="Hunt single long-period (mono-)transits in public TESS light curves.",
+    )
+    parser.add_argument("--version", action="version", version=f"monohunter {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    run = sub.add_parser("run", help="search one target by TIC id")
+    run.add_argument("--tic", type=int, required=True, help="TESS Input Catalog id")
+    run.add_argument("--window", type=float, default=3.0, help="detrend window in days (>> transit)")
+    run.add_argument("--outdir", default="candidates", help="where to write JSON + PNG")
+    run.add_argument("--no-plot", action="store_true", help="skip PNG generation")
+    run.add_argument(
+        "--sectors",
+        type=int,
+        nargs="+",
+        default=None,
+        help="restrict to these sector numbers (default: all available)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "run":
+        records = run_target(
+            args.tic,
+            window_length=args.window,
+            outdir=args.outdir,
+            make_plots=not args.no_plot,
+            sectors=args.sectors,
+        )
+        if not records:
+            print(f"No candidates for TIC {args.tic} (nothing above SNR threshold).")
+            return 0
+
+        os.makedirs(args.outdir, exist_ok=True)
+        for rec in records:
+            path = os.path.join(args.outdir, f"tic{rec.tic}_s{rec.sector}.json")
+            with open(path, "w", encoding="utf-8") as fh:
+                fh.write(rec.to_json(indent=2))
+            flag = f"  [known {rec.known_toi_id}]" if rec.known_toi_match else "  [not a known TOI]"
+            print(
+                f"S{rec.sector}: depth={rec.depth_ppt:.2f}ppt "
+                f"dur={rec.duration_hr:.0f}h SNR={rec.snr:.1f}{flag} -> {path}"
+            )
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

monohunter-0.1.0/monohunter/crossmatch.py

@@ -0,0 +1,33 @@
+"""T7 — known-TOI cross-match.
+
+Flags whether a target is already a known TESS Object of Interest, so a candidate
+the tool surfaces is auto-labeled "already known" vs potentially new. Queries the
+NASA Exoplanet Archive TOI table. Network-optional: any failure degrades to
+"unknown" (False, None) so the tool still runs offline.
+"""
+
+from __future__ import annotations
+
+_CACHE: dict[int, tuple[bool, str | None]] = {}
+
+
+def known_toi(tic: int) -> tuple[bool, str | None]:
+    """Return (is_known_toi, toi_id_or_None). Cached per TIC; safe offline."""
+    tic = int(tic)
+    if tic in _CACHE:
+        return _CACHE[tic]
+
+    result: tuple[bool, str | None] = (False, None)
+    try:
+        from astroquery.ipac.nexsci.nasa_exoplanet_archive import (
+            NasaExoplanetArchive,
+        )
+
+        table = NasaExoplanetArchive.query_criteria(table="toi", where=f"tid={tic}")
+        if len(table) > 0:
+            result = (True, f"TOI-{table['toi'][0]}")
+    except Exception:
+        result = (False, None)  # network down / astroquery hiccup -> unknown
+
+    _CACHE[tic] = result
+    return result

monohunter-0.1.0/monohunter/detect/__init__.py

@@ -0,0 +1,6 @@
+"""Detection engine: a Detector interface with pluggable implementations."""
+
+from .base import Candidate, Detector
+from .box import BoxMatchedFilter
+
+__all__ = ["Candidate", "Detector", "BoxMatchedFilter"]

monohunter-0.1.0/monohunter/detect/base.py

@@ -0,0 +1,34 @@
+"""T2 — the Detector seam (design decision 1D).
+
+A Detector is PURE SIGNAL: it takes a detrended light curve (time, flux) and
+returns candidate dips. It knows nothing about TIC ids, sectors, or JSON — the
+pipeline assembles those into a FindRecord. This keeps the box detector, the
+future nuance (GP) detector, and Swarm's server-side re-scoring all behind one
+interface. Detection logic must NOT leak into the fetch or CLI layers.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """A single dip found in a light curve. No target metadata — that's the pipeline's job."""
+
+    event_time_btjd: float
+    depth_ppt: float
+    duration_hr: float
+    snr: float
+
+
+class Detector(ABC):
+    """Search a detrended light curve for mono-transit candidates."""
+
+    @abstractmethod
+    def search(self, time: np.ndarray, flux: np.ndarray) -> list[Candidate]:
+        """Return candidates ordered best-first (highest SNR). Empty list = nothing found."""
+        raise NotImplementedError

monohunter-0.1.0/monohunter/detect/box.py

@@ -0,0 +1,92 @@
+"""T3 — matched-filter box scan (v1 detector).
+
+Non-periodic by design: slides a box (uniform-mean) transit model of several
+trial durations across the light curve and scores the deepest sustained dip by
+SNR. No phase-folding, so a SINGLE transit is detectable — which is the whole
+point (TLS can't do this; it needs a period to fold on).
+
+    flux ─┐         ┌─────  baseline ≈ 1 (after normalize+detrend)
+          │  ┌───┐  │
+          └──┘   └──┘       one box, width = trial duration
+             ▲
+          depth = 1 - mean_in_box
+          snr   = depth / (sigma / sqrt(n_in))     sigma = robust MAD scatter
+
+ponytail: returns the single best candidate. Multi-candidate / iterative masking
+is a later upgrade once v1 finds things.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.ndimage import uniform_filter1d
+
+from .base import Candidate, Detector
+
+# ponytail: fixed duration grid tuned for long/single transits (hours). Widen if
+# you start hunting shorter events.
+DEFAULT_DURATIONS_HR = (2.0, 4.0, 6.0, 8.0, 12.0, 18.0, 24.0, 30.0)
+DEFAULT_SNR_THRESHOLD = 7.0  # SDE-like floor; below this is noise (see TLS best practice)
+_MAD_TO_SIGMA = 1.4826  # MAD -> Gaussian sigma
+# ponytail: trim this much from each end before searching. Start/end-of-sector
+# ramps span hours-to-a-day and masquerade as transits; a box-width-only guard
+# misses ramps wider than the smallest box. Widen if edge FPs persist.
+EDGE_TRIM_D = 0.5
+
+
+class BoxMatchedFilter(Detector):
+    def __init__(
+        self,
+        durations_hr: tuple[float, ...] = DEFAULT_DURATIONS_HR,
+        snr_threshold: float = DEFAULT_SNR_THRESHOLD,
+    ) -> None:
+        self.durations_hr = durations_hr
+        self.snr_threshold = snr_threshold
+
+    def search(self, time: np.ndarray, flux: np.ndarray) -> list[Candidate]:
+        time = np.asarray(time, dtype=float)
+        flux = np.asarray(flux, dtype=float)
+        good = np.isfinite(time) & np.isfinite(flux)
+        time, flux = time[good], flux[good]
+        if time.size < 10:
+            return []
+
+        dt = float(np.median(np.diff(time)))  # days per cadence
+        if not np.isfinite(dt) or dt <= 0:
+            return []
+
+        sigma = _MAD_TO_SIGMA * float(np.median(np.abs(flux - np.median(flux))))
+        if sigma <= 0:
+            return []
+
+        best: Candidate | None = None
+        for dur_hr in self.durations_hr:
+            width = int(round((dur_hr / 24.0) / dt))  # cadences in the box
+            if width < 3 or width >= flux.size:
+                continue
+            rolling_mean = uniform_filter1d(flux, size=width, mode="nearest")
+            # Edge guard: a box centered at index i spans [i-width/2, i+width/2],
+            # so to keep the whole box clear of the trimmed edge zone (padding +
+            # start/end-of-sector ramps — the S26 TOI-2180 false positive) the
+            # center must sit at least EDGE_TRIM_D + half a box from each end.
+            edge = int(round(EDGE_TRIM_D / dt)) + width // 2
+            if 2 * edge >= rolling_mean.size:
+                continue
+            rolling_mean[:edge] = np.inf
+            rolling_mean[-edge:] = np.inf
+            i = int(np.argmin(rolling_mean))
+            depth = 1.0 - float(rolling_mean[i])
+            if depth <= 0:
+                continue
+            snr = depth / (sigma / np.sqrt(width))
+            if best is None or snr > best.snr:
+                best = Candidate(
+                    event_time_btjd=float(time[i]),
+                    depth_ppt=depth * 1e3,
+                    duration_hr=float(dur_hr),
+                    snr=float(snr),
+                )
+
+        if best is None or best.snr < self.snr_threshold:
+            return []
+        return [best]

monohunter-0.1.0/monohunter/detrend.py

@@ -0,0 +1,30 @@
+"""T5 — detrend wrapper (wotan).
+
+Thin wrapper so the rest of the code depends on ONE detrend entry point. The only
+real knob is `window_length` (days): it MUST be several times the transit
+duration, or flattening eats the very dip you're hunting. That footgun has a
+regression test (test_detrend.py) — do not remove it.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from wotan import flatten as _wotan_flatten
+
+DEFAULT_METHOD = "biweight"
+DEFAULT_WINDOW_D = 3.0  # ponytail: 3x a ~1-day (24h) transit. Tune per target.
+
+
+def flatten(
+    time: np.ndarray,
+    flux: np.ndarray,
+    method: str = DEFAULT_METHOD,
+    window_length: float = DEFAULT_WINDOW_D,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Return (flat_flux, trend). window_length is in DAYS."""
+    time = np.asarray(time, dtype=float)
+    flux = np.asarray(flux, dtype=float)
+    flat, trend = _wotan_flatten(
+        time, flux, method=method, window_length=window_length, return_trend=True
+    )
+    return flat, trend

monohunter-0.1.0/monohunter/fetch.py

@@ -0,0 +1,83 @@
+"""T4 — sector resolution + streaming loader (design decision 3A + streaming).
+
+Two jobs:
+  1. resolve_sectors(): dedup a search result to ONE row per sector, preferring
+     2-min (120s) SPOC over the 20-sec duplicate. The notebook's naive all-58
+     download is a footgun — many rows are the same sector at two cadences.
+  2. iter_lightcurves(): stream sectors one at a time so memory stays bounded to
+     ~one light curve even on 58-sector targets. The downloader is injected so
+     this is unit-testable without hitting the network.
+
+A "row" is any mapping with at least {"sector": int, "cadence_s": int}. In real
+use these come from lightkurve's search table; in tests they're plain dicts.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Iterable, Iterator, Mapping, TypeVar
+
+Row = Mapping[str, object]
+LC = TypeVar("LC")
+
+
+def _sector_from_mission(value: object) -> int | None:
+    match = re.search(r"Sector\s+(\d+)", str(value))
+    return int(match.group(1)) if match else None
+
+
+def _scalar(value: object) -> float:
+    return float(getattr(value, "value", value))
+
+
+def search_tess(tic: int, author: str = "SPOC") -> tuple[Any, list[Row]]:
+    """Search TESS light curves for a TIC. Returns (SearchResult, rows).
+
+    Prefers SPOC, falls back to QLP (FFI) if SPOC has nothing. Each row carries
+    the SearchResult index so the streaming loader can download it lazily.
+    Network call — not unit-tested; the CLI E2E exercises it live.
+    """
+    import lightkurve as lk
+
+    sr = lk.search_lightcurve(f"TIC {int(tic)}", mission="TESS", author=author)
+    if len(sr) == 0:
+        sr = lk.search_lightcurve(f"TIC {int(tic)}", mission="TESS", author="QLP")
+
+    table = sr.table
+    rows: list[Row] = []
+    for i in range(len(sr)):
+        sector = _sector_from_mission(table["mission"][i])
+        if sector is None:
+            continue
+        cadence = int(round(_scalar(table["exptime"][i])))
+        rows.append({"sector": sector, "cadence_s": cadence, "_index": i})
+    return sr, rows
+
+
+def _preference(cadence_s: int) -> tuple[int, int]:
+    """Lower sorts first. 120s (2-min) wins; otherwise shorter cadence."""
+    return (0 if cadence_s == 120 else 1, int(cadence_s))
+
+
+def resolve_sectors(rows: Iterable[Row]) -> list[Row]:
+    """One row per sector, 2-min preferred, sorted by sector."""
+    by_sector: dict[int, Row] = {}
+    for row in rows:
+        sector = int(row["sector"])  # type: ignore[call-overload]
+        cadence = int(row["cadence_s"])  # type: ignore[call-overload]
+        current = by_sector.get(sector)
+        if current is None or _preference(cadence) < _preference(int(current["cadence_s"])):  # type: ignore[call-overload]
+            by_sector[sector] = row
+    return [by_sector[s] for s in sorted(by_sector)]
+
+
+def iter_lightcurves(
+    rows: Iterable[Row], download: Callable[[Row], LC]
+) -> Iterator[tuple[Row, LC]]:
+    """Yield (row, light_curve) one deduped sector at a time.
+
+    The caller runs the detector on each and keeps only the find-record, so the
+    light curve is released before the next download — bounded memory.
+    """
+    for row in resolve_sectors(rows):
+        yield row, download(row)

monohunter-0.1.0/monohunter/pipeline.py

@@ -0,0 +1,89 @@
+"""Pipeline — glue fetch -> detrend -> detect -> FindRecord for one target.
+
+Streams sectors one at a time (bounded memory), runs the detector on each
+detrended light curve, and assembles a validated FindRecord per candidate with
+a diagnostic PNG. This is the orchestration layer the CLI calls.
+"""
+
+from __future__ import annotations
+
+import os
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless: save PNGs, never open a window
+import matplotlib.pyplot as plt
+import numpy as np
+
+from . import __version__
+from .crossmatch import known_toi
+from .detect import BoxMatchedFilter, Detector
+from .detrend import DEFAULT_METHOD, DEFAULT_WINDOW_D, flatten
+from .fetch import iter_lightcurves, search_tess
+from .record import FindRecord
+
+
+def _values(array: object) -> np.ndarray:
+    return np.asarray(getattr(array, "value", array), dtype=float)
+
+
+def _save_plot(outdir: str, rec: FindRecord, time: np.ndarray, flux: np.ndarray) -> str:
+    os.makedirs(outdir, exist_ok=True)
+    fig, ax = plt.subplots(figsize=(10, 4))
+    ax.scatter(time, flux, s=1)
+    ax.axvline(rec.event_time_btjd, color="red", lw=1)
+    ax.set_xlabel("Time [BTJD]")
+    ax.set_ylabel("flattened flux")
+    ax.set_title(f"TIC {rec.tic}  S{rec.sector}  SNR={rec.snr:.1f}")
+    path = os.path.join(outdir, f"tic{rec.tic}_s{rec.sector}.png")
+    fig.savefig(path, dpi=100, bbox_inches="tight")
+    plt.close(fig)
+    return path
+
+
+def run_target(
+    tic: int,
+    detector: Detector | None = None,
+    window_length: float = DEFAULT_WINDOW_D,
+    outdir: str = "candidates",
+    make_plots: bool = True,
+    sectors: list[int] | None = None,
+) -> list[FindRecord]:
+    """Search deduped sectors of one TIC; return validated candidate records.
+
+    sectors: restrict to these sector numbers (None = all available).
+    """
+    detector = detector or BoxMatchedFilter()
+    sr, rows = search_tess(tic)
+    if sectors is not None:
+        wanted = set(sectors)
+        rows = [r for r in rows if int(r["sector"]) in wanted]
+    is_known, toi_id = known_toi(tic)
+
+    def download(row: dict) -> object:
+        return sr[row["_index"]].download().remove_nans().normalize()
+
+    records: list[FindRecord] = []
+    for row, lc in iter_lightcurves(rows, download):
+        time = _values(lc.time.value if hasattr(lc.time, "value") else lc.time)
+        flux = _values(lc.flux)
+        flat, _ = flatten(time, flux, window_length=window_length)
+        for cand in detector.search(time, flat):
+            rec = FindRecord(
+                tic=int(tic),
+                sector=int(row["sector"]),
+                cadence_s=int(row["cadence_s"]),
+                event_time_btjd=cand.event_time_btjd,
+                depth_ppt=cand.depth_ppt,
+                duration_hr=cand.duration_hr,
+                snr=cand.snr,
+                detrend_method=DEFAULT_METHOD,
+                detrend_window_d=window_length,
+                tool_version=__version__,
+                known_toi_match=is_known,
+                known_toi_id=toi_id,
+            )
+            if make_plots:
+                rec = rec.model_copy(update={"plot_path": _save_plot(outdir, rec, time, flat)})
+            records.append(rec)
+    return records

monohunter-0.1.0/monohunter/record.py

@@ -0,0 +1,37 @@
+"""T1 — the find-record: MonoHunter's output unit and the Swarm aggregation contract.
+
+Versioned + validated (design decision 2A). `schema_version` travels with every
+record so a future Swarm server can migrate old contributor files. `extra="forbid"`
+makes a typo'd or drifted field a hard error at write time, not a silent mismatch
+that only surfaces when 100 people's JSON files fail to merge.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+SCHEMA_VERSION = 1
+
+
+class FindRecord(BaseModel):
+    """One candidate mono-transit, ready to serialize to JSON."""
+
+    model_config = ConfigDict(extra="forbid")  # reject unknown/drifted fields
+
+    schema_version: int = SCHEMA_VERSION
+    tic: int = Field(..., description="TESS Input Catalog id of the target")
+    sector: int
+    cadence_s: int = Field(..., description="120 (2-min) or 20 (20-sec)")
+    event_time_btjd: float = Field(..., description="dip center, TESS BTJD")
+    depth_ppt: float = Field(..., ge=0, description="transit depth, parts per thousand")
+    duration_hr: float = Field(..., gt=0)
+    snr: float = Field(..., ge=0)
+    detrend_method: str
+    detrend_window_d: float = Field(..., gt=0)
+    tool_version: str
+    known_toi_match: bool = False
+    known_toi_id: str | None = None
+    plot_path: str | None = None
+
+    def to_json(self, **kwargs: object) -> str:
+        return self.model_dump_json(**kwargs)  # type: ignore[arg-type]

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

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: monohunter
+Version: 0.1.0
+Summary: Find single long-period (mono-)transits in public TESS light curves that periodic pipelines under-find.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: pydantic>=2
+Requires-Dist: lightkurve>=2.5
+Requires-Dist: wotan
+Requires-Dist: astroquery
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# monohunter
+
+Find single long-period **mono-transits** in public TESS light curves — the
+single-transit events that periodic pipelines (SPOC/QLP, which fold on a period)
+structurally under-find. Built so many people can each search under-covered
+targets and combine machine-readable finds.
+
+Status: early. Detection core (P1) done and tested; CLI + packaging in progress.
+
+## Why
+
+Automated TESS pipelines run periodic searches (BLS/TLS) over every target.
+A single transit has no period to fold on, so those searches miss it. Real
+long-period planets have been co-discovered exactly here (e.g. TOI-2180 b, found
+from one ~24-hour transit). monohunter targets that gap.
+
+## How it works
+
+```
+fetch (dedup sectors, prefer 2-min, stream) ->
+detrend (wotan, window >> transit or the dip gets eaten) ->
+detect (matched-filter box scan, non-periodic) ->
+FindRecord (versioned + validated JSON)  ->  candidates/
+```
+
+The `Detector` interface is a seam: v1 is a matched-filter box scan; a
+GP-based detector (`nuance`) plugs in later without touching the pipeline.
+The versioned `FindRecord` JSON is the contract a future aggregation server
+consumes.
+
+## Reuse, not reinvention
+
+Stands on [lightkurve](https://docs.lightkurve.org),
+[wotan](https://github.com/hippke/wotan), scipy, and astroquery. monohunter is
+orchestration + the single-transit gap + result aggregation, not a new detection
+engine.
+
+## Dev
+
+```bash
+python -m venv .venv && . .venv/Scripts/activate   # Windows
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Releasing to PyPI
+
+CI (`.github/workflows/ci.yml`) runs the tests on every push. Publishing
+(`.github/workflows/release.yml`) fires on a version tag and uses **Trusted
+Publishing** — no token in GitHub.
+
+One-time PyPI setup (before the first release):
+
+1. On PyPI: Account → Publishing → **Add a pending publisher**:
+   - PyPI project name: `monohunter`
+   - Owner: `Rinkia`  ·  Repository: `monohunter`
+   - Workflow: `release.yml`  ·  Environment: leave blank (Any)
+2. (Optional) For a manual approval gate, create a GitHub Environment, set it
+   as the pending-publisher Environment, and add `environment: <name>` back to
+   the `publish` job in `release.yml`.
+
+Then release:
+
+```bash
+# bump version in pyproject.toml first
+git tag v0.1.0
+git push --tags
+```
+
+## License
+
+MIT.

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

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+monohunter/__init__.py
+monohunter/cli.py
+monohunter/crossmatch.py
+monohunter/detrend.py
+monohunter/fetch.py
+monohunter/pipeline.py
+monohunter/record.py
+monohunter.egg-info/PKG-INFO
+monohunter.egg-info/SOURCES.txt
+monohunter.egg-info/dependency_links.txt
+monohunter.egg-info/entry_points.txt
+monohunter.egg-info/requires.txt
+monohunter.egg-info/top_level.txt
+monohunter/detect/__init__.py
+monohunter/detect/base.py
+monohunter/detect/box.py
+tests/test_detect_box.py
+tests/test_detrend.py
+tests/test_fetch.py
+tests/test_pipeline.py
+tests/test_record.py

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

@@ -0,0 +1 @@
+

monohunter-0.1.0/monohunter.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+monohunter = monohunter.cli:main

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

@@ -0,0 +1,10 @@
+numpy
+scipy
+matplotlib
+pydantic>=2
+lightkurve>=2.5
+wotan
+astroquery
+
+[dev]
+pytest

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

@@ -0,0 +1 @@
+monohunter

monohunter-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "monohunter"
+version = "0.1.0"
+description = "Find single long-period (mono-)transits in public TESS light curves that periodic pipelines under-find."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "numpy",
+    "scipy",
+    "matplotlib",
+    "pydantic>=2",
+    "lightkurve>=2.5",
+    "wotan",
+    "astroquery",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+monohunter = "monohunter.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["monohunter*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

monohunter-0.1.0/setup.cfg

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

monohunter-0.1.0/tests/test_detect_box.py

@@ -0,0 +1,59 @@
+"""T3 tests — the box detector must recover a real dip AND reject flat noise."""
+
+import numpy as np
+
+from monohunter.detect import BoxMatchedFilter, Candidate
+
+
+def _time_axis(n=2000, cadence_min=2.0):
+    dt = cadence_min / (60.0 * 24.0)  # days
+    return np.arange(n) * dt
+
+
+def test_flat_noise_yields_no_candidate():
+    rng = np.random.default_rng(0)
+    time = _time_axis()
+    flux = 1.0 + rng.normal(0.0, 5e-4, size=time.size)
+    assert BoxMatchedFilter().search(time, flux) == []
+
+
+def test_injected_transit_is_recovered():
+    rng = np.random.default_rng(1)
+    time = _time_axis()
+    flux = 1.0 + rng.normal(0.0, 5e-4, size=time.size)
+
+    # Inject a ~24h box dip, depth 5 ppt, centered in the light curve.
+    dt = time[1] - time[0]
+    half = int((0.5 / 24.0) / dt) * 24  # ~12h half-width -> ~24h box
+    center = time.size // 2
+    flux[center - half : center + half] -= 5e-3
+
+    found = BoxMatchedFilter().search(time, flux)
+    assert len(found) == 1
+    cand = found[0]
+    assert isinstance(cand, Candidate)
+    assert cand.snr >= 7.0
+    assert cand.depth_ppt > 2.0  # recovered a real dip, not noise
+    # event time lands within the injected window
+    assert abs(cand.event_time_btjd - time[center]) < (half + 5) * dt
+
+
+def test_edge_ramp_is_not_a_candidate():
+    # Start-of-sector ramp (no real transit) must NOT fire — the S26 false-positive bug.
+    time = _time_axis()
+    flux = np.ones(time.size)
+    ramp = 300
+    flux[:ramp] = np.linspace(0.995, 1.0, ramp)  # rising ramp at the left edge
+    rng = np.random.default_rng(2)
+    flux += rng.normal(0.0, 5e-4, size=time.size)
+    assert BoxMatchedFilter().search(time, flux) == []
+
+
+def test_short_light_curve_is_safe():
+    assert BoxMatchedFilter().search(np.arange(4.0), np.ones(4)) == []
+
+
+def test_zero_scatter_is_safe():
+    # A perfectly flat curve has sigma 0 — must not divide by zero.
+    time = _time_axis(n=500)
+    assert BoxMatchedFilter().search(time, np.ones(time.size)) == []

monohunter-0.1.0/tests/test_detrend.py

@@ -0,0 +1,34 @@
+"""T5 tests — the top footgun: a too-short detrend window EATS the transit.
+
+This regression guards the #1 mistake from the reproduce-by-hand notebook.
+"""
+
+import numpy as np
+
+from monohunter.detrend import flatten
+
+
+def _curve_with_dip():
+    # 27-day sector, slow sinusoidal stellar trend, one ~24h box dip of 1%.
+    time = np.linspace(0.0, 27.0, 27 * 720)  # 2-min cadence
+    trend = 1.0 + 0.01 * np.sin(2 * np.pi * time / 13.0)
+    flux = trend.copy()
+    center = time.size // 2
+    half = 360  # ~12h -> 24h dip
+    flux[center - half : center + half] -= 0.01
+    return time, flux
+
+
+def test_long_window_preserves_dip_short_window_eats_it():
+    time, flux = _curve_with_dip()
+
+    flat_good, _ = flatten(time, flux, window_length=3.0)   # >> 1-day transit
+    flat_bad, _ = flatten(time, flux, window_length=0.5)    # < 1-day transit
+
+    depth_good = 1.0 - np.nanmin(flat_good)
+    depth_bad = 1.0 - np.nanmin(flat_bad)
+
+    # Good window keeps most of the 1% dip.
+    assert depth_good > 5e-3
+    # Short window flattens the dip away — strictly shallower.
+    assert depth_bad < depth_good

monohunter-0.1.0/tests/test_fetch.py

@@ -0,0 +1,38 @@
+"""T4 tests — sector dedup (prefer 2-min) and streaming, no network."""
+
+from monohunter.fetch import iter_lightcurves, resolve_sectors
+
+
+def test_prefers_2min_and_dedups_by_sector():
+    rows = [
+        {"sector": 25, "cadence_s": 20},
+        {"sector": 25, "cadence_s": 120},   # 2-min duplicate of S25 — should win
+        {"sector": 26, "cadence_s": 20},    # only 20-sec available for S26
+    ]
+    resolved = resolve_sectors(rows)
+    assert [(r["sector"], r["cadence_s"]) for r in resolved] == [(25, 120), (26, 20)]
+
+
+def test_sorted_by_sector():
+    rows = [{"sector": 40, "cadence_s": 120}, {"sector": 14, "cadence_s": 120}]
+    assert [r["sector"] for r in resolve_sectors(rows)] == [14, 40]
+
+
+def test_iter_streams_deduped_rows_one_at_a_time():
+    rows = [
+        {"sector": 25, "cadence_s": 20},
+        {"sector": 25, "cadence_s": 120},
+        {"sector": 26, "cadence_s": 120},
+    ]
+    downloaded = []
+
+    def fake_download(row):
+        downloaded.append((row["sector"], row["cadence_s"]))
+        return f"lc-{row['sector']}"
+
+    out = list(iter_lightcurves(rows, fake_download))
+
+    # Only the deduped set was downloaded (no 20-sec S25 duplicate).
+    assert downloaded == [(25, 120), (26, 120)]
+    assert out[0][1] == "lc-25"
+    assert out[1][1] == "lc-26"

monohunter-0.1.0/tests/test_pipeline.py

@@ -0,0 +1,114 @@
+"""T6/T7 tests — pipeline assembles a valid FindRecord end to end, no network.
+
+We fake the two network touchpoints (search_tess, known_toi) and feed a light
+curve with an injected dip through the real detrend + detect + record path.
+"""
+
+import numpy as np
+
+from monohunter import pipeline
+from monohunter.record import FindRecord
+
+
+class _FakeQuantity:
+    def __init__(self, arr):
+        self.value = np.asarray(arr, dtype=float)
+
+
+class _FakeLC:
+    def __init__(self, time, flux):
+        self.time = _FakeQuantity(time)
+        self.flux = _FakeQuantity(flux)
+
+    def remove_nans(self):
+        return self
+
+    def normalize(self):
+        return self
+
+
+class _FakeSel:
+    def __init__(self, lc):
+        self._lc = lc
+
+    def download(self):
+        return self._lc
+
+
+class _FakeSR:
+    def __init__(self, lc):
+        self._lc = lc
+
+    def __getitem__(self, idx):
+        return _FakeSel(self._lc)
+
+
+def _lc_with_dip():
+    dt = 2.0 / (60 * 24)  # 2-min cadence in days
+    time = np.arange(2000) * dt
+    rng = np.random.default_rng(3)
+    flux = 1.0 + rng.normal(0, 5e-4, size=time.size)
+    c = time.size // 2
+    flux[c - 360 : c + 360] -= 6e-3  # ~24h, 6 ppt dip
+    return time, flux
+
+
+def test_run_target_builds_valid_record(monkeypatch, tmp_path):
+    time, flux = _lc_with_dip()
+    fake_sr = _FakeSR(_FakeLC(time, flux))
+    rows = [{"sector": 25, "cadence_s": 120, "_index": 0}]
+
+    monkeypatch.setattr(pipeline, "search_tess", lambda tic: (fake_sr, rows))
+    monkeypatch.setattr(pipeline, "known_toi", lambda tic: (True, "TOI-2180"))
+
+    records = pipeline.run_target(
+        298663873, outdir=str(tmp_path), make_plots=True
+    )
+
+    assert len(records) == 1
+    rec = records[0]
+    assert isinstance(rec, FindRecord)
+    assert rec.tic == 298663873
+    assert rec.sector == 25
+    assert rec.known_toi_match is True
+    assert rec.known_toi_id == "TOI-2180"
+    assert rec.snr >= 7.0
+    assert rec.plot_path is not None
+    # plot actually written
+    import os
+
+    assert os.path.exists(rec.plot_path)
+
+
+def test_sectors_filter_excludes_others(monkeypatch, tmp_path):
+    time, flux = _lc_with_dip()
+    fake_sr = _FakeSR(_FakeLC(time, flux))
+    rows = [
+        {"sector": 25, "cadence_s": 120, "_index": 0},
+        {"sector": 40, "cadence_s": 120, "_index": 0},
+    ]
+    monkeypatch.setattr(pipeline, "search_tess", lambda tic: (fake_sr, rows))
+    monkeypatch.setattr(pipeline, "known_toi", lambda tic: (False, None))
+
+    records = pipeline.run_target(
+        1, outdir=str(tmp_path), make_plots=False, sectors=[25]
+    )
+    assert {r.sector for r in records} == {25}
+
+
+def test_cli_run_wires_through(monkeypatch, tmp_path, capsys):
+    from monohunter import cli
+
+    time, flux = _lc_with_dip()
+    fake_sr = _FakeSR(_FakeLC(time, flux))
+    rows = [{"sector": 25, "cadence_s": 120, "_index": 0}]
+    monkeypatch.setattr(pipeline, "search_tess", lambda tic: (fake_sr, rows))
+    monkeypatch.setattr(pipeline, "known_toi", lambda tic: (False, None))
+
+    rc = cli.main(
+        ["run", "--tic", "298663873", "--outdir", str(tmp_path), "--no-plot"]
+    )
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "S25" in out
+    assert (tmp_path / "tic298663873_s25.json").exists()

monohunter-0.1.0/tests/test_record.py

@@ -0,0 +1,57 @@
+"""T1 tests — FindRecord is the Swarm contract, so validation must be strict."""
+
+import json
+
+import pytest
+from pydantic import ValidationError
+
+from monohunter.record import SCHEMA_VERSION, FindRecord
+
+
+def _valid_kwargs():
+    return dict(
+        tic=298663873,
+        sector=25,
+        cadence_s=120,
+        event_time_btjd=1955.3,
+        depth_ppt=4.2,
+        duration_hr=24.0,
+        snr=18.5,
+        detrend_method="biweight",
+        detrend_window_d=3.0,
+        tool_version="0.1.0",
+        known_toi_match=True,
+        known_toi_id="TOI-2180",
+    )
+
+
+def test_valid_record_builds_and_versions():
+    rec = FindRecord(**_valid_kwargs())
+    assert rec.schema_version == SCHEMA_VERSION
+    assert rec.tic == 298663873
+
+
+def test_json_round_trip_preserves_fields():
+    rec = FindRecord(**_valid_kwargs())
+    back = FindRecord(**json.loads(rec.to_json()))
+    assert back == rec
+
+
+def test_unknown_field_is_rejected():
+    # A drifted/typo'd field must be a hard error, not silently accepted.
+    with pytest.raises(ValidationError):
+        FindRecord(**_valid_kwargs(), planet_radius=6.7)
+
+
+def test_missing_required_field_is_rejected():
+    kwargs = _valid_kwargs()
+    del kwargs["tic"]
+    with pytest.raises(ValidationError):
+        FindRecord(**kwargs)
+
+
+def test_negative_depth_is_rejected():
+    kwargs = _valid_kwargs()
+    kwargs["depth_ppt"] = -1.0
+    with pytest.raises(ValidationError):
+        FindRecord(**kwargs)