soloresearch 0.1.1__tar.gz

soloresearch-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+# run on every push and pull request to main
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build the wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+
+      - name: Install the built wheel and pytest
+        run: |
+          python -m pip install dist/*.whl
+          python -m pip install pytest
+
+      - name: Run the tests
+        run: |
+          python -m pytest tests/ -q

soloresearch-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+# runs when you push a version tag like v0.1.0
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    # trusted publishing needs this permission to get an OIDC token
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build the wheel and sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

soloresearch-0.1.1/.gitignore

@@ -0,0 +1,21 @@
+# build artifacts
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+
+# environments
+.venv/
+venv/
+.env
+
+# test data and run outputs (never ship these)
+data/
+outputs/
+runs/
+soloresearch/autoresearch/data/
+soloresearch/autoresearch/runs/
+
+# OS junk
+.DS_Store

soloresearch-0.1.1/LICENSE

@@ -0,0 +1 @@
+MIT License

soloresearch-0.1.1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: soloresearch
+Version: 0.1.1
+Summary: Autonomous single-track forecasting research: data-quality gating plus an agent-driven model search.
+Project-URL: Homepage, https://github.com/shantiswarup2/soloresearch
+Project-URL: Repository, https://github.com/shantiswarup2/soloresearch
+Author-email: Shanti Swarup Nayak <shantiswarup.nayak@sigmoidanalytics.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyarrow>=10.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: ruptures>=1.1.7
+Requires-Dist: scipy>=1.9
+Requires-Dist: statsmodels>=0.14
+Description-Content-Type: text/markdown
+
+# soloresearch
+
+Autonomous single-track forecasting research. Point it at a table of historical
+values and it does two things: checks whether the data can be forecast at all,
+then lets a coding agent iteratively discover a forecasting model that drives
+validation error down, with every attempt scored against a leakage-safe judge
+and logged.
+
+It is the packaged version of a research loop that, on the M5 competition data,
+took a seasonal-naive baseline from WRMSSE 0.807 to 0.542 with no human in the
+loop. The package ships the *method* (the data-quality gate, the scoring judge,
+and the agent-driven search); the numbers you get depend on your data.
+
+---
+
+## Install
+
+```
+pip install soloresearch
+```
+
+Python 3.9+. All dependencies (pandas, numpy, scipy, statsmodels, ruptures,
+openpyxl, pyarrow, pyyaml) install automatically.
+
+For stage 2 you also need a coding-agent CLI, either the Gemini CLI or Claude
+Code. The package works with whichever you have.
+
+---
+
+## Quickstart
+
+```
+soloresearch init myproject          # 1. scaffold a project
+# 2. put your data file in myproject/data/ and fill in myproject/forecast.yaml
+soloresearch run myproject           # 3. data-quality checks + stage the panel
+cd myproject/autoresearch
+gemini                               # 4. or `claude`
+```
+
+Then give the agent this prompt:
+
+> Read GEMINI.md and begin the autonomous forecasting research loop.
+> Iterate on solution.py until RMSSE plateaus.
+
+That is the whole flow. Stage 1 (`run`) is automatic. Stage 2 is an agent
+working in the project, exactly as the original research loop did.
+
+---
+
+## How it works
+
+### Stage 1 - data quality (automatic)
+
+`soloresearch run` reads your `forecast.yaml`, loads the data, and runs a
+two-part assessment on every series:
+
+- **Structural** - parses timestamps, sorts, de-duplicates, fills calendar gaps,
+  and infers the target profile from the actual values. Verdict: Clean /
+  Acceptable / Deficient.
+- **Forecastability** - gates on the three things no model can fix: too little
+  history, a constant/flat series, or pure white noise. Verdict: Forecastable /
+  Not Forecastable.
+
+It also characterises each series (trend, seasonality, demand class) and detects
+four kinds of regime change (level, trend, variance, seasonality). The headline
+is **Forecast-Ready %**: the share of series that are both non-Deficient and
+Forecastable.
+
+Reports are written to `myproject/outputs/` as Excel (detailed), HTML (summary),
+and JSON (machine-readable). A cleaned panel is staged for stage 2.
+
+If too little of the data is forecastable, it stops here and tells you why.
+
+### Stage 2 - agent-driven model search
+
+The clean panel becomes a research problem. A coding agent, following the
+`GEMINI.md` / `CLAUDE.md` instructions in the project, repeatedly:
+
+1. reads the current best score,
+2. edits `solution.py` (one hypothesis at a time),
+3. runs `python run.py` to score it against a leakage-safe RMSSE judge that
+   holds out the last `horizon` periods of each series,
+4. keeps the change if the score improved, reverts it otherwise,
+5. repeats until the score plateaus.
+
+Every attempt is snapshotted and logged to `autoresearch/runs/`, so the whole
+search is auditable. The judge only ever shows `predict()` the training history;
+the holdout is hidden, and anti-leakage rules are enforced in the instructions.
+
+---
+
+## forecast.yaml
+
+```yaml
+file: sales.parquet    # data file inside data/  (.parquet or .csv)
+time: date             # timestamp column
+target: target         # column to forecast
+entity: series_id      # column identifying each series (omit if single series)
+partitions: []         # extra grouping columns (optional)
+horizon: 6             # periods ahead to forecast and hold out for validation
+timestep: M            # Y / Q / M / W / D / H
+metric: smape          # reporting metric
+```
+
+Only `file`, `time`, and `target` are strictly required; the rest are inferred
+when omitted, but declaring them is more reliable.
+
+---
+
+## What a project looks like
+
+```
+myproject/
+  data/              your input file
+  forecast.yaml      your config
+  outputs/           DQ reports (Excel / HTML / JSON) + staged panel
+  autoresearch/      the research harness the agent drives
+    solution.py        the model file the agent evolves
+    run.py             scores the current solution
+    GEMINI.md          agent instructions
+    runs/              every attempt, snapshotted and scored
+```
+
+---
+
+## Scope and honest notes
+
+- This ships a **method**, not a guaranteed number. The M5 result (0.807 to
+  0.542) is a documented demonstration of the loop; your dataset, metric, and
+  agent will produce their own result.
+- Stage 2 is **agent-driven** by design: an external coding agent operates the
+  harness by following the prompt, which is what makes the search auditable and
+  reproducible as a process. It is not a black-box API call.
+- The search is **single-track** (one solution improved along one path). A
+  population-based version with an explicit trust layer is a separate project.
+
+---
+
+## License
+
+MIT

soloresearch-0.1.1/README.md

@@ -0,0 +1,141 @@
+# soloresearch
+
+Autonomous single-track forecasting research. Point it at a table of historical
+values and it does two things: checks whether the data can be forecast at all,
+then lets a coding agent iteratively discover a forecasting model that drives
+validation error down, with every attempt scored against a leakage-safe judge
+and logged.
+
+It is the packaged version of a research loop that, on the M5 competition data,
+took a seasonal-naive baseline from WRMSSE 0.807 to 0.542 with no human in the
+loop. The package ships the *method* (the data-quality gate, the scoring judge,
+and the agent-driven search); the numbers you get depend on your data.
+
+---
+
+## Install
+
+```
+pip install soloresearch
+```
+
+Python 3.9+. All dependencies (pandas, numpy, scipy, statsmodels, ruptures,
+openpyxl, pyarrow, pyyaml) install automatically.
+
+For stage 2 you also need a coding-agent CLI, either the Gemini CLI or Claude
+Code. The package works with whichever you have.
+
+---
+
+## Quickstart
+
+```
+soloresearch init myproject          # 1. scaffold a project
+# 2. put your data file in myproject/data/ and fill in myproject/forecast.yaml
+soloresearch run myproject           # 3. data-quality checks + stage the panel
+cd myproject/autoresearch
+gemini                               # 4. or `claude`
+```
+
+Then give the agent this prompt:
+
+> Read GEMINI.md and begin the autonomous forecasting research loop.
+> Iterate on solution.py until RMSSE plateaus.
+
+That is the whole flow. Stage 1 (`run`) is automatic. Stage 2 is an agent
+working in the project, exactly as the original research loop did.
+
+---
+
+## How it works
+
+### Stage 1 - data quality (automatic)
+
+`soloresearch run` reads your `forecast.yaml`, loads the data, and runs a
+two-part assessment on every series:
+
+- **Structural** - parses timestamps, sorts, de-duplicates, fills calendar gaps,
+  and infers the target profile from the actual values. Verdict: Clean /
+  Acceptable / Deficient.
+- **Forecastability** - gates on the three things no model can fix: too little
+  history, a constant/flat series, or pure white noise. Verdict: Forecastable /
+  Not Forecastable.
+
+It also characterises each series (trend, seasonality, demand class) and detects
+four kinds of regime change (level, trend, variance, seasonality). The headline
+is **Forecast-Ready %**: the share of series that are both non-Deficient and
+Forecastable.
+
+Reports are written to `myproject/outputs/` as Excel (detailed), HTML (summary),
+and JSON (machine-readable). A cleaned panel is staged for stage 2.
+
+If too little of the data is forecastable, it stops here and tells you why.
+
+### Stage 2 - agent-driven model search
+
+The clean panel becomes a research problem. A coding agent, following the
+`GEMINI.md` / `CLAUDE.md` instructions in the project, repeatedly:
+
+1. reads the current best score,
+2. edits `solution.py` (one hypothesis at a time),
+3. runs `python run.py` to score it against a leakage-safe RMSSE judge that
+   holds out the last `horizon` periods of each series,
+4. keeps the change if the score improved, reverts it otherwise,
+5. repeats until the score plateaus.
+
+Every attempt is snapshotted and logged to `autoresearch/runs/`, so the whole
+search is auditable. The judge only ever shows `predict()` the training history;
+the holdout is hidden, and anti-leakage rules are enforced in the instructions.
+
+---
+
+## forecast.yaml
+
+```yaml
+file: sales.parquet    # data file inside data/  (.parquet or .csv)
+time: date             # timestamp column
+target: target         # column to forecast
+entity: series_id      # column identifying each series (omit if single series)
+partitions: []         # extra grouping columns (optional)
+horizon: 6             # periods ahead to forecast and hold out for validation
+timestep: M            # Y / Q / M / W / D / H
+metric: smape          # reporting metric
+```
+
+Only `file`, `time`, and `target` are strictly required; the rest are inferred
+when omitted, but declaring them is more reliable.
+
+---
+
+## What a project looks like
+
+```
+myproject/
+  data/              your input file
+  forecast.yaml      your config
+  outputs/           DQ reports (Excel / HTML / JSON) + staged panel
+  autoresearch/      the research harness the agent drives
+    solution.py        the model file the agent evolves
+    run.py             scores the current solution
+    GEMINI.md          agent instructions
+    runs/              every attempt, snapshotted and scored
+```
+
+---
+
+## Scope and honest notes
+
+- This ships a **method**, not a guaranteed number. The M5 result (0.807 to
+  0.542) is a documented demonstration of the loop; your dataset, metric, and
+  agent will produce their own result.
+- Stage 2 is **agent-driven** by design: an external coding agent operates the
+  harness by following the prompt, which is what makes the search auditable and
+  reproducible as a process. It is not a black-box API call.
+- The search is **single-track** (one solution improved along one path). A
+  population-based version with an explicit trust layer is a separate project.
+
+---
+
+## License
+
+MIT

soloresearch-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "soloresearch"
+version = "0.1.1"
+description = "Autonomous single-track forecasting research: data-quality gating plus an agent-driven model search."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Shanti Swarup Nayak", email = "shantiswarup.nayak@sigmoidanalytics.com" }]
+dependencies = [
+    "numpy>=1.23", "pandas>=1.5", "pyarrow>=10.0", "scipy>=1.9",
+    "statsmodels>=0.14", "ruptures>=1.1.7", "openpyxl>=3.1", "pyyaml>=6.0",
+]
+
+[project.scripts]
+soloresearch = "soloresearch.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/shantiswarup2/soloresearch"
+Repository = "https://github.com/shantiswarup2/soloresearch"
+
+[tool.hatch.build.targets.wheel]
+packages = ["soloresearch"]
+artifacts = ["*.md"]

soloresearch-0.1.1/soloresearch/autoresearch/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md - autonomous forecasting research
+
+You are running an autonomous forecasting research loop. Drive the
+validation **RMSSE** as low as possible by iterating on ONE file:
+`solution.py`. The dataset is whatever clean panel the data-quality stage
+produced - it is not tied to any one domain.
+
+## This is the ML phase (hard constraint)
+Every solution MUST be built around a trained machine-learning model that
+learns from features. Hand-built statistical rules - moving averages,
+seasonal-naive, multiplying by fixed factors, manual weekday adjustments -
+are NOT valid solutions on their own; they may appear ONLY as a fallback for
+series too short or too sparse to train. The seasonal-naive starting file is
+a placeholder to beat, not a thing to tune: your FIRST iteration must replace
+it with a trained model.
+
+WHICH model is yours to discover by measuring - try a model family, see if it
+lowers RMSSE, keep it if it does. Whatever you choose, use only libraries that
+are already installed in the run environment; if an import fails, that library
+is unavailable - switch to one that is present rather than trying to install
+it. Improvements must come from the model (its features, target transform,
+loss, hyperparameters, or per-group training), each justified by a measured
+drop in RMSSE.
+
+## What the data is
+`run.py` loads a clean long panel (`series_id, t, target`), holds out the
+LAST `horizon` periods of each series as validation, and scores your
+forecast of that holdout with RMSSE (scale-free per-series error, averaged).
+`predict()` only ever sees TRAIN history; the holdout is hidden.
+
+## The contract (do NOT change)
+```
+predict(train_panel, series_ids, horizon) -> np.ndarray  # (n_series, horizon)
+```
+Rows in `series_ids` order. You edit ONLY `solution.py`. `eval.py`,
+`run.py`, `logger.py` are fixed - never edit them.
+
+## The loop (repeat on your own; do not stop to ask between runs)
+1. Read `runs/log.jsonl`. Find the best `overall` RMSSE so far.
+2. Read the current `solution.py`.
+3. Form ONE hypothesis. Make ONE change that tests it. Small, reviewable diff.
+4. Run:  `python run.py <short_name> "<what you changed and why>"`
+5. Read the printed RMSSE.
+   - Lower than best -> keep it.
+   - Not lower -> revert `solution.py` to the best snapshot in
+     `runs/solutions/` and try a different idea.
+6. Go back to step 1.
+
+## Stop only when
+- 20 runs in a row fail to beat the best, OR
+- you judge the score has plateaued near the achievable floor.
+Then write a short summary: what worked, what didn't, and why.
+
+## Discover, do not assume
+- Start from the baseline (seasonal-naive). Do not jump to a known recipe.
+- Try the cheapest idea that could move the metric before any complex one.
+- A change is "better" ONLY if it lowers validation RMSSE. Nothing else counts.
+- Every choice (features, model, loss, hyperparameters) must be justified by a
+  result YOU measured and logged in this loop. No recipes recalled from
+  memory; no web search; no external solutions or papers.
+- Keep a running `runs/feature_journal.md`: one line per idea, marked KEPT /
+  DROPPED / UNTESTED-IDEA. Check it before proposing a feature so you do not
+  repeat a dead end.
+
+## Hard rules (breaking these invalidates results)
+- Use ONLY `train_panel` passed to `predict()`. Never read the holdout, the
+  original files, or any other source.
+- Lag/rolling features must be shift-then-roll: no row may see its own day or
+  any future day.
+- If you forecast recursively, your own predictions feed the next step's
+  lags - never real future values.
+- Output shape exactly (len(series_ids), horizon), rows in series_ids order.
+- Forecasts are non-negative unless the data is genuinely signed.
+
+## Memory (large panels can crash the machine)
+- Read only the columns you need; downcast to float32 / category.
+- Work per group (per series, or per partition) when models get heavy:
+  train + predict one group, write its rows, then `del` large locals and
+  `gc.collect()` before the next.
+- If a run dies on memory, the next experiment must shrink footprint, not grow it.
+
+## Environment
+Run Python in the env where `python run.py baseline` worked. The wrapper
+stages the dataset at `data/clean_panel.parquet` (the default `run.py` reads);
+override with `--panel PATH --horizon N` if needed.

soloresearch-0.1.1/soloresearch/autoresearch/GEMINI.md

@@ -0,0 +1,85 @@
+# GEMINI.md - autonomous forecasting research
+
+You are running an autonomous forecasting research loop. Drive the
+validation **RMSSE** as low as possible by iterating on ONE file:
+`solution.py`. The dataset is whatever clean panel the data-quality stage
+produced - it is not tied to any one domain.
+
+## This is the ML phase (hard constraint)
+Every solution MUST be built around a trained machine-learning model that
+learns from features. Hand-built statistical rules - moving averages,
+seasonal-naive, multiplying by fixed factors, manual weekday adjustments -
+are NOT valid solutions on their own; they may appear ONLY as a fallback for
+series too short or too sparse to train. The seasonal-naive starting file is
+a placeholder to beat, not a thing to tune: your FIRST iteration must replace
+it with a trained model.
+
+WHICH model is yours to discover by measuring - try a model family, see if it
+lowers RMSSE, keep it if it does. Whatever you choose, use only libraries that
+are already installed in the run environment; if an import fails, that library
+is unavailable - switch to one that is present rather than trying to install
+it. Improvements must come from the model (its features, target transform,
+loss, hyperparameters, or per-group training), each justified by a measured
+drop in RMSSE.
+
+## What the data is
+`run.py` loads a clean long panel (`series_id, t, target`), holds out the
+LAST `horizon` periods of each series as validation, and scores your
+forecast of that holdout with RMSSE (scale-free per-series error, averaged).
+`predict()` only ever sees TRAIN history; the holdout is hidden.
+
+## The contract (do NOT change)
+```
+predict(train_panel, series_ids, horizon) -> np.ndarray  # (n_series, horizon)
+```
+Rows in `series_ids` order. You edit ONLY `solution.py`. `eval.py`,
+`run.py`, `logger.py` are fixed - never edit them.
+
+## The loop (repeat on your own; do not stop to ask between runs)
+1. Read `runs/log.jsonl`. Find the best `overall` RMSSE so far.
+2. Read the current `solution.py`.
+3. Form ONE hypothesis. Make ONE change that tests it. Small, reviewable diff.
+4. Run:  `python run.py <short_name> "<what you changed and why>"`
+5. Read the printed RMSSE.
+   - Lower than best -> keep it.
+   - Not lower -> revert `solution.py` to the best snapshot in
+     `runs/solutions/` and try a different idea.
+6. Go back to step 1.
+
+## Stop only when
+- 20 runs in a row fail to beat the best, OR
+- you judge the score has plateaued near the achievable floor.
+Then write a short summary: what worked, what didn't, and why.
+
+## Discover, do not assume
+- Start from the baseline (seasonal-naive). Do not jump to a known recipe.
+- Try the cheapest idea that could move the metric before any complex one.
+- A change is "better" ONLY if it lowers validation RMSSE. Nothing else counts.
+- Every choice (features, model, loss, hyperparameters) must be justified by a
+  result YOU measured and logged in this loop. No recipes recalled from
+  memory; no web search; no external solutions or papers.
+- Keep a running `runs/feature_journal.md`: one line per idea, marked KEPT /
+  DROPPED / UNTESTED-IDEA. Check it before proposing a feature so you do not
+  repeat a dead end.
+
+## Hard rules (breaking these invalidates results)
+- Use ONLY `train_panel` passed to `predict()`. Never read the holdout, the
+  original files, or any other source.
+- Lag/rolling features must be shift-then-roll: no row may see its own day or
+  any future day.
+- If you forecast recursively, your own predictions feed the next step's
+  lags - never real future values.
+- Output shape exactly (len(series_ids), horizon), rows in series_ids order.
+- Forecasts are non-negative unless the data is genuinely signed.
+
+## Memory (large panels can crash the machine)
+- Read only the columns you need; downcast to float32 / category.
+- Work per group (per series, or per partition) when models get heavy:
+  train + predict one group, write its rows, then `del` large locals and
+  `gc.collect()` before the next.
+- If a run dies on memory, the next experiment must shrink footprint, not grow it.
+
+## Environment
+Run Python in the env where `python run.py baseline` worked. The wrapper
+stages the dataset at `data/clean_panel.parquet` (the default `run.py` reads);
+override with `--panel PATH --horizon N` if needed.