# Atlas Response Schema v1

This file defines the canonical response contract for `resolve_entity`.

## Design goals
- One coherent entity record across Raw / Canonical / Derived layers
- Claim-level provenance (no floating provenance blobs)
- Same data model for normal + debug output, with debug as superset

---

## 1) Normal response (default)

```json
{
  "entity": {
    "entity_id": "atlas:mid:/m/0cqt90",
    "canonical_label": "Donald Trump",
    "canonical_description": "45th and 47th U.S. President",
    "canonical_type": "atlas:Person",
    "needs_curation": false,
    "identifiers": [
      {"type": "atlas:Mid", "value": "/m/0cqt90"},
      {"type": "atlas:WikidataQID", "value": "Q22686"}
    ]
  },
  "summary": {
    "raw_claim_count": 5,
    "derived_claim_count": 1,
    "sources": ["google-trends", "wikidata", "groq-llm"]
  }
}
```

### Notes
- Normal response is compact and consumer-friendly.
- No giant payload blobs by default.
- Identifiers and canonical type are always easy to access.

---

## 2) Debug response (`debug=true`)

Debug mode returns the normal response plus:

```json
{
  "debug": {
    "raw_claims": [
      {
        "claim_id": "clm_raw_mid_1",
        "layer": "raw",
        "subject": "atlas:mid:/m/0cqt90",
        "predicate": "atlas:hasIdentifier",
        "object": {"kind": "identifier", "id_type": "atlas:Mid", "value": "/m/0cqt90"},
        "provenance": {
          "source": "google-trends",
          "method": "trends-resolution",
          "confidence": 0.90,
          "retrieved_at": "2026-04-03T18:00:00Z"
        }
      }
    ],
    "derived_claims": [
      {
        "claim_id": "clm_drv_type_1",
        "layer": "derived",
        "subject": "atlas:mid:/m/0cqt90",
        "predicate": "atlas:hasCanonicalType",
        "object": {"kind": "type", "value": "atlas:Person"},
        "provenance": {
          "source": "wikidata+llm",
          "method": "type-adjudication",
          "confidence": 0.97,
          "retrieved_at": "2026-04-03T18:00:02Z"
        }
      }
    ],
    "source_payloads": {
      "g_trends_payload": {},
      "wikidata_payload": {},
      "llm_payload": {}
    },
    "turtle": "...",
    "turtle_path": "/tmp/atlas-debug/trump.ttl"
  }
}
```

### Notes
- Debug is strictly a superset of normal.
- Provenance belongs to each claim.
- Payload snapshots are debug-only.

---

## 3) Layer interpretation

- **Raw layer**: source-aligned facts (MIDs, QIDs, external type claims, labels)
- **Canonical layer**: Atlas normalized entity fields (canonical label/type/description)
- **Derived layer**: computed claims (e.g., canonical type adjudication, enrichment links)

All three layers must align around the same `entity_id`.

---

## 4) Field policy

### Required in normal mode
- `entity.entity_id`
- `entity.canonical_label`
- `entity.canonical_type`
- `entity.needs_curation`
- `entity.identifiers[]`

### Required in debug mode
- `debug.raw_claims[]`
- `debug.derived_claims[]`
- `debug.source_payloads`
- `debug.turtle`

---

## 5) Backward compatibility

Current implementation fields (`atlas_id`, `entity_type`, etc.) may remain temporarily,
but target output should migrate to this schema to avoid ambiguity and drift.