Data Models

interface SearchJobRequest {
  query: string;                      // Search query (required)
  design_standard?: string | null;    // Filter by standard: "us", "eurocode", "aus-nz", "canada"
  document_id?: string | null;        // Search within specific document
  page?: number;                      // Page number (default: 1)
  per_page?: number;                  // Results per page (default: 25, max: 100)
}

interface JobResponse {
  job_id: string;                // Unique job identifier
  status: "pending" | "in_progress" | "completed" | "failed";
  created_at: string;            // ISO 8601 timestamp
  completed_at?: string | null;  // ISO 8601 timestamp when completed
  results?: SearchResults | null; // Only present when status is "completed"
  error?: ErrorDetails | null;   // Only present when status is "failed"
}

{
  "job_id": "job_abc123xyz",
  "status": "pending",
  "created_at": "2025-10-17T10:30:00Z",
  "completed_at": null,
  "results": null
}

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "created_at": "2025-10-17T10:30:00Z",
  "completed_at": "2025-10-17T10:30:03.245Z",
  "results": {
    "total": 15,
    "page": 1,
    "per_page": 25,
    "total_pages": 1,
    "matches": [...]
  }
}

interface SearchResults {
  total: number;                 // Total number of matches
  page: number;                  // Current page number
  per_page: number;              // Results per page
  total_pages: number;           // Total number of pages
  matches: SearchMatch[];        // Array of search results
}

interface SearchMatch {
  file_id: string;               // Document identifier
  filename: string;              // Original filename
  description: string;           // Document description
  design_standard: string;       // Regional standard
  snippet: string;               // Matching text excerpt
  page_number: number;           // Page number in PDF
  relevance_score: number;       // Score 0.0 to 1.0
  context: string;               // Surrounding text for context
  content_type: "text" | "table" | "figure_caption";
}

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "created_at": "2025-10-17T10:30:00Z",
  "completed_at": "2025-10-17T10:30:03.245Z",
  "results": {
    "total": 15,
    "page": 1,
    "per_page": 25,
    "total_pages": 1,
    "matches": [
      {
        "file_id": "asce-7-22",
        "filename": "ASCE_7-22.pdf",
        "description": "ASCE 7-22: Minimum Design Loads and Associated Criteria for Buildings and Other Structures",
        "design_standard": "us",
        "snippet": "...the deflection of structural members shall not exceed L/360 for roof members supporting plaster ceilings...",
        "page_number": 142,
        "relevance_score": 0.92,
        "context": "Section 10.5.3 - Deflection Limits. The deflection of structural members shall not exceed the following limits: (a) L/360 for roof members supporting plaster ceilings, (b) L/240 for roof members supporting nonplaster ceilings...",
        "content_type": "text"
      },
      {
        "file_id": "aisc-steel-manual-16th-2022",
        "filename": "AISC_Steel_Manual_16th.pdf",
        "description": "AISC Steel Construction Manual, 16th Edition",
        "design_standard": "us",
        "snippet": "Table 3-23: Recommended Deflection Limits for Steel Beams",
        "page_number": 87,
        "relevance_score": 0.88,
        "context": "Table 3-23 provides recommended maximum deflections for various structural applications. For roof beams supporting brittle finishes, L/360 is recommended...",
        "content_type": "table"
      }
    ]
  }
}

interface BuildingCode {
  file_id: string;               // Unique identifier
  filename: string;              // PDF filename
  description: string;           // Full title
  design_standard: string;       // Regional category
  path: string;                  // Internal storage path
  added_at: number;              // Unix timestamp
}

{
  "file_id": "asce-7-22",
  "filename": "ASCE_7-22.pdf",
  "description": "ASCE 7-22: Minimum Design Loads and Associated Criteria for Buildings and Other Structures",
  "design_standard": "us",
  "path": "/processed_via_script_v2/ASCE_7-22.pdf",
  "added_at": 1756064601.5558982
}

interface CodesListResponse {
  stru: BuildingCode[];          // Array of all available codes
}

{
  "stru": [
    {
      "file_id": "aci-318-19",
      "filename": "ACI_318_19.pdf",
      "description": "ACI 318-19: Building Code Requirements for Structural Concrete",
      "design_standard": "us",
      "path": "/processed_via_script_v2/ACI_318_19.pdf",
      "added_at": 1756268806.1990368
    },
    {
      "file_id": "asce-7-22",
      "filename": "ASCE_7-22.pdf",
      "description": "ASCE 7-22: Minimum Design Loads and Associated Criteria for Buildings and Other Structures",
      "design_standard": "us",
      "path": "/processed_via_script_v2/ASCE_7-22.pdf",
      "added_at": 1756064601.5558982
    }
  ]
}

interface ErrorDetails {
  code: string;                  // Error code
  message: string;               // Human-readable message
  details?: any;                 // Additional error context
}

{
  "code": "SEARCH_TIMEOUT",
  "message": "Search operation timed out after 30 seconds",
  "details": {
    "query": "very complex query...",
    "timeout_ms": 30000
  }
}