### Install DocuDevs SDK with uv

Source: https://github.com/docudevs/docs/blob/main/docs/getting-started/quick-start.md

Install the DocuDevs Python SDK using uv. This example also shows how to create and activate a virtual environment.

```bash
# Optional: create a virtual environment
uv venv
source .venv/bin/activate

# Install the SDK
uv pip install docu-devs-api-client
```

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

### Install Dependencies

Source: https://github.com/docudevs/docs/blob/main/README.md

Run this command to install all project dependencies defined in the package.json file.

```bash
$ yarn
```

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

### Verify SDK Installation

Source: https://github.com/docudevs/docs/blob/main/docs/basics/install.md

Confirm the library is correctly installed by importing the client.

```python
# Test your installation
from docudevs.docudevs_client import DocuDevsClient
print("DocuDevs SDK installed successfully!")
```

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

### Install and configure DocuDevs CLI

Source: https://github.com/docudevs/docs/blob/main/docs/basics/PlainOCR.md

Install the client package and set the required API key environment variable.

```bash
pip install docu-devs-api-client
```

```bash
export DOCUDEVS_API_KEY="your_api_key"
```

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

### Install DocuDevs SDK

Source: https://github.com/docudevs/docs/blob/main/docs/basics/install.md

Install the client library using common Python package managers.

```bash
# Install the latest version
pip install docu-devs-api-client

# Or install a specific version
pip install docu-devs-api-client==1.0.1
```

```bash
# Add to your project
poetry add docu-devs-api-client

# Or specify version

poetry add docu-devs-api-client==1.0.1
```

```bash
# Install from PyPI via conda
conda install -c conda-forge pip
pip install docu-devs-api-client
```

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

### Install DocuDevs SDK with pip

Source: https://github.com/docudevs/docs/blob/main/docs/getting-started/quick-start.md

Install the DocuDevs Python SDK using pip. Ensure you have Python 3.9+ installed.

```bash
pip install docu-devs-api-client
```

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

### Start Development Server

Source: https://github.com/docudevs/docs/blob/main/README.md

Launches a local development server with hot-reloading enabled for rapid iteration.

```bash
$ yarn start
```

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

### Python SDK - Get Image

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/tracing.md

Example of how to retrieve a page thumbnail image using the Python SDK.

```APIDOC
## Get a specific page thumbnail
```python
# Get a specific page thumbnail
image_bytes = await client.get_image(job_guid, page_index=0)
if image_bytes:
    with open("page_0.png", "wb") as f:
        f.write(image_bytes)
```
```

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

### Java SDK - Get Image

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/tracing.md

Example of how to retrieve a page thumbnail image using the Java SDK.

```APIDOC
## Get a specific page thumbnail
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

String jobGuid = "your-job-guid";
String apiKey = System.getenv("API_KEY");

HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.docudevs.ai/job/image/" + jobGuid + "/0"))
    .header("Authorization", "Bearer " + apiKey)
    .GET()
    .build();

HttpResponse<byte[]> response = httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray());
if (response.statusCode() / 100 != 2) {
    throw new IllegalStateException("Image fetch failed: HTTP " + response.statusCode());
}

Files.write(Path.of("page_0.png"), response.body());
```
```

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

### Finnish Autovero Calculation Example

Source: https://github.com/docudevs/docs/blob/main/docs/core/calculated-fields.md

A practical example calculating a total tax value based on two extracted vehicle price components.

```json
{
  "type": "object",
  "properties": {
    "ajoneuvon_perushinta": { "type": "number" },
    "varusteiden_verotusarvo": { "type": "number" },
    "verotusarvot_yhteensa": { "type": "number" },
    "laskettu_verotusarvot_yhteensa": {
      "type": "number",
      "x-docudevs": {
        "fieldType": "calculated",
        "dependsOn": ["ajoneuvon_perushinta", "varusteiden_verotusarvo"],
        "formula": {
          "lang": "excel",
          "expression": "ROUND({ajoneuvon_perushinta} + {varusteiden_verotusarvo}, 2)"
        }
      }
    }
  }
}
```

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

### Python SDK - Get Trace

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/tracing.md

Example of retrieving LLM trace data for a job using the Python SDK.

```APIDOC
## Get the LLM trace for a job
```python
async def get_trace(self, guid: str) -> dict | None:
    """Get the LLM trace for a job.

    Returns:
        The trace data as a dict, or None if no trace is available.
    """
```
```

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

### POST /document/process/{guid}/with-configuration/{configurationName}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/process-document-with-configuration.api.mdx

Processes a document identified by a GUID using a specified configuration name.

```APIDOC
## POST /document/process/{guid}/with-configuration/{configurationName}

### Description
Processes a document identified by a GUID using a specified configuration name.

### Method
POST

### Endpoint
/document/process/{guid}/with-configuration/{configurationName}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the document.
- **configurationName** (string) - Required - The name of the configuration to apply.

#### Query Parameters
- **dependsOn** (string) - Optional - Dependency identifier.

### Response
#### Success Response (200)
- **guid** (string) - The unique identifier of the document.
- **status** (string) - The current status of the processing request.

#### Response Example
{
  "guid": "string",
  "status": "string"
}
```

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

### Upload and Process Documents with cURL

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/job-management.md

Uploads a document to generate a GUID, then processes it for extraction. The second example demonstrates chaining jobs to reuse parsed content.

```bash
GUID=$(curl -s -X POST https://api.docudevs.ai/document/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "document=@invoice.pdf" | jq -r '.guid')

curl -X POST "https://api.docudevs.ai/document/process/$GUID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema": "...", "prompt": "Extract header fields"}'
```

```bash
curl -X POST "https://api.docudevs.ai/document/process/$GUID?dependsOn=$GUID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema": "...", "prompt": "Extract line items"}'
```

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

### GET /configuration/{configuration_name}

Source: https://github.com/docudevs/docs/blob/main/docs/configuration/Configuration.md

Get the details of a specific configuration to inspect its settings.

```APIDOC
## GET /configuration/{configuration_name}

### Description
Get the details of a specific configuration to inspect its settings.

### Method
GET

### Endpoint
/configuration/{configuration_name}

### Parameters
#### Path Parameters
- **configuration_name** (string) - Required - The name of the configuration to retrieve.

### Request Example
```bash
curl -X GET https://api.docudevs.ai/configuration/invoice-config \
  -H "Authorization: Bearer $API_KEY"
```

### Response
#### Success Response (200)
- **prompt** (string) - The prompt associated with the configuration.
- **ocr** (string) - OCR settings for the configuration.
- **llm** (string) - LLM settings for the configuration.

### Response Example
```json
{
  "prompt": "Extract invoice details.",
  "ocr": "tesseract",
  "llm": "gpt-4"
}
```
```

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

### Get Specific Configuration Details

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Retrieve detailed information for a specific saved configuration by its name.

```bash
docudevs get-configuration CONFIG_NAME
```

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

### Get Case Details with CLI

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/cases.md

Use the command-line interface to retrieve details for a specific case.

```bash
docudevs cases get 123
```

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

### POST /document/batch/{guid}/process

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/process-batch.api.mdx

Initiates the processing of a document batch identified by the provided GUID.

```APIDOC
## POST /document/batch/{guid}/process

### Description
Initiates the processing of a document batch identified by the provided GUID. This endpoint allows for custom configurations including OCR types, LLM models, extraction modes, and map-reduce settings.

### Method
POST

### Endpoint
/document/batch/{guid}/process

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the batch to process.

#### Request Body
- **orgId** (string) - Required - The organization ID associated with the request.
- **ocr** (OcrType) - Optional - OCR processing type (DEFAULT, PREMIUM, EXCEL, NONE, AUTO, LOW).
- **llm** (LlmType) - Optional - LLM model type (DEFAULT, NANO, MINI, HIGH).
- **extractionMode** (ExtractionMode) - Optional - Mode for data extraction (SIMPLE, STEPS, OCR, GENERATIVE).
- **schema** (string) - Optional - Schema definition for extraction.
- **prompt** (string) - Optional - Custom prompt for processing.
- **barcodes** (boolean) - Optional - Whether to extract barcodes.
- **mimeType** (string) - Optional - The MIME type of the documents.
- **describeFigures** (boolean) - Optional - Whether to describe figures.
- **extractFigures** (boolean) - Optional - Whether to extract figures.
- **mapReduce** (MapReduceCommand) - Optional - Configuration for map-reduce processing.
- **tools** (array) - Optional - List of tools to be used during processing.
- **trace** (boolean) - Optional - Enable tracing for the request.
- **pageRange** (array) - Optional - Specific page range to process.
```

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

### GET /configuration

Source: https://github.com/docudevs/docs/blob/main/docs/configuration/Configuration.md

Retrieve a list of all saved configurations in your organization.

```APIDOC
## GET /configuration

### Description
Retrieve a list of all saved configurations in your organization.

### Method
GET

### Endpoint
/configuration

### Request Example
```bash
curl -X GET https://api.docudevs.ai/configuration \
  -H "Authorization: Bearer $API_KEY"
```

### Response
#### Success Response (200)
- **configs** (array) - A list of configuration objects.
  - **name** (string) - The name of the configuration.
  - **created_at** (string) - The timestamp when the configuration was created.

### Response Example
```json
[
  {
    "name": "invoice-config",
    "created_at": "2023-10-27T10:00:00Z"
  }
]
```
```

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

### Object Detection JSON Output Example

Source: https://github.com/docudevs/docs/blob/main/docs/core/object-detection.md

This is an example of the structured JSON output you can expect from object detection, including scene summary and detected objects with bounding boxes.

```json
{
  "scene_summary": "A soccer match in progress near the goal.",
  "objects": [
    {
      "name": "goalkeeper in green jersey",
      "object_type": "player",
      "description": "Goalkeeper standing in front of the net.",
      "bbox": {
        "left": 0.61,
        "top": 0.18,
        "right": 0.74,
        "bottom": 0.78
      },
      "confidence": 0.93
    }
  ]
}
```

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

### Retrieve a specific configuration

Source: https://github.com/docudevs/docs/blob/main/docs/configuration/Configuration.md

Get the details of a specific configuration to inspect its settings.

```python
config = await client.get_configuration("invoice-config")
print(f"Prompt: {config.prompt}")
```

```bash
docudevs get-configuration invoice-config
```

```java
import ai.docudevs.client.DocuDevsClient;
import com.fasterxml.jackson.databind.JsonNode;

DocuDevsClient client = DocuDevsClient.builder()
    .apiKey(System.getenv("API_KEY"))
    .build();

JsonNode config = client.getConfiguration("invoice-config");

System.out.println("Prompt: " + config.path("prompt").asText());
System.out.println("OCR: " + config.path("ocr").asText());
System.out.println("LLM: " + config.path("llm").asText());
```

```bash
curl -X GET https://api.docudevs.ai/configuration/invoice-config \
  -H "Authorization: Bearer $API_KEY"
```

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

### GET /job/status/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/status.api.mdx

Retrieves the status of a job identified by its GUID.

```APIDOC
## GET /job/status/{guid}

### Description
Retrieves the status of a job identified by its GUID.

### Method
GET

### Endpoint
/job/status/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the job.

### Response
#### Success Response (200)
- **status** (string) - The current status of the job.
- **guid** (string) - The unique identifier of the job.
- **error** (string | null) - An error message if the job failed, otherwise null.
- **tokenCount** (integer | null) - The number of tokens processed, if applicable.
- **jobType** (string) - The type of job.
- **operationType** (string | null) - The type of operation performed by the job.
- **organizationId** (integer) - The ID of the organization associated with the job.
- **dependsOnGuid** (string | null) - The GUID of a job this job depends on, if any.
- **dependencyStatus** (string) - The status of the job's dependencies.
- **createdAt** (string | null) - The timestamp when the job was created.
- **updatedAt** (string | null) - The timestamp when the job was last updated.

### Response Example
{
  "status": "completed",
  "guid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "error": null,
  "tokenCount": 1500,
  "jobType": "processing",
  "operationType": "text_analysis",
  "organizationId": 123,
  "dependsOnGuid": null,
  "dependencyStatus": "satisfied",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z"
}
```

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

### GET /job/status/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-job-status.api.mdx

Retrieves the status of a job identified by its GUID.

```APIDOC
## GET /job/status/{guid}

### Description
Retrieves the status of a job identified by its GUID.

### Method
GET

### Endpoint
/job/status/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the job.

### Response
#### Success Response (200)
- **status** (string) - The current status of the job.
- **guid** (string) - The unique identifier of the job.
- **error** (string | null) - Any error message associated with the job.
- **tokenCount** (integer | null) - The number of tokens processed.
- **jobType** (string) - The type of the job.
- **operationType** (string | null) - The type of operation performed.
- **organizationId** (integer) - The ID of the organization associated with the job.
- **dependsOnGuid** (string | null) - The GUID of the job this job depends on.
- **dependencyStatus** (string) - The status of the job's dependencies.
- **jobMode** (string) - The mode in which the job is running.
- **totalFragments** (integer | null) - The total number of fragments for the job.
- **completedFragments** (integer | null) - The number of completed fragments.
- **isBatch** (boolean) - Indicates if the job is part of a batch.
- **totalDocs** (integer) - The total number of documents processed.
- **completedDocs** (integer) - The number of documents successfully processed.
- **failedDocs** (integer) - The number of documents that failed processing.
- **maxConcurrency** (integer) - The maximum concurrency level for the job.
- **nextDocIndex** (integer) - The index of the next document to be processed.
- **inProgressDocs** (integer) - The number of documents currently being processed.
- **batchMetadata** (object | null) - Metadata related to batch processing.
- **createdAt** (string | null) - The timestamp when the job was created.
- **updatedAt** (string | null) - The timestamp when the job was last updated.
- **mapReduceStatus** (object | null) - Status details for MapReduce jobs.
  - **totalChunks** (integer | null) - Total number of chunks.
  - **completedChunks** (integer | null) - Number of completed chunks.
  - **headerCaptured** (boolean | null) - Indicates if the header has been captured.
  - **stopWhenEmpty** (boolean | null) - Indicates if the job should stop when empty.
  - **earlyTerminated** (boolean | null) - Indicates if the job was terminated early.
  - **terminationChunkIndex** (integer | null) - The index of the chunk where termination occurred.
  - **terminationReason** (string | null) - The reason for termination.

#### Response Example
```json
{
  "status": "completed",
  "guid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "error": null,
  "tokenCount": 15000,
  "jobType": "document_processing",
  "operationType": "translation",
  "organizationId": 12345,
  "dependsOnGuid": null,
  "dependencyStatus": "satisfied",
  "jobMode": "batch",
  "totalFragments": 10,
  "completedFragments": 10,
  "isBatch": true,
  "totalDocs": 100,
  "completedDocs": 100,
  "failedDocs": 0,
  "maxConcurrency": 5,
  "nextDocIndex": 101,
  "inProgressDocs": 0,
  "batchMetadata": {},
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T11:00:00Z",
  "mapReduceStatus": {
    "totalChunks": 20,
    "completedChunks": 20,
    "headerCaptured": true,
    "stopWhenEmpty": false,
    "earlyTerminated": false,
    "terminationChunkIndex": null,
    "terminationReason": null
  }
}
```
```

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

### GET /job/trace/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-trace.api.mdx

Retrieves trace information for a given job GUID.

```APIDOC
## GET /job/trace/{guid}

### Description
Retrieves trace information for a given job GUID.

### Method
GET

### Endpoint
/job/trace/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the job.

### Response
#### Success Response (200)
- **(empty schema)** - Description of the successful response.

#### Response Example
```json
{}
```
```

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

### GET /job/figures/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-figures-metadata.api.mdx

Retrieves metadata for figures associated with a given GUID.

```APIDOC
## GET /job/figures/{guid}

### Description
Retrieves metadata for figures associated with a given GUID.

### Method
GET

### Endpoint
/job/figures/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier for the figures.
#### Query Parameters
- **batchIndex** (integer) - Optional - The index of the batch to retrieve figures from.

### Response
#### Success Response (200)
- **(empty object)** - Description for the successful response.

#### Response Example
{
  "example": "{}"
}
```

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

### Initialize DocuDevs Client

Source: https://github.com/docudevs/docs/blob/main/docs/basics/install.md

Demonstrates various ways to initialize the client, including direct token usage and environment variable retrieval.

```python
import os
from docudevs.docudevs_client import DocuDevsClient

# Option 1: Direct initialization

client = DocuDevsClient(token="your-api-key-here")

# Option 2: From environment variable

api_key = os.getenv('API_KEY')
client = DocuDevsClient(token=api_key)

# Option 3: With error handling

api_key = os.getenv('API_KEY')
if not api_key:
    raise ValueError("API_KEY environment variable not set")

client = DocuDevsClient(token=api_key)
```

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

### GET /job/dependencies/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-dependencies.api.mdx

Retrieves dependency information for a specific job identified by its GUID.

```APIDOC
## GET /job/dependencies/{guid}

### Description
Retrieves dependency information for a specific job identified by its GUID.

### Method
GET

### Endpoint
/job/dependencies/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the job.

### Response
#### Success Response (200)
- **guid** (string) - The unique identifier of the dependency.
- **dependsOnGuid** (string | null) - The GUID of the job this dependency depends on.
- **dependencyStatus** (string) - The status of the dependency.
- **parentJob** (object | null) - Information about the parent job.
  - **status** (string)
  - **guid** (string)
  - **error** (string | null)
  - **tokenCount** (integer | null)
  - **jobType** (string)
  - **operationType** (string | null)
  - **organizationId** (integer)
  - **dependsOnGuid** (string | null)
  - **dependencyStatus** (string)
  - **createdAt** (string | null) - Formatted as date-time.
  - **updatedAt** (string | null) - Formatted as date-time.

#### Response Example
```json
{
  "guid": "string",
  "dependsOnGuid": "string",
  "dependencyStatus": "string",
  "parentJob": {
    "status": "string",
    "guid": "string",
    "error": "string",
    "tokenCount": 0,
    "jobType": "string",
    "operationType": "string",
    "organizationId": 0,
    "dependsOnGuid": "string",
    "dependencyStatus": "string",
    "createdAt": "2023-01-01T12:00:00Z",
    "updatedAt": "2023-01-01T12:00:00Z"
  }
}
```
```

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

### Submit Document for Processing

Source: https://github.com/docudevs/docs/blob/main/docs/basics/SimpleDocuments.md

Examples of submitting a document for processing using various interfaces.

```java
import ai.docudevs.client.DocuDevsClient;
import ai.docudevs.client.ProcessOptions;
import ai.docudevs.client.UploadRequest;
import ai.docudevs.client.WaitOptions;
import com.fasterxml.jackson.databind.JsonNode;
import java.nio.file.Files;
import java.nio.file.Path;

DocuDevsClient client = DocuDevsClient.builder()
    .apiKey(System.getenv("API_KEY"))
    .baseUrl("https://api.docudevs.ai")
    .build();

String schema = """
{
  "type": "object",
  "properties": {
    "invoice_number": {"type": "string"},
    "total": {"type": "number"}
  }
}
""";

byte[] docBytes = Files.readAllBytes(Path.of("invoice.pdf"));

String guid = client.submitAndProcessDocument(
    new UploadRequest("invoice.pdf", "application/pdf", docBytes),
    ProcessOptions.builder()
        .mimeType("application/pdf")
        .schema(schema)
        .build()
);

JsonNode result = client.waitUntilReadyJson(guid, WaitOptions.builder().build());
System.out.println(result.toPrettyString());
```

```bash
# Save schema to schema.json first
curl -X POST https://api.docudevs.ai/document/upload-files/sync \
  -H "Authorization: Bearer $API_KEY" \
  -F "document=@invoice.pdf" \
  -F "schema=@schema.json"
```

```python
from docudevs import json_schema

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"}
    }
}

guid = await client.submit_and_process_document(
    document=doc_bytes,
    document_mime_type="application/pdf",
    schema=json_schema(schema)
)
```

```bash
docudevs process invoice.pdf --schema-file schema.json
```

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

### GET /job/image/{guid}/{pageIndex}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-image.api.mdx

Retrieves image data based on GUID and page index.

```APIDOC
## GET /job/image/{guid}/{pageIndex}

### Description
Retrieves image data based on GUID and page index.

### Method
GET

### Endpoint
/job/image/{guid}/{pageIndex}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier for the image.
- **pageIndex** (integer) - Required - The index of the page to retrieve.

### Response
#### Success Response (200)
- **(empty object)** - Description for the successful response.

#### Response Example
{
  "example": "{}"
}
```

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

### GET /job/figure/{guid}/{imageId}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-figure-image.api.mdx

Retrieves a figure image based on the provided GUID and image ID, with an optional batch index.

```APIDOC
## GET /job/figure/{guid}/{imageId}

### Description
Retrieves a figure image based on the provided GUID and image ID.

### Method
GET

### Endpoint
/job/figure/{guid}/{imageId}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier for the job.
- **imageId** (string) - Required - The unique identifier for the image.

#### Query Parameters
- **batchIndex** (integer) - Optional - The index of the batch.
```

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

### Initialize DocuDevs Client

Source: https://github.com/docudevs/docs/blob/main/docs/getting-started/first-document.md

Configure the client using an API key retrieved from environment variables.

```python
import os
import asyncio
from docudevs.docudevs_client import DocuDevsClient
import json

# Initialize the client
client = DocuDevsClient(token=os.getenv('API_KEY'))
```

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

### Configure with .env File

Source: https://github.com/docudevs/docs/blob/main/docs/basics/install.md

Use a .env file to manage configuration and load it using python-dotenv.

```bash
# .env file
API_KEY=your-api-key-here
DOCUDEVS_API_URL=https://api.docudevs.ai
```

```python
from dotenv import load_dotenv
import os
from docudevs.docudevs_client import DocuDevsClient

# Load environment variables from .env file
load_dotenv()

client = DocuDevsClient(token=os.getenv('API_KEY'))
```

```bash
pip install python-dotenv
```

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

### GET /agent/status/{jobGuid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-agent-status.api.mdx

Retrieves the status of an agent job by its GUID.

```APIDOC
## GET /agent/status/{jobGuid}

### Description
Retrieves the current status, session information, and any associated response data for a specific agent job.

### Method
GET

### Endpoint
/agent/status/{jobGuid}

### Parameters
#### Path Parameters
- **jobGuid** (string) - Required - The unique identifier for the job.

### Response
#### Success Response (200)
- **jobGuid** (string) - The job identifier.
- **sessionId** (string) - The session identifier.
- **status** (string) - The current status of the job.
- **response** (object) - The agent response content, including messages and actions.
- **error** (string) - Error details if applicable.

#### Response Example
{
  "jobGuid": "string",
  "sessionId": "string",
  "status": "string",
  "response": {
    "message": "string",
    "actions": [
      {
        "type": "string",
        "description": "string",
        "data": {}
      }
    ],
    "suggestedConfig": {},
    "toolsUsed": ["string"]
  },
  "error": "string"
}
```

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

### Example Configuration JSON

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

A sample JSON structure for defining a processing configuration, including prompt, schema, OCR, and LLM settings.

```json
{
  "prompt": "Extract invoice data",
  "schema": "{\"type\": \"object\"}",
  "ocr": "DEFAULT",
  "llm": "DEFAULT"
}
```

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

### Get job result

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Retrieve the result payload for a completed job, identified by its GUID.

```bash
docudevs result JOB_GUID
```

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

### Initialize DocuDevs Client and List Billing Prices

Source: https://github.com/docudevs/docs/blob/main/docs/reference/billing-tokens.md

Instantiate the DocuDevs client with an API token and fetch available token pack prices. Ensure you have your API key and the necessary asynchronous context to run these operations.

```python
from docudevs_client import DocuDevsClient

client = DocuDevsClient(token="your-api-key")

prices = await client.list_billing_prices()
session = await client.create_billing_checkout_session("price_123")
balance = await client.get_billing_balance()
```

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

### GET /operation/{jobGuid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/get-operation-status.api.mdx

Retrieves the status of operations associated with a specific job GUID.

```APIDOC
## GET /operation/{jobGuid}

### Description
Retrieves the status of operations associated with a specific job GUID.

### Method
GET

### Endpoint
/operation/{jobGuid}

### Parameters
#### Path Parameters
- **jobGuid** (string) - Required - The unique identifier for the job.

### Response
#### Success Response (200)
- **parentJobGuid** (string) - The parent job GUID.
- **operations** (array) - List of operations.
  - **jobGuid** (string) - The operation job GUID.
  - **operationType** (string) - The type of operation.
  - **status** (string) - The current status of the operation.
  - **createdAt** (string) - Creation timestamp.
  - **updatedAt** (string) - Last update timestamp.
  - **error** (string|null) - Error message if any.
- **totalOperations** (integer) - Total count of operations.

#### Response Example
{
  "parentJobGuid": "string",
  "operations": [
    {
      "jobGuid": "string",
      "operationType": "string",
      "status": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "error": null
    }
  ],
  "totalOperations": 0
}
```

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

### Client Initialization

Source: https://github.com/docudevs/docs/blob/main/docs/reference/sdk-methods.md

Initialize the DocuDevsClient with your API key. The API URL is optional and defaults to the production environment.

```APIDOC
## Client Initialization

### DocuDevsClient

Initialize the client with your API key.

```python
from docudevs.docudevs_client import DocuDevsClient
import os

client = DocuDevsClient(
    api_url="https://api.docudevs.ai",  # Optional, defaults to production
    token=os.getenv("DOCUDEVS_API_KEY") # Required
)
```
```

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

### GET /job/result/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/basics/PlainOCR.md

Retrieves the final results of a completed OCR processing job.

```APIDOC
## GET /job/result/{guid}

### Description
Fetches the extracted text or markdown content once the job is complete.

### Method
GET

### Endpoint
https://api.docudevs.ai/job/result/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the job.
```

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

### GET /job/status/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/basics/PlainOCR.md

Checks the current status of an asynchronous OCR processing job.

```APIDOC
## GET /job/status/{guid}

### Description
Retrieves the current processing status of a specific job.

### Method
GET

### Endpoint
https://api.docudevs.ai/job/status/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the job.
```

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

### Minimal Python SDK Pipeline Builder

Source: https://github.com/docudevs/docs/blob/main/docs/reference/pipeline-mode.md

A concise example of building a pipeline with OCR and extraction nodes. This demonstrates the core builder pattern for setting up a pipeline.

```python
pipeline = Pipeline().ocr(mode="AUTO", source_locations=True, quality_artifact=True)

extract_data = pipeline.extract(
    "extract_data",
    source=P.ocr.content,
    prompt="Extract the requested fields.",
    schema={"type": "object", "properties": {"name": {"type": "string"}}},
    source_locations=True,
)

pipeline.final(
    "final_result",
    depends_on=[extract_data],
    output=extract_data.result,
)
```

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

### cURL - Get Image

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/tracing.md

Example of how to retrieve a page thumbnail image using cURL.

```APIDOC
## Get page 0 thumbnail
```bash
# Get page 0 thumbnail
curl -X GET https://api.docudevs.ai/job/image/{guid}/0 \
  -H "Authorization: Bearer $API_KEY" \
  --output page_0.png
```
```

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

### List all configurations

Source: https://github.com/docudevs/docs/blob/main/docs/configuration/Configuration.md

Retrieve a list of all saved configurations in the organization.

```python
configs = await client.list_configurations()
for config in configs:
    print(f"Name: {config.name}, Created: {config.created_at}")
```

```bash
docudevs list-configurations
```

```java
import ai.docudevs.client.DocuDevsClient;
import com.fasterxml.jackson.databind.JsonNode;

DocuDevsClient client = DocuDevsClient.builder()
    .apiKey(System.getenv("API_KEY"))
    .build();

JsonNode configs = client.listConfigurations();

for (JsonNode config : configs) {
    System.out.println(config.path("name").asText() + " created=" + config.path("createdAt").asText());
}
```

```bash
curl -X GET https://api.docudevs.ai/configuration \
  -H "Authorization: Bearer $API_KEY"
```

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

### List LLM key bindings

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Display all current key bindings for LLM providers.

```bash
docudevs llm keys
```

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

### Initialize DocuDevsClient

Source: https://github.com/docudevs/docs/blob/main/docs/reference/sdk-methods.md

Initialize the DocuDevs Python SDK client with your API key. The API URL is optional and defaults to the production environment.

```python
from docudevs.docudevs_client import DocuDevsClient
import os

client = DocuDevsClient(
    api_url="https://api.docudevs.ai",  # Optional, defaults to production
    token=os.getenv("DOCUDEVS_API_KEY") # Required
)
```

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

### Organize Documents into Cases in Python

Source: https://github.com/docudevs/docs/blob/main/docs/getting-started/first-document.md

Demonstrates creating a case, uploading multiple documents to that case, and processing them individually.

```python
async def process_with_case_organization():
    # Create a case for related documents
    case_data = {
        "name": "January 2024 Vendor Invoices",
        "description": "All vendor invoices received in January 2024"
    }
    
    case_response = await client.create_case(case_data)
    case_id = case_response.parsed.id
    print(f"Created case: {case_id}")
    
    # Upload documents to the case
    invoice_files = ["vendor1_invoice.pdf", "vendor2_invoice.pdf"]
    
    for filename in invoice_files:
        with open(filename, "rb") as f:
            document_data = f.read()
        
        doc_response = await client.upload_case_document(
            case_id=case_id,
            document=document_data,
            filename=filename
        )
        
        print(f"Uploaded {filename} to case {case_id}")
        
        # Process the document
        document_id = doc_response.parsed.document_id
        process_response = await client.process_document(
            guid=document_id,
            instruction="Extract invoice data"
        )
        
        result = await client.wait_until_ready(process_response.parsed.guid, result_format="json")
        print(f"Processed {filename}")
    
    # List all documents in the case
    docs_response = await client.list_case_documents(case_id)
    print(f"Case contains {len(docs_response.parsed.content)} documents")

# Run case-based processing
await process_with_case_organization()
```

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

### Create Case and Upload Document

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/cases.md

Demonstrates the workflow of creating a new case and uploading a document to it using the Python SDK.

```python
from docudevs.models import CasesControllerCreateCaseRequest, UploadCaseDocumentBody
from docudevs.types import File
import json

# Step 1: Create a case first
case_request = CasesControllerCreateCaseRequest(
    name="Contract Review",
    description="Contract documents for review"
)
case_response = await client.create_case(case_request)
case = case_response.parsed
case_id = case.id

# Step 2: Upload document to case
with open("contract.pdf", "rb") as f:
    document_data = f.read()

upload_body = UploadCaseDocumentBody(
    document=File(payload=document_data, file_name="contract.pdf")
)
upload_response = await client.upload_case_document(case_id=case_id, body=upload_body)
document = upload_response.parsed

print(f"Uploaded document {document.document_id} to case {case_id}")
```

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

### Save and Get Pipeline Configuration

Source: https://github.com/docudevs/docs/blob/main/docs/reference/sdk-methods.md

Saves a named pipeline configuration and retrieves it later. Useful for reusing specific processing setups.

```python
await client.save_pipeline_configuration(
    "router-pipeline",
    pipeline=pipeline,
    mime_type="application/pdf",
    ocr="AUTO"
)

saved_pipeline = await client.get_pipeline_configuration("router-pipeline")
```

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

### Promote Case to Knowledge Base

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Promote an existing case to become a knowledge base, making its content available for broader use.

```bash
docudevs knowledge-base add CASE_ID
```

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

### Create New Case

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Create a new case with a specified name and description for organizing documents.

```bash
docudevs cases create --name "Quarterly Invoices" --description "Q4 2024 invoice processing"
```

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

### DELETE /job/{guid}

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/delete-job.api.mdx

Deletes a specific job identified by its GUID.

```APIDOC
## DELETE /job/{guid}

### Description
Deletes a specific job identified by its GUID.

### Method
DELETE

### Endpoint
/job/{guid}

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the job to delete.

### Request Body
This endpoint does not accept a request body.

### Response
#### Success Response (200)
- **jobsDeleted** (integer) - The number of jobs successfully deleted.
- **errors** (array of strings) - A list of any errors encountered during the deletion process.

#### Response Example
```json
{
  "jobsDeleted": 1,
  "errors": []
}
```
```

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

### Build Static Site

Source: https://github.com/docudevs/docs/blob/main/README.md

Compiles the project into static assets located in the build directory.

```bash
$ yarn build
```

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

### POST /document/batch/{guid}/schedule

Source: https://github.com/docudevs/docs/blob/main/docs/openapi/schedule-batch.api.mdx

Schedules a batch process for a given document GUID.

```APIDOC
## POST /document/batch/{guid}/schedule

### Description
Schedules a batch process for a given document GUID.

### Method
POST

### Endpoint
/document/batch/{guid}/schedule

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the document batch.

#### Request Body
- **orgId** (string) - Required - The identifier of the organization.

### Request Example
```json
{
  "orgId": "your_org_id"
}
```

### Response
#### Success Response (200)
- **jobGuid** (string) - The unique identifier for the scheduled job.
- **scheduled** (integer) - The timestamp when the job was scheduled.
- **status** (string) - The status of the scheduling operation.
```

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

### Configure Knowledge Base Evaluate Tool

Source: https://github.com/docudevs/docs/blob/main/docs/core/knowledge-search.md

Sets up the evaluation tool for complex analysis scenarios, allowing the LLM to select an optimal strategy.

```json
{
  "tools": [
    {
      "type": "KNOWLEDGE_BASE_EVALUATE",
      "config": {
        "caseId": "123",
        "strategy": "auto"
      }
    }
  ]
}
```

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

### Create a checkout session for a token pack

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Initiate a checkout session for purchasing a specific token pack, identified by its price ID.

```bash
docudevs billing checkout PRICE_ID
```

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

### List available token pack prices

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Display a list of all available token pack prices for managing billing.

```bash
docudevs billing prices
```

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

### Error Analysis CLI Example

Source: https://github.com/docudevs/docs/blob/main/docs/advanced/operations.md

Example of how to submit an error analysis operation using the CLI.

```APIDOC
## CLI Example for Error Analysis

### Description
This example shows how to submit an error analysis operation using the DocuDevs CLI and specify a timeout for waiting for completion.

### Usage
```bash
# Submit error analysis and wait for completion
docudevs operations error-analysis JOB_GUID --timeout 180
```
```

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

### Create an OCR provider

Source: https://github.com/docudevs/docs/blob/main/docs/reference/cli-reference.md

Add a new OCR provider, specifying its name, endpoint, and API key.

```bash
docudevs ocr create --name "My Azure OCR" --endpoint "https://..." --api-key "..."
```

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

### Provide Context and Format Instructions in Prompts

Source: https://github.com/docudevs/docs/blob/main/docs/core/ai-analysis.md

Enhances prompt effectiveness by including context and explicit formatting instructions. This guides the AI to produce structured and relevant output.

```python
prompt = """Analyze this financial report and provide:
1. Revenue trends (increase/decrease and percentages)
2. Key financial metrics (profit margin, ROI, etc.)  
3. Risk factors mentioned
4. Management outlook/guidance

Format your response with clear headings for each section."""
```

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

### Execute Batch Processing Workflow

Source: https://github.com/docudevs/docs/blob/main/docs/core/batch-processing.md

Demonstrates the full lifecycle of creating a batch, uploading files, processing with a schema, and awaiting results.

```python
import asyncio
import os
from docudevs import DocuDevsClient, json_schema

async def run_batch():
    client = DocuDevsClient(token=os.environ["API_KEY"])

    # 1. Create Batch
    batch_guid = await client.create_batch(max_concurrency=3)
    print(f"Created batch: {batch_guid}")

    # 2. Upload Documents
    files = ["invoice_jan.pdf", "invoice_feb.pdf", "invoice_mar.pdf"]
    for path in files:
        with open(path, "rb") as f:
            await client.upload_batch_document(
                batch_guid=batch_guid,
                document=f.read(),
                mime_type="application/pdf",
                file_name=os.path.basename(path),
            )
    print(f"Uploaded {len(files)} documents.")

    # 3. Process Batch
    schema = {
        "statements": [{
            "date": "date",
            "customer": "string",
            "total": "number"
        }]
    }
    
    await client.process_batch(
        batch_guid=batch_guid,
        mime_type="application/pdf",
        prompt="Extract statement details.",
        schema=json_schema(schema),
    )
    print("Processing started...")

    # 4. Wait for Results
    results = await client.wait_until_ready(
        batch_guid,
        poll_interval=2,
        result_format="json",
    )

    # 5. Handle Results
    for i, result in enumerate(results):
        if isinstance(result, str):
            print(f"Doc {i} Error: {result}")
        elif result is None:
            print(f"Doc {i} Pending/Failed")
        else:
            print(f"Doc {i} Data: {result}")

if __name__ == "__main__":
    asyncio.run(run_batch())
```

```java
import ai.docudevs.client.DocuDevsClient;
import ai.docudevs.client.ProcessOptions;
import ai.docudevs.client.UploadRequest;
import ai.docudevs.client.WaitOptions;
import com.fasterxml.jackson.databind.JsonNode;
import java.nio.file.Files;
import java.nio.file.Path;

DocuDevsClient client = DocuDevsClient.builder()
    .apiKey(System.getenv("API_KEY"))
    .build();

// 1. Create Batch
String batchGuid = client.createBatch(3);
System.out.println("Created batch: " + batchGuid);

// 2. Upload Documents
for (String path : new String[]{"invoice_jan.pdf", "invoice_feb.pdf", "invoice_mar.pdf"}) {
    byte[] fileBytes = Files.readAllBytes(Path.of(path));
    UploadRequest upload = new UploadRequest(path, "application/pdf", fileBytes);
    client.uploadBatchDocument(batchGuid, upload);
    System.out.println("Uploaded " + path);
}

// 3. Process Batch
String schema = """
{
  "type": "object",
  "properties": {
    "statements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {"type": "string"},
          "customer": {"type": "string"},
          "total": {"type": "number"}
        }
      }
    }
  }
}
""";

ProcessOptions options = ProcessOptions.builder()
    .prompt("Extract statement details.")
    .schema(schema)
    .build();

client.processBatch(batchGuid, options);
System.out.println("Processing started...");

// 4. Wait and Fetch Results
JsonNode results = client.waitUntilReadyJson(batchGuid, WaitOptions.defaults());
System.out.println(results);
```