Add AI Assistant (Chatbot + Agent) to IPED

[gibi177]

Add AI Assistant (Chatbot + Agent) to IPED

Summary

This PR introduces a full-featured AI assistant module into IPED, enabling forensic investigators to interact with their cases using natural language. It encompasses ** ~160+ non-merge commits** across 98 files, contributed by 2 developers. The work builds on the upstream #2812_ai_assistant / #2641 foundations and extends them with a complete chatbot UI and an autonomous agent mode.

---

Features

1. AI Chatbot (Chatbot Mode)

A conversational AI assistant integrated into IPED's UI that allows investigators to select WhatsApp chat exports and ask natural-language questions. The LLM returns answers with clickable citations that navigate directly to referenced items in IPED's viewer.

• Single-chat workflow: sends raw HTML of one chat to the LLM
• Multi-chat workflow: adaptive three-path routing based on data volume:
  • Below chunk threshold -> raw HTML of all chats
  • Above threshold -> pre-computed AI summaries
  • Single chat -> direct HTML
• Multi-turn memory: conversation history is included in requests for contextual follow-ups
• Streaming responses with teletype animation (ChatStreamAnimator)
• Markdown rendering via AIMarkdownRenderer (supports code blocks, bold, italic, lists, links)
• Collapsible thinking blocks showing the model's reasoning process
• Conversation persistence: save/load conversations as JSON files, with sidebar management
• Context management: add items via right-click menu ("Add all highlighted/checked to AI context"), drag, or sidebar panel; clickable removal; context-edit locking after LLM response
• Citation navigation: clickable tokens in responses navigate to the referenced item in IPED

2. AI Agent (Agent Mode)

An autonomous AI agent that communicates with an external opencode CLI process via JSON-Lines over stdin/stdout. The agent has autonomous access to the IPED case through a MCP (Model Context Protocol).

Key differences from chatbot mode:

• The AI model runs outside IPED (external process)
• The model can autonomously decide to call IPED tools (search, bookmark, document access) without user prompting
• MCP Server (Python, in iped-app/resources/scripts/mcp/iped-mcp-server/) exposes IPED case data as callable tools:
  • list_sources, search, search_by_type, search_by_name
  • get_searchable_fields, get_document, get_document_text, read, read_batch
  • list_bookmarks, get_bookmark
• JVM Bridge via PyJnius to call IPED's Java API from the Python MCP server
• Session reuse across messages within the same conversation

Architecture

The new iped.app.ui.ai package follows a clean layered architecture:

iped/app/ui/ai/
  agent/                  # Agent mode (OpenCodeAgentService)
  backend/                # HTTP client + DTOs for chatbot backend (8 classes)
  context/                # Thread-safe context management (4 classes)
  controller/             # Main controller (AIAssistantController)
  documentation/          # Technical docs + sequence diagrams (5 HTML files)
  filters/                # AI filter tree (moved from ai/ root, 5 files)
  model/                  # Data models (5 classes)
  util/                   # Utilities (6 classes)
  view/                   # UI components (7 classes)

Minimal footprint on existing code: ~95% of changes are within the ai/ package. Existing files touched:

• App.java: AI assistant toolbar button + Ctrl+Shift+A shortcut
• MenuClass.java: "Add highlighted/checked to AI context" right-click menu items
• ViewerController.java: AI assistant button initialization
• UICaseDataLoader.java: AI task registration
• UiUtil.java: HTML utility enhancements for empty-view messages
• SummaryViewer.java: New viewer for AI summaries
• SimpleFilterNode.java: Support for AI summary filter icons
• ExtraProperties.java: New SUMMARY constant

---

Configuration

• IPEDConfig.txt: enableAISummarization = true/false
• AISummarizationConfig.txt: Remote service address, timeouts, chat analysis questions
• AIFiltersConfig.json: Added "Analyzed Chats" and "Summarized Chats" filter entries
• iped-mcp-server/.env: JVM heap size, JAVA_HOME override
• opencode.json: LLM provider configuration for agent mode (example provided)

Localization

All new strings localized in 6 languages:

• English (base), German (de_DE), Spanish (es_AR), French (fr_FR), Italian (it_IT), Portuguese (pt_BR)

Documentation

5 comprehensive HTML documentation files included:

• Chatbot Complete Technical Documentation.html - Full technical reference
• Chatbot Broader Project Report.html - Architecture, changes, and development journey
• Chatbot sequence diagrams.html - Mermaid sequence diagrams
• Agent Complete Technical Documentation.html - Full technical reference
• Agent sequence diagrams.html - Mermaid sequence diagrams

---

File Changes Summary

Category	Count	Description
New Java files	~40	AI module (backend, UI, context, agent, model, util)
New Python files	~8	MCP server
New config files	5	MCP configs, AI summarization configs
New resources	8	Icons (toolbar, filter), localization strings
Documentation	5	Technical docs + sequence diagrams
Modified existing	~10	App.java, MenuClass.java, ViewerController, UiUtil, etc.

---

Dependencies

• Backend service: The chatbot mode requires a running AI backend service (FastAPI). Configuration in AISummarizationConfig.txt
• opencode CLI: Agent mode requires opencode installed and accessible in PATH
• Python 3.10+: For the MCP server and AISummarizationTask
• PyJnius: For JVM bridge in the MCP server
• No changes to Maven dependencies or build configuration

---

Testing

• Backend HTTP client tested locally with FastAPI via Docker
• MCP server tools tested against processed IPED cases
• Chatbot multi-chat routing tested with single, summarized, and full chat scenarios
• Conversation persistence tested with save/load cycles
• UI tested across multiple chat switches, context modifications, and streaming scenarios

---

Notes for Reviewers

1. The ai/ filters package move (AIFiltersLoader, etc. from ai/ to ai/filters/) is a pure refactor with import updates
2. The MCP server is a standalone Python project bundled as a resource.
3. The opencode.json.example file should be copied to opencode.json by users configuring agent mode
4. Backend service availability: The chatbot feature depends on an external AI backend being accessible. The summarization task handles connection failures gracefully with configurable retry logic
5. The AI assistant button is always visible in the toolbar but the panel functionality is self-contained - no impact on existing workflows if the backend is unavailable

[lfcnassif]

Thank you very much @gibi177! This looks awesome!

But could you please base this PR on master branch? I see hundreds of commits here already merged on master, seems you based the PR on an outdated branch.

[gibi177]

Thank you, @lfcnassif! I've changed the base to master as requested. Hope it helps Sepinf in the future. It's been a pleasure to work on this project!