DEV Community: Solon Framework

One Interface, Seven Formats: How Solon AI Turns Files, Web Pages, and Even Database Schemas into RAG Documents

Solon Framework — Sat, 10 Oct 2026 02:14:50 +0000

Every RAG pipeline starts the same way: you have stuff, and the model needs Documents.

The interesting question is how far that idea stretches. Solon AI answers it with a deliberately small contract — and then pushes it across seven formats, including one you probably haven't tried feeding to a retriever: your database schema.

This is a source-code tour of solon-ai-rag-loaders. All claims below are checked against the current source tree; where a class behaves in a way you wouldn't guess from its name, I'll point it out.

The Contract Is Three Methods

public interface DocumentLoader {
    DocumentLoader additionalMetadata(String key, Object value);
    DocumentLoader additionalMetadata(Map<String, Object> metadata);
    List<Document> load() throws IOException;
}

That's the entire contract: two metadata methods and one load(). No provider field, no API key, no vendor. Seven Maven sub-modules implement it (solon-ai-load-markdown, -pdf, -word, -excel, -html, -ppt, -ddl), each pulling only its own parsing dependency — commonmark, PDFBox, POI, jsoup, Tika.

The base class AbstractOptionsDocumentLoader adds the options pattern with two entry points:

MarkdownLoader loader = new MarkdownLoader(file)
        .options(o -> o.codeBlockAsNew(true));
// or, if you already hold an Options instance:
loader.options(myOptions);

A SupplierEx<InputStream> constructor appears in every loader, so your source can be a file, a URL, a byte array, or anything else that can produce a stream lazily.

The Default Splitting Tells You What Each Format Means

Seven loaders, and no single "chunk size" knob. Instead, each loader picks its default unit of meaning — and the defaults disagree on purpose:

Loader	Default unit	Default mode
`MarkdownLoader`	Section (per heading)	AST walk, headings always split
`PdfLoader`	Page	`LoadMode.PAGE`
`WordLoader`	Paragraph	`LoadMode.PARAGRAPH`
`PptLoader`	Whole document	`LoadMode.SINGLE`
`ExcelLoader`	Sheet, batched at 200 rows	JSON rows
`HtmlSimpleLoader`	Whole page	Single document
`DdlLoader`	Table	One `SHOW CREATE TABLE` each

That asymmetry is the design. A paragraph is the natural retrieval unit for prose; a page is the natural unit for a PDF; a slide deck usually makes more sense as one document; a table is a complete thought. You can override the defaults (PdfLoader goes SINGLE, WordLoader goes SINGLE, PptLoader splits on "\n\n\n"), but the out-of-the-box behavior already encodes a per-format answer to "what is a chunk here?"

Markdown: Splitting on the AST, Not on Regex

MarkdownLoader doesn't slice text with regexes. It parses the document with commonmark into an AST and walks it with a visitor:

Headings always start a new document. Not an option — a rule.
Three switches default to off: horizontalLineAsNew, blockquoteAsNew, codeBlockAsNew.
Fenced code blocks are more subtle. When codeBlockAsNew(true), the code block starts its own document. Either way, a fenced block always ends its document — so code never bleeds into the prose chunk that follows it.
The produced documents carry metadata you can filter on later: category=header_1..6 with a title, category=code_block with lang, or category=blockquote.

One nuance worth knowing before you rely on metadata: the visitor writes title/category onto the current document while walking. If a section has no heading text before its content, the metadata simply won't be there for that chunk. Fine for retrieval; worth remembering if you build UI on top of it.

PDF and Word: The Same Two Ideas, Different Truth

PdfLoader (PDFBox) defaults to one Document per page, each stamped with page, total_pages, and a summary of "Page 3" — handy in a search UI. Switch to LoadMode.SINGLE and you get the whole file as one document, pages joined by "\n\f", with just a pages count.

WordLoader handles both binary eras: it checks the stream with POI's FileMagic and routes .docx (OOXML) and legacy .doc (OLE2) to different readers. It defaults to paragraph mode — one Document per paragraph — with a SINGLE escape hatch.

Excel: Rows in, JSON Out

ExcelLoader (POI + snack4) treats the first non-empty row of a sheet as the header row, then maps every following row to {column: value} and serializes batches as JSON documents. Two defaults shape its behavior:

200 rows per document. A sheet with 620 rows becomes 4 documents. Set documentMaxRows(-1) to keep one document per sheet.
An empty row stops the sheet. The read loop breaks, so anything after the first blank row is silently ignored — by design, trailing blank rows shouldn't kill the parse, but data below a blank row won't be indexed. Keep that in mind with hand-edited spreadsheets.

Formula cells are read as their formula text, not computed values.

PowerPoint: Trust Tika

PptLoader doesn't parse slide XML itself. It hands the stream to Apache Tika's AutoDetectParser and gets body text back. Default is SINGLE — the whole deck as one document; PAGE mode splits on "\n\n\n" if your decks have predictable slide breaks.

DDL: Your Schema Is Already a Document

This is the one that changes how you think about the pipeline. DdlLoader connects to a plain DataSource (no ORM, no entities) and emits one Document per table containing its DDL:

DdlLoader loader = new DdlLoader(dataSource);   // MySQL config built in
loader.options(o -> o.loadOptions("shop", null)); // schema only: all its tables
List<Document> docs = loader.load();

Three granularities via loadOptions(schema, table): whole instance, one schema, one table. The default configuration is MySQL (information_schema + SHOW CREATE TABLE, system schemas excluded), but every SQL string is a template — the loader runs them through Solon's own expression engine (SnEL.evalTmpl), so you can rewire it for another database by replacing the template set in a DdlLoadConfig.

One detail I like: SHOW CREATE TABLE returns CREATE TABLE \order(...) — a table name that's only meaningful inside its schema. The loader rewrites the header to CREATE TABLE \shop.\order(...) so every retrieved DDL document is self-describing, and stamps metadata("table", "order") so your filter layer can target tables directly.

The use case writes itself: point it at production (read-only!), and your AI assistant retrieves schema facts instead of hallucinating column names.

After `load()`: One Shape Downstream

Whatever the format, load() hands you List<Document> — content plus metadata plus the fluent fields (title, url, summary, id, embedding, score). From here, everything is format-agnostic: embed, store in a Repository, attach as a tool. The loaders are the only place in the pipeline where format-specific knowledge lives.

When You Might Skip This Module

To be fair to your architecture review: if your corpus is already clean Markdown, you might not need seven loaders — Solon AI's splitter story covers embedding-time splitting separately. The loaders earn their keep when sources are heterogeneous (office files, web pages, live schema) or when the natural unit (page, paragraph, table) should decide the chunk, not a character count.

Wrapping Up

solon-ai-rag-loaders is a good example of a small contract held firmly: three methods, seven implementations, and per-format defaults that encode real opinions instead of one generic knob. The DDL loader alone is worth a look if you build assistants that need to talk about your database accurately.

Project: solon-ai on GitHub
Docs: solon.noear.org
All source references in this post were checked against the current source tree of solon-ai-rag-loaders.

One Interface, Three Search Backends: Web Search Is Just Another Repository

Solon Framework — Sat, 10 Oct 2026 01:26:29 +0000

If you build anything with LLMs, you will need web search sooner or later. The model's training data is frozen; your users' questions are not.

In Solon AI, web search is not a special subsystem bolted onto the side. It is a Repository — the same interface a vector store implements, the same interface an in-memory document list implements. That single design decision is the whole story of the solon-ai-rag-searchs family, and it composes in ways you might not expect.

The one method that matters

public interface Repository {
    default List<Document> search(String query) throws IOException {
        return search(new QueryCondition(query));
    }

    List<Document> search(QueryCondition condition) throws IOException;

    default ChatMessage promptAugment(String query) throws IOException {
        List<Document> context = search(query);
        return ChatMessage.ofUserAugment(query, context);
    }
}

One required method. Two defaults on top of it. The interface has been marked @Preview since it landed in 3.1 — which reads as an honest signal: the surface is small enough to grow carefully.

Everything a caller can express goes through QueryCondition:

Field	Default	Notes
`limit`	4	max documents back
`similarityThreshold`	0.4	used by the optional refilter pass
`freshness`	null	`ONE_DAY` / `ONE_WEEK` / `ONE_MONTH` / `ONE_YEAR`
`filterExpression`	null	an `Expression<Boolean>`, parsed from SnEL if you pass a string
`searchType`	`VECTOR`	`FULLTEXT`, `HYBRID` (3.3+) for repositories that support them
`disableRefilter`	false	skip the similarity re-filter pass

Note what is not here: no provider, no apiKey, no vendor field. Those live in the implementation's builder. The interface never learns which search engine answered the question.

Three implementations, three philosophies

Bocha: the reference implementation

BochaWebSearchRepository repo = BochaWebSearchRepository
        .of("https://api.bochaai.com/v1/web-search")
        .apiKey("sk-...")
        .build();

List<Document> docs = repo.search(new QueryCondition("solon framework").limit(5));

The Bocha adapter (@since 3.1) is deliberately plain: build a JSON body with query, count, and optional freshness, POST it, map data.webPages.value[] into Documents. If the response code is not 200, it throws an IOException — no empty-list disguise, no silent fallback.

There is a comment in the source that tells you why it stays this plain: "此示例，可作为对接其它搜索的参考" — "this example can serve as a reference for integrating other search providers". It is the one you copy when you wire up your own provider.

Baidu AI Search: two modes, one flag

BaiduWebSearchRepository repo = BaiduWebSearchRepository
        .ofAI()                              // or ofBasic()
        .apiKey("bce-...")
        .apiUrl("https://qianfan.baidubce.com/v2/ai_search")
        .build();

The Baidu adapter (@since 3.0, built on Baidu's AI Search V2 endpoint) has two personalities:

BASIC — classic results list. No model field is sent; the server infers the mode.
AI — sends model (default ernie-3.5-8k; the builder javadoc also lists deepseek-r1, deepseek-v3, and the ERNIE 4.0 turbo variants) and gets back an LLM-synthesized answer plus references.

Here is the detail I like most: in AI mode, the synthesized answer is returned as the first Document in the same list — titled Solon AI智能回答, with metadata("type", "ai_answer"). References follow it with metadata("source", "baidu_search"). The caller does not need a second type or a special branch to consume an AI answer; it is just document zero.

Your limit is translated into a resource_type_filter of type web with top_k. An empty or blank query short-circuits to an empty list without a network call; an error code in the response becomes an IOException. If nothing at all parses out, that is an exception too — "no content found" is surfaced, not swallowed.

Tavily: search, extract, crawl, map

Tavily is the maximalist of the three. The solon-ai-search-tavily module (@since 3.9.5) exposes four operations through TavilySimpleSearchRepository:

TavilySimpleSearchRepository repo = TavilySimpleSearchRepository
        .of("tvly-...")
        .build();

// Standard Repository path — returns List<Document>
List<Document> docs = repo.search(new QueryCondition("solon framework").limit(5));

// Full Tavily power — returns TavilySearchResponse
TavilySearchResponse resp = repo.search(new SearchCondition("solon framework")
        .topic("news")                // general / news / finance
        .searchDepth("advanced")      // basic / advanced / fast / ultra-fast
        .timeRange("week")            // day / week / month / year
        .includeAnswer("basic")       // LLM answer, basic / advanced
        .includeFavicon(true)
        .includeDomains(List.of("github.com"))
        .maxResults(10));

String answer = resp.getText();        // the LLM answer, if requested
List<Document> docs2 = resp.toDocuments();

Beyond search there is extract(condition) (pull clean content from specific URLs), crawl(condition) (walk a site with maxDepth 1–5, maxBreadth up to 500, path regex filters), and map(condition) (structure-only: just the URL list, cheap, meant to feed a later extract).

The standard QueryCondition.freshness is faithfully translated — ONE_DAY → "day", ONE_YEAR → "year" — so the vendor-neutral path still gets time filtering.

The module actually contains two repository classes, and their names are a trap for the unwary:

TavilyWebSearchRepository — despite the full-sounding name, this is the simplified one: it implements Repository and forwards search to a delegate.
TavilySimpleSearchRepository — despite the humble name, this is the complete one: search with full parameters, extract, crawl, map. It also implements Repository.

The simplified one exposes getFullRepository() so you can start narrow and widen later without rebuilding. (If you find older docs mentioning a TavilySearchRepository, that class name does not exist in the source tree — use TavilySimpleSearchRepository.)

And if you want none of the repository abstraction at all, the underlying TavilyClient is public: ClientBuilder.of(apiKey).apiBase(...).timeout(...).build() gives you the raw four operations.

The optional embedding model — and why you usually shouldn't

All three adapters accept an optional EmbeddingModel. When present, the flow after the HTTP call is identical everywhere:

embeddingModel.embed(docs);
float[] queryEmbed = embeddingModel.embed(condition.getQuery());
return SimilarityUtil.refilter(docs.stream()
        .map(doc -> SimilarityUtil.score(doc, queryEmbed)), condition);

Embed every result, embed the query, score, then refilter — which re-ranks and applies your similarityThreshold and limit.

The module README makes the counterintuitive point explicitly: for web search, similarity re-ranking is usually not meaningful. The snippets come back already ranked by the engine's own relevance machinery, and cosine similarity between a short query and a web snippet is a noisy signal at best. So the guidance is: unless you have a concrete reason, do not pass an embedding model to a web-search repository. The parameter exists for the cases where you do.

This is a nice instance of a general principle: a capability that is off by default and documented as "probably skip this" beats a magic pipeline you cannot turn off.

From passive retrieval to an agent that searches

promptAugment is passive RAG: you search, you glue results into the user message, you send. Fine for FAQs, useless when the model needs to decide whether to search, or what to search for.

Since 3.10.1 there is RepositoryTool:

RepositoryTool tool = new RepositoryTool(webSearchRepo);
// optionally: new RepositoryTool(repo, rerankingModel)

It extends the framework's tool provider base and registers itself as a repository_query tool with two parameters: queries (a list of query strings, hard-capped at 5 per call — the source comment says why: to stop a model from fetching ten pages at once and blowing up its own context) and topK (default 3).

For each query it searches, optionally reranks, and formats results as Markdown with title, relevance score, content, and citation URL. One detail worth copying into your own tools: any document's content is truncated at 2000 characters before it enters the tool response, with an explicit ...(内容过长已截断) marker. Context budgets are defended at the tool layer, not trusted to the model's restraint.

Because it takes any Repository, the same tool class works against a vector store, an in-memory repo, or your Bocha/Baidu/Tavily web repo. One tool, whatever knowledge backend you configured.

When not to use this

You need domain filtering on the neutral path — includeDomains/excludeDomains exist only on Tavily's SearchCondition; the shared QueryCondition has no such field. For the others, put the filtering in your query or downstream.
You expect streaming search results. The interface returns a completed List<Document>; an AI-mode synthesis on Baidu takes however long it takes.
You need hybrid search semantics — searchType(HYBRID) in QueryCondition is for repositories that understand it (3.3+). A web adapter ignores what does not apply to it.

The takeaway

solon-ai-rag-searchs is a small family doing exactly one thing well: making web search interchangeable with every other knowledge source behind Repository. The result is that "add live web knowledge to this agent" becomes a one-line wiring change — and the same wiring upgrades from promptAugment to a self-directed RepositoryTool without touching the backend.

Bocha shows the pattern, Baidu folds an LLM answer into the document list, Tavily goes deep on capabilities — and your agent code sees none of the differences.

All API details above were verified against the source of the solon-ai repository (solon-ai-rag-searchs and solon-ai-core); dependencies are managed by the Solon AI BOM, so no per-artifact version is shown. If you try it, the docs live at solon.noear.org.

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.

DEV Community: Solon Framework

One Interface, Seven Formats: How Solon AI Turns Files, Web Pages, and Even Database Schemas into RAG Documents

The Contract Is Three Methods

The Default Splitting Tells You What Each Format Means

Markdown: Splitting on the AST, Not on Regex

PDF and Word: The Same Two Ideas, Different Truth

Excel: Rows in, JSON Out

PowerPoint: Trust Tika

DDL: Your Schema Is Already a Document

After load(): One Shape Downstream

When You Might Skip This Module

Wrapping Up

One Interface, Three Search Backends: Web Search Is Just Another Repository

The one method that matters

Three implementations, three philosophies

Bocha: the reference implementation

Baidu AI Search: two modes, one flag

Tavily: search, extract, crawl, map

The optional embedding model — and why you usually shouldn't

From passive retrieval to an agent that searches

When not to use this

The takeaway

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)

After `load()`: One Shape Downstream

`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`