tessl/maven-org-springframework-ai--spring-ai-commons
Common classes used across Spring AI providing document processing, text transformation, embedding utilities, observability support, and tokenization capabilities for AI application development
index.mddocs/
Spring AI Commons
Spring AI Commons provides foundational abstractions for AI application development in Spring, including document processing, text transformation, embedding utilities, observability, and tokenization.
Quick Start
Installation
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-commons</artifactId>
<version>1.1.2</version>
</dependency>Requirements: Java 17+
Basic Example
import org.springframework.ai.document.Document;
import org.springframework.ai.transformer.splitter.TokenTextSplitter;
import org.springframework.ai.reader.TextReader;
import org.springframework.core.io.ClassPathResource;
// Read and process documents
TextReader reader = new TextReader(new ClassPathResource("data.txt"));
List<Document> documents = reader.get();
// Split into chunks for embedding
TokenTextSplitter splitter = TokenTextSplitter.builder()
.withChunkSize(800)
.build();
List<Document> chunks = splitter.apply(documents);Core Components
Document Model
Core abstractions for text and media content with metadata.
Key Classes: Document, Media, Content, MetadataMode
Document Processing
ETL interfaces for reading, writing, and transforming documents.
Key Interfaces: DocumentReader, DocumentWriter, DocumentTransformer
Text Splitting
Split documents into chunks optimized for embeddings and AI processing.
Key Classes: TokenTextSplitter, TextSplitter
Content Formatting
Convert documents to AI-friendly text with configurable metadata.
Key Classes: ContentFormatter, DefaultContentFormatter
Readers & Writers
I/O operations for loading and saving documents.
Key Classes: JsonReader, TextReader, FileDocumentWriter
Embedding Optimization
Batching strategies for efficient embedding API calls.
Key Classes: TokenCountBatchingStrategy, BatchingStrategy
Tokenization
Token counting and estimation for AI models.
Key Classes: JTokkitTokenCountEstimator, TokenCountEstimator
Evaluation
Framework for evaluating AI response quality.
Key Classes: Evaluator, EvaluationRequest, EvaluationResponse
Observability
Metrics and tracing with OpenTelemetry integration.
Key Classes: AiOperationMetadata, TracingAwareLoggingObservationHandler
Utilities
Helper classes for JSON, parsing, resources, and logging.
Key Classes: JacksonUtils, ParsingUtils, ResourceUtils, LoggingMarkers
Quick Reference
Common Imports
// Document model
import org.springframework.ai.document.Document;
import org.springframework.ai.document.DocumentReader;
import org.springframework.ai.document.DocumentWriter;
import org.springframework.ai.document.DocumentTransformer;
import org.springframework.ai.document.MetadataMode;
// Media support
import org.springframework.ai.content.Media;
import org.springframework.ai.content.MediaContent;
// Text processing
import org.springframework.ai.transformer.splitter.TokenTextSplitter;
import org.springframework.ai.reader.JsonReader;
import org.springframework.ai.reader.TextReader;
// Embedding and tokenization
import org.springframework.ai.embedding.TokenCountBatchingStrategy;
import org.springframework.ai.tokenizer.JTokkitTokenCountEstimator;
// Evaluation
import org.springframework.ai.evaluation.Evaluator;
import org.springframework.ai.evaluation.EvaluationRequest;
import org.springframework.ai.evaluation.EvaluationResponse;Common Patterns
| Task | Component | Example |
|---|---|---|
| Read text file | TextReader | new TextReader(resource).get() |
| Read JSON | JsonReader | new JsonReader(resource).get() |
| Create document | Document.Builder | Document.builder().text("...").build() |
| Split text | TokenTextSplitter | splitter.apply(documents) |
| Count tokens | JTokkitTokenCountEstimator | estimator.estimate(text) |
| Batch for embedding | TokenCountBatchingStrategy | strategy.batch(documents) |
| Format content | Document | doc.getFormattedContent(MetadataMode.EMBED) |
| Evaluate response | Evaluator | evaluator.evaluate(request) |
Architecture
┌─────────────────────────────────────────────────┐
│ Content Layer │
│ (Document, Media, Content, MediaContent) │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Processing Layer │
│ (DocumentReader, DocumentWriter, Transformer) │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Transformation Layer │
│ (TextSplitter, ContentFormatter, Batching) │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Integration Layer │
│ (Readers, Writers, Tokenization, Evaluation) │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Observability Layer │
│ (Metrics, Tracing, Monitoring) │
└─────────────────────────────────────────────────┘Resources
Guides
- Quick Start Guide - Get started with Spring AI Commons
- RAG Pipeline Guide - Build retrieval-augmented generation
- Error Handling Guide - Handle errors and edge cases
Examples
- Real-World Scenarios - Common use cases and patterns
- Edge Cases - Advanced scenarios and error handling
API Reference
- Document Model - Document, Media, Content APIs
- Document Processing - Reader, Writer, Transformer APIs
- Content Formatting - Formatting APIs
- Text Splitting - Splitting APIs
- Readers & Writers - I/O APIs
- Embedding - Batching APIs
- Tokenization - Token counting APIs
- Evaluation - Evaluation APIs
- Observability - Metrics and tracing APIs
- Utilities - Helper utilities
Package Information
- Group ID: org.springframework.ai
- Artifact ID: spring-ai-commons
- Version: 1.1.2
- Package Type: Maven
- Language: Java
- License: Apache License 2.0
Install with Tessl CLI
npx tessl i tessl/maven-org-springframework-ai--spring-ai-commons@1.1.0