Hercules
Human capital, same discipline as macro
The labor and human development arm of the deluair observatory line. 55 curated WDI series across 7 topics: 19 labor market indicators (employment-to-population, labor force by sector and vulnerability, LFPR and unemployment by gender and youth), 11 education (adult literacy by gender, enrollment primary to tertiary, completion rates, out-of-school rates, government expenditure), 8 health (life expectancy, under-5 and maternal mortality, physicians, stunting, health expenditure), 5 welfare (poverty at $2.15 and national lines, Gini, income shares), 5 gender (LFPR ratio, enrollment parity, women in parliament, adolescent fertility), 5 demographic (population, growth, urban share, dependency ratio, fertility rate), 2 levels (GDP per capita PPP, Human Capital Index). Default port 8011.
What this observatory promises
Human capital, not the whole WDI
55 indicators across 7 topic tags (labor, education, health, welfare, gender, demographic, levels). Enough structure for employment, schooling, welfare, and gender-gap panels without importing Sisyphus macro breadth.
Reproducible by construction
Collectors are versioned code paths, not one-off spreadsheets. Weekly UTC schedule (Sunday 06:00), collection logs, `last_fetched_at` on sources, same SQLite shape as sibling observatories.
API first, analytics honest
Read-only routes for sources, series, country slices, persistence, shock features, comparators, and regression-ready panels. Admin diagnostics behind a key. Built for scripts and papers, not chart galleries.
Companion, not competitor
Sisyphus holds long-run macro and external-sector packs. Hercules holds the employability and welfare slice. Run both on different ports with different database files when you need the full picture.
7 topics, 55 indicators
Covers labor markets (employment, LFPR, unemployment by gender and age, sector composition, vulnerability), education (enrollment primary to tertiary, adult literacy by gender, completion rates, out-of-school rates, government expenditure), health (life expectancy, under-5 and maternal mortality, physicians, stunting, health expenditure), welfare (poverty at $2.15 and national lines, Gini, income shares), gender (LFPR ratio, enrollment parity, women in parliament, adolescent fertility), demographics (population, urban share, dependency ratio, fertility rate), and aggregate levels (GDP per capita PPP, Human Capital Index).
Production surface
FastAPI and Starlette middleware: gzip over a size threshold, optional CORS for explicit origins, security headers, X-Request-ID on every response, optional JSON log lines via LOG_JSON. Readiness runs SELECT 1 against SQLite. Optional GET /metrics exposes hercules_http_* counters and latency histograms.
- Warehouse: WAL SQLite, tuned page cache and mmap, optimize on shutdown.
- Ingestion: one GET per indicator for all countries, 0.45s pacing between indicators, retries on 400/429/5xx.
- OpenAPI: /docs and /redoc on the running service.
4 analytical engines
Human Capital Pipeline
Education-to-employment pipeline efficiency: enrollment rates at primary, secondary, and tertiary levels linked to employment outcomes and labor force participation. Identifies where the pipeline leaks.
Gender Gap Analysis
Gender gap metrics with convergence speed estimates: female-to-male LFPR ratios, school enrollment parity indices, women in parliament, adolescent fertility. Tracks where gaps are closing and where they persist.
Welfare Mobility
Transition matrices and upward mobility indices: poverty headcount dynamics, Gini trajectories, income share distributions. Measures whether countries are generating shared prosperity.
Cross-Country Inequality
Gini and Theil decomposition across countries and time: within-country inequality trends, income share held by top 10% versus bottom 10%, convergence or divergence patterns.
Route map (read-only data)
All under /api/data/. Query parameters support filtering, year windows, pagination, and multi-series panels (up to 30 codes per panel request). Admin routes under /api/admin/ require X-Admin-Key when configured beyond the default placeholder.
What operators should know
Full pack collects are long-running: the client spaces requests to stay inside the public API comfort zone. Treat integration tests as network jobs. For production, set a real admin secret, decide whether metrics scrape is internal-only, and back up the SQLite file with a quiet window or SQLite backup API.
The exhaustive manual (schema DDL, every query parameter bound, troubleshooting table, deployment notes) lives in the repo:
Load the warehouse
From the hercules/ directory:
Integration tests against the live Bank API:
Then open http://127.0.0.1:8011/docs or call /api/data/sources and /api/data/series/hc.lfpr_total with your filters.