Skip to content

somtech-931/helpDeskAssistant

BranchesTags

Repository files navigation

_# Help Desk Assistant

Quickstart

  • This is a self-contained Spring AI application built on Spring Boot.
  • It has all dependent components wired up and can be started with 1 click.
  • Please create the .env file at the root location of the project and adjust the values as per your requirements or setup. Primarily we would need:
    • OPEN_AI API Key: Please put your OPEN_AI key in the .env file
    • mcp-servers.json replace the values like:
      • "", "", "" for Confluence MCP configuration
      • "": for the GITHUB MCP portion
    • the rest can stay as is.
  • Please have the compose.yaml file at the root location of your project startup and your Docker Desktop running when you start the application. This is required to start the Qdrant Vector Database as a docker container. During bootstrap the application tries to create this Vector DB container.
  • Please have a data directory created at the root of the project. The in-memory h2 db configured will use this to store the db values.
  • This is a gradle project and we used Java 24. Please have your project configured accordingly to download and use Java 24 or make necessary changes in the build.gradle "languageVersion = JavaLanguageVersion.of(24)" section to adapt to the Java version of your choice. N.B.: We cannot go down beyond Java 17.
  • Also we need to have gradle v 8.14 installed to run the project successfully.
  • Access the backend from the Browser:
  • There is a Conversation-ID field in the Swagger UI. This is primarily used for chat-memory purposes.
    • On starting a new conversation the Conversation-ID would be null or empty.
    • In the very first response the backend generates a Conversation-ID and sends it as part of the response.
    • We can use this generated Conversation-ID for all the future communication of that chat.
    • Once we are changing the topic, we can refresh and start again with a blank Conversation-ID - which will again start a new conversation.
    • All the conversations are stored in h2 database in a table called SPRING_AI_CHAT_MEMORY.
  • Once application is started we can see in Docker-desktop the required quadrant db container also coming up.

Project components:

  1. LLM Used: OPEN_AI

    • Requirements:
      • OPEN_AI API Key: We must generate and use our own OPEN_AI API Key for running this project
      • Here OPEN_AI has been used extensively for all the LLM related activities like embedding, completion etc.
      • There is also a scheme for using model of your choice with OLLAMA, however the results obtained with OPEN_AI far outweighed those with OLLAMA
      • So primarily OPEN_AI has been used for all LLM related activities.
      • Since this is just for demo purposes for the Innofest, it is somewhat ok to use OPEN_AI. However, we need to be careful about what documents and resources we are sharing since it is an external LLM. Of course if this is adopted in future we need to replace the OPEN_AI parts with one of our supported LLM Models like Gemma or Gemini.
      • The LLM related properties can be configured from the # OPENAI CONFIG # section in the .env file

  2. Retrieval Augment Generation (RAG)

    • We have used Qdrant as the Vector DB for our RAG purposes.
    • This Qdrant DB configurations are in the compose.yaml file present at the root of the location
    • There is a DocumentLoader.java class which has a method: loadRagMaterialsToVectorStore() We have a functionality during startup which chunks all documents from the resources/rag-materials folder and embeds them in the vector store during startup. Currently only .pdf files are supported. So whatever pdf files you put under that folder will be embedded.
    • Currently only 2 documents are added - which will be enough for demo purposes.
    • Since we are using OPEN_AI embedding, please be careful as not to use any company confidential docs.
    • The rag params are already tuned, if further tuning is required we can change those parameters in the .env files under: # RAG CONFIG # section.
    • Qdrant UI: http://localhost:6333/dashboard#/collections/knowledge-base
    • TheRAG Configurations can also be configured from the .env file from the # QDRANT VECTOR STORE # section.

  3. MCP Servers:

    • The mcp-servers.json have the details for configuring the required mcp-servers.
    • Currently only 2 MCP-Servers have been configured: confluence-mcp and github-mcp
    • Please configure the values accordingly for these servers to work, as mentioned in the Quickstart section.
    • Currently, a community supported Confluence MCP Server is used. The official ROVO MCP Server from Confluence requires paid version of Confluence.
    • For demo purposes, I have created a personal Confluence account (which will be expired by Jan 31 2026), and using this for quick prototyping.
    • The GitHub MCP Server is however the official integration. All we need to do is generate an access token for the GITHUB MCP and use it in mcp-servers.json
    • GITLAB MCP also supports only paid versions of GITLAB Enterprise, so currently kept out of scope.
    • mcp-servers-reference.json holds some reference configurations for other MCP Servers.
    • The MCP server properties can also be configured from the .env file from the # MCP CLIENT CONFIG # and # CONFLUENCE MCP SERVER CONFIGURATIONS # sections.

  4. Tools implementation:

    • The application supports LLM Tool Calling features.
    • There is a package named tools in the project where we have a class called HelpDeskIncidentTools.
    • 2 tools have been configured:
      • @Tool(name = "createIncident", description = "Create the HelpDesk Incident Ticket", returnDirect = true) : for creating HelpDesk Incident Tickets
      • @Tool(name = "getIncidentsForReporter", description = "Fetch entire Incident ticket(s) details based on reporter name") - for retrieval
      • We can add more tooling functionality in that same class, but we need to make the name and descriptions lucid enough for the LLM to discover and invoke them.
    • Currently, these tools simply make a call via the JpaRepository and interact with an in memory H2 database.
    • This in-memory database have been configured to hold the data even after the application stops. It makes all the entries in the chat_memory.mv.db under the data directory (mentioned as part of Quickstart). When the application starts it again reads all the data from that file and loads them in the h2 database automatically.
    • There is a table: help_desk_tickets which stores the created incident ticket details.
    • The schema can be found under the resources/chat-memory/schema folder.
    • In case we want a fresh start on an empty database, we can delete the chat_memory.mv.db file and then start the application.
    • H2 Console Login: http://localhost:8082/h2-console/test.do?jsessionid=20b32b08241f2df12e9bbabebda204 Creds: root/Admin_1234

  5. Chat Memory configurations:

    • The application manages chat memory using the Conversation-ID field.
    • When the application is first loaded the Conversation-ID field is empty.
    • When the first request is triggered the backend automatically generates a Conversation-ID and sends it as part of the response if the ID is null or empty
    • For subsequent requests we can send it as part of the request header.
    • All the chat memory configurations are also maintained in the H2 database.
    • There is a table called SPRING_AI_CHAT_MEMORY which holds the chat memory data.
    • The schema can be found under the resources/chat-memory/schema folder.

  6. Agentic AI Flow

    • The brain of the application for the Agentic AI flow is the system prompt defined as part of systemPromptTemplate.st under resources/promptTemplates folder.
    • The prompt defines all the intents, states and dictates all the Agentic AI workflow or behaviour for this backend.
    • Be careful, if we are changing anything in the systemPrompt.st file, since it affects the overall Agentic AI flow and functionality.

  7. Application specific

    • Since it is a locally running Spring Boot application, all configurations can be done via application.yaml file.
    • All properties of the application.yaml have been externalised to the .env file, so we need not hard code anything in application.yaml, we can simply make changes as per our requirements in the .env file as per our local setups.
    • There is a section in the .env file called # CUSTOM CONFIG #, where we can configure these application specific business logic properties.
    • We have 3 controller classes:
      • ChatClientControllerOpenAI: main controller exposing the chat API - talks to OPENAI LLM
      • ChatClientControllerOllama: controller for OLLAMA endpoints - talks to OLLAMA
        • currently the OLLAMA configurations are disabled by commenting out
        • the OLLAMA endpoints are disabled using @Hidden annotation. If we want to enable just remove the @Hidden annotation from line 34 of ChatClientControllerOllama class.
      • TestController: controller for individually testing the output of the above components in isolation.
        • there are curated prompts for all the specific functionality testing available under the resources\promptTemplates\test-template folder.

  8. Application Containerization: (NOT RECOMMENDED)

    • Some work has been done in containerizing this application.
      • Dockerfile is not used, I have been using Google jib plugin to generate the images
      • command: ./gradlew jibDockerbuild -Djib.to.image=/:
      • there is also a compose-bkp.yaml file which can be used to start the services as containers.
      • remember to do the following changes if you are using docker-containers
      • change the SPRING_PROFILES_ACTIVE=prod in .env and comment out
      • disable //developmentOnly 'org.springframework.boot:spring-boot-docker-compose' line 53 in build.gradle
      • MCP_STDIO_ENABLED=false
      • MCP_HTTP_ENABLED=false
      • comment out mcp configurations
      • VECTOR_DB_HOST=localhost --> qdrant in .env file line: 47,48
      • the UI can be accessed using these urls:
      • Swagger UI:http://localhost:8888/swagger-ui/index.html#/
      • Qdrant UI: http://localhost:6333/dashboard#/collections/knowledge-base
      • H2 Console: http://localhost:8888/h2-console Creds: root/Admin_1234
    • There are some challenges in containerizing the application.
      • the base docker image that jib is using does not have docker installed, so the the mcp servers - specially the github, which is configured to start with docker command cannot start up.
      • Also, we would need to use streamable-http support for MCP in place of stdio, which is still evolving in Spring Framework and has very esoteric configuration steps.
      • If we disable the MCP part and have only tools and RAG functionality then we can use the container approach also, but the MCP configurations are a bit difficult to handle so far.
      • Work was stopped in this containerization part, since our main idea was to demo an Agentic Flow, so more time was invested there, than already known solved problems like application packaging.
    • Docker-compose commands:
      • Start: docker compose -f compose-bkp.yaml up -d
      • Tear down: docker compose -f compose-bkp.yaml down -v

  9. Some handy useful commands:

  1. MCP Inspector

    • LLM models can only leverage the capabilities exposed by the MCP Server.
    • So if the MCP Server has some limitations, they cannot be handled out of the box by the LLM model.
    • That's why to make sure we are doing enough testing on the MCP Server capabilities and test all our requirements we can use the MCP inspector
    • Download MCP Inspector: https://github.com/modelcontextprotocol/inspector
    • Command to run: npx @modelcontextprotocol/inspector
    • MCP inspector UI will be automatically open up.
    • There we can provide the details of the MCP-Server that we are trying to test using exactly the same values from mcp-servers.json for that particular MCP server.
    • Once connected we can see the green button, and then we can click List Tools and test out the individual tool capabilities exposed by that MCP server and the input they are expecting.

  2. questions.txt

    • This contains some of the examples of user messages with which the Agentic AI application works the best.
    • Since we are deciding the intent based on a systemPrompt and do not have any fine-grained Intent detection module, so it will be better to use the messages as per the given examples.
    • Most important part for the intent detection is use of keywords like: "search Confluence" or "search Github" or "Create Help Desk Incident" etc. in the messages for the LLM to understand the user intent.
    • We can add more such questions in the questions.txt as per our use cases and can harden it further.
    • From the ICE Client UI mascot it would be nice if we can actually have a map where we have these kind of questions hard coded when user clicks on a button/link say for Confluence/GITHUB or Help Desk Incident creation.
    • We can use LLM to generate the intent also, but that would be a bit unreliable since if the LLM misses any of the keywords like Confluence or GITHUB or Help Desk etc. then the backend Agentic AI might not be able to detect the intent.
    • So for the demo purposes it would be ok to have a limited set of questions in a map and invoke the backend accordingly._

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages