This page reflects the pre-1.0 roadmap as of October 2026: the latest release is v0.5.1; v0.5.0 was the first with the split module artifacts. It replaces the June 2026 snapshot, which still named v0.3.2 as current, and it links the community mentorship tracks (LFX, ESoC) to the phases they advance. Which packages 1.0 freezes is stated on 1.0 Scope; this page is the plan for getting there.
LLM4S has broad, working framework functionality today: multi-provider clients (including Vertex AI and AWS Bedrock), agents, tool calling, RAG/vector stores, GraphRAG/Neo4j, memory, guardrails (including prompt-injection detection), tracing, metrics, JMH benchmarks, reliability wrappers, workspace isolation, MCP transports with auth hardening, multimodal APIs (vision, image generation, speech), and Java, Kotlin, Spring Boot, cats-effect and ZIO integrations. The code that used to ship as one core artifact is split into per-concern modules (#1126); that split shipped in 0.5.0. The remaining v1.0 work is productization: a binary-compatibility baseline, provider capability parity, default-deny tool/MCP security, unified cost telemetry, deterministic CI, runnable docs, and polished reference applications.
0.4.x: coordinate rename and fixes (done) → 0.5.0: modularisation complete, separate artifacts published (done), with 0.5.2 adding the Kotlin API → a pre-1.0 release: designs final, MiMa baseline set → 1.0: frozen surface, after it has survived two releases
Main branch
Work after 0.5.1; see the CHANGELOG’s Unreleased section
Artifacts
org.llm4s:llm4s-*. The pre-0.4.0 coordinates (org.llm4s:core, …) stop at 0.3.4; see the migration guide
Stability
Pre-1.0, API stabilizing; each package’s tier is on 1.0 Scope
Scala support
Scala 3.7.1 only. Scala 2.13 is deferred to after 1.0 (#874)
Java support
JDK 21 is required (and the only JDK CI runs); see 1.0 Scope
Target
v1.0 production-ready stable modules
Timeline
2026 H2 stabilization phases; the v1.0 date is intentionally not fixed
Mentorship
LFX Mentorship 2026 · European Summer of Code 2026 · GSoC 2026
Maturity Legend
These tiers match 1.0 Scope, so the two pages agree.
Maturity
Meaning
Frozen at 1.0
Source and binary compatible within the 1.x series once published under its target module.
Beta
Implemented and usable, but API, provider behavior, or docs still need hardening before v1.0.
Experimental
Useful prototype or advanced feature; expect changes.
Planned
Roadmap item, design, issue, mentorship track, or PR queue item; not a stable user contract.
The Status column in the phase tables below is separate from maturity: Landed means merged to main (some of it ships first in 0.5.0), In progress means partly done, and Planned means not started.
Current Capability Map
Area
Current state
v1.0 gap
Provider clients
Chat: OpenAI, Anthropic, Azure OpenAI, Gemini, Vertex AI, AWS Bedrock, IBM watsonx.ai (Beta), DeepSeek, Cohere, Mistral, xAI (Beta), OpenRouter, Requesty, Z.ai, Ollama, and a generic openai-compatible provider configured from a named section. Embeddings: OpenAI, Voyage, Jina, Ollama. Every provider is a module found on the classpath through the ProviderDescriptor SPI, and llm4s-provider-testkit lets an external author prove one.
Grow the generated capability matrix with facts the descriptors declare (structured output, vision, reasoning, stream usage), and grow the testkit into fake-provider contract tests for chat, streaming, tools, structured output, embeddings, image/audio, timeouts, retries, cost, and raw exchange logging. (ESoC track)
Agents
llm4s-agent: core agents, tool calling, handoffs, guardrails (incl. prompt-injection detector), streaming events, async tools, reasoning modes, and state serialization; memory (incl. LLM entity extraction) in llm4s-memory. A typed graph runtime (middleware, approval barriers, checkpoints, cancellation) exists as a prototype in llm4s-agent (#1266); 1.0 Scope does not tier it yet.
Settle the graph runtime’s tier and graduate it from prototype; durable session stores; Temporal workflows; A2A interop; voice agent loop; replay/debug; compile-test reference apps. (LFX + ESoC tracks)
RAG and vector stores
llm4s-rag and llm4s-knowledgegraph: document loading, chunking, SQLite/pgvector/Qdrant, keyword indexes, hybrid search, reranking, RAGAS-style evaluation, permission-aware RAG, WebCrawlerLoader (BFS/robots/rate limits), GraphRAG with an optional Neo4j store.
Sitemap + concurrent + JS crawl; unified cost/latency across RAG; runnable golden-path tutorials; production reference deployments. (LFX track)
Tooling and MCP
The tool API stays in llm4s-core; the built-in tools are in llm4s-agent-tools; llm4s-mcp has client and server, Streamable HTTP, HTTP+SSE, bearer-token auth, and public-bind protection; workspace isolation is in llm4s-workspace-*.
Console tracing in core; Langfuse, the trace collector and CostTracker in llm4s-observability; OpenTelemetry in llm4s-observability-otel; Prometheus in llm4s-observability-prometheus; tracing backends are discovered through an SPI. Image-generation cost hooks and agent usage summaries exist.
Unified cost/token telemetry across request/agent/session/RAG/multimodal; retention/redaction guidance; agent run replay; regression thresholds on JMH. (ESoC track)
Reliability
ReliableClient supports retry, circuit breaker, deadlines, rate limiting and metrics; every client sends through one HTTP layer that honours a 503’s Retry-After; a sample exists.
Multi-provider failover & hedging; consistent timeouts/retries across providers; health checks. (LFX track)
JVM interop
llm4s-java-api (Java-friendly layer), a Kotlin coroutine API, llm4s-spring-boot-starter, llm4s-effect (cats-effect), llm4s-zio and llm4s-pekko (Apache Pekko Streams), plus a Gradle integration guide and gradle-demo. These ship in 0.5.0, except the Kotlin API, which ships from 0.5.2.
Maven quickstart; CI-tested sample projects for each path.
Docs and examples
Broad docs and samples, migration guides (0x-to-1x), troubleshooting, 1.0 Scope, the compatibility policy, GOVERNANCE/MAINTAINERS/RELEASES, Scaladoc for every module, and install snippets that follow the latest release (checked by scripts/check-doc-versions.sh).
Remove/label remaining pseudocode placeholders; runnable golden-path tutorials from capability metadata.
Security and governance
Secret scanning, API-key redaction, workspace sandboxing, Dependabot, a threat model (security.md), config-policy module + CI gate, MCP auth hardening, DCO checks.
Suite timeouts / hang isolation; split fast/integration/Docker/provider/benchmark jobs.
API stability
@Stable/@Experimental mark a public type’s tier in the code; a compatibility and deprecation policy is published; frozenDependencyCheck and publishedArtifactsCheck guard the frozen modules and the artifact list; MiMa is wired into the build.
Set the MiMa baseline at a pre-1.0 release once the designs are final, and enforce it from 1.0 once the frozen surface has survived two releases.
Provider parity
Broad coverage, one SPI, a provider testkit; uneven feature parity.
Fake-provider contracts; more declared facts in the generated capability matrix.
JVM adoption
Strong Scala-native design; Java, Spring Boot, cats-effect and ZIO modules, published from 0.5.0, and Kotlin from 0.5.2.
Maven and Gradle paths with CI-tested runnable samples.
Wired in the build; baseline set at a pre-1.0 release once the designs are final (0.5.0 sets none), enforced from 1.0 once the frozen surface has survived two releases.
Package-level Scaladoc
In progress
Public API intent documented; the published Scaladoc covers every module.
The compatibility matrix is generated from the descriptors and the build, and CI fails when it drifts. Structured output, vision, reasoning and stream usage are not declared by descriptors yet.
Consistent integrations: base URL, headers, Retry-After and the proxy and TLS settings (llm4s.http, #2273) are handled in one place; request-ID options are not yet exposed.
Tool poisoning / prompt-injection guidance beyond the detector
Planned (ESoC)
MCP treated as a security boundary.
SBOM + release-gate security tests
Planned
Auditable release artifacts.
Phase 5: Reliability, Cost, Observability, And Scale
Target: v1.0 RC · LFX + ESoC tracks.
Deliverable
Status
Outcome
ReliableClient + sample
Landed
Retry/circuit/deadline patterns usable.
JMH benchmarks module
Landed
Perf measurement infrastructure exists.
Staged-deployment template (dev, staging, prod)
Landed
A copyable rollout pattern with a health gate.
Multi-provider failover & hedging
Planned (LFX)
Graceful degradation across providers.
Unified cost & token telemetry
Planned (ESoC)
Spend control across agents/RAG/multimodal.
Persistent session store (Redis/Postgres)
Planned (LFX)
Resume conversations across restarts.
Durable Temporal workflows
Planned (ESoC)
Crash-safe long-running agents.
Health checks; JMH regression thresholds; reference apps
Planned
Production-operable defaults.
What Landed Since The June 2026 Snapshot
Release
Highlights
v0.3.3
MCP SSE transport and bearer-token auth with a constant-time comparison and a public-bind guard; image generation with cost tracking; LLM-driven memory entity extraction; the streaming chat-TUI sample; a published threat model, Dependabot, API-key redaction in provider errors; a ReDoS fix.
v0.3.4
Dependency updates, Docker image fix, Scaladoc for LLMCompressor and ContextManager.
v0.4.0
Every published artifact renamed to llm4s-* (coordinates only; no API or package change).
v0.4.1
Fixes to the Neo4j and Qdrant stores, and integration suites that had been run by nothing now run in tiers.
v0.5.0
The modular split (slices 1–7); the provider SPI and testkit; Bedrock, watsonx.ai and Jina providers; llm4s-java-api, Spring Boot, cats-effect and ZIO modules; the typed graph runtime prototype; the @Stable/@Experimental tiers, the compatibility policy and MiMa wiring; the staged-deployment template.
v0.5.1
Multimodal content parts in user messages and tool results; the agent harness’s backend SPIs (FileBackend, SandboxBackend, LongTermStore), filesystem tools, context management (summarisation, tool-output offload), Agent Skills, instruction memory (AGENTS.md) and the harness profile (HarnessProfile).
Community Mentorship Tracks (2026)
These are planned contribution paths aligned with the phases above. Details and mentors live in the linked idea lists.
Broader idea list (agents, RAG, data pipelines, hardware design, demos): GSoC Project Ideas 2026.
Reference Applications Needed For v1.0
Application
Purpose
Spring Boot RAG API with pgvector or Qdrant
JVM production service with auth, metrics, tracing, cost tracking, and deployment notes.
Sandboxed tool-calling agent with MCP
Secure agent workflow with explicit policies and audit logging.
Kotlin coroutine service
Kotlin-native API usage and error handling.
Java/Gradle quickstart
Minimal non-Scala adoption path (the Gradle guide and demo are the start).
Observability and evaluation sample
Langfuse/OpenTelemetry/Prometheus plus RAG evaluation and replay/debugging.
TermFlow streaming chat TUI
Terminal golden-path demo (ESoC track).
Release Policy Direction
Area
Direction
Pre-1.0 releases
Regular previews while APIs stabilize. 0.4.x was the artifact rename and fixes; 0.5.0 completes the modularisation and publishes the separate artifacts; a later pre-1.0 release sets the MiMa baseline once the designs are final.
v1.0
Freeze the stable modules once they have survived two releases, publish a migration guide, document known limitations, and require compatibility/security/performance gates. Scala 3 only.
Post-1.0
Semantic Versioning with binary compatibility checks for stable modules; deferred Scala 2.13 support for the frozen spine is considered then (#874). Experimental modules may retain separate compatibility notes.