PdfAnalysis

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/slideforge-dev/json-schema/slideforge-dev-pdf-analysis-schema.json",
  "title": "PdfAnalysis",
  "description": "Output of analyze_pdf() — what /analyze returns and what /generate uses to route.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/slideforge-dev-openapi.json#/components/schemas/PdfAnalysis",
  "properties": {
    "producer": {
      "type": "string",
      "title": "Producer",
      "description": "PDF metadata producer string (telemetry only — never used for routing). Captured so we can correlate buckets with real-world tools after the fact.",
      "default": ""
    },
    "page_count": {
      "type": "integer",
      "title": "Page Count",
      "description": "Number of pages in the PDF"
    },
    "file_size_bytes": {
      "type": "integer",
      "title": "File Size Bytes",
      "description": "Source PDF size in bytes"
    },
    "bucket": {
      "type": "string",
      "enum": [
        "slide-vector",
        "slide-raster",
        "doc-text",
        "doc-image-heavy",
        "scanned",
        "mixed",
        "unknown"
      ],
      "title": "Bucket",
      "description": "Routing decision derived from structural features. The /v1/deck/from-pdf endpoint accepts a file iff its bucket is currently implemented."
    },
    "features": {
      "$ref": "#/$defs/PdfFeatures",
      "description": "Document-level structural features used by the classifier"
    },
    "estimated_cost_usd": {
      "type": "number",
      "title": "Estimated Cost Usd",
      "description": "Per-page price for the bucket × page_count"
    },
    "can_extract": {
      "type": "boolean",
      "title": "Can Extract",
      "description": "True iff /v1/deck/from-pdf will currently accept this file."
    },
    "unsupported_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Unsupported Reason",
      "description": "Human-readable hint shown to the user when can_extract is False, explaining what's not yet supported."
    },
    "pages": {
      "items": {
        "$ref": "#/$defs/PdfPageInfo"
      },
      "type": "array",
      "title": "Pages",
      "description": "Per-page summary, in document order"
    }
  },
  "type": "object",
  "required": [
    "page_count",
    "file_size_bytes",
    "bucket",
    "features",
    "estimated_cost_usd",
    "can_extract"
  ],
  "$defs": {
    "PdfFeatures": {
      "properties": {
        "aspect_ratio_first": {
          "type": "number",
          "title": "Aspect Ratio First",
          "description": "width / height of the first page"
        },
        "is_slide_aspect": {
          "type": "boolean",
          "title": "Is Slide Aspect",
          "description": "True if the first page sits in a slide-shaped aspect band (roughly 1.25–2.45 — covers 4:3, 16:10, 16:9, ultrawide)"
        },
        "is_doc_portrait": {
          "type": "boolean",
          "title": "Is Doc Portrait",
          "description": "True if the first page is portrait-oriented (aspect < 1.0)"
        },
        "consistent_dimensions": {
          "type": "boolean",
          "title": "Consistent Dimensions",
          "description": "True if every page in the document shares the same width/height"
        },
        "total_text_chars": {
          "type": "integer",
          "title": "Total Text Chars",
          "description": "Sum of extractable characters across all pages"
        },
        "total_text_spans": {
          "type": "integer",
          "title": "Total Text Spans",
          "description": "Sum of text spans (formatted runs) across all pages. Zero with non-zero total_text_chars suggests glyph-outlined text — readable but unformatted."
        },
        "total_images": {
          "type": "integer",
          "title": "Total Images",
          "description": "Sum of embedded images across all pages"
        },
        "total_drawings": {
          "type": "integer",
          "title": "Total Drawings",
          "description": "Sum of vector drawing primitives (rects, paths, lines) across all pages — high counts indicate hand-built slide content rather than scanned/raster"
        },
        "unique_fonts": {
          "type": "integer",
          "title": "Unique Fonts",
          "description": "Number of distinct fonts seen across the doc"
        },
        "pages_with_text": {
          "type": "integer",
          "title": "Pages With Text",
          "description": "Pages with at least 50 chars of extractable text"
        },
        "pages_image_only": {
          "type": "integer",
          "title": "Pages Image Only",
          "description": "Pages with images present but fewer than 50 chars of extractable text"
        },
        "pages_blank": {
          "type": "integer",
          "title": "Pages Blank",
          "description": "Pages with no text and no images"
        }
      },
      "type": "object",
      "required": [
        "aspect_ratio_first",
        "is_slide_aspect",
        "is_doc_portrait",
        "consistent_dimensions",
        "total_text_chars",
        "total_text_spans",
        "total_images",
        "total_drawings",
        "unique_fonts",
        "pages_with_text",
        "pages_image_only",
        "pages_blank"
      ],
      "title": "PdfFeatures",
      "description": "Document-level structural features used by the bucket classifier.\n\nEverything here comes from `fitz` primitives — no LLM calls. The fields\nare deliberately concrete (counts, ratios, booleans) so threshold tuning\nagainst a real corpus is reproducible."
    },
    "PdfPageInfo": {
      "properties": {
        "page_number": {
          "type": "integer",
          "title": "Page Number",
          "description": "1-based page number"
        },
        "has_text": {
          "type": "boolean",
          "title": "Has Text",
          "description": "True if the page contains extractable text"
        },
        "has_images": {
          "type": "boolean",
          "title": "Has Images",
          "description": "True if the page contains embedded images"
        },
        "text_char_count": {
          "type": "integer",
          "title": "Text Char Count",
          "description": "Total characters of extractable text"
        },
        "text_preview": {
          "type": "string",
          "title": "Text Preview",
          "description": "First ~80 characters of text content (for the analysis card)",
          "default": ""
        }
      },
      "type": "object",
      "required": [
        "page_number",
        "has_text",
        "has_images",
        "text_char_count"
      ],
      "title": "PdfPageInfo",
      "description": "Per-page summary returned by the analyzer (lean — used by the UI list)."
    }
  }
}