Metadata-Version: 2.5
Name: theta-empirical-lab
Version: 0.1.2
Summary: theta-empirical-lab: extensible plugin-based scientific analysis for Θ-theory
Author: Vasiliy Zdanovskiy
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: jplephem>=2.24
Requires-Dist: numpy>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# theta-empirical-lab

`theta-empirical-lab` is the reusable scientific-analysis application and Code Analysis Server project for Θ-theory. The same name is used for the project directory and the Python distribution published on PyPI; the installed command-line entry point is `theta-lab`.

The root `README.md` is the canonical human-readable overview of the `theta-empirical-lab` project and its plugin contract.

## Project language policy

All project artifacts intended for users or publication must be English-only. This includes the root README, every command `help.md`, every command `info.md`, every `command.json` value, CLI output, error messages, user-facing logs, examples, package metadata, release notes, generated reports, and published documentation. Non-English user-facing text is not permitted in the package.

## CLI architecture standard

The CLI is plugin-based. These rules are normative for the project and for every command added later.

1. `src/theta_empirical_lab/cli.py` is only a dispatcher. It must not contain scientific command implementation logic.
2. All commands live directly under `src/theta_empirical_lab/commands/`.
3. One invocation may select exactly one command. Command-specific arguments belong only to that selected command.
4. The public command name is exactly the name of its direct subdirectory under `commands/`. Directory names are the primary command identifiers.
5. Every direct command subdirectory is a plugin directory (not a Python package) and must contain all of the following files:
   - `command.py` exposing callable `run(argv)`;
   - `command.json` containing discovery metadata;
   - `help.md` containing complete command help;
   - `info.md` containing command information and scientific scope.
6. `command.json` must contain a non-empty `name` and `summary`. Its `name` must exactly equal the command subdirectory name. A mismatch is a fatal registry error.
7. At process startup the dispatcher builds the complete command registry once by scanning all direct subdirectories of `commands/`. Every candidate directory is validated before any command is selected or executed.
8. If any command directory violates this standard, startup fails with an actionable error and non-zero exit status. Invalid plugins are never silently skipped.
9. After the registry has been built successfully, the single command name from the CLI is resolved only against that registry. An unknown command is an error and terminates the process.
10. `theta-lab <command> --help` prints that plugin's `help.md`; `theta-lab <command> --info` prints that plugin's `info.md`.
11. A large command may use additional implementation modules or subpackages inside its own command directory. Those internal files are not separate commands and are never registered independently.
12. Command registration must never be hard-coded as a growing command list in `cli.py` or `command_registry.py`.
13. A command must return a stable non-zero exit status on failure and emit an actionable diagnostic to stderr. Raw tracebacks are reserved for an explicit debug mode.
14. Command behavior must be reproducible from a clean installation of the published wheel.

Required layout:

```text
src/theta_empirical_lab/
  cli.py
  command_registry.py
  commands/
    chirality-cells/
      command.py
      command.json
      help.md
      info.md
      source.py
      ...
    probe-crossings/
      command.py
      command.json
      help.md
      info.md
      ...
    radial-break/
      command.py
      command.json
      help.md
      info.md
      ...
```

## Scientific-data command standard

Scientific commands are responsible for obtaining their own primary input data. A user must not have to manually prepare source files for the normal workflow.

1. Downloads must use identified primary sources. Source URL, access time, byte size, SHA-256, and processing parameters must be retained in output provenance.
2. Large downloads must support continuation. Incomplete files are stored under a temporary `.part` name and resumed from their current byte length when the source supports HTTP byte ranges.
3. If a server ignores a Range request and returns the whole file, the command must safely restart that file from byte zero rather than append incompatible bytes.
4. Network and HTTP failures must be retried with bounded exponential backoff. Retry count and timeout must be configurable or documented.
5. A completed download must not become the canonical cached filename until expected size and SHA-256 validation succeeds. Final promotion must be atomic.
6. A checksum mismatch, unexpected file size, malformed response, exhausted retry budget, or unavailable source is a hard command error and must never silently fall through to calculation.
7. Existing validated cache files may be reused. Existing invalid files must be rejected or replaced explicitly; they must not be trusted because their name matches.
8. Commands querying an online API must validate structural markers before accepting a raw response. For JPL Horizons vector responses this includes a valid data block bounded by `$$SOE` and `$$EOE`.
9. Raw downloaded responses and calculation products must be separable. Original source bytes are never rewritten as processed data.
10. Optional local-path arguments may be supplied for offline reproduction, but they are an override of the default self-fetching workflow, not a prerequisite.
11. Runtime scientific data belong under `./data/<command-name>/` by default. The project-level `data/` directory is runtime output and must not be included in wheel or sdist artifacts.

## Current commands

### `chirality-cells`

Downloads and verifies the pinned official Galaxy Zoo 1 Table 2 catalog, selects the published clean apparent clockwise/anticlockwise sample, and aggregates it in equal-solid-angle observational sky cells. The normal workflow downloads its own source data and stores all inputs and products under `./data/chirality-cells/`. It also self-acquires the pinned Galaxy Zoo mirror-control tables, Yang SDSS DR7 group catalogues, McConnachie Local Group membership, and the Iye S/Z catalogue, then writes normalized physical-group aggregates. Catalogue group membership is observational input; it is not identified with Θ-cell adjacency, and apparent winding is not equated with mechanical rotation or Θ-chirality.

### `probe-crossings`

Downloads JPL Horizons vector data for selected interplanetary probes, archives the raw responses, and determines crossings of requested heliocentric radii. It is intended to compare the same candidate radial boundary across probes that crossed it in different years and directions.

### `radial-break`

Downloads and verifies JPL DE440s and the corresponding DE440 GM kernel, computes the heliocentric ephemeris-minus-rich-Newtonian radial residual for all eight planets using analytic differentiation of SPK Chebyshev coefficients, summarizes per-planet radial amplitudes, and searches for a data-selected radial change point without assigning its location or slopes in advance.

## Reproducibility and release requirements

A release is not complete until all of the following pass:

- formatter, linter, static type checks, and project validation;
- unit and integration tests;
- full startup registry validation for every plugin directory;
- rejection tests for an unknown command and for a malformed plugin;
- wheel and sdist build checks;
- verification that runtime `data/` is absent from wheel and sdist;
- installation of the built wheel into a fresh empty virtual environment;
- dependency resolution from package metadata without relying on the development environment;
- `theta-lab --help` plus every command's `--help` and `--info` from the fresh environment;
- smoke execution of command discovery and exactly-one-command dispatch from the installed package;
- verification that package data include every `command.json`, `help.md`, and `info.md` needed at runtime;
- a real self-fetching execution of a scientific command when its release changes data acquisition or scientific processing;
- publication only after the clean-environment checks pass.

The clean-install test must detect undeclared runtime dependencies. A module being present in the developer environment is not evidence that it is declared correctly in package metadata.

## Primary data sources

### Galaxy Zoo 1 source used by `chirality-cells`

- Galaxy Zoo 1 public data release Table 2, SDSS DR7 spectroscopic sample.
- URL: `https://galaxy-zoo-1.s3.amazonaws.com/GalaxyZoo1_DR_table2.csv.gz`.
- expected size: `20,384,458` bytes.
- SHA-256: `5121e43f502856c9f73e31934a6e7d7282669c3ae065564a31f5d5115f45541d`.

### JPL ephemeris sources used by `radial-break`

- JPL/NAIF `de440s.bsp` — expected size `32,726,016` bytes; SHA-256 `c1c7feeab882263fc493a9d5a5b2ddd71b54826cdf65d8d17a76126b260a49f2`.
- JPL/NAIF `gm_de440.tpc` — expected size `12,406` bytes; SHA-256 `924ddf4fb9ead9fe8a1aa55780bcabde40b09d00065d58226e24b68d8092f140`.

Each command verifies the pinned identity of its primary file inputs before calculation.
