Master AI — Complete AI Engineering Guide¶

// Using Spring AI's PromptTemplate
@Service
public class StructuredPromptService {
    private final ChatClient chatClient;

    // Few-shot prompt template
    private static final String FEW_SHOT_TEMPLATE = """
        Classify the following customer message into one of these categories:
        - billing
        - technical
        - general

        Examples:
        Message: "My payment failed" → Category: billing
        Message: "App crashes on login" → Category: technical
        Message: "What are your hours?" → Category: general

        Message: "{userMessage}" → Category:
        """;

    public String classifyMessage(String userMessage) {
        PromptTemplate template = new PromptTemplate(FEW_SHOT_TEMPLATE);
        Prompt prompt = template.create(Map.of("userMessage", userMessage));
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }

    // Chain-of-Thought prompt
    private static final String COT_TEMPLATE = """
        You are a senior Java developer. Analyze the following code for bugs.

        Think step by step:
        1. First, understand what the code is trying to do
        2. Check for null pointer risks
        3. Check for concurrency issues
        4. Check for resource leaks
        5. Provide your final assessment

        Code:
        ```java
        {code}
        ```

        Analysis:
        """;

    public String analyzeCode(String code) {
        PromptTemplate template = new PromptTemplate(COT_TEMPLATE);
        Prompt prompt = template.create(Map.of("code", code));
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }
}

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.messages.SystemMessage;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.stereotype.Service;

@Service
public class AIChatService {
    private final ChatClient chatClient;

    public AIChatService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    public String chat(String userInput) {
        Prompt prompt = new Prompt(List.of(
            new SystemMessage("You are a helpful Java programming assistant."),
            new UserMessage(userInput)
        ));
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }
}

// REST Controller
@RestController
@RequestMapping("/api/chat")
public class ChatController {
    private final AIChatService chatService;

    public ChatController(AIChatService chatService) {
        this.chatService = chatService;
    }

    @PostMapping
    public Map<String, String> chat(@RequestBody Map<String, String> request) {
        String response = chatService.chat(request.get("message"));
        return Map.of("response", response);
    }
}

// Define your output structure
public record MovieRecommendation(
    String title,
    int year,
    String genre,
    double rating,
    String reason
) {}

@Service
public class MovieService {
    private final ChatClient chatClient;

    public List<MovieRecommendation> getRecommendations(String preferences) {
        String prompt = """
            Based on these preferences: %s
            Recommend 3 movies. For each, provide:
            - title, year, genre, rating (out of 10), and reason.
            Respond as a JSON array.
            """.formatted(preferences);

        String response = chatClient.call(new Prompt(prompt))
            .getResult().getOutput().getContent();

        // Parse JSON response into typed objects
        ObjectMapper mapper = new ObjectMapper();
        return mapper.readValue(response,
            new TypeReference<List<MovieRecommendation>>() {});
    }
}

@Service
public class StreamingChatService {
    private final ChatClient chatClient;

    // For real-time streaming (SSE)
    public Flux<String> streamChat(String userInput) {
        Prompt prompt = new Prompt(List.of(
            new SystemMessage("You are a helpful assistant."),
            new UserMessage(userInput)
        ));

        return chatClient.stream(prompt)
            .map(response -> response.getResult().getOutput().getContent())
            .filter(Objects::nonNull);
    }
}

@RestController
public class StreamController {
    private final StreamingChatService streamService;

    @GetMapping(value = "/api/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestParam String message) {
        return streamService.streamChat(message);
    }
}

ChatLanguageModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName("gpt-4o-mini")
    .build();

String response = model.generate("Explain Java Streams in 3 sentences.");
System.out.println(response);

List<ChatMessage> messages = new ArrayList<>();
messages.add(new SystemMessage("You are a Java tutor."));
messages.add(new UserMessage("What is a HashMap?"));

ChatResponse response1 = model.generate(messages);
messages.add(response1.content());

// Follow-up (model remembers context)
messages.add(new UserMessage("How does it handle collisions?"));
ChatResponse response2 = model.generate(messages);

// Define your AI service as a Java interface
interface JavaTutor {

    @SystemMessage("You are a patient Java tutor. Explain concepts simply with examples.")
    String explain(@UserMessage String concept);

    @SystemMessage("You are a code reviewer. Be constructive.")
    String review(@UserMessage String code);
}

// LangChain4j generates the implementation
JavaTutor tutor = AiServices.builder(JavaTutor.class)
    .chatLanguageModel(model)
    .chatMemory(MessageWindowChatMemory.withMaxMessages(20))
    .build();

String explanation = tutor.explain("What are Java generics?");
String codeReview = tutor.review("public void process(List list) { ... }");

public class RAGSystem {
    private final ChatLanguageModel model;
    private final EmbeddingModel embeddingModel;
    private final InMemoryEmbeddingStore<TextSegment> store;

    // Index documents
    public void indexDocuments(List<String> documents) {
        for (String doc : documents) {
            // Chunk the document first
            List<String> chunks = splitIntoChunks(doc, 500, 50); // size=500, overlap=50
            for (String chunk : chunks) {
                Embedding emb = embeddingModel.embed(chunk).content();
                store.add(emb, new TextSegment(chunk, null));
            }
        }
    }

    // Query with RAG
    public String query(String question) {
        // 1. Embed the question
        Embedding queryEmb = embeddingModel.embed(question).content();

        // 2. Retrieve relevant documents
        List<EmbeddingMatch<TextSegment>> matches = store.findRelevant(queryEmb, 3);

        // 3. Filter by relevance score
        String context = matches.stream()
            .filter(m -> m.score() > 0.7) // Only high-relevance matches
            .map(m -> m.embedded().text())
            .collect(Collectors.joining("\n---\n"));

        if (context.isEmpty()) {
            return "I don't have enough information to answer that question.";
        }

        // 4. Generate grounded response
        String prompt = """
            Based on the following context, answer the question.
            If the answer is not in the context, say "I don't have that information."

            Context:
            %s

            Question: %s

            Answer:
            """.formatted(context, question);

        return model.generate(prompt);
    }

    private List<String> splitIntoChunks(String text, int chunkSize, int overlap) {
        List<String> chunks = new ArrayList<>();
        for (int i = 0; i < text.length(); i += (chunkSize - overlap)) {
            chunks.add(text.substring(i, Math.min(i + chunkSize, text.length())));
        }
        return chunks;
    }
}

public class ReflectionAgent {
    private final ChatLanguageModel model;

    public String generateWithReflection(String task, int maxIterations) {
        String draft = model.generate("Complete this task: " + task);

        for (int i = 0; i < maxIterations; i++) {
            // Self-critique
            String critique = model.generate(
                "Review this response for errors, missing details, and improvements:\n" + draft
            );

            // Check if good enough
            if (critique.toLowerCase().contains("no issues") ||
                critique.toLowerCase().contains("looks good")) {
                break;
            }

            // Refine based on critique
            draft = model.generate(
                "Original: " + draft + "\nCritique: " + critique +
                "\nGenerate an improved version addressing the critique."
            );
        }

        return draft;
    }
}

public class ReActAgent {
    private final ChatLanguageModel model;
    private final Map<String, Function<String, String>> tools;

    public String solve(String question) {
        StringBuilder scratchpad = new StringBuilder();
        String systemPrompt = """
            You are a helpful agent. Use the following format:
            Thought: your reasoning
            Action: toolName(argument)
            ... (wait for Observation)
            Thought: reasoning about observation
            Answer: final answer to the user

            Available tools: %s
            """.formatted(tools.keySet());

        for (int step = 0; step < 5; step++) {
            String response = model.generate(
                systemPrompt + "\nQuestion: " + question + "\n" + scratchpad
            );

            // Parse action from response
            if (response.contains("Answer:")) {
                return response.substring(response.indexOf("Answer:") + 8).trim();
            }

            if (response.contains("Action:")) {
                String action = parseAction(response);
                String toolName = action.split("\\(")[0].trim();
                String arg = action.substring(action.indexOf('(') + 1, action.lastIndexOf(')'));

                String observation = tools.get(toolName).apply(arg);
                scratchpad.append(response)
                    .append("\nObservation: ").append(observation).append("\n");
            }
        }
        return "I couldn't find an answer within the step limit.";
    }
}

import dev.langchain4j.agent.tool.Tool;

public class DeveloperTools {

    @Tool("Search for Java documentation")
    public String searchDocs(String query) {
        return "Documentation result for: " + query;
    }

    @Tool("Execute a SQL query against the database")
    public String executeQuery(String sql) {
        // Validate SQL (prevent injection!)
        if (sql.toLowerCase().contains("drop") || sql.toLowerCase().contains("delete")) {
            return "Error: Destructive queries are not allowed.";
        }
        return "Query results: [...]";
    }

    @Tool("Get current system metrics")
    public String getMetrics() {
        Runtime rt = Runtime.getRuntime();
        return String.format("Memory: %dMB / %dMB, Processors: %d",
            rt.totalMemory() / 1024 / 1024,
            rt.maxMemory() / 1024 / 1024,
            rt.availableProcessors());
    }

    @Tool("Send an HTTP GET request to a URL")
    public String httpGet(String url) {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url)).GET().build();
        try {
            return client.send(request, HttpResponse.BodyHandlers.ofString()).body();
        } catch (Exception e) {
            return "Error: " + e.getMessage();
        }
    }
}

public class PlanningAgent {
    private final ChatLanguageModel model;

    public String solve(String goal) {
        // Step 1: Create plan
        String plan = model.generate(
            "Break this goal into numbered steps (max 5): " + goal
        );

        // Step 2: Execute each step
        StringBuilder results = new StringBuilder();
        for (String step : plan.split("\n")) {
            if (step.trim().isEmpty()) continue;
            String result = model.generate("Execute this step: " + step);
            results.append(step).append("\nResult: ").append(result).append("\n\n");
        }

        // Step 3: Synthesize
        return model.generate("Summarize these results into a coherent answer:\n" + results);
    }
}

public class MultiAgentSystem {
    private final ChatLanguageModel researcher;
    private final ChatLanguageModel coder;
    private final ChatLanguageModel reviewer;

    public String buildFeature(String requirement) {
        // Agent 1: Research
        String research = researcher.generate(
            "Research the best approach for: " + requirement +
            "\nConsider: design patterns, performance, edge cases."
        );

        // Agent 2: Implement
        String code = coder.generate(
            "Based on this research, write production-quality Java code:\n" + research +
            "\nInclude error handling, logging, and javadoc."
        );

        // Agent 3: Review
        String review = reviewer.generate(
            "Review this code for bugs, security issues (OWASP), and improvements:\n" + code
        );

        // Agent 4: Iterate if needed
        if (review.toLowerCase().contains("critical") || review.toLowerCase().contains("bug")) {
            code = coder.generate(
                "Fix these issues in the code:\n" + review + "\n\nOriginal code:\n" + code
            );
        }

        return "Code:\n" + code + "\n\nReview:\n" + review;
    }
}

@McpServer
public class JavaDocsServer {

    @McpTool(description = "Search Java API documentation for a class")
    public String searchJavaDocs(String className) {
        return "Documentation for " + className + ": ...";
    }

    @McpTool(description = "Get all method signatures for a Java class")
    public String getMethods(String className) {
        return "Methods for " + className + ": ...";
    }

    @McpTool(description = "Run a Java code snippet and return the output")
    public String executeJava(String code) {
        // Sandboxed execution
        return "Output: ...";
    }

    @McpResource(uri = "docs://java/tutorials")
    public String getTutorials() {
        return "Available tutorials: Streams, Collections, Concurrency...";
    }
}

@Service
public class HallucinationDetector {
    private final ChatLanguageModel judge;

    public boolean isHallucination(String context, String answer) {
        String prompt = """
            Given the following context and answer, determine if the answer
            contains any claims NOT supported by the context.

            Context: %s

            Answer: %s

            Respond with only "FAITHFUL" or "HALLUCINATION" followed by explanation.
            """.formatted(context, answer);

        String verdict = judge.generate(prompt);
        return verdict.toUpperCase().contains("HALLUCINATION");
    }
}

@Component
public class TokenUsageTracker {
    private final AtomicLong totalInputTokens = new AtomicLong(0);
    private final AtomicLong totalOutputTokens = new AtomicLong(0);

    // Pricing per 1M tokens (example: GPT-4o-mini)
    private static final double INPUT_COST_PER_M = 0.15;
    private static final double OUTPUT_COST_PER_M = 0.60;

    public void track(ChatResponse response) {
        Usage usage = response.getMetadata().getUsage();
        totalInputTokens.addAndGet(usage.getInputTokens());
        totalOutputTokens.addAndGet(usage.getOutputTokens());
    }

    public double getTotalCost() {
        return (totalInputTokens.get() / 1_000_000.0) * INPUT_COST_PER_M +
               (totalOutputTokens.get() / 1_000_000.0) * OUTPUT_COST_PER_M;
    }

    public String getReport() {
        return String.format("Input: %d tokens | Output: %d tokens | Cost: $%.4f",
            totalInputTokens.get(), totalOutputTokens.get(), getTotalCost());
    }
}

@Component
public class AIRateLimiter {
    // Sliding window rate limiter
    private final Semaphore permits;
    private final ScheduledExecutorService scheduler;

    public AIRateLimiter(
        @Value("${ai.rate-limit.requests-per-minute:60}") int rpm
    ) {
        this.permits = new Semaphore(rpm);
        this.scheduler = Executors.newSingleThreadScheduledExecutor();

        // Replenish permits every minute
        scheduler.scheduleAtFixedRate(
            () -> permits.release(rpm - permits.availablePermits()),
            1, 1, TimeUnit.MINUTES
        );
    }

    public <T> T executeWithRateLimit(Supplier<T> aiCall) {
        if (!permits.tryAcquire(5, TimeUnit.SECONDS)) {
            throw new RateLimitExceededException("AI rate limit exceeded. Try again later.");
        }
        return aiCall.get();
    }
}

@Service
public class CachedAIService {
    private final ChatLanguageModel model;
    private final Cache<String, String> cache;

    public CachedAIService(ChatLanguageModel model) {
        this.model = model;
        this.cache = Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(1, TimeUnit.HOURS)
            .build();
    }

    public String chat(String input) {
        String cacheKey = hashInput(input);
        return cache.get(cacheKey, k -> model.generate(input));
    }

    // For semantic caching: embed the query and check similarity
    // to cached queries before calling the model
    public String semanticCachedChat(String input) {
        Embedding queryEmb = embeddingModel.embed(input).content();
        // Check if similar query exists in cache
        Optional<CacheEntry> cached = findSimilar(queryEmb, 0.95);
        if (cached.isPresent()) return cached.get().response();

        String response = model.generate(input);
        cacheWithEmbedding(queryEmb, input, response);
        return response;
    }
}

@Service
public class ResilientAIService {
    private final ChatLanguageModel primary;   // GPT-4o
    private final ChatLanguageModel secondary; // Claude 3.5
    private final ChatLanguageModel fallback;  // Local Ollama

    public String generate(String prompt) {
        // Try primary
        try {
            return primary.generate(prompt);
        } catch (Exception e) {
            log.warn("Primary model failed: {}", e.getMessage());
        }

        // Try secondary
        try {
            return secondary.generate(prompt);
        } catch (Exception e) {
            log.warn("Secondary model failed: {}", e.getMessage());
        }

        // Fallback to local
        try {
            return fallback.generate(prompt);
        } catch (Exception e) {
            log.error("All models failed", e);
            throw new AIServiceUnavailableException("All AI providers are unavailable");
        }
    }
}

@Service
public class AIGuardrails {

    // Input guardrails — validate before sending to model
    public String sanitizeInput(String userInput) {
        // 1. Check for prompt injection attempts
        if (containsPromptInjection(userInput)) {
            throw new SecurityException("Potential prompt injection detected");
        }

        // 2. Check length limits
        if (userInput.length() > 10_000) {
            throw new ValidationException("Input too long");
        }

        // 3. Remove PII (emails, phone numbers, SSN)
        return removePII(userInput);
    }

    // Output guardrails — validate before returning to user
    public String sanitizeOutput(String modelOutput) {
        // 1. Check for harmful content
        if (containsHarmfulContent(modelOutput)) {
            return "I'm unable to provide that information.";
        }

        // 2. Remove any leaked system prompt content
        modelOutput = removeSystemPromptLeaks(modelOutput);

        return modelOutput;
    }

    private boolean containsPromptInjection(String input) {
        String lower = input.toLowerCase();
        return lower.contains("ignore previous instructions") ||
               lower.contains("you are now") ||
               lower.contains("system prompt");
    }
}

@Service
public class DocumentQAService {
    private final ChatLanguageModel model;
    private final EmbeddingModel embeddingModel;
    private final InMemoryEmbeddingStore<TextSegment> store;

    public void ingestDocument(String content) {
        List<String> chunks = splitIntoChunks(content, 500);
        for (String chunk : chunks) {
            Embedding emb = embeddingModel.embed(chunk).content();
            store.add(emb, new TextSegment(chunk, null));
        }
    }

    public String askQuestion(String question) {
        Embedding queryEmb = embeddingModel.embed(question).content();
        List<EmbeddingMatch<TextSegment>> relevant = store.findRelevant(queryEmb, 3);

        String context = relevant.stream()
            .map(m -> m.embedded().text())
            .collect(Collectors.joining("\n\n"));

        return model.generate(
            "Answer based on context only. If not found, say 'not found'.\n\n" +
            "Context:\n" + context + "\n\nQuestion: " + question
        );
    }

    private List<String> splitIntoChunks(String text, int chunkSize) {
        List<String> chunks = new ArrayList<>();
        for (int i = 0; i < text.length(); i += chunkSize) {
            chunks.add(text.substring(i, Math.min(i + chunkSize, text.length())));
        }
        return chunks;
    }
}

@Service
public class CodeReviewAgent {
    private final ChatLanguageModel model;

    public CodeReviewResult review(String code) {
        String review = model.generate(
            "You are a senior Java developer. Review this code for:\n" +
            "1. Bugs and logical errors\n" +
            "2. Security vulnerabilities (OWASP Top 10)\n" +
            "3. Performance issues\n" +
            "4. Best practice violations\n" +
            "5. Suggestions for improvement\n\n" +
            "Code:\n```java\n" + code + "\n```\n\n" +
            "Format: For each issue, provide [SEVERITY] Description and Fix."
        );

        return new CodeReviewResult(review);
    }
}

@Service
public class DatabaseAgent {
    private final ChatLanguageModel model;
    private final JdbcTemplate jdbc;

    @Tool("Execute a read-only SQL query and return results")
    public String queryDatabase(String sql) {
        // Safety: only allow SELECT
        if (!sql.trim().toUpperCase().startsWith("SELECT")) {
            return "Error: Only SELECT queries are allowed";
        }
        List<Map<String, Object>> results = jdbc.queryForList(sql);
        return results.toString();
    }

    public String ask(String question, String schema) {
        String prompt = """
            Given this database schema:
            %s

            Convert this natural language question to SQL:
            "%s"

            Rules:
            - Only use SELECT queries
            - Use proper JOINs
            - Add LIMIT 10 to prevent large result sets

            SQL:
            """.formatted(schema, question);

        String sql = model.generate(prompt).trim();
        String results = queryDatabase(sql);

        return model.generate(
            "Based on these query results, answer the user's question in natural language.\n" +
            "Question: " + question + "\nResults: " + results
        );
    }
}