Skip to content

api.md

Latest commit

 

History

History
139 lines (104 loc) · 14 KB

api.md

File metadata and controls

139 lines (104 loc) · 14 KB
Raw

Shared Types

from landingai_ade.types import ParseGroundingBox, ParseMetadata

LandingAIADE

Types:

from landingai_ade.types import (
    ClassifyResponse,
    ExtractResponse,
    ExtractBuildSchemaResponse,
    ParseResponse,
    SectionResponse,
    SplitResponse,
)

Methods:

ParseJobs

Types:

from landingai_ade.types import ParseJobCreateResponse, ParseJobListResponse, ParseJobGetResponse

Methods:

ExtractJobs

Types:

from landingai_ade.types import (
    ExtractJobCreateResponse,
    ExtractJobListResponse,
    ExtractJobGetResponse,
)

Methods:

V2

The client.v2 sub-client targets LandingAI's next-generation ADE gateway, which lives on its own host (api.ade.[env].landing.ai) rather than the V1 host (api.va.[env].landing.ai). It is additive: client.v2.* is a separate surface from the top-level client.* (V1) methods documented above, and using it does not change any V1 behavior. See the README for environment selection and usage examples.

client.v2.parse_jobs and client.v2.extract_jobs both return a single, unified Job shape, even though the underlying parse/extract job envelopes differ upstream -- Job.raw retains the full original envelope as an escape hatch for any field not surfaced on the typed model.

Types:

from landingai_ade.types.v2 import (
    Job,
    JobError,
    JobStatus,
    V2BuildSchemaBilling,
    V2BuildSchemaMetadata,
    V2BuildSchemaResponse,
    V2BuildSchemaWarning,
    V2ExtractBilling,
    V2ExtractMetadata,
    V2ExtractResult,
    V2GroundBilling,
    V2GroundMetadata,
    V2GroundResult,
    V2ParseBilling,
    V2ParseBox,
    V2ParseElement,
    V2ParseGrounding,
    V2ParseGroundingElement,
    V2ParseGroundingEntry,
    V2ParseGroundingPage,
    V2ParseMetadata,
    V2ParseNodeGrounding,
    V2ParsePage,
    V2ParseRange,
    V2ParseResponse,
    V2ParseStructure,
)
  • Job -- unified job shape: job_id, status (JobStatus: pending / processing / completed / failed / cancelled), created_at, completed_at, progress, result (a V2ParseResponse for parse jobs, a V2ExtractResult for extract jobs, a V2BuildSchemaResponse for build-schema jobs, or None until completion), error (JobError), metadata (the result's metadata receipt as a dict, populated top-level only when output_save_url was set and the result was delivered to output_url instead of inline; None otherwise, since inline jobs carry it on result.metadata), raw (the full original envelope as a dict), and the .is_terminal property.
  • V2ParseResponse -- markdown, structure, grounding, metadata (V2ParseMetadata, which nests V2ParseBilling and carries output_markdown_chars, range_units, and openapi_spec). structure is a typed V2ParseStructure tree (document → V2ParsePage → V2ParseElement); each node below the root carries its spatial data inline in a V2ParseNodeGrounding (page, V2ParseRange, V2ParseBox, normalized page coordinates), and leaf elements additionally carry an atomic_grounding list. With options.inline_markdown, each node also carries its markdown slice. The legacy top-level grounding tree (V2ParseGrounding → V2ParseGroundingPage → V2ParseGroundingElement → V2ParseGroundingEntry) is retained for older gateway responses. Element type/page status are permissive strings and unknown keys are retained.
  • V2ExtractResult -- extraction, extraction_metadata, markdown, output_ref, schema_violation_error (set when strict=False and the schema had unextractable fields), warnings, and metadata (V2ExtractMetadata, which carries model_version, input_markdown_chars, output_extraction_chars, range_units, openapi_spec, and nests V2ExtractBilling).
  • V2BuildSchemaResponse -- extraction_schema (the generated JSON Schema serialized as a string) and metadata (V2BuildSchemaMetadata: job_id, duration_ms, openapi_spec, filename/org_id/version (retained for compatibility), a warnings list of V2BuildSchemaWarning (code, msg), and nested V2BuildSchemaBilling).
  • V2GroundResult -- grounding (a tree mirroring the input extraction_metadata, each {value, ranges} leaf replaced by the list of structure blocks its ranges overlap) and metadata (V2GroundMetadata: job_id, duration_ms, openapi_spec, and nested V2GroundBilling).

Methods:

  • client.v2.parse(*, document=..., document_url=..., model=..., options=..., password=..., save_to=...) -> V2ParseResponse

    Synchronous parse. Provide exactly one of document (file) or document_url. Returns a V2ParseResponse on both full success (HTTP 200) and partial success (HTTP 206, where result.metadata.failed_pages lists unparsed pages). Raises V2SyncTimeoutError (from landingai_ade.lib.v2_errors) on a 504; use parse_jobs for long-running documents.

  • client.v2.parse_jobs.create(*, document=..., document_url=..., model=..., options=..., password=..., output_save_url=..., service_tier=...) -> Job

  • client.v2.parse_jobs.get(job_id) -> Job

  • client.v2.parse_jobs.list(*, page=..., page_size=..., status=...) -> JobList[Job]

  • client.v2.parse_jobs.wait(job_id, *, timeout=600, poll_interval=None, raise_on_failure=False) -> Job

    Blocks, polling .get(job_id) with exponential backoff, until the job reaches a terminal status. Raises JobWaitTimeoutError if timeout seconds elapse first, and JobFailedError if raise_on_failure=True and the terminal job carries an error (not simply every failed/cancelled status).

  • client.v2.extract(*, schema, markdown=..., markdown_url=..., model=..., strict=..., save_to=...) -> V2ExtractResult

    Synchronous extract. schema accepts a pydantic BaseModel subclass, a dict, or a JSON-encoded string -- all are coerced to a JSON Schema object. Provide exactly one of markdown or markdown_url. strict=True rejects schemas with unsupported fields (HTTP 422) instead of silently pruning them. Raises V2SyncTimeoutError on a 504; use extract_jobs for long-running documents.

  • client.v2.extract_jobs.create(*, schema, markdown=..., markdown_url=..., model=..., strict=..., output_save_url=..., service_tier=...) -> Job

  • client.v2.extract_jobs.get(job_id) -> Job

  • client.v2.extract_jobs.list(*, page=..., page_size=..., status=...) -> JobList[Job]

  • client.v2.extract_jobs.wait(job_id, *, timeout=600, poll_interval=None, raise_on_failure=False) -> Job

    Same polling/timeout semantics as parse_jobs.wait. Extract jobs have no cancelled status, so raise_on_failure only ever triggers on failed.

  • client.v2.ground(*, extraction_metadata, structure) -> V2GroundResult

    Synchronous ground. Maps each extracted field back to the structure blocks it was quoted from by overlapping extraction_metadata ranges against every block's inline grounding.range. Both extraction_metadata (e.g. client.v2.extract(...).extraction_metadata) and structure (e.g. client.v2.parse(...).structure) accept a dict or a pydantic model. Block ids resolve only against the structure supplied here, so pass the parse result the extraction actually came from. /v2/ground is synchronous-only (no async jobs route).

Notes:

  • parse_jobs.list and extract_jobs.list both return a JobList (a list[Job] subclass) carrying pagination metadata: .has_more, .org_id, .page, .page_size.
  • All client.v2.* methods accept the usual extra_headers, extra_query, extra_body, and timeout overrides; sync methods additionally accept save_to (parse/extract only, not the job-creation methods) to write the response to disk, mirroring V1's save_to.