astrooracle 0.1.0__tar.gz

astrooracle-0.1.0/LICENSE

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

astrooracle-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: astrooracle
+Version: 0.1.0
+Summary: AstroOracle: active learning oracle for astronomical anomaly triage (SkyView cutouts + annotations + retrain hooks).
+Author: AstroOracle Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/<OWNER>/AstroOracle
+Project-URL: Issues, https://github.com/<OWNER>/AstroOracle/issues
+Keywords: astronomy,anomaly-detection,active-learning,skyview,astropy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: astropy>=5.3
+Requires-Dist: astroquery>=0.4.6
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: pyarrow>=12.0
+Requires-Dist: pillow>=10.0
+Provides-Extra: notebook
+Requires-Dist: ipywidgets>=8.1; extra == "notebook"
+Requires-Dist: jupyterlab>=4.0; extra == "notebook"
+Requires-Dist: plotly>=5.18; extra == "notebook"
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.18; extra == "plotly"
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == "watch"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-cov<8,>=5; extra == "dev"
+Requires-Dist: coverage[toml]<8,>=7; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.6; extra == "dev"
+Requires-Dist: black<27,>=24; extra == "dev"
+Requires-Dist: pre-commit<5,>=3.7; extra == "dev"
+Requires-Dist: mypy<2,>=1.10; extra == "dev"
+Requires-Dist: types-requests>=2.32.0.20240914; extra == "dev"
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Requires-Dist: nox>=2024.4.15; extra == "dev"
+Dynamic: license-file
+
+# AstroOracle
+
+AstroOracle is an active learning “oracle” for astronomical anomaly triage.
+
+- Reads candidate detections from a Parquet file.
+- Ranks them by uncertainty + optional embedding diversity.
+- Pulls multi-survey cutouts from SkyView.
+- Annotates via CLI (matplotlib) or Jupyter (ipywidgets + Plotly).
+- Logs events in append-only JSONL.
+- Optionally triggers retraining.
+
+## Install (editable)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e ".[plotly,watch,notebook]"
+```
+
+## Quickstart (CLI)
+
+Generate sample candidates:
+
+```bash
+python examples/sample_candidates.py
+```
+
+Run oracle:
+
+```bash
+astrooracle run --candidates candidates.parquet --interval 300 --n-query 6
+```
+
+Headless + PNG export:
+
+```bash
+astrooracle run --no-gui --save-cutouts cutouts/ --candidates candidates.parquet
+```
+
+## Jupyter UI
+
+```bash
+jupyter lab
+```
+
+Open `examples/oracle_notebook.ipynb`.
+
+## Watch mode (watchdog)
+
+```bash
+astrooracle watch --candidates candidates.parquet
+```
+
+## Batch HTML export
+
+```bash
+astrooracle batch-html --candidates candidates.parquet --out-dir batch_out/ --n-query 60
+```
+
+Open `batch_out/index.html` and export annotations from the page.
+
+## License
+
+MIT

astrooracle-0.1.0/README.md

@@ -0,0 +1,65 @@
+# AstroOracle
+
+AstroOracle is an active learning “oracle” for astronomical anomaly triage.
+
+- Reads candidate detections from a Parquet file.
+- Ranks them by uncertainty + optional embedding diversity.
+- Pulls multi-survey cutouts from SkyView.
+- Annotates via CLI (matplotlib) or Jupyter (ipywidgets + Plotly).
+- Logs events in append-only JSONL.
+- Optionally triggers retraining.
+
+## Install (editable)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e ".[plotly,watch,notebook]"
+```
+
+## Quickstart (CLI)
+
+Generate sample candidates:
+
+```bash
+python examples/sample_candidates.py
+```
+
+Run oracle:
+
+```bash
+astrooracle run --candidates candidates.parquet --interval 300 --n-query 6
+```
+
+Headless + PNG export:
+
+```bash
+astrooracle run --no-gui --save-cutouts cutouts/ --candidates candidates.parquet
+```
+
+## Jupyter UI
+
+```bash
+jupyter lab
+```
+
+Open `examples/oracle_notebook.ipynb`.
+
+## Watch mode (watchdog)
+
+```bash
+astrooracle watch --candidates candidates.parquet
+```
+
+## Batch HTML export
+
+```bash
+astrooracle batch-html --candidates candidates.parquet --out-dir batch_out/ --n-query 60
+```
+
+Open `batch_out/index.html` and export annotations from the page.
+
+## License
+
+MIT

astrooracle-0.1.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "astrooracle"
+version = "0.1.0"
+description = "AstroOracle: active learning oracle for astronomical anomaly triage (SkyView cutouts + annotations + retrain hooks)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AstroOracle Contributors" }]
+keywords = ["astronomy", "anomaly-detection", "active-learning", "skyview", "astropy"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = [
+  "numpy>=1.23",
+  "pandas>=2.0",
+  "matplotlib>=3.7",
+  "astropy>=5.3",
+  "astroquery>=0.4.6",
+  "scikit-learn>=1.3",
+  "pyarrow>=12.0",
+  "pillow>=10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/<OWNER>/AstroOracle"
+Issues = "https://github.com/<OWNER>/AstroOracle/issues"
+
+[project.optional-dependencies]
+notebook = [
+  "ipywidgets>=8.1",
+  "jupyterlab>=4.0",
+  "plotly>=5.18",
+]
+plotly = ["plotly>=5.18"]
+watch = ["watchdog>=3.0"]
+
+# A single extra that makes CI/dev reproducible.
+# Pins are intentionally bounded to avoid surprise breakage in CI.
+dev = [
+  "pytest>=8,<10",
+  "pytest-cov>=5,<8",
+  "coverage[toml]>=7,<8",
+  "ruff>=0.6,<1.0",
+  "black>=24,<27",
+  "pre-commit>=3.7,<5",
+  "mypy>=1.10,<2",
+  "types-requests>=2.32.0.20240914",
+  "build>=1.2,<2",
+  "twine>=5,<7",
+  "nox>=2024.4.15",
+]
+
+
+[project.scripts]
+astrooracle = "astrooracle.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+astrooracle = ["py.typed"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-q --disable-warnings --maxfail=1 --cov=astrooracle --cov-report=term-missing"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["astrooracle"]
+
+[tool.coverage.report]
+fail_under = 0
+show_missing = true
+skip_covered = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["E501"]  # black handles line-length
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+no_implicit_optional = true
+check_untyped_defs = true
+strict_equality = true
+ignore_missing_imports = true
+mypy_path = "src"

astrooracle-0.1.0/setup.cfg

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

astrooracle-0.1.0/src/astrooracle/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

astrooracle-0.1.0/src/astrooracle/annotations.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from .config import OracleConfig
+
+
+def append_annotations(cfg: OracleConfig, rows: list[dict[str, Any]]) -> None:
+    if not rows:
+        return
+    df_new = pd.DataFrame(rows)
+    cfg.annot_path.parent.mkdir(parents=True, exist_ok=True)
+    write_header = not cfg.annot_path.exists()
+    df_new.to_csv(cfg.annot_path, mode="a", header=write_header, index=False)
+
+
+def read_annotations(cfg: OracleConfig) -> pd.DataFrame:
+    if not cfg.annot_path.exists():
+        return pd.DataFrame()
+    df = pd.read_csv(cfg.annot_path)
+    if "embedding" in df.columns and not df.empty:
+
+        def _loads(x):
+            if pd.isna(x):
+                return None
+            if isinstance(x, str) and x.strip():
+                try:
+                    return np.array(json.loads(x), dtype=float)
+                except Exception:
+                    return None
+            return None
+
+        df["embedding_vec"] = df["embedding"].map(_loads)
+    return df
+
+
+def count_labels(cfg: OracleConfig) -> int:
+    if not cfg.annot_path.exists():
+        return 0
+    with cfg.annot_path.open("r", encoding="utf-8") as f:
+        n = sum(1 for _ in f)
+    return max(n - 1, 0)
+
+
+def get_retrain_cursor(cfg: OracleConfig) -> int:
+    cursor_path = cfg.annot_path.with_suffix(".cursor.json")
+    if not cursor_path.exists():
+        return 0
+    try:
+        return int(json.loads(cursor_path.read_text(encoding="utf-8")).get("rows", 0))
+    except Exception:
+        return 0
+
+
+def set_retrain_cursor(cfg: OracleConfig, rows: int) -> None:
+    cursor_path = cfg.annot_path.with_suffix(".cursor.json")
+    cursor_path.write_text(json.dumps({"rows": rows}), encoding="utf-8")

astrooracle-0.1.0/src/astrooracle/batch_html.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from PIL import Image
+
+from .config import OracleConfig
+from .core import fetch_cutouts
+
+
+def _slug(s: Any) -> str:
+    return re.sub(r"[^a-zA-Z0-9_-]+", "_", str(s))
+
+
+def _save_png(array2d: np.ndarray, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    arr = np.asarray(array2d, dtype=float)
+    finite = arr[np.isfinite(arr)]
+    if finite.size == 0:
+        norm = np.zeros_like(arr, dtype=np.uint8)
+    else:
+        lo = np.percentile(finite, 1)
+        hi = np.percentile(finite, 99)
+        if hi <= lo:
+            hi = lo + 1.0
+        norm = np.clip((arr - lo) / (hi - lo), 0, 1)
+        norm = (norm * 255).astype(np.uint8)
+    Image.fromarray(norm).save(path)
+
+
+def generate_batch_html(cfg: OracleConfig, candidates_df: pd.DataFrame, out_dir: Path) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    cut_dir = out_dir / "cutouts"
+    cut_dir.mkdir(exist_ok=True)
+
+    recs: list[dict[str, Any]] = []
+    for _, r in candidates_df.iterrows():
+        ra = float(r["ra"])
+        dec = float(r["dec"])
+        cid = r["id"]
+        cutouts = fetch_cutouts(ra, dec, cfg)
+
+        surveys = []
+        for survey, data in cutouts:
+            surveys.append(survey)
+            png = cut_dir / f"{_slug(cid)}_{_slug(survey)}.png"
+            _save_png(data, png)
+
+        recs.append(
+            {
+                "id": str(cid),
+                "ra": ra,
+                "dec": dec,
+                "score": float(r["anomaly_score"]),
+                "surveys": surveys,
+            }
+        )
+
+    (out_dir / "candidates.json").write_text(json.dumps(recs, indent=2), encoding="utf-8")
+
+    template = Path(__file__).resolve().parents[2] / "templates" / "batch_index.html"
+    (out_dir / "index.html").write_text(template.read_text(encoding="utf-8"), encoding="utf-8")

astrooracle-0.1.0/src/astrooracle/cli.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .annotations import append_annotations, count_labels, get_retrain_cursor, set_retrain_cursor
+from .batch_html import generate_batch_html
+from .config import OracleConfig
+from .core import fetch_cutouts, load_candidates, select_candidates
+from .logging_utils import log_event
+from .viz_matplotlib import render_cutouts_matplotlib
+from .watch import watch_candidates
+
+
+def _make_cfg(args: argparse.Namespace) -> OracleConfig:
+    cfg0 = OracleConfig.default()
+    save_dir = Path(args.save_cutouts) if args.save_cutouts else None
+    cutout_radius = (
+        cfg0.cutout_radius
+        if args.cutout_radius_arcmin is None
+        else (float(args.cutout_radius_arcmin) * cfg0.cutout_radius.unit)
+    )
+    return OracleConfig(
+        candidates_path=Path(args.candidates),
+        annot_path=Path(args.annotations),
+        log_path=Path(args.log),
+        retrain_script=Path(args.retrain_script),
+        model_path=Path(args.model_path),
+        min_new_labels_for_retrain=int(args.min_new_labels),
+        check_interval_s=int(args.interval),
+        surveys=list(args.survey),
+        cutout_radius=cutout_radius,
+        pixels=int(args.pixels),
+        n_query=int(args.n_query),
+        no_gui=bool(args.no_gui),
+        save_cutouts_dir=save_dir,
+    )
+
+
+def maybe_retrain(cfg: OracleConfig) -> None:
+    total = count_labels(cfg)
+    cursor = get_retrain_cursor(cfg)
+    new_since = total - cursor
+    if new_since >= cfg.min_new_labels_for_retrain:
+        print(f"Retrain triggered: {new_since} new labels.")
+        log_event(
+            cfg, {"event": "retrain_triggered", "new_labels": new_since, "total_labels": total}
+        )
+        try:
+            subprocess.run(["python", str(cfg.retrain_script)], check=True)
+            set_retrain_cursor(cfg, total)
+            log_event(cfg, {"event": "retrain_success"})
+        except Exception as e:
+            log_event(cfg, {"event": "retrain_failed", "error": str(e)})
+            print(f"Retrain failed: {e}")
+
+
+def annotate_batch(cfg: OracleConfig, top: pd.DataFrame) -> None:
+    label_map = {"r": "real_anomaly", "a": "artefact", "c": "known", "j": "new_type"}
+
+    new_rows = []
+    has_emb = "embedding" in top.columns
+
+    for _, row in top.iterrows():
+        title = (
+            f"ID: {row['id']} | Score: {float(row['anomaly_score']):.4f} | "
+            f"RA: {float(row['ra']):.5f} Dec: {float(row['dec']):.5f}"
+        )
+        print("\n" + "=" * 60)
+        print(title)
+
+        cutouts = fetch_cutouts(float(row["ra"]), float(row["dec"]), cfg)
+
+        save_path = None
+        if cfg.save_cutouts_dir is not None:
+            safe_id = str(row["id"]).replace("/", "_")
+            save_path = cfg.save_cutouts_dir / f"{safe_id}.png"
+
+        render_cutouts_matplotlib(cutouts, title, cfg, save_path=save_path)
+
+        while True:
+            choice = (
+                input("Label ? [r]éel [a]rtefact [c]onnu [j]junk/nouveau [s]kip -> ")
+                .strip()
+                .lower()
+            )
+            if choice in {"r", "a", "c", "j", "s"}:
+                break
+
+        if choice == "s":
+            continue
+
+        comment = input("Commentaire (Enter pour skip): ").strip()
+        entry = {
+            "id": row["id"],
+            "ra": float(row["ra"]),
+            "dec": float(row["dec"]),
+            "anomaly_score": float(row["anomaly_score"]),
+            "label": label_map[choice],
+            "comment": comment,
+            "annotated_at": pd.Timestamp.utcnow().isoformat(),
+        }
+
+        if has_emb and row.get("embedding", None) is not None:
+            entry["embedding"] = json.dumps(np.asarray(row["embedding"], dtype=float).tolist())
+
+        new_rows.append(entry)
+
+    if new_rows:
+        append_annotations(cfg, new_rows)
+        log_event(cfg, {"event": "new_annotations", "count": len(new_rows)})
+        maybe_retrain(cfg)
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    cfg = _make_cfg(args)
+    log_event(cfg, {"event": "oracle_started", "mode": "poll"})
+    print(f"AstroOracle running. candidates={cfg.candidates_path} interval={cfg.check_interval_s}s")
+
+    while True:
+        try:
+            df = load_candidates(cfg)
+            if not df.empty:
+                top = select_candidates(df, cfg)
+                if not top.empty:
+                    annotate_batch(cfg, top)
+        except KeyboardInterrupt:
+            log_event(cfg, {"event": "oracle_stopped"})
+            print("Stopped.")
+            break
+        except Exception as e:
+            log_event(cfg, {"event": "error", "msg": str(e)})
+            print(f"Error: {e}")
+
+        time.sleep(cfg.check_interval_s)
+
+
+def cmd_watch(args: argparse.Namespace) -> None:
+    cfg = _make_cfg(args)
+    log_event(cfg, {"event": "oracle_started", "mode": "watch"})
+    print(f"AstroOracle watching {cfg.candidates_path}")
+
+    def _on_change():
+        try:
+            df = load_candidates(cfg)
+            if not df.empty:
+                top = select_candidates(df, cfg)
+                if not top.empty:
+                    annotate_batch(cfg, top)
+        except Exception as e:
+            log_event(cfg, {"event": "error", "msg": str(e)})
+            print(f"Error: {e}")
+
+    watch_candidates(cfg.candidates_path, _on_change)
+
+
+def cmd_batch_html(args: argparse.Namespace) -> None:
+    cfg = _make_cfg(args)
+    out_dir = Path(args.out_dir)
+    df = load_candidates(cfg)
+    if df.empty:
+        print("No candidates.")
+        return
+
+    cfg2 = OracleConfig(**{**cfg.__dict__, "n_query": int(args.n_query)})
+    top = select_candidates(df, cfg2)
+    if top.empty:
+        print("No selected candidates.")
+        return
+
+    generate_batch_html(cfg2, top, out_dir)
+    log_event(cfg2, {"event": "batch_html_generated", "out_dir": str(out_dir), "count": len(top)})
+    print(f"Batch HTML written to: {out_dir}/index.html")
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="astrooracle")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def add_common(sp):
+        sp.add_argument("--candidates", default="candidates.parquet")
+        sp.add_argument("--annotations", default="annotations.csv")
+        sp.add_argument("--log", default="oracle_log.jsonl")
+        sp.add_argument("--retrain-script", default="scripts/retrain_model.py")
+        sp.add_argument("--model-path", default="best_model.pkl")
+        sp.add_argument("--min-new-labels", type=int, default=10)
+        sp.add_argument("--interval", type=int, default=300)
+        sp.add_argument("--n-query", type=int, default=6)
+        sp.add_argument("--pixels", type=int, default=400)
+        sp.add_argument("--cutout-radius-arcmin", type=float, default=None)
+        sp.add_argument("--survey", action="append", default=["DSS2 Red", "2MASS J"])
+        sp.add_argument("--no-gui", action="store_true")
+        sp.add_argument("--save-cutouts", default=None)
+
+    sp_run = sub.add_parser("run", help="Poll candidates file and annotate in CLI.")
+    add_common(sp_run)
+    sp_run.set_defaults(fn=cmd_run)
+
+    sp_watch = sub.add_parser("watch", help="Watch candidates file changes (watchdog).")
+    add_common(sp_watch)
+    sp_watch.set_defaults(fn=cmd_watch)
+
+    sp_html = sub.add_parser("batch-html", help="Generate static HTML batch annotator.")
+    add_common(sp_html)
+    sp_html.add_argument("--out-dir", required=True)
+    sp_html.set_defaults(fn=cmd_batch_html)
+
+    args = p.parse_args()
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()

astrooracle-0.1.0/src/astrooracle/config.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from astropy import units as u
+
+
+@dataclass(frozen=True)
+class OracleConfig:
+    candidates_path: Path
+    annot_path: Path
+    log_path: Path
+    retrain_script: Path
+    model_path: Path
+    min_new_labels_for_retrain: int
+    check_interval_s: int
+    surveys: list[str]
+    cutout_radius: u.Quantity
+    pixels: int
+    n_query: int
+    no_gui: bool
+    save_cutouts_dir: Path | None
+
+    @staticmethod
+    def default() -> OracleConfig:
+        return OracleConfig(
+            candidates_path=Path("candidates.parquet"),
+            annot_path=Path("annotations.csv"),
+            log_path=Path("oracle_log.jsonl"),
+            retrain_script=Path("scripts/retrain_model.py"),
+            model_path=Path("best_model.pkl"),
+            min_new_labels_for_retrain=10,
+            check_interval_s=300,
+            surveys=["DSS2 Red", "2MASS J"],
+            cutout_radius=0.15 * u.arcmin,
+            pixels=400,
+            n_query=6,
+            no_gui=False,
+            save_cutouts_dir=None,
+        )

astrooracle-0.1.0/src/astrooracle/core.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from astropy import units as u
+from astropy.coordinates import SkyCoord
+from astroquery.skyview import SkyView
+from sklearn.metrics import pairwise_distances
+
+from .annotations import read_annotations
+from .config import OracleConfig
+
+REQUIRED_CAND_COLS = {"id", "ra", "dec", "anomaly_score"}
+
+
+def load_candidates(cfg: OracleConfig) -> pd.DataFrame:
+    if not cfg.candidates_path.exists():
+        return pd.DataFrame()
+    df = pd.read_parquet(cfg.candidates_path)
+    missing = REQUIRED_CAND_COLS - set(df.columns)
+    if missing:
+        raise ValueError(f"Missing columns in candidates: {missing}")
+    return df
+
+
+def select_candidates(df: pd.DataFrame, cfg: OracleConfig) -> pd.DataFrame:
+    df = df.copy()
+    median_score = float(df["anomaly_score"].median())
+    df["unc"] = np.abs(df["anomaly_score"] - median_score)
+
+    diversity = np.ones(len(df), dtype=float)
+    if "embedding" in df.columns and cfg.annot_path.exists():
+        annot = read_annotations(cfg)
+        if not annot.empty and "embedding_vec" in annot.columns:
+            ann_vecs = [v for v in annot["embedding_vec"].tolist() if isinstance(v, np.ndarray)]
+            if ann_vecs:
+                emb_all = np.stack(df["embedding"].values)
+                emb_ann = np.stack(ann_vecs)
+                dists = pairwise_distances(emb_all, emb_ann, metric="cosine")
+                diversity = dists.min(axis=1)
+                denom = (diversity.max() - diversity.min()) + 1e-8
+                diversity = (diversity - diversity.min()) / denom
+
+    unc_norm = df["unc"].to_numpy(dtype=float)
+    unc_norm = unc_norm / (float(unc_norm.max()) + 1e-8)
+
+    df["query_score"] = 0.6 * unc_norm + 0.4 * diversity
+    return df.nlargest(cfg.n_query, "query_score").reset_index(drop=True)
+
+
+def fetch_cutouts(ra_deg: float, dec_deg: float, cfg: OracleConfig) -> list[tuple[str, np.ndarray]]:
+    coord = SkyCoord(ra=ra_deg * u.deg, dec=dec_deg * u.deg)
+    results: list[tuple[str, np.ndarray]] = []
+    for survey in cfg.surveys:
+        try:
+            images = SkyView.get_images(
+                position=coord,
+                survey=[survey],
+                pixels=cfg.pixels,
+                radius=cfg.cutout_radius,
+            )
+            if not images:
+                continue
+            data = images[0][0].data
+            if data is None:
+                continue
+            results.append((survey, data))
+        except Exception:
+            continue
+    return results

astrooracle-0.1.0/src/astrooracle/logging_utils.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from .config import OracleConfig
+
+
+def utcnow_iso() -> str:
+    return datetime.utcnow().isoformat()
+
+
+def get_file_hash(path: Path) -> str:
+    if not path.exists():
+        return "no_file"
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()[:12]
+
+
+def log_event(cfg: OracleConfig, event: dict[str, Any]) -> None:
+    payload = {
+        **event,
+        "timestamp": utcnow_iso(),
+        "model_version": get_file_hash(cfg.model_path),
+        "candidates_hash": get_file_hash(cfg.candidates_path),
+    }
+    cfg.log_path.parent.mkdir(parents=True, exist_ok=True)
+    with cfg.log_path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(payload, ensure_ascii=False) + "\n")

astrooracle-0.1.0/src/astrooracle/ui_notebook.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+try:
+    import ipywidgets as w
+    from IPython.display import clear_output, display
+except Exception:  # pragma: no cover
+    w = None  # type: ignore
+    display = None  # type: ignore
+    clear_output = None  # type: ignore
+
+from .config import OracleConfig
+
+LABELS = [
+    ("Réel", "real_anomaly"),
+    ("Artefact", "artefact"),
+    ("Connu", "known"),
+    ("Nouveau type", "new_type"),
+    ("Skip", "skip"),
+]
+
+
+class OracleUI:
+    def __init__(
+        self,
+        cfg: OracleConfig,
+        load_candidates_fn: Callable[[OracleConfig], pd.DataFrame],
+        select_candidates_fn: Callable[[pd.DataFrame, OracleConfig], pd.DataFrame],
+        fetch_cutouts_fn: Callable[[float, float, OracleConfig], Any],
+        render_fn: Callable[[Any, str], None],
+        append_annotations_fn: Callable[[OracleConfig, list[dict[str, Any]]], None],
+    ):
+        if w is None:
+            raise RuntimeError(
+                "ipywidgets not installed. Install extras: pip install -e '.[notebook]'"
+            )
+
+        self.cfg = cfg
+        self.load_candidates = load_candidates_fn
+        self.select_candidates = select_candidates_fn
+        self.fetch_cutouts = fetch_cutouts_fn
+        self.render = render_fn
+        self.append_annotations = append_annotations_fn
+
+        self.batch = pd.DataFrame()
+        self.idx = 0
+
+        self.title = w.HTML("")
+        self.comment = w.Textarea(
+            description="Commentaire", layout=w.Layout(width="100%", height="80px")
+        )
+        self.next_btn = w.Button(description="Next")
+        self.reload_btn = w.Button(description="Reload candidates", button_style="info")
+        self.out = w.Output()
+
+        self.label_buttons = []
+        for txt, lab in LABELS:
+            b = w.Button(description=txt)
+            b.on_click(lambda _, lab=lab: self.on_label(lab))
+            self.label_buttons.append(b)
+
+        self.next_btn.on_click(lambda _: self.on_next())
+        self.reload_btn.on_click(lambda _: self.on_reload())
+
+        controls = w.HBox([*self.label_buttons, self.next_btn, self.reload_btn])
+        display(w.VBox([self.title, self.comment, controls, self.out]))
+
+        self.on_reload()
+
+    def on_reload(self):
+        df = self.load_candidates(self.cfg)
+        if df.empty:
+            self.batch = pd.DataFrame()
+            self.idx = 0
+            with self.out:
+                clear_output()
+                print("Aucun candidat.")
+            return
+        self.batch = self.select_candidates(df, self.cfg)
+        self.idx = 0
+        self.show_current()
+
+    def show_current(self):
+        if self.batch.empty or self.idx >= len(self.batch):
+            with self.out:
+                clear_output()
+                print("Batch terminé.")
+            return
+
+        row = self.batch.iloc[self.idx]
+        title = (
+            f"ID: {row['id']} | score: {float(row['anomaly_score']):.4f} | "
+            f"RA: {float(row['ra']):.5f} Dec: {float(row['dec']):.5f}"
+        )
+        self.title.value = f"<b>{title}</b>"
+
+        cutouts = self.fetch_cutouts(float(row["ra"]), float(row["dec"]), self.cfg)
+        with self.out:
+            clear_output()
+            self.render(cutouts, title)
+
+    def on_label(self, label: str):
+        if label == "skip":
+            self.on_next()
+            return
+
+        row = self.batch.iloc[self.idx]
+        entry: dict[str, Any] = {
+            "id": row["id"],
+            "ra": float(row["ra"]),
+            "dec": float(row["dec"]),
+            "anomaly_score": float(row["anomaly_score"]),
+            "label": label,
+            "comment": self.comment.value.strip(),
+            "annotated_at": pd.Timestamp.utcnow().isoformat(),
+        }
+        if "embedding" in self.batch.columns and row.get("embedding", None) is not None:
+            entry["embedding"] = json.dumps(np.asarray(row["embedding"], dtype=float).tolist())
+
+        self.append_annotations(self.cfg, [entry])
+        self.comment.value = ""
+        self.on_next()
+
+    def on_next(self):
+        self.idx += 1
+        self.show_current()

astrooracle-0.1.0/src/astrooracle/viz_matplotlib.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+from astropy.visualization import ImageNormalize, ZScaleInterval
+
+from .config import OracleConfig
+
+
+def render_cutouts_matplotlib(
+    cutouts: list[tuple[str, np.ndarray]],
+    title: str,
+    cfg: OracleConfig,
+    save_path: Path | None = None,
+) -> None:
+    if not cutouts:
+        print("No cutouts available.")
+        return
+
+    n = len(cutouts)
+    fig, axes = plt.subplots(1, n, figsize=(4 * n, 4))
+    if n == 1:
+        axes = [axes]
+
+    for ax, (survey, data) in zip(axes, cutouts, strict=False):
+        norm = ImageNormalize(data, interval=ZScaleInterval())
+        ax.imshow(data, cmap="gray", norm=norm, origin="lower")
+        ax.set_title(survey, fontsize=9)
+        ax.axis("off")
+
+    fig.suptitle(title, fontsize=10)
+    plt.tight_layout()
+
+    if save_path is not None:
+        save_path.parent.mkdir(parents=True, exist_ok=True)
+        fig.savefig(save_path, dpi=150)
+
+    if not cfg.no_gui:
+        plt.show(block=False)
+        plt.pause(0.25)
+
+    plt.close(fig)

astrooracle-0.1.0/src/astrooracle/viz_plotly.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import numpy as np
+
+try:
+    import plotly.express as px
+except Exception:  # pragma: no cover
+    px = None  # type: ignore
+
+
+def render_cutouts_plotly(cutouts: list[tuple[str, np.ndarray]], title: str) -> None:
+    if px is None:
+        raise RuntimeError("Plotly not installed. Install extras: pip install -e '.[plotly]'")
+    for survey, data in cutouts:
+        arr = np.asarray(data, dtype=float)
+        fig = px.imshow(arr, origin="lower", aspect="equal", title=f"{title} | {survey}")
+        fig.update_layout(margin=dict(l=10, r=10, t=40, b=10))
+        fig.update_xaxes(showticklabels=False)
+        fig.update_yaxes(showticklabels=False)
+        fig.show()

astrooracle-0.1.0/src/astrooracle/watch.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+try:
+    from watchdog.events import FileSystemEventHandler
+    from watchdog.observers import Observer
+except Exception:  # pragma: no cover
+    Observer = None  # type: ignore
+    FileSystemEventHandler = object  # type: ignore
+
+
+class CandidatesHandler(FileSystemEventHandler):
+    def __init__(self, candidates_path: Path, on_change: Callable[[], None]):
+        self.candidates_path = candidates_path.resolve()
+        self.on_change = on_change
+
+    def on_modified(self, event):
+        if getattr(event, "is_directory", False):
+            return
+        src = Path(getattr(event, "src_path", ""))
+        if src and src.resolve() == self.candidates_path:
+            self.on_change()
+
+    def on_created(self, event):
+        self.on_modified(event)
+
+    def on_moved(self, event):
+        dst = Path(getattr(event, "dest_path", ""))
+        if dst and dst.resolve() == self.candidates_path:
+            self.on_change()
+
+
+def watch_candidates(candidates_path: Path, on_change: Callable[[], None]) -> None:
+    if Observer is None:
+        raise RuntimeError("watchdog not installed. Install extras: pip install -e '.[watch]'")
+
+    handler = CandidatesHandler(candidates_path, on_change)
+    obs = Observer()
+    obs.schedule(handler, str(candidates_path.parent), recursive=False)
+    obs.start()
+    try:
+        while True:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        obs.stop()
+        obs.join()

astrooracle-0.1.0/src/astrooracle.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: astrooracle
+Version: 0.1.0
+Summary: AstroOracle: active learning oracle for astronomical anomaly triage (SkyView cutouts + annotations + retrain hooks).
+Author: AstroOracle Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/<OWNER>/AstroOracle
+Project-URL: Issues, https://github.com/<OWNER>/AstroOracle/issues
+Keywords: astronomy,anomaly-detection,active-learning,skyview,astropy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: astropy>=5.3
+Requires-Dist: astroquery>=0.4.6
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: pyarrow>=12.0
+Requires-Dist: pillow>=10.0
+Provides-Extra: notebook
+Requires-Dist: ipywidgets>=8.1; extra == "notebook"
+Requires-Dist: jupyterlab>=4.0; extra == "notebook"
+Requires-Dist: plotly>=5.18; extra == "notebook"
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.18; extra == "plotly"
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == "watch"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-cov<8,>=5; extra == "dev"
+Requires-Dist: coverage[toml]<8,>=7; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.6; extra == "dev"
+Requires-Dist: black<27,>=24; extra == "dev"
+Requires-Dist: pre-commit<5,>=3.7; extra == "dev"
+Requires-Dist: mypy<2,>=1.10; extra == "dev"
+Requires-Dist: types-requests>=2.32.0.20240914; extra == "dev"
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Requires-Dist: nox>=2024.4.15; extra == "dev"
+Dynamic: license-file
+
+# AstroOracle
+
+AstroOracle is an active learning “oracle” for astronomical anomaly triage.
+
+- Reads candidate detections from a Parquet file.
+- Ranks them by uncertainty + optional embedding diversity.
+- Pulls multi-survey cutouts from SkyView.
+- Annotates via CLI (matplotlib) or Jupyter (ipywidgets + Plotly).
+- Logs events in append-only JSONL.
+- Optionally triggers retraining.
+
+## Install (editable)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e ".[plotly,watch,notebook]"
+```
+
+## Quickstart (CLI)
+
+Generate sample candidates:
+
+```bash
+python examples/sample_candidates.py
+```
+
+Run oracle:
+
+```bash
+astrooracle run --candidates candidates.parquet --interval 300 --n-query 6
+```
+
+Headless + PNG export:
+
+```bash
+astrooracle run --no-gui --save-cutouts cutouts/ --candidates candidates.parquet
+```
+
+## Jupyter UI
+
+```bash
+jupyter lab
+```
+
+Open `examples/oracle_notebook.ipynb`.
+
+## Watch mode (watchdog)
+
+```bash
+astrooracle watch --candidates candidates.parquet
+```
+
+## Batch HTML export
+
+```bash
+astrooracle batch-html --candidates candidates.parquet --out-dir batch_out/ --n-query 60
+```
+
+Open `batch_out/index.html` and export annotations from the page.
+
+## License
+
+MIT

astrooracle-0.1.0/src/astrooracle.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+src/astrooracle/__init__.py
+src/astrooracle/annotations.py
+src/astrooracle/batch_html.py
+src/astrooracle/cli.py
+src/astrooracle/config.py
+src/astrooracle/core.py
+src/astrooracle/logging_utils.py
+src/astrooracle/py.typed
+src/astrooracle/ui_notebook.py
+src/astrooracle/viz_matplotlib.py
+src/astrooracle/viz_plotly.py
+src/astrooracle/watch.py
+src/astrooracle.egg-info/PKG-INFO
+src/astrooracle.egg-info/SOURCES.txt
+src/astrooracle.egg-info/dependency_links.txt
+src/astrooracle.egg-info/entry_points.txt
+src/astrooracle.egg-info/requires.txt
+src/astrooracle.egg-info/top_level.txt
+tests/test_select.py

astrooracle-0.1.0/src/astrooracle.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

astrooracle-0.1.0/src/astrooracle.egg-info/entry_points.txt

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

astrooracle-0.1.0/src/astrooracle.egg-info/requires.txt

@@ -0,0 +1,32 @@
+numpy>=1.23
+pandas>=2.0
+matplotlib>=3.7
+astropy>=5.3
+astroquery>=0.4.6
+scikit-learn>=1.3
+pyarrow>=12.0
+pillow>=10.0
+
+[dev]
+pytest<10,>=8
+pytest-cov<8,>=5
+coverage[toml]<8,>=7
+ruff<1.0,>=0.6
+black<27,>=24
+pre-commit<5,>=3.7
+mypy<2,>=1.10
+types-requests>=2.32.0.20240914
+build<2,>=1.2
+twine<7,>=5
+nox>=2024.4.15
+
+[notebook]
+ipywidgets>=8.1
+jupyterlab>=4.0
+plotly>=5.18
+
+[plotly]
+plotly>=5.18
+
+[watch]
+watchdog>=3.0

astrooracle-0.1.0/src/astrooracle.egg-info/top_level.txt

@@ -0,0 +1 @@
+astrooracle

astrooracle-0.1.0/tests/test_select.py

@@ -0,0 +1,21 @@
+import numpy as np
+import pandas as pd
+
+from astrooracle.config import OracleConfig
+from astrooracle.core import select_candidates
+
+
+def test_select_candidates_basic():
+    cfg = OracleConfig.default()
+    cfg = OracleConfig(**{**cfg.__dict__, "n_query": 5})
+    df = pd.DataFrame(
+        {
+            "id": [f"a{i}" for i in range(10)],
+            "ra": np.linspace(0, 1, 10),
+            "dec": np.linspace(0, 1, 10),
+            "anomaly_score": np.linspace(-2, 2, 10),
+        }
+    )
+    top = select_candidates(df, cfg)
+    assert len(top) == 5
+    assert "query_score" in top.columns