agentic-doc

The library automatically handles intermittent HTTP errors and rate limits using an exponential backoff strategy with jitter.

Retried HTTP Status Codes:

• 408 (Request Timeout)
• 429 (Too Many Requests)
• 502 (Bad Gateway)
• 503 (Service Unavailable)
• 504 (Gateway Timeout)

Retry Logic Details:

• Initial Wait: 1 second, increasing exponentially.
• Jitter: Includes a random jitter of up to 10 seconds to prevent thundering herd problems.
• Limits: Retries stop after max_retries attempts or when the wait time reaches max_retry_wait_time. Exceeding these limits raises an exception.

Parsing Errors: If an unrecoverable error occurs during parsing, the resulting object for the affected page(s) will include an errors field containing the error_message, error_code, and the page number.

The library requires a LandingAI agentic AI API key. Set this key as an environment variable or in a .env file using the name VISION_AGENT_API_KEY.

export VISION_AGENT_API_KEY=<your-api-key>

Install the library using pip. It requires Python 3.9, 3.10, 3.11, or 3.12.

pip install agentic-doc

The library provides a global settings object in agentic_doc.config to support legacy code that modifies settings directly.

Warning: This approach is deprecated. You should instead pass a ParseConfig instance to the parse function.

When you modify agentic_doc.config.settings, it uses a SettingsOverrides object to capture changes, which are then merged into the actual Settings instance when get_settings() is called.

Document connectors provide a unified interface for interacting with different storage backends (Local, Google Drive, S3, and URLs). All connectors inherit from BaseConnector and implement three core methods:

1. list_files(path, pattern): Returns a list of file identifiers (e.g., paths, IDs, or URLs).
2. download_file(file_id, local_path): Downloads a specific file to a local path. If local_path is not provided, the connector typically saves the file to a temporary directory.
3. get_file_info(file_id): Retrieves metadata (like size or modification time) for a specific file.

To instantiate a connector, use the create_connector factory function with an appropriate ConnectorConfig object.

When calling _send_parsing_request, you can pass a ParseConfig object to customize how the document is processed. The following parameters can be controlled via the config object:

• figure_captioning_type: Controls the detail of figure captioning. Defaults to FigureCaptioningType.verbose if not specified.
• figure_captioning_prompt: A custom prompt used for figure captioning.
• split: Determines how the document is split. Defaults to SplitType.full if not specified.
• enable_rotation_detection: A boolean to enable or disable rotation detection.
• api_key: An optional override for the API key. If not provided in the config, the library uses the vision_agent_api_key from your environment settings.

The RETRY_LOGGING_STYLE setting determines how the library reports retry attempts:

• log_msg (Default): Logs each retry attempt as a separate log message.
• inline_block: Prints a yellow progress block (█) on the same line for each attempt. Useful for tracking progress without verbose logs.
• none: Disables retry logging entirely.

A Chunk represents a segment of extracted content. It includes the text, its type, a unique ID, and grounding information which maps the text to specific locations in the document.

ChunkGrounding provides the page number and a ChunkGroundingBox (coordinates in [left, top, right, bottom] format). Note that image_path in ChunkGrounding is None by default as it is not provided by the server API.

The parse() function supports BaseConnector instances or ConnectorConfig objects. This allows you to trigger parsing workflows directly from external storage systems (e.g., S3, Google Drive) managed by a connector.

When using a connector:

• You can specify connector_path to search within a specific directory in the connector.
• You can specify connector_pattern to filter files (e.g., using glob patterns).
• The library handles downloading the files to temporary local paths before parsing.

To extract specific fields from a document, you must provide either a Pydantic model or a JSON schema to the parsing functions. You cannot use both simultaneously.

Options:

1. extraction_model: A Pydantic BaseModel class. The extracted data will be validated against this model and returned as a typed object within the ParsedDocument.
2. extraction_schema: A standard JSON schema dictionary. The extracted data will be validated against this schema.

Constraint: If extraction_model is used, the library also attempts to validate extraction_metadata using a metadata model derived from your provided model.