### Install Dependencies and Setup Shell

Source: https://github.com/landing-ai/agentic-doc/blob/main/tests/README.md

Install development requirements and activate the poetry shell for running tests.

```bash
poetry install --all-extras
poetry shell
```

--------------------------------

### Install agentic-doc and Set API Key

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Install the library using pip and set your API key as an environment variable before making any calls.

```bash
pip install agentic-doc

export VISION_AGENT_API_KEY=<your-api-key>
```

--------------------------------

### Install agentic-doc Library

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Install the agentic-doc library using pip. This is a batteries-included install.

```bash
pip install agentic-doc
```

--------------------------------

### Parse Documents from Google Drive

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Connect to Google Drive to parse documents. Requires Google Cloud project setup and OAuth 2.0 credentials. You can parse all documents or filter by a pattern.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import GoogleDriveConnectorConfig

# Using OAuth credentials file (from quickstart tutorial)
config = GoogleDriveConnectorConfig(
    client_secret_file="path/to/credentials.json",
    folder_id="your-google-drive-folder-id"  # Optional
)

# Parse all documents in the folder
results = parse(config)

# Parse with filtering
results = parse(config, connector_pattern="*.pdf")
```

--------------------------------

### Structured Field Extraction with Pydantic Model

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Use a Pydantic `BaseModel` with the `extraction_model` argument in `parse()` to get typed extraction results with confidence scores and chunk references.

```python
from pydantic import BaseModel, Field
from agentic_doc.parse import parse

class PayStub(BaseModel):
    employee_name: str = Field(description="Full name of the employee")
    employee_ssn: str  = Field(description="Social security number")
    gross_pay: float   = Field(description="Gross pay amount")
    employer_name: str = Field(description="Name of the employer")

results = parse("paystub.pdf", extraction_model=PayStub)
doc = results[0]

# Typed extraction result
fields: PayStub = doc.extraction
print(fields.employee_name)   # "Jane Doe"
print(fields.gross_pay)       # 4500.0
```

--------------------------------

### Verify Agentic Doc Settings at Runtime

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Retrieve and print the current effective settings for batch size, worker threads, and retry attempts as configured via environment variables.

```python
# Verify effective settings at runtime
from agentic_doc.config import get_settings
s = get_settings()
print(s.batch_size, s.max_workers, s.max_retries)
```

--------------------------------

### parse() - Universal Entry Point

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

The top-level `parse()` function is the main entry point for extracting data. It accepts various input formats like local files, URLs, raw bytes, or connector configurations and returns a list of `ParsedDocument` objects.

```APIDOC
## parse()

### Description
Accepts a single document path, a list of paths, raw bytes, a URL string, or a connector config object. Returns a `list[ParsedDocument]`, each containing `markdown` (full extracted text), `chunks` (structured content units), and optional `extraction` (typed field extraction).

### Method
`parse(source, extraction_model=None, result_save_dir=None, **kwargs)`

### Parameters
#### Path Parameters
- **source**: (str | list[str] | bytes | object) - Required - Path to a local file, URL, raw bytes, or connector config object.
- **extraction_model**: (BaseModel | None) - Optional - A Pydantic model for structured field extraction.
- **result_save_dir**: (str | None) - Optional - Directory to save results.

### Request Example
```python
import os
from agentic_doc.parse import parse

os.environ["VISION_AGENT_API_KEY"] = "your-api-key"

# --- Single local file ---
results = parse("invoice.pdf")
doc = results[0]
print(doc.markdown)

# --- URL ---
results = parse("https://example.com/report.pdf")
print(results[0].markdown)

# --- Multiple files ---
results = parse(["contract.pdf", "slide_deck.png"])

# --- Raw bytes ---
with open("document.pdf", "rb") as f:
    raw = f.read()
results = parse(raw)

# --- Save results ---
results = parse(["file1.pdf"], result_save_dir="./output")
print(results[0].result_path)
```

### Response
#### Success Response (200)
- **list[ParsedDocument]**: A list of parsed document objects.

#### Response Example
```json
[
  {
    "markdown": "Extracted document text as markdown.",
    "chunks": [
      {
        "chunk_id": "uuid-string",
        "chunk_type": "text | table | figure | marginalia",
        "text": "Chunk content.",
        "grounding": [
          {
            "page": 0,
            "box": {"l": 0.1, "t": 0.1, "r": 0.9, "b": 0.9}
          }
        ]
      }
    ],
    "errors": [
      {
        "page_num": 1,
        "error": "Parsing failed.",
        "error_code": 500
      }
    ],
    "extraction": { ... } // Optional structured extraction
  }
]
```
```

--------------------------------

### Run Integration Test with API Key

Source: https://github.com/landing-ai/agentic-doc/blob/main/tests/README.md

Execute integration tests, requiring a Vision Agent API Key to be set as an environment variable.

```bash
vision_agent_api_key=xxxx poetry run pytest tests/integ/test_parse_integ.py::test_parse_and_save_documents_multiple_inputs
```

--------------------------------

### Configure Agentic Doc via Environment Variables

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Control concurrency, retries, and logging settings using environment variables or a `.env` file. These settings affect runtime behavior without code modification.

```bash
# .env
VISION_AGENT_API_KEY=your-api-key

# Parallel files processed simultaneously (default: 4)
BATCH_SIZE=8

# Threads per document for chunk parallelism (default: 5)
# Max allowed: BATCH_SIZE * MAX_WORKERS <= 200
MAX_WORKERS=10

# Retry attempts on 408/429/502/503/504 (default: 3)
MAX_RETRIES=10

# Retry backoff ceiling in seconds (default: 60)
MAX_RETRY_WAIT_TIME=30

# Retry logging: "log_msg" | "inline_block" | "none" (default: log_msg)
RETRY_LOGGING_STYLE=inline_block

# DPI for PDF→image conversion (default: 96)
PDF_TO_IMAGE_DPI=150

# Pages per API chunk for regular parsing (default: 10, max: 100)
SPLIT_SIZE=20

# Pages per API chunk when using field extraction (default: 50, max: 50)
EXTRACTION_SPLIT_SIZE=30
```

--------------------------------

### Set LandingAI API Key

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Set your LandingAI agentic AI API key as an environment variable. This is required for authentication.

```bash
export VISION_AGENT_API_KEY=<your-api-key>
```

--------------------------------

### Run All Tests with Pytest

Source: https://github.com/landing-ai/agentic-doc/blob/main/tests/README.md

Execute all tests in the project using pytest.

```bash
pytest
```

--------------------------------

### Parse Documents from Local Directory

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Use the local connector to parse documents from a directory on your file system. Supports recursive searching and pattern filtering. Ensure the path to the documents is correct.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import LocalConnectorConfig

config = LocalConnectorConfig()

# Parse all supported documents in a directory
results = parse(config, connector_path="/path/to/documents")

# Parse with pattern filtering
results = parse(config, connector_path="/path/to/documents", connector_pattern="*.pdf")

# Parse all supported documents in a directory recursively (search subdirectories as well)
config = LocalConnectorConfig(recursive=True)
results = parse(config, connector_path="/path/to/documents")
```

--------------------------------

### Custom Figure Captioning with Prompt

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Control figure descriptions by using FigureCaptioningType.custom with a specific figure_captioning_prompt. This allows for tailored analysis of charts and images.

```python
from agentic_doc.parse import parse
from agentic_doc.config import ParseConfig
from agentic_doc.common import FigureCaptioningType

config = ParseConfig(
    figure_captioning_type=FigureCaptioningType.custom,
    figure_captioning_prompt=(
        "Describe this chart focusing on numerical trends and axis labels. "
        "Ignore decorative elements."
    ),
)

results = parse("financial_charts.pdf", config=config)
for chunk in results[0].chunks:
    if chunk.chunk_type.value == "figure":
        print(chunk.text)  # Custom-prompted figure caption
```

--------------------------------

### Visualize Parsing Results with Default Settings

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Generate annotated images showing where each chunk of content was extracted from a document. This helps verify extraction accuracy and debug issues. Output images are of type PIL.Image.Image.

```python
from agentic_doc.parse import parse
from agentic_doc.utils import viz_parsed_document

# Parse a document
results = parse("path/to/document.pdf")
parsed_doc = results[0]

# Create visualizations with default settings
# The output images have a PIL.Image.Image type
images = viz_parsed_document(
    "path/to/document.pdf",
    parsed_doc,
    output_dir="path/to/save/visualizations"
)
```

--------------------------------

### Save Grounding Images for Chunks

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Export bounding-box regions of document chunks as PNG images. The `image_path` attribute is populated in-place after saving, allowing easy reference to visual elements.

```python
from agentic_doc.parse import parse

results = parse(
    "technical_manual.pdf",
    grounding_save_dir="./groundings"
)
doc = results[0]

for chunk in doc.chunks:
    for grounding in chunk.grounding:
        if grounding.image_path:
            # Path: ./groundings/<stem>/page_<N>/<type>_<id>_<i>.png
            print(f"[{chunk.chunk_type}] saved → {grounding.image_path}")
```

--------------------------------

### Visualize Parsing Results with Custom Settings

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Customize the appearance of parsing visualizations, including bounding box thickness, text background opacity, font scale, and colors for different chunk types. This allows for tailored visual debugging.

```python
from agentic_doc.parse import parse
from agentic_doc.utils import viz_parsed_document
from agentic_doc.config import VisualizationConfig

# Parse a document
results = parse("path/to/document.pdf")
parsed_doc = results[0]

# Or customize the visualization appearance
viz_config = VisualizationConfig(
    thickness=2,  # Thicker bounding boxes
    text_bg_opacity=0.8,  # More opaque text background
    font_scale=0.7,  # Larger text
    # Custom colors for different chunk types
    color_map={
        ChunkType.TITLE: (0, 0, 255),  # Red for titles
        ChunkType.TEXT: (255, 0, 0),  # Blue for regular text
        # ... other chunk types ...
    }
)

images = viz_parsed_document(
    "path/to/document.pdf",
    parsed_doc,
    output_dir="path/to/save/visualizations",
    viz_config=viz_config
)

# The visualization images will be saved as:
# path/to/save/visualizations/document_viz_page_X.png
# Where X is the page number
```

--------------------------------

### Advanced Parse Options with ParseConfig

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Configure parsing behavior with ParseConfig, including API key overrides, marginalia inclusion, figure captioning, split modes, and rotation detection.

```python
from agentic_doc.parse import parse
from agentic_doc.config import ParseConfig
from agentic_doc.common import FigureCaptioningType, SplitType

config = ParseConfig(
    api_key="per-request-api-key",          # Override env var
    include_marginalia=False,               # Skip headers/footers/page numbers
    include_metadata_in_markdown=False,     # Omit metadata comments from markdown
    figure_captioning_type=FigureCaptioningType.transcribe,  # transcribe | verbose | custom
    split=SplitType.page,                   # Return per-page markdown list instead of one string
    split_size=20,                          # Pages per API call chunk (default 10)
    enable_rotation_detection=True,         # Auto-correct rotated pages
)

results = parse("scanned_report.pdf", config=config)
doc = results[0]

# With SplitType.page, markdown is a list[str] — one entry per page
for page_num, page_md in enumerate(doc.markdown):
    print(f"--- Page {page_num} ---")
    print(page_md[:300])
```

--------------------------------

### Run Unit Tests with Pytest

Source: https://github.com/landing-ai/agentic-doc/blob/main/tests/README.md

Execute only the unit tests located in the `tests/unit/` directory.

```bash
pytest tests/unit/
```

--------------------------------

### Parse Local Directory (Recursive and Non-Recursive)

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Scan local folders for supported document types. Set `recursive=False` for only top-level files or `recursive=True` to include subdirectories. Use `connector_pattern` to filter files by name or extension.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import LocalConnectorConfig

# Non-recursive: only files directly in /docs/
config = LocalConnectorConfig(recursive=False)
results = parse(config, connector_path="/docs", connector_pattern="*.pdf")

# Recursive: all PDFs in /archive/ and all subdirectories
config_recursive = LocalConnectorConfig(recursive=True)
results = parse(config_recursive, connector_path="/archive", connector_pattern="*.pdf")

for res in results:
    print(res.markdown[:100])
```

--------------------------------

### Visualize Extraction Results with Bounding Boxes

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Render annotated overlay images of parsed documents using `viz_parsed_document`. Supports default visualization or custom styling via VisualizationConfig.

```python
from agentic_doc.parse import parse
from agentic_doc.utils import viz_parsed_document
from agentic_doc.config import VisualizationConfig
from agentic_doc.common import ChunkType

results = parse("contract.pdf")
doc = results[0]

# Default visualization
images = viz_parsed_document("contract.pdf", doc, output_dir="./viz_output")
# Saves: ./viz_output/contract_viz_page_0.png, _page_1.png, ...

# Custom colors and styling
viz_config = VisualizationConfig(
    thickness=2,
    font_scale=0.6,
    text_bg_opacity=0.85,
    color_map={
        ChunkType.title:       (0,   0,   255),  # Red  (BGR)
        ChunkType.text:        (255, 0,   0  ),  # Blue (BGR)
        ChunkType.table:       (0,   128, 0  ),  # Green
        ChunkType.figure:      (0,   165, 255),  # Orange
        ChunkType.marginalia:  (128, 0,   128),  # Purple
    },
)
images = viz_parsed_document("contract.pdf", doc,
                             output_dir="./viz_output",
                             viz_config=viz_config)
for img in images:
    img.show()  # PIL.Image.Image
```

--------------------------------

### Parse Document from URL

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Parse a document directly from a URL. Optional headers and timeout can be configured. The library will fetch the document content from the provided URL.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import URLConnectorConfig

config = URLConnectorConfig(
    headers={"Authorization": "Bearer your-token"},  # Optional
    timeout=60  # Optional
)

# Parse document from URL
results = parse(config, connector_path="https://example.com/document.pdf")
```

--------------------------------

### Run Specific Test Case with Pytest

Source: https://github.com/landing-ai/agentic-doc/blob/main/tests/README.md

Execute a particular test case within a file, identified by its class and method name.

```bash
pytest tests/unit/test_parse_document.py::TestParseAndSaveDocument::test_parse_single_page_pdf
```

--------------------------------

### Parse Single Local File

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Use the `parse()` function to process a single local PDF file. The results contain markdown, chunks, and errors.

```python
import os
from agentic_doc.parse import parse

os.environ["VISION_AGENT_API_KEY"] = "your-api-key"

# --- Single local file ---
results = parse("invoice.pdf")
doc = results[0]
print(doc.markdown)        # Full document as markdown string
print(len(doc.chunks))     # Number of extracted content chunks
print(doc.errors)          # [] if no errors
```

--------------------------------

### Parse Document from URL with Authentication

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Parse a document directly from an HTTP/HTTPS URL. Supports custom headers for authentication and configurable timeouts.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import URLConnectorConfig

config = URLConnectorConfig(
    headers={"Authorization": "Bearer secret-token"},
    timeout=90,
)

results = parse(config, connector_path="https://internal.example.com/reports/q4.pdf")
print(results[0].markdown)
```

--------------------------------

### Parse Document from URL

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Process a document directly from a URL using the `parse()` function. The extracted markdown is returned.

```python
# --- URL ---
results = parse("https://example.com/report.pdf")
print(results[0].markdown)
```

--------------------------------

### Parse and Save Single Document (In-Memory or to JSON)

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Use `parse_and_save_document` for lower-level control. It can return the parsed document in memory or persist it to a timestamped JSON file in a specified directory. The function returns the path to the saved file when persisting.

```python
from agentic_doc.parse import parse_and_save_document
from pathlib import Path

# In-memory result
doc = parse_and_save_document("report.pdf")
print(doc.markdown)

# Persist to disk — returns Path to timestamped JSON
save_path: Path = parse_and_save_document(
    "report.pdf",
    result_save_dir="./results",
    grounding_save_dir="./groundings",
)
print(save_path)  # PosixPath('results/report_20250101_120000.json')

# Reload from disk
import json
with open(save_path) as f:
    data = json.load(f)
print(data["markdown"][:200])
```

--------------------------------

### Parse Raw Bytes

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Read a document into raw bytes and pass them to the `parse()` function. This is useful for in-memory processing.

```python
# --- Raw bytes ---
with open("document.pdf", "rb") as f:
    raw = f.read()
results = parse(raw)
print(results[0].chunks[0].text)
```

--------------------------------

### Save Groundings as Images

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Extract and save visual regions (groundings) of a document where content was found. This is useful for debugging extraction issues. Images are organized by page number and chunk ID.

```python
from agentic_doc.parse import parse

# Parse a document from a URL & save groundings
results = parse(["https://www.rbcroyalbank.com/banking-services/_assets-custom/pdf/eStatement.pdf"],
                grounding_save_dir="./grounding")


# Print the path to each saved grounding
for chunk in results[0].chunks:
    for grounding in chunk.grounding:
        if grounding.image_path:
            print(f"Grounding saved to: {grounding.image_path}")
```

--------------------------------

### Run Specific Test File with Pytest

Source: https://github.com/landing-ai/agentic-doc/blob/main/tests/README.md

Execute tests within a specific file, such as `test_parse_document.py`.

```bash
pytest tests/unit/test_parse_document.py
```

--------------------------------

### Parse Multiple Documents in Parallel

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Call `parse()` with a list of document paths or URLs to process them in parallel. The results are returned as a list.

```python
# --- Multiple files in one call (processed in parallel) ---
results = parse(["contract.pdf", "slide_deck.png", "https://example.com/doc.pdf"])
for res in results:
    print(res.markdown[:200])
```

--------------------------------

### Parse Single Image File

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

The `parse()` function can also process single image files like PNGs. The output includes the extracted markdown.

```python
# --- Single image ---
results = parse("receipt.png")
print(results[0].markdown)
```

--------------------------------

### Extract Data from Multiple Documents

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Process multiple documents by providing a list of file paths to the `parse` function. Results can be saved to a specified directory.

```python
from agentic_doc.parse import parse

# Parse multiple local files
file_paths = ["path/to/your/document1.pdf", "path/to/another/document2.pdf"]
results = parse(file_paths)
for result in results:
    print(result.markdown)

# Parse and save results to a directory
results = parse(file_paths, result_save_dir="path/to/save/results")
result_paths = []
for result in results:
    result_paths.append(result.result_path)
# result_paths: ["path/to/save/results/document1_20250313_070305.json", ...]
```

--------------------------------

### Extract Fields from Document

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Use this snippet to extract specific fields from a document using a Pydantic model for structured output. Ensure the Pydantic model accurately defines the fields you want to extract.

```python
from pydantic import BaseModel, Field
from agentic_doc.parse import parse

class ExtractedFields(BaseModel):
    employee_name: str = Field(description="the full name of the employee")
    employee_ssn: str = Field(description="the social security number of the employee")
    gross_pay: float = Field(description="the gross pay of the employee")
    employee_address: str = Field(description="the address of the employee")

results = parse("mydoc.pdf", extraction_model=ExtractedFields)
fields = results[0].extraction
metadata = results[0].extraction_metadata
print(f"Field value: {fields.employee_name}, confidence: {metadata.employee_name.confidence}")
```

--------------------------------

### Parse Documents from Amazon S3

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Connect to Amazon S3 to parse documents. AWS credentials can be provided directly or via IAM roles. Supports parsing all documents in a bucket or within a specific prefix.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import S3ConnectorConfig

config = S3ConnectorConfig(
    bucket_name="your-bucket-name",
    aws_access_key_id="your-access-key",  # Optional if using IAM roles
    aws_secret_access_key="your-secret-key",  # Optional if using IAM roles
    region_name="us-east-1"
)

# Parse all documents in the bucket
results = parse(config)

# Parse documents in a specific prefix/folder
results = parse(config, connector_path="documents/")
```

--------------------------------

### Parse Document Excluding Marginalia and Metadata

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Use this snippet to parse a document while excluding marginalia and metadata from the output markdown. Ensure the `agentic_doc.parse` function is imported.

```python
from agentic_doc.parse import parse

results = parse(
    "path/to/document.pdf",
    include_marginalia=False,  # Exclude marginalia from output
    include_metadata_in_markdown=False  # Exclude metadata from markdown
)
```

--------------------------------

### Extract Confidence Metadata

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Access confidence scores and chunk references for extracted fields. Useful for understanding the reliability of the extraction.

```python
meta = doc.extraction_metadata
print(meta.employee_name.confidence)       # 0.97
print(meta.employee_name.chunk_references) # ["chunk-uuid-abc"]
print(meta.gross_pay.confidence)           # 0.99

if doc.extraction_error:
    print("Extraction failed:", doc.extraction_error)
```

--------------------------------

### Parse Documents from Google Drive

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Parse documents from Google Drive using OAuth2 credentials. Optionally restrict parsing to a specific folder ID or filter by file name patterns.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import GoogleDriveConnectorConfig

config = GoogleDriveConnectorConfig(
    client_secret_file="credentials.json",  # From Google Cloud Console
    folder_id="1BxiMVs0XRA5nFMdKvBdBZjgm",  # Optional: restrict to folder
)

# All PDFs/images in the specified folder
results = parse(config)

# Filter to specific file names
results = parse(config, connector_pattern="Q4_*.pdf")

for res in results:
    print(res.markdown[:300])
```

--------------------------------

### Save Parse Results to Disk

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Specify a `result_save_dir` to automatically save the parsing results to JSON files on disk. The function returns the paths to the saved files.

```python
# --- Save results to disk ---
results = parse(["file1.pdf", "file2.pdf"], result_save_dir="./output")
for res in results:
    print(res.result_path)
# Output: PosixPath('output/file1_20250313_070305.json'), ...
```

--------------------------------

### Parse Raw Bytes Input

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Process documents directly from raw bytes in memory. This is useful for documents loaded from API responses or uploads. The library auto-detects the file type from the bytes.

```python
from agentic_doc.parse import parse

# Load a PDF or image file as bytes
with open("document.pdf", "rb") as f:
    raw_bytes = f.read()

# Parse the document from bytes
results = parse(raw_bytes)
```

```python
with open("image.png", "rb") as f:
    image_bytes = f.read()

results = parse(image_bytes)
```

--------------------------------

### Structured Field Extraction with JSON Schema

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Parse documents using a raw JSON schema for language-agnostic schema definitions. Ensures extracted data conforms to the specified structure.

```python
from agentic_doc.parse import parse

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string", "description": "The invoice number"},
        "total_amount":   {"type": "number",  "description": "Total amount due"},
        "due_date":       {"type": "string",  "description": "Payment due date"},
    },
    "required": ["invoice_number", "total_amount"],
}

results = parse("invoice.pdf", extraction_schema=schema)
doc = results[0]

extracted: dict = doc.extraction  # dict validated against the schema
print(extracted["invoice_number"])  # "INV-00423"
print(extracted["total_amount"])    # 1250.00
```

--------------------------------

### Extract Data from a Single Document

Source: https://github.com/landing-ai/agentic-doc/blob/main/README.md

Parse a local file or a document from a URL using the `parse` function. Access the extracted data as markdown or structured chunks.

```python
from agentic_doc.parse import parse

# Parse a local file
result = parse("path/to/image.png")
print(result[0].markdown)  # Get the extracted data as markdown
print(result[0].chunks)  # Get the extracted data as structured chunks of content

# Parse a document from a URL
result = parse("https://example.com/document.pdf")
print(result[0].markdown)
```

--------------------------------

### Stream Documents from Amazon S3

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Stream documents directly from an S3 bucket. Supports IAM role credentials or explicit access key/secret pairs. Filter documents by prefix and pattern.

```python
from agentic_doc.parse import parse
from agentic_doc.connectors import S3ConnectorConfig

config = S3ConnectorConfig(
    bucket_name="my-documents-bucket",
    aws_access_key_id="AKIAIOSFODNN7EXAMPLE",       # Optional with IAM roles
    aws_secret_access_key="wJalrXUtnFEMI/K7MDENG",  # Optional with IAM roles
    region_name="us-west-2",
)

# All documents in bucket
results = parse(config)

# Only PDFs under the "invoices/" prefix
results = parse(config, connector_path="invoices/", connector_pattern="*.pdf")

for res in results:
    print(res.markdown[:200])
```

--------------------------------

### Structured Field Extraction with Pydantic Model

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Enables structured field extraction by passing a Pydantic `BaseModel` to the `parse()` function. The API returns typed fields with confidence scores.

```APIDOC
## Structured Field Extraction

### Description
Pass a Pydantic `BaseModel` as `extraction_model` to have the API return typed fields with confidence scores. Each field in the result has `.value`, `.confidence`, and `.chunk_references`.

### Method
`parse(source, extraction_model=YourPydanticModel, ...)`

### Parameters
#### Request Body
- **extraction_model**: (pydantic.BaseModel) - Required - The Pydantic model defining the fields to extract.

### Request Example
```python
from pydantic import BaseModel, Field
from agentic_doc.parse import parse

class PayStub(BaseModel):
    employee_name: str = Field(description="Full name of the employee")
    employee_ssn: str  = Field(description="Social security number")
    gross_pay: float   = Field(description="Gross pay amount")
    employer_name: str = Field(description="Name of the employer")

results = parse("paystub.pdf", extraction_model=PayStub)
doc = results[0]

# Typed extraction result
fields: PayStub = doc.extraction
print(fields.employee_name)
print(fields.gross_pay)
```

### Response
#### Success Response (200)
- **extraction**: (YourPydanticModel) - The extracted fields conforming to the provided Pydantic model.

#### Response Example
```json
{
  "employee_name": "Jane Doe",
  "employee_ssn": "***-**-1234",
  "gross_pay": 4500.0,
  "employer_name": "Example Corp"
}
```
```

--------------------------------

### ParsedDocument Schema

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Represents the structure of a parsed document, including its markdown content, extracted chunks, and any errors encountered during parsing.

```APIDOC
## ParsedDocument

### Description
Each `ParsedDocument` holds the full markdown, a list of typed `Chunk` objects with bounding-box groundings, optional structured extraction, page range metadata, and any per-page errors.

### Fields
- **markdown** (str): Full document content as a markdown string.
- **doc_type** (str): Type of the document ('pdf' or 'image').
- **start_page_idx** (int): 0-based index of the first page.
- **end_page_idx** (int): 0-based index of the last page.
- **chunks** (list[Chunk]): A list of extracted content chunks.
- **errors** (list[Error]): A list of errors encountered during parsing, per page.
- **extraction** (object | None): Optional structured extraction result.

### Chunk Object
- **chunk_id** (str): Unique identifier for the chunk.
- **chunk_type** (ChunkType): Type of the chunk (text, table, figure, marginalia).
- **text** (str): Extracted text or markdown for this chunk.
- **grounding** (list[Grounding]): Bounding box information for the chunk.

### Grounding Object
- **page** (int): 0-based page index.
- **box** (BoundingBox): Normalized bounding box coordinates [l, t, r, b].

### Error Object
- **page_num** (int): Page number where the error occurred.
- **error** (str): Description of the error.
- **error_code** (int): Error code.

### Request Example
```python
from agentic_doc.parse import parse

results = parse("annual_report.pdf")
doc = results[0]

print(doc.markdown)
print(doc.doc_type)
print(doc.start_page_idx)

for chunk in doc.chunks:
    print(chunk.chunk_id)
    print(chunk.chunk_type)
    print(chunk.text)
    grounding = chunk.grounding[0]
    print(grounding.page)
    print(grounding.box.l, grounding.box.t, grounding.box.r, grounding.box.b)

for err in doc.errors:
    print(f"Page {err.page_num}: {err.error} (code {err.error_code})")
```
```

--------------------------------

### Access ParsedDocument Schema

Source: https://context7.com/landing-ai/agentic-doc/llms.txt

Iterate through the `ParsedDocument` object to access its markdown, document type, page range, and individual chunks with their types and grounding information.

```python
from agentic_doc.parse import parse
from agentic_doc.common import ChunkType

results = parse("annual_report.pdf")
doc = results[0]

# Markdown output
print(doc.markdown)           # str — full document
print(doc.doc_type)           # "pdf" | "image"
print(doc.start_page_idx)     # 0-based first page
print(doc.end_page_idx)       # 0-based last page

# Iterate chunks
for chunk in doc.chunks:
    print(chunk.chunk_id)             # Unique UUID string
    print(chunk.chunk_type)           # ChunkType.text | .table | .figure | .marginalia
    print(chunk.text)                 # Extracted text / markdown for this chunk
    grounding = chunk.grounding[0]
    print(grounding.page)             # 0-based page index
    print(grounding.box.l, grounding.box.t,
          grounding.box.r, grounding.box.b)  # Normalized [0,1] bounding box

# Errors (per page, when parsing partially fails)
for err in doc.errors:
    print(f"Page {err.page_num}: {err.error} (code {err.error_code})")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.