Java Client SDK (`oc-java-client-sdk`)

Programmatic Ingestion Control for Enterprise Java

A strongly typed, fluent Java 25 client SDK designed to manage document ingestion pipelines, connector registration, Auto-Narrativization Copilot workflows, and AIOps observability directly from your Java & Spring Boot microservices.

View Usage Examples Install via Maven

Fluent Client API

Type-safe builder patterns for client configuration, custom endpoints, HTTP timeouts, authentication headers, and reactive execution.

Job Lifecycle Control

Create, start, pause, stop, and monitor document ingestion pipelines asynchronously with full standard OIS model compliance.

Auto-Narrativization Copilot

Trigger AI-driven narrative generation from connector schemas, test dry-run outputs, and update Mustache templates programmatically.

AIOps Observability & RCA

Query automated Root Cause Analysis (RCA) reports, correlated OpenTelemetry spans, and live pipeline throughput metrics.

Spring Boot Starter

Seamless autoconfiguration via `opencrawling.client.*` properties and injectable `OpenCrawlingClient` beans in Spring components.

Java 25 & Zero-Dependency

Built with native `java.net.http.HttpClient` leveraging Virtual Threads for non-blocking I/O with zero external transport bloat.

Interactive Usage Examples

OpenCrawlingClientInitialization.java

import org.opencrawling.sdk.OpenCrawlingClient;
import java.time.Duration;

// Initialize OpenCrawlingClient with fluent configuration
OpenCrawlingClient client = OpenCrawlingClient.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("oc-api-key-enterprise-prod")
        .connectTimeout(Duration.ofSeconds(10))
        .readTimeout(Duration.ofSeconds(30))
        .build();

System.out.println("Connected to OpenCrawling REST API!");

JobManagementExample.java

import org.opencrawling.sdk.models.JobRequest;
import org.opencrawling.sdk.models.JobResponse;
import org.opencrawling.sdk.models.NarrativizationConfig;

// Create job with Auto-Narrativization enabled
JobResponse job = client.jobs().create(
    JobRequest.builder()
        .name("Enterprise Documentation Crawler")
        .targetUrl("https://docs.example.com")
        .repositoryConnector("FileSystem_Local")
        .outputConnector("PGVector_Output")
        .transformationConnector("Ollama_Embedding_Default")
        .narrativization(NarrativizationConfig.builder()
            .enabled(true)
            .template("Document titled {{title}} with content: {{content}}")
            .build())
        .build()
);

System.out.println("Job created with ID: " + job.id());

// Trigger immediate job execution
client.jobs().start(job.id());

ConnectorRegistrationExample.java

import org.opencrawling.sdk.models.ConnectorRequest;
import org.opencrawling.sdk.models.ConnectorResponse;

// Register custom PGVector output store connector
ConnectorResponse connector = client.connectors().create(
    ConnectorRequest.builder()
        .name("Custom_PGVector_Output")
        .description("Custom PGVector Vector Store Output Connector")
        .type("output")
        .className("org.opencrawling.vector.VectorOutputConnector")
        .maxConnections(20)
        .addConfiguration("pgVectorUrl", "jdbc:postgresql://localhost:5432/opencrawling")
        .addConfiguration("tableName", "vector_embeddings_ais")
        .build()
);

System.out.println("Registered connector: " + connector.name());

AutoNarrativizationCopilot.java

import org.opencrawling.sdk.models.CopilotRequest;
import org.opencrawling.sdk.models.CopilotResponse;

// Trigger AI Copilot to generate Mustache narrative template
CopilotResponse copilotResponse = client.narrativization().generateTemplate(
    CopilotRequest.builder()
        .connectorType("repository")
        .addField("title", "string", "Document Title")
        .addField("content", "string", "Extracted body text content")
        .addField("author", "string", "Document creator/author")
        .build()
);

System.out.println("Generated Template:\n" + copilotResponse.template());

AIOpsObservabilityExample.java

import org.opencrawling.sdk.models.DiagnosticReport;
import org.opencrawling.sdk.models.JobTraceResponse;

// Fetch AI-powered Root Cause Analysis (RCA) report
DiagnosticReport report = client.observability().diagnose("job-123");
System.out.println("Health Status: " + report.status());
System.out.println("AI Summary: " + report.summary());

// Query correlated OpenTelemetry spans for trace inspection
JobTraceResponse traces = client.observability().getTraces("job-123");
System.out.println("Total Spans: " + traces.totalSpans() + ", Duration: " + traces.totalDurationMillis() + "ms");

SpringIntegrationService.java

// application.yml
opencrawling:
  client:
    base-url: http://localhost:8080
    api-key: your-api-key
    connect-timeout: 10s
    read-timeout: 30s

// Spring Service
import org.opencrawling.sdk.OpenCrawlingClient;
import org.springframework.stereotype.Service;

@Service
public class DocumentIngestionService {

    private final OpenCrawlingClient client;

    public DocumentIngestionService(OpenCrawlingClient client) {
        this.client = client;
    }

    public void triggerJob(String jobId) {
        client.jobs().start(jobId);
    }
}

Add to Your Project

Deploying via Maven Central or local repository dependency.

pom.xml

<dependency>
    <groupId>org.opencrawling</groupId>
    <artifactId>oc-java-client-sdk</artifactId>
    <version>1.0.0</version>
</dependency>