← back to AbramsOS

docs/SPEC.md

246 lines

# AbramsOS — Canonical Specification

> Captured verbatim from the project kickoff brief, 2026-05-09. Source of truth for product scope. Update only by appending dated revision sections; do not rewrite history.

## Executive summary

AbramsOS is viable, but only if it is designed as a consent-led, event-driven consumer protection system rather than a generic "receipt manager." The winning architecture is a source-of-truth graph that merges inbox receipts, marketplace exports, card transactions, product identifiers, medical device/drug registries, warranties, service commitments, recall feeds, and jurisdiction-specific rights rules into a single case engine. That engine should decide three things continuously: **what the user owns or purchased, what risks or deadlines now apply, and what action is worth taking next**. The official data landscape is strong for recalls and regulated medical products — especially through the U.S. Consumer Product Safety Commission, NHTSA, FDA / openFDA, AccessGUDID, DailyMed, RxNorm, and Medicare DME supplier directories — but fragmented for retail guarantees, service promises, and card benefits, which are spread across merchant policies, issuer benefit guides, and consumer-protection rules.

The core product insight is that **the hard problem is not AI generation; it is rights-aware orchestration**. Models can gather missing facts, normalize purchases, match recalls, draft letters, assemble claim packets, and prepare disputes — but external side effects must be constrained by user approvals, standing consent, and auditable policy gates. Anthropic's Claude Code and MCP stack are well-aligned with a multi-agent buildout and per-user connector model; OpenAI's tool and function-calling primitives are suitable for production orchestration and selective tool loading.

The biggest product constraints are access and compliance. There is no general published consumer-order API for retail Amazon purchases analogous to seller APIs; the official consumer paths are order history, product-safety alerts, and personal-data requests. Likewise, WhatsApp officially supports chat export and backup/transfer flows for users, but that is not the same as an open personal-history API. Credit-card protections also split between public-law rights and issuer-specific benefits. That means an MVP should focus first on mail/calendar connectors, official recall feeds, user-authorized exports, receipt ingestion, warranty parsing, deadline reminders, and draft-first claim automation. Full autonomy — auto-registering products, sending letters, launching disputes, filing regulator complaints, or submitting medical safety reports — should come later, with explicit approval tiers and stronger legal/compliance controls.

The recommended product positioning is therefore: **"a household rights operating system"** with first-class support for products, services, medical equipment, and pharmaceuticals. It should behave like a blend of asset registry, recall sentinel, warranty manager, service-guarantee tracker, travel-rights assistant, and claim-prep engine. In the early product, every risky action should end as a prepared draft. In the mature product, low-risk actions can run automatically under standing consent while high-risk actions remain user-approved. That sequencing is what makes AbramsOS ambitious but operable.

## Integration and source strategy

### Required integrations

| Surface | Path | Ingest | Reality check |
|---|---|---|---|
| Inbox | Gmail API, Microsoft Graph | order confirmations, invoices, warranty PDFs, service confirmations, card-benefit guides, claim emails | Delegated OAuth per user, minimal scopes, refresh-token vaulting, webhook/subscription re-sync |
| Calendar | Google Calendar, Microsoft Graph, Apple EventKit | warranty-expiry reminders, service follow-ups, airline claim clocks, registration reminders | iOS/macOS local calendar access is product-side, not multi-tenant cloud OAuth |
| Commerce marketplaces | Amazon order history help, Amazon product-safety alerts, Amazon data request | historical orders, seller identity, ASIN-linked receipts, recall matches | Amazon's published APIs are seller-facing, not a general consumer purchase API |
| Messaging and chat | WhatsApp chat export, Twilio | WhatsApp purchase evidence, SMS receipts, support transcripts, delivery notices | Personal-history intake should be export-based or device-local; cloud messaging is for outbound/inbound channels you control |
| Payments and cards | Plaid, Stripe, PayPal REST | posted transactions, merchant names, statement dates, dispute IDs, refund evidence | Statement-level data alone is insufficient; you still need receipt + benefit/rules corpus |
| E-sign / comms | DocuSign, Twilio | signed complaint letters, claim attestations, OTPs, outbound notices | Signatures and delivery receipts should be first-class evidence artifacts |
| Model layer | OpenAI, Anthropic / Claude Code / MCP | multi-agent orchestration, extraction, drafting, case planning | Use at least two providers; keep all side effects behind policy gates |

### Authoritative recall, medical, and product identity sources

| Domain | Primary sources | Store |
|---|---|---|
| Consumer products / furniture | CPSC Data hub, CPSC Recall API, Recalls.gov | recall ID, firm, model, hazard, remedy, images, publication date |
| Vehicles / car seats / tires / equipment | NHTSA recalls + datasets + vPIC | VIN or make-model-year, recall status, campaign IDs, manufacturer remedy, equipment type |
| Drugs and biologics | openFDA drug enforcement, FDA Drug Recalls + Safety Communications, DailyMed, RxNorm | NDC, RXCUI, labeler, lot/recall class, label text, safety communication links |
| Medical devices | openFDA device enforcement + recall + registration/listing, AccessGUDID + lookup API, FDA safety communications | UDI/DI, manufacturer, catalog number, device class, establishment/listing, recall/safety notices |
| DME / medical furniture | Medicare supplier directory, DMEPOS fee schedules, DME coverage, DMEPOS supplier enrollment | HCPCS/DMEPOS categories, supplier identity, CMS enrollment status, coverage notes, replacement/repair rules |
| Brand / manufacturer graph | Verified by GS1, GS1 company database, GTIN standard | GTIN, brand owner, company prefix, location/contact references |

These are **category-specific master registries**, not a single universal database. Build a unified internal graph above them.

### Credit-card protections, passenger rights, guarantee sources

| Domain | Source of truth | Product use |
|---|---|---|
| Billing disputes / claims-and-defenses | CFPB Regulation Z + complaint channel | when card disputes are viable, generate merchant-first or creditor notices, escalate failed cases |
| Issuer purchase / return / extended warranty benefits | Amex purchase protection guide, Chase guide to benefits, Visa extended warranty guide, Mastercard guide to benefits | benefit value, evidence checklist, claim deadlines, exclusions |
| Airline disruptions | DOT dashboards/refund rules, EU/UK passenger rights, Canadian APPR, Brazilian ANAC | track coverage by itinerary and jurisdiction, prompt for refund, compensation, care, regulator complaint, or insurer/card claim |
| International carriage injury / baggage liability | ICAO Montreal Convention | route bodily-injury and baggage matters into legal triage, preserve evidence, show liability limits and escalation |
| Warranties / "satisfaction guaranteed" / returns | FTC warranty/guarantee guides, merchant return-policy structured data | extract merchant promises from ads/policy pages, compare with receipt date, draft demand letters and refund requests |

Build a **Rights Rules Corpus** with three layers: statutory/regulatory rules, issuer/merchant benefit terms, user-specific evidence. Build a **Guarantee Graph** from FTC guidance + merchant policies + archived screenshots, because no national registry exists.

For airline claims: ask only route, carrier, ticket type, disruption cause, and whether anyone was injured — then route automatically.

## Architecture and data model

Multi-tenant microservice platform with a user-scoped connector plane and a central evidence graph. MCP is the right abstraction for user-specific tool hookups.

```mermaid
flowchart LR
    U[End User] --> W[Web / iOS / Android]
    A[Admin Console] --> W
    W --> API[API Gateway]
    API --> AUTH[Auth & Consent Service]
    API --> CONN[Connector Gateway]
    API --> ING[Ingestion Pipeline]
    API --> CASE[Case & Claims Service]
    API --> CAL[Reminder Engine]
    API --> COMMS[Document / Letter / Messaging Service]

    CONN --> EMAIL[Email Connectors]
    CONN --> CALAPI[Calendar Connectors]
    CONN --> CHAT[Marketplace / Chat Imports]
    CONN --> PAY[Bank / Card / Payment Connectors]
    CONN --> MCP[MCP Tool Plane]

    ING --> OCR[Doc Parser / Receipt Extractor]
    ING --> ER[Entity Resolution]
    ING --> GRAPH[Ownership Graph]
    ING --> RULES[Rights Rules Corpus]
    ING --> RECALL[Recall Matching Service]

    RECALL --> SOURCES[Recall / Device / Drug / DME Sources]
    CASE --> GRAPH
    CASE --> RULES
    CASE --> COMMS
    CASE --> APPROVAL[Approval Policy Engine]
    CAL --> GRAPH
    CAL --> W
    GRAPH --> DB[(Postgres + Object Store + Search)]
    RULES --> DB
    COMMS --> DB
    APPROVAL --> AUDIT[Audit Log Service]
    AUTH --> AUDIT
    CASE --> AUDIT
```

Principle: **ingest once, normalize once, decide many times**. Every artifact becomes evidence tied to one or more assets, services, or claims.

### Core database schema (full target)

| Table | Purpose | Key fields |
|---|---|---|
| `org_account` | tenant root; admin and household account models | org_id, plan, region, policy_profile |
| `user_account` | end-user identity | user_id, org_id, locale, timezone |
| `admin_account` | admin/operator identity | admin_id, org_id, role, approval_scope |
| `consent_grant` | OAuth/MCP/import consent ledger | grant_id, user_id, connector_type, scopes, granted_at, revoked_at |
| `connector_account` | bound connector instance | connector_id, user_id, provider, external_subject_id, token_ref |
| `source_message` | raw email/SMS/chat/order artifact | source_id, connector_id, source_type, received_at, payload_ref |
| `document` | receipt, warranty, invoice, screenshot, policy PDF | document_id, owner_id, kind, hash, object_ref, parsed_status |
| `purchase` | purchase-level record | purchase_id, user_id, merchant_name, order_number, purchase_date, total_amount, currency |
| `purchase_item` | line-level asset/service | item_id, purchase_id, category, brand, model, serial, GTIN, quantity, unit_price |
| `service_commitment` | service booking, guarantee, SLA, promise | service_id, purchase_id, provider_name, guarantee_text, refund_window, promised_outcome |
| `medical_asset` | DME/device/medical furniture asset | medical_asset_id, item_id, hcpcs_code, udi_di, supplier_id, coverage_status |
| `pharma_product` | normalized drug/biologic identity | pharma_id, ndc, rxcui, labeler, strength, dosage_form |
| `coverage_policy` | manufacturer warranty, service contract, card benefit, insurer rule | policy_id, owner_ref, policy_type, start_at, end_at, deductible, exclusions_ref |
| `registration_requirement` | whether/where/how a product can or should be registered | req_id, item_id, manufacturer_ref, method, data_needed_json |
| `recall_event` | normalized inbound recall/safety alert | recall_id, authority, external_id, published_at, product_keys_json, remedy |
| `recall_match` | match between owned asset and recall | match_id, recall_id, asset_ref, confidence, status, last_checked_at |
| `rights_rule_snapshot` | versioned policy corpus | rule_id, domain, jurisdiction, source_ref, effective_date, rule_json |
| `claim_case` | claim/dispute lifecycle | case_id, claimant_id, asset_or_service_ref, claim_type, jurisdiction, state, due_at |
| `action_queue` | draft/send/file workflow | action_id, case_id, action_type, approval_level, scheduled_at, executed_at |
| `calendar_reminder` | reminder engine | reminder_id, owner_ref, due_at, reason_code, calendar_event_id |
| `audit_log` | immutable audit trail | audit_id, actor_type, actor_id, object_type, object_id, event_type, metadata, occurred_at |

Two schema decisions matter most: (1) products and services must be peers; (2) medical and consumer records must be separable so the platform supports both consumer and regulated-health deployments from day one.

## Agents and autonomous workflows

Supervisor + specialist skills, not one giant generalist.

| Agent | Mission | Approval |
|---|---|---|
| Intake Orchestrator | classify new evidence, route it | read-only |
| Receipt Extractor | turn docs into structured purchases | read-only |
| Ownership Resolver | resolve brands, models, GTINs, serials, services | read-only |
| Recall Sentinel | monitor recall/safety feeds, match owned assets | read-only |
| Coverage Analyst | infer warranty, service-contract, insurance, card-benefit coverage | read-only |
| Rights Policy Agent | choose the relevant rights regime | read-only |
| Claim Strategist | build the best next action plan | draft-only |
| Letter Composer | draft merchant/manufacturer/issuer/regulator letters | draft-only |
| Registration Agent | auto-fill product registration forms where allowed | user-approved or standing consent |
| Action Agent | send letters, submit forms, open disputes, create calendar events | explicit approval except low-risk reminders |
| Compliance Guardian | enforce consent, HIPAA/privacy boundaries, prompt-injection protections | blocking control |
| Audit Narrator | explain what happened and why | read-only |

### Workflow

```mermaid
flowchart TD
    A[New receipt / email / export / recall feed] --> B[Intake Orchestrator]
    B --> C[Normalize purchase or service]
    C --> D[Entity Resolution]
    D --> E[Ownership Graph update]
    E --> F{Any active risk or deadline?}
    F -- No --> G[Store + remind on warranty expiry]
    F -- Recall --> H[Recall Sentinel opens case]
    F -- Coverage event --> I[Coverage Analyst opens case]
    F -- Service failure --> J[Rights Policy Agent opens case]
    H --> K[Claim Strategist]
    I --> K
    J --> K
    K --> L{Need user approval?}
    L -- Draft only --> M[Compose letter / packet]
    L -- Yes --> N[Approval request]
    N --> O[Action Agent]
    O --> P[Send / file / calendar / sign]
    P --> Q[Audit log + case timeline]
    M --> Q
    G --> Q
```

The "merchant, store, or both?" decision should not be a first question. The strategist computes the recommended routing from evidence + remedy + rule set; the UI surfaces "Recommended first send: store. Optional backup: manufacturer."

### Recall matching (canonical pseudocode)

```python
def match_recall_to_asset(asset, recall):
    score = 0.0
    if asset.gtin and asset.gtin in recall.product_keys.gtins: score += 0.45
    if asset.model and fuzzy(asset.model, recall.product_keys.models) > 0.92: score += 0.25
    if asset.serial and serial_in_range(asset.serial, recall.product_keys.serial_ranges): score += 0.20
    if asset.brand and asset.brand == recall.brand: score += 0.05
    if asset.purchase_date and recall.published_at >= asset.purchase_date: score += 0.05
    if asset.category == "medical_device" and asset.udi_di == recall.product_keys.udi_di: score += 0.40
    status = "positive_match" if score >= 0.85 else "needs_user_confirmation" if score >= 0.60 else "no_match"
    return {"score": round(score, 3), "status": status}
```

### Coverage-value heuristic

```text
EV(warranty/insurance) = P(failure during covered period) × expected covered loss
                       - deductible - exclusions risk - claim friction cost - contract price
```

Produce a plain-language verdict per item: **worth it / borderline / skip**.

## Security, privacy, compliance

Mirror HIPAA-style safeguards even in consumer deployments because medical features will drift toward PHI. Use OAuth 2.0 authorization-code with PKCE for public clients, short-lived service credentials, refresh-token vault. Anthropic explicitly warns that third-party MCP servers can create prompt-injection risk → AbramsOS needs a **Connector Security Gateway** with URL allowlists, schema validation, content sanitization, and egress restrictions.

Required posture (non-negotiable):

| Control | Posture |
|---|---|
| Consent | explicit per-connector; revocation any time; standing-consent matrix for low-risk only |
| Access control | strict RBAC; separate admin and user accounts; JIT elevation |
| Data minimization | scoped tokens; redact PHI/PII before model calls |
| Model safety | destination allowlists, tool schemas, anti-exfiltration checks, prompt-injection scanning |
| Auditability | immutable action log, evidence hash chain, decision trace, approval record |
| Data security | envelope encryption, tenant-scoped keys, signed download URLs |
| Medical | PHI boundary tags, BAA-ready vendors, breach-notification workflow |
| Legal | versioned rights-rule snapshots, source references, confidence scores, "not legal advice" copy |

## Product experience

Calm "control room for ownership," not a spreadsheet. Primary nav: **Home, Assets, Recalls, Claims, Medical, Services, Timeline, Settings.** Dual-surface (household app + admin/policy console).

Visual: layered translucent panels (slate base #0f172a, hairline borders rgba(255,255,255,0.08), 24px backdrop-blur), large radii on cards, soft ambient depth, calm blue for monitoring / amber for deadlines / red only for confirmed high-severity. Always provide a "reduce transparency" theme.

## Roadmap

| Milestone | Duration | Deliverables |
|---|---|---|
| Foundation | 6–8 weeks | auth, org/user/admin model, consent ledger, doc store, audit log, core UI shell |
| Ingestion MVP | 8–10 weeks | Gmail + Outlook, document parsing, receipt extraction, purchase graph, reminders |
| Protection MVP | 8–10 weeks | CPSC/NHTSA/FDA/openFDA ingest, recall matching, warranty parser, case dashboard |
| Claim MVP | 6–8 weeks | draft letters, evidence bundles, calendar workflows, merchant/manufacturer send approval |
| Rights expansion | 8–12 weeks | card benefits corpus, airline rights router, service guarantees, guarantee graph |
| Medical expansion | 8–12 weeks | DME, medical device, pharma identity, supplier registry integration, medical safety center |
| Full autonomy layer | 10–14 weeks | standing approvals, e-sign, partial dispute filing, regulator complaint routing, MCP marketplace |

MVP realistic at 4–6 months. Full platform 9–15 months. Build cost MVP $0.9M–$1.8M; full $3M–$7M. Ongoing $20k–$80k MVP, $100k–$300k full.

## Open questions / limitations

1. Amazon consumer purchase ingestion — no clean official end-user API; rely on inbox + export.
2. WhatsApp purchase capture — export/backup/transfer only, not a personal-history API.
3. Card-benefit coverage is fragmented; need a maintained benefits corpus.
4. Service guarantees are merchant-specific; depends on policy ingestion + screenshot preservation.
5. Medical compliance boundary depends on go-to-market lane (consumer vs provider channel).

**Strategic conclusion:** build AbramsOS as a rights-aware evidence engine with progressive autonomy, not a generic AI concierge.