Metadata-Version: 2.4
Name: lunartrace
Version: 0.1.1
Summary: Reproducible event-conditioned lunar observation studies
Keywords: lunar-science,planetary-science,astronomy,remote-sensing,reproducibility,NASA-PDS
Author: Krit Promsanuwong
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pydantic>=2,<3
Requires-Dist: httpx>=0.28.1,<0.29
Requires-Python: >=3.11
Project-URL: Homepage, https://lunartrace.org/
Project-URL: Documentation, https://lunartrace.org/manual/
Description-Content-Type: text/markdown

# LunarTrace

**Reproducible event-conditioned lunar observation studies.**

LunarTrace is research software for constructing, inspecting, and reproducing event-conditioned lunar observation studies. The Python package is the canonical scientific-computation surface; the interactive web Lab provides spatial discovery, source-backed observation inspection, exploratory comparison analysis, and a path back to reproducible Python workflows.

- **Research Lab:** https://lunartrace.org/
- **Scientific manual:** https://lunartrace.org/manual/

## Install

The 0.1.1 release is available on [PyPI](https://pypi.org/project/lunartrace/0.1.1/). Install it with:

```bash
python -m pip install lunartrace==0.1.1
```

For source development, use the repository's locked environment:

```bash
uv sync --frozen
```

The Python distribution contains the scientific package and CLI. The React/Cesium web Lab and deployed Cloudflare Worker are separate product surfaces and are not bundled into the wheel.

## Python surface

The public package root exposes the scientific entry points used to define and verify studies:

```python
from lunartrace import StudyProtocol

protocol = StudyProtocol()
print(protocol.protocol_id)
print([frontier.frontier_id for frontier in protocol.frontiers])
```

This prints the protocol identity and its four declared screening frontiers. The package API also exposes the compiler, event and evidence models, verification, and the retained historical benchmark helpers.

Python owns canonical scientific semantics. Browser-side exploration is deliberately provisional and must not silently become an admitted scientific Study.

## CLI

```bash
lunartrace --help
lunartrace inspect <artifact>
lunartrace verify <study-dir>
lunartrace reproduce <study-dir>
lunartrace benchmark --repository-root <source-repository>
```

The `benchmark` command requires the source repository's retained research basis; those research files are not bundled into the wheel. See the scientific manual for exact command semantics, artifacts, and proof boundaries.

## Scientific model

LunarTrace treats an event-conditioned study as a traceable sequence:

```text
event / reference
→ bounded source query
→ normalized observations
→ strict PRE / POST partition
→ candidate comparisons
→ explicit multi-objective screening
→ evidence + provenance
→ scientific standing
```

The package distinguishes source custody, integrity, scientific computation, and scientific standing. In particular:

```text
ContextBasis != StudyBasis
Selected != Included
Exploration != Admission
Integrity != Scientific truth
Archive miss != physical absence
```

## Qualified Chang'e 6 historical exemplar

The retained historical exemplar preserves these aggregate facts:

```text
PRE observations          14
POST observations         39
evaluable temporal pairs 546
V1 / V2 / V3 / V4         7 / 26 / 71 / 102
```

The historical observation and pair rows are unavailable. Retained browse imagery remains `REFERENCE_ONLY` and `UNALIGNED`.

LunarTrace does **not** claim image registration, photometric comparability, change detection, causal attribution, or physical absence from an archive miss.

## Reproducibility

The package supports content-addressed artifacts, source receipts, explicit query closure, verification, replay-oriented workflows, and bounded live Lunar ODE acquisition. The web Lab can export exploratory intent and captured source receipts for offline audit and deliberate continuation in Python without promoting browser exploration to canonical admission.

## Status

`0.1.1` is the current public Python release. It is alpha research software: interfaces are intentionally conservative, but compatibility is not yet promised across all future minor releases.

Before relying on a result, read the methodology, limitations, evidence-standing, and reproducibility sections of the scientific manual.

## Citation

Krit Promsanuwong. *LunarTrace* 0.1.1. Software release. See `CITATION.cff` for machine-readable citation metadata.
