Metadata-Version: 2.4
Name: middle-passage
Version: 0.1.1
Summary: Phase 0 protection-first memorial GIS scaffold: reproducible zones, explicit limits, no remains claims
Author: Middle Passage Forensic Recovery Project
License-Expression: CC-BY-4.0
Project-URL: Homepage, https://github.com/Yufok1/middle-passage
Project-URL: Repository, https://github.com/Yufok1/middle-passage
Project-URL: Issues, https://github.com/Yufok1/middle-passage/issues
Project-URL: Documentation, https://github.com/Yufok1/middle-passage/tree/main/docs
Keywords: middle-passage,gis,memorial,maritime-archaeology,humanitarian,historical-research
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# middle-passage

> "The ocean kept receipts. We are learning to read them."

**PyPI:** [pypi.org/project/middle-passage](https://pypi.org/project/middle-passage/)

Open-source toolkit for the Middle Passage Forensic Recovery Project: a **protection-first**
Phase 0 scaffold for voyage records, **explicit** modeling limits, and memorial GIS outputs.

The word **forensic** in the project name refers to **recovery and accountability framing**,
not to a court-certified or validated forensic analysis product. This package is **Pre-Alpha**
research software.

## What you get today (real capabilities)

These are **implemented and tested** behaviors you can rely on:

- **CSV → structured voyages** with flexible column aliases (`middle_passage.voyages.loader`).
- **Filtering** in Python or via CLI: route match, mortality threshold, jettison-only, year range.
- **Survey-priority zones** as centers, radii, and assumption strings derived from **documented**
  Phase 0 placeholders (not from real bathymetry or ocean reanalysis).
- **GeoJSON export** with protection language, sensitivity fields, **package version**,
  **validation status**, **what is included vs not included**, and limitation bullets
  (`metadata` on every `FeatureCollection`).
- **stdlib-first**: no mandatory Shapely/pyproj/geojson dependency for the core pipeline.

Machine-readable capability and boundary lists (same strings as GeoJSON metadata):

```bash
middle-passage inspect-sources --json
```

## What is not in this package (yet)

Stated loudly so nobody mistakes Phase 0 for finished science:

- No GEBCO/NOAA (or other) **tile bathymetry**—depths are **heuristic bands** for pipeline tests.
- No **measured or hindcast currents**—bearing and speed are **named-corridor placeholders**.
- No **validated** deposition, dispersal, or search physics for site identification.
- **No** identification of human remains and **no** “proof” language in the model layer—only
  memorial / protection-first framing in outputs.

**License:** Creative Commons CC BY 4.0  
**Purpose:** Humanitarian. Scientific. Memorial.  
**Status:** Phase 0 scaffold with synthetic-safe defaults.

## Real vs placeholder (quick reference)

| Piece | In this package |
|------|-----------------|
| CSV loading, filtering, CLI, GeoJSON structure | Implemented for reproducible pipelines |
| Bathymetry | **Heuristic depth bands**, not GEBCO/NOAA tiles — see `middle_passage/bathymetry/gebco.py` |
| Currents | **Constant bearing + speed** from named corridors — not a hindcast or reanalysis |
| Descent / scatter | **Illustrative parameters** to exercise the pipeline — not validated settling physics |
| Geometry | **Sphere-based offsets and rings** (stdlib + math) |

## Principles

- People, not cargo.
- Ancestors, not artifacts.
- Probability zones, not treasure maps.
- Public methods, careful precision.
- Protection before spectacle.

## Install

```bash
pip install middle-passage
```

Install a specific branch from GitHub (optional):

```bash
pip install "middle-passage @ git+https://github.com/Yufok1/middle-passage.git@main"
```

Local development:

```bash
pip install -e ".[dev]"
```

## CLI

Synthetic-safe sample GeoJSON:

```bash
middle-passage sample --output sample.geojson
```

Survey-priority zones from a voyage CSV:

```bash
middle-passage model-deposits --voyages voyages.csv --output zones.geojson
```

Optional **voyage filters** (CSV rows only; `--corridor` sets the **placeholder current bearing**):

```bash
middle-passage model-deposits --voyages voyages.csv --output zones.geojson \
  --filter-route doldrums_zone --min-mortality 0.1 --jettison-only \
  --year-from 1700 --year-to 1800
```

Ethics, version, capabilities, and limits:

```bash
middle-passage inspect-sources
```

If no voyage file is provided, the CLI uses a clearly marked synthetic sample for development only.

## Data Sensitivity

Labels supported on domain objects:

- `public` — safe public metadata or generalized zones
- `generalized` — public map data with reduced precision
- `restricted` — high-precision working data for qualified review
- `do_not_publish` — sensitive records or coordinates that should not be released

Precise burial-site candidates should not be published casually. Release policy must follow
descendant/community review, legal review, and protection risk assessment.

## Release

- **Published builds:** [middle-passage on PyPI](https://pypi.org/project/middle-passage/).
- **Manual upload path** (when GitHub Actions / Trusted Publishing are unavailable): see
  `docs/PYPI_RELEASE.md` for `python -m build` and `twine upload`.
