Skip to main content
Back to challenges
Challenge

Structured Crude Oil Assay Extractor with Pydantic AI and Upstage Document AI

Crude oil exports under Iraq's interim policy require precise matching of API gravity, sulfur percentage, and viscosity against terminal contractual requirements. Raw technical assay PDFs from laboratories like Saybolt or SGS must be reliably parsed into strictly typed computational structures. Using Pydantic AI for type-safe agent execution and Upstage Document AI for layout-aware PDF OCR extraction, build an automated parser that converts noisy assay sheets into validated Pydantic models for trade valuation engines.

Business OperationsHosted by Vera
Sign in free to start
Challenge brief

What you are building

The core problem, expected build, and operating context for this challenge.

Build a type-safe crude assay extraction agent using Pydantic AI and Upstage Document AI.

Delivery guide

How work is evaluated

Evaluation

Evaluates JSON extraction accuracy against gold standard assay certificates.

Datasets

Challenge datasets

Public datasets, plus the private datasets you have access to.

Evaluation rubric

How submissions are scored

These dimensions define what the evaluator checks and which criteria separate a passable run from a strong one.

Dimensions
2 scoring checks
Binary
2 pass or fail dimensions
Ordinal
0 scaled dimensions
Dimension 1

check_api_gravity

Ensure API gravity numeric extraction is accurate.

Binary check

This dimension contributes its full weight only when the submission satisfies the requirement. Partial credit is not awarded.

Dimension 2

extraction_f1_score

F1 score across key-value entity pairs. • target: 0.98 • range: 0-1

Binary check

This dimension contributes its full weight only when the submission satisfies the requirement. Partial credit is not awarded.

Learning goals

What you should walk away with

  • Implement document layout extraction with Upstage Document AI.

  • Construct strict Pydantic schemas for crude oil quality assays.

  • Build error-handling and retry logic using Pydantic AI validation hooks.

Resources and assets

Reference links and supporting material

Dataset notes

25 synthetic crude oil quality laboratory certificates in text and PDF layout format.

Challenge setup

Evaluates JSON extraction accuracy against gold standard assay certificates.

Challenge input

JSON containing raw_layout_text

Pydantic AI

Provides robust schema validation for structured LLM output.

Upstage

Superior document processing capabilities for technical tables.

Evaluated output

JSON representing CrudeAssay Pydantic schema

Evaluation checks
  • Ensure API gravity numeric extraction is accurate.
  • F1 score across key-value entity pairs. • target: 0.98 • range: 0-1
Configured evaluation evidence
  • Benchmark: DocExtract-Bench-Pydantic
  • Extraction F1 Score target: 0.98
  • 1 public reference case
Configured runtime
  • Python execution harness
  • Python sandbox (unavailable on Versalist)

Summary shows the first task, up to three tools, and up to three evidence items. Open the technical recipe to view all configured items.

View technical recipe

Configured tools

Action Space
  • Pydantic AI · Required
  • Upstage · Optional
  • Coval · Optional
Orchestration
  • Pydantic AI · Required

Evaluation contract

  • check_api_gravity · Weight 1
  • extraction_f1_score · Weight 1

Metrics

  • extraction_f1_score · Target 0.98

Benchmarks

  • DocExtract-Bench-Pydantic
  • general

Reference cases

  • 1 public reference case

Workflow tasks

  1. Task 1

    Input: JSON containing raw_layout_text

    Output: JSON representing CrudeAssay Pydantic schema

    Execution harness: Python

Evaluation tools

  • Pydantic AI · Type Validation & Agent Shell
  • Upstage · Document Parsing

Recipe freeze marker

No recipe freeze time is recorded.

Frequently Asked Questions about Structured Crude Oil Assay Extractor with Pydantic AI and Upstage Document AI