LLM Providers

LLMClient client = LLMClientFactory.create("openai", "gpt-4o", 0.7f);
ChatResponse response = client.chat("What is quantum computing?");

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

// Basic — provider name, model, temperature
LLMClient client = LLMClientFactory.create("openai", "gpt-4o", 0.7f);

// With max tokens
LLMClient client = LLMClientFactory.create("anthropic", "claude-sonnet-4-20250514", 0.7f, 4096);

// With topP (nucleus sampling)
LLMClient client = LLMClientFactory.create("gemini", "gemini-2.5-flash", 0.7f, 2048, 0.95f);

// From @RoleSpec annotation
LLMClient client = LLMClientFactory.fromAnnotation(MyRole.class);

// OpenAI with custom settings
LLMClient client = new OpenAIClient("gpt-4o", 0.7f, 0.95f, 4096);

// Anthropic with custom API key
LLMClient client = new AnthropicClient("claude-sonnet-4-20250514", "sk-ant-...");

// Ollama with custom base URL
LLMClient client = new OllamaClient("http://gpu-server:11434", "llama3", 0.7f, 4096, null);

// Azure with endpoint
LLMClient client = new AzureOpenAIClient("gpt-4", "your-api-key", "https://myresource.openai.azure.com/");

// Text stream
Stream<String> tokens = client.streamChat("Tell me a story");

// ChatChunk stream
Stream<ChatChunk> chunks = client.streamChatWithSpec(request);

// Handler-based
client.streamChatWithHandler(request, chunk -> { ... });

LLMClient resilient = CircuitBreakerClient.builder()
    .client(openaiClient)
    .failureThreshold(3)
    .recoveryTimeout(Duration.ofSeconds(60))
    .build();

// Single observer
LLMClient observable = new ObservableLLMClient(client, metrics);

// Multiple observers (varargs)
LLMClient observable = new ObservableLLMClient(client, metrics, promptLogger, auditObserver);

LLMObserver myObserver = new LLMObserver() {
    @Override
    public void onRequest(LLMClient client, String message,
                          Optional<String> systemPrompt,
                          Optional<List<Map<String, Object>>> history,
                          Optional<List<Map<String, Object>>> tools) {
        log.info("Request to {}: {}", client.getModel(), message);
    }

    @Override
    public void onResponse(LLMClient client, ChatResponse response, long latencyMs) {
        log.info("Response from {} ({}ms)", client.getModel(), latencyMs);
    }
};

LLMClient observed = new ObservableLLMClient(client, myObserver);

LLMObserver combined = CompositeObserver.of(metricsObserver, loggingObserver, auditObserver);

PromptLogger promptLogger = PromptLogger.builder()
    .filterPII(true)            // default: true
    .logLevel(PromptLogger.LogLevel.INFO)  // DEBUG, INFO, or WARN
    .maxContentLength(500)      // default: 200 chars
    .logFullContent(false)      // true to disable truncation
    .build();

LLMClient observed = new ObservableLLMClient(client, promptLogger);

PromptLogger.withPIIFiltering();   // PII enabled, defaults
PromptLogger.withoutFiltering();   // PII disabled, defaults

[INFO] LLM Request [req-abc123] OpenAI/gpt-4o: "My email is [REDACTED_EMAIL]"
[INFO] LLM Response [req-abc123] OpenAI/gpt-4o (245ms): "The answer is 4"

[INFO]   Tool call: calculator({"expression":"2+2"})

LLMMetrics metrics = new LLMMetrics();
LLMClient observed = new ObservableLLMClient(client, metrics);

// Use the client normally
observed.chat("Hello!");

LLMMetrics.Report report = metrics.getReport();
report.totalRequests();      // total request count
report.totalResponses();     // successful responses
report.totalErrors();        // error count
report.totalInputTokens();   // estimated input tokens
report.totalOutputTokens();  // estimated output tokens
report.totalEstimatedCost(); // cost in USD (based on provider pricing)
report.avgLatencyMs();       // average latency
report.p50LatencyMs();       // median latency
report.p95LatencyMs();       // 95th percentile latency
report.p99LatencyMs();       // 99th percentile latency
report.successRate();        // percentage (0-100)
report.errorRate();          // percentage (0-100)
report.timestamp();          // Instant of report generation

Map<String, LLMMetrics.ProviderMetrics> byProvider = metrics.getMetricsByProvider();
for (var entry : byProvider.entrySet()) {
    String providerKey = entry.getKey(); // e.g. "OpenAI/gpt-4o"
    LLMMetrics.ProviderMetrics pm = entry.getValue();
    pm.requests();       // request count for this provider
    pm.responses();      // successful responses
    pm.errors();         // errors
    pm.inputTokens();    // estimated input tokens
    pm.outputTokens();   // estimated output tokens
    pm.estimatedCost();  // cost in USD
    pm.avgLatencyMs();   // average latency
    pm.streamChunks();   // total streaming chunks
    pm.successRate();    // percentage (0-100)
    pm.errorRate();      // percentage (0-100)
}

LLMMetrics metrics = new LLMMetrics();
PromptLogger logger = PromptLogger.withPIIFiltering();

LLMClient observed = new ObservableLLMClient(client, metrics, logger);

// Simple wrap -- uses JSON_OBJECT format, auto-detects native support
JsonModeClient client = JsonModeClient.wrap(baseClient);

ChatResponse response = client.chat("List 3 programming languages");
// {"languages": ["Python", "Java", "JavaScript"]}

JsonModeClient client = JsonModeClient.builder()
    .client(baseClient)                      // Required: LLM client to wrap
    .responseFormat(format)                   // ResponseFormat (default: jsonObject())
    .objectMapper(customMapper)              // Custom Jackson ObjectMapper
    .forcePromptEngineering(true)            // Skip native JSON mode, use prompt injection
    .schemaFromClass("Person", Person.class) // Auto-generate schema from class
    .build();

record LanguageList(List<String> languages) {}

// Simple
LanguageList list = client.chatAs(LanguageList.class, "List 3 programming languages");

// With system prompt
LanguageList list = client.chatAs(LanguageList.class, "List 3 languages",
    Optional.of("You are a helpful assistant"));

// Full parameters
LanguageList list = client.chatAs(LanguageList.class, message, systemPrompt, history, tools);

// Plain text (default LLM behavior)
ResponseFormat text = ResponseFormat.text();

// JSON object (valid JSON, structure not enforced)
ResponseFormat json = ResponseFormat.jsonObject();

// JSON Schema (valid JSON conforming to a schema)
ResponseFormat schema = ResponseFormat.jsonSchema("Person", Map.of(
    "type", "object",
    "properties", Map.of(
        "name", Map.of("type", "string"),
        "age", Map.of("type", "integer")
    ),
    "required", List.of("name", "age")
));

// JSON Schema from a Java class (uses SchemaGenerator)
ResponseFormat schema = ResponseFormat.jsonSchema("Person", Person.class);

public record Person(String name, int age, List<String> hobbies) {}

Map<String, Object> schema = SchemaGenerator.generateSchema(Person.class);
// {"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer"},
//  "hobbies":{"type":"array","items":{"type":"string"}}},"required":["name","age","hobbies"]}

// Record-specific (all components required)
Map<String, Object> schema = SchemaGenerator.generateRecordSchema(Person.class);

LLMClient client = new OpenAIClient("gpt-4o");
LLMCapabilities caps = client.getCapabilities();

// Check before use
if (caps.supportsVision()) {
    response = client.chat(List.of(textPart, imagePart), system, history, tools);
}

// Context window check
if (estimatedTokens > caps.getMaxInputTokens()) {
    // Truncate or summarize
}

Set<LLMCapabilities.Modality> modalities = caps.getSupportedModalities();
boolean canHandleAudio = caps.supportsModality(Modality.AUDIO);

boolean suitable = caps.meetsRequirements(
    true,   // requiresVision
    true,   // requiresTools
    32000   // minContextTokens
);

caps.requireToolCalling();  // throws ToolCallNotSupportedException
caps.requireStreaming();     // throws LLMCapabilityException
caps.requireVision();        // throws LLMCapabilityException

// Create image part from Base64 data
ImagePart image = ImagePart.fromBase64(base64Data, "image/png");

// Build multimodal message
List<ContentPart> parts = List.of(
    new TextPart("What do you see in this image?"),
    image
);

// Send to a vision-capable model
ChatResponse response = client.chat(parts,
    Optional.of("You are a helpful assistant"),
    Optional.empty(),
    Optional.empty()
);

// From file
AudioPart audio = AudioPart.fromFile(new File("recording.mp3"));

// From Base64
AudioPart audio = AudioPart.fromBase64(base64String, "audio/wav");

// From byte array
AudioPart audio = AudioPart.fromBytes(rawBytes, "audio/mp3");

// From URL
AudioPart audio = AudioPart.fromUrl("https://example.com/audio.mp3");

// Send as multimodal message
List<ContentPart> parts = List.of(
    new TextPart("Transcribe this audio"),
    audio
);
ChatResponse response = client.chat(parts, systemPrompt, history, tools);

LLMCapabilities caps = client.getCapabilities();

if (caps.supportsVision()) {
    // Safe to send ImagePart
    client.chat(List.of(new TextPart("Describe this"), image), system, history, tools);
} else {
    // Fall back to text-only
    client.chat("Describe the concept", system, history, tools);
}

# META-INF/services/com.tnsai.llm.LLMClientProvider
com.tnsai.llm.LLMClientFactoryProvider