{"id":"ops/reconciliation-service","relativePath":"ops/reconciliation-service.md","title":"Reconciliation Service (C2)","markdown":"# Reconciliation Service (C2)\n\nThis runbook covers the C2 FastAPI reconciliation service with Redis URI cache.\n\nService path:\n\n- `services/reconciliation-service/`\n\nWhat it does:\n\n- Exposes `POST /reconcile/lookup` for authority lookups across:\n - Getty SPARQL\n - VIAF AutoSuggest\n - Wikidata entity search\n - GeoNames search\n- Caches upstream URI responses in Redis using deterministic SHA-256 cache keys.\n- Returns per-provider cache hit/miss metrics so cache behavior is observable.\n- Runs B6.1 exhibition/literature reconciliation as first-class service pipelines.\n\n## Install deps\n\n```bash\npnpm reconcile:service:deps\n```\n\n## Run locally\n\n```bash\npnpm reconcile:service\n```\n\nDefault bind:\n\n- `http://127.0.0.1:8002`\n\n## Health check\n\n```bash\ncurl http://127.0.0.1:8002/health\n```\n\n## Example lookup\n\n```bash\ncurl -X POST http://127.0.0.1:8002/reconcile/lookup \\\n -H \"content-type: application/json\" \\\n -d \"{\\\"query\\\":\\\"vincent van gogh\\\",\\\"providers\\\":[\\\"wikidata\\\",\\\"viaf\\\"],\\\"limit\\\":5}\"\n```\n\n## B6.1 pipeline endpoints\n\nList available pipelines:\n\n```bash\ncurl http://127.0.0.1:8002/reconcile/pipelines\n```\n\nRun exhibition/literature reconciliation pipeline:\n\n```bash\ncurl -X POST http://127.0.0.1:8002/reconcile/pipelines/exhibitions-literature \\\n -H \"content-type: application/json\" \\\n -d '{\"records\":[{\"id\":\"https://example.org/exh/1\",\"type\":\"PropositionalObject\",\"_label\":\"Sample Exhibition\",\"_source\":{\"provider\":\"met\"}},{\"id\":\"https://example.org/exh/2\",\"type\":\"Activity\",\"_label\":\"Sample Exhibition\",\"classified_as\":[{\"type\":\"Type\",\"_label\":\"Exhibition\"}],\"_source\":{\"provider\":\"rijks\"}}]}'\n```\n\nThreshold band metadata:\n\n```bash\ncurl http://127.0.0.1:8002/reconcile/pipelines/exhibitions-literature/bands\n```\n\n## Environment variables\n\n- `RECONCILIATION_REDIS_URL` (default `redis://127.0.0.1:6379/0`)\n- `RECONCILIATION_CACHE_KEY_PREFIX` (default `mm:reconcile:uri`)\n- `RECONCILIATION_CACHE_TTL_SECONDS` (default `86400`)\n- `RECONCILIATION_HTTP_TIMEOUT_SECONDS` (default `15`)\n- `RECONCILIATION_MAX_RESULTS_DEFAULT` (default `5`)\n- `GETTY_SPARQL_ENDPOINT` (default `https://data.getty.edu/museum/collection/sparql`)\n- `VIAF_AUTOSUGGEST_ENDPOINT` (default `https://viaf.org/viaf/AutoSuggest`)\n- `WIKIDATA_API_ENDPOINT` (default `https://www.wikidata.org/w/api.php`)\n- `GEONAMES_SEARCH_ENDPOINT` (default `http://api.geonames.org/searchJSON`)\n- `GEONAMES_USERNAME` (required to query GeoNames)\n","sections":[{"level":2,"heading":"Install deps","anchor":"install-deps"},{"level":2,"heading":"Run locally","anchor":"run-locally"},{"level":2,"heading":"Health check","anchor":"health-check"},{"level":2,"heading":"Example lookup","anchor":"example-lookup"},{"level":2,"heading":"B6.1 pipeline endpoints","anchor":"b6-1-pipeline-endpoints"},{"level":2,"heading":"Environment variables","anchor":"environment-variables"}],"html":"

Reconciliation Service (C2)

\n

This runbook covers the C2 FastAPI reconciliation service with Redis URI cache.

\n

Service path:

\n\n

What it does:

\n\n

Install deps

\n
\npnpm reconcile:service:deps\n
\n

Run locally

\n
\npnpm reconcile:service\n
\n

Default bind:

\n\n

Health check

\n
\ncurl http://127.0.0.1:8002/health\n
\n

Example lookup

\n
\ncurl -X POST http://127.0.0.1:8002/reconcile/lookup \\\n  -H "content-type: application/json" \\\n  -d "{\\"query\\":\\"vincent van gogh\\",\\"providers\\":[\\"wikidata\\",\\"viaf\\"],\\"limit\\":5}"\n
\n

B6.1 pipeline endpoints

\n

List available pipelines:

\n
\ncurl http://127.0.0.1:8002/reconcile/pipelines\n
\n

Run exhibition/literature reconciliation pipeline:

\n
\ncurl -X POST http://127.0.0.1:8002/reconcile/pipelines/exhibitions-literature \\\n  -H "content-type: application/json" \\\n  -d '{"records":[{"id":"https://example.org/exh/1","type":"PropositionalObject","_label":"Sample Exhibition","_source":{"provider":"met"}},{"id":"https://example.org/exh/2","type":"Activity","_label":"Sample Exhibition","classified_as":[{"type":"Type","_label":"Exhibition"}],"_source":{"provider":"rijks"}}]}'\n
\n

Threshold band metadata:

\n
\ncurl http://127.0.0.1:8002/reconcile/pipelines/exhibitions-literature/bands\n
\n

Environment variables

\n","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"05162c313ea9512166bdda9aec5f49af5af1f278c4af9aa6f3bf6651dd20d852","checksumPrefix":"05162c313ea9","anchorCount":6,"lineCount":84,"rawUrl":"/api/docs/content?path=ops%2Freconciliation-service.md","htmlUrl":"/docs?doc=ops%2Freconciliation-service.md","apiUrl":"/api/docs/content?path=ops%2Freconciliation-service.md"}