/ README.md
README.md
1 # DriftKit Framework 2 3 **Production-ready AI framework for Java** - Complete prompt lifecycle management from development to production 4 5 ## 🚀 Why choose DriftKit? 6 7 ### Framework comparison 8 9 | Feature | DriftKit | Spring AI | LangChain4j | [Google ADK](https://github.com/google/adk-java) | 10 |---------|----------------------------------------------------------------------------------|---------------------------------|---------------------------------|-------------------------------------------------| 11 | **Text embedding** | ✅ Multiple providers | ✅ Multiple providers | ✅ Multiple providers | ❌ | 12 | **Vector storage** | ✅ In-memory, File, Pinecone, Spring AI (all providers) | ✅ In-memory, Chroma, PGVector etc | ✅ In-memory, Pinecone, Chroma etc | ❌ | 13 | **Structured output** | ✅ Java Pojo/Json based | ✅ | ✅ | ✅ | 14 | **Tool calling** | ✅ Type-safe with auto/manual-execution: function calling, tools, agents as tools | ✅ | ✅ | ✅ | 15 | **Prompt lifecycle management** | ✅ Dev→Test→Prod + Tracing | ❌ | ❌ | ❌ | 16 | **Visual prompt IDE** | ✅ Full web platform | ❌ Code only | ❌ Code only | ❌ | 17 | **Production prompt testing** | ✅ Test sets + evaluation | ❌ | ❌ | ❌ | 18 | **Prompt versioning** | ✅ Built-in | ❌ Manual | ❌ Manual | ❌ | 19 | **A/B testing** | ✅ Native | ❌ | ❌ | ❌ | 20 | **Test automation** | ✅ Comprehensive | ❌ | ⚠️ Basic | ❌ | 21 | **Multi-agent patterns** | ✅ Loop, Sequential, Hierarchical, Graph, Cross-graph calls | ❌ | ⚠️ Limited | ✅ Built-in | 22 | **Workflow as graph** | ✅ Full graph with cross-workflow calls | ❌ | ⚠️ Chain only | ⚠️ Basic | 23 | **Simplified LLM SDK** | ✅ High-level Agent API | ⚠️ Low-level | ⚠️ Complex | ✅ Good | 24 | **Model hot-swap** | ✅ Config change only | ✅ Config change | ❌ Code rewrite | ⚠️ Limited | 25 | **Audio processing** | ✅ VAD + Transcription | ❌ | ❌ | ❌ | 26 | **Text-to-speech** | ❌ Not supported | ✅ Multiple providers | ❌ | ❌ | 27 | **Spring AI integration** | ✅ Full bidirectional integration | Native | ❌ | ❌ | 28 29 ### 🎯 Unique features 30 31 1. **Complete prompt lifecycle platform** - The ONLY framework with full Dev→Test→Prod workflow 32  33 - Version control and A/B testing 34 - Test sets with multiple evaluation methods 35 - Production tracing and monitoring 36 - Real-world scenario testing 37 38 2. **Enterprise prompt management** - What competitors lack: 39  40 - Automated prompt testing against production data 41 - Multiple evaluation strategies 42 - Performance tracking and optimization 43 - No other Java framework offers this! 44 45 3. **Workflow as maintainable graph** - Build complex agents with cross-workflow composition 46 4. **Simplified LLM SDK** - High-level Agent API for quick prototyping and production 47 5. **Hot-swap AI models** - Change models via config without code changes or recompilation 48 6. **Type-safe AI integration** - Direct Java objects, no JSON parsing needed 49 7. **Multi-agent orchestration** - Loop, Sequential, and Hierarchical patterns 50 8. **Built-in audio processing** - VAD, transcription, and streaming capabilities 51 9. **Spring AI integration** - Use DriftKit prompts with Spring AI ChatClient, full tracing support 52 53 ## 🏆 Business solutions 54 55 ### Customer support automation 56 **Problem:** Support teams overwhelmed with repetitive inquiries, inconsistent responses, high costs 57 **Solution:** DriftKit automates 80% of common requests while maintaining brand voice 58 59 **Technical Implementation:** 60 - **driftkit-context-engineering**: Create and A/B test response templates for different customer scenarios 61 - **driftkit-workflow-engine-core**: Intelligent routing - simple questions to AI, complex issues to specialists 62 - **driftkit-vector**: Knowledge base search for accurate, up-to-date information 63 - **driftkit-clients**: Multi-model support (GPT-4/Gemini 2.5 Pro/Claude Opus 4 for complex, GPT-4o-mini/Gemini 2.5 Flash/Claude Haiku for simple queries) 64 - **driftkit-common**: Conversation memory to maintain context across multiple interactions 65 66 **Business Impact:** 60% reduction in response time, 40% cost savings, 95% customer satisfaction 67 68 ### Financial document processing 69 **Problem:** Manual processing of contracts, invoices, compliance documents - slow, error-prone, expensive 70 **Solution:** Intelligent document analysis with 99%+ accuracy and structured data extraction 71 72 **Technical Implementation:** 73 - **driftkit-clients**: Multi-modal AI (GPT-4 Vision/Gemini 2.5/Claude with vision) for processing PDFs, images, scanned documents 74 - **driftkit-embedding**: Document similarity for duplicate detection and categorization 75 - **driftkit-vector**: Store processed documents for quick retrieval and compliance auditing 76 - **driftkit-workflow-engine-core**: Multi-step validation workflows with human-in-the-loop for critical decisions 77 - **driftkit-common**: Structured output extraction directly into your ERP/accounting systems 78 79 **Business Impact:** 90% faster processing, 95% error reduction, full compliance automation 80 81 ### E-commerce personalization engine 82 **Problem:** Generic product recommendations, poor conversion rates, high customer acquisition costs 83 **Solution:** AI-powered product matching and hyper-personalized customer journeys 84 85 **Technical Implementation:** 86 - **driftkit-vector**: Product catalog embeddings for intelligent similarity matching 87 - **driftkit-embedding**: Customer behavior analysis and preference modeling 88 - **driftkit-context-engineering**: Dynamic product description templates for different customer segments 89 - **driftkit-workflow-engine-core**: Real-time recommendation pipelines with A/B testing 90 - **driftkit-clients**: Multi-model optimization (fast models like GPT-4o-mini/Gemini Flash/Claude Haiku for real-time, advanced models like GPT-4/Gemini Pro/Claude Opus for deep analysis) 91 92 **Business Impact:** 35% increase in conversion rates, 50% higher average order value, 60% improved customer lifetime value 93 94 ### Content marketing at scale 95 **Problem:** Consistent content creation across multiple channels, languages, and brand voices 96 **Solution:** Automated content generation maintaining brand consistency across all touchpoints 97 98 **Technical Implementation:** 99 - **driftkit-context-engineering**: Brand voice templates with automated testing against brand guidelines 100 - **driftkit-workflow-engine-agents**: Multi-stage content pipelines using SequentialAgent pattern 101 - **driftkit-vector**: Content similarity checking to avoid duplication across channels 102 - **driftkit-embedding**: SEO keyword optimization and content clustering 103 - **driftkit-clients**: Model selection by content type (creative writing with GPT-4/Claude vs technical documentation with Gemini) 104 105 **Business Impact:** 10x content output, 80% cost reduction, consistent brand messaging across 50+ channels 106 107 ### HR and recruitment automation 108 **Problem:** Resume screening bottlenecks, unconscious bias, poor candidate experience 109 **Solution:** Intelligent candidate matching with bias reduction and automated communications 110 111 **Technical Implementation:** 112 - **driftkit-common**: Resume parsing and structured data extraction (skills, experience, education) 113 - **driftkit-embedding**: Candidate-job matching based on semantic understanding, not just keywords 114 - **driftkit-vector**: Talent pool management and similar candidate discovery 115 - **driftkit-workflow-engine-core**: Interview scheduling, personalized communications, feedback collection 116 - **driftkit-context-engineering**: Personalized outreach templates optimized for response rates 117 118 **Business Impact:** 70% faster hiring process, 40% improvement in hire quality, 90% candidate satisfaction 119 120 ### Intelligent banking assistant 121 **Problem:** Banking customers need 24/7 support for complex transactions, account management, and financial advice - but current chatbots are limited to simple FAQ responses 122 **Solution:** Multi-step conversational AI that handles everything from balance inquiries to loan applications with seamless human handoff 123 124 **Technical Implementation:** 125 - **driftkit-workflow-engine**: Advanced conversational workflows with automatic message tracking and human-in-the-loop support 126 - **driftkit-clients**: Dynamic model selection (GPT-4/Claude Opus for financial advice, GPT-4o-mini/Claude Haiku for simple queries) with structured outputs for transaction data 127 - **driftkit-workflow-engine-agents**: Multi-agent orchestration for complex financial analysis - LoopAgent for iterative refinement of investment advice 128 - **driftkit-vector**: Knowledge base for financial products, regulations, and personalized investment recommendations 129 - **driftkit-context-engineering**: Compliance-tested prompt templates for different financial scenarios with A/B testing for conversion optimization 130 - **driftkit-common**: Persistent session management with encrypted conversation history and document processing for uploaded statements 131 - **Database Integration**: Direct connections to core banking systems, CRM, and fraud detection APIs 132 - **Legacy System Integration**: REST/SOAP connectors to existing banking infrastructure with real-time transaction processing 133 134 **Conversation Flow Examples:** 135 - **Simple**: "What's my balance?" → Direct database query → Formatted response (2 seconds) 136 - **Complex**: "Help me apply for a mortgage" → Identity verification → Document collection → Credit check → Pre-approval calculation → Loan officer scheduling (15-minute guided process) 137 - **Emergency**: "My card was stolen" → Fraud detection → Card blocking → Replacement ordering → Temporary credit setup → Follow-up scheduling 138 139 **Business Impact:** 85% reduction in call center volume, 60% faster loan processing, 24/7 availability, 40% increase in product cross-sell, 95% customer satisfaction for complex transactions 140 141 ## 🧩 Framework modules 142 143 | Module | Purpose | Key Features | 144 |--------|---------|--------------| 145 | [**driftkit-common**](driftkit-common/README.md) | Core utilities | Chat memory, document processing, templates | 146 | [**driftkit-clients**](driftkit-clients/README.md) | AI providers | OpenAI, Gemini, Claude, O3-Mini, Spring AI supported models, type-safe responses | 147 | [**driftkit-embedding**](driftkit-embedding/README.md) | Text embeddings | OpenAI, Cohere, Spring AI providers, local BERT models | 148 | [**driftkit-vector**](driftkit-vector/README.md) | Vector search | In-memory, file-based, Pinecone, Spring AI | 149 | [**driftkit-workflows**](driftkit-workflows/README.md) | AI Orchestration | Workflow engine, testing framework, multi-agent patterns, Spring Boot integration | 150 | [**driftkit-context-engineering**](driftkit-context-engineering/README.md) | Prompt management | Web UI, versioning, A/B testing, Spring AI integration | 151 | [**driftkit-audio**](driftkit-audio/README.md) | Audio processing | VAD, transcription, streaming | 152 153 ## 📦 Module structure 154 155 ``` 156 driftkit-framework/ 157 ├── driftkit-common/ # 🔧 Core utilities and shared domain objects 158 ├── driftkit-clients/ # 🤖 AI model client abstractions and implementations 159 │ ├── driftkit-clients-core/ # Core client interfaces 160 │ ├── driftkit-clients-openai/ # OpenAI implementation 161 │ ├── driftkit-clients-gemini/ # Google Gemini implementation 162 │ ├── driftkit-clients-claude/ # Anthropic Claude implementation 163 │ ├── driftkit-clients-spring-ai/ # Spring AI models integration 164 │ └── driftkit-clients-spring-boot-starter/ 165 ├── driftkit-embedding/ # 🧠 Text embedding services 166 │ ├── driftkit-embedding-core/ # Core embedding interfaces 167 │ ├── driftkit-embedding-spring-ai/ # Spring AI providers integration 168 │ └── driftkit-embedding-spring-boot-starter/ 169 ├── driftkit-vector/ # 🔍 Vector storage and similarity search 170 │ ├── driftkit-vector-core/ # Core vector abstractions 171 │ ├── driftkit-vector-spring-boot-starter/ 172 │ ├── driftkit-vector-spring-ai/ # Spring AI vector stores integration 173 │ └── driftkit-vector-spring-ai-starter/ 174 ├── driftkit-workflows/ # ⚙️ AI orchestration and chat workflows 175 │ ├── driftkit-workflow-engine-core/ # Core engine with chat support 176 │ ├── driftkit-workflow-engine-agents/ # Multi-agent patterns (Loop, Sequential, Hierarchical) 177 │ ├── driftkit-workflow-test-framework/ # Comprehensive testing support 178 │ └── driftkit-workflow-engine-spring-boot-starter/ # Spring Boot integration 179 ├── driftkit-context-engineering/ # 📝 Prompt management and engineering 180 │ ├── driftkit-context-engineering-core/ 181 │ ├── driftkit-context-engineering-spring-boot-starter/ 182 │ ├── driftkit-context-engineering-spring-ai/ # Spring AI integration 183 │ └── driftkit-context-engineering-spring-ai-starter/ 184 ├── driftkit-workflow-examples/ # 🎯 Reference workflow implementations 185 │ └── example-workflows/ # Sample workflows using new engine 186 └── driftkit-audio/ # 🎵 Audio processing and transcription 187 ├── driftkit-audio-core/ # Core audio processing 188 └── driftkit-audio-spring-boot-starter/ 189 ``` 190 191 ## 🛠️ Technology stack 192 193 - **Java 21** - Modern Java with advanced language features 194 - **Spring Boot 3.3.1** - Enterprise application framework with auto-configuration (optional - core modules work without Spring) 195 - **MongoDB** - Document storage for persistence (optional - PostgreSQL support coming soon) 196 - **Vue.js 3** - Modern frontend framework for prompt engineering UI 197 - **Maven** - Build and dependency management 198 - **Jackson** - JSON processing and serialization 199 - **Feign** - Declarative HTTP client for API integrations 200 201 ## 🚀 Quick start 202 203 ### Add to your project 204 205 ```xml 206 <!-- Add complete framework --> 207 <dependency> 208 <groupId>ai.driftkit</groupId> 209 <artifactId>driftkit-framework</artifactId> 210 <version>0.8.8</version> 211 </dependency> 212 213 <!-- Or add specific modules --> 214 <dependency> 215 <groupId>ai.driftkit</groupId> 216 <artifactId>driftkit-workflow-engine-spring-boot-starter</artifactId> 217 <version>0.8.8</version> 218 </dependency> 219 ``` 220 221 ### Run with minimal config 222 223 ```yaml 224 # application.yml 225 driftkit: 226 vault: 227 - name: "primary" 228 type: "openai" 229 apiKey: "${OPENAI_API_KEY}" 230 model: "gpt-4" 231 - name: "gemini" 232 type: "gemini" 233 apiKey: "${GEMINI_API_KEY}" 234 model: "gemini-2.5-flash" 235 - name: "claude" 236 type: "claude" 237 apiKey: "${CLAUDE_API_KEY}" 238 model: "claude-sonnet-4-20250514" 239 240 # Spring AI integration (optional) 241 driftkit: 242 spring-ai: 243 application-name: "my-app" 244 tracing: 245 enabled: true 246 chat-client: 247 enabled: true 248 ``` 249 250 ```java 251 // That's it! Start using DriftKit 252 @SpringBootApplication 253 public class MyApp { 254 public static void main(String[] args) { 255 SpringApplication.run(MyApp.class, args); 256 } 257 } 258 ``` 259 260 Visit http://localhost:8080/prompt-engineering for the visual prompt editor! 261 262 ## 💻 Code examples 263 264 ### 1. Type-safe AI integration 265 266 ```java 267 // No JSON parsing needed - direct Java objects! 268 LLMAgent agent = LLMAgent.builder() 269 .modelClient(modelClient) 270 .systemMessage("You are a helpful assistant") 271 .build(); 272 273 // Type-safe tool calling 274 @Tool(description = "Get weather for a city") 275 public WeatherInfo getWeather(String city) { 276 return new WeatherInfo(city, 22.5, "Sunny"); 277 } 278 279 // Automatic tool execution with typed results 280 agent.registerTool("getWeather", this); 281 var response = agent.executeWithTools("What's the weather in Paris?"); 282 WeatherInfo weather = response.getToolResults().get(0).getTypedResult(); // No JSON! 283 284 // Structured output extraction 285 Person person = agent.executeStructured( 286 "Extract: John Doe, 30 years old, engineer", 287 Person.class 288 ).getStructuredData(); 289 ``` 290 291 ### 2. Visual prompt engineering 292 293 - **Web-based editor** with syntax highlighting 294 - **Version control** and A/B testing 295 - **Test sets** with automated evaluation 296 - **Real-time preview** and variable detection 297 298 ### 3. Chat Workflows with Human-in-the-Loop 299 300 ```java 301 @Workflow(id = "customer-support", version = "1.0") 302 public class CustomerSupportWorkflow { 303 304 @InitialStep 305 public StepResult<SupportMenu> greetCustomer(StartEvent event, WorkflowContext context) { 306 SupportMenu menu = new SupportMenu(); 307 menu.setGreeting("Hello! How can I help you today?"); 308 menu.setOptions(Arrays.asList("Account Help", "Technical Support", "Billing")); 309 310 // Suspend workflow and wait for customer choice 311 return StepResult.suspend(menu, CustomerChoice.class); 312 } 313 314 @Step 315 public StepResult<?> handleChoice(CustomerChoice choice, WorkflowContext context) { 316 if ("Billing".equals(choice.getSelection())) { 317 // Complex case - collect more info 318 BillingForm form = new BillingForm(); 319 form.setMessage("I can help with billing. Please provide details:"); 320 return StepResult.suspend(form, BillingDetails.class); 321 } 322 323 // Simple case - provide immediate help 324 HelpResponse response = generateHelp(choice.getSelection()); 325 return StepResult.finish(response); 326 } 327 328 @Step 329 public StepResult<Resolution> processBilling(BillingDetails details, WorkflowContext context) { 330 // Process billing issue 331 Resolution resolution = resolveBillingIssue(details); 332 return StepResult.finish(resolution); 333 } 334 } 335 ``` 336 337 ### 4. Spring AI Integration 338 339 ```java 340 // Use DriftKit prompts with Spring AI ChatClient 341 @Component 342 public class CustomerService { 343 private final DriftKitChatClient chatClient; 344 345 public String analyzeSentiment(String review) { 346 // Use DriftKit prompt with full tracing 347 return chatClient.promptById("sentiment.analysis") 348 .withVariable("review", review) 349 .withLanguage(Language.ENGLISH) 350 .call() 351 .content(); 352 } 353 354 public ProductInfo extractProductInfo(String description) { 355 // Structured output with DriftKit prompt management 356 return chatClient.promptById("product.extraction") 357 .withVariable("description", description) 358 .call() 359 .entity(ProductInfo.class); 360 } 361 } 362 363 // Or use Spring AI directly with DriftKit prompt provider 364 @Component 365 public class AIService { 366 private final ChatClient chatClient; 367 private final DriftKitPromptProvider promptProvider; 368 369 public String generateContent(Map<String, Object> variables) { 370 // Get prompt configuration from DriftKit 371 var config = promptProvider.getPrompt("content.generation", Language.ENGLISH); 372 373 // Use with Spring AI's fluent API 374 return chatClient.prompt() 375 .system(config.getSystemMessage()) 376 .user(u -> u.text(config.getUserMessage()).params(variables)) 377 .options(opt -> opt.temperature(config.getTemperature())) 378 .call() 379 .content(); 380 } 381 } 382 ``` 383 384 ## 🧩 Core Modules 385 386 ### DriftKit Common 387 **Foundation module providing shared utilities and domain objects** 388 389 - **Chat Management** - Conversation handling with memory and context 390 - **Document Processing** - Intelligent text splitting and tokenization 391 - **Text Analysis** - Similarity calculations and NLP utilities 392 - **Template Engine** - Variable substitution with control flow 393 - **JSON Processing** - Robust parsing with error recovery 394 - **Configuration** - Centralized configuration management 395 396 **Key Classes:** 397 - `Chat`, `Message`, `AITask` - Core domain objects 398 - `TokenWindowChatMemory` - Token-based memory management 399 - `DocumentSplitter` - Intelligent text chunking 400 - `TemplateEngine` - Advanced template processing 401 - `EtlConfig` - Configuration management 402 403 ### DriftKit Clients 404 **Unified AI model client abstraction with multiple provider support** 405 406 - **Provider Abstraction** - Consistent interface across AI models 407 - **OpenAI Integration** - Complete OpenAI API support including GPT-4, O3-Mini 408 - **Google Gemini Integration** - Full Gemini API support including 2.5 Pro/Flash/Lite models 409 - **Anthropic Claude Integration** - Full Claude API support including Opus 4, Sonnet 4, Haiku 3.5 410 - **Multi-modal Support** - Text-to-text, text-to-image, image-to-text 411 - **Function Calling** - Tool use and structured output 412 - **Structured Output** - JSON schema-based responses with strict mode support 413 - **Request Tracing** - Performance monitoring and debugging 414 415 **Supported Models:** 416 - OpenAI: GPT-4, GPT-4o, GPT-4o-mini, o3-Mini, DALL-E 417 - Google Gemini: 2.5 Pro, 2.5 Flash, 2.5 Flash-Lite, experimental models (TTS, native audio) 418 - Anthropic Claude: Opus 4, Sonnet 4, Haiku 3.5 (multimodal with vision support) 419 - Extensible architecture for custom providers 420 421 **Key Features:** 422 - Dynamic client discovery via ServiceLoader 423 - Comprehensive parameter support (temperature, top_p, max_tokens, etc.) 424 - Tool/function calling with JSON schema support 425 - Built-in tracing and performance monitoring 426 427 ### DriftKit Embedding 428 **Text embedding services with multiple backends** 429 430 - **Provider Abstraction** - Unified interface for embedding models 431 - **OpenAI Embeddings** - text-embedding-ada-002 and newer models 432 - **Cohere Integration** - embed-english-v2.0 support 433 - **Spring AI Integration** - Access all Spring AI embedding providers 434 - **Local BERT Models** - ONNX-based local embedding generation 435 - **Performance Optimization** - Caching and batch processing 436 437 **Supported Providers:** 438 - OpenAI (text-embedding-ada-002, text-embedding-3-small/large) 439 - Cohere (embed-english-v2.0, embed-multilingual-v2.0) 440 - Spring AI providers (OpenAI, Azure OpenAI, Ollama, and more) 441 - Local BERT models via ONNX Runtime 442 443 **Spring AI Integration:** 444 - Unified access to all Spring AI embedding providers 445 - Automatic configuration handling 446 - Seamless conversion between Spring AI and DriftKit formats 447 - Full error handling and validation 448 449 **Key Features:** 450 - Automatic model discovery and configuration 451 - Batch processing for efficiency 452 - Type-safe metadata management 453 - Local model support for offline scenarios 454 - Spring AI provider support for extended compatibility 455 456 ### DriftKit Vector 457 **Vector storage and similarity search with multiple backends** 458 459 - **Storage Backends** - In-memory, file-based, Pinecone, and Spring AI support 460 - **Document Management** - Full CRUD operations with metadata 461 - **Similarity Search** - Efficient k-nearest neighbor search 462 - **Content Processing** - Multi-format document parsing 463 - **REST API** - Complete web interface for vector operations 464 - **Spring AI Integration** - Use any Spring AI vector store through DriftKit interface 465 466 **Storage Options:** 467 - **InMemoryVectorStore** - High-performance for development 468 - **FileBasedVectorStore** - Persistent local storage 469 - **PineconeVectorStore** - Cloud-based production storage 470 - **Spring AI Vector Stores** - Qdrant, Weaviate, ChromaDB, PGVector, MongoDB Atlas, Redis, and more 471 472 **Spring AI Integration Features:** 473 - Seamless adapter between Spring AI and DriftKit interfaces 474 - Auto-configuration for Spring Boot applications 475 - Support for all Spring AI vector store implementations 476 - Consistent API across different backends 477 478 **Document Processing:** 479 - PDF, Microsoft Office, OpenDocument formats 480 - Images with AI-powered content extraction 481 - YouTube transcript processing 482 - HTML and plain text support 483 484 ### DriftKit Workflows 485 **Comprehensive AI orchestration engine with native chat and human-in-the-loop support** 486 487 - **Chat Workflows** - Multi-turn conversations with automatic message tracking 488 - **Human-in-the-Loop** - Suspend/resume for data collection and approvals 489 - **Annotation-driven** - Define workflows with @Workflow, @Step, @AsyncStep 490 - **Fluent API** - Programmatic workflow construction with WorkflowBuilder 491 - **Multi-Agent Patterns** - Loop, Sequential, and Hierarchical agent orchestration 492 - **Async Processing** - Long-running operations with progress tracking 493 - **Type-Safe Results** - StepResult types for suspend, continue, branch, async, finish 494 495 #### LLMAgent SDK Features 496 497 The LLMAgent provides a simplified, type-safe interface for AI interactions: 498 499 **Key Features:** 500 - **Unified execute*() methods** - Consistent API for all operations 501 - **Type-safe responses** - `AgentResponse<T>` wrapper for typed results 502 - **Tool calling** - Both manual and automatic execution modes 503 - **Structured output** - JSON schema-based extraction with type safety 504 - **Multi-modal support** - Text + images in single interface 505 - **Memory management** - Conversation history with `ChatMemory` 506 - **Prompt templates** - Integration with `PromptService` 507 - **Error handling** - Comprehensive error management 508 509 **API Methods:** 510 - `executeText()` - Simple text chat 511 - `executeForToolCalls()` - Get tool calls for manual execution 512 - `executeWithTools()` - Automatic tool execution with typed results 513 - `executeStructured()` - Type-safe structured output extraction 514 - `executeWithPrompt()` - Use prompt templates by ID 515 - `executeWithImages()` - Multi-modal text + image processing 516 517 **Core Features:** 518 - **Automatic Chat Tracking** - Messages saved to ChatStore without manual code 519 - **Workflow Suspension** - Pause for human input with type-safe resumption 520 - **Context Preservation** - State maintained across suspensions 521 - **Progress Reporting** - Real-time updates for async operations 522 - **Error Recovery** - Comprehensive error handling with retry policies 523 524 ### DriftKit Context Engineering 525 **Advanced prompt management and engineering platform** 526 527 - **Multi-storage Backends** - In-memory, filesystem, and MongoDB 528 - **Template Processing** - Advanced variable substitution with control flow 529 - **Version Control** - Prompt lifecycle management 530 - **Testing Framework** - Comprehensive evaluation system 531 - **Vue.js Frontend** - Modern web interface for prompt development 532 533 **Template Features:** 534 - Variable substitution: `{{variable}}` 535 - Conditional rendering: `{{#if condition}}...{{/if}}` 536 - List iteration: `{{#list items as item}}...{{/list}}` 537 - Dictionary integration: `dict:itemId-markers:` 538 539 **Frontend Capabilities:** 540 - Monaco-style editor with syntax highlighting 541 - Real-time variable detection and validation 542 - Test set creation and execution 543 - Multi-language prompt support 544 - Version comparison and rollback 545 546 ### DriftKit Workflow Examples 547 **Production-ready patterns for modern AI applications** 548 549 **Chat & Conversational AI:** 550 - **Customer Service Bot** - Multi-turn support with automatic message tracking 551 - **Product Recommendation** - Conversational commerce with context awareness 552 - **FAQ Assistant** - Intelligent routing with human escalation 553 554 **Human-in-the-Loop:** 555 - **Approval Workflows** - Document approval with suspension points 556 - **Data Collection** - Multi-step forms with validation 557 - **Review Processes** - Content moderation with human oversight 558 559 **Multi-Agent Systems:** 560 - **Research Pipeline** - Sequential agents for data gathering and analysis 561 - **Content Creation** - LoopAgent for iterative refinement 562 - **Complex Planning** - Hierarchical agents with specialized tools 563 564 ## 🛠️ Production Features 565 566 ### Built-in Capabilities 567 - **Request tracing** and monitoring 568 - **Token-based memory** management 569 - **Retry mechanisms** with backoff 570 - **Connection pooling** and caching 571 - **Graceful error handling** 572 - **Structured logging** 573 574 575 ## 🎨 LLMAgent Use Cases & Real-World Scenarios 576 577 ### Loop Pattern - Iterative Refinement 578 579 The LoopAgent executes a worker agent repeatedly until an evaluator agent determines the result meets specific criteria. Perfect for tasks requiring refinement or validation. 580 581 **Example: Travel Planning with Requirements** 582 ```java 583 // Worker generates, evaluator validates until perfect 584 Agent planner = LLMAgent.builder() 585 .systemMessage("Create travel itinerary") 586 .build(); 587 588 Agent validator = LLMAgent.builder() 589 .systemMessage("Check if plan includes all requirements") 590 .build(); 591 592 LoopAgent travelLoop = LoopAgent.builder() 593 .worker(planner) 594 .evaluator(validator) 595 .stopCondition(LoopStatus.COMPLETE) 596 .maxIterations(5) 597 .build(); 598 599 String perfectPlan = travelLoop.execute("Plan my Paris trip"); 600 ``` 601 602 ### Sequential Pattern - Pipeline Processing 603 604 ```java 605 SequentialAgent pipeline = SequentialAgent.builder() 606 .agent(researcher) // Research topic 607 .agent(analyzer) // Analyze findings 608 .agent(summarizer) // Create summary 609 .build(); 610 611 String report = pipeline.execute("Quantum computing trends"); 612 ``` 613 614 ### Hierarchical Pattern - Agent as Tool 615 616 ```java 617 // Specialized agents become tools for orchestrator 618 Agent flightAgent = LLMAgent.builder() 619 .systemMessage("Find flights") 620 .name("FlightSearch") 621 .build(); 622 623 Agent orchestrator = LLMAgent.builder() 624 .systemMessage("Plan complete trips") 625 .addTool(AgentAsTool.create("searchFlights", flightAgent)) 626 .build(); 627 ``` 628 629 630 631 ## 🎨 Structured Output Support 632 633 ### Type-Safe JSON Schema Generation 634 ```java 635 // Define your model with validation 636 public class Person { 637 @NotNull private String name; 638 private Integer age; 639 private String email; 640 } 641 642 // Automatic schema generation 643 ResponseFormat format = ResponseFormat.jsonSchema(Person.class); 644 645 // Get typed response 646 ModelTextResponse response = modelClient.textToText( 647 ModelTextRequest.builder() 648 .messages(messages) 649 .responseFormat(format) 650 .build() 651 ); 652 653 Person person = JsonUtils.fromJson( 654 response.getChoices().get(0).getMessage().getContent(), 655 Person.class 656 ); 657 ``` 658 659 ### Strict Mode for Required Fields 660 ```java 661 @JsonSchemaStrict // All fields required 662 public class StrictPerson { 663 private String name; 664 private int age; 665 private String email; 666 } 667 ``` 668 669 ## 🗺️ Roadmap 670 671 ### Ecosystem expansion 672 - **Additional LLM providers** - Mistral AI, Grok, DeepSeek 673 - **PostgreSQL backend** - Enterprise-grade persistence for context-engineering module 674 - **Extended vector storage** - Native support without Spring: Weaviate, Qdrant, Redis Vector, Elasticsearch 675 676 ### Developer experience 677 - **Frontend upgrade** - Modern UI/UX for prompt engineering, real-time collaboration, advanced debugging 678 - **Comprehensive testing** - Full test coverage, performance benchmarks, integration tests 679 - **Documentation website** - Interactive examples, API references, best practices guide 680 - **Open-source demos** - Production-ready reference implementations 681 682 ### Advanced capabilities 683 - **Enhanced evaluations** - More metrics, custom evaluators, industry benchmarks 684 - **Text-to-speech** - OpenAI TTS, ElevenLabs, local TTS models 685 - **OpenTelemetry** - Full observability for model calls and agent workflows 686 - **Docker deployment** - One-click containerized deployment 687 688 **Want to contribute or have suggestions?** Open an issue on GitHub! 689 690 ## 🌿 Spring AI Integration 691 692 DriftKit provides seamless integration with Spring AI, allowing you to leverage the entire Spring AI ecosystem while benefiting from DriftKit's advanced features. 693 694 ### Spring AI Support Across Modules 695 696 #### 1. **DriftKit Clients - Spring AI Models** 697 Access all Spring AI chat models through DriftKit's unified interface: 698 699 ```java 700 // Use Spring AI models with DriftKit 701 @Bean 702 public ModelClient springAIModelClient(ChatModel chatModel) { 703 return new SpringAIModelClient(chatModel) 704 .withModel("gpt-4") 705 .withTemperature(0.7); 706 } 707 708 // Supports all Spring AI features 709 - OpenAI, Azure OpenAI, Ollama, Anthropic, Google Gemini 710 - Function/tool calling with FunctionToolCallback 711 - Streaming responses 712 - Full tracing integration 713 ``` 714 715 #### 2. **DriftKit Embedding - Spring AI Providers** 716 Use any Spring AI embedding provider: 717 718 ```yaml 719 driftkit: 720 embedding: 721 name: spring-ai 722 config: 723 provider: openai # or azure-openai, ollama 724 model-name: text-embedding-3-small 725 api-key: ${OPENAI_API_KEY} 726 ``` 727 728 ```java 729 // Automatic Spring AI embedding model creation 730 @Autowired 731 private EmbeddingModel embeddingModel; // Works with any Spring AI provider 732 ``` 733 734 Supported providers: 735 - OpenAI (text-embedding-3-small, text-embedding-3-large) 736 - Azure OpenAI (with deployment configuration) 737 - Ollama (local embeddings) 738 - Any custom Spring AI embedding provider 739 740 #### 3. **DriftKit Vector - Spring AI Vector Stores** 741 Integrate with all Spring AI vector stores: 742 743 ```java 744 // Use Spring AI vector stores with DriftKit 745 @Bean 746 public VectorStore springAIVectorStore( 747 org.springframework.ai.vectorstore.VectorStore springAIStore) { 748 return new SpringAIVectorStore(springAIStore); 749 } 750 ``` 751 752 Supported backends: 753 - Qdrant 754 - Weaviate 755 - ChromaDB 756 - PGVector 757 - MongoDB Atlas 758 - Redis 759 - Elasticsearch 760 - Any Spring AI vector store implementation 761 762 #### 4. **DriftKit Context Engineering - Spring AI ChatClient** 763 Enhanced Spring AI ChatClient with DriftKit features: 764 765 ```java 766 // Enhanced ChatClient with DriftKit integration 767 @Autowired 768 private DriftKitChatClient chatClient; 769 770 // Use DriftKit prompts with Spring AI 771 PromptConfig config = chatClient.promptProvider() 772 .prompt("customer-support") 773 .withVariable("customer", customerName) 774 .build(); 775 776 String response = chatClient.prompt(config).content(); 777 778 // Spring AI ChatClient with DriftKit advisors 779 @Bean 780 public ChatClient enhancedChatClient(SpringAIChatClientFactory factory) { 781 return factory.createSpringAIChatClient(); // Includes tracing, memory, logging 782 } 783 ``` 784 785 ### Spring Boot Auto-Configuration 786 787 Add the starter for automatic configuration: 788 789 ```xml 790 <dependency> 791 <groupId>ai.driftkit</groupId> 792 <artifactId>driftkit-context-engineering-spring-ai-starter</artifactId> 793 <version>0.8.8</version> 794 </dependency> 795 ``` 796 797 Configuration options: 798 799 ```yaml 800 driftkit: 801 spring-ai: 802 application-name: "my-app" 803 tracing: 804 enabled: true # Enable DriftKit tracing for Spring AI 805 memory: 806 enabled: true # Add conversation memory 807 logging: 808 enabled: true # Add request/response logging 809 chat-client: 810 enabled: true # Create DriftKitChatClient bean 811 enhanced-chat-client: 812 enabled: false # Create enhanced ChatClient with all features 813 default-system-message: "You are a helpful assistant" 814 ``` 815 816 ### Key Benefits 817 818 1. **Unified Interface** - Use Spring AI models with DriftKit's advanced features 819 2. **Full Compatibility** - All Spring AI providers work out of the box 820 3. **Enhanced Features** - Add tracing, memory, and monitoring to Spring AI 821 4. **Type Safety** - Maintain type safety across the integration 822 5. **Auto-Configuration** - Spring Boot starters for zero-config setup 823 6. **Extensibility** - Easy to add new Spring AI providers 824 825 ### Migration from Spring AI 826 827 Migrating from pure Spring AI to DriftKit is straightforward: 828 829 ```java 830 // Before (Spring AI only) 831 ChatClient chatClient = ChatClient.builder(chatModel).build(); 832 String response = chatClient.prompt() 833 .user("Hello") 834 .call() 835 .content(); 836 837 // After (DriftKit + Spring AI) 838 DriftKitChatClient chatClient = factory.createChatClient(); 839 String response = chatClient.prompt() 840 .user("Hello") 841 .call() 842 .content(); 843 // Plus: automatic tracing, memory, prompt management, etc. 844 ``` 845 846 ## 📄 License 847 848 Apache License 2.0 - see [LICENSE](LICENSE) file for details. 849 850 ``` 851 Copyright 2024 DriftKit Contributors 852 853 Licensed under the Apache License, Version 2.0 (the "License"); 854 you may not use this file except in compliance with the License. 855 You may obtain a copy of the License at 856 857 http://www.apache.org/licenses/LICENSE-2.0 858 859 Unless required by applicable law or agreed to in writing, software 860 distributed under the License is distributed on an "AS IS" BASIS, 861 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 862 See the License for the specific language governing permissions and 863 limitations under the License. 864 ``` 865 866 ## 🤝 Get Started Today 867 868 ```bash 869 # Add to your pom.xml and start building! 870 <dependency> 871 <groupId>ai.driftkit</groupId> 872 <artifactId>driftkit-framework</artifactId> 873 <version>0.8.8</version> 874 </dependency> 875 ``` 876 877 Visit http://localhost:8080/prompt-engineering and start building! 878 879 --- 880 881 **DriftKit** - The most comprehensive AI framework for Java developers.