# BookingTruth

**Is that booking actually real?** BookingTruth is a booking-assurance API and MCP server for AI agents. Feed it booking confirmation emails and receipts; it reconciles contradictions across supplier records and returns a verdict - `confirmed`, `held`, `pending`, `cancelled`, or an honest `unknown` - each with a citable proof packet.

**The core rule:** `CONFIRMED` is returned only on supplier-authoritative evidence (tier 5-6: an authenticated supplier lookup, or a supplier-issued receipt carrying an issuance artifact such as an eTicket number). Everything below that bar returns a safe `UNKNOWN` with an `indicated_state` - never an LLM guess. An OTA "you're all set!" email is not ticketing. "We're processing your request" is not ticketing. An issued 13-digit eTicket number is.

Live endpoint: `https://api.bookingtruth.com` - sandbox is free, no signup.

## MCP tools

| Tool | What it does |
|------|--------------|
| `booking_check` | Parse booking/confirmation documents (emails, receipts) and return reconciled booking-state verdicts with citable proof packets. |
| `supplier_coverage` | List suppliers BookingTruth can currently parse or look up, with per-supplier status (seeded/planned). |

## Installation

Remote streamable-HTTP server - no install, no key for the sandbox.

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "bookingtruth": {
      "type": "url",
      "url": "https://api.bookingtruth.com/mcp"
    }
  }
}
```

Cursor / other MCP clients: add a remote MCP server with URL `https://api.bookingtruth.com/mcp`.

## Usage

Ask your agent things like:

- "Here's the confirmation email United sent - is my flight actually ticketed?"
- "Expedia says my rental car is confirmed. Verify it."
- "I changed my flight and got three different emails. What's the real state of my booking?"

Or call the tool directly with raw document text:

```json
{
  "documents": [
    {"filename": "united_eticket.txt", "content": "<raw email text>"}
  ]
}
```

## REST API

```bash
# free sample documents to try (synthetic demo fixtures)
curl https://api.bookingtruth.com/v1/demo/fixtures
curl https://api.bookingtruth.com/v1/demo/fixtures/united_eticket_QA7X2K.txt

# run a check (sandbox: any Bearer key starting with sb_)
curl -X POST https://api.bookingtruth.com/v1/check \
  -H "Authorization: Bearer sb_demo" \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"filename": "doc.txt", "content": "<raw email text>"}]}'
```

- Discovery: `https://api.bookingtruth.com/.well-known/booking-assurance.json`
- OpenAPI 3.0: `https://api.bookingtruth.com/v1/openapi.yaml`
- Agent-oriented docs: `https://api.bookingtruth.com/llms.txt`
- Verdicts persist: `GET /v1/bookings/{id}` and `GET /v1/bookings/{id}/proof`

## Pricing

Sandbox: free, full round trip, demo fixtures included.
Paid: $0.05 per check, prepaid packs ($10 / $25 / $50 = 200 / 500 / 1,000 checks) via `POST /v1/buy`. Paid keys start with `pk_`; check remaining credit at `GET /v1/balance`.

## Supplier coverage

Seeded today: United (confirmation + eTicket receipt parsing), Expedia (OTA itinerary), Disney (aggregate reservation emails). More suppliers planned - call `supplier_coverage` for the live matrix.

## How it works

1. **Parse** - supplier-specific parsers extract typed claims (identity, status, party, money) from each document, each claim carrying an evidence tier (0-6).
2. **Reconcile** - claims are resolved into booking identities; contradictions (e.g. "processing" prose vs. an issued eTicket) are logged as first-class conflict records, rules R0-R5 decide the verdict.
3. **Prove** - every verdict ships with a proof packet: the claims, tiers, rule trace, and source hashes behind the decision. LLM output is tier 0 and can never decide a verdict.

See `docs/` for ARCHITECTURE, API-SPEC, PARSER-FRAMEWORK, and PROOF-PACKET.

## Repo layout

- `booking_assurance/` - the Python package (stdlib only, Python 3.10+): parsers, reconciliation engine, proof packets, REST + MCP servers
- `fixtures/` - synthetic demo fixtures (no real data)
- `tests/run_tests.py` - 16 checks over the contradiction cases
- `server.json` - MCP registry metadata (`com.bookingtruth/bookingtruth`)

## Run the tests

```bash
python3 tests/run_tests.py
```

## License

MIT