GitHub - singlr-ai/helios: Production-grade agentic framework for Java. Simple, explicit, no magic.

<!-- Core — always required -->
<dependency>
    <groupId>ai.singlr</groupId>
    <artifactId>helios-core</artifactId>
    <version>${helios.version}</version>
</dependency>

<!-- Gemini provider — for LLM chat, streaming, tool calling -->
<dependency>
    <groupId>ai.singlr</groupId>
    <artifactId>helios-gemini</artifactId>
    <version>${helios.version}</version>
</dependency>

<!-- ONNX embeddings — for local vector embeddings -->
<dependency>
    <groupId>ai.singlr</groupId>
    <artifactId>helios-onnx</artifactId>
    <version>${helios.version}</version>
</dependency>

<!-- PostgreSQL persistence — for memory, prompt versioning, and trace storage -->
<dependency>
    <groupId>ai.singlr</groupId>
    <artifactId>helios-persistence</artifactId>
    <version>${helios.version}</version>
</dependency>

requires ai.singlr.core;
requires ai.singlr.gemini;       // if using Gemini
requires ai.singlr.onnx;         // if using ONNX embeddings
requires ai.singlr.persistence;  // if using persistence

var config = ModelConfig.of("your-api-key");
var model = new GeminiModel(GeminiModelId.GEMINI_3_FLASH_PREVIEW, config);

var agent = new Agent(AgentConfig.newBuilder()
    .withName("assistant")
    .withModel(model)
    .withSystemPrompt("You are a helpful assistant.")
    .build());

// Quick — get the value or throw
var response = agent.run("What is the capital of France?").getOrThrow();
System.out.println(response.content());

// Or pattern match for full control
switch (agent.run("What is the capital of France?")) {
    case Result.Success<Response>(var r) -> System.out.println(r.content());
    case Result.Failure<Response>(var error, var cause) -> System.err.println(error);
}

var weatherTool = Tool.newBuilder()
    .withName("get_weather")
    .withDescription("Gets the current weather for a city")
    .withParameter(ToolParameter.newBuilder()
        .withName("city")
        .withType(ParameterType.STRING)
        .withDescription("City name")
        .withRequired(true)
        .build())
    .withExecutor(args -> {
        var city = (String) args.get("city");
        return ToolResult.success("72°F and sunny in " + city);
    })
    .build();

var agent = new Agent(AgentConfig.newBuilder()
    .withName("weather-bot")
    .withModel(model)
    .withTool(weatherTool)
    .build());

var memory = new InMemoryMemory();
memory.putBlock(MemoryBlock.of("user_profile", Map.of(
    "name", "Alice",
    "preferences", "concise answers"
)));

var agent = new Agent(AgentConfig.newBuilder()
    .withName("assistant")
    .withModel(model)
    .withMemory(memory)
    .build());

record Sentiment(String label, double confidence) {}

Response<Sentiment> response = model.chat(messages, OutputSchema.of(Sentiment.class));
Sentiment sentiment = response.parsed();

var events = model.chatStream(messages, tools);
while (events.hasNext()) {
    switch (events.next()) {
        case StreamEvent.TextDelta d -> System.out.print(d.text());
        case StreamEvent.ToolCallComplete tc -> System.out.println("Called: " + tc.toolCall().name());
        case StreamEvent.Done d -> System.out.println("\nDone: " + d.response().content());
        case StreamEvent.Error e -> System.err.println(e.message());
        default -> {}
    }
}

var events = model.chatStream(messages, List.of());
try {
    // process some events, then bail out
} finally {
    if (events instanceof java.io.Closeable c) c.close();
}

// Create an embedding model — the provider knows the model's dimensions and settings
try (var model = EmbeddingProvider.resolve(OnnxModelId.NOMIC_EMBED_V1_5.id(), EmbeddingConfig.defaults())) {

    // Embed text
    var result = model.embed("A man is eating food.");
    float[] embedding = result.getOrThrow(); // 768-dim vector

    // Query vs document embeddings (some models use different prefixes)
    var queryEmb = model.embedQuery("eating food").getOrThrow();
    var docEmb = model.embedDocument("A man is eating food.").getOrThrow();

    // Batch embedding
    var batch = model.embedBatch(new String[]{"text one", "text two"}).getOrThrow();
}

var provider = new OnnxEmbeddingProvider();
try (var model = provider.create(OnnxModelId.EMBEDDING_GEMMA_300M.id(), EmbeddingConfig.defaults())) {
    var embedding = model.embedDocument("A software engineer building AI apps.").getOrThrow();
}

var ft = FaultTolerance.newBuilder()
    .withRetry(RetryPolicy.newBuilder()
        .withMaxAttempts(3)
        .withBackoff(Backoff.exponential(Duration.ofMillis(500), 2.0))
        .build())
    .withCircuitBreaker(CircuitBreaker.newBuilder()
        .withFailureThreshold(5)
        .withHalfOpenAfter(Duration.ofSeconds(30))
        .build())
    .withOperationTimeout(Duration.ofMinutes(5))
    .build();

var agent = new Agent(AgentConfig.newBuilder()
    .withName("resilient-agent")
    .withModel(model)
    .withFaultTolerance(ft)
    .build());

var classifier = new Agent(AgentConfig.newBuilder()
    .withName("classifier")
    .withModel(model)
    .build());

var responder = new Agent(AgentConfig.newBuilder()
    .withName("responder")
    .withModel(model)
    .build());

var workflow = Workflow.newBuilder("support-pipeline")
    .withStep(Step.agent("classify", classifier))
    .withStep(Step.condition("route",
        ctx -> ctx.lastResult().content().contains("urgent"),
        Step.agent("urgent-response", responder),
        Step.agent("standard-response", responder)))
    .build();

Result<StepResult> result = workflow.run("My order hasn't arrived");

var workflow = Workflow.newBuilder("research")
    .withStep(Step.parallel("gather",
        Step.agent("analyst-1", analyst),
        Step.agent("analyst-2", analyst),
        Step.agent("analyst-3", analyst)))
    .withStep(Step.agent("synthesize", synthesizer))
    .build();

var workflow = Workflow.newBuilder("reliable-query")
    .withStep(Step.fallback("try-models",
        Step.agent("primary", primaryAgent),
        Step.agent("backup", backupAgent)))
    .build();

var workflow = Workflow.newBuilder("traced-pipeline")
    .withStep(Step.agent("classify", classifier))
    .withTraceListener(traceStore)
    .build();

var agent = new Agent(AgentConfig.newBuilder()
    .withName("traced-agent")
    .withModel(model)
    .withTraceListener(traceStore)
    .build());

psql -d mydb -f schema.sql

CREATE SCHEMA IF NOT EXISTS lg;
SET search_path TO lg;
\i schema.sql

CREATE SCHEMA IF NOT EXISTS lg;

SET search_path TO lg;

CREATE TABLE IF NOT EXISTS helios_prompts ( ... );
-- rest of schema.sql

// Default schema (public) — no schema prefix applied to SQL
var pgConfig = PgConfig.newBuilder()
    .withDbClient(dbClient)
    .build();

// Custom schema — all SQL is qualified as lg.helios_*
var pgConfig = PgConfig.newBuilder()
    .withDbClient(dbClient)
    .withSchema("lg")
    .build();

// With agent scoping (required for PgMemory)
var pgConfig = PgConfig.newBuilder()
    .withDbClient(dbClient)
    .withSchema("lg")
    .withAgentId("my-agent")
    .build();

// Prompt versioning
var prompts = new PgPromptRegistry(pgConfig);
prompts.register("greeting", "Hello {name}!");
var prompt = prompts.resolve("greeting");

// Trace storage
var traces = new PgTraceStore(pgConfig);
var agent = new Agent(AgentConfig.newBuilder()
    .withName("my-agent")
    .withModel(model)
    .withTraceListener(traces)
    .build());

// Persistent memory (requires agentId in PgConfig)
var memory = new PgMemory(pgConfig);
var agent = new Agent(AgentConfig.newBuilder()
    .withName("my-agent")
    .withModel(model)
    .withMemory(memory)
    .build());

ai.singlr.core/
├── agent/      Agent, AgentConfig, AgentState
├── common/     Result<T>, Ids (UUID v7), Strings, HttpClientFactory
├── embedding/  EmbeddingModel, EmbeddingProvider, EmbeddingConfig
├── fault/      Backoff, RetryPolicy, CircuitBreaker, FaultTolerance
├── memory/     Memory, InMemoryMemory, MemoryBlock, MemoryTools
├── model/      Model, ModelProvider, ModelConfig, Message, Response, StreamEvent
├── prompt/     Prompt, PromptRegistry
├── schema/     SchemaGenerator, JsonSchema, OutputSchema
├── tool/       Tool, ToolParameter, ToolExecutor, ToolResult
├── trace/      TraceBuilder, TraceListener, Span, SpanKind
└── workflow/   Workflow, Step, StepResult, StepContext

ai.singlr.gemini/
├── GeminiModel, GeminiProvider, GeminiModelId
└── api/        Interactions API DTOs

ai.singlr.onnx/
├── OnnxEmbeddingProvider, OnnxEmbeddingModel, OnnxModelId
└── (internal)  OnnxModelDownloader, OnnxModelSpec

ai.singlr.persistence/
├── PgConfig           (Shared config: DbClient, schema, agentId)
├── PgMemory           (PostgreSQL-backed Memory)
├── PgPromptRegistry   (PostgreSQL-backed PromptRegistry)
└── PgTraceStore       (PostgreSQL-backed TraceStore)

mvn spotless:apply   # auto-format
mvn spotless:check   # verify formatting