DEV Community: Solon Framework

One Event Stream, Two UI Protocols: Wiring Solon AI to Any Frontend

Solon Framework — Tue, 06 Oct 2026 04:03:37 +0000

Your Java agent streams tokens. Your frontend speaks a protocol. Between them sits a translation layer that nobody wants to write — and that everybody writes badly.

It is the same story every time: text deltas, reasoning deltas, tool-call arguments, tool results, citations, errors, aborts. Six or seven channels, all multiplexed onto one SSE connection, all needing stable IDs so the UI can stitch deltas back into messages. Get the ID keying wrong and two parallel tool calls collide. Forget to close a block on error and the frontend hangs forever waiting for an end that never comes. Cancel the request and — if you forgot one line — the model keeps generating, and you keep paying.

Solon AI has a module whose only job is this translation layer: solon-ai-ui.

Repo: https://github.com/opensolon/solon-ai (module: solon-ai-ui)

It ships two adapters:

Artifact	Protocol it speaks	Pairs with
`solon-ai-ui-aisdk`	Vercel AI SDK — UI Message Stream Protocol v1	`@ai-sdk/react`, `@ai-sdk/vue` `useChat`
`solon-ai-ui-agui`	AG-UI	AG-UI compatible component libraries

Both convert Solon AI's internal Flux<ChatEvent> into a frontend-facing event stream. Neither is a rewrite of your agent — they are thin adapters, and the way they stay thin is the most interesting part of the design.

The layering rule: adapters may not know what an agent is

The obvious implementation would be: ui depends on agent, and maps AgentEvent to UI events directly. Simple. And wrong — it would drag the entire agent stack into every app that just wants to stream a chat model, and every agent event added upstream would become a breaking change downstream.

So the adapters depend only on solon-ai-core. Agent events arrive as Object, and the adapter figures them out reflectively:

If the event exposes getChatEvent(), the adapter delegates to the core event state machine. The three delta events — the ones carrying actual text, reasoning, and tool arguments — all take this path.
Otherwise it matches on the simple class name: ToolCallStartEvent, ToolCallEndEvent, RunEndEvent / SimpleEndEvent / TeamEndEvent.
Anything it still doesn't recognize falls through to a custom / data-* bucket instead of being dropped.

Nothing is silently discarded. That is the rule the whole module is built around.

Adapter 1: Vercel AI SDK

The AI SDK adapter converts chatModel.prompt(prompt).stream() into a Flux<SseEvent> that is a drop-in for useChat.

@Controller
public class AiChatController {
    @Inject
    ChatModel chatModel;

    private final AiSdkStreamWrapper wrapper = AiSdkStreamWrapper.of();

    @Produces(MimeType.TEXT_EVENT_STREAM_UTF8_VALUE)
    @Mapping("/ai/chat/stream")
    public Flux<SseEvent> stream(String prompt, Context ctx) {
        // required by the AI SDK protocol
        ctx.headerSet("x-vercel-ai-ui-message-stream", "v1");

        return wrapper.toAiSdkStream(chatModel.prompt(prompt).stream());
    }
}

The protocol is a parts model — roughly twenty part types, each a small JSON frame — and the wrapper emits them in a fixed order:

start → (message-metadata) → start-step
  → (reasoning-start → reasoning-delta* → reasoning-end)
  → (tool-input-start → tool-input-delta* → tool-input-available → tool-output-available)
  → (source-url* / source-document*)
  → (text-start → text-delta* → text-end)
  → (file* / data-*)
→ finish-step → … → finish → [DONE]

A single-turn reply is one step. A tool call that re-prompts the model produces multiple steps, and the start-step / finish-step pair is what lets useChat reassemble a multi-step assistant turn correctly.

There is also a blocking counterpart: toAiSdkStream(ChatResponse) wraps a call() result into the same frame sequence, so a non-streaming endpoint can still feed a streaming client.

Adapter 2: AG-UI

The AG-UI adapter targets a different event vocabulary — RUN_STARTED, TEXT_MESSAGE_CONTENT, TOOL_CALL_ARGS, REASONING_MESSAGE_CONTENT, STEP_FINISHED, and so on.

AgUiStreamWrapper wrapper = AgUiStreamWrapper.of("thread-1", "run-1");
Flux<Event> stream = wrapper.toAgUiStream(chatModel.prompt(prompt).stream());

Two details are worth calling out.

The reasoning rename is handled for you. AG-UI's modern vocabulary is REASONING_*; the older THINKING_* events are marked @Deprecated in the enum, with each old constant pointing at its replacement. Solon AI's core still calls its events THINKING_*, so the adapter maps them onto the modern REASONING_START / REASONING_MESSAGE_CONTENT / REASONING_END family — including the message-level boundaries, not just the outer block.

Interruption is a first-class outcome, not an error. When the core emits ABORT, the AG-UI adapter closes any open content block, then emits a RUN_FINISHED whose outcome type is interrupt. A user pressing "stop" is a normal ending with a name — not a fake failure.

Events AG-UI has no standard representation for — server-side tools, media, safety, usage, custom payloads — are preserved as CUSTOM rather than mapped onto something semantically wrong. For backwards compatibility the payload is written to both the standard name/value fields and the legacy rawEvent field, so older clients keep working while standard clients move forward.

There is also typed support for state sync: StateDeltaEvent carries RFC 6902 JSON Patch operations.

StateDeltaEvent delta = new StateDeltaEvent()
        .add(JsonPatchOperation.replace("/progress", 50))
        .add(JsonPatchOperation.add("/message", "working..."));

The five details that decide whether this works in production

Protocol mapping is the easy 20%. These are the rest.

1. Stable IDs across deltas. Deltas arrive in fragments, so each block needs an ID minted once and reused for its start / delta / end frames. Both adapters key the ID map on responseId + step + itemId, falling back to index. That key is what keeps two concurrent tool calls, or two reasoning channels, from borrowing each other's IDs. The AI SDK adapter also lets you swap the ID source entirely — UUID by default, snowflake or anything else via AiSdkIdGenerator, with prefixed helpers (msg_, txt_, rsn_, call_, src_).

2. Cancellation has to propagate upstream. Both wrappers call sink.onDispose(upstream). When the browser disconnects, the subscription to the model is released — the request doesn't keep running in the background burning tokens after nobody is listening.

3. Failures must not be dressed up as success. If the stream errors mid-flight, the wrapper first closes any open text/reasoning blocks (otherwise the client waits forever for an end), then emits the error part with finishReason set to error — not the default stop. The error text is taken from the terminal ERROR event when one was emitted, because that carries more context than the bare Throwable. If the error path had to synthesize the end frames itself, it reuses the same closing logic as the success path rather than inventing new frames.

4. No orphan tool output. Some providers deliver a tool result without ever sending a tool-input-* frame. A strict client will drop an output that references an input it never saw. So the adapter idempotently emits the missing tool-input-start / tool-input-available pair first, then the output. Same guard applies to agent tool events arriving from a replay or resume path.

5. Content that isn't the answer must not look like the answer. In a multi-agent run, a supervisor's internal routing chatter can arrive on the same stream. Both adapters force those events into a custom / data-* bucket — never into the assistant text or reasoning channels, so internal deliberation can't leak into what the user sees as the reply. Similarly, agent turns are namespaced by run and reason ID in the AI SDK adapter, so two turns can't accidentally reuse a closed part ID.

One more, from the AI SDK adapter's javadoc, worth knowing before you file a bug: the core's default event filter blocks RAW and HEARTBEAT, so unmodeled raw frames never reach the wrapper by default. If you want them passed through, opt in explicitly when building the stream:

chatModel.prompt(prompt).eventFilter(ChatEventFilter.all()).stream()

Which adapter?

If your frontend…	Use
already uses `useChat` from `@ai-sdk/react` or `@ai-sdk/vue`, or any AI-Elements component library	`solon-ai-ui-aisdk`
targets AG-UI / is protocol-first and wants run/step semantics, or you want typed JSON-Patch state sync	`solon-ai-ui-agui`
just wants plain SSE text and parses it by hand	neither — `streamText()` is enough

The two are not exclusive. ChatEvent is Solon AI's internal, provider-agnostic model; each adapter is an outbound projection of it. If you ever genuinely need both, you're translating one core stream two ways, not maintaining two agents.

Getting started

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-ui-aisdk</artifactId>
</dependency>

Versions are managed by the Solon AI BOM, so no <version> is needed. The adapter follows the Solon AI 4.1 line.

The interesting thing about a translation layer is that the best one is invisible. You wire two lines, the UI renders text, reasoning, tool calls and citations in order, and you never think about it again — until the day a tool call hangs the frontend, and you have to go find out whose job it was to close the block.

This module's answer to that question is: ours.

All behavior described above was read from the solon-ai-ui source in the opensolon/solon-ai repository.

An Agent That Finishes: Inside Solon AI's Loop Engine

Solon Framework — Tue, 06 Oct 2026 03:59:20 +0000

Most AI coding agents fail in the same way. Not with a wrong answer — with an incomplete one. They start confidently, get 70% of the way there, announce "done!", and hand you a task you now have to finish yourself.

That failure isn't a prompting problem. It's a control-flow problem: nothing in the system knows how to tell "finished" from "tired".

Solon AI ships a module whose entire job is that distinction — solon-ai-loop.

Repo: https://github.com/opensolon/solon-ai (module: solon-ai-loop)

Not to be confused with the /loop command in SolonCode. That's a feature of a product. This is a Java library you embed in your own application.

1. What it actually is

Strip away the naming and solon-ai-loop is four things bolted together:

A state machine — where the work is, and which transitions are legal.
A strategy — what one iteration means (implement a story? run a pipeline phase? run the test gate?).
A validator — whether this iteration passed, and if not, why.
Durable state — so the loop can survive a restart, a crash, or a human going home.

The point of the module is that none of these is left implicit. A loop ends because a criterion was met, or because a patience budget ran out — never because the model stopped talking.

2. The state machine

Eight states, with a whitelist of legal transitions:

State	Active	Terminal	Pausable
`IDLE`	✗	✗	✗
`PLANNING`	✓	✗	✓
`EXECUTING`	✓	✗	✓
`VERIFYING`	✓	✗	✓
`FIXING`	✓	✗	✓
`PAUSED`	✗	✗	— (resumable)
`COMPLETED`	✗	✓	✗
`FAILED`	✗	✓	✗

IDLE → PLANNING → EXECUTING → VERIFYING → COMPLETED
                       ↑            │
                       └── FIXING ◄─┘      (the fix loop)

The transition table is enforced in code, not in comments:

From	Allowed to
`IDLE`	`PLANNING`
`PLANNING`	`EXECUTING`, `PAUSED`, `FAILED`
`EXECUTING`	`VERIFYING`, `PAUSED`, `FAILED`
`VERIFYING`	`COMPLETED`, `FIXING`, `PAUSED`, `FAILED`
`FIXING`	`EXECUTING`, `PAUSED`, `FAILED`
`PAUSED`	`PLANNING`, `EXECUTING`, `VERIFYING`, `FIXING`, `FAILED`
`COMPLETED` / `FAILED`	— (terminal)

Two things worth noticing. First, FIXING can only go back to EXECUTING — a fix is work, not a shortcut to done. Second, VERIFYING is the only state that can reach COMPLETED. There is no code path where an executor declares victory about its own output.

3. Three strategies, three shapes of "keep going"

Ralph — PRD-driven story loop

Reads a PRD, takes the next unfinished user story by priority, implements it, verifies it, records progress, repeats.

RalphLoopStrategy strategy = RalphLoopStrategy.builder()
    .verificationRequired(true)
    .criticMode("architect")        // architect / critic / codex / none
    .maxIterations(50)
    .storyImplementor((task, ctx) -> { /* your agent goes here */ })
    .storyValidator((task, result, ctx) -> /* Boolean */ true)
    .build();

The two hooks are plain functional interfaces — StoryImplementor is a BiFunction<String, LoopContext, Object>, StoryValidator a TriFunction<String, Object, LoopContext, Boolean>. So the loop engine doesn't care how a story gets implemented. Wire it to a ReActAgent, a shell command, a human, whatever. The loop only owns the rhythm.

Team Pipeline — phase-ordered collaboration

Runs a fixed sequence of phases with guards between them:

TeamPipelineStrategy.builder()
    .phases(Arrays.asList(Phase.PLAN, Phase.PRD, Phase.EXEC, Phase.VERIFY, Phase.FIX))
    .maxFixAttempts(3)
    .build();

Phases: PLAN, PRD, EXEC, VERIFY, FIX, plus COMPLETED / FAILED / CANCELLED. The VERIFY phase won't proceed unless tasksCompleted >= tasksTotal, and the fix loop gives up after maxFixAttempts instead of oscillating forever.

UltraQA — the quality gate loop

Run build / test / lint / typecheck. If it fails, fix and run again. Repeat until green, or until you name why you stopped.

UltraQAStrategy.builder()
    .goalType(UltraQAStrategy.UltraQAGoalType.TESTS)   // TESTS / BUILD / LINT / TYPECHECK / CUSTOM
    .maxTestAttempts(10)
    .build();

4. The part I actually like: named exit reasons

GOAL_MET  · MAX_CYCLES · SAME_FAILURE · ENV_ERROR · CANCELLED

SAME_FAILURE is the interesting one. Every failed gate run is normalised — timestamps, line numbers and other noise stripped — then compared. If the same failure shows up 3 times in a row (that's SAME_FAILURE_THRESHOLD, a public constant), the loop stops.

That's a very old idea from build systems, and it's exactly right for agents: a loop that keeps producing the identical error is not making progress, no matter how busy it looks. Killing it early and loudly is the feature.

5. State that outlives the JVM

Long tasks and short processes are a bad match. So the engine can persist to disk:

.solon-ai-loop/
├── state/
│   ├── ralph/{sessionId}.json         # Ralph state (+ strategy mutex)
│   ├── team/{sessionId}.json          # Team Pipeline state
│   ├── ultraqa/{sessionId}.json       # UltraQA state
│   └── sessions/{sessionId}.json      # session index, for querying
├── prd/{sessionId}.json               # the PRD document
└── progress/{sessionId}.txt           # progress memory

Each file is wrapped in two layers — _meta (written_at, mode, sessionId) and data (the full state). Writes go through an atomic-write helper, and the base directory is created with 0700 permissions. The sessions/ index is what makes "what was running when I killed it?" an answerable question.

Because the three strategies share a state directory, they also share a mutex: MutualExclusionGuard refuses to start Ralph while UltraQA holds the lock (canStartRalph / canStartUltraQA / canStartTeam, with stale-lock cleanup). Two loops fighting over one workspace is a nasty failure mode, and it's designed out rather than documented away.

6. Validation is an interface, not an opinion

public interface Validator {
    ValidationResult validate(Object result, ValidationCriteria criteria);
    ValidationResult validateQualityGate(QualityGate gate, Object result);
    ValidationResult validateIteration(Object iterationResult, ValidationContext context);
}

Results are one of three things — passed(message), failed(message, details), or needsFix(message, errors). That third one is what feeds the FIXING state.

Preset gates cover the boring 80%:

QualityGate.build();   // compilation, dependencies
QualityGate.test();    // unit-tests, integration-tests
QualityGate.lint();    // style, complexity, duplication

And the module ships two built-in verifiers, ArchitectVerifier and CriticVerifier, the latter with three modes — architect (architecture-level changes), critic (general review) and codex (test coverage, null handling).

Internally, each verification carries its own little state machine: PENDING → IMPLEMENTED → AWAITING_REVIEW → ARCHITECT_APPROVED → CRITIC_APPROVED, with FAILED after the attempt budget (3 by default) and SKIPPED as the escape hatch. Verification that isn't tracked is just an opinion; this one leaves a trail.

7. Autopilot: chaining strategies into one pipeline

The AutopilotExecutor composes the whole thing into five stages, each bound to a default strategy:

Stage	Default strategy
`EXPANSION` — requirement analysis	Team Pipeline
`PLANNING`	Team Pipeline
`EXECUTION`	Ralph
`QA`	UltraQA
`VALIDATION`	Team Pipeline
`COMPLETED` / `FAILED`	—

PipelineConfig config = PipelineConfig.builder()
    .expansionEnabled(true).planningEnabled(true)
    .executionEnabled(true).qaEnabled(true).validationEnabled(true)
    .strategyForStage(PipelineStage.EXECUTION, RalphLoopStrategy.builder().maxIterations(20).build())
    .strategyForStage(PipelineStage.QA,        UltraQAStrategy.builder().maxTestAttempts(5).build())
    .build();

AutopilotExecutor autopilot = new AutopilotExecutor(engine, config);
var future = autopilot.startPipeline(
    AutopilotExecutor.PipelineRequest.create(sessionId, "Build feature X"));

System.out.println(autopilot.formatPipelineHUD(sessionId));

Any stage can be replaced via the StageAdapter SPI, and the pipeline can be driven by hand — skipStage, advanceStage, cancelPipeline. That matters more than it sounds: an autonomous pipeline you can't interrupt is a liability, and one you can't inspect is a black box.

8. Wiring it into a Solon app

The module has first-class integration with three neighbours — solon-ai-agent (agents drive iterations), solon-flow (a flow context drives phases), and solon-ai-harness (tool management drives the QA loop):

LoopAutoConfiguration.IntegratedComponents c = LoopAutoConfiguration.createDefault();

LoopEngine engine = c.loopEngine;
// c.agentIntegration, c.flowIntegration, c.harnessIntegration

SimpleAgent agent = SimpleAgent.of().chatModel(chatModel).build();
LoopSession session = c.agentIntegration
    .startAgentDrivenRalphLoop("Implement user management", agent);

9. Getting started

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-loop</artifactId>
    <version>4.1.0</version>
</dependency>

Minimal run:

// one-liner, in-memory
LoopEngine engine = LoopAutoConfiguration.createDefaultEngine();

// or durable: state under the project dir, monitoring on
LoopEngine engine = new LoopAutoConfiguration()
    .useDiskState("/path/to/project")
    .enableMonitoring(true)
    .build();

LoopConfig config = LoopConfig.builder()
    .taskDescription("Implement user login feature")
    .strategy(RalphLoopStrategy.builder().verificationRequired(false).maxIterations(5).build())
    .maxIterations(5)
    .build();

LoopSession session = engine.start(config);
session.onStateChange(s -> System.out.println("state: " + s));
session.waitForCompletion(Duration.ofSeconds(10));

LoopResult result = session.getResult();
System.out.println(result.isSuccess() + " / iterations: " + result.getTotalIterations());

10. When not to use this

Being fair about scope:

Don't reach for it for a single tool call. If a ChatModel + one tool answers the question, a loop engine is overhead.
It does not implement anything for you. You supply the implementor, the validator, or the stage adapter. It provides the rhythm and the memory, not the intelligence.
Disk persistence is local. The state manager writes to the project's filesystem — it's not a distributed job queue. Multi-node orchestration is a different problem.

What it removes is the boring, failure-prone part: deciding what "done" means, remembering where you were, and being honest about when to stop. Every agent framework eventually grows this. Solon AI's version is small, explicit, and — in the spirit of the framework — named after exactly one thing it does.

Verified against the solon-ai-loop module source (64 Java files) and Maven Central metadata on 2026-10-06. Code samples are taken from the module's own APIs; the version shown is the current 4.1.x line.

One Router, Four Strategies: How Solon AI Picks the Right ChatModel

Solon Framework — Sun, 04 Oct 2026 12:09:13 +0000

In the multi-model era, your application already talks to more than one LLM: a cheap fast model for casual chat, an expensive smart one for reasoning, plus dedicated code models, vision models, and local small models. That raises a question — who gets each request?

The solon-ai-router module in Solon AI (v4.1.0+) answers this the "Solon way": a router so small it almost doesn't exist. Only 6 public classes in the whole module, yet it makes model selection clean.

Repo: https://github.com/opensolon/solon-ai (module: solon-ai-router)

1. It Does Exactly One Thing: Pick a ChatModel for You

The scope of ChatModelRouter is deliberately narrow:

When a chat request is created, select one physical model from a set of already-built ChatModel instances;
Return the ChatRequestDesc produced by that model, untouched.

Note the second half — the Router never hijacks request logic. After routing, session(), role(), instruction(), systemPrompt(), options(), call(), and stream() are all handled by the target model's own implementation. No Agent, no Flow, no Harness — just a pure model selector.

That differs from the common "AI gateway" approach where routing, retries, fallback, caching, and rate limiting all fuse into one big blob. Solon AI draws the line clearly: routing is routing, execution is execution.

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-router</artifactId>
    <version>4.1.0</version>
</dependency>

2. Basic Usage

ChatModelRouter router = new ChatModelRouter(Arrays.asList(
        new ChatModelRoute("fast", "Fast, cheap model for routine Q&A", 1, fastModel),
        new ChatModelRoute("reasoning", "Model for complex analysis and multi-step reasoning", 1, reasoningModel)
), new RoundRobinRoutingStrategy());

ChatResponse response = router.prompt("Analyze this concurrency issue")
        .options(options -> options.temperature(0.2F))
        .call();

A ChatModelRoute takes four arguments: id, description (used later by the LLM classifier), weight (must be > 0), and the chatModel instance.

ChatModelRouter mirrors the four ChatModel entry points, so migration cost is near zero:

router.prompt(prompt);
router.prompt(messages);
router.prompt(systemMessage, userMessage);
router.prompt("user message");

One subtle detail: routing happens at prompt(...) time. Even if you only create the request and never call call() or stream(), one round-robin slot has already been consumed. Don't hoard prompt() outside a loop.

3. Four Built-in Strategies, From Dumb to Smart

1) RoundRobinRoutingStrategy

new RoundRobinRoutingStrategy()

Cycles through candidates in registration order. Backed by an AtomicLong cursor — lock-free, thread-safe, shareable across threads. Perfect for a pool of equivalent models (e.g., same spec, multiple accounts) to spread quota evenly.

2) WeightedRoundRobinRoutingStrategy

new WeightedRoundRobinRoutingStrategy()

Smooth weighted round-robin over ChatModelRoute.getWeight() — the same algorithm nginx uses. With a 5:1 weight ratio, requests spread out evenly instead of "5 hits on A, then 1 on B", which is friendlier to rate-limit windows.

A design decision worth noting: once used, a strategy instance pins the candidate IDs, order, and weights. If the candidate list topology changes afterwards (added/removed candidates, changed weights), it throws RoutingException instead of quietly running with the new config. Configuration drift should be visible, not swallowed.

3) RuleBasedRoutingStrategy

RuleBasedRoutingStrategy strategy = new RuleBasedRoutingStrategy(Arrays.asList(
        new RoutingRule("reasoning", context -> {
            String content = context.getPrompt().getUserContent();
            return content != null && content.contains("analyze");
        }),
        new RoutingRule("fast", context -> true)   // catch-all: keep it last
));

Rules execute in registration order; the first match wins. RoutingContext exposes the Prompt, so you can branch on message content, attributes, or anything else — tenant tier, task type, message length.

Two semantics you must know:

If no rule matches, the strategy throws RoutingException immediately. It won't guess a default model for you — add an explicit catch-all rule if every request needs a home;
A predicate that throws a RuntimeException gets wrapped in a RoutingException and propagated, never silently skipped.

4) SmartRoutingStrategy — an LLM as the Dispatcher

ChatModelRouter router = new ChatModelRouter(Arrays.asList(
        new ChatModelRoute("fast", "Routine Q&A", 3, fastModel),
        new ChatModelRoute("reasoning", "Complex reasoning", 1, reasoningModel)
), new SmartRoutingStrategy(classifierModel));

ChatResponse response = router.prompt("Analyze this concurrency issue")
        .options(options -> options.temperature(0.2F))
        .call();

The most interesting one: a dedicated, ordinary ChatModel acts as the classifier. It reads the candidates' description fields plus the original messages, then emits a structured RoutingDecision (with routeId + reasoning).

Look inside SmartRoutingStrategy and the classifier prompt is refreshingly plain:

You are a routing classifier. Select only one candidate route id
and explain the reason.

Candidate routes:
- fast: Routine Q&A
- reasoning: Complex reasoning
...

The implementation leans on Solon AI's structured output: options.outputSchema(RoutingDecision.class) constrains the classifier to a valid shape, then message.toBean(RoutingDecision.class) deserializes it, then it validates that routeId is non-empty, reasoning is non-empty, and the id is a registered candidate. Any failed step fails the request immediately — it never proceeds to a business model with uncertainty.

This is why ChatModelRoute.description is required — it's the model's "business card" shown to the classifier. How well you write it directly determines routing accuracy.

The cost is equally clear: one extra model call per request (latency included). Use a small, fast classifier — e.g., a local 1.5B model via Ollama — not your flagship reasoning model.

4. Explicit Routing: The Escape Hatch

A Prompt can bypass the strategy via a fixed attribute:

Prompt prompt = Prompt.of("Summarize this")
        .attrPut(ChatModelRouter.ATTR_ROUTE_ID, "fast");

router.prompt(prompt).call();

Semantics stay deliberate: the explicit id must be a registered, non-empty string; an unknown or invalid id throws RoutingException and never falls back to the configured strategy. This makes "let advanced users pick the model" a clean feature — no more silent model swaps the user never asked for.

5. Error Semantics: No Magic, Only Determinism

List every failure path of ChatModelRouter.prompt() and you see the module's full personality:

Scenario	Behavior
Empty decision / empty routeId / unknown candidate	Throws `RoutingException` immediately
No rule matched (rule strategy)	Throws `RoutingException` immediately
Classifier failed / invalid output / unknown candidate	Throws `RoutingException`; business models are never called
Invalid explicit route id	Throws `RoutingException`; no fallback to the strategy
Target model `call()`/`stream()` throws	Original type and propagation preserved

One sentence: the Router provides no default candidate, no failover, no silent fallback.

In production, that's a life-saver. The most common AI disaster isn't "the request failed" — it's "the request quietly succeeded some other way": degraded to a model the user never approved, silently switched to one 10× more expensive, or misclassified with nobody knowing. Solon AI makes every routing failure loud and hands the degradation decision back to business code. Need a fallback? Catch RoutingException and write your own — three lines of code, but the control is yours.

6. Choosing a Strategy

Scenario	Strategy
Spread load/quota across equivalent models	`RoundRobinRoutingStrategy`
Split traffic by ratio (e.g., 3:1)	`WeightedRoundRobinRoutingStrategy`
Deterministic business rules (VIP routing, long-input routing)	`RuleBasedRoutingStrategy`
Rules can't enumerate everything; let the model decide	`SmartRoutingStrategy` (with a small classifier)
User manually picks the model	`ATTR_ROUTE_ID` explicit routing

They compose too: put deterministic rules first, then nest smart routing as the catch-all for the long tail.

Wrapping Up

solon-ai-router is 6 public classes that decompose a real engineering problem — multi-model selection — cleanly: single responsibility, explicit failure, pluggable strategies. It doesn't aspire to be an AI gateway; it does model selection, and does it without surprises.

That's the taste the Solon ecosystem keeps showing — restrained, but never compromising.

Links

Solon AI repo: https://github.com/opensolon/solon-ai
Solon website: https://solon.noear.org
Getting started with Solon AI: https://solon.noear.org/article/learn-solon-ai

All APIs and behaviors in this post were verified against the solon-ai repo's solon-ai-router module source (since 4.1).

What Makes a Coding Agent Trustworthy? A Look at SolonCode's Design Choices

Solon Framework — Mon, 28 Sep 2026 01:58:44 +0000

Every week there's a new coding agent, and every week someone asks the same question in a slightly different tone: can I actually trust this thing with my codebase?

It's a fair question. A coding agent reads your source, runs commands in your shell, and — increasingly — edits files and opens pull requests on its own. That's a lot of access to hand to a black box. So instead of arguing about which agent is "smartest," I want to talk about a less glamorous property: trust. What does it actually take for a coding agent to earn it?

I'll use SolonCode — an open-source coding agent built in Java on top of Solon AI — as a concrete reference, not because it's the only good answer, but because its design happens to line up with a checklist I think is worth having. Take the checklist with you and hold any agent to it, including this one.

A trust checklist for coding agents

Here are the five questions I ask before I let an agent near a real repo.

Question	Why it matters
Can I read the source?	You can't trust what you can't inspect.
Where does my code go?	Every network hop is a place your code can leak.
Am I locked into one vendor?	Lock-in quietly removes your ability to walk away.
Can I control what it does?	An agent that acts without review is a liability, not a tool.
Can I undo a mistake?	Autonomy is only safe when it's reversible.

Let's go through them.

1. Can I read the source?

The strongest form of trust is the kind you don't have to take on faith. If the agent is open source, you (or your security team) can read exactly how it builds prompts, what it sends over the wire, and where it stores things.

SolonCode is MIT-licensed and fully open source — the CLI, the Web UI, and the desktop client are all in the open. That means the interesting questions ("what exactly gets sent to the model?", "does it phone home?") are answerable by reading code, not by trusting a marketing page.

This is the part that "purity" really comes down to for me: not a vibe, but the fact that there's nothing you can't look at.

2. Where does my code go?

A coding agent has to send something to a model to be useful. The question is what else happens along the way — telemetry, analytics, background uploads.

SolonCode runs locally. You start it from your own machine in whichever form you like:

# terminal (CLI)
soloncode cli

# browser (Web UI)
soloncode web 0

# or the desktop IDE

The agent process lives on your box, works in your workspace, and talks directly to the model endpoint you configured. There's no mandatory middle-tier service that your code has to pass through first. For teams with source that legally cannot leave the building, that distinction is the whole ballgame.

There's a more fundamental angle worth stating on its own: even if it wanted your code, it has no motive to take it and nowhere to use it. A lot of the worry assumes the vendor is quietly harvesting your code to train its own model — but that assumption has a precondition: the vendor needs a first-party model or cloud business for your data to be worth anything to it. SolonCode isn't that kind of player. It has no hosted foundation model of its own, and no official cloud API that your requests are forced to route through — it's a local client that hands the work off to the model you chose. No in-house model to feed means no incentive to scrape user code for training; no mandatory relay means no pipe where your data could be siphoned off. It can't technically, and it has no reason to commercially — and those two things together are more reassuring than any "we promise not to collect" ever could be.

3. Am I locked into one vendor?

A lot of agents are welded to a single model provider. That's convenient right up until pricing changes, a better model ships elsewhere, or your employer mandates a specific vendor.

SolonCode is provider-agnostic. You configure models yourself — through Settings → LLM in the Web UI — and point it at whatever you're allowed to use: a hosted API, an OpenAI-compatible endpoint, or a local model. Because it's built on Solon AI, swapping the underlying model is a configuration change, not a migration.

The practical value: the day a cheaper or smarter model shows up, you switch a setting instead of switching tools.

4. Can I control what it does?

This is the one people underestimate until an agent runs a command they didn't expect. Trust isn't "the agent is always right" — it's "I decide how much rope it gets."

SolonCode makes the autonomy level an explicit choice. Its work modes include:

Approval execution — the agent proposes actions; you approve before anything runs.
Automatic editing — for when you've built up trust on a task and want it to move.
Read-only planning — it can analyze and plan, but cannot touch your files.
Goal execution — persistent, longer-horizon autonomous work.

The point isn't that one mode is "correct." It's that you pick the risk level per task, instead of the tool picking for you. Reviewing a hairy migration? Read-only planning. Renaming a variable across ten files? Let it run.

5. Can I undo a mistake?

Even a careful agent will occasionally do the wrong thing. What matters is whether that's a shrug or a disaster.

SolonCode keeps persistent session history with rewind and redo, recoverable workspace checkpoints, and safe deletion. If a run goes sideways, you roll back to a known-good checkpoint instead of reconstructing your working tree from memory. Autonomy and reversibility are two sides of the same coin: the more freedom you give an agent, the more you want a clean undo.

Trust is a property you can check

None of these five points are about which agent writes the cleverest code. They're about whether you can verify how it behaves — read its source, see where your code goes, keep your model options open, control its autonomy, and undo its mistakes.

That's a better lens than "which one is smartest," because smart-but-opaque is exactly the combination that gets you into trouble. An agent you can inspect, run locally, point at any model, gate with approvals, and roll back is one you can reason about — and reasoning about your tools is the whole job.

SolonCode is one implementation that scores well on this checklist, and it's open source, so you can confirm every claim above by reading the code:

Repo: https://github.com/opensolon/soloncode
Built on Solon AI: https://github.com/opensolon/solon-ai
Docs: https://solon.noear.org/article/soloncode

Run the checklist against whatever agent you use. The goal isn't loyalty to a tool — it's keeping the power to check, choose, and undo in your own hands.

Build a RAG Pipeline in Java with Solon AI: From Raw Text to Grounded Answers

Solon Framework — Mon, 28 Sep 2026 00:55:54 +0000

A large language model only knows what it saw during training. Ask it about your internal wiki, last week's release notes, or a customer's support history, and it will either shrug or — worse — confidently make something up. Retrieval-Augmented Generation (RAG) is the standard fix: before the model answers, you retrieve the relevant facts from your own data and hand them over as context.

Most RAG tutorials are written in Python. This one is in Java, using Solon AI — the AI module of the Solon framework. We'll go from a pile of raw text to a grounded answer in a single, runnable file, then look at how to swap the in-memory store for Redis, load real documents, and filter by metadata.

Every API in this article was checked against the solon-ai source, so the method names are the real ones — not the hallucinated ones.

The moving parts

A RAG pipeline in Solon AI is built from five small pieces:

Piece	Type	Job
`EmbeddingModel`	model	turn text into vectors
`Document`	data	a chunk of content + metadata + score
`DocumentSplitter`	util	slice long text into chunks
`Repository`	store	save vectors, search by similarity
`ChatModel`	model	generate the final answer

The flow is always the same: split → embed → store, then at query time embed the question → search → augment the prompt → generate.

Add the dependency

The solon-ai aggregate pulls in the core plus the OpenAI / Ollama / DashScope / Gemini / Anthropic dialects, which is everything you need for a minimal pipeline.

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai</artifactId>
    <!-- replace with the latest stable release from Maven Central -->
    <version>4.1.0</version>
</dependency>

EmbeddingModel, ChatModel, InMemoryRepository, Document, and the built-in splitters all live in solon-ai-core, so a minimal RAG needs no extra vector-store or loader modules.

The whole pipeline in one file

Here is an end-to-end example. It uses a local Ollama server so you can run it without any API keys — point the URLs and models at OpenAI or DashScope if you prefer.

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.ChatResponse;
import org.noear.solon.ai.chat.message.ChatMessage;
import org.noear.solon.ai.embedding.EmbeddingModel;
import org.noear.solon.ai.rag.Document;
import org.noear.solon.ai.rag.RepositoryStorable;
import org.noear.solon.ai.rag.repository.InMemoryRepository;
import org.noear.solon.ai.rag.splitter.SplitterPipeline;
import org.noear.solon.ai.rag.splitter.TokenSizeTextSplitter;
import org.noear.solon.ai.rag.util.QueryCondition;

import java.util.Arrays;
import java.util.List;

public class MiniRag {
    public static void main(String[] args) throws Exception {
        // 1) Embedding model: turns text into vectors
        EmbeddingModel embeddingModel = EmbeddingModel.of("http://127.0.0.1:11434/api/embed")
                .provider("ollama")          // or "openai" / "dashscope"
                .model("bge-m3")
                .batchSize(10)
                .build();

        // 2) In-memory vector store (must be given an EmbeddingModel)
        RepositoryStorable repository = new InMemoryRepository(embeddingModel);

        // 3) Your source content
        String rawText = "Solon is a Java application development framework. "
                + "It offers its own IoC/AOP container, a lightweight web layer, "
                + "and Solon AI for building LLM applications. "
                + "Solon starts fast and has a small memory footprint, "
                + "which makes it a good fit for GraalVM native images.";

        List<Document> rawDocs = Arrays.asList(
                new Document(rawText).title("About Solon").url("https://solon.noear.org")
        );

        // 4) Split long text into chunks (default chunkSize = 500 tokens)
        SplitterPipeline pipeline = new SplitterPipeline()
                .next(new TokenSizeTextSplitter(500));
        List<Document> chunks = pipeline.split(rawDocs);

        // 5) Store — save() embeds each chunk in batches automatically
        repository.save(chunks);

        // 6) Retrieve
        String question = "What is Solon and why is it good for native images?";
        QueryCondition condition = new QueryCondition(question)
                .limit(4)                    // default is 4
                .similarityThreshold(0.4D);  // default is 0.4
        List<Document> hits = repository.search(condition);

        // 7) Chat model for generation
        ChatModel chatModel = ChatModel.of("http://127.0.0.1:11434/api/chat")
                .provider("ollama")          // or "openai" / "dashscope"
                .model("qwen2.5")
                .build();

        // 8) Augment the prompt with retrieved context, then ask
        ChatMessage userMsg = ChatMessage.ofUserAugment(question, hits);
        ChatResponse resp = chatModel.prompt(userMsg).call();

        if (resp.getError() != null) {
            throw resp.getError();
        }
        System.out.println(resp.getMessage().getContent());
    }
}

That's the entire pipeline. Let's unpack the parts that matter.

What the API is actually doing

`Document` — plain data, no magic factory

A Document holds an id, content, a Map<String, Object> metadata, a transient score (filled in during search), and a float[] embedding. There is no Document.of(...) factory — you use the constructor and chain setters:

new Document("some content")
        .title("About Solon")
        .url("https://solon.noear.org")
        .metadata("category", "framework");

Splitting is a pipeline

SplitterPipeline lets you chain splitters with next(...). The built-in TokenSizeTextSplitter cuts on token count (default 500, backed by jtokkit's CL100K_BASE), and RegexTextSplitter cuts on a pattern (default \n\n). Chain them when you want "split on blank lines, then cap each piece at N tokens".

`save()` embeds for you

RepositoryStorable.save(...) is the write path — note the name is save, not insert or store. Internally it batches by embeddingModel.batchSize() and calls embed(...) for each batch, so you never touch vectors by hand. There's also asyncSave(...), deleteById(String...), and existsById(String).

`QueryCondition` controls retrieval

The constructor takes the query string; everything else is chained:

limit(int) — how many chunks to return (default 4)
similarityThreshold(double) — minimum score to keep (default 0.4)
filterExpression(String) — metadata filter (more on this below)

Augmentation: two ways

The interesting one is ChatMessage.ofUserAugment(question, context). It wraps your question and the retrieved documents into a single user message using this template:

{question}

 Now: {current time}

 References: {context}

So the model gets the question, the current time (handy for "latest" style questions), and the references — all in one shot.

If you'd rather not orchestrate the search yourself, Repository has a one-liner that does search + wrap together:

// search(question) + ofUserAugment(...) in a single call
ChatMessage augmented = repository.promptAugment(question);
ChatResponse resp = chatModel.prompt(augmented).call();
System.out.println(resp.getContent());

Going beyond in-memory

Swap in a real vector store

InMemoryRepository is great for demos, but for production you'll want a persistent store. Solon AI ships repositories for Redis, Milvus, Qdrant, pgvector, Elasticsearch, OpenSearch, Chroma, Weaviate, MySQL, MariaDB, and more — each is a separate Maven module (solon-ai-repo-redis, solon-ai-repo-milvus, …).

Redis, for example, uses a builder that takes the embedding model plus a Jedis client:

// dependency: org.noear:solon-ai-repo-redis
RedisRepository repository = RedisRepository
        .builder(embeddingModel, jedisClient)
        .indexName("my_docs")
        .build();

The Repository interface is identical across stores, so everything downstream — save, search, QueryCondition — stays exactly the same. Swapping the store never touches your retrieval code.

Load real documents

For real content you rarely start from a String. The TextLoader (from File, URI, URL, byte[], or a stream) lives in the core; separate modules add MarkdownLoader, PdfLoader, HtmlSimpleLoader (note: not HtmlLoader), WordLoader, ExcelLoader, and PptLoader. Every loader returns List<Document>, so it drops straight into the splitter → store flow.

Filter by metadata with SnEL

QueryCondition.filterExpression(String) accepts a SnEL expression and narrows the search to documents whose metadata matches — vector similarity and a structured filter, in one query:

QueryCondition condition = new QueryCondition(question)
        .limit(4)
        .filterExpression("category == 'framework' AND year >= 2024");

Under the hood the string is parsed by SnEL.parse into a portable expression tree, and each vector store rewrites that tree into its own native filter syntax. (If you want the full story on how one SnEL expression targets Redis, Milvus, Qdrant, and pgvector, I wrote about that in an earlier post.)

Let the agent retrieve on its own

Everything above is "retrieve first, then ask". Solon AI also supports agentic RAG via RepositoryTool, which wraps a Repository as a callable tool (@ToolMapping("repository_query")). Hand it to a ChatModel and the model decides when to search — useful for multi-turn conversations where not every question needs a lookup.

ChatModel chatModel = ChatModel.of(apiUrl)
        .provider("openai")
        .model("gpt-4o-mini")
        .defaultToolAdd(new RepositoryTool(repository))
        .build();

Wrapping up

The mental model is small: split → embed → store, then embed → search → augment → generate. Solon AI gives you each step as a plain, composable piece — Document, DocumentSplitter, Repository, EmbeddingModel, ChatModel — with no framework ceremony. Start with InMemoryRepository to prove the flow, switch to Redis or pgvector when you need persistence, and reach for filterExpression and RepositoryTool when your retrieval gets more demanding.

Same interface all the way down, no rewrite when you scale up. That's the part I like.

Project: solon.noear.org · Source: github.com/opensolon/solon-ai

SnEL Inside the Container: How Solon Wires Expressions Into Config, Beans, Cache and Data Sources (Java)

Solon Framework — Wed, 23 Sep 2026 12:58:42 +0000

In an earlier post I looked at Solon's SnEL engine as a standalone, portable filter DSL — the trick where one expression string gets rewritten into Redis / Milvus / Qdrant filter syntax. A few readers asked the obvious follow-up: that's nice for a library, but where does the expression engine actually show up when I'm running a normal Solon app?

The answer is: almost everywhere the container touches a string that might need to be resolved at runtime. Solon threads SnEL through configuration, dependency injection, conditional beans, method caching, dynamic data sources, and even validation messages. This post is a tour of those integration points, with the exact source paths so you can go read the wiring yourself.

APIs below are checked against the solon core and solon-projects source. The relevant helper is org.noear.solon.core.util.SnelUtil.

The dispatcher: `#{...}` vs `${...}`

Almost every container-side use goes through one small helper, SnelUtil.evalTmpl. It's worth reading because it explains a naming convention you'll see all over Solon:

// org.noear.solon.core.util.SnelUtil
public static String evalTmpl(String tmpl, Map model) {
    if (tmpl.indexOf("#{") >= 0) {
        return SnEL.evalTmpl(tmpl, model);       // new: full SnEL sub-expression
    } else if (tmpl.indexOf("${") >= 0) {
        return TmplUtil.parse(tmpl, model);      // legacy: simple property template
    } else {
        return tmpl;                             // no marker: return as-is
    }
}

So the rule of thumb across the whole framework:

${...} — a property placeholder. Pull a value from config by key, optionally ${key:default}.
#{...} — a SnEL evaluation placeholder. The braces contain a real sub-expression that gets evaluated.

Keep that distinction in your head; it's the key to reading everything below.

1. Resolving placeholders anywhere

AppContext exposes the resolver directly:

// org.noear.solon.core.AppContext
public String resolvePlaceholders(String expr) {
    return SnelUtil.evalTmpl(expr, cfg());
}

cfg() is the application configuration (app.yml / properties). So anywhere you have the context, you can expand a template against config:

String url = Solon.context()
        .resolvePlaceholders("jdbc:mysql://${db.host:localhost}:${db.port:3306}/app");

// or evaluate a real expression against config
String banner = Solon.context()
        .resolvePlaceholders("app is #{'v' + ${app.version:1.0}}");

2. Injection: config values and evaluated values

@Inject is where the ${} / #{} split really pays off. The container inspects the string and branches (see BeanContainer):

// @Inject("${xxx}") or @Inject("${xxx:def}") — inject a config value (single value)
if (name.startsWith("${")) {
    String name2 = findConfigKey(name);
    beanInjectConfig(vh, name2, required);
    // ... plus auto-refresh binding when the config key changes
    return;
}

// @Inject("#{...}") — evaluate a SnEL template, then convert to the field type
if (name.startsWith("#{")) {
    String val  = SnelUtil.evalTmpl(name, cfg());
    Object val2 = ConvertUtil.to(vh.getType(), vh.getGenericType(), val);
    vh.setValue(val2);
    return;
}

In practice:

@Component
public class MyService {
    // classic config injection, with default + hot-refresh on field injection
    @Inject("${app.title:Solon}")
    String title;

    // evaluated expression, converted to the target type
    @Inject("#{${server.port:8080} + 1}")
    int adminPort;
}

Note the nesting in the second one: ${server.port:8080} is a property reference inside a #{...} expression, so the config value is pulled first and then the arithmetic runs. And because ${} field injection registers a config-change listener, those values can hot-refresh when the config source updates.

3. Conditional beans with `@Condition(onExpression=...)`

This is my favorite container-side use. @Condition decides whether a bean/configuration is created at all, and onExpression is a SnEL expression evaluated against config:

// org.noear.solon.core.util.ConditionUtil
private static boolean testExpression(AppContext context, String expr) {
    Object val = SnelUtil.eval(expr, context.cfg());

    if (val instanceof Boolean) return (Boolean) val;         // true/false directly
    if (val instanceof String)  return Assert.isNotEmpty((String) val); // non-empty string
    return val != null;                                        // otherwise: non-null
}

The annotation documents the intended shape (note it uses ${} property refs inside the expression):

@Condition(onExpression = "${env} == 'pro'")
@Configuration
public class ProdOnlyConfig {
    @Bean
    public MetricsReporter reporter() { ... }
}

// combine conditions
@Condition(onExpression = "${feature.cache} == 'on' && ${env} != 'test'")
@Component
public class CacheWarmup { ... }

Because the evaluation result is coerced sensibly (Boolean → itself, String → non-empty, other → non-null), you can also write @Condition(onExpression = "${some.key}") to mean "only if this key has a value." @Condition also has the type-safe onClass / onBean / onMissingBean knobs — onExpression is the escape hatch for config-driven logic. (The older onProperty attribute is deprecated in 3.6 in favor of onExpression.)

4. Method caching: templating keys from arguments

Solon's declarative cache (solon-data) builds cache keys and tags from a template that can reference method arguments by name. The interceptor runs each attribute through SnelUtil.evalTmpl with an Invocation-backed context:

// org.noear.solon.data.cache.CacheExecutorImp (abridged)
String key = anno.key();
if (Utils.isEmpty(key)) {
    key = InvKeys.buildByInv(inv); // auto key from args when none given
}
key = SnelUtil.evalTmpl(key, inv); // expand #{...} against method args (+ result)

The context that backs inv exposes each argument by its @Param name, plus a special result key for the return value (used by @CachePut):

// org.noear.solon.core.util.SnelUtil.InvocationContext#apply
if (inv.result() != null && "result".equals(key)) {
    return inv.result();
}
Object rst = inv.argsAsMap().get(key); // argument-by-name

So the real usage looks like this (straight from the framework's own test service):

@Component
public class UserService {
    @Cache(key = "#{id}", seconds = 30)
    public User getUser(@Param("id") String id) { ... }

    @CachePut(key = "user_#{user.id}")
    public User update(User user) { ... }

    @CacheRemove(keys = "user_#{id}")
    public void delete(@Param("id") String id) { ... }
}

tags works the same way and supports multiple comma-separated values, each templated. The Cache annotation's own Javadoc gives the canonical example: user_#{user_id}.

5. Dynamic data source routing with `@DynamicDs`

The dynamic data source interceptor picks a datasource name by evaluating its template — so you can route by a method argument at call time:

// org.noear.solon.data.dynamicds.DynamicDsInterceptor
String dsName = SnelUtil.evalTmpl(anno.value(), inv);
return DynamicDsKey.with(dsName, inv::invoke);

@Component
public class OrderDao {
    // route to a datasource chosen by the tenant argument
    @DynamicDs("#{tenant}_db")
    public Order load(@Param("tenant") String tenant, long id) { ... }
}

Same Invocation context as caching, so argument names are in scope.

6. Validation messages: a per-instance `SnelParser`

Not everything uses the static SnEL facade. When you need a configured parser — a custom marker, a bounded cache — you instantiate SnelParser directly. The i18n validation failure handler does exactly this:

// org.noear.solon.validation.ValidatorFailureHandlerI18n
private final SnelParser SNEL;

// custom marker '#','{' and a cache capacity
SNEL = new SnelParser(cacheCapacity, '#', '{');

// ...
if (SNEL.hasMarker(msg)) {
    msg = SNEL.forTmpl()
              .parse(msg)
              .eval(key -> I18nUtil.getMessage(ctx, key.toString()));
}

Here the "variable lookup" isn't a map at all — it's a lambda that resolves each key through the i18n message bundle. That's the general shape of SnEL: the context is any Function<String, Object>, so you can back it with config, a POJO, method arguments, or a message catalog.

Why do it this way?

Two things stand out once you see all six use sites together.

First, one engine, consistent semantics. Config injection, conditional beans, cache keys, and datasource routing all share the same ${}/#{} convention and the same evaluator. Learn it once and it reads the same everywhere.

Second, safe by omission. SnEL has no object instantiation and no control flow, so exposing it to app.yml or annotation strings doesn't open a scripting hole. It's an evaluator, not a scripting language — which is precisely why the container can lean on it so heavily.

If you came from the vector-DB filter angle in the last post, this is the other half of the picture: the same tiny 40KB engine that rewrites database filters is also the quiet workhorse behind Solon's configuration and DI.

solon-expression: https://github.com/opensolon/solon-expression
Solon: https://github.com/opensolon/solon
SnEL docs: https://solon.noear.org/article/learn-solon-snel

Have you wired an expression engine into your own container or config layer? I'm curious how you kept it from turning into a security footgun.

One Expression, Many Databases: A Tour of Solon's SnEL Engine (Java)

Solon Framework — Wed, 23 Sep 2026 01:54:57 +0000

Most Java projects reach for an expression engine sooner or later — a rule check here, a dynamic config value there, a filter that a user types at runtime. The usual suspects are heavyweight: they pull in scripting runtimes, allow arbitrary code, and become a security review headache.

Solon takes a more restrained path with SnEL (Solon Expression Language). It is a pure-Java, zero-dependency engine that compiles to a little over 40KB, and it works standalone — you can drop it into Spring Boot, Vert.x, jFinal, or a plain main method. But the part I find genuinely clever is how Solon AI reuses the parsed expression tree as a portable DSL and rewrites it into the native filter syntax of Redis, Milvus, Qdrant, pgvector, and friends.

This post walks through SnEL from "hello world" to that vector-database trick.

All APIs below are checked against the solon-expression and solon-ai source. SnEL ships in Solon 3.1.1+.

Adding the dependency

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-expression</artifactId>
</dependency>

SnEL is a shortcut interface over SnelEvaluator.getInstance(). You can use the static helpers directly, or instantiate an evaluator when you need isolation.

The philosophy: an evaluator, not a scripting language

SnEL is deliberately constrained, and the constraints are the feature:

It always returns a single value — it is an evaluation expression, not a statement block.
Variables come only from the context you pass in; there is no new Xxx().
One expression, no ;. No if/for/loops — it is not a scripting engine.
Field, property, and method access can nest deeply, but only public members are reachable.

That last set of rules is exactly what makes it safe to expose to config files or, carefully, to end-user input: there is no way to instantiate arbitrary classes or run control flow.

Evaluating expressions

The context is just a Map (or any Function<String, Object>). Values flow in by name.

import org.noear.solon.expression.snel.SnEL;

// Constants and arithmetic — no context needed
SnEL.eval("1 + 1");           // 2
SnEL.eval("1 * (1 + 2)");     // 3
SnEL.eval("'hello ' + 'world!'"); // "hello world!"
SnEL.eval("[1, 2, 3, -4]");   // a list

// Variables from a context map
Map<String, Object> ctx = new HashMap<>();
ctx.put("name", "solon");
ctx.put("list", Arrays.asList(1, 2, 3));

SnEL.eval("name.length()", ctx);            // 5  (method call)
SnEL.eval("name.length() > 2 OR true", ctx);// true
SnEL.eval("list[0] == 1", ctx);             // true

The syntax at a glance

Capability	Example
Constants	`1`, `'name'`, `true`, `[1,2,3]`
Variables	`name`
Map / list access	`map['name']`, `list[0]`
Property / method	`user.name`, `user['name']`, `order.getUser()`
Arithmetic	`+` `-` `*` `/` `%`
Comparison	`<` `<=` `>` `>=` `==` `!=`
`like` / `in`	`name LIKE 'so'`, `vip IN ['l3','l4']`
Ternary	`age > 18 ? 'adult' : 'minor'`
Logical	`AND` `OR` `NOT` (aliases `&&` `
Safe navigation	{% raw %}`user?.name`
Default (Elvis)	`user.name ?: 'noear'`
Property reference	`${user.name}`, `${user.name:noear}`
Static type call	`T(java.lang.Integer).valueOf(45)`

A couple of rules worth remembering:

Keywords are uppercase: LIKE, NOT LIKE, IN, NOT IN, AND, OR, NOT.
Numeric literals follow Java: 1.1F, 1.1D, 1L, 1.1 (double), 1 (int).

Here is a heftier condition, exactly the kind of rule you would otherwise hand-code:

Map<String, Object> ctx = new HashMap<>();
ctx.put("age", 25);
ctx.put("salary", 4000);
ctx.put("isMarried", false);
ctx.put("label", "aa");
ctx.put("title", "ee");
ctx.put("vip", "l3");

String expr = "(((age > 18 AND salary < 5000) OR (NOT isMarried)) "
            + "AND label IN ['aa','bb'] AND title NOT IN ['cc','dd']) "
            + "OR vip == 'l3'";

boolean pass = (Boolean) SnEL.eval(expr, ctx); // true

Beans as context, and virtual variables

A plain Function<String, Object> cannot expose a POJO's properties. EnhanceContext bridges that gap and adds the root / this virtual variables:

import org.noear.solon.expression.context.EnhanceContext;

User user = new User(); // has a public getUserId()

SnEL.eval("userId > 12 ? 'A' : 'B'", new EnhanceContext(user));
SnEL.eval("root.userId > 12 ? 'A' : 'B'", new EnhanceContext(user));

// When the whole target is the value itself:
SnEL.eval("root ? 'A' : 'B'", new EnhanceContext(true)); // "A"

EnhanceContext also lets you bind application properties, so ${...} property references resolve against config:

SnEL.eval("${user.name:solon}", Solon.cfg());
SnEL.eval("'Hello ' + ${user.name:solon}", Solon.cfg());

Template expressions

For string templating, SnEL uses two placeholders:

#{...} — an evaluation placeholder (a full sub-expression)
${...} / ${...:default} — a property placeholder

SnEL.evalTmpl("a val is #{a}", model);
SnEL.evalTmpl("sum val is #{a + b}", model);
SnEL.evalTmpl("sum is #{a + b}, c prop is ${demo.c:c}", context);

This is not a toy. Solon AI uses evalTmpl in real code paths: system/user message templates (SystemMessageTemplate, UserMessageTemplate), tool descriptions (@ToolMapping descriptions run through SnEL.evalTmpl), and even DDL loaders that build SQL for RAG ingestion.

The interesting part: one tree, many query languages

SnEL.parse(expr) does not just give you an answer — it returns an Expression tree. Because that tree is a neutral structure, it can be walked and rewritten. Solon defines a Transformer<Boolean, String> interface for exactly this, and Solon AI ships a FilterTransformer for each vector store.

In practice, you write your metadata filter once as a SnEL string, and each repository turns it into its own dialect. Here is where it enters the RAG path — QueryCondition parses the string into a tree:

// solon-ai: QueryCondition
public QueryCondition filterExpression(String filterExpression) {
    this.filterExpression = SnEL.parse(filterExpression);
    return this;
}

So your application code stays portable:

QueryCondition cond = new QueryCondition("What is Solon?")
        .filterExpression("category == 'framework' AND year >= 2020")
        .limit(4);

List<Document> docs = repository.search(cond);

Now the same tree — LogicalNode(AND) → ComparisonNode(eq), ComparisonNode(gte) — gets rewritten per backend. The Redis transformer, for example, walks the node types and emits Redis Search syntax:

// solon-ai-repo-redis: FilterTransformer (abridged)
if (filterExpression instanceof ComparisonNode) {
    ComparisonNode node = (ComparisonNode) filterExpression;
    switch (node.getOperator()) {
        case eq:  // @field:{value}
            parse(node.getLeft(), buf);  buf.append(":");  parse(node.getRight(), buf);
            break;
        case gte: // @field:[value +inf]
            parse(node.getLeft(), buf);  buf.append(":[");
            parse(node.getRight(), buf); buf.append(" +inf]");
            break;
        // ...
    }
} else if (filterExpression instanceof LogicalNode) {
    // AND -> space, OR -> " | ", NOT -> "-"
}

category == 'framework' AND year >= 2020 becomes something like (@category:{framework} @year:[2020 +inf]) for Redis, while the Milvus, Qdrant, pgvector, Elasticsearch, and Chroma transformers each produce their own native filter for the very same input. Swap your vector store and the filter code doesn't move.

Building the tree by hand

If you would rather not go through string parsing, ConditionBuilder assembles the same tree programmatically — handy when the condition is generated from a UI or another rule system:

import org.noear.solon.expression.snel.ConditionBuilder;
import org.noear.solon.expression.Expression;

ConditionBuilder cb = new ConditionBuilder();

// (age > 18 AND salary < 5000) OR (isMarried == false)
Expression<Boolean> condition = cb.or(
        cb.and(cb.gt("age", 18), cb.lt("salary", 5000)),
        cb.eq("isMarried", "false")
);

boolean result = condition.eval(context::get);

The output of ConditionBuilder is the same Expression<Boolean> type that SnEL.parse yields, so it flows into QueryCondition.filterExpression(...) and every Transformer exactly the same way.

When to use it

SnEL fits nicely when you want:

Dynamic config / conditions without embedding a scripting engine.
A safe evaluator for semi-trusted input — no object construction, no control flow.
A portable filter DSL that you can retarget across data stores (its reason for existing inside Solon AI).

It is intentionally not a general-purpose scripting language. If you need loops, assignments, or object instantiation, reach for something else. But for the "evaluate this condition against this context" job — which is 90% of what people actually want — its small surface area and predictable behavior are the whole point.

Wrapping up

SnEL is a good example of Solon's design taste: keep the core tiny, keep it safe by omission, and make the output composable. The fact that a 40KB evaluator doubles as the intermediate representation for cross-database vector filtering is the kind of leverage you get from picking the right abstraction.

solon-expression: https://github.com/opensolon/solon-expression
Docs (SnEL series): https://solon.noear.org/article/learn-solon-snel
Solon: https://github.com/opensolon/solon

If you have used SnEL — or a similar "expression tree as DSL" pattern — I'd love to hear how it held up in your project.

Tool Calling in Java, the Simple Way: Building an AI Agent with Solon AI

Solon Framework — Tue, 22 Sep 2026 13:49:40 +0000

Large language models are great at reasoning over text, but on their own they can't check today's weather, query your database, or hit an internal API. Tool calling (a.k.a. function calling) is what bridges that gap: you expose plain methods to the model, and it decides when to call them.

If you live in the Java world, you might assume this requires a heavyweight stack. It doesn't. Solon AI — the AI module of the Solon framework — lets you turn an ordinary Java method into an LLM tool with a single annotation. This post walks through a complete, runnable example.

Solon is an independent, full-scenario Java application framework. It is not Spring and has its own IoC/AOP, plugins, and annotations. Nothing here depends on Spring.

What we're building

A tiny "assistant" that can answer questions like "What's the weather in Hangzhou, and what time is it there?" The model will call two Java methods we provide — a weather lookup and a clock — and weave the results into a natural-language answer.

1. Add the dependency

Solon AI ships an aggregate artifact (solon-ai) that bundles the core plus the built-in dialects. The openai dialect (the default) is compatible with a wide range of providers — DeepSeek, Qwen, GLM, Kimi, GPT, and others.

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai</artifactId>
    <version>4.0.3</version>
</dependency>

2. Define your tools

A "tool" is just a method annotated with @ToolMapping. The description tells the model what the tool does; @Param describes each argument. Solon AI generates the JSON schema and handles the call dispatch for you.

import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.annotation.Param;

import java.time.LocalTime;

public class AssistantTools {

    @ToolMapping(description = "Get the current weather for a city")
    public String getWeather(@Param(description = "City name") String city) {
        // In a real app this would call a weather API.
        return city + ": sunny, 14°C";
    }

    @ToolMapping(description = "Get the current local time")
    public String getTime(@Param(description = "City name") String city) {
        return city + " local time: " + LocalTime.now();
    }
}

That's it — no interfaces to implement, no schema to hand-write. The method's name, parameters, and descriptions become the tool contract exposed to the model.

3. Build the ChatModel and register the tools

ChatModel.of(...) gives you a fluent builder. Point it at your provider's chat endpoint, set the model, then attach your tools with defaultToolAdd. Passing an object makes Solon AI scan it for @ToolMapping methods automatically.

import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.ChatResponse;

public class Demo {
    public static void main(String[] args) throws Exception {
        ChatModel chatModel = ChatModel.of("https://api.deepseek.com/v1/chat/completions")
                .apiKey(System.getenv("DEEPSEEK_API_KEY")) // never hard-code keys
                .provider("openai")   // openai-compatible dialect
                .model("deepseek-chat")
                .defaultToolAdd(new AssistantTools()) // register both tools
                .build();

        ChatResponse resp = chatModel
                .prompt("What's the weather in Hangzhou, and what time is it there?")
                .call();

        System.out.println(resp.getMessage().getContent());
    }
}

Under the hood, Solon AI runs the full tool-calling loop: it sends your prompt plus the tool definitions, receives the model's request to call getWeather and getTime, invokes your Java methods, feeds the results back, and returns the final composed answer. You just call .call().

A possible output:

The weather in Hangzhou is sunny at 14°C, and the local time there is 09:42.

4. Prefer configuration over code (optional)

Hard-coding endpoints is fine for a demo, but in a real Solon app you'd externalize this to app.yml (Solon's config file — not application.yml):

solon.ai.chat:
  assistant:
    apiUrl: "https://api.deepseek.com/v1/chat/completions"
    apiKey: "${DEEPSEEK_API_KEY}"
    provider: "openai"
    model: "deepseek-chat"

Then bind it with a config bean:

import org.noear.solon.annotation.Bean;
import org.noear.solon.annotation.Configuration;
import org.noear.solon.annotation.Inject;
import org.noear.solon.ai.chat.ChatConfig;
import org.noear.solon.ai.chat.ChatModel;

@Configuration
public class AiConfig {
    @Bean
    public ChatModel chatModel(@Inject("${solon.ai.chat.assistant}") ChatConfig config) {
        return ChatModel.of(config)
                .defaultToolAdd(new AssistantTools())
                .build();
    }
}

Now ChatModel is a managed component you can @Inject anywhere.

A few useful extras

Streaming: swap .call() for .stream() to get a Flux<ChatResponse> (requires solon-web-rx). Great for typing-effect UIs.
Return direct: set @ToolMapping(returnDirect = true) when a tool's result should be returned verbatim, skipping a second LLM pass.
Reasoning control: on the builder you can call .reasoning_effort("high") or .thinking(true) — Solon AI maps these to each provider's native format (OpenAI, Anthropic, Gemini, DashScope, and more), so your code stays provider-agnostic.
MCP: if your tools live in an external Model Context Protocol server, register an McpClientProvider via the same defaultToolAdd(...) — the model can't tell the difference.

Wrapping up

Tool calling in Java doesn't have to be verbose. With Solon AI you annotate a method, register the object, and call .prompt(...).call() — the framework handles schema generation, the multi-turn tool loop, and cross-provider quirks. From here it's a short hop to RAG pipelines, MCP servers, and multi-agent setups, all in the same lightweight framework.

Links:

Website: https://solon.noear.org
GitHub: https://github.com/opensolon/solon

If you're building AI features on the JVM, give it a try — and let me know what you build.

Giving an AI Agent a Real Sandbox: Filesystem and Network Jail, in Java

Solon Framework — Mon, 14 Sep 2026 00:53:49 +0000

Ask a coding agent to run a build, and you have just handed a language model the ability to cat ~/.ssh/id_rsa. Prompt-level instructions like "do not read sensitive files" are not a security boundary — they are a suggestion to a stochastic process. If the agent executes commands on your machine, the only control that actually holds is the one the operating system enforces.

That is the problem Solon AI's new solon-ai-sandbox module solves. It is a Java port of Claude Code's sandbox-runtime, and it wraps agent-issued commands in real filesystem and network isolation — on macOS, Linux, and Windows.

All code below was verified against the solon-ai-sandbox source in the Solon AI 4.1.x tree.

Why not just run the agent in Docker?

Containers are the usual answer, and for a server-side agent they are the right one. But the agents people actually run interactively — the ones editing their working copy of a repo — are not in a container. They are on a laptop, in a terminal, one bash call away from everything the user can touch.

Booting a VM or a container per command is too slow for that loop, and it breaks the agent's access to the working tree you wanted it to edit. What you want is a narrow boundary: keep the agent in the project directory, let it reach the registries and package mirrors the build needs, and make everything else fail closed — without a container runtime in the picture.

solon-ai-sandbox does exactly that, using each platform's native facility:

Platform	Mechanism
macOS	`sandbox-exec` with a generated Seatbelt profile
Linux	`bubblewrap` (`bwrap`), plus `socat` for the network bridge
Windows	`srt-win.exe` with a WFP filter layer

The module depends on nothing but solon-ai-core, so pulling it in does not drag a container runtime along with it.

The entry point is one class

SandboxManager is a final class with static methods — there is one sandbox per process, and there is one place to configure it.

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-sandbox</artifactId>
    <version>${solon-ai.version}</version>
</dependency>

Initialization takes a runtime config and an optional interactive callback:

SandboxManager.initialize(config, askCallback);

And wrapping a command is a single call:

String wrapped = SandboxManager.wrapWithSandbox("git status");
Process p = Runtime.getRuntime().exec(new String[]{"/bin/bash", "-c", wrapped});

On macOS the result is a sandbox-exec -p '<seatbelt profile>' invocation; on Linux it is a bwrap invocation with the appropriate bind mounts and namespaces. Your code never branches on the platform.

Filesystem: two different policies, on purpose

Reads and writes use opposite defaults, and understanding why is the key to configuring this correctly.

Writes are allow-only. The default is deny everything. You list the paths the agent may write, and denyWrite punches holes back out of that list. The manager always adds the paths a process genuinely cannot function without — /dev/*, temp directories, and so on — so you are not fighting the OS.

Reads are deny-then-allow-back. The default is allow, because breaking every read on the machine would break the compiler, the JVM, and half of userspace. Instead you name the regions to protect, and allowRead re-opens specific paths inside them.

FilesystemConfig fs = new FilesystemConfig(
    Arrays.asList("~/.ssh", "~/.aws"),   // denyRead
    Collections.emptyList(),             // allowRead
    Arrays.asList("/tmp", "."),          // allowWrite
    Arrays.asList(".git"),               // denyWrite
    false                                // allowGitConfig
);

Read that as: the agent may write only under the current working directory and /tmp, must never write into .git, and may not read your SSH or AWS credentials even though reads are otherwise open.

Two details that matter in practice:

An empty allowWrite list is the strictest possible setting — it means no writes at all beyond the mandatory system paths.
Don't write into .git. A corrupted or maliciously rewritten Git directory is a nasty persistence vector, which is why denyWrite on .git shows up in the security defaults, and why .git/config gets its own allowGitConfig switch (default false).

Network: a proxy, not a firewall rule

Network isolation here is implemented with a local HTTP and SOCKS5 forward proxy. The sandboxed process is pointed at it via environment variables, and the module decides per request whether to let the connection through.

NetworkConfig network = new NetworkConfig(
    Arrays.asList("api.openai.com", "*.github.com"), // allowlist
    Arrays.asList("telemetry.example.com"),          // denylist
    null, null, null, null, null, null, null, null, null, null
);

Domain patterns support wildcards like *.github.com, and HostUtils normalizes IPv4, IPv6, and hostnames so that matching is not trivially bypassed by writing an address a different way.

The reason to use a proxy instead of a kernel firewall rule is live updates. The proxies read the configuration on every request, so this takes effect immediately, on already-running agent processes, with no rebind and no port change:

SandboxManager.updateConfig(newConfig);

Compare that with filesystem rules, which are not live: on macOS the rules are baked into the Seatbelt profile when the command is wrapped, and on Windows they have to be explicitly re-stamped. To change filesystem restrictions you must reset() and initialize() again. Know which knob is hot and which one requires a restart.

There is also a callback for the case where the allowlist is not the final word:

SandboxAskCallback callback = (hostPattern) -> {
    System.out.println("Allow " + hostPattern.getHost() + ":" + hostPattern.getPort() + "? [y/N]");
    return new Scanner(System.in).nextLine().trim().equalsIgnoreCase("y");
};

It fails closed: if the callback throws, or no configuration covers the request, the connection is denied.

The constructor signature changed — watch out for this

Here is a concrete trap. The module's README still shows a SandboxRuntimeConfig with 12 constructor arguments. The current source declares 13:

SandboxRuntimeConfig config = new SandboxRuntimeConfig(
    network,                       // NetworkConfig
    fs,                            // FilesystemConfig
    ignoredViolations,             // Map<String, List<String>>
    null,                          // enableWeakerNestedSandbox
    null,                          // enableWeakerNetworkIsolation
    null,                          // allowAppleEvents
    null,                          // RipgrepConfig
    null,                          // mandatoryDenySearchDepth
    null,                          // allowPty
    null,                          // SeccompConfig
    null,                          // bwrapPath
    null,                          // socatPath
    null                           // WindowsConfig  <-- the 13th
);

The trailing WindowsConfig parameter is the one the README example is missing, so code copied from it will not compile against 4.1.x. I verified this directly in SandboxRuntimeConfig.java; the code in this post is written against the source, not the README.

Windows needs a different call

wrapWithSandbox(String) returns a shell string, and on Windows it throws instead:

wrapWithSandbox() returns a shell string and is not supported on Windows. Use SandboxManager.wrapWithSandboxArgv()...

The argv variant returns { argv, env }, where env carries the full proxy environment the child needs to inherit. On macOS and Linux it still works — it just wraps the string form behind <shell> -c — so if you want one code path across all three platforms, use wrapWithSandboxArgv everywhere and spawn with { shell: false }.

Observability: violations are data, not just logs

A blocked operation is an event worth recording. SandboxViolationStore is a thread-safe, category-keyed store:

SandboxViolationStore store = new SandboxViolationStore(ignoreViolations);
store.record("network", "attempted connection to telemetry.example.com:443");

for (String category : store.getCategories()) {
    System.out.println(category + ": " + store.getViolations(category));
}

Because violations are categorized — file_read, file_write, network — a burst of network denials from a normally well-behaved agent is a signal worth alerting on. ignoreViolations suppresses known-noisy entries by substring match, which keeps the signal readable.

Before you ship this: two operational gotchas

Check dependencies at startup, and fail loudly. initialize() refuses to proceed if the platform's dependency is missing, and you should surface that rather than silently degrading to an unsandboxed run:

Platform platform = PlatformDetector.detect();
SandboxDependencyCheck deps = SandboxManager.checkDependencies();
if (deps.hasErrors()) {
    throw new IllegalStateException("Sandbox unavailable: " + deps.getErrors());
}

On Linux that means bubblewrap and socat must be installed (apt install bubblewrap socat); macOS needs nothing, since sandbox-exec ships with the OS; Windows needs srt-win.exe installed once with elevation to set up the WFP layer.

Call cleanupAfterCommand() after each command on Linux. bwrap creates empty placeholder files on the host filesystem when it protects paths that do not exist — ~/.bashrc on a fresh container, for example. They linger after the process exits. The method is a no-op on macOS, and it is also invoked from reset() and a JVM shutdown hook, but calling it in your command loop avoids accumulating junk.

The mental model

Three rules cover almost all of it:

Writes are opt-in, reads are opt-out. Configure writes as an explicit allowlist; configure reads as a short list of things worth protecting.
Network is hot, filesystem is cold. Allowlist changes apply to running processes; filesystem changes need a reset.
Fail closed, and fail visibly. Missing dependencies and unmatched callbacks should surface as errors, not as an unsandboxed fallback.

The larger point is about where the boundary lives. Once an agent can execute code, "the model was asked nicely" is not a control. solon-ai-sandbox moves that control down into the mechanism the OS already enforces — Seatbelt, bubblewrap, or the Windows Filtering Platform — and hands you a small, uniform Java API for it.

For a Java agent stack, that is the difference between a demo and something you let near a real repository.

References

Solon AI documentation: https://solon.noear.org/article/learn-solon-ai
Module source (solon-ai-sandbox), Solon AI 4.1.x tree
Claude Code sandbox-runtime (the TypeScript original this module ports)

MCP Without the Boilerplate: Solon AI's Annotation-Driven Server and Self-Healing Client

Solon Framework — Tue, 08 Sep 2026 02:23:53 +0000

If you have been following this series, you have seen how Solon AI streams chat as semantic events and how it chunks documents by meaning. This time we move from conversation plumbing to capability plumbing: how Solon AI turns ordinary Java code into MCP (Model Context Protocol) services, and how it consumes remote MCP servers without hand-writing protocol code.

All code in this post was verified against the Solon AI 4.1.x source tree (solon-ai-mcp and mcp-core modules).

Why MCP, and why in-process?

MCP standardizes how an LLM application discovers and invokes tools, reads resources, and loads prompts from an external provider. Instead of hard-coding function calls into your prompt pipeline, you point your app at an MCP endpoint — local or remote — and the capability list arrives over the wire.

Solon AI ships MCP support in two layers:

mcp-core — a self-contained protocol implementation covering MCP spec revisions from 2024-11-05 through 2025-11-25.
solon-ai-mcp — the application-facing layer: an annotation-driven server and a ToolProvider-compatible client that plugs straight into ChatModel.

The design goal is visible in the dependency direction: the protocol layer knows nothing about Solon AI, and the integration layer adds almost nothing you have to learn.

The server: one annotation per capability

Declare an endpoint class with @McpServerEndpoint, then annotate plain methods:

@McpServerEndpoint(
        mcpEndpoint = "/mcp/sse",
        heartbeatInterval = "30s")
@Component
public class McpServerTool {
    // Tip: enable the -parameters compiler flag,
    // or give every @Param an explicit name.
    @ToolMapping(description = "查询天气预报")
    public String getWeather(@Param(description = "城市位置") String location) {
        return "晴，14度";
    }
}

That is the whole server. At startup, McpPlugin scans @McpServerEndpoint classes and builds an McpServerEndpointProvider from them. Method-level providers — MethodToolProvider, MethodResourceProvider, MethodPromptProvider — extract @ToolMapping, @ResourceMapping, and @PromptMapping methods and register them with the endpoint's lifecycle. No JSON schemas to maintain by hand, no dispatch switch, no transport wiring.

Details worth knowing:

heartbeatInterval defaults to "30s" on the server side.
sseEndpoint() and messageEndpoint() are deprecated; the unified mcpEndpoint() is the way to go.
There are two hosting models: a stateful host (STREAMABLE channel) that keeps session state per client, and a stateless one (STREAMABLE_STATELESS) where every request carries everything it needs — the better fit behind load balancers.
enableOutputSchema() can turn on output schema validation for tools that need it.

The client: `McpClientProvider`

On the consuming side, one class implements ToolProvider, ResourceProvider, and PromptProvider:

McpClientProvider mcpClient = McpClientProvider.builder()
        .url("http://localhost:8081/sse")
        .build();

ChatModel chatModel = ChatModel.of(chatConfig)
        .defaultToolAdd(mcpClient)
        .build();

ChatResponse resp = chatModel
        .prompt("杭州天气和北京降雨量如何？")
        .call();

The provider is lazy: the underlying McpAsyncClient is created on first use, guarded by a lock. From then on, ChatModel treats MCP tools exactly like local function tools — the model sees them in its tool list, picks one, and Solon AI routes the invocation through callTool(name, args).

Four channels, one builder

McpChannel defines STDIO, SSE, STREAMABLE, and STREAMABLE_STATELESS. The builder picks the transport for you:

Channel	Transport	Typical use
`STDIO`	`StdioClientTransport`	Launching a local MCP binary as a subprocess
`SSE`	`WebRxSseClientTransport`	Classic HTTP + server-sent events
`STREAMABLE`	`WebRxStreamableHttpTransport`	Modern streamable HTTP, stateful session
`STREAMABLE_STATELESS`	`WebRxStreamableHttpTransport`	Stateless streamable HTTP, LB-friendly

For per-call granularity instead of defaults, push the tool list into the prompt options:

chatModel.prompt("今天杭州的天气情况？")
        .options(options -> options.toolAdd(mcpClient.getTools()))
        .stream()
        .filter(e -> e.is(ChatEventType.TEXT_DELTA) && e.hasText())
        .map(ChatEvent::getText);

Note how this composes with the ChatEvent streaming API from the first post in this series — MCP tools and semantic events are orthogonal layers.

Self-healing connections

Network transport code fails in boring, repetitive ways. McpClientProvider centralizes the retry:

public <T> T executeWithRetry(Function<McpAsyncClient, Mono<T>> action) {
    try {
        return action.apply(getClient()).block();
    } catch (Throwable ex) {
        if (isTransportError(ex)) {
            this.reset();                                 // drop the broken client
            return action.apply(getClient()).block();     // reconnect, retry once
        }
        throw ex;
    }
}

isTransportError matches McpTransportException, timeouts, connection refusals, and friends. Protocol-level errors (a tool that returned an error, for example) propagate untouched — retrying those would be wrong.

If you enable heartbeats, a failed beat doubles the backoff interval on each retry, capped at 10 minutes. Intervals under 5 seconds are rejected outright. And note the asymmetry: the server sends heartbeats every 30s by default, while the client opts in explicitly — a deliberate choice to keep the client quiet unless you ask.

Caching and change notification

Listing tools, resources, and prompts over MCP is a round trip you do not want on every prompt. The client caches these lists locally for 30 seconds by default (cacheSeconds). When the server emits a change notification, the matching cache entry is invalidated — the next listing goes back over the wire. The notification clears the cache; it does not push the new list. Subtle, but it is the difference between "eventually fresh" and "push-updated," and it keeps the client simple.

Tool allow-lists and deny-lists

allowedTools and disallowedTools filter what the client exposes. Filtering applies the allow-list first, then the deny-list — so a tool must pass both gates to reach your model. Handy for exposing a curated subset of a large third-party MCP server.

Configuration-driven wiring

Instead of building clients in code, bind them from configuration under the solon.ai.mcp.client.<name> prefix:

@Bean
public McpClientProvider clientWrapper(
        @Inject("${solon.ai.mcp.client.demo}") McpClientProvider client) {
    return client;
}

There is also McpClientProviders.fromMcpServers(uri) for loading a whole mcpServers-style map at once — useful when your tool landscape lives in config rather than Java.

Gotchas I hit while reading the source

The Javadoc lies a little. The class-level example in McpClientProvider shows .apiUrl(...) and .defaultToolsAdd(...); the actual builder method is .url(...), and the demo code uses defaultToolAdd. Trust the code, not the comment — I have reported the drift.
-parameters matters. Without the compiler flag, parameter names vanish from bytecode, and @Param needs an explicit name.
Heartbeat defaults are asymmetric. Server: 30s on. Client: off. Do not assume both ends keep-alive the same way.
Stateless is a mode, not a transport. STREAMABLE_STATELESS uses the same HTTP transport; the difference is in session handling on the server host.

When does this matter?

The annotation server shines when you have an existing Solon service full of business methods that AI agents suddenly need to call. The client shines when you want to compose capabilities across process boundaries — a weather server here, a database MCP there, all flowing into one ChatModel with retries and caching you did not write.

Together with the streaming events and semantic splitting covered earlier, that completes a picture worth remembering: Solon AI treats MCP not as a bolt-on integration but as another expression of the same builder-and-provider abstractions the rest of the framework runs on.

References

Solon AI repository and docs: https://solon.noear.org/article/learn-solon-ai
Model Context Protocol specification: https://modelcontextprotocol.io
Earlier in this series: Semantic Chat Events, SemanticSplitter

Verified against the Solon AI 4.1.x source tree; class and method names reflect that version.

Chunk by Meaning, Not Just Size: A Deep Dive into Solon AI's SemanticSplitter

Solon Framework — Mon, 07 Sep 2026 06:07:19 +0000

Chunk by Meaning, Not Just Size: A Deep Dive into Solon AI’s SemanticSplitter

RAG quality is often discussed as if the only question were which vector database to choose. In practice, the shape of the text entering that database matters just as much. If one chunk mixes a refund rule, a shipping exception, and an account-security note, a strong embedding model cannot fully repair the damaged boundary.

Solon AI’s SemanticSplitter offers a different trade-off from regex- and token-based splitting: it uses an embedding model to look for likely topic boundaries before applying a token-size fallback.

This article examines what the implementation actually does in Solon AI v4.1.0, where it fits in the RAG pipeline, and which assumptions an application should still validate.

The splitter is an ingestion-stage component

Solon’s RAG documentation separates the main stages clearly:

DocumentLoader -> DocumentSplitter -> RepositoryStorable.save(...)

DocumentLoader turns a file or other source into Document objects. A DocumentSplitter can then turn large documents into smaller retrieval units. The resulting documents are finally stored in a Repository.

SemanticSplitter belongs to the middle stage. It does not query a vector database and it does not decide which documents to retrieve at runtime. Its job is to decide where the boundaries of the documents should be before indexing.

The class is:

org.noear.solon.ai.rag.splitter.SemanticSplitter

and it implements the same DocumentSplitter abstraction used by other Solon AI splitters.

What the default constructor configures

The simplest construction is:

SemanticSplitter splitter = new SemanticSplitter(embeddingModel);

The source defines these defaults:

Setting	Default	Meaning
`similarityThreshold`	`0.5`	A lower similarity marks a candidate boundary
`maxChunkTokenSize`	`512`	Target maximum size for a semantic group
`similarityWindow`	`3`	Number of preceding sentences used as context
`minSentencesPerChunk`	`1`	Minimum distance between accepted boundaries
`delimiters`	`ALL_COMMON_DELIM`	Common English, Chinese, and newline delimiters

These are defaults, not universal production settings. Similarity distributions vary between embedding models, languages, and corpora. A threshold that is useful for one model can be too aggressive or too conservative for another.

The algorithm is a sliding-window comparison

The implementation does not embed the entire document once and then run a generic clustering algorithm. Its flow is more specific:

raw text
  -> sentence-like segments
  -> sliding context windows
  -> embeddings for windows and following sentences
  -> cosine similarities
  -> threshold-based boundaries
  -> token-size fallback
  -> new Documents with inherited metadata

1. Sentence-like segmentation

The splitter scans the text using the configured delimiters. The delimiter remains attached to the preceding segment. The built-in common set includes:

SemanticSplitter.ALL_COMMON_DELIM

which covers ., !, ?, Chinese 。, ！, ？, ；, and newlines.

This is deliberately simpler than a full natural-language sentence parser. If a document uses unusual punctuation or has long sections without the configured delimiters, the resulting segments will reflect that.

2. Build a context window

For each position, the splitter concatenates the next similarityWindow sentences into a window. With the default window of three, the comparison looks conceptually like this:

[sentence 0 + sentence 1 + sentence 2]  vs  [sentence 3]
[sentence 1 + sentence 2 + sentence 3]  vs  [sentence 4]
[sentence 2 + sentence 3 + sentence 4]  vs  [sentence 5]

Each side is embedded. The cosine similarity between the window and the following sentence becomes the signal for that position.

A low score suggests that the next sentence may represent a topic transition. It is a candidate boundary, not a semantic truth guarantee.

3. Apply the threshold

The source uses the direction below:

if (similarities[i] < similarityThreshold) {
    // candidate split
}

This direction matters. Holding the text, model, and other parameters constant, increasing the threshold makes it easier for a position to fall below the threshold, so it will usually create more candidate boundaries. Lowering the threshold usually keeps larger groups together.

The result is not a simple linear knob. The final chunks also depend on the embedding model, the window size, the minimum-sentence rule, and the token fallback.

4. Enforce a token-size fallback

After semantic groups are created, the splitter counts tokens using its configured jtokkit encoding. If a group is over maxChunkTokenSize, it allocates sentences into smaller groups until the group would exceed the limit.

That makes the token limit a second-stage guardrail, not the primary boundary detector.

There is an important edge case: the fallback only moves whole sentences. If one individual sentence is already larger than the configured maximum, it can still appear as an oversized output chunk. Also, very short documents with no more than similarityWindow segments are returned as one document before the normal embedding and token fallback path runs.

So the safe statement is:

SemanticSplitter applies a token-size fallback to oversized semantic groups, but applications should still validate final chunk sizes for short documents and individually oversized sentences.

Embedding cost is part of the design

Regex splitting and token splitting can be performed locally. Semantic splitting calls the configured EmbeddingModel.

For a document with N segments and a window size of W, the normal path builds approximately:

N - W window texts
N - W following-sentence texts
2 * (N - W) embedding inputs

The inputs are sent in batches according to embeddingModel.batchSize(). The current implementation also requests:

.options(o -> o.dimensions(512))

That detail deserves operational attention. The selected embedding provider must support the requested dimension behavior, and the application should measure whether the chosen dimension preserves acceptable boundary quality for its corpus. Do not assume that every provider interprets dimensionality options identically.

The practical cost model is therefore different:

Splitter	Boundary signal	Typical cost	Main risk
`RegexTextSplitter`	Document structure	Local CPU	Structure may be inconsistent
`TokenSizeTextSplitter`	Token count	Local CPU	A chunk can cross topic boundaries
`SemanticSplitter`	Embedding similarity	Embedding calls plus CPU	Cost and thresholds need validation

This is not a ranking in which the semantic splitter always wins. It is a choice between different failure modes.

Metadata is preserved, but chunk identity is not invented

When the splitter creates a new Document, it passes the original metadata through:

new Document(content, metadata)

That is useful for filters such as:

source file;
department;
tenant;
document version;
access scope.

However, the splitter does not automatically add a chunk number, parent-document ID, page number, character offsets, or neighboring-chunk links. If those fields are needed for citation, deletion, re-indexing, or audit trails, add them in the application’s ingestion layer rather than assuming they are framework-generated.

A production ingestion pipeline might therefore enrich the metadata after splitting:

List<Document> chunks = splitter.split(loadedDocuments);

for (int i = 0; i < chunks.size(); i++) {
    // Add application-owned tracking fields here:
    // chunkIndex, sourceId, pageNumber, version, and so on.
}

repository.save(chunks);

The exact metadata API depends on the application’s ownership model. The important design point is that chunk tracking is an application responsibility unless the loader already supplies the required fields.

How to evaluate it instead of guessing

Semantic chunking should be evaluated with the same discipline as a retrieval model. A useful experiment can use one mixed-topic corpus containing, for example:

refund rules;
shipping compensation;
account-security requirements;
similar vocabulary across all three sections.

Compare at least these measurements:

number of produced chunks;
average and P95 token count;
number of chunks crossing a known section boundary;
embedding request count;
ingestion latency;
Recall@K on a fixed question set;
retrieved-context token count;
whether the final answer cites the correct section.

A small parameter sweep is also more informative than copying defaults blindly:

similarityThreshold: 0.35 / 0.50 / 0.65
similarityWindow:    1 / 3 / 5
maxChunkTokenSize:   256 / 512 / 1024

Report results with the corpus, embedding model, parameter values, and measurement method. Without those details, a claim such as “semantic splitting improves accuracy” is too broad to be reliable.

Where Agent RAG fits

Solon AI has separate concepts for ingestion and runtime retrieval. A useful mental model is:

SemanticSplitter
      -> better-shaped Documents
      -> Repository
      -> RepositoryTool
      -> ReActAgent

These components answer different questions:

SemanticSplitter: where should the knowledge be divided?
Repository: where are the indexed documents stored and searched?
RepositoryTool: how can retrieval be exposed as a tool?
ReActAgent: when should the agent search, and whether it should search again?

Improving chunk boundaries can help the retrieval layer, but it does not turn the splitter into an agent. Conversely, an agent cannot reliably compensate for every bad ingestion boundary. Treat the ingestion strategy and runtime strategy as separate, measurable layers.

A practical decision guide

Use a structure-based splitter when:

headings and paragraphs are reliable;
indexing cost must be minimal;
deterministic boundaries are important;
you need straightforward debugging.

Use a token splitter when:

model input limits are the dominant constraint;
the corpus has weak structure;
you want predictable chunk sizes;
the retrieval quality trade-off is acceptable.

Evaluate SemanticSplitter when:

the corpus contains frequent topic transitions inside long sections;
structural delimiters are not enough;
you can afford embedding work during ingestion;
you have a representative retrieval benchmark.

A hybrid pipeline can also be reasonable, but its order and benefit should be tested on the target corpus rather than declared as a universal best practice.

Closing thoughts

SemanticSplitter is interesting precisely because it is not magic. It is a concrete algorithm with visible costs and boundaries:

sentence-like segmentation first;
sliding-window embeddings;
cosine similarity as a boundary signal;
threshold-based grouping;
token-size fallback;
metadata inheritance;
no automatic chunk identity model.

That makes it possible to reason about, benchmark, and adapt. In a Solon AI RAG pipeline, the best splitter is not the one with the most sophisticated name. It is the one whose boundary behavior, embedding cost, and retrieval results are understood on your own documents.

Sources

Beyond Token Streaming: Solon AI 4.1's Semantic Chat Events

Solon Framework — Mon, 07 Sep 2026 04:30:29 +0000

Streaming an LLM response looks simple until the response contains more than text.

Depending on the provider, a modern stream may include reasoning fragments, tool-call arguments, citations, media updates, safety decisions, usage snapshots, status messages, and errors over the same connection. Treating every frame as “another partial response” pushes provider-specific parsing into the UI and makes it difficult to distinguish a transient fragment from the final answer.

Solon AI 4.1 addresses that problem with a semantic event stream:

Before 4.1:       Flux<ChatResponse>
Starting with 4.1: Flux<ChatEvent>

The change is more than a generic type replacement. ChatEvent represents what is happening while a response is in flight. ChatResponse represents an aggregated result. The distinction gives application code a vocabulary for text, reasoning, tools, lifecycle, usage, and failure without requiring it to understand every provider's raw SSE dialect.

This article builds on the official streaming event guide and checks the behavior against the Solon AI 4.1 source and core tests. One important qualification: the event API is marked @Preview("4.1") in the current source, so treat it as a preview contract that may evolve in future releases.

`call()` and `stream()` now answer different questions

The synchronous API still asks for the completed answer:

ChatResponse response = chatModel.prompt("Explain semantic streaming").call();
String text = response.getText();

The streaming API asks to observe the response lifecycle:

Flux<ChatEvent> events = chatModel
        .prompt("Explain semantic streaming")
        .stream();

That difference prevents an intermediate frame from pretending to be a complete response.

For a text-only projection, select the exact semantic event you need:

Flux<String> text = chatModel.prompt(message).stream()
        .filter(event -> event.is(ChatEventType.TEXT_DELTA)
                && event.hasText())
        .map(ChatEvent::getText);

Two details are intentional:

isDelta() is too broad for a typewriter projection. It also covers reasoning, tool arguments, media partials, and refusal deltas.
getText() is nullable. hasText() keeps a Reactor map from receiving a null result.

This is the first practical rule of the new model: project by meaning, not by transport shape.

Nine groups provide the current routing layer

The current source defines 31 event types organized into nine groups:

Group	What it represents	Representative events
`LIFECYCLE`	Whole-response state	`RESPONSE_START`, `STATUS`, `HEARTBEAT`, `RESPONSE_END`, `ABORT`
`STEP`	One model round	`STEP_START`, `STEP_END`
`TEXT`	User-visible answer text	`TEXT_START`, `TEXT_DELTA`, `TEXT_END`
`THINKING`	Reasoning-related output	`THINKING_START`, `THINKING_DELTA`, `THINKING_END`
`TOOL_CALL`	Client-executed tools	`TOOL_CALL_START`, `TOOL_CALL_ARGS_DELTA`, `TOOL_CALL_END`, `TOOL_RESULT`
`SERVER_TOOL`	Provider-side tools	`SERVER_TOOL_START`, `SERVER_TOOL_ARGS_DELTA`, `SERVER_TOOL_RESULT`
`MEDIA`	Citations and generated media	`CITATION`, `MEDIA_PARTIAL`, `MEDIA_DONE`
`SAFETY`	Refusals and filtering	`REFUSAL_DELTA`, `CONTENT_FILTER`
`META`	Usage, errors, raw and custom data	`USAGE`, `ERROR`, `RAW`, `CUSTOM`

These groups are useful when building a generic router. Specific event types can evolve while the application keeps stable top-level destinations:

void route(ChatEvent event) {
    switch (event.getGroup()) {
        case TEXT:
            if (event.is(ChatEventType.TEXT_DELTA) && event.hasText()) {
                ui.appendAnswer(event.getText());
            }
            break;
        case THINKING:
            if (event.is(ChatEventType.THINKING_DELTA) && event.hasText()) {
                ui.appendReasoning(event.getText());
            }
            break;
        case TOOL_CALL:
            toolPanel.accept(event);
            break;
        case SERVER_TOOL:
            serverToolPanel.accept(event);
            break;
        case MEDIA:
            mediaPanel.accept(event);
            break;
        case SAFETY:
            safetyPanel.accept(event);
            break;
        case STEP:
            timeline.accept(event);
            break;
        case LIFECYCLE:
            lifecycle.accept(event);
            break;
        case META:
            diagnostics.accept(event);
            break;
        default:
            log.debug("Unhandled event type: {}", event.getType());
    }
}

Keeping a default branch is still sensible for preview APIs and future versions.

An event-phase `END` is not necessarily the end of the stream

Events also have phases such as START, DELTA, END, and NONE. The word END is local to an event scope.

For example:

TEXT_END closes a text block;
THINKING_END closes a reasoning block;
TOOL_CALL_END closes one tool call;
STEP_END closes one model round;
RESPONSE_END closes a successful response lifecycle.

Use event.isTerminal() when you mean a whole-stream semantic terminal. In the current enum, it is true for:

RESPONSE_END
ABORT
ERROR

Do not replace that check with event.getPhase() == END. ERROR is terminal but has phase NONE, while several local boundary events have phase END without terminating the response.

Recover the final response from `RESPONSE_END`

If a caller needs the final aggregate while using the streaming path, it should select RESPONSE_END first:

ChatResponse response = chatModel.prompt(query).stream()
        .filter(event -> event.is(ChatEventType.RESPONSE_END))
        .map(ChatEvent::getResponse)
        .blockFirst();

The asynchronous form can expose the first matching terminal response as a Mono<ChatResponse>:

Mono<ChatResponse> response = chatModel.prompt(query).stream()
        .filter(event -> event.is(ChatEventType.RESPONSE_END))
        .map(ChatEvent::getResponse)
        .next();

Calling blockFirst() on the unfiltered stream is a classic migration mistake. The first event is normally RESPONSE_START, not the final answer.

The caller does not need to concatenate every TEXT_DELTA to reconstruct the official final response. Solon AI accumulates the response internally and attaches the aggregate to the terminal event. Local concatenation can still be useful for immediate rendering, but it should be treated as a UI projection rather than the source of truth for tool calls, usage, and the complete assistant message.

The normalizer creates consistent stateful event boundaries

Provider stream formats differ in how consistently they expose boundaries. A provider may send a text delta without an explicit text-start frame. Tool-call fragments may omit a stable identifier after the first frame. Reasoning and answer text may alternate. A stream can terminate while a content block is still open.

ChatEventNormalizer sits between parsed provider semantics and the subscriber. Its job is to make event boundaries usable:

TEXT_START -> TEXT_DELTA* -> TEXT_END
THINKING_START -> THINKING_DELTA* -> THINKING_END
TOOL_CALL_START -> TOOL_CALL_ARGS_DELTA* -> TOOL_CALL_END

For text and thinking blocks, the normalizer uses stricter tracking:

a bare delta can cause a matching start to be synthesized;
duplicate starts for the same block are dropped;
an unmatched end is dropped;
switching between thinking and text closes the previously open block;
completion closes remaining open blocks.

Tool calls use a deliberately looser policy. An arguments delta can synthesize a start when no call is open, and an unmatched end is preserved. This is not a malformed-stream validator. It is a compatibility layer for providers whose later argument fragments do not repeat a complete tool-call ID.

That difference is important when writing application code. The normalizer provides compatibility-oriented boundary completion, not strict tool-call identity validation. Use normalized events for rendering and correlation, but read the complete ToolCall objects from a completed step or final response rather than assuming that one argument delta contains valid JSON.

Tool execution introduces steps

An automatic tool workflow is not a single model round. It commonly looks like this:

RESPONSE_START
  STEP_START (0)
    TOOL_CALL_START
    TOOL_CALL_ARGS_DELTA ...
    TOOL_CALL_END
    TOOL_RESULT
  STEP_END (0)
  STEP_START (1)
    TEXT_START
    TEXT_DELTA ...
    TEXT_END
  STEP_END (1)
RESPONSE_END

The response lifecycle remains one unit, while each provider request becomes a step. The current implementation starts step numbering at zero and increments it for recursive model calls.

A normally completed STEP_END event carries the terminal snapshot and usage for that step. RESPONSE_END carries the whole successful response aggregate and cross-step usage total. This lets an observability system answer two different questions:

What did this model round produce and cost?
What did the complete tool-assisted response produce and cost?

Tool argument fragments may be interleaved when multiple calls are in flight. Correlate them by toolCallId when one is available; do not build a parser that assumes all fragments for one call arrive as a single contiguous JSON document.

Usage is a two-level aggregation problem

Usage data is easy to overcount.

Within one provider step, usage frames are commonly cumulative snapshots. Adding every frame would count the same tokens repeatedly. Across steps, however, each step is a separate model request, so completed-step totals need to be added.

Solon AI's stream session reflects that distinction:

within a step: keep/merge the provider snapshot
across steps:  add completed-step usage

Consequently:

STEP_END.getUsage() describes the current completed step;
RESPONSE_END.getUsage() describes the accumulated successful response;
a standalone USAGE event is an observation, not an instruction to blindly add every value it contains.

The source also preserves provider usage metadata across steps. Numeric fields such as token and server-tool counts are accumulated, while label-like values use different merge behavior. The larger lesson is portable: billing telemetry needs a scope model, not just a counter.

Errors, aborts, and cancellation are different

A production subscriber must distinguish three mechanisms.

`ERROR` and Reactor `onError`

For failures that enter the main reactive error path, Solon AI attempts to expose an ERROR event before terminating the Reactor stream with an error. The two channels serve different purposes:

the event channel can carry semantic context such as a previously completed response snapshot or accumulated usage;
Reactor onError drives retry, fallback, timeout, and recovery operators.

They describe one failure, not two failures. Also, do not assume that ERROR.getResponse() contains the partially streamed text from the currently failing step. The aggregate may contain only previously completed steps, or it may be null when the first step fails early.

A custom event filter can suppress a META event such as ERROR, while Reactor onError still arrives. Keep an error consumer even if the UI also handles error events:

chatModel.prompt(query).stream().subscribe(
        this::route,
        error -> recoverOrReport(error),
        () -> markTransportComplete());

`ABORT`

ABORT is an upstream semantic event. It is not the same thing as the subscriber cancelling its subscription. Application code can route it as a lifecycle signal, but should not infer Reactor cancellation from it.

Reactor cancellation

Operators such as take(...) may cancel the subscription. Once cancellation occurs, the downstream cannot expect extra events. In particular, it should not wait for synthetic TEXT_END, STEP_END, ABORT, or RESPONSE_END events after it has cancelled.

Cleanup belongs in Reactor lifecycle hooks such as doFinally, not in a handler that assumes every path ends with RESPONSE_END:

chatModel.prompt(query).stream()
        .doFinally(signal -> releaseUiResources(signal))
        .subscribe(this::route, this::recoverOrReport);

Event filtering is delivery policy, not aggregation policy

The default filter rejects high-volume HEARTBEAT and unmodeled RAW events. Diagnostic or gateway code can request more:

chatModel.prompt(query)
        .eventFilter(ChatEventFilter.all())
        .stream();

Or it can extend the default policy:

ChatEventFilter filter = ChatEventFilter.DEFAULT.or(
        ChatEventFilter.of(ChatEventType.RAW));

chatModel.prompt(query)
        .eventFilter(filter)
        .stream();

There is a subtle source-level detail worth knowing. Runtime filtering is guarded so lifecycle and step groups survive a non-null custom filter. Therefore, this:

.eventFilter(ChatEventFilter.of(ChatEventType.TEXT_DELTA))

does not mean the subscriber will receive only text deltas. Lifecycle and step events remain available for aggregation and boundaries. In the current preview implementation, the interaction between the default filter, guarded custom filters, and HEARTBEAT is nuanced because heartbeat itself belongs to the lifecycle group.

The robust approach is:

use eventFilter to control broad delivery volume;
still use an exact downstream filter when projecting one semantic channel;
use ChatEventFilter.all() only when raw protocol visibility is genuinely needed.

Filtering happens after Solon AI's internal normalization and aggregation. Hiding an event from a subscriber does not undo the internal final response.

A provider dialect translates frames; it should not duplicate semantics

A custom provider integration implements the streaming parser entry point:

void parseResponseJson(ChatStreamContext ctx, String respJson);

Conceptually, there are two output paths:

Put primary content such as answer text, reasoning, and client tool calls into the accumulator so the core can generate standard events and aggregates.
Emit semantic events directly for provider capabilities such as citations, status, server-side tools, or specialized media.

The following is illustrative pseudocode; readProviderResponseId, readTextDelta, readCitation, and buildCitation are provider-specific helpers:

@Override
public void parseResponseJson(ChatStreamContext ctx, String json) {
    ctx.setProviderResponseId(readProviderResponseId(json));

    String text = readTextDelta(json);
    if (text != null && !text.isEmpty()) {
        ctx.getAccumulator().addContentItem(
                new AssistantMessage(text));
    }

    String citationUrl = readCitation(json);
    if (citationUrl != null) {
        ctx.emit(ctx.event(ChatEventType.CITATION)
                .block(buildCitation(citationUrl))
                .build());
    }
}

Do not send the same semantic payload through both paths. If text is added to the accumulator and also emitted as a text delta, consumers can see duplicate deltas and the aggregate can be corrupted.

The unified layer is valuable precisely because provider frames and application events are not one-to-one. A single frame may update usage and text; one semantic tool call may span many frames. The dialect should translate provider protocol, while the core owns the cross-provider event contract.

A practical migration checklist

When moving pre-4.1 streaming code to the preview event model:

Replace Flux<ChatResponse> declarations with Flux<ChatEvent>.
Render answer text only from TEXT_DELTA plus hasText().
Route reasoning separately from answer text.
Do not use isDelta() as a synonym for user-visible text.
Select RESPONSE_END before calling blockFirst() or next() for the final response.
Read completed tool calls from STEP_END or RESPONSE_END, not from one arguments fragment.
Treat STEP_END usage and RESPONSE_END usage as different scopes.
Keep Reactor error handling even when consuming ERROR events.
Treat cancellation as a transport/control action, not as ABORT.
Revisit custom dialects for the parseResponseJson(ChatStreamContext, String) contract.
Re-check the exact 4.1 preview API before upgrading future versions.

What the tests establish

The core source contains focused tests for the event model. I ran these three deterministic suites against the reviewed checkout:

ChatEventNormalizerTest       20 tests
ChatEventFilterTest            6 tests
ChatStreamSessionUsageTest     9 tests
---------------------------------------
Total                         35 tests

Result:

Tests run: 35, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

They provide a useful regression net for boundary normalization, filter composition, and cross-step usage aggregation. They do not prove every arbitrary event sequence, every provider's behavior, deep immutability of every payload, or every cancellation race. Provider capabilities also differ: an application must not expect every dialect to emit reasoning, citations, media, safety, server-tool, or usage events.

The architectural payoff

The most useful part of Solon AI 4.1's streaming redesign is not the number of event types. It is the separation of responsibilities:

provider SSE / JSON frames
          ↓
provider dialect parsing
          ↓
semantic accumulation and event emission
          ↓
boundary normalization
          ↓
application routing and protocol adapters

A UI can focus on rendering. An agent can focus on tool steps. An observability layer can focus on usage and failure. A gateway can opt into raw events without forcing ordinary consumers to pay that cost.

Token streaming answers, “What bytes arrived next?” Semantic streaming answers, “What happened next?” For applications that combine reasoning, tools, citations, safety, and multiple provider calls, the semantic model is generally easier to extend.

DEV Community: Solon Framework

One Event Stream, Two UI Protocols: Wiring Solon AI to Any Frontend

The layering rule: adapters may not know what an agent is

Adapter 1: Vercel AI SDK

Adapter 2: AG-UI

The five details that decide whether this works in production

Which adapter?

Getting started

An Agent That Finishes: Inside Solon AI's Loop Engine

1. What it actually is

2. The state machine

3. Three strategies, three shapes of "keep going"

Ralph — PRD-driven story loop

Team Pipeline — phase-ordered collaboration

UltraQA — the quality gate loop

4. The part I actually like: named exit reasons

5. State that outlives the JVM

6. Validation is an interface, not an opinion

7. Autopilot: chaining strategies into one pipeline

8. Wiring it into a Solon app

9. Getting started

10. When not to use this

One Router, Four Strategies: How Solon AI Picks the Right ChatModel

1. It Does Exactly One Thing: Pick a ChatModel for You

2. Basic Usage

3. Four Built-in Strategies, From Dumb to Smart

1) RoundRobinRoutingStrategy

2) WeightedRoundRobinRoutingStrategy

3) RuleBasedRoutingStrategy

4) SmartRoutingStrategy — an LLM as the Dispatcher

4. Explicit Routing: The Escape Hatch

5. Error Semantics: No Magic, Only Determinism

6. Choosing a Strategy

Wrapping Up

What Makes a Coding Agent Trustworthy? A Look at SolonCode's Design Choices

A trust checklist for coding agents

1. Can I read the source?

2. Where does my code go?

3. Am I locked into one vendor?

4. Can I control what it does?

5. Can I undo a mistake?

Trust is a property you can check

Build a RAG Pipeline in Java with Solon AI: From Raw Text to Grounded Answers

The moving parts

Add the dependency

The whole pipeline in one file

What the API is actually doing

Document — plain data, no magic factory

Splitting is a pipeline

save() embeds for you

QueryCondition controls retrieval

Augmentation: two ways

Going beyond in-memory

Swap in a real vector store

Load real documents

Filter by metadata with SnEL

Let the agent retrieve on its own

Wrapping up

SnEL Inside the Container: How Solon Wires Expressions Into Config, Beans, Cache and Data Sources (Java)

The dispatcher: #{...} vs ${...}

1. Resolving placeholders anywhere

2. Injection: config values and evaluated values

3. Conditional beans with @Condition(onExpression=...)

4. Method caching: templating keys from arguments

5. Dynamic data source routing with @DynamicDs

6. Validation messages: a per-instance SnelParser

Why do it this way?

One Expression, Many Databases: A Tour of Solon's SnEL Engine (Java)

Adding the dependency

The philosophy: an evaluator, not a scripting language

Evaluating expressions

The syntax at a glance

Beans as context, and virtual variables

Template expressions

The interesting part: one tree, many query languages

Building the tree by hand

When to use it

Wrapping up

Tool Calling in Java, the Simple Way: Building an AI Agent with Solon AI

What we're building

`Document` — plain data, no magic factory

`save()` embeds for you

`QueryCondition` controls retrieval

The dispatcher: `#{...}` vs `${...}`

3. Conditional beans with `@Condition(onExpression=...)`

5. Dynamic data source routing with `@DynamicDs`

6. Validation messages: a per-instance `SnelParser`

The client: `McpClientProvider`

`call()` and `stream()` now answer different questions

An event-phase `END` is not necessarily the end of the stream

Recover the final response from `RESPONSE_END`

`ERROR` and Reactor `onError`

`ABORT`