Merge pull request #8 from appunite/feature/flatten-structured-output

Flatten schema for structured output compatibility

Author: emilwojtaszek

README.md

@@ -76,7 +76,7 @@ curl -X POST http://localhost:8000/extract \
   -F "file=@invoice.pdf"
 ```
 
-**Custom schema** (all fields must be `required`; use `anyOf` with `null` for nullable fields):
+**Custom schema:**
 
 ```bash
 curl -X POST http://localhost:8000/extract \
@@ -90,16 +90,15 @@ curl -X POST http://localhost:8000/extract \
         "description": "Unique invoice identifier (e.g. INV-2025-001)"
       },
       "total_amount": {
-        "anyOf": [{"type": "number"}, {"type": "null"}],
+        "type": "number",
         "description": "Total invoice amount including tax"
       },
       "vendor_name": {
         "type": "string",
         "description": "Name of the company that issued the invoice"
       }
     },
-    "required": ["invoice_number", "total_amount", "vendor_name"],
-    "additionalProperties": false
+    "required": ["invoice_number", "total_amount", "vendor_name"]
   }'
 ```
 
@@ -116,6 +115,26 @@ curl -X POST http://localhost:8000/extract \
 }
 ```
 
+#### Custom schema constraints
+
+The `output_schema` is compiled into a structured output grammar by the Anthropic SDK. This imposes constraints:
+
+**Make all fields required.** For missing values, the LLM returns empty string (`""`) for text and `0` for numbers. Do not use nullable/optional fields.
+
+**Do not use union types.** `"type": ["string", "null"]` causes an SDK assertion error. `"anyOf"` works but counts against complexity limits.
+
+**Keep schemas flat.** Nested objects with multiple fields compound grammar complexity. Use flat keys like `seller_address_street` instead of `seller_address.street`.
+
+**Complexity limits** (hard, non-configurable):
+
+| Limit | Value |
+|---|---|
+| Optional parameters | 24 total |
+| Union type parameters (`anyOf`, type arrays) | 16 total |
+| Compilation timeout | 180 seconds |
+
+Each optional parameter roughly doubles grammar state space. Schemas with >18 optional params will likely timeout.
+
 #### `GET /health`
 
 Health check endpoint (no auth required).

scripts/generate_schema.py

@@ -1,7 +1,7 @@
 """Generate default_invoice_schema.json from the Pydantic InvoiceSchema model.
 
-Produces a flat, human-readable JSON Schema by inlining $ref definitions
-and stripping Pydantic-specific keys (title, default, $defs, examples).
+Inlines $ref definitions and strips Pydantic-specific keys (title, default,
+$defs, examples) to produce a clean, human-readable JSON Schema.
 
 Usage:
     uv run python -m scripts.generate_schema
@@ -28,35 +28,6 @@ def _resolve_refs(node: Any, defs: dict[str, Any]) -> Any:
     return node
 
 
-def _simplify_any_of(node: Any) -> Any:
-    """Convert anyOf: [{type: X}, {type: null}] to type: [X, null]."""
-    if isinstance(node, dict):
-        if "anyOf" in node:
-            types = node["anyOf"]
-            if (
-                len(types) == 2
-                and all(isinstance(t, dict) and set(t.keys()) == {"type"} for t in types)
-            ):
-                merged_type = [t["type"] for t in types]
-                result = {k: v for k, v in node.items() if k != "anyOf"}
-                result["type"] = merged_type
-                return {k: _simplify_any_of(v) for k, v in result.items()}
-
-            if len(types) == 2:
-                null_types = [t for t in types if isinstance(t, dict) and t.get("type") == "null"]
-                obj_types = [t for t in types if t not in null_types]
-                if len(null_types) == 1 and len(obj_types) == 1:
-                    obj = _simplify_any_of(obj_types[0])
-                    if isinstance(obj, dict) and "type" in obj:
-                        obj["type"] = [obj["type"], "null"]
-                    return {**{k: _simplify_any_of(v) for k, v in node.items() if k != "anyOf"}, **obj}
-
-        return {k: _simplify_any_of(v) for k, v in node.items()}
-    if isinstance(node, list):
-        return [_simplify_any_of(item) for item in node]
-    return node
-
-
 def _strip_keys(node: Any, keys: set[str]) -> Any:
     """Remove unwanted keys recursively."""
     if isinstance(node, dict):
@@ -70,9 +41,7 @@ def generate() -> dict:
     raw = InvoiceSchema.model_json_schema()
     defs = raw.pop("$defs", {})
     resolved = _resolve_refs(raw, defs)
-    simplified = _simplify_any_of(resolved)
-    cleaned = _strip_keys(simplified, {"title", "default", "examples"})
-    return cleaned
+    return _strip_keys(resolved, {"title", "default", "examples"})
 
 
 def main() -> None:

src/app/prompts/extraction.py

@@ -7,12 +7,21 @@
 
 Rules:
 - Extract ONLY data explicitly present in the document.
-- If a field cannot be found, use null.
+- For fields not found on the invoice: if the schema allows null, return null. If the field is
+required, return an empty string for text fields and 0 for numeric fields.
 - For numeric fields, extract the numeric value without currency symbols or thousand separators.
-- For date fields, use ISO 8601 format (YYYY-MM-DD). Be aware that US invoices use MM/DD/YYYY and European invoices use DD/MM/YYYY. If the format is ambiguous (e.g. 03/04/2025), use other clues such as language, currency, or the fact that most invoices are issued around the current date.
-- For tax identification numbers, correct obvious OCR errors (O→0, l→1, S→5) when the result produces a valid ID.
-- For line items: extract only actual product/service lines, skip subtotals, totals, and summary rows.
+- For date fields, use ISO 8601 format (YYYY-MM-DD). Be aware that US invoices use MM/DD/YYYY and
+European invoices use DD/MM/YYYY. If the format is ambiguous (e.g. 03/04/2025), use other clues such
+as language, currency, or the fact that most invoices are issued around the current date.
+- For tax identification numbers, correct obvious OCR errors (O→0, l→1, S→5) when the result
+produces a valid ID.
+- For line items: extract only actual product/service lines, skip subtotals, totals, and summary
+rows.
 - Be precise — do not infer or guess values that are not clearly stated.
+
+Additional context:
 {context}
+
 Document text:
-{document_text}"""
+{document_text}
+"""