diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc index ae095035d..adf19c343 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc @@ -41,5 +41,6 @@ *** xref:api/vectordbs/pinecone.adoc[] ** xref:api/etl-pipeline.adoc[] ** xref:api/testing.adoc[] +** xref:api/generic-model.adoc[] * Appendices ** xref:upgrade-notes.adoc[]] diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc index d2d65ddc0..f99403ce9 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc @@ -11,10 +11,6 @@ This design aligns with Spring's philosophy of modularity and interchangeability Also with the help of companion classes like `Prompt` for input encapsulation and `ChatResponse` for output handling, the Chat Completion API unifies the communication with AI Models. It manages the complexity of request preparation and response parsing, offering a direct and simplified API interaction. -The Spring AI Chat Completion API is build on top of the Spring AI `Generic Model API` providing Chat specific abstractions and implementations. Following class diagram illustrates the main classes and interfaces of the Spring AI Chat Completion API. - -image::spring-ai-chat-api.jpg[align="center", width="900px"] - == API Overview This section provides a guide to the Spring AI Chat Completion API interface and associated classes. @@ -190,6 +186,12 @@ image::spring-ai-chat-completions-clients.jpg[align="center", width="800px"] ** xref:api/clients/bedrock/bedrock-titan.adoc[Titan Chat Completion] ** xref:api/clients/bedrock/bedrock-anthropic.adoc[Anthropic Chat Completion] +== Chat Model API + +The Spring AI Chat Completion API is build on top of the Spring AI `Generic Model API` providing Chat specific abstractions and implementations. Following class diagram illustrates the main classes and interfaces of the Spring AI Chat Completion API. + +image::spring-ai-chat-api.jpg[align="center", width="900px"] + // == Best Practices // // TBD diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc index 0f7309680..aed9a6938 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc @@ -6,7 +6,6 @@ The ETL pipeline orchestrates the flow from raw data sources to a structured vec The RAG use case is text to augment the capabilities of generative models by retrieving relevant information from a body of data to enhance the quality and relevance of the generated output. - == API Overview === DocumentReader @@ -18,49 +17,151 @@ public interface DocumentReader extends Supplier> { } ``` -==== Available Implementations +==== JsonReader +The `JsonReader` Parses documents in JSON format. -*JsonReader*:: -+ Parses documents in JSON format. +Example: -*TextReader*:: -+ Processes plain text documents. +[source,java] +---- +@Component +public class MyAiApp { -*PagePdfDocumentReader*:: -+ Uses Apache PdfBox library to parse PDF documents + @Value("classpath:bikes.json") // This is the json document to load + private Resource resource; -*ParagraphPdfDocumentReader*:: -+ Uses the PDF catalog (e.g. TOC) information to split the input PDF into text paragraphs and output a single `Document` per paragraph. + List loadJsonAsDocuments() { + JsonReader jsonReader = new JsonReader(resource, "description"); + return jsonReader.get(); + } +} +---- -*TikaDocumentReader*:: -+ Uses Apache Tika to extract text from a variety of document formats, such as PDF, DOC/DOCX, PPT/PPTX, and HTML. For a comprehensive list of supported formats, refer to the https://tika.apache.org/2.9.0/formats.html[Tika documentation]. +==== TextReader +The `TextReader` processes plain text documents. + +Example: + +[source,java] +---- +@Component +public class MyTextReader { + + @Value("classpath:text-source.txt") // This is the text document to load + private Resource resource; + + List loadText() { + TextReader textReader = new TextReader(resource); + textReader.getCustomMetadata().put("filename", "text-source.txt"); + + return textReader.get(); + } +} +---- + +==== PagePdfDocumentReader +The `PagePdfDocumentReader` uses Apache PdfBox library to parse PDF documents + +Example: + +[source,java] +---- +@Component +public class MyPagePdfDocumentReader { + + List getDocsFromPdf() { + + PagePdfDocumentReader pdfReader = new PagePdfDocumentReader("classpath:/sample1.pdf", + PdfDocumentReaderConfig.builder() + .withPageTopMargin(0) + .withPageExtractedTextFormatter(ExtractedTextFormatter.builder() + .withNumberOfTopTextLinesToDelete(0) + .build()) + .withPagesPerDocument(1) + .build()); + + return pdfReader.get(); + } + +} + +---- + + +==== ParagraphPdfDocumentReader +The `ParagraphPdfDocumentReader` uses the PDF catalog (e.g. TOC) information to split the input PDF into text paragraphs and output a single `Document` per paragraph. +NOTE: Not all PDF documents contain the PDF catalog. + +Example: + +[source,java] +---- +@Component +public class MyPagePdfDocumentReader { + + List getDocsFromPdfwithCatalog() { + + new ParagraphPdfDocumentReader("classpath:/sample1.pdf", + PdfDocumentReaderConfig.builder() + .withPageTopMargin(0) + .withPageExtractedTextFormatter(ExtractedTextFormatter.builder() + .withNumberOfTopTextLinesToDelete(0) + .build()) + .withPagesPerDocument(1) + .build()); + + return pdfReader.get(); + } +} +---- + + +==== TikaDocumentReader +The `TikaDocumentReader` uses Apache Tika to extract text from a variety of document formats, such as PDF, DOC/DOCX, PPT/PPTX, and HTML. For a comprehensive list of supported formats, refer to the https://tika.apache.org/2.9.0/formats.html[Tika documentation]. + +Example: + +[source,java] +---- +@Component +public class MyTikaDocumentReader { + + @Value("classpath:/word-sample.docx") // This is the word document to load + private Resource resource; + + List loadText() { + TikaDocumentReader tikaDocumentReader = new TikaDocumentReader(resourceUri); + return tikaDocumentReader.get(); + } +} +---- === DocumentTransformer Transforms a batch of documents as part of the processing workflow. -```java +[source,java] +---- public interface DocumentTransformer extends Function, List> { } -``` +---- -==== Available Implementations +==== TextSplitter +The `TextSplitter` an abstract base class that helps divides documents to fit the AI model's context window. -*TextSplitter*:: -+ Divides documents to fit the AI model's context window. -*TokenTextSplitter*:: -+ Splits documents while preserving token-level integrity. +==== TokenTextSplitter +Splits documents while preserving token-level integrity. -*ContentFormatTransformer*:: -+ Ensures uniform content formats across all documents. +==== ContentFormatTransformer*:: +Ensures uniform content formats across all documents. -*KeywordMetadataEnricher*:: -+ Augments documents with essential keyword metadata. +==== KeywordMetadataEnricher*:: +Augments documents with essential keyword metadata. -*SummaryMetadataEnricher*:: -+ Enriches documents with summarization metadata for enhanced retrieval. +==== SummaryMetadataEnricher*:: +Enriches documents with summarization metadata for enhanced retrieval. === DocumentWriter @@ -77,57 +178,3 @@ public interface DocumentWriter extends Consumer> { There is an implementation for each of the Vector Stores that Spring AI supports, e.g. `PineconeVectorStore`. See xref:api/vectordbs.adoc[Vector DB Documentation] for a full listing. - - -== Using PagePdfDocumentReader - -[source,java] ----- -PagePdfDocumentReader pdfReader = new PagePdfDocumentReader( - "file:document-readers/pdf-reader/src/test/resources/sample.pdf", - PdfDocumentReaderConfig.builder() - .withPageTopMargin(0) - .withPageBottomMargin(0) - .withPageExtractedTextFormatter(PageExtractedTextFormatter.builder() - .withNumberOfTopTextLinesToDelete(0) - .withNumberOfBottomTextLinesToDelete(3) - .withNumberOfTopPagesToSkipBeforeDelete(0) - .build()) - .withPagesPerDocument(1) - .build()); - -var documents = pdfReader.get(); - -PdfTestUtils.writeToFile("document-readers/pdf-reader/target/sample.txt", documents, false); ----- - -[source,java] ----- -public static void main(String[] args) throws IOException { - - ParagraphPdfDocumentReader pdfReader = new ParagraphPdfDocumentReader( - "file:document-readers/pdf-reader/src/test/resources/sample2.pdf", - PdfDocumentReaderConfig.builder() - // .withPageBottomMargin(15) - // .withReversedParagraphPosition(true) - // .withTextLeftAlignment(true) - .build()); - // ParagraphPdfDocumentReader pdfReader = new ParagraphPdfDocumentReader( - // "file:document-readers/pdf-reader/src/test/resources/spring-framework.pdf", - // PdfDocumentReaderConfig.builder() - // .withPageBottomMargin(15) - // .withReversedParagraphPosition(true) - // // .withTextLeftAlignment(true) - // .build()); - - // PdfDocumentReader pdfReader = new - // PdfDocumentReader("file:document-readers/pdf-reader/src/test/resources/uber-k-10.pdf", - // PdfDocumentReaderConfig.builder().withPageTopMargin(80).withPageBottomMargin(60).build()); - - var documents = pdfReader.get(); - - writeToFile("document-readers/pdf-reader/target/sample2.txt", documents, true); - System.out.println(documents.size()); - -} ----- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc new file mode 100644 index 000000000..6776c0fad --- /dev/null +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc @@ -0,0 +1,23 @@ +[[generic-model-api]] += Generic Model API + +In order to provide a foundation for all AI Model clients, the Generic Model API was created. +This makes it easy to contribute new AI Model support to Spring AI by following a common pattern. +The following sections walk through this API and how it works. + + +== Class Diagram + +image::spring-ai-generic-model-api.jpg[width=900, align="center"] + +== ModelClient + +== StreamingModelClient + +== ModelRequest + +== ModelOptions + +== ModelResponse + +== ModelResult diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc index 8071d7a80..62d81b566 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc @@ -2,15 +2,15 @@ == Introduction -The following sections introduce each part of the API. +The Spring AI API covers a wide range of functionalities. +Each major feature is detailed in its own dedicated section. +To provide an overview, the following key functionalities are available: -The <> can help you understand the basic constructs used implementing all the other APIs. - -== APIs -* xref:api/embeddings.adoc[Embeddings API] -* xref:api/chatclient.adoc[Chat Completion API] -* xref:api/vectordbs.adoc[Vector Database API] -* xref:api/[Image Generation API](WIP) +* Portable API across AI providers for Chat and for Embedding models. Both synchronous and stream API options are supported. Dropping down to access model specific features is also supported. +* Portable API across Vector Store providers, including a novel SQL-like metadata filter API that is also portable. +* Spring Boot Auto Configuration and Starters for AI Models and Vector Stores. +* OpenAI Function calling +* ETL framework for Data Engineering == API Docs @@ -20,20 +20,3 @@ You can find the Javadoc https://docs.spring.io/spring-ai/docs/current-SNAPSHOT/ The project's https://github.com/spring-projects/spring-ai/discussions[GitHub discussions] is a great place to send feedback. -== Spring AI Generic Model API [[generic-model-api]] - -image::spring-ai-generic-model-api.jpg[width=900, align="center"] - -=== ModelClient - -=== StreamingModelClient - -=== ModelRequest - -=== ModelOptions - -=== ModelResponse - -=== ModelResult - - diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc index cf63611a8..904b99e70 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc @@ -8,15 +8,23 @@ The project was founded with the belief that the next wave of Generative AI appl At its core, Spring AI provides abstractions that serve as the foundation for developing AI applications. These abstractions have multiple implementations, enabling easy component swapping with minimal code changes. -For example, Spring AI introduces the `ChatClient`/`StreamingChatClient` interfaces with implementations for OpenAI and Azure OpenAI, Ollama, VertexAI, Huggingface, Bedrock/Llama2, Bedrock/Anthropic, Bedrock/Titan, Bedrock/Cohere etc. -Similarly abstractions, such as `EmbeddingClient`, `ImageClient` and various model implementations for them are provided. -In addition to these core abstractions, Spring AI aims to provide higher-level functionalities to address common use cases such as "`Q&A over your documentation`" or "`Chat with your documentation.`" -As the complexity of the use cases increases, the Spring AI project will integrate with other projects in the Spring Ecosystem, such as Spring Integration, Spring Batch, and Spring Data, Spring Cloud GCP, Spring Cloud, etc. +Spring AI provides the following features: -To simplify setup, Spring Boot starters are available to help set up essential dependencies and classes. -There is also a collection of sample applications to help you explore the project's features. Lastly, the new Spring CLI project also enables you to get started quickly by using the `spring boot new ai` command for new projects or `spring boot add ai` for adding AI capabilities to your existing application. +* Support for all major Model providers such as OpenAI, Microsoft, Amazon, Google, and Huggingface. +* Supported Model types are Chat and Text to Image with more on the way. +* Portable API across AI providers for Chat and for Embedding models. Both synchronous and stream API options are supported. Dropping down to access model specific features is also supported. +* Mapping of AI Model output to POJOs. +* Support for all major Vector Database providers such as Azure Vector Search, Chroma, Milvus, Neo4j, PostgreSQL/PGVector, PineCone, Redis, and Weaviate +* Portable API across Vector Store providers, including a novel SQL-like metadata filter API that is also portable. +* Function calling +* Spring Boot Auto Configuration and Starters for AI Models and Vector Stores. +* ETL framework for Data Engineering + +This feature set lets you implement common use cases such as "`Q&A over your documentation`" or "`Chat with your documentation.`" + + +The xref:concepts.adoc[concepts section] provides a high-level overview of AI concepts and their representation in Spring AI. -The xref:concepts.adoc[next section] provides a high-level overview of AI concepts and their representation in Spring AI. The xref:getting-started.adoc[Getting Started] section shows you how to create your first AI application. Subsequent sections delve into each component and common use cases with a code-focused approach.