Skip to main content

Operations

Perform post-processing operations on completed document jobs for error analysis, generative tasks, image selection, and AcroForm PDF generation.

Overview​

Operations allow you to run additional analysis and processing on documents that have already been processed. Available operations include:

  • Error Analysis: Identify potential issues in extraction results.
  • Generative Tasks: Generate summaries, translations, or custom AI responses based on processed documents.
  • Image Selection: Pick relevant figures from extracted images based on a prompt.
  • PDF AcroForm Conversion: Turn a normal PDF into a generated fillable AcroForm PDF, inspect generated field metadata, and reapply reviewed field definitions.
  • Document Outline: (Re)build a structural outline artifact for a completed job without rerunning the extraction.

Available Operations​

Error Analysis​

Analyzes completed document processing jobs to identify:

  • Potential extraction errors or inconsistencies.
  • Missing or incomplete data fields.
  • Confidence levels for extracted information.
  • Suggestions for improving accuracy.

Generative Tasks​

Generates custom AI responses based on processed document content:

  • Document summaries and explanations.
  • Content transformation (e.g., format conversion).
  • Question answering based on document content.
  • Custom analysis with user-defined prompts.

Image Selection​

Selects the most relevant extracted figures based on a prompt. The parent job must have figure artifacts, which are created by running document processing or OCR with extract_figures=True (or describe_figures=True).

PDF AcroForm Conversion​

Converts a completed PDF job into a generated fillable AcroForm PDF. This is useful when the source document has visible entry areas but no native AcroForm fields.

The conversion workflow has two companion artifacts:

  • get_acroform_metadata(operation_job_guid) returns the generated PDF's embedded widget metadata in PDF page-point coordinates.
  • get_pdf_acroform_field_definitions(operation_job_guid) returns normalized editable field definitions with entryBbox values in 0..1 page-image coordinates.

Use the field-definition artifact for review UIs or manual edits, then send the reviewed list back through pdf-acroform/apply to regenerate the PDF without rerunning visual detection.

Document Outline​

Rebuilds the structural-outline artifact for an already-completed job as a follow-up operation, instead of re-running the whole extraction. This is the same outline-building logic used by the DOCUMENT_OUTLINE map-reduce split type — see Map-Reduce Extraction — exposed here as a standalone operation so you can get or regenerate just the outline.

How Operations Work​

  1. Document Processing: First, process a document normally.
  2. Operation Submission: Submit an operation request on the completed job.
  3. Analysis: AI analyzes the original processing results.
  4. Results: Get detailed analysis, generated content, or selected images.

API Endpoints​

Submit Operation​

POST /operation

Request Body:

{
  "jobGuid": "uuid-of-completed-job",
  "type": "error-analysis",
  "parameters": {
    "llmType": "HIGH",
    "customParameters": {}
  }
}

Submit Generative Task​

POST /operation/{parentJobId}/generative-task

Request Body:

{
  "prompt": "Summarize this document and explain its main purpose",
  "model": "DEFAULT",
  "temperature": 0.7,
  "maxTokens": 500
}

SDK & CLI Examples​

Error Analysis​

from docudevs.docudevs_client import DocuDevsClient
import os
import asyncio

client = DocuDevsClient(token=os.getenv('API_KEY'))

async def analyze_errors(job_guid):
    # Submit error analysis operation and wait for the result
    analysis_result = await client.submit_and_wait_for_error_analysis(
        job_guid=job_guid,
        timeout=120
    )
    print(f"Analysis result: {analysis_result}")

# Usage
# asyncio.run(analyze_errors("your-job-guid"))

Generative Tasks​

async def summarize_document(job_guid):
    summary = await client.submit_and_wait_for_generative_task(
        parent_job_id=job_guid,
        prompt="Summarize the main findings",
        model="DEFAULT"
    )
    # The result is a JSON string inside the response object
    import json
    result_data = json.loads(summary.result)
    print(result_data['generated_text'])

Image Selection​

import json

job_guid = await client.submit_and_process_document(
    document=document_bytes,
    document_mime_type="application/pdf",
    prompt="Extract key information",
    extract_figures=True
)
await client.wait_until_ready(job_guid)

selection = await client.submit_and_wait_for_image_selection(
    job_guid,
    prompt="Return all diagrams from the document",
    top_k=5,
    match_mode="all",
    use_vision=False
)

selection_payload = json.loads(selection.result)
first = selection_payload["selected"][0]
image_bytes = await client.get_figure_image(job_guid, first["id"])

PDF AcroForm Conversion​

Run pdf-acroform on a completed PDF job to generate a fillable AcroForm PDF, then inspect or edit the generated field definitions.

The parent job must point to a PDF. The operation also needs rendered page images, so the safest setup is to create the parent job with ocr="PREMIUM" or pass force_ocr=True when thumbnails are missing.

import json

parent_job_guid = await client.submit_and_process_document(
    document=pdf_bytes,
    document_mime_type="application/pdf",
    ocr="PREMIUM",
    extraction_mode="OCR",
    acro_form_metadata=True,
)
await client.wait_until_ready(parent_job_guid, timeout=900, poll_interval=5)

conversion = await client.submit_and_wait_for_pdf_acroform_operation(
    parent_job_guid,
    llm_type="DEFAULT",
    ocr="PREMIUM",
    min_confidence=0.35,
    max_fields_per_page=300,
    timeout=1200,
    poll_interval=10,
    save_to="medical-examination-form-fillable.pdf",
)

generated_metadata = await client.get_acroform_metadata(conversion.operation_job_guid)
definitions_artifact = await client.get_pdf_acroform_field_definitions(
    conversion.operation_job_guid
)

print(json.dumps(generated_metadata.get("fields", [])[:3], indent=2))
print(json.dumps(definitions_artifact["fieldDefinitions"][:3], indent=2))

reviewed_fields = [dict(field) for field in definitions_artifact["fieldDefinitions"]]
for field in reviewed_fields:
    field["reviewStatus"] = "accepted"

applied = await client.submit_and_wait_for_pdf_acroform_apply_operation(
    parent_job_guid,
    field_definitions=reviewed_fields,
    source_operation_guid=conversion.operation_job_guid,
    save_to="medical-examination-form-reviewed.pdf",
)

print(applied.operation_job_guid)

The generated PDF from either the initial conversion or the reviewed apply flow is always downloaded through GET /job/result/{guid}/pdf-acroform.

Document Outline​

outline_result = await client.submit_and_wait_for_document_outline_operation(
    job_guid,
    pages_per_chunk=3,
    overlap_pages=1,
    parallel_processing=True,
    timeout=180,
)

print(outline_result.result)
print(outline_result.document_outline)

If the job already has an outline artifact — for example, a job originally processed with splitType=DOCUMENT_OUTLINE — fetch it directly without submitting a new operation:

outline = await client.get_document_outline(job_guid)

Or wait for a still-running job and fetch its outline in one call:

combined = await client.wait_until_ready_with_document_outline(job_guid)

print(combined.result)
print(combined.document_outline)

pagesPerChunk must be at least 1, overlapPages must be at least 0, and overlapPages must be less than pagesPerChunk. There is no CLI command and no Java SDK method for this operation today — use the Python SDK or the raw HTTP API directly.

Advanced Usage​

Document Question Answering​

You can use Generative Tasks to ask specific questions about a processed document.

questions = [
    "What is the contract duration?",
    "Who are the parties involved?",
    "What are the key obligations?"
]

for question in questions:
    answer = await client.submit_and_wait_for_generative_task(
        parent_job_id=ocr_job_id,
        prompt=f"Based on this document, answer the following question: {question}"
    )
    
    result_data = json.loads(answer.result)
    print(f"Q: {question}")
    print(f"A: {result_data['generated_text']}\n")

Advanced Parameters​

# Submit operation with custom LLM and parameters
await client.submit_operation_with_parameters(
    job_guid=job_guid,
    operation_type="error-analysis",
    llm_type="HIGH",  # Use high-quality LLM for analysis
    custom_parameters={
        "focus_areas": ["numerical_accuracy", "date_formats"],
        "confidence_threshold": 0.8,
        "detailed_suggestions": True
    }
)

Output Formats​

Error Analysis Output​

{
  "analysis": {
    "overall_confidence": 0.85,
    "field_confidence": {
      "invoice_number": 0.95,
      "total_amount": 0.90
    },
    "potential_issues": [
      {
        "field": "line_items",
        "issue": "Some quantities may be misread",
        "confidence": 0.75,
        "suggestion": "Review items with quantities > 100"
      }
    ]
  },
  "recommendations": [
    {
      "type": "processing_improvement",
      "description": "Consider using higher quality OCR settings"
    }
  ]
}

Generative Task Output​

{
  "generated_text": "This document is a household contents insurance policy...",
  "model_used": "DEFAULT",
  "prompt": "Summarize this document...",
  "processing_time_ms": 3245,
  "token_usage": {
    "prompt_tokens": 2847,
    "completion_tokens": 94,
    "total_tokens": 2941
  }
}

Best Practices​

  • Quality Assurance: Run error analysis on critical documents or when confidence scores are low.
  • Summarization: Use generative tasks to create quick summaries for document lists.
  • Translation: Use generative tasks to translate document content while preserving context.
  • Chain Operations: Process a document, then run error analysis, then summarize it—all via API.
  • Map-Reduce Re-processing: Use submit_and_wait_for_map_reduce(parent_job_id=...) to run map-reduce on a previously processed document without re-uploading or re-running OCR. See Map-Reduce Extraction for details.