AI Incident Assistant

A Spring Boot REST API application that analyzes incident descriptions using Gemini 2.5 Fast LLM and returns structured JSON responses.

Architecture

The application implements a clear pipeline with separate stages:

1. Input parsing - Validates and cleans the incident description
2. Context loading - Loads system description and past incidents
3. Prompt construction - Builds the LLM prompt with context
4. LLM call - Calls Gemini 2.5 Fast API
5. Output validation - Validates response structure and content
6. Retry/recovery logic - Retries up to 2 times on failure

API Endpoint

POST /api/analyze

Request Body

{
  "incident": "string"
}

Response

{
  "category": "string",
  "summary": "string",
  "severity": "low|medium|high",
  "hypotheses": [
    {
      "title": "string",
      "reasoning": "string",
      "nextSteps": ["string", "string"]
    }
  ]
}

Setup

Prerequisites

• Java 17+
• Maven 3.6+
• Gemini API Key

Environment Variables

Set the following environment variable:

# On Windows
set GEMINI_API_KEY=your_gemini_api_key_here

# On Linux/Mac
export GEMINI_API_KEY=your_gemini_api_key_here

Configuration

The application uses application.yml for configuration:

server:
  port: 8080

gemini:
  api:
    key: ${GEMINI_API_KEY}

logging:
  level:
    org.elmez.iaj: DEBUG

Running the Application

1. Clone the repository
2. Set the GEMINI_API_KEY environment variable
3. Run the application:

   mvn spring-boot:run

4. The application will start on port 8080

Example Usage

curl -X POST http://localhost:8080/analyze -H "Content-Type: application/json" -d '{ "incident": "Payment service is experiencing timeouts and users cannot complete transactions" }'

Invoke-RestMethod -Uri "http://localhost:8080/analyze" -Method Post -ContentType "application/json" -Body '{ "incident": "Payment service is experiencing timeouts and users cannot complete transactions" }'

http://localhost:8080/api/models

Project Structure

src/main/java/org/elmez/iaj/
├── Main.java                          # Spring Boot main class
├── controller/
│   └── IncidentController.java        # REST API controller
├── service/
│   ├── IncidentAnalysisService.java   # Main orchestrator service
│   └── GeminiClient.java              # Gemini API client
├── model/
│   ├── IncidentRequest.java           # Request DTO
│   ├── IncidentResponse.java          # Response DTO
│   └── Hypothesis.java                # Hypothesis model
├── validation/
│   └── ResponseValidator.java         # Response validation
├── prompt/
│   └── PromptBuilder.java             # LLM prompt construction
└── context/
    └── SystemContext.java             # System knowledge and past incidents

Features

• Structured Pipeline: Clear separation of concerns with explicit stages
• Response Validation: Comprehensive JSON structure validation with detailed error messages
• Case-Insensitive Enum Handling: Supports both lowercase and uppercase severity values
• Error Handling: Proper HTTP status codes and descriptive error responses
• Logging: Debug-level logging for troubleshooting and monitoring
• Configuration: Environment-based configuration with YAML support
• Input Validation: Bean validation for request parameters

Testing

Run the unit tests:

mvn test

Dependencies

• Spring Boot 3.2.5
• Spring Web (REST API)
• Spring Validation (request validation)
• Jackson (JSON processing)
• Lombok (reduces boilerplate)
• Google Generative AI SDK (v1.51.0)