Soil Companion (chatbot)

Introduction

Overview and Scope

The Soil Companion is an AI chatbot developed in the SoilWise project. It provides an intelligent conversational interface through which users can explore European soil metadata, query global and country-specific soil data services, and receive answers grounded in the SoilWise knowledge repository.

The chatbot uses an agentic tool-calling approach: a large language model (LLM) autonomously decides which external data sources to consult for each question, executes the relevant tool calls, and synthesizes the results into a coherent response. Answers are enriched with auto-generated links to SoilWise vocabulary terms and Wikipedia articles. A sidebar Insight panel displays related SKOS vocabulary concepts and clickable chips that allow users to explore connected topics.

Intended Audience

The Soil Companion targets the following user groups:

• Soil scientists and researchers working with European soil health data and seeking catalogued knowledge, publications, and datasets from the SoilWise repository.
• Agricultural experts and extension officers looking for soil property data, field-level KPIs, and crop information to inform land management decisions.
• Students and educators exploring soil science concepts through a conversational interface that provides definitions, vocabulary hierarchies, and links to authoritative sources.
• Farmers and land managers (in selected regions) who want accessible field-level agricultural data such as crop history, soil physical properties, and greenness indices.

Key Features

The chatbot combines agentic LLM tool calling with retrieval-augmented generation and post-response enrichment to deliver grounded, linked answers. The key features are:

1. Agentic tool calling — The LLM autonomously decides which of the available tool integrations to invoke (catalog search, SoilGrids, AgroDataCube, Wikipedia, vocabulary SPARQL), executing up to 10 sequential tool-call iterations per query.
2. RAG from local core knowledge — Documents (PDF, text, Markdown) are split into chunks, embedded with a local model (AllMiniLmL6V2), and stored in memory. Relevant chunks are retrieved by cosine similarity and injected into the prompt.
3. Response enrichment — After the LLM generates a response, auto-linkers scan for vocabulary terms and Wikipedia article titles, inserting navigable links into the rendered output.
4. Insight panel — The frontend extracts SoilWise and Wikipedia links from responses and displays broader/narrower/related vocabulary concepts with definitions in a sidebar panel.
5. Token streaming — Responses are streamed token-by-token over WebSocket, giving users immediate visual feedback.
6. Feedback loop — Thumbs up/down ratings are logged to daily JSONL files; evaluation tools compute quality metrics (like rate, NSAT, Wilson lower bound).

Architecture

Technological Stack

Backend (JVM)

Frontend (Browser)

Infrastructure

Main Components Diagram

High-level component overview:

graph TD
    subgraph Browser ["Browser (Scala.js)"]
        App["SoilCompanionApp
- WebSocket client (real-time chat streaming)
- Authentication & session management
- Location picker (Leaflet map)
- Insight panel (vocabulary concepts, Wikipedia links)
- File upload, feedback, theme toggle"]
    end

    Browser -- "WebSocket + HTTP" --> Server

    subgraph Server ["SoilCompanionServer (Cask, JVM)"]
        direction TB
        Routes["Routes: /healthz, /readyz, /login, /logout, /session,
/subscribe/:id (WS), /query, /clear, /upload,
/feedback, /location, /vocab, /app/*"]

        subgraph Internal_Modules [" "]
            direction LR
            Config["Config
(PureConfig)"]
            Logger["Feedback
Logger"]
            SessMgmt["Session Management
(ConcurrentHashMaps)"]
        end

        subgraph Assistant ["Assistant (per session)"]
            AIServices["LangChain4j AiServices
- StreamingChatModel (OpenAI)
- ChatMemory (50 messages)
- RAG ContentRetriever (embeddings + local docs)
- Tool methods (5 integrations)"]
        end

        subgraph PostLinking ["(post-response linking)"]
            direction LR
            VL[VocabLinker]
            WL[WikipediaLinker]
        end
    end

    Server -- "HTTP calls" --> External

    subgraph External ["External Services"]
        direction TB
        E1["OpenAI API
(LLM, embed)"]
        E2["Solr
(catalog)"]
        E3["ISRIC SoilGrids v2.0
(global soil properties)"]
        E4["SoilWise
SPARQL"]
        E5["Wikipedia
(6 langs)"]
        E6["WUR AgroDataCube v2
(NL field data)"]
    end

    %% Styling
    style Browser fill:#f9f9f9,stroke:#333,stroke-width:2px
    style Server fill:#fff,stroke:#333,stroke-width:2px
    style External fill:#f9f9f9,stroke:#333,stroke-width:2px
    style Assistant fill:#fff,stroke:#333,stroke-dasharray: 5 5
    style Internal_Modules fill:none,stroke:none
    style PostLinking fill:none,stroke:none

Main Sequence Diagram

User query to response flow:

sequenceDiagram
    autonumber
    participant C as Client (Browser)
    participant S as Server (JVM)
    participant E as External APIs

    Note over C, S: Session Initialization
    C->>S: GET /session
    S-->>C: { sessionId: UUID }

    C->>S: WS /subscribe/:sessionId
    Note right of S: store connection
    S-->>C: connection established

    C->>S: POST /login
    Note right of S: validate credentials
    S-->>C: { ok: true }

    Note over C, S: Chat Interaction
    C->>S: POST /query
{ sessionId, content }

    S-->>C: QueryEvent("received")
    Note right of S: generate questionId
    S-->>C: QueryEvent("thinking")
    S-->>C: QueryEvent("retrieving_context")

    S->>E: RAG: embed query
    E-->>S: top-5 document chunks

    S->>E: LLM: evaluate tools (OpenAI)
    E-->>S: tool call decision

    S->>E: Tool: e.g. Solr search (Solr)
    E-->>S: search results

    S->>E: LLM: synthesize answer (OpenAI)
    E-->>S: token stream begins

    loop Token Streaming
        S-->>C: QueryPartialResponse(token)
    end

    Note right of S: stream complete
Apply VocabLinker
Apply WikipediaLinker

    S-->>C: QueryEvent("links_added", linkedResponse)
    S-->>C: QueryEvent("done")

    Note left of C: render markdown,
show feedback buttons

    C->>S: POST /feedback
{ questionId, vote }
    Note right of S: log to JSONL

Database Design

The Soil Companion does not use a traditional database. All runtime state is held in-memory; only feedback and application logs are persisted to disk.

In-memory state (per server process):

In-memory vector store:

Documents from the data/knowledge/ directory are loaded, split into 500-character chunks (100-character overlap), embedded using AllMiniLmL6V2, and stored at startup.

Persistent file storage:

Integrations & Interfaces

All external service credentials and endpoints are configured through HOCON (application.conf) with environment variable overrides.

HTTP endpoints exposed by the server:

WebSocket event types:

Key Architectural Decisions

Risks & Limitations