Skip to content

AI Fabric Framework 0.3.0

Choose a tag to compare

View all tags
@mahmoudashraf mahmoudashraf released this 27 Jun 13:14
ai-fabric-framework-v0.3.0
93d1cf4

AI Fabric 0.3.0 Release Notes

  • Released: 2026-06-27
  • Version: 0.3.0
  • Current branch reviewed: Spirng-AI-Integration
  • Compared against: origin/main at 1122bc6
  • Maven version: 0.3.0
  • Release scope: open-source Java framework only. Hosted Platform/Product control-plane workflows are not part of this framework release.

This release is a large framework hardening and enablement release. It moves commodity LLM and
embedding execution to Spring AI, keeps AI Fabric-owned orchestration, action safety, RAG policy,
provider fallback, transient input safety, and vector lifecycle/admin contracts, and adds much
stronger release verification around real apps, vector providers, and RealAPI provider lanes.

The branch diff is intentionally broad. The main external migration cost is provider dependency
replacement and runtime baseline alignment.

Highlights

  • Spring AI-backed cloud LLM and embedding execution. ai-fabric-provider-spring-ai now provides
    OpenAI, Azure OpenAI, Anthropic, and Gemini chat providers through Spring AI, plus OpenAI, Azure
    OpenAI, Gemini, and optional Spring AI ONNX embeddings.
  • Native cloud provider modules removed. The previous native OpenAI, Azure OpenAI, Anthropic,
    Gemini, and Cohere provider modules are removed from the reactor. Use the Spring AI provider for
    commodity model execution.
  • Native ONNX remains. ai-fabric-onnx-starter remains the local/offline embedding path and is
    separate from the optional spring-ai-onnx embedding provider.
  • Java and Spring baseline raised. The framework now targets Java 21, Spring Boot 4.1.x, and
    Spring AI 2.0.x.
  • Vector lifecycle/admin contract hardened. Vector providers now expose typed capabilities,
    readiness evidence, diagnostics, exact lifecycle methods, metadata-filter mode evidence, and
    shared contract tests across Docker-backed providers.
  • RAG and indexing now use selected Spring AI pieces. The framework adds Spring AI document
    ingestion helpers and opt-in Spring AI RAG evaluation helpers while keeping AI Fabric RAG policy
    and vector providers.
  • Actions are safer and more connected. Connector-backed actions, DB-backed action registry,
    Customer Connector API relay, retrieval connector, Spring AI tool callbacks, and MCP action bridge
    paths are hardened and tested.
  • Real app release proof expanded. The examples now prove product-shaped workflows for chat,
    action confirmation/interceptors, data sync, privacy deletion, RAG quality, behavior signals,
    relationship query, and migration/backfill.
  • CI is now release-oriented. New guard scripts reject skipped-test release examples, obvious
    production placeholder markers, vector documentation overclaims, and missing provider/vector
    readiness proof.

Breaking Changes And Compatibility Notes

1. Runtime Baseline

External applications should run on:

  • Java 21
  • Maven 3.9+
  • Spring Boot 4.1.x
  • Spring AI 2.0.x

If your application is still on an older Spring Boot line, plan the Spring/Spring Security/Jakarta
dependency upgrade before adopting this release.

2. Provider Module Replacement

Removed native provider modules:

  • ai-fabric-provider-openai
  • ai-fabric-provider-azure
  • ai-fabric-provider-anthropic
  • ai-fabric-provider-gemini
  • ai-fabric-provider-cohere

Use:

  • ai-fabric-provider-spring-ai for cloud LLMs and cloud embeddings
  • ai-fabric-onnx-starter for native local ONNX embeddings

Provider support in this release:

Provider id Chat Embeddings Implementation path Notes
openai Yes Yes Spring AI Default cloud LLM path when enabled and credentials are present.
azure Yes Yes Spring AI Azure OpenAI Requires endpoint and deployment names.
anthropic Yes No Spring AI Select another embedding provider.
gemini Yes Yes Spring AI Google GenAI Uses Gemini chat and text embedding models.
onnx No Yes AI Fabric native ONNX starter Local/offline embedding path.
spring-ai-onnx No Yes Spring AI Transformers Optional Spring AI ONNX embedding path.
cohere No No Not active Configuration shape remains modeled, but execution is not wired in this provider path.

Cohere configuration objects still exist in core provider configuration for compatibility of modeled
settings, but Cohere is not active in the Spring AI execution path in this release.

3. Spring AI Provider Behavior

AI Fabric now uses Spring AI for commodity provider calls, but AI Fabric still owns:

  • provider selection and fallback
  • orchestration and intent extraction
  • action authorization and confirmation
  • transient file input policy
  • RAG retrieval policy
  • response normalization
  • usage and safety metadata
  • vector lifecycle/admin behavior

SpringAiModelResolver caches Spring AI chat and embedding model clients by connection identity. It
also supports request-scoped endpoint/model overrides for trusted server-side callers.

4. Embedding Provider Defaults

The default embedding provider remains native onnx when no embedding provider is configured.

Supported embedding choices in this branch:

  • onnx: native AI Fabric ONNX provider from ai-fabric-onnx-starter
  • openai: Spring AI OpenAI embeddings
  • azure: Spring AI Azure OpenAI embeddings
  • gemini: Spring AI Gemini embeddings
  • spring-ai-onnx: optional Spring AI Transformers ONNX embeddings

Anthropic and Cohere embeddings are not available through this Spring AI provider path.

5. Cache Names Are Namespaced

Framework-owned Spring cache regions now use explicit AI Fabric names:

  • ai-fabric-embeddings
  • ai-fabric-vector-search
  • ai-fabric-text-search
  • ai-fabric-generation
  • ai-fabric-validation
  • ai-fabric-retention-status
  • ai-fabric-behavior-retention
  • ai-fabric-access-decisions

If an external application, metrics dashboard, cache manager, or Redis/Ehcache integration refers to
old generic names such as embeddings, vectorSearch, textSearch, aiGeneration,
aiValidation, retentionStatus, behaviorRetention, or accessDecisions, update those names.

The previous helper native cache beans named embeddingCache, searchCache, and generationCache
are no longer exposed as separate Spring beans by the default cache auto-configuration.

6. Vector Provider Semantics Are Stricter

Vector providers now advertise separate search/admin capabilities:

  • similarity-search metadata filtering
  • scan/admin metadata filtering
  • exact fetch by id
  • clear by entity type
  • efficient entity-type counts
  • hybrid/keyword support
  • durability and production-profile posture

Portable metadata filters are exact scalar filters over strings, booleans, and integer/long values.
Unsupported filter shapes fail closed instead of broadening results.

If you switch embedding dimensions, for example from OpenAI default dimensions to ONNX 384, rebuild
or clear existing Lucene indexes before running mixed provider tests or production traffic.

The in-memory vector provider is for demos/tests unless an operator explicitly acknowledges its use
under production profiles with ai.vector-db.memory.allow-in-production=true.

7. Data Sync And Runtime Auth Are More Explicit

ai-fabric-data-sync now has stricter request normalization and verified-auth handling. The new
property:

ai:
  data-sync:
    allow-trusted-platform-internal-sync-bypass: false

defaults to false. Enable it only behind a trusted backend/runtime boundary that injects verified
system auth context with the expected data-sync scope.

8. Confirmation Routing Is LLM-Structured, Not Backend Text Matching

Pending action confirmation now relies on LLM-produced structured intent or a dedicated
confirmation-resolution LLM prompt. The backend accepts only canonical confirmation decisions:

  • POSITIVE
  • NEGATIVE
  • UNKNOWN

Natural-language decision labels or synonyms in model output fail closed as UNKNOWN. If you
customized confirmation prompts, update them to output those exact enum values.

9. Relationship Query Is More Tolerant Of Real Model Output

Relationship query planning now tolerates null optional fields and unknown JSON properties from
provider output. Blank queries and execution failures return structured unsuccessful RAGResponse
results with error metadata instead of ambiguous failures.

10. Relay Packaging Is Now Runtime-Proved

ai-fabric-relay now builds as an executable Spring Boot jar, ships Docker improvements, and adds a
Helm chart under:

ai-infrastructure-module/ai-fabric-relay/deploy/helm/ai-fabric-relay

The packaged relay local smoke proves API-key rejection, action forwarding, idempotent replay,
idempotency conflict handling, retrieval forwarding, and documents-only retrieval enforcement.

New And Improved Areas

Spring AI Provider

  • New Spring AI provider module for cloud chat and embeddings.
  • Dynamic model resolver/cache for provider endpoint/model overrides.
  • Spring AI ChatClient execution path with ChatClientBuilderCustomizer support.
  • Redacted Spring AI observation diagnostics.
  • Request-scoped Spring AI advisors for trusted Java callers.
  • Guarded AI Fabric action tool callbacks exposed through Spring AI.
  • Spring AI MCP action bridge for connector-backed mcp-tool actions.

Core Orchestration And Provider Runtime

  • Shared structured JSON extraction is used by core intent parsing and Spring AI structured output
    support.
  • AICoreService now has stronger provider-purpose routing and content validation tests.
  • Provider availability checks and startup validation are more explicit.
  • Transient input policy remains an AI Fabric policy layer and is verified independently of Spring AI.
  • Confirmation routing now uses canonical structured decisions only.

Vector Providers

  • VectorDatabaseService exposes lifecycle/admin capabilities and diagnostics.
  • New vector readiness evaluator and health indicator.
  • Shared vector contract tests for memory, Lucene, Qdrant, Weaviate, Milvus, and provider-specific
    lifecycle behavior.
  • Lucene, Qdrant, Pinecone, Weaviate, Milvus, and memory providers have broader tests for metadata
    filtering, scan, update/delete, count, clear, exact fetch, diagnostics, and provider-specific edge
    behavior.
  • Pinecone has live integration test support.
  • Qdrant supports REST/gRPC contract coverage.

RAG And Indexing

  • RAG services have expanded tests around indexing content, source registry behavior, advanced
    search, query expansion, reranking, context optimization, and property-driven defaults.
  • Spring AI RAG evaluation helper maps AI Fabric RAGResponse documents into Spring AI evaluation
    requests while redacting unsafe metadata.
  • Indexing gains Spring AI document reader/chunker helpers for trusted ingestion sources.
  • Spring AI document indexing options bound chunk count, content length, metadata count, and metadata
    value length.

Actions, Connector, Registry, And Relay

  • Connector action execution has stricter response validation, bounded retry behavior, idempotency
    handling, HMAC/API-key support, and stable error codes.
  • File-based connector catalogs have stronger validation.
  • DB-backed action registry and Liquibase helper are tested.
  • AI Action registry merges annotation, file, and DB contributors into a unified action registry and
    rejects duplicate names.
  • Spring AI action tool callbacks preserve AI Fabric action authorization, hidden parameter, and
    confirmation boundaries.
  • Relay action and retrieval services validate upstream behavior more strictly.

Governance, PII, Data Sync, And Privacy

  • User data deletion now coordinates domain providers, behavior deletion, index catalog cleanup, and
    vector removal with structured partial-failure reporting.
  • Retention cleanup now reports disabled, skipped, completed, and partial outcomes with failure
    evidence.
  • PII detection has expanded property and service coverage.
  • Data Sync push API now proves vector-space listing, upsert, delete, batch size limits, verified
    auth context, and fail-closed authorization behavior.

Real Apps And Examples

The real apps now cover many release scenarios:

  • chat-capabilities-demo: local deterministic LLM for smoke profile, runtime vector search,
    conversation tests, action confirmation/interceptor coverage, and data-sync runtime proof.
  • ecommerce-store: data-sync client proof, admin reset, runtime request examples, and connector
    request examples.
  • smart-faq-assistant: seeded FAQ catalog, golden-answer quality service, RAG evidence checks.
  • privacy-first-customer-facing-support: PII masking, governance deletion, indexed residue proof.
  • it-support-action-bot: support/action authorization and confirmation smoke endpoints.
  • relationship-query-crm-insights: relationship-query scenario smoke coverage.
  • behavior-churn-signals: behavior signal scenario smoke coverage.
  • migration-enabled-product-catalog: migration/backfill smoke coverage.

CI And Release Verification

Automatic CI now covers:

  • release guard scripts
  • framework module tests and install
  • executable relay smoke
  • integration test compilation
  • minimal consumer compile
  • real-app build/install
  • offline real-app boot smoke
  • ecommerce to chat data-sync runtime smoke
  • deterministic P1 real-app scenario smoke
  • Docker-backed vector provider contract tests

Manual/keyed verification now has scorecard-producing RealAPI runners for:

  • core provider matrix
  • chat-session RealAPI
  • relationship-query RealAPI
  • behavior RealAPI
  • OpenAI/OpenAI/Lucene
  • OpenAI/ONNX/Lucene
  • ONNX fallback

External User Migration Plan

Use this checklist when upgrading an application from 0.2.1 to this release.

Step 1: Upgrade The Runtime Baseline

Verify:

  • Java 21 is used by local builds, CI, and deployment images.
  • Spring Boot dependency management is on 4.1.x.
  • Your application no longer pins older Spring Framework, Spring Security, Jackson, or Jakarta
    versions that conflict with Boot 4.1.x.
  • Maven is 3.9+.

Step 2: Update The AI Fabric BOM Version

Use the released AI Fabric BOM:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.github.loom-ai-labs</groupId>
      <artifactId>ai-fabric-bom</artifactId>
      <version>0.3.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Step 3: Replace Native Cloud Provider Dependencies

Remove any direct dependencies on these artifacts:

<artifactId>ai-fabric-provider-openai</artifactId>
<artifactId>ai-fabric-provider-azure</artifactId>
<artifactId>ai-fabric-provider-anthropic</artifactId>
<artifactId>ai-fabric-provider-gemini</artifactId>
<artifactId>ai-fabric-provider-cohere</artifactId>

Add:

<dependency>
  <groupId>io.github.loom-ai-labs</groupId>
  <artifactId>ai-fabric-provider-spring-ai</artifactId>
</dependency>

Keep native ONNX only when you want local/offline embeddings:

<dependency>
  <groupId>io.github.loom-ai-labs</groupId>
  <artifactId>ai-fabric-onnx-starter</artifactId>
</dependency>

Step 4: Recheck Provider Configuration

OpenAI example:

ai:
  providers:
    llm-provider: openai
    embedding-provider: openai
    openai:
      enabled: true
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com/v1
      model: gpt-4o-mini
      embedding-model: text-embedding-3-small

Azure OpenAI example:

ai:
  providers:
    llm-provider: azure
    embedding-provider: azure
    azure:
      enabled: true
      api-key: ${AZURE_OPENAI_API_KEY}
      endpoint: ${AZURE_OPENAI_ENDPOINT}
      deployment-name: ${AZURE_OPENAI_DEPLOYMENT_NAME}
      api-version: ${AZURE_OPENAI_API_VERSION:}
      embedding-deployment-name: ${AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME}

Gemini example:

ai:
  providers:
    llm-provider: gemini
    embedding-provider: gemini
    gemini:
      enabled: true
      api-key: ${GEMINI_API_KEY}
      model: gemini-2.5-flash
      embedding-model: text-embedding-004

Anthropic example:

ai:
  providers:
    llm-provider: anthropic
    anthropic:
      enabled: true
      api-key: ${ANTHROPIC_API_KEY}
      model: claude-3-7-sonnet-latest

Anthropic is chat-only in this provider path. Select another embedding provider.

Step 5: Decide Between Native ONNX And Spring AI ONNX

Native ONNX:

ai:
  providers:
    embedding-provider: onnx
    onnx:
      model-path: ${AI_FABRIC_ONNX_MODEL_PATH:./models/embeddings/all-MiniLM-L6-v2.onnx}
      tokenizer-path: ${AI_FABRIC_ONNX_TOKENIZER_PATH:./models/embeddings/tokenizer.json}
      max-sequence-length: 512

Spring AI ONNX:

ai:
  providers:
    embedding-provider: spring-ai-onnx
    spring-ai-onnx:
      model-uri: ${SPRING_AI_ONNX_MODEL_URI:}
      tokenizer-uri: ${SPRING_AI_ONNX_TOKENIZER_URI:}
      cache-enabled: true
      dimensions: 384

Both providers enforce nonblank input text and an 8000-character text limit at the provider
boundary.

Step 6: Rebuild Or Reindex Vector Stores When Dimensions Change

Check your embedding dimensions before reusing an existing vector index:

  • Native ONNX and Spring AI ONNX default to 384 dimensions.
  • OpenAI embedding dimensions depend on model and ai.providers.openai.embedding-dimensions.
  • Gemini defaults to 768 dimensions in the Spring AI provider resolver.

If the dimension changes, clear/rebuild the vector index or run a full migration/backfill. Do not
reuse an index built with a different embedding dimension.

Step 7: Review Vector Provider Settings

For Lucene:

ai:
  vector-db:
    type: lucene
    lucene:
      index-path: ./data/lucene-vector-index

For Qdrant:

ai:
  vector-db:
    type: qdrant
    operations:
      await-clear-consistency: true
      await-clear-timeout-ms: 30000
      fail-on-missing-payload-index: false
  providers:
    qdrant:
      host: ${AI_PROVIDERS_QDRANT_HOST}
      grpc-port: ${AI_PROVIDERS_QDRANT_GRPC_PORT:6334}
      api-key: ${AI_PROVIDERS_QDRANT_API_KEY:}

For memory in development or test:

ai:
  vector-db:
    type: memory

Use memory in production profiles only with an explicit operator acknowledgement:

ai:
  vector-db:
    memory:
      allow-in-production: true

Readiness and diagnostics are now part of the vector contract. If ai-fabric-web and actuator are
enabled, review:

  • /api/ai/advanced-rag/health for vector provider diagnostics under vectorDatabase
  • /actuator/health/vectorProvider for the Spring Boot health component

Release checks can also validate captured JSON with:

.github/scripts/verify-vector-readiness-health.sh <health-json-file-or-url>

Step 8: Update Cache Observability And External Cache Configuration

If you have cache metrics, cache dashboards, cache invalidation scripts, or external cache manager
configuration, migrate to the namespaced cache names listed above.

Step 9: Review Data Sync Auth

If you use ai-fabric-data-sync, confirm every Data Sync request includes:

  • vectorSpace
  • id
  • trace
  • verified auth context appropriate for your runtime boundary

Review the stricter normalization limits:

ai:
  data-sync:
    max-batch-size: 200
    max-content-chars: 8000
    max-field-value-chars: 2000
    max-metadata-keys: 75

Keep allow-trusted-platform-internal-sync-bypass=false unless your application sits behind a
trusted backend that verifies and injects the expected platform/system auth context. Verified
requests must carry data-sync:upsert or data-sync:delete for the requested operation.

Step 10: Review Action And Connector Configuration

If you use connector-backed actions, verify:

ai:
  actions:
    connector:
      base-url: https://connector.example
      execute-path: /actions/execute
      api-key:
        header: X-AIFABRIC-API-KEY
        value: ${AI_ACTIONS_CONNECTOR_API_KEY:}
      hmac:
        secret: ${AI_ACTIONS_CONNECTOR_HMAC_SECRET:}

If you use MCP-backed connector actions, configure the gateway or Spring AI MCP clients:

ai:
  actions:
    connector:
      mcp-gateway:
        base-url: https://mcp-gateway.internal
        execute-path: /api/internal/mcp/actions/execute
        api-key-header: X-MCP-GATEWAY-API-KEY
        api-key: ${AI_MCP_GATEWAY_API_KEY:}

Review file or DB action catalogs for:

  • unique action names
  • explicit accessMode; connector catalogs now fail startup if it is missing
  • confirmation requirements for mutating actions
  • hidden parameters supplied only by trusted server-side context
  • stable idempotency handling for non-read actions
  • readActionResolutionEligible only on READ actions; READ_WRITE and WRITE_ONLY actions are
    rejected for read-action planning

Annotated actions also require explicit accessMode and requiresConfirmation values. This keeps
action safety visible at the action boundary instead of inferred from names.

Step 11: Review Confirmation Prompt Customizations

If you override curated confirmation prompts, make sure the confirmation-resolution response is
valid JSON and uses only:

{
  "decision": "POSITIVE",
  "confidence": 1.0
}

Use NEGATIVE or UNKNOWN as appropriate. Other labels are not interpreted.

Step 12: Opt Into Optional Spring AI Helpers Deliberately

Request-scoped Spring AI advisors and AI Fabric action tool callbacks are Java-only trusted server
helpers. Do not accept advisor names, tool names, hidden action context, or transient file URLs from
browser/user JSON and convert them directly into Spring AI objects.

RAG evaluation helpers are off by default:

ai:
  infrastructure:
    rag:
      evaluation:
        enabled: false

Enable them only for tests, quality gates, or trusted operator paths.

Step 13: Review Web Controller Exposure

ai-fabric-web now has independent controller toggles. Review exposed endpoints before deploying:

ai:
  web:
    enabled: true
    base-path: /api/ai
    controllers:
      advanced-rag: true
      compliance: true
      migration: true
      profile: true
      security: true

Disable controllers your app does not expose publicly, and apply your application security policy at
the web boundary.

Step 14: Reverify Real Application Flows

Run at least:

mvn -B -V --no-transfer-progress -f ai-infrastructure-module/pom.xml install
mvn -B -V --no-transfer-progress -f examples/minimal-spring-boot/pom.xml compile
mvn -B -V --no-transfer-progress -f examples/real-apps/pom.xml install
.github/scripts/smoke-boot-realapps.sh
.github/scripts/smoke-ecommerce-chat-datasync.sh
.github/scripts/smoke-p1-realapp-scenarios.sh

For vector provider parity with Docker:

.github/scripts/run-vector-container-contracts.sh

For live provider evidence, run the RealAPI matrix with your own credentials:

cd ai-infrastructure-module/integration-Testing/integration-tests
bash ./run-provider-matrix-tests.sh "openai:openai:lucene" "" "all"
bash ./run-provider-matrix-tests.sh "openai:onnx:lucene" "" "all"

Verification Evidence From This Branch

The branch contains committed test and documentation evidence for:

  • P0 framework release gates in docs/planning/0006-framework-capability-priority-map.md
  • P1 relay, connector, action, real-app, runtime auth, governance, and smoke proof
  • P2 OpenAI/OpenAI/Lucene and OpenAI/ONNX/Lucene RealAPI proof
  • Docker vector provider contracts for Qdrant, Weaviate, and Milvus
  • Spring AI provider focused tests
  • chat-session, relationship-query, and behavior RealAPI scorecards

Not included in this framework release proof:

  • hosted Platform/Product admin UI regression
  • managed deployment template rollout
  • marketplace install workflows
  • live hosted control-plane provisioning for every external vector SaaS provider

Those are Platform/Product verification lanes, not Java framework release gates.

Known Limitations

  • Cohere chat/embedding execution is not active through this Spring AI provider path.
  • Anthropic embeddings are not supported by this provider path.
  • Existing vector indexes must be rebuilt when embedding dimensions change.
  • Spring AI RAG evaluation helpers are intended for tests and release gates, not untrusted end-user
    request paths.

Recommended Release Engineer Checklist

  1. Confirm all Maven modules and the release tag use 0.3.0.
  2. Re-run the automatic CI gate.
  3. Run Docker vector provider contracts.
  4. Run at least the OpenAI/OpenAI/Lucene and OpenAI/ONNX/Lucene RealAPI scorecard lanes.
  5. Verify Maven Central staging metadata after version bump.
  6. Verify README.md latest release link after publishing.
  7. Keep Platform/Product live admin regression tracked separately from this framework release.
Assets 2
Loading