# Deterministic Augmented Operator Platform (The $15/hr Expert Runtime) > Target YC RFS Thesis: Brad Flora's "The $15-an-Hour Expert" — transforming generalist, uncredentialed workers into verified domain execution specialists without $350/hr billable dependencies. ## 1. System Architecture & Defensibility Philosophy ### 1.1 The Anti-Wrapper Moat This platform explicitly rejects the "chat copilot" pattern. Generalist operators are not provided raw LLM completions or open chat dialogues. Instead, the platform treats domain-specific operations as a **Strict Finite State Machine (FSM)**: - **Source Document Ingestion & Chunking:** Ingest multi-page regulatory, financial, legal, or claims documents. PyMuPDF extracts token character offsets, page indices, and quad bounding boxes [ymin, xmin, ymax, xmax]. - **Deterministic Rules & Statutory Validation:** Hard-coded procedural constraints and policy verifications. 100% compliant fields auto-pass with zero human touch. - **Constrained Operator Playbook:** Micro-prompts requiring binary or exact choices (e.g., verifying a mismatch, checking Box 7b vs. schedule line). Zero unstructured chat. - **Cryptographic Proof Ledger (Audit Trail):** Every field resolution is bound to an exact character offset, bounding box, rule ID, operator user ID, and timestamp, chained via SHA-256 tamper-evident hashes. - **Human-in-the-Loop Supervision (1:50 Ratio):** Flagged discrepancies automatically escalate to a supervisor queue for credentialed sign-off. ``` ┌────────────────────────────────────────────────────────┐ │ Input Ingestion │ │ (PDFs, Scans, EDI, Court/Tax filings, ERP) │ └──────────────────────────┬─────────────────────────────┘ ▼ ┌────────────────────────────────────────────────────────┐ │ Extraction & Document Parser │ │ (PyMuPDF / OCR -> Token Character Offsets + BBox) │ └──────────────────────────┬─────────────────────────────┘ ▼ ┌────────────────────────────────────────────────────────┐ │ Statutory & Deterministic Rules Engine │ │ (Pure logic, regex, cross-table checks, validations) │ └──────────────┬───────────────────────────┬─────────────┘ │ Pass │ Ambiguity / Flag ▼ ▼ ┌─────────────────────────────┐ ┌───────────────────────┐ │ Auto-Validated Line Items │ │ Constrained Micro-UI │ │ (Zero human touch needed) │ │ ($15/hr Operator) │ └──────────────┬──────────────┘ └───────────┬───────────┘ │ │ Resolved ▼ ▼ ┌────────────────────────────────────────────────────────┐ │ Audit Trail & Proof Ledger Engine │ │ (Offset links, Diff generation, Cryptographic hash) │ └──────────────────────────┬─────────────────────────────┘ ▼ ┌────────────────────────────────────────────────────────┐ │ 1:50 Supervisor Gateway (Sign-off) │ │ (Escalated discrepancies & anomaly review) │ └────────────────────────────────────────────────────────┘ ``` --- ## 2. Core Technical Requirements ### 2.1 Backend Stack - **Language / Framework:** Python 3.11+, FastAPI - **Database:** PostgreSQL (with JSONB support for document state and rule results) - **ORM:** SQLAlchemy 2.0 (async) or SQLModel - **Document Processing:** pypdf, pdfplumber, or fitz (PyMuPDF) with bounding box and character offset extraction - **Validation & Schemas:** Pydantic v2 for structured outputs and state constraints ### 2.2 Frontend Stack - **Framework:** React / Next.js with TypeScript and Tailwind CSS - **PDF Viewer / Canvas:** Two-column layout: - **Left Column:** PDF/Document viewer with highlighted bounding boxes and character offset overlays. - **Right Column:** Sequential Checklist / Micro-Action Flow (no open chat). The operator only resolves structured prompts (`[Confirm Match]`, `[Flag Discrepancy]`, `[Select Disclosed Entity]`). --- ## 3. Data Models (Pydantic / SQLAlchemy Schema) ```python from datetime import datetime from typing import List, Optional, Literal, Dict, Any from uuid import UUID, uuid4 from pydantic import BaseModel, Field class SourceCitation(BaseModel): document_id: str page_number: int bounding_box: Optional[List[float]] = Field(default=None, description="[ymin, xmin, ymax, xmax]") char_offset_start: int char_offset_end: int raw_text: str class VerificationStep(BaseModel): step_id: str rule_name: str rule_description: str status: Literal["pending", "auto_passed", "requires_operator", "flagged_discrepancy"] evidence_citation: Optional[SourceCitation] = None expected_value: Optional[str] = None extracted_value: Optional[str] = None prompt_to_operator: Optional[str] = None allowed_choices: Optional[List[str]] = None operator_decision: Optional[str] = None operator_id: Optional[str] = None resolved_at: Optional[datetime] = None class AuditTrailRecord(BaseModel): audit_id: UUID = Field(default_factory=uuid4) case_id: str step_id: str operator_id: str action_type: Literal["CONFIRM", "OVERRIDE", "ESCALATE"] rationale_tag: Optional[str] = None payload_snapshot: Dict[str, Any] timestamp: datetime = Field(default_factory=datetime.utcnow) hash_signature: str class CasePackage(BaseModel): case_id: str task_type: Literal["tax_exemption_8833", "prior_authorization", "customs_entry"] assigned_operator_id: Optional[str] = None supervisor_id: Optional[str] = None status: Literal["ingested", "in_review", "escalated", "approved", "rejected"] steps: List[VerificationStep] audit_trail: List[AuditTrailRecord] = [] ``` --- ## 4. API Endpoints Specification ### 4.1 Ingestion & Parsing `POST /api/v1/cases/upload` - **Input:** Multipart file (PDF/Image) + task_type - **Logic:** Ingests document, extracts text with coordinate offsets, triggers deterministic rule evaluation, seeds CasePackage. - **Output:** CasePackage object with computed steps. ### 4.2 Operator Micro-Actions `GET /api/v1/cases/{case_id}/next-step` - **Output:** Returns the highest-priority VerificationStep where `status == "requires_operator"`. `POST /api/v1/cases/{case_id}/resolve-step` - **Input:** ```json { "step_id": "step_8833_residency", "operator_id": "op_9281", "decision": "CONFIRM", "override_value": null, "notes": "Verified against Box 7b tax treaty cert" } ``` - **Logic:** Records the decision, computes cryptographic SHA-256 hash across prior state + resolution payload, updates state, and advances to the next step. ### 4.3 1:50 Supervisor Escalation Gateway `GET /api/v1/supervisor/queue` - Returns cases where status == "escalated" or operator overrode a rule. `POST /api/v1/supervisor/{case_id}/sign-off` - Adds supervisor credential signature, marks case approved, and releases deliverable. --- ## 5. UI/UX Functional Requirements ### Split-Screen Workspace - **Synchronized scrolling:** Clicking a verification card automatically jumps the PDF viewer to the relevant bounding box and page. ### Keyboard-Driven Rapid Micro-Tasks - Keys `[1]`, `[2]`, `[3]` for selection options. - `[Enter]` to confirm. - `[E]` to escalate. - Target average decision latency: under 4 seconds per checkpoint. ### No Unstructured Prompting - Operators select structured reasons from an enum list if overriding or flagging. Zero conversational chat. --- ## 6. Implementation Milestones - [x] **Milestone 1: Extraction Pipeline & Data Models** — Implemented Pydantic models for SourceCitation, VerificationStep, CasePackage. Built PDF token position parser. - [x] **Milestone 2: Deterministic Rule Validator** — Created procedural rules engine for Form 8833, CMS-1500 Prior Auth, and CBP Form 7501. - [x] **Milestone 3: Fast Execution API** — REST routes for upload, next-step retrieval, and SHA-256 cryptographic audit record generation. - [x] **Milestone 4: Operator Frontend Interface** — Next.js/Tailwind operator harness with synchronized bounding box highlights, keyboard shortcuts, latency stopwatch, and 1:50 supervisor sign-off.