Arconia Docling

Arconia provides seamless integration with Docling, a powerful AI-powered document conversion service that transforms documents into structured formats like Markdown. The integration is based on the Docling Java project and provides an auto-configured DoclingServeApi that can be used in Spring Boot applications to interact with a Docling Serve API for converting various document formats including PDFs, Word documents, and web pages.

Quick Start

Let’s see how you can get started with Arconia Docling in your Spring Boot application.

Dependencies

To add Docling support to your Spring Boot application, include the Arconia Docling Spring Boot Starter dependency in your project.

Gradle
Maven

dependencies {
    implementation 'io.arconia:arconia-docling-spring-boot-starter'
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-docling-spring-boot-starter</artifactId>
</dependency>

Arconia publishes a BOM (Bill of Materials) that you can use to manage the version of the Arconia libraries. While not required, it is recommended to use the BOM to ensure that all dependencies are compatible.

Gradle
Maven

dependencyManagement {
    imports {
        mavenBom "io.arconia:arconia-bom:0.31.0"
    }
}

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.arconia</groupId>
            <artifactId>arconia-bom</artifactId>
            <version>0.31.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Dev Services

Arconia Dev Services provide zero-code integrations for services your application depends on, both at development and test time, relying on the power of Testcontainers and Spring Boot.

When working with Docling, you can use the Docling Dev Service to automatically start a Docling Serve instance during development and testing, giving you the possibility to convert documents without manually setting up a Docling Serve instance.

To enable the Docling Dev Service, add the following dependency to your project:

Gradle
Maven

dependencies {
    testAndDevelopmentOnly "io.arconia:arconia-dev-services-docling"
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-docling</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

By default, the Dev Service is configured to expose the Docling Serve UI on a specific port. The application logs will show you the URL where you can access that.

... Docling Serve UI: http://localhost:<port>/ui

Running the Application

When using the Arconia Dev Services, you can keep running your application as you normally would. The Dev Services will automatically start when you run your application.

Gradle
Maven
CLI

./gradlew bootRun

./mvnw spring-boot:run

arconia dev

Unlike the lower-level Testcontainers support in Spring Boot, Arconia doesn’t require special tasks to run your application when using Dev Services (./gradlew bootTestRun or ./mvnw spring-boot:test-run) nor requires you to define a separate @SpringBootApplication class for configuring Testcontainers.

The application logs will show you the URL where you can access the Docling Serve UI for interactive document conversion.

Configuration

The Arconia Docling integration provides sensible defaults for connecting to a Docling Serve API. You can customize the connection settings and timeouts via configuration properties.

Table 1. Docling Client Configuration Properties
Property	Default	Description
`arconia.docling.base-url`	`http://localhost:5001`	Base URL for the Docling Serve API.
`arconia.docling.api-key`	``	API key to be used for authenticating requests to the Docling Serve API.
`arconia.docling.connect-timeout`	`5s`	Timeout to establish a connection to the Docling Serve API.
`arconia.docling.read-timeout`	`30s`	Timeout for receiving a response from the Docling Serve API.
`arconia.docling.log-requests`	`false`	Whether to log the requests sent to the Docling Serve API. The API key is masked.
`arconia.docling.log-responses`	`false`	Whether to log the responses received from the Docling Serve API. Non-JSON bodies, such as zip archives, are not logged.
`arconia.docling.pretty-print`	`false`	Whether to pretty-print the JSON bodies of the logged requests and responses.

Actuator

Health Indicator

When Spring Boot Actuator is present on the classpath, Arconia automatically configures a health indicator for the Docling integration. This health indicator checks the connectivity to the Docling Serve API by calling its health endpoint. You can customize it via configuration properties.

Table 2. Health Configuration Properties
Property	Default	Description
`management.health.docling.enabled`	`true`	Whether the Docling health indicator should be enabled.

When enabled, the health status will be included in the actuator /health endpoint response, showing whether the Docling Serve API is reachable and operational.

When health details are shown, the response also includes the location of the Docling Serve instance (its base URL). In case of failure, the response includes the status reported by Docling Serve or the error that prevented the check from completing.

{
  "status": "DOWN",
  "details": {
    "location": "http://localhost:5001",
    "status": "unhealthy"
  }
}

Using the Docling Client

Once you have added the dependency and optionally configured the connection settings, you can autowire and use the auto-configured DoclingServeApi in your Spring components.

Basic Usage

@Component
public class DocumentService {

    private final DoclingServeApi doclingClient;

    public DocumentService(DoclingServeApi doclingClient) {
        this.doclingClient = doclingClient;
    }

    public String convertWebPage(String url) {
        ConvertDocumentRequest request = ConvertDocumentRequest.builder()
                .source(HttpSource.builder().url(url).build())
                .build();

        InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) doclingServeApi.convertSource(request);
        return response.getDocument().getMarkdownContent();
    }
}

Building a Client Manually

Arconia registers a DoclingServeApiProvider, so the standard DoclingServeApi.builder() entry point from Docling Java resolves to the Arconia client as well. That’s useful outside the Spring context, for example in tests, or to create a modified copy of the auto-configured client via config().toBuilder().

DoclingServeApi doclingClient = DoclingServeApi.builder()
        .baseUrl("http://localhost:5001")
        .readTimeout(Duration.ofMinutes(2))
        .build();

DoclingServeApi slowerClient = doclingClient.config().toBuilder()
        .readTimeout(Duration.ofMinutes(5))
        .build();

The async operations of the Arconia client don’t poll for the task status, so the asyncPollInterval and asyncTimeout options are ignored with a warning. They run on virtual threads unless you pass your own asyncExecutor. To customize the underlying RestClient, use DoclingServeClient.builder() directly.

Converting HTTP Sources

You can convert web pages or documents accessible via HTTP/HTTPS URLs:

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
        .source(HttpSource.builder()
            .url(URI.create("https://docs.arconia.io/arconia/latest/integrations/docling/"))
            .build())
        .build();

InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) doclingClient.convertSource(request);
String markdownContent = response.getDocument().getMarkdownContent();
String filename = response.getDocument().getFilename();

Converting File Sources

You can also convert local files by encoding them as Base64:

byte[] fileContent = new ClassPathResource("document.pdf").getContentAsByteArray();
String base64Content = Base64.getEncoder().encodeToString(fileContent);

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
        .source(FileSource.builder()
            .filename("document.pdf")
            .base64String(base64Content)
            .build())
        .build();

InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) doclingClient.convertSource(request);
String markdownContent = response.getDocument().getMarkdownContent();

Conversion Options

You can customize the conversion process using ConvertDocumentOptions:

ConvertDocumentOptions options = ConvertDocumentOptions.builder()
        .includeImages(true)
        .doOcr(true)
        .build();

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
        .source(HttpSource.builder()
            .url(URI.create("https://docs.arconia.io/arconia/latest/integrations/docling/"))
            .build())
        .options(options)
        .build();

ConvertDocumentResponse response = doclingClient.convertSource(request);

Error Handling

When the Docling Serve API rejects a request, the DoclingServeApi throws a ValidationException from Docling Java, carrying the validation details reported by the API. Any other error condition results in the runtime exceptions of the underlying RestClient.

try {
    ConvertDocumentRequest request = ConvertDocumentRequest.builder()
            .source(HttpSource.builder()
                .url(URI.create("https://invalid-url.com/document.pdf"))
                .build())
            .build();
    ConvertDocumentResponse response = doclingClient.convertSource(request);
} catch (ValidationException ex) {
    ex.getValidationError().getErrorDetails()
            .forEach(detail -> log.warn("Invalid request: {} at {}", detail.getMessage(), detail.getLocations()));
} catch (HttpClientErrorException ex) {
    log.error("Client error during conversion: {}", ex.getMessage());
} catch (HttpServerErrorException ex) {
    log.error("Server error during conversion: {}", ex.getMessage());
}

Health Check

You can also programmatically check the health of the Docling Serve service:

HealthCheckResponse health = doclingClient.health();
if ("ok".equals(health.getStatus())) {
    // Docling server is healthy
} else {
    // Handle unhealthy server
}