{"id":31650254,"url":"https://github.com/kpavlov/koog-spring-boot-assistant","last_synced_at":"2026-05-06T10:39:52.378Z","repository":{"id":315889648,"uuid":"1056931395","full_name":"kpavlov/koog-spring-boot-assistant","owner":"kpavlov","description":"Kotlin + SpringBoot + Koog + Promptfoo example","archived":false,"fork":false,"pushed_at":"2026-05-01T17:40:52.000Z","size":2719,"stargazers_count":10,"open_issues_count":14,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T19:28:04.404Z","etag":null,"topics":["example","koog","kotlin","promptfoo","rag","spring-boot"],"latest_commit_sha":null,"homepage":"https://kpavlov.github.io/koog-spring-boot-assistant/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kpavlov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-15T03:49:09.000Z","updated_at":"2026-04-06T06:56:26.000Z","dependencies_parsed_at":"2025-10-25T08:20:07.118Z","dependency_job_id":"f3a5a730-13bd-4258-8112-10955ed8d8e3","html_url":"https://github.com/kpavlov/koog-spring-boot-assistant","commit_stats":null,"previous_names":["kpavlov/koog-spring-boot-assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kpavlov/koog-spring-boot-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fkoog-spring-boot-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fkoog-spring-boot-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fkoog-spring-boot-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fkoog-spring-boot-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kpavlov","download_url":"https://codeload.github.com/kpavlov/koog-spring-boot-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpavlov%2Fkoog-spring-boot-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32689655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["example","koog","kotlin","promptfoo","rag","spring-boot"],"created_at":"2025-10-07T08:11:36.564Z","updated_at":"2026-05-06T10:39:52.372Z","avatar_url":"https://github.com/kpavlov.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Koog Spring-Boot Elven Assistant\n\n[![Java CI with Maven](https://github.com/kpavlov/koog-spring-boot-assistant/actions/workflows/maven.yml/badge.svg?branch=main)](https://github.com/kpavlov/koog-spring-boot-assistant/actions/workflows/maven.yml)\n[![Node.js CI](https://github.com/kpavlov/koog-spring-boot-assistant/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/kpavlov/koog-spring-boot-assistant/actions/workflows/node.js.yml)\n\n[**WEB UI**](https://kpavlov.github.io/koog-spring-boot-assistant/)\n\n🎞️ Featuring in the [\"Testing Challenges in the Age of AI\"](https://www.youtube.com/watch?v=IwAsq3EfaC0) \nDevoxx Belgium 2025 talk\n - [Slides](https://speakerdeck.com/kpavlov/testing-challenges-in-the-age-of-ai-devoxx-dot-be-2025)\n\n## Overview\n\nAn AI-powered conversational assistant demonstrating \nthe [JetBrains Koog](https://github.com/jetbrains/koog) framework for building intelligent agents \nwith Kotlin and Spring Boot. \nThe application features an Elven-themed chatbot that combines RAG (Retrieval-Augmented Generation), \nsession persistence, and real-time WebSocket communication.\n\n**Key Features:**\n- 🤖 **AI Agent Workflow**: Multi-node execution graph with input moderation, LLM processing, and conditional routing\n- 💬 [**Interactive Chat UI**]((https://kpavlov.github.io/koog-spring-boot-assistant/)): Svelte-based web interface with real-time WebSocket messaging\n- 📚 **RAG System**: Vector-based knowledge retrieval from markdown documents\n- 🔍 **Observability**: Integrated OpenTelemetry tracing and metrics\n- 💾 **Session Management**: Persistent conversation state with checkpoint recovery\n\n**Testing:**\n- 🧪 **Fast and deterministic integration testing** with [Mokksy.dev](https://mokksy.dev). **Run them on the plane ✈️!!!**\n- 🧫 **Prompt Evaluation**: Promptfoo integration for testing and optimizing LLM prompts\n\n**Tech Stack:** Spring Boot 3.5 • Kotlin 2.2 • [JetBrains Koog](https://github.com/jetbrains/koog) • [Mokksy.dev](https://mokksy.dev)• WebFlux • Svelte, OpenAPI\n\n\u003cdiv style=\"max-height: 80vh; display: inline-flex\"\u003e\n\n[![screenshot-1.png](docs/screenshot-1.png)](https://kpavlov.github.io/koog-spring-boot-assistant/)\n\n\u003c/div\u003e\n\n\u003cdiv style=\"max-height: 80vh; display: inline-flex\"\u003e\n\n[![screenshot-2.png](docs/screenshot-2.png)](https://kpavlov.github.io/koog-spring-boot-assistant/)\n\n\u003c/div\u003e\n\n## Quickstart\n\nYou may find the instructions also on [**WEB UI**](https://kpavlov.github.io/koog-spring-boot-assistant/)\n\n### Prerequisites\n- Java 17+ (JDK). Using the same JDK as your IDE is recommended.\n- Maven 3.9+\n- macOS with Homebrew for installing optional tools (or install those tools manually on your platform).\n\n### 1) Create your environment file first\nThe project includes a template for environment variables.\n\n- Copy the template and edit values as needed:\n  ```shell\n  cp .env.template .env\n  ```\n- At minimum, ensure your OpenAI key is available to tools that read from `.env`.\n  In `.env` add: `OPENAI_API_KEY=sk-...`\n\n### 2) Define secrets in application properties\nThe Spring app reads secrets from `app/config/application.properties`.\n\n- Open app/config/application.properties and set your key(s), for example:\n    ```properties\n    OPENAI_API_KEY=sk-...\n    ```\n\u003csummary\u003e\n\u003cdescription\u003e\nNote: Do not commit real secrets.\n\u003c/description\u003e\nThe repo may contain a template, but ensure your local file is ignored by VCS.\n\nRun \n```shell\ngitleaks git .\n```\nor \n```shell\nmake no-leaks\n```\nto make sure your secrets are not gonna be commited.\n\u003c/summary\u003e\n\n### 3) Build the project with Maven\nBuild the Spring Boot application (module `app`) using Maven:\n\n```shell\nmvn clean package\n```\n\nThis will produce a runnable jar under `app/target/`.\n\n### 4) Run the project\n\nYou can run the app from your IDE (IntelliJ IDEA is recommended) or via Maven.\n\n- **Before opening a project in the IDE, please make sure you have generated sources and resources,\nlike API classes from OpenAPI, and `build-info.properties`:**\n    ```shell\n    mvn generate-resources\n    ```\n- IntelliJ IDEA: Open the project, select the `Application.kt` run configuration (module `app`), and Run.\n- Start server:\n  ```shell\n  mvn spring-boot:run -pl :app\n  ```\n  or\n  ```shell\n  make run\n  ``` \n\n- Open [Web UI](https://kpavlov.github.io/koog-spring-boot-assistant/).\n  To build and run it locally:\n    ```shell\n    cd chat-ui \u0026\u0026 npm run dev \n    ```\n    or\n    ```shell\n    make ui\n    ```\n\n### 5) Observability: run OpenTelemetry TUI\nUse the Makefile target to launch the [OpenTelemetry terminal UI (otel-tui)](https://github.com/ymtdzzz/otel-tui). \nThis target also cleans any process already bound to the default port.\n\n```shell\nmake otel\n``` \n\nTip: If you don't have the tool, run the `prepare` target first to install it.\n\n```shell\nmake prepare\n``` \n\n### 6) Evaluate prompts with Promptfoo\nPromptfoo commands are wrapped in Makefile targets and read environment from the `promptfoo/.env` file if present.\n\n- Start a continuous evaluation and write results to `promptfoo/output.yml`:\n\n    ```shell\n    make pf-e2e\n    ``` \n- Launch the Promptfoo UI to explore results:\n\n    ```shell\n    make pf-e2e-ui\n    ```\n\n## Troubleshooting\n- Ensure `OPENAI_API_KEY` is present in both `.env` (for tools) and `app/config/application.properties` (for the Spring app).\n- If Maven cannot find Java, confirm `JAVA_HOME` points to a JDK (not a JRE).\n- If otel-tui or promptfoo are missing, run `make prepare` (macOS/Homebrew) or install them manually.\n\n--- \n\n## Project Design\n\nThis project demonstrates an AI-powered conversational assistant built with Spring Boot and the [Koog](https://github.com/kpavlov/koog) framework. The design follows a modular architecture with clear separation of concerns.\n\n### Architecture Overview\n\nThe application consists of three main layers:\n\n1. **API Layer** (`app/src/main/kotlin/com/example/app/api/`)\n   - REST endpoints defined via OpenAPI specification (`docs/openapi.yaml`)\n   - Controllers implement generated API interfaces\n   - Reactive endpoints using Spring WebFlux with Kotlin coroutines\n\n2. **Agent Layer** (`app/src/main/kotlin/com/example/app/agents/`)\n   - **ElvenAgent**: Core AI agent orchestrating LLM interactions\n   - Uses Koog framework's agentic workflow with:\n     - Input moderation via OpenAI's Moderation API\n     - RAG (Retrieval-Augmented Generation) for context-aware responses\n     - Session persistence and checkpoint recovery\n   - Implements multi-node execution strategy with conditional routing\n\n3. **Infrastructure Layer**\n   - **RAG Configuration**: Vector embeddings for knowledge base search\n   - **Prompt Management**: Template-based prompts loaded from filesystem\n   - **Observability**: OpenTelemetry integration for tracing and metrics\n\n### Key Components\n\n#### AI Agent Workflow\nThe agent implements a node-based execution graph with tool calling capabilities:\n\n```mermaid\n---\ntitle: streaming-strategy\n---\nstateDiagram\n    state \"moderate-input\" as moderate_input\n    state \"mapStringToRequests\" as mapStringToRequests\n    state \"applyRequestToSession\" as applyRequestToSession\n    state \"nodeStreaming\" as nodeStreaming\n    state \"executeMultipleTools\" as executeMultipleTools\n    state \"mapToolCallsToRequests\" as mapToolCallsToRequests\n\n    [*] --\u003e moderate_input : transformed\n    moderate_input --\u003e mapStringToRequests : transformed\n    moderate_input --\u003e [*] : transformed\n    mapStringToRequests --\u003e applyRequestToSession\n    applyRequestToSession --\u003e nodeStreaming\n    nodeStreaming --\u003e executeMultipleTools : onCondition\n    nodeStreaming --\u003e [*] : onCondition\n    executeMultipleTools --\u003e mapToolCallsToRequests\n    mapToolCallsToRequests --\u003e applyRequestToSession\n```\n\n#### RAG System\n- Knowledge base: Markdown files in `app/data/knowledge/`\n- Embedding storage: JVM-based vector store\n- Retrieves top 3 relevant documents per query\n- Uses OpenAI's `text-embedding-3-small` model\n\n#### Prompt Templates\n- Stored in `app/data/prompt-templates/`\n- Versioned templates (e.g., `elven-assistant/system/latest.md`)\n- Loaded dynamically via `JVMFilePromptTemplateProvider`\n\n#### Session Management\n- Persistent conversation state\n- Automatic checkpoint creation\n- Message history preservation on restore\n- Storage path: `./target/tmp/session-store`\n\n### Technology Stack\n- **Framework**: Spring Boot 3.5.6 with WebFlux\n- **Language**: Kotlin 2.2.20\n- **AI Framework**: Koog 0.5.0-rc\n- **LLM Provider**: OpenAI (GPT-4 Mini for cost optimization)\n- **Build Tool**: Maven 3.9+\n- **Observability**: OpenTelemetry, Micrometer\n- **Testing**: Kotest, MockK, AI-Mocks (mokksy)\n\n### Design Patterns\n- **Code Generation**: OpenAPI → Kotlin Spring interfaces\n- **Dependency Injection**: Spring's constructor-based injection\n- **Reactive Programming**: Kotlin coroutines with WebFlux\n- **Feature Composition**: Koog's plugin system (Persistence, OpenTelemetry, Tracing)\n- **DSL Builders**: Fluent prompt and agent configuration\n\n## Useful paths\n- Application entry point: [Application.kt](app/src/main/kotlin/com/example/app/Application.kt)\n- AI Agent: [ElvenAgent.kt](app/src/main/kotlin/com/example/app/agents/ElvenAgent.kt)\n- REST Controller: [ChatController.kt](app/src/main/kotlin/com/example/app/api/ChatController.kt)\n- Spring config: [application.yml](app/src/main/resources/application.yml)\n- External properties: [application.properties](app/config/application.properties)\n- OpenAPI spec: [openapi.yaml](docs/openapi.yaml)\n- Knowledge base: [app/data/knowledge/](app/data/knowledge/)\n- Prompt templates: [app/data/prompt-templates/](app/data/prompt-templates/)\n- Prompt scenarios: [scenarios](promptfoo/scenarios)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpavlov%2Fkoog-spring-boot-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkpavlov%2Fkoog-spring-boot-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpavlov%2Fkoog-spring-boot-assistant/lists"}