feat: Add structured LLM extraction endpoint

app/__init__.py

@@ -1 +0,0 @@
-from flask import Flask\nfrom .config import Config\nfrom .routes import main as main_blueprint\ndef create_app():\n    app = Flask(__name__)\n    app.config.from_object(Config)\n    app.register_blueprint(main_blueprint)\n    return app

app/api/__init__.py

@@ -1 +1,3 @@
-from .text_extract import extract_text
+from .text_extract import extract_text
+from .pdf_extract import extract_pdf
+from .structured_extract import extract_structured

app/api/structured_extract.py

@@ -0,0 +1,180 @@
+from fastapi import APIRouter, UploadFile, File, Form, HTTPException
+from typing import List, Optional
+import time
+import os
+
+from app.domain import ocr, pdf_ocr, fileUpload, structured_extraction
+from app.model.StructuredSchema import StructuredExtractionResult
+from app.services import storage
+
+router = APIRouter()
+
+@router.post("/extract_structured", response_model=List[StructuredExtractionResult])
+async def extract_structured(
+    input_files: Optional[List[UploadFile]] = File(None, description="List of files (Images or PDFs) to process (required if source='upload')"),
+    source: str = Form("upload", description="Source of the file: 'upload' or 'object_storage'"),
+    client_id: Optional[str] = Form(None, description="Client ID for object storage (required if source='object_storage')"),
+    object_keys: Optional[List[str]] = Form(None, description="List of object keys in the bucket (required if source='object_storage')"),
+    lang: str = Form("eng+por", description="Language code (eng, por, eng+por)."),
+    mode: str = Form("fast", description="OCR mode: 'fast' or 'accurate'."),
+    auto_detect: bool = Form(False, description="Enable Orientation and Script Detection (OSD)."),
+    model_provider: str = Form("local_tesseract", description="Provider for structured extraction (e.g., 'local_tesseract', 'openai', 'ollama', 'azure')"),
+    model_name: str = Form("", description="Model name to use (e.g., 'gpt-4o-mini', 'llama3'). Required if provider is not 'local_tesseract'"),
+    force_processing: bool = Form(False, description="Force PDF processing even if page count > 10.")
+):
+    """
+    Extract structured data from uploaded images or PDFs.
+    First performs OCR, then optionally passes the raw text to an LLM for structured JSON output.
+    """
+
+    if mode not in ["fast", "accurate"]:
+        raise HTTPException(status_code=400, detail="Invalid mode. Use 'fast' or 'accurate'.")
+
+    if lang == "auto":
+        auto_detect = True
+        lang = "eng+por"
+
+    if model_provider != "local_tesseract" and not model_name:
+        raise HTTPException(status_code=400, detail="model_name is required when model_provider is not 'local_tesseract'.")
+
+    results = []
+
+    if source == "upload":
+        if not input_files:
+             raise HTTPException(status_code=400, detail="input_files is required when source is 'upload'.")
+
+        if client_id or object_keys:
+             raise HTTPException(status_code=400, detail="Ambiguous request: cannot provide both upload files and object storage parameters.")
+
+        for file in input_files:
+            start_time = time.time()
+            filename = file.filename
+
+            # Determine file type
+            is_pdf = filename.lower().endswith(".pdf")
+
+            # Save file
+            temp_file = fileUpload._save_file_to_server(file)
+
+            try:
+                # Perform OCR
+                if is_pdf:
+                    # Basic PDF header check
+                    try:
+                        with open(temp_file, "rb") as f:
+                            header = f.read(5)
+                        if header != b"%PDF-":
+                            raise HTTPException(status_code=400, detail="Downloaded file is not a valid PDF.")
+                    except HTTPException:
+                        raise
+                    except Exception as e:
+                         raise HTTPException(status_code=400, detail=f"Error validating file: {e}")
+
+                    raw_text = await pdf_ocr.process_pdf(
+                        file_path=temp_file,
+                        lang=lang,
+                        mode=mode,
+                        auto=auto_detect,
+                        force_processing=force_processing
+                    )
+                else:
+                    fileUpload.validate_image_file(file)
+                    raw_text = await ocr.read_image(
+                        img_path=temp_file,
+                        lang=lang,
+                        mode=mode,
+                        auto=auto_detect
+                    )
+
+                # Extract Structured Data
+                structured_data = structured_extraction.extract_structured_data(
+                    text=raw_text,
+                    provider=model_provider,
+                    model_name=model_name,
+                    lang_hint=lang
+                )
+
+            finally:
+                if os.path.exists(temp_file):
+                    os.remove(temp_file)
+
+            time_taken = str(round((time.time() - start_time), 2))
+
+            results.append(StructuredExtractionResult(
+                file_name=filename or "unknown",
+                provider_used=model_provider,
+                model_used=model_name if model_provider != "local_tesseract" else None,
+                data=structured_data,
+                time_taken=time_taken
+            ))
+
+    elif source == "object_storage":
+        if input_files:
+             raise HTTPException(status_code=400, detail="Ambiguous request: cannot provide both upload files and object storage parameters.")
+
+        if not client_id or not object_keys:
+             raise HTTPException(status_code=400, detail="client_id and object_keys are required when source is 'object_storage'.")
+
+        for key in object_keys:
+            start_time = time.time()
+
+            is_pdf = key.lower().endswith(".pdf")
+            temp_file = None
+
+            try:
+                try:
+                    temp_file = storage.download_file_from_storage(client_id, key)
+                except ValueError as e:
+                    raise HTTPException(status_code=400, detail=str(e))
+                except Exception as e:
+                     raise HTTPException(status_code=500, detail=f"Error retrieving file {key} from storage.")
+
+                if is_pdf:
+                    try:
+                        with open(temp_file, "rb") as f:
+                            header = f.read(5)
+                        if header != b"%PDF-":
+                            raise HTTPException(status_code=400, detail="Downloaded file is not a valid PDF.")
+                    except HTTPException:
+                        raise
+                    except Exception as e:
+                         raise HTTPException(status_code=400, detail=f"Error validating file: {e}")
+
+                    raw_text = await pdf_ocr.process_pdf(
+                        file_path=temp_file,
+                        lang=lang,
+                        mode=mode,
+                        auto=auto_detect,
+                        force_processing=force_processing
+                    )
+                else:
+                    raw_text = await ocr.read_image(
+                        img_path=temp_file,
+                        lang=lang,
+                        mode=mode,
+                        auto=auto_detect
+                    )
+
+                # Extract Structured Data
+                structured_data = structured_extraction.extract_structured_data(
+                    text=raw_text,
+                    provider=model_provider,
+                    model_name=model_name,
+                    lang_hint=lang
+                )
+
+                time_taken = str(round((time.time() - start_time), 2))
+                results.append(StructuredExtractionResult(
+                    file_name=key,
+                    provider_used=model_provider,
+                    model_used=model_name if model_provider != "local_tesseract" else None,
+                    data=structured_data,
+                    time_taken=time_taken
+                ))
+            finally:
+                if temp_file and os.path.exists(temp_file):
+                    os.remove(temp_file)
+    else:
+        raise HTTPException(status_code=400, detail="Invalid source. Use 'upload' or 'object_storage'.")
+
+    return results

app/domain/structured_extraction.py

@@ -0,0 +1,77 @@
+import litellm
+import instructor
+from litellm import completion
+from app.model.StructuredSchema import StructuredDocumentData, DocumentEntity
+from app.domain import ner
+import logging
+
+log = logging.getLogger("uvicorn")
+
+def extract_structured_data(
+    text: str,
+    provider: str = "local_tesseract",
+    model_name: str = "",
+    lang_hint: str = "eng+por"
+) -> StructuredDocumentData:
+    """
+    Extracts structured data from raw text.
+    If provider is 'local_tesseract', returns a fallback structure using heuristics and spaCy.
+    Otherwise, uses litellm + instructor to ask the specified model for the StructuredDocumentData.
+    """
+
+    if provider == "local_tesseract" or not model_name:
+        # Fallback to local heuristic extraction
+        log.info("Using local fallback for structured extraction (no LLM)")
+
+        # Extract entities using existing spaCy NER
+        spacy_entities = ner.extract_entities(text, lang_hint=lang_hint)
+        entities = [
+            DocumentEntity(text=e["text"], label=e["label"])
+            for e in spacy_entities
+        ]
+
+        return StructuredDocumentData(
+            document_type="unknown",
+            key_values=[],
+            tables=[],
+            entities=entities,
+            text_summary=f"Fallback extraction. Extracted {len(text)} characters of text."
+        )
+
+    # Use litellm with instructor to get structured JSON
+    log.info(f"Using LLM for structured extraction: provider={provider}, model={model_name}")
+
+    # Patch litellm completion with instructor
+    client = instructor.from_litellm(completion)
+
+    # Prefix the model with the provider if litellm requires it
+    # litellm format is usually "provider/model_name"
+    full_model_name = f"{provider}/{model_name}" if "/" not in model_name and provider != "openai" else model_name
+
+    prompt = (
+        "You are an expert data extraction assistant. I will provide you with the raw OCR text of a document. "
+        "Your task is to analyze the text and extract structured information, including the type of the document, "
+        "any key-value pairs (like invoice numbers, dates, totals, names), any tables you can identify, "
+        "and a brief summary. Also extract important named entities.\n\n"
+        "Here is the raw document text:\n"
+        "------------------\n"
+        f"{text}\n"
+        "------------------\n"
+    )
+
+    try:
+        # instructor will handle forcing the StructuredDocumentData schema
+        structured_data = client.chat.completions.create(
+            model=full_model_name,
+            messages=[
+                {"role": "system", "content": "You are a precise data extraction AI."},
+                {"role": "user", "content": prompt}
+            ],
+            response_model=StructuredDocumentData,
+            max_tokens=4096,
+        )
+        return structured_data
+    except Exception as e:
+        log.error(f"Error during LLM structured extraction: {e}")
+        # Return fallback on error
+        return extract_structured_data(text, "local_tesseract", "", lang_hint)

app/main.py

@@ -1,21 +1,12 @@
 from fastapi import FastAPI
-from pydantic import BaseModel
-import uvicorn
+from app.api import text_extract, pdf_extract, structured_extract
 
-app = FastAPI()
+app = FastAPI(title="API_OCR")
 
-class Item(BaseModel):
-    name: str
-    description: str | None = None
-    price: float
+app.include_router(text_extract.router)
+app.include_router(pdf_extract.router)
+app.include_router(structured_extract.router)
 
-@app.get('/')
-def read_root():
-    return {'message': 'Welcome to the FastAPI app!'}
-
-@app.post('/items/')
-def create_item(item: Item):
-    return item
-
-if __name__ == '__main__':
-    uvicorn.run('main:app', host='127.0.0.1', port=8000, reload=True)
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8080)

app/model/StructuredSchema.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict, Any
+
+class KeyValue(BaseModel):
+    key: str = Field(description="The field name or key")
+    value: str | float | int | bool | None = Field(description="The extracted value")
+
+class TableRow(BaseModel):
+    cells: List[str] = Field(description="The cells in this row")
+
+class Table(BaseModel):
+    title: Optional[str] = Field(None, description="Optional title or caption of the table")
+    columns: List[str] = Field(description="Column headers")
+    rows: List[TableRow] = Field(description="Rows of the table")
+
+class DocumentEntity(BaseModel):
+    text: str = Field(description="The text of the entity")
+    label: str = Field(description="The type of the entity (e.g., PER, ORG, LOC, DATE, MONEY)")
+
+class StructuredDocumentData(BaseModel):
+    document_type: str = Field(description="Inferred type of the document (e.g., 'invoice', 'scientific_paper', 'receipt', 'contract', 'unknown')")
+    key_values: List[KeyValue] = Field(default_factory=list, description="Extracted key-value pairs from the document")
+    tables: List[Table] = Field(default_factory=list, description="Extracted tables from the document")
+    entities: List[DocumentEntity] = Field(default_factory=list, description="Named entities found in the document")
+    text_summary: Optional[str] = Field(None, description="A brief summary of the document's content")
+
+class StructuredExtractionResult(BaseModel):
+    file_name: str
+    provider_used: str
+    model_used: Optional[str] = None
+    data: StructuredDocumentData
+    time_taken: str

pyproject.toml

@@ -9,6 +9,8 @@ dependencies = [
     "fastapi>=0.129.0",
     "filetype>=1.2.0",
     "httpx>=0.28.1",
+    "instructor>=1.15.1",
+    "litellm>=1.83.0",
     "pdf2image>=1.17.0",
     "pillow>=12.1.1",
     "pip>=26.0.1",