Metadata-Version: 2.4
Name: libby
Version: 0.1.0
Summary: Radiocarbon calibration tool with LLM-powered narrative explanations, Bayesian modelling, and GIS curve selection
Author: Marcus Quinn
License: MIT
Project-URL: Homepage, https://github.com/mabo-du/libby
Project-URL: Repository, https://github.com/mabo-du/libby
Project-URL: Documentation, https://github.com/mabo-du/libby#readme
Keywords: radiocarbon,calibration,archaeology,bayesian,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: iosacal>=0.6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: aiosqlite>=0.20
Requires-Dist: numpy>=2.0
Requires-Dist: httpx>=0.28
Requires-Dist: openai>=1.0.0
Requires-Dist: reportlab>=4.5.1
Requires-Dist: matplotlib>=3.5.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.7; extra == "dev"
Requires-Dist: httpx>=0.28; extra == "dev"
Dynamic: license-file

# Libby

<p align="center">
  <img src="assets/LibbyLogo.png" alt="Libby logo" width="200"/>
</p>

**Modern radiocarbon calibration with LLM-powered narrative explanations, Bayesian modelling, and GIS curve selection.**

Libby is a full-featured web application for calibrating radiocarbon dates with
a modern Svelte 5 frontend, a Python/FastAPI backend, and unique features —
including plain-English narrative explanations of calibration results, summed
probability distributions, and a lat/lng-based curve selector for IntCal vs
SHCal vs mixed curves.

---

## Features

- **Single-date calibration** — BP age + σ → calibrated PDF chart with 1σ/2σ HPD ranges
- **Batch calibration** — paste multiple dates at once, view SPD chart and results table
- **LLM-powered narratives** — plain-English explanation of every calibration result
- **Multi-language support** — narratives in 12 languages (English, French, German, Spanish, Italian, Portuguese, Japanese, Arabic, Chinese, Dutch, Swedish, Polish)
- **Multi-provider LLM support** — Nvidia NIM (free tier, 40 req/min), Anthropic Claude
- **Bayesian Phase & Sequence modelling** — Metropolis-Hastings MCMC with Agreement Index
- **GIS curve selector** — Leaflet map pin-drop auto-suggests IntCal20/SHCal20/mixed curve
- **Project management** — group dates by site, context, or research project
- **Summed Probability Distribution (SPD)** — combined probability across all dates
- **Taphonomic warnings** — material-aware notes (old-wood effect, collagen preservation, marine reservoir effect, etc.)
- **Export:** formatted PDF report, CSV, OxCal CQL2 script, publication-ready text
- **Calibration curves:** IntCal20, SHCal20, Marine20 (CC BY 4.0)
- **GIS map** — OpenStreetMap with zone overlays (journal-safe, no Google Maps)

---

## Tech Stack

| Layer | Technology |
|---|---|
| **Backend** | Python 3.13+ / FastAPI |
| **Frontend** | Svelte 5 / SvelteKit / Chart.js / Leaflet |
| **Calibration engine** | iosacal + direct IntCal curve data |
| **Bayesian MCMC** | Pure numpy/scipy Metropolis-Hastings |
| **LLM** | Nvidia NIM (OpenAI-compatible) or Anthropic Claude |
| **Database** | SQLite (aiosqlite) |
| **PDF** | ReportLab |
| **Charts** | Chart.js (frontend), matplotlib (PDF reports) |

---

## Quick Start

```bash
# Clone
git clone https://github.com/mabo-du/libby.git
cd libby

# Backend
uv sync
uv run uvicorn libby.main:app --reload --port 50001

# Frontend (separate terminal)
cd frontend
npm install
npm run dev -- --port 50002
```

Open **http://localhost:50002** in your browser.

### LLM Narratives (Optional)

Libby works without any LLM — a deterministic fallback generates coherent
narratives from the numbers alone. For AI-powered narratives, set:

```bash
# Nvidia NIM (free — sign up at build.nvidia.com)
echo 'LIBBY_NIM_API_KEY=nvapi-...' > .env

# Or Anthropic Claude
# echo 'LIBBY_LLM_PROVIDER=anthropic' >> .env
# echo 'LIBBY_ANTHROPIC_API_KEY=sk-ant-...' >> .env
```

---

## Usage

### Single Calibration
Enter a BP age and standard deviation, select a curve, click **Calibrate**.
View the probability distribution chart, 1σ/2σ ranges, and plain-English narrative.

### Batch Calibration
Click **Batch** in the nav, paste dates as CSV-like text, calibrate all at once
with Summed Probability Distribution.

### GIS Curve Selector
On the calibration page, expand **Curve selector by site location**.
Click anywhere on the map to place a pin — Libby suggests the correct curve
based on latitude and explains the reasoning.

### Projects
Create projects to group dates by site. Each project shows:
- All dates with full calibration data
- Summed Probability Distribution chart
- Project summary narrative
- Bayesian modelling (Phase or Sequence)
- PDF report, OxCal export, CSV export

### Bayesian Modelling
With 2+ dates in a project:
- **Phase model** — estimates start/end boundaries for an activity period
- **Sequence model** — applies stratigraphic ordering constraints
- Agreement Index (A) per date, following OxCal's convention (A ≥ 60 = acceptable)

### Lab Report Import
Navigate to **Import**, paste CSV/TSV from your radiocarbon lab.
Auto-detects columns, handles "3000±30" embedded sigma format,
previews all rows, then batch-calibrates with one click.

---

## Project Structure

```
libby/
├── src/libby/           # Python backend
│   ├── main.py          # FastAPI app factory and routes
│   ├── calibration.py   # iosacal integration
│   ├── bayesian.py      # MCMC Phase/Sequence models
│   ├── narrative.py     # LLM + fallback narrative generation
│   ├── models.py        # Pydantic schemas
│   ├── database.py      # SQLite (projects, calibrations)
│   ├── gis.py           # Curve suggestion by latitude
│   ├── spd.py           # Summed Probability Distribution
│   ├── export.py        # CSV/text formatters
│   ├── oxcal.py         # OxCal CQL2 script export
│   ├── report.py        # PDF report generation
│   ├── importer.py      # Lab report CSV parser
│   └── providers/       # LLM providers (NIM, Anthropic)
├── frontend/src/        # Svelte 5 frontend
│   ├── routes/          # Pages (/, /batch, /import, /projects)
│   └── lib/             # Components (form, chart, map, etc.)
├── tests/               # pytest test suite
└── notebooks/           # Research notebooks
```

---

## Calibration Curves

This tool uses the internationally ratified calibration curves:
- **IntCal20** — Northern Hemisphere terrestrial (Reimer et al. 2020)
- **SHCal20** — Southern Hemisphere terrestrial (Hogg et al. 2020)
- **Marine20** — Global marine (Heaton et al. 2020)

All curves are CC BY 4.0 licensed. Calibration engine: iosacal (GPLv3).

---

## Licence

MIT License. See [LICENSE](LICENSE) for details.

## Citation

If you use Libby in published research, please cite:
- IntCal20: Reimer et al. 2020, *Radiocarbon* 62(4)
- SHCal20: Hogg et al. 2020, *Radiocarbon* 62(4)
- Marine20: Heaton et al. 2020, *Radiocarbon* 62(4)
