GO — Healthy across the board

• Last commit today
• 15 active contributors
• Distributed ownership (top contributor 46% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Spring AI is a Spring Boot framework that abstracts over multiple LLM providers (OpenAI, Anthropic, Google, AWS Bedrock, Ollama, etc.) to build AI applications in Java. It connects enterprise data and APIs with AI models through a unified ChatModel, EmbeddingModel, and ImageModel API, inspired by LangChain but designed natively for the Spring ecosystem with full Spring Boot integration. Multi-module Maven monorepo: core abstractions in spring-ai-core, provider implementations (openai/, anthropic/, etc.) as separate modules, advisors/ contains chat client advisors like QuestionAnswerAdvisor and VectorStoreChatMemoryAdvisor under advisors/spring-ai-advisors-vector-store. Each module has standard Maven layout (src/main/java, src/test/java) with common parent pom.xml (spring-ai-parent).

Java/Spring developers building generative AI applications who want to avoid vendor lock-in, leverage existing Spring patterns (dependency injection, configuration via properties), and use RAG (Retrieval-Augmented Generation) with vector stores. Also appeals to enterprises wanting to add AI capabilities without rewriting backend infrastructure.

Actively developed and production-ready: on Spring Boot 4.x (main branch), published to Maven Central with version 2.0.0-SNAPSHOT, comprehensive CI/CD via GitHub Actions (continuous-integration.yml, maven-central-release.yml), and organized module structure. The advisors module exists with integration tests (QuestionAnswerAdvisorTests.java), indicating battle-tested RAG patterns.

Standard open source risks apply.

Version 2.0.0-SNAPSHOT in active development targeting Spring Boot 4.x; GitHub Actions workflows show ongoing integration testing (mcp-integration-tests.yml), documentation deployment (deploy-docs.yml), and automated cherry-pick/backport for maintenance branches (auto-cherry-pick.yml, backport-issue.yml).

git clone https://github.com/spring-projects/spring-ai.git && cd spring-ai && ./mvnw clean install. Requires Maven 3.6+ (via .mvn/wrapper/maven-wrapper.jar). Java 17+ required (maven.compiler.source=17 in pom.xml). Then run individual module tests: ./mvnw -pl advisors/spring-ai-advisors-vector-store test

Daily commands: Not a runnable app, but a library. To test locally: ./mvnw clean install (builds all modules). To run specific advisor tests: ./mvnw -pl advisors/spring-ai-advisors-vector-store test. To verify docs: ./mvnw -pl docs build (implied by deploy-docs.yml). Requires no external services for unit tests; integration tests (mcp-integration-tests.yml) need live API credentials.

• pom.xml — Root Maven POM defining Spring AI project structure, dependency management, and build configuration for all modules
• auto-configurations/common/spring-ai-autoconfigure-retry/src/main/java/org/springframework/ai/retry/autoconfigure/SpringAiRetryAutoConfiguration.java — Core retry mechanism auto-configuration that all AI model integrations depend on for resilience patterns
• auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/McpClientAutoConfiguration.java — Model Context Protocol client auto-configuration enabling tool-use and dynamic capability discovery for LLM integrations
• advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/QuestionAnswerAdvisor.java — Foundational advisor pattern for RAG (Retrieval-Augmented Generation) implementations using vector stores
• auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/NamedClientMcpTransport.java — Transport abstraction for MCP protocol enabling plugin architecture for different LLM provider integrations
• README.md — Project overview documenting Spring Boot version compatibility (Boot 4.x with AI 2.x) and core mission
• CONTRIBUTING.adoc — Contributor guidelines and Development Certificate of Origin requirements for all pull requests

Add a new MCP Server Integration

1. Create a new transport implementation in auto-configurations/mcp/ that extends McpTransport interface (auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/NamedClientMcpTransport.java)
2. Add auto-configuration class in the new module that registers the transport bean and binds properties (auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/StdioTransportAutoConfiguration.java)
3. Create application.properties documentation mapping the new transport's configuration options (.github/workflows/continuous-integration.yml)
4. Register the auto-configuration in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports (auto-configurations/common/spring-ai-autoconfigure-retry/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports)

Add a new Chat Client Advisor

1. Create advisor class extending ChatClientAdvisor in advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/ (advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/QuestionAnswerAdvisor.java)
2. Implement the advise() method to intercept and modify ChatClientRequestContext before LLM invocation (advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/VectorStoreChatMemoryAdvisor.java)
3. Add integration test in advisors/spring-ai-advisors-vector-store/src/test/ mocking external services (vector store, LLM) (advisors/spring-ai-advisors-vector-store/src/test/java/org/springframework/ai/chat/client/advisor/vectorstore/QuestionAnswerAdvisorTests.java)
4. Document the advisor in the main README.md with usage examples and configuration options (README.md)

Add a new Retry Strategy for LLM Calls

1. Create a RetryTemplate configuration in auto-configurations/common/spring-ai-autoconfigure-retry/ implementing Spring Retry interfaces (auto-configurations/common/spring-ai-autoconfigure-retry/src/main/java/org/springframework/ai/retry/autoconfigure/SpringAiRetryAutoConfiguration.java)
2. Add configuration properties for backoff policy (initial delay, multiplier, max attempts) in SpringAiRetryProperties (auto-configurations/common/spring-ai-autoconfigure-retry/src/main/java/org/springframework/ai/retry/autoconfigure/SpringAiRetryProperties.java)
3. Create integration test validating retry behavior on transient failures from mock LLM (auto-configurations/common/spring-ai-autoconfigure-retry/src/test/java/org/springframework/ai/retry/autoconfigure/SpringAiRetryAutoConfigurationIT.java)
4. Update pom.xml to add spring-retry and micrometer-core dependencies if needed (auto-configurations/common/spring-ai-autoconfigure-retry/pom.xml)

• Spring Boot 4.x — undefined

1. DCO enforcement: all commits require 'Signed-off-by' footer (git commit -s), enforced by dco.yml—PRs without it will fail. 2) Multi-branch strategy: main branch targets Spring Boot 4.x, but 1.1.x branch still maintained for Boot 3.5.x; check which branch when reporting issues. 3) Maven build cache in .mvn/maven-build-cache-config.xml may cause stale artifacts; clear with ./mvnw clean if tests fail unexpectedly. 4) Integration tests (mcp-integration-tests.yml) need live API credentials (OpenAI, Anthropic, etc.) via GitHub Secrets; local runs will skip if env vars absent.

• Retrieval-Augmented Generation (RAG) — Core use case for Spring AI—QuestionAnswerAdvisor and VectorStoreChatMemoryAdvisor implement RAG by injecting external knowledge into LLM prompts, enabling domain-specific AI without fine-tuning
• Chat Memory Advisor Pattern — Spring AI's extension mechanism for composing behaviors into ChatClient calls; VectorStoreChatMemoryAdvisor shows how advisors intercept and modify chat requests/responses
• Embedding Models — Essential for RAG: EmbeddingModel converts text into vectors for similarity search; QuestionAnswerAdvisor depends on embeddings to find relevant documents in vector stores
• Provider Abstraction / Strategy Pattern — ChatModel and EmbeddingModel interfaces abstract away provider details (OpenAI vs Anthropic vs local Ollama); Spring AI's core value is this portability
• Spring Boot AutoConfiguration — Each LLM provider module uses @EnableAutoConfiguration to inject beans conditionally based on classpath and properties; enables zero-config setup with spring.ai.*.api-key
• Vector Store Abstraction — VectorStore interface (implied in advisors module) decouples RAG from specific storage backends (Pinecone, Weaviate, PostgreSQL pgvector, etc.); enables switching without code changes
• Prompt Templates — Spring AI uses PromptTemplate for parameterized LLM inputs; QuestionAnswerAdvisor likely wraps user questions in prompt templates to include retrieved context

• langchain4j/langchain4j — Direct Java alternative to Spring AI; provides similar LLM abstractions but without Spring Boot integration, suitable for non-Spring JVM apps
• spring-projects/spring-boot — Core dependency and foundation; Spring AI is a Spring Boot starter library, so Boot's autoconfiguration and property binding patterns directly apply
• spring-projects/spring-data — Vector store integrations leverage Spring Data patterns (repositories, entity mappings); spring-ai-advisors uses vector store repos for RAG
• spring-projects/spring-ai-integration-tests — Separate repo containing live API integration tests against real LLM providers; runs via mcp-integration-tests.yml workflow in this repo
• langchain-ai/langchain — Python inspiration for Spring AI's design philosophy (advisors, retrievers, memory patterns borrowed from LangChain but adapted for Spring)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for VectorStoreChatMemoryAdvisor with multiple vector store implementations

The file advisors/spring-ai-advisors-vector-store/src/test/java/org/springframework/ai/chat/client/advisor/vectorstore/VectorStoreChatMemoryAdvisorTests.java exists but likely only tests basic scenarios. Spring AI supports multiple vector store backends (as evidenced by the module structure). Adding comprehensive integration tests for different vector store implementations (e.g., Chroma, Pinecone, Weaviate) would catch regressions and ensure compatibility across all supported backends.

• [ ] Review existing VectorStoreChatMemoryAdvisorTests.java to identify coverage gaps
• [ ] Check spring-ai-vector-stores/* modules to identify all supported implementations
• [ ] Create test classes for each vector store implementation (e.g., VectorStoreChatMemoryAdvisorChromaTests.java, VectorStoreChatMemoryAdvisorPineconeTests.java)
• [ ] Add parameterized tests using @ParameterizedTest to test advisor behavior across different vector store backends
• [ ] Ensure tests cover edge cases like memory eviction, embedding retrieval, and concurrent advisor access

Add GitHub Actions workflow for isolated advisor module testing

The .github/workflows directory has workflows for CI, but no dedicated workflow for testing just the advisors modules. Currently, advisor tests likely run as part of the full build in continuous-integration.yml. Creating a separate workflow would enable faster PR feedback for advisor-specific changes and catch regressions earlier without running the entire test suite.

• [ ] Create .github/workflows/advisors-tests.yml with Maven commands targeting only advisors/* modules
• [ ] Configure the workflow to run on PRs affecting files in advisors/ directory using path filters
• [ ] Add caching for Maven artifacts to speed up advisor-only test runs
• [ ] Configure the workflow to report results back to PRs with a clear status check label (e.g., 'advisors/tests')
• [ ] Document the new workflow in CONTRIBUTING.adoc

Implement advisor configuration validation and auto-configuration in spring-ai-autoconfigure-retry

The spring-ai-autoconfigure-retry module exists with SpringAiRetryAutoConfiguration.java and SpringAiRetryProperties.java, but there's no corresponding auto-configuration for the vector store advisors. Adding AutoConfiguration for QuestionAnswerAdvisor and VectorStoreChatMemoryAdvisor would allow Spring Boot users to configure advisors via application.properties/yaml without manual bean registration, improving developer experience and consistency with Spring Boot conventions.

• [ ] Create auto-configurations/common/spring-ai-autoconfigure-vector-store-advisors/ module parallel to spring-ai-autoconfigure-retry
• [ ] Add SpringAiVectorStoreAdvisorsAutoConfiguration.java with conditional bean registration based on classpath availability
• [ ] Create SpringAiVectorStoreAdvisorsProperties.java to support configuration keys like spring.ai.advisors.vector-store.enabled and spring.ai.advisors.question-answer.similarity-threshold
• [ ] Register the auto-configuration in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
• [ ] Add unit tests in auto-configurations/common/spring-ai-autoconfigure-vector-store-advisors/src/test/ verifying conditional bean creation and property binding

• Add missing unit tests for VectorStoreChatMemoryAdvisor error paths (null vector store, empty results); currently QuestionAnswerAdvisorTests.java exists but memory advisor test coverage is incomplete.
• Document the advisor plugin architecture with a code example in docs/: show how to create a custom Advisor extending AbstractChatMemoryAdvisor (file likely missing or buried in Javadoc).
• Add @ParameterizedTest cases to QuestionAnswerAdvisorTests for multiple LLM providers (OpenAI, Anthropic, etc.) rather than provider-agnostic tests, ensuring RAG works across integrations.

The Spring AI repository demonstrates reasonable security practices with parent POM inheritance and organized module structure. However, the analysis is hampered by a truncated/corrupted pom.xml file that prevents complete dependency verification. The primary concerns are: (1) incomplete POM configuration that needs immediate remediation, (2) use of snapshot versions unsuitable for production, (3) lack of visible security policy documentation, and (4) inability to fully assess transitive dependency risks due to the truncated configuration. The Java 17 target is reasonable for a modern framework. Immediate action required: fix the malformed pom.xml file and run comprehensive dependency vulnerability scanning.

• Medium · Incomplete POM.xml Dependency Declaration — advisors/spring-ai-advisors-vector-store/pom.xml. The pom.xml file appears to be truncated with an incomplete dependency declaration. The second dependency block has a malformed closing tag: <groupId>org.springframework.ai</groupI which is cut off. This could indicate a build configuration issue or file corruption that might lead to missing dependencies or unpredictable build behavior. Fix: Complete the truncated dependency declaration and ensure all dependencies are properly defined with complete, valid XML syntax. Validate the pom.xml file against Maven schema.
• Medium · Snapshot Version in Use — advisors/spring-ai-advisors-vector-store/pom.xml (parent version). The project uses version '2.0.0-SNAPSHOT' which indicates development/unreleased code. Snapshot versions can introduce instability and are not recommended for production deployments. This makes version pinning and reproducibility more difficult. Fix: Use stable, released versions in production environments. Document snapshot version usage and implement version management policies. Consider using a continuous integration system to pin dependency versions.
• Low · Java Compiler Target Version — advisors/spring-ai-advisors-vector-store/pom.xml (properties section). The project targets Java 17 (maven.compiler.target and source both set to 17). While Java 17 is a Long-Term Support (LTS) release, ensure all deployment environments support this version. Java versions beyond LTS should be carefully evaluated for production use. Fix: Document the minimum Java version requirement clearly. Ensure all CI/CD pipelines and production environments are configured with compatible Java versions.
• Low · Missing Dependency Version Management — advisors/spring-ai-advisors-vector-store/pom.xml (dependencies section). Dependencies reference parent version using ${project.parent.version} which is good practice, but the pom.xml truncation prevents full analysis of dependency management. Version alignment across the Spring AI module ecosystem should be strictly enforced. Fix: Ensure all internal dependencies use consistent versioning strategies. Implement a bill of materials (BOM) if not already present. Run regular dependency audits using tools like OWASP Dependency-Check.
• Low · No Visible Security Policy or SECURITY.md — Repository root (missing SECURITY.md). The repository structure shows standard GitHub templates (bug_report.md, feature_request.md) but no visible SECURITY.md file for security vulnerability reporting. This makes it unclear how security issues should be reported. Fix: Create a SECURITY.md file in the repository root with clear instructions for responsible vulnerability disclosure. Include security@springframework.org or appropriate contact information.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/spring-projects/spring-ai shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live spring-projects/spring-ai repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/spring-projects/spring-ai.

What it runs against: a local clone of spring-projects/spring-ai — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in spring-projects/spring-ai | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of spring-projects/spring-ai. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/spring-projects/spring-ai.git
#   cd spring-ai
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of spring-projects/spring-ai and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "spring-projects/spring-ai(\\.git)?\\b" \\
  && ok "origin remote is spring-projects/spring-ai" \\
  || miss "origin remote is not spring-projects/spring-ai (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "auto-configurations/common/spring-ai-autoconfigure-retry/src/main/java/org/springframework/ai/retry/autoconfigure/SpringAiRetryAutoConfiguration.java" \\
  && ok "auto-configurations/common/spring-ai-autoconfigure-retry/src/main/java/org/springframework/ai/retry/autoconfigure/SpringAiRetryAutoConfiguration.java" \\
  || miss "missing critical file: auto-configurations/common/spring-ai-autoconfigure-retry/src/main/java/org/springframework/ai/retry/autoconfigure/SpringAiRetryAutoConfiguration.java"
test -f "auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/McpClientAutoConfiguration.java" \\
  && ok "auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/McpClientAutoConfiguration.java" \\
  || miss "missing critical file: auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/McpClientAutoConfiguration.java"
test -f "advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/QuestionAnswerAdvisor.java" \\
  && ok "advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/QuestionAnswerAdvisor.java" \\
  || miss "missing critical file: advisors/spring-ai-advisors-vector-store/src/main/java/org/springframework/ai/chat/client/advisor/vectorstore/QuestionAnswerAdvisor.java"
test -f "auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/NamedClientMcpTransport.java" \\
  && ok "auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/NamedClientMcpTransport.java" \\
  || miss "missing critical file: auto-configurations/mcp/spring-ai-autoconfigure-mcp-client-common/src/main/java/org/springframework/ai/mcp/client/common/autoconfigure/NamedClientMcpTransport.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/spring-projects/spring-ai"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.