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.

OIS Document Lifecycle & Job Control

Create, start, pause, stop, and monitor document ingestion pipelines with full compliance for OIS models and DocumentAction (UPSERT / DELETE tombstones).

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.1</version>
</dependency>