Skip to content
Log in

Contextual Schema Optimization

Build and improve extraction configurations from representative documents.

Contextual Schema Optimization helps you create a new extraction configuration or improve an existing one. Give it representative documents, describe the output you need, and optionally attach expected JSON. Contextual Schema Optimization returns a schema, system prompt, evaluation evidence, and a report describing remaining assumptions.

During the private beta, Contextual Schema Optimization is available through two interfaces:

  • reducto-beta MCP is the recommended interface for interactive work with a coding agent. It can inspect local documents, prepare inputs, ask for confirmation, submit the run, and present the result.
  • Contextual Schema Optimization API is the lower-level interface for applications that need to submit runs, poll status, and receive completion webhooks directly.

Choose a workflow

Goal MCP tool API endpoint
Create a schema and prompt for a new use case setup_use_case POST /setup-use-case
Improve an existing schema or prompt optimize_schema POST /schema-optimize
Check an existing production schema Coming soon Coming soon
Retrieve an accepted or finished run get_optimizer_run GET /runs/{run_id}

Use at least three representative documents for setup or optimization. A broader sample usually produces a more useful result than the three-document minimum.

Ground truth

Ground truth pairs a document with expected JSON. It is optional, but it changes what Contextual Schema Optimization can measure:

  • With ground truth, Contextual Schema Optimization can compare extraction output against expected values and report measured accuracy.
  • Without ground truth, Contextual Schema Optimization uses document-backed evaluation and consistency checks. Treat unresolved ambiguities in the report as decisions for a human reviewer.

For schema optimization, attach ground truth as one JSON object per document. The JSON shape should match the extraction schema you want Contextual Schema Optimization to evaluate.

Run lifecycle

Every workflow is asynchronous:

flowchart LR
    A[Prepare documents and requirements] --> B[Submit]
    B --> C[accepted]
    C --> D[running]
    D --> E{Final status}
    E --> F[completed]
    E --> G[partial]
    E --> H[failed]
    F --> I[Review and validate configuration]
    G --> I

completed means Contextual Schema Optimization produced the required artifacts. partial means Contextual Schema Optimization produced a usable result with warnings or missing supporting evidence. failed means Contextual Schema Optimization produced no usable configuration.

Always review the result report and validate the proposed configuration against your own acceptance criteria before promoting it to production.

Limits

  • Setup and optimization require 3–10,000 documents.
  • Each document may be up to 50 MiB.
  • Inline API inputs may total up to 150 MiB.
  • Native workspace ZIPs may occupy up to 1.5 GiB both before and after expansion.
  • Ground-truth JSON must be an object and may be up to 1 MB (1,000,000 bytes) per document.
  • Requirement files may be up to 10 MiB each.
  • A run may execute for up to four hours.

Contextual Schema Optimization does not support on-premises deployments or PrivateLink-only organizations. Reducto will confirm eligibility and provide the Contextual Schema Optimization API base URL during beta onboarding.

Troubleshooting

A run stays at accepted or running

Problem: The run has not reached a final status.

Solution: Continue polling with get_optimizer_run or GET /runs/{run_id} for up to four hours. See the reducto-beta workflow or Contextual Schema Optimization API polling guide.

Contextual Schema Optimization returns partial or failed

Problem: Contextual Schema Optimization found warnings, missing evidence, or an error.

Solution: Read partial_reason, error, and the result report before changing your production configuration. Keep the previous configuration active when Contextual Schema Optimization returns failed.

You cannot access Contextual Schema Optimization

Problem: Your MCP client does not show Contextual Schema Optimization tools, or the API rejects your organization.

Solution: Confirm that Reducto enabled the private beta for your organization. Then reconnect reducto-beta or use the Contextual Schema Optimization API base URL from onboarding.

Type to search…

escClose