Docudevs api client

This is a client-library for docudevs API, the most accurate document to data service. Documentation available at docs.docudevs.ai

The extraction-review helpers support stored review profiles, exact-run discovery and registration, versioned evaluator claims, human resolutions and adjudications, a cursor-based decision feed, and verified artifact downloads as bytes. See the extraction human review guide for the role boundaries, wire formats, and workflow. Raw extraction results remain immutable; adjudicated results are stored separately.

For hybrid pipelines, ClientPipeline.review_descriptor(producer=..., local_function_ids=..., final_schema=...) builds a detached JSON description of the remote graph, local input/dependency declarations and compiled segments. Supply stable local implementation IDs and release/code/data identities explicitly. It does not execute or serialize Python callables. Bind it to a named review profile using clientPipelineJson as JSON text. Preview/save return a separate server-computed producerFingerprint; omitted/null descriptors preserve the binding and removeClientPipeline: true clears it. This prepares the review capture bridge; hybrid run capture remains pending. See the guide's hybrid producer descriptor and named profile section.

Contract-analysis runs may capture a package of up to 32 explicitly selected documents (including the anchor) and 32 MiB of source material. create_contract_analysis_run accepts package_members, expected_missing_documents, and excluded_documents; the CLI knowledge-base contract-analysis run-create accepts matching JSON-array files. Package member order does not establish precedence.

Finding reviews use a separate append-only record and never replace the machine assessment. Use get_contract_analysis_run_reviews(run_id) to read current dispositions and put_contract_analysis_run_review(...) with the result fingerprint, expected review revision, disposition, and idempotency key to record one. The CLI exposes the same operations as run-reviews and review; the latter accepts evidence references from a JSON file.

Use propose_contract_analysis_finding_test_case(...) to turn one captured finding into an unapproved expectation in a new suite revision. Supply the exact run/result/criterion/target identities, the reviewer-selected expected assessment, rationale, current suite revision, and an idempotency key. The captured package is copied into the proposal. Approve it explicitly, run a new scored trial, attest the report, and publish separately; proposal creation does not trigger any of those actions. The CLI equivalent is knowledge-base contract-analysis propose-test-case. If multiple suite cases share the same anchor, pass suite_case_id to create_contract_analysis_trial(...) (CLI: trial --suite-case-id) to select the exact approved case.

Use confirm_contract_analysis_findings(...) to record reviewer-confirmed results from one run in a single batch. The confirmations join one approved suite case per contract package, and a stale expected_suite_revision is reported as a conflict.

Installation

pip install docu-devs-api-client

Case records

await api.record_stats(case_id, page=0, size=50, q="4.12") pages category counts from the latest applied table version. Pages are zero-based, size is 1–200 (default 50), and q matches a case-insensitive category-code substring. Counts are sorted by total descending, then code ascending. pagination.total is the matching category count and pagination.totalCategories is the full count; record and unlabelled totals remain global. Omit all options for the existing complete response. The CLI accepts the same options: docudevs records stats 42 --page 0 --size 50 --q 4.12.

Create a records case, load rows, and classify them against a category tree. Long-running calls return a job handle; the *_and_wait variants block until the job finishes.

import os

from docudevs import DocuDevsClient

api = DocuDevsClient(token=os.environ["DOCUDEVS_API_KEY"])
case = await api.create_records_case(
    "Product classification",
    key="ean",
    text=["name", "generic_name", "ingredients"],
    label="leaf",
    metadata=["brand"],
    target_depth=[1, 2, 3],
)
await case.import_records_and_wait(rows)  # dicts keyed by the field names above
await case.set_tree_and_wait(nodes, name="Taxonomy v1")

job = await case.classify_and_wait(keys=["4001", "4002"], llm_level="MINI")
for row in await job.flagged():
    await row.accept()  # or row.correct("4.1.2", reason="...") / row.feedback("...")

await case.memo.add("Oat drinks belong under 4.1", scope="4.1")
evaluation = await case.holdout_eval_and_wait({"baseline": {}, "no memo": {"memo": "none"}})
print(evaluation.report.summary())

api.records_case(case_id) returns the same handle for an existing case without making a request; the first classify call with plain rows reads the dataset's field mapping from the server. case.get_record(key) reads one record back, and case.pending_actions() returns AgentAction objects with confirm() and reject(). classify_scores(results, truth, tree=nodes) scores classify results per tree level against a {key: code} mapping as LevelScore counts (1/2 (50%)); classify_accuracy returns the same as fractions.

Workbook normalization (v1)

Submit one native .xlsx workbook with a nonblank interpretation prompt. Do not provide a target schema. Poll the job, then inspect the returned dataset envelope and its issues (a dataset may be complete or needsReview). Fetch the caller-inspectable transformation plan and source map when you need provenance. The SDK does not start downstream processing automatically; choose the next step in your application.

guid = await client.submit_and_process_document(
    workbook,
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    prompt="Normalize the discovered tables and preserve source references.",
    extraction_mode="WORKBOOK",
)
dataset = await client.wait_until_ready(guid, result_format="json")
if dataset.get("status") == "needsReview":
    print(dataset.get("issues", []))
plan = await client.get_workbook_plan(guid)
source_map = await client.get_workbook_source_map(guid)
summary = await client.get_workbook_summary(guid)
# Caller-controlled next step.

Workbook normalization v1 accepts exactly one workbook per job. Cross-workbook joins are a required future capability and are not silently enabled by this SDK.