Waqt API v1

A Makkah-anchored, Maghrib-to-Maghrib civil time and Hijri calendar API — a stable, versioned, language-independent HTTP contract. You do not need to read any Python here to integrate it; start with docs/API.md.

core/                          — Sprint 11: `waqt-core`, the independently installable computation layer
  waqt_core/                     (import name waqt_core; deps: ephem, timezonefinder — no FastAPI)
    core.py, solar.py, hijri.py, semantics.py, timescale.py, timezone_provider.py, calendar_interop.py
    calendar_providers/           — Umm al-Qura, local observation, registry
    scheduling/                   — Sprint 6: windows, deadlines, event-relative rules
    institutional/                — Sprint 7: week, fiscal year, academic year, calendar profiles
  tests/                         — standalone conformance vs all vector files, shim-identity, clean-install, solar regressions
waqt/                          — `waqt-api` (repo root pyproject.toml): the HTTP layer only
  __init__.py                    — aliases waqt.core/.hijri/.scheduling/... to the SAME objects as waqt_core.*
  api/                           — Waqt API v1: common.py, providers.py and one *_endpoint.py per endpoint group
local/                         — Sprint 10: `waqt-local`, embeddable no-server library (depends on waqt-core)
sdks/                          — Sprint 9/10: remote HTTP clients (Python, JS) + shared conformance vectors
consumers/js/                  — independent zero-dependency Node consumer of the shared vector files
independent-astronomy/         — Sprint 9-12: Level-B (independent_solar) and Level-A (level_a, VSOP87) references,
                                  comparison matrices, threshold-day truth scan, multi-year evidence (Sprint 12)
apps/                          — Sprint 12: reference applications, the first user-facing consumers of Waqt
  cli/                            — waqt-cli: offline command-line app on waqt-local
  web/                             — waqt-web: static, dependency-free page consuming the HTTP API
  api-consumer/                    — stdlib-only HTTP client, demonstrates consuming the API with no Waqt import
tests/                         — waqt.api suite + vectors/ (portable conformance vectors + their generators)
docs/
  API.md, TIME-MODEL.md, CALENDARS.md, SEMANTICS.md, SCHEDULING.md, INSTITUTIONAL.md, CALENDAR-INTEROP.md,
  SDK.md, LOCAL.md, RELEASING.md, VERSIONING.md, ACCURACY-LEVEL-REVIEW.md
  ASTRONOMY.md                   — solar engine, accuracy levels (measured), elevation, DeltaT, edge cases
  ASTRONOMY-ENGINE-EVALUATION.md — Sprint 11: NOAA vs Level B vs Level A, the bugs found, the production-engine decision
  PACKAGING.md                   — Sprint 11: package architecture, shim, install, gating tests
  VERSIONING.md                  — Sprint 12: how waqt-core version / engine revision / API version / SDK
                                    version / conformance-vector-set version relate
  ACCURACY-LEVEL-REVIEW.md       — Sprint 12: promotion criteria for Level A, evidence so far, decision record
SCOPE.md, SPRINT-*-REPORT.md     — build history and honest limitations

## Quickstart

```bash
pip install -r requirements.txt      # editable installs of core/, ., local/ + dev tools
uvicorn waqt.api:app --reload --port 8000
curl "http://localhost:8000/v1/waqt?lat=9.0192&lon=38.7525"

Or open http://localhost:8000/docs for interactive testing (Swagger UI, generated automatically from the same code that serves requests).

The seven endpoints

Full request/response schemas, every error code, units, and versioning policy: docs/API.md and docs/VERSIONING.md.

Scheduling (Sprint 6)

Waqt provides temporal facts, not religious rulings — see docs/SCHEDULING.md.

Institutional calendars (Sprint 7)

No universal Islamic fiscal or school calendar is baked in — see docs/INSTITUTIONAL.md.

SDKs, local computation, and independent astronomy (Sprint 9-10)

• Official SDKs — sdks/python/waqt_client and sdks/js/waqt-client, remote HTTP clients with full read coverage plus typed request builders for every POST endpoint. See docs/SDK.md and each package's CHANGELOG.md. Packaging/versioning/release procedure: docs/RELEASING.md.
• Local computation library — local/waqt_local, a no-HTTP, in-process Python package computing the same facts the server does, straight from waqt.core/waqt.scheduling/waqt.institutional. See docs/LOCAL.md.
• Independent astronomy — independent-astronomy/independent_solar (a from-scratch Level-B solar engine) and independent-astronomy/level_a (a VSOP87-based Level-A reference, Sprint 10, used to measure both Level-B engines). See docs/INDEPENDENT-ASTRONOMY.md and docs/ASTRONOMY.md's "Accuracy levels" section. Sprint 12 extended the comparison across 7 years; see docs/ACCURACY-LEVEL-REVIEW.md.
• Reference applications (Sprint 12) — apps/cli (offline CLI on waqt-local), apps/web (a static page on the HTTP API), and apps/api-consumer (a stdlib-only HTTP client proving the API needs no Waqt package to use). None compute Waqt semantics themselves — each has a structural test enforcing that. See each package's own README.md.

Formal conformance and an independent implementation (Sprint 15)

conformance/ holds a portable conformance specification (protocol, 63 requirement IDs, accuracy bands), a language-neutral harness, 600+ vectors (DE421-oracle, closed-form, metamorphic, provider-failure), and a clean-room second implementation in Node.js that shares no code with waqt-core. Run conformance/run.sh; read conformance/DISAGREEMENTS.md for what it found and conformance/spec/OPEN-QUESTIONS.md for where the written specification is ambiguous. Report: SPRINT-15-REPORT.md.

Verify

python3 -m pytest tests/ -v

Sprint 7 adds 86 tests (institutional-layer unit tests, HTTP surface, 22 portable calendar-table vectors, and the independent JS consumer, run from pytest when Node is installed) on top of Sprint 6's 320. Sprint 6 added 200+ tests (scheduling engine, HTTP, 116 portable vectors, and the independent JS consumer). Sprint 5's baseline was 106 tests: the full geographic matrix, elevation, the date-line fix, ΔT, all five calendar provider categories (including 4/4 historical Umm al-Qura dates), the complete v1 HTTP contract, and Sprint 5's formal temporal semantics — the exact-Maghrib boundary rule, same-day-only comparison enforcement, undefined-event handling, and 10 portable conformance vectors an independent implementation in another language could check itself against.

Read SCOPE.md and the SPRINT-*-REPORT.md files before using this for anything beyond development and review — especially before trusting any Hijri date for a religious purpose.