Python quickstart

The Python package is the scientific compiler and verification substrate. The 0.1.0 release is available from PyPI, while this guide also covers repository-only workflows and current APIs.

Prerequisites and installation

For the public release, use Python 3.11 or newer and install lunartrace==0.1.0 from PyPI. For repository-only workflows, use an authorized checkout of the private KritP/lunartrace repository and record the exact source revision used for research.

python -m pip install lunartrace==0.1.0
python -m lunartrace --help

For source development, use the repository’s locked uv workflow:

git rev-parse HEAD
uv sync --frozen
uv run python -m lunartrace --help

uv sync --frozen installs the package and locked development environment without silently updating the lock. An unauthenticated reader of this manual does not automatically have repository access.

Inspect the public Python surface

from lunartrace import FRONTIERS, StudyProtocol

protocol = StudyProtocol()
for definition in FRONTIERS:
    print(definition.frontier_id)
    print([objective.value for objective in definition.objectives])

The default protocol is the fixed Moon/LRO/LROC/CDRNAC4 point-query family. It is not a generic arbitrary-archive query builder. See Event-conditioned comparison methodology for its actual objective definitions.

Recover and export the historical example

Run from the repository root:

from pathlib import Path

from lunartrace import historical_change6
from lunartrace.bundles import export_study

study, dependencies = historical_change6(Path("."))
manifest = export_study(
    study,
    Path(".build/my-change6-record"),
    dependencies,
)
print(study.kind)
print(manifest.study_artifact.content_hash)

historical_change6 returns both the historical Study and the retained dependency payloads. Do not discard those dependencies when creating a verifiable bundle.

This recovers the hash-locked historical record. It does not reconstruct the original observations or re-execute their screening.

Then inspect and verify:

uv run lunartrace inspect .build/my-change6-record
uv run lunartrace verify .build/my-change6-record
uv run lunartrace reproduce .build/my-change6-record

The historical replay status should be interpreted as unavailable from missing original rows, not as permission to invent them. Verification can still inspect the retained contracts, hashes, dependencies, and consistency.

Continue from the web Lab

Download a draft or captured investigation from Reproduce & export, then run:

uv run python tools/reproduce_lab.py lunartrace-lab-export.json

The default operation is offline metadata-byte audit. It does not query ODE, verify remote image pixels, or admit scientific claims.

A new network acquisition is explicit:

uv run python tools/reproduce_lab.py lunartrace-lab-export.json --acquire .build/lab-capture

Only point-query intent is accepted by this bridge. A surrounding-box discovery requires a separate scientific decision; it is not silently converted into a point.

See From exploration to reproducible computation before requesting canonical compilation.

Where to go next

Use Python API reference for exact callable objects, Command-line reference for the installed command plane, and Artifact identity and evidence bundles for bundle identity. Read Limitations and non-claims before describing any successful software operation as scientific validation.