Skip to content
Back to search

eddi

Config-driven engine that turns JSON into production-grade AI agents. Multi-agent orchestration, 12+ LLM providers, MCP/A2A protocols, RAG, persistent memory, and enterprise compliance (EU AI Act, GDPR, HIPAA). Built on Quarkus.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/labsai/eddi with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/labsai/eddi'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/labsai--eddi/badge.svg)](/listings/labsai--eddi)

HTML

<a href="/listings/labsai--eddi"><img src="/api/listings/labsai--eddi/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

The fastest way to get EDDI running is the **one-command installer**. It sets up EDDI + your choice of database via Docker Compose and points you at the dashboard, where the **Platform Operator** (or the form-based agent wizard) creates your first AI agent for you.

**Linux / macOS / WSL2:**

curl -fsSL https://raw.githubusercontent.com/labsai/EDDI/main/install.sh | bash

**Windows (PowerShell):**

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/labsai/EDDI/main/install.ps1" -OutFile "install.ps1"
Unblock-File .\install.ps1
.\install.ps1

Requires [Docker](https://docs.docker.com/get-docker/). The wizard auto-generates a unique vault encryption key for secret management.

Everything is served from one port: `http://localhost:7070` opens a chooser between the **Manager** (`/manage`, the admin dashboard) and the **Workforce** workspace (`/workforce`, group conversations), and the standalone chat UI is at `/chat`. See [Getting Started](docs/getting-started.md).

<details> <summary><strong>๐Ÿ”ง Installer options</strong></summary>

bash install.sh --defaults                 # All defaults, no prompts
bash install.sh --db=postgres --with-auth  # PostgreSQL + Keycloak
bash install.sh --full                     # Everything enabled (PostgreSQL + auth + monitoring)
bash install.sh --local                    # Build Docker image from local source
bash install.sh --eddi-version=6.5.0       # Pin a release (image and compose files from its tag)
bash install.sh --dry-run                  # Show the image tag and the git ref the files come from

With the default `latest` image, the compose files are downloaded from the newest release's tag (looked up through the GitHub API), not from `main`.

The `--local` flag is for contributors testing pre-release builds:

./mvnw package -DskipTests    # Build the Java app
bash install.sh --local        # Build Docker image + start containers

</details>

๐Ÿ”„ Updating

The installer creates an `eddi` CLI wrapper that makes updating easy:

eddi update

This pulls the latest Docker image from the registry and restarts the containers. It works even when the same tag (e.g. `latest`) was re-published โ€” Docker always checks the remote digest for changes.

> **Upgrading across releases?** Read the upgrade guide first: [Upgrading from 6.4](docs/upgrading-from-6.4.md) lists what an existing deployment must change, because several defaults now fail closed (a Keycloak realm imported from 6.1โ€“6.4 needs a repair that re-running the installer applies and `eddi update` does not). A database that comes from EDDI 5 starts with [Upgrading from 5.x](docs/upgrading-from-5x.md).

> **`eddi` command not found?** The CLI lives at `~/.eddi/eddi` (Linux/macOS) or `~/.eddi/eddi.cmd` (Windows). Either restart your terminal so the PATH takes effect, or use the full path: > > ```bash > # Linux / macOS > ~/.eddi/eddi update > > # Windows (PowerShell) > & "$HOME\.eddi\eddi.cmd" update > ```

<details> <summary><strong>Manual update (without the CLI)</strong></summary>

If the `eddi` CLI isn't available, run the equivalent docker commands from your install directory (`~/.eddi` by default):

cd ~/.eddi
docker compose --env-file .env -f docker-compose.yml pull
docker compose --env-file .env -f docker-compose.yml up -d

Adjust the `-f` flags to match your setup (e.g. add `-f docker-compose.auth.yml` if using Keycloak).

</details>

๐Ÿณ Docker Compose (Manual)

If you prefer manual control over Docker Compose:

# Default (EDDI + MongoDB)
docker compose up

# PostgreSQL instead of MongoDB โ€” a complete stack, so it is NOT layered on
# docker-compose.yml (an overlay cannot un-declare the base's mongodb service).
# The database password has no default; keep the value stable across runs
# (install.sh --db=postgres generates one into .env for you)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json ยท Manifest ยท 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "eddi",
  3. "description": "Claude Code plugins for working with an EDDI server.",
  4. "owner": {
  5. "name": "EDDI contributors",
  6. "url": "https://github.com/labsai/EDDI"
  7. },
  8. "plugins": [
  9. {
  10. "name": "eddi",
  11. "source": "./integrations/claude-plugin",
  12. "description": "Skills for using and administering an EDDI server through its MCP tools."
  13. }
  14. ]
  15. }
README.md ยท README ยท 740 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ![EDDI Banner Image](/screenshots/EDDI-Readme-banner-image.webp)
  2. # E.D.D.I โ€” Multi-Agent Orchestration Middleware for Conversational AI
  3. [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12355/badge?v=2)](https://www.bestpractices.dev/projects/12355) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/labsai/EDDI/badge)](https://securityscorecards.dev/viewer/?uri=github.com/labsai/EDDI) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/2c5d183d4bd24dbaa77427cfbf5d4074)](https://app.codacy.com/organizations/gh/labsai/dashboard?utm_source=github.com&utm_medium=referral&utm_content=labsai/EDDI&utm_campaign=Badge_Grade)
  4. [![CI](https://github.com/labsai/EDDI/actions/workflows/ci.yml/badge.svg)](https://github.com/labsai/EDDI/actions/workflows/ci.yml) [![CodeQL](https://github.com/labsai/EDDI/actions/workflows/codeql.yml/badge.svg)](https://github.com/labsai/EDDI/actions/workflows/codeql.yml) ![Tests](https://img.shields.io/badge/tests-20%2C000%2B-brightgreen) ![Coverage](https://img.shields.io/badge/coverage-%3E90%25%20instr%20%2F%20%3E80%25%20branch-brightgreen)
  5. [![Docker Pulls](https://img.shields.io/docker/pulls/labsai/eddi)](https://hub.docker.com/r/labsai/eddi) [![Latest Release](https://img.shields.io/github/v/release/labsai/EDDI?label=latest&color=blue)](https://github.com/labsai/EDDI/releases) [![Repository: AI Ready](https://img.shields.io/badge/Repository-AI_Ready-blueviolet?logo=robot)](AGENTS.md)
  6. **E.D.D.I** (Enhanced Dialog Driven Interface) is a production-grade, **config-driven multi-agent orchestration middleware** for conversational AI. It coordinates users, AI agents, and business systems through **intelligent routing, persistent memory, and API orchestration** โ€” without writing code.
  7. Built with **Java 25** and **Quarkus**. Ships as a **Red Hat-certified Docker image** with the **Manager dashboard and Chat UI built in**. Selected as a **UNIDO Trusted Partner** for Industrial AI. Native support for **MCP** (Model Context Protocol), **A2A** (Agent-to-Agent), the **OpenAI Chat Completions API**, **Slack**, **OpenAPI**, and **OAuth 2.0**.
  8. [Website](https://eddi.technology/) ยท [Documentation](https://docs.labs.ai/) ยท License: Apache 2.0
  9. ---
  10. ## ๐Ÿ“‘ Table of Contents
  11. - [๐Ÿ Quick Start](#-quick-start)
  12. - [๐Ÿ’ก Why EDDI?](#-why-eddi)
  13. - [๐Ÿ“ธ See It In Action](#-see-it-in-action)
  14. - [โœจ Features](#-features)
  15. - [๐Ÿ“– Documentation](#-documentation)
  16. - [๐Ÿ“‹ Compliance & Privacy](#-compliance--privacy)
  17. - [๐Ÿ—๏ธ Development](#๏ธ-development)
  18. - [Prerequisites](#prerequisites)
  19. - [Quarkus Dev Mode](#quarkus-dev-mode)
  20. - [Maven Command Reference](#maven-command-reference)
  21. - [Build & Docker](#build--docker)
  22. - [Kubernetes](#๏ธ-kubernetes)
  23. - [๐Ÿค Contributing](#-contributing)
  24. - [๐Ÿ”’ Security](#-security)
  25. - [๐Ÿ“œ Code of Conduct](#-code-of-conduct)
  26. ---
  27. ## ๐Ÿ Quick Start
  28. The fastest way to get EDDI running is the **one-command installer**. It sets up EDDI + your choice of database via Docker Compose and points you at the dashboard, where the **Platform Operator** (or the form-based agent wizard) creates your first AI agent for you.
  29. **Linux / macOS / WSL2:**
  30. ```bash
  31. curl -fsSL https://raw.githubusercontent.com/labsai/EDDI/main/install.sh | bash
  32. ```
  33. **Windows (PowerShell):**
  34. ```powershell
  35. Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/labsai/EDDI/main/install.ps1" -OutFile "install.ps1"
  36. Unblock-File .\install.ps1
  37. .\install.ps1
  38. ```
  39. Requires [Docker](https://docs.docker.com/get-docker/). The wizard auto-generates a unique vault encryption key for secret management.
  40. Everything is served from one port: `http://localhost:7070` opens a chooser between the **Manager** (`/manage`, the admin dashboard) and the **Workforce** workspace (`/workforce`, group conversations), and the standalone chat UI is at `/chat`. See [Getting Started](docs/getting-started.md).
  41. <details>
  42. <summary><strong>๐Ÿ”ง Installer options</strong></summary>
  43. ```bash
  44. bash install.sh --defaults # All defaults, no prompts
  45. bash install.sh --db=postgres --with-auth # PostgreSQL + Keycloak
  46. bash install.sh --full # Everything enabled (PostgreSQL + auth + monitoring)
  47. bash install.sh --local # Build Docker image from local source
  48. bash install.sh --eddi-version=6.5.0 # Pin a release (image and compose files from its tag)
  49. bash install.sh --dry-run # Show the image tag and the git ref the files come from
  50. ```
  51. PowerShell equivalents (`install.ps1`):
  52. ```powershell
  53. .\install.ps1 -Defaults # All defaults, no prompts
  54. .\install.ps1 -Database postgres -WithAuth # PostgreSQL + Keycloak
  55. .\install.ps1 -Full # Everything enabled
  56. .\install.ps1 -Local # Build Docker image from local source (run from a repo checkout, after .\mvnw.cmd package -DskipTests)
  57. .\install.ps1 -DryRun # Show what would be done
  58. ```
  59. With the default `latest` image, the compose files are downloaded from the newest
  60. release's tag (looked up through the GitHub API), not from `main`.
  61. The `--local` flag is for contributors testing pre-release builds:
  62. ```bash
  63. ./mvnw package -DskipTests # Build the Java app
  64. bash install.sh --local # Build Docker image + start containers
  65. ```
  66. </details>
  67. ### ๐Ÿ”„ Updating
  68. The installer creates an `eddi` CLI wrapper that makes updating easy:
  69. ```bash
  70. eddi update
  71. ```
  72. This pulls the latest Docker image from the registry and restarts the containers. It works even when the same tag (e.g. `latest`) was re-published โ€” Docker always checks the remote digest for changes.
  73. > **Upgrading across releases?** Read the upgrade guide first: [Upgrading from 6.5](docs/upgrading-from-6.5.md) covers a 6.5 deployment moving to 6.6 or 6.7, and [Upgrading from 6.4](docs/upgrading-from-6.4.md) lists what an existing deployment must change, because several defaults now fail closed (a Keycloak realm imported from 6.1โ€“6.4 needs a repair that re-running the installer applies and `eddi update` does not). A database that comes from EDDI 5 starts with [Upgrading from 5.x](docs/upgrading-from-5x.md).
  74. > **`eddi` command not found?** The CLI lives at `~/.eddi/eddi` (Linux/macOS) or `~/.eddi/eddi.cmd` (Windows). Either restart your terminal so the PATH takes effect, or use the full path:
  75. >
  76. > ```bash
  77. > # Linux / macOS
  78. > ~/.eddi/eddi update
  79. >
  80. > # Windows (PowerShell)
  81. > & "$HOME\.eddi\eddi.cmd" update
  82. > ```
  83. <details>
  84. <summary><strong>Manual update (without the CLI)</strong></summary>
  85. If the `eddi` CLI isn't available, run the equivalent docker commands from your install directory (`~/.eddi` by default):
  86. ```bash
  87. cd ~/.eddi
  88. docker compose --env-file .env -f docker-compose.yml pull
  89. docker compose --env-file .env -f docker-compose.yml up -d
  90. ```
  91. Adjust the `-f` flags to match your setup (e.g. add `-f docker-compose.auth.yml` if using Keycloak).
  92. </details>
  93. ### ๐Ÿณ Docker Compose (Manual)
  94. If you prefer manual control over Docker Compose:
  95. ```bash
  96. # Default (EDDI + MongoDB)
  97. docker compose up
  98. # PostgreSQL instead of MongoDB โ€” a complete stack, so it is NOT layered on
  99. # docker-compose.yml (an overlay cannot un-declare the base's mongodb service).
  100. # The database password has no default; keep the value stable across runs
  101. # (install.sh --db=postgres generates one into .env for you)
  102. POSTGRES_PASSWORD=$(openssl rand -base64 24) docker compose -f docker-compose.postgres-only.yml up
  103. # With Keycloak authentication. No realm account ships a password (see the
  104. # header of docker-compose.auth.yml, or let install.sh --with-auth set one)
  105. docker compose -f docker-compose.yml -f docker-compose.auth.yml up
  106. # With Prometheus + Grafana monitoring
  107. docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up
  108. # With a local LLM โ€” Ollama on the same Docker network, reachable as
  109. # http://ollama:11434 (no host.docker.internal needed)
  110. docker compose -f docker-compose.yml -f docker-compose.ollama.yml up -d
  111. # The same local LLM, on the host's NVIDIA GPUs โ€” layered on the Ollama overlay
  112. # above, never instead of it (all it adds is `gpus: all`)
  113. docker compose -f docker-compose.yml -f docker-compose.ollama.yml \
  114. -f docker-compose.ollama-nvidia.yml up -d
  115. # Auth + monitoring + NATS together (overlays stack in any combination)
  116. docker compose -f docker-compose.yml -f docker-compose.auth.yml \
  117. -f docker-compose.monitoring.yml -f docker-compose.nats.yml up
  118. # A cluster: three EDDI replicas behind a round-robin load balancer, a
  119. # three-node NATS JetStream cluster and MongoDB โ€” a whole stack, run on its own
  120. EDDI_VAULT_MASTER_KEY=$(openssl rand -base64 24) MONGO_PASSWORD=$(openssl rand -base64 24) NATS_PASSWORD=$(openssl rand -base64 24) \
  121. docker compose -f docker-compose.cluster.yml up -d
  122. ```
  123. Available compose overlays: `docker-compose.auth.yml` (Keycloak), `docker-compose.monitoring.yml` (Prometheus+Grafana), `docker-compose.nats.yml` (cluster mode with one replica and one NATS server), `docker-compose.ollama.yml` (local LLM; add `docker-compose.ollama-nvidia.yml` on top for NVIDIA GPU access), `docker-compose.chroma.yml` (vector store), `docker-compose.mcp-sidecar.yml` (reach a stdio-only MCP server through a bridge sidecar โ€” read the [MCP Client](docs/mcp-client.md#stdio-servers-via-a-bridge-sidecar) guide first), `docker-compose.local.yml` (build from source). `docker-compose.postgres-only.yml` is a complete standalone stack rather than an overlay โ€” use it on its own, not with `-f docker-compose.yml`; so is `docker-compose.openwebui.yml`, a runnable [Open WebUI](docs/open-webui-integration.md) demo of the OpenAI-compatible API, and `docker-compose.cluster.yml`, the multi-replica stack above (see [Clustering](docs/clustering.md)).
  124. The compose files publish EDDI (and Keycloak) on `127.0.0.1` only. To reach them from another host, set `EDDI_BIND=0.0.0.0` (and `KEYCLOAK_BIND` for Keycloak) in `.env` โ€” with authentication on.
  125. The Ollama overlay pulls `llama3.2:3b` on first start and keeps models in a named volume; override with `OLLAMA_PULL_MODEL=qwen3:4b`, or set it empty to skip the pull. It also sets `EDDI_OLLAMA_DEFAULT_BASE_URL`, so the agent wizard and the setup API pre-fill a base URL that resolves from inside the container โ€” the one thing that trips up every first local-LLM agent, because `localhost` there is the container, not the host.
  126. `docker-compose.ollama-nvidia.yml` adds GPU access to that Ollama and needs two things of the host, neither of which it degrades gracefully without: **Docker Compose 2.30.0 or newer**, which is where the `gpus` service attribute was introduced โ€” older versions fail on it, so check `docker compose version` โ€” and the **NVIDIA Container Toolkit** configured as a Docker runtime. `gpus: all` is a device *request*: with no GPU driver registered, the daemon cannot satisfy it and the container fails to start (`could not select device driver "" with capabilities: [[gpu]]`) rather than quietly falling back to the CPU. If you want Ollama on the CPU, leave this overlay off.
  127. ```bash
  128. docker pull labsai/eddi # Pull latest from Docker Hub
  129. ```
  130. โ†’ [hub.docker.com/r/labsai/eddi](https://hub.docker.com/r/labsai/eddi)
  131. ---
  132. ## ๐Ÿ’ก Why EDDI?
  133. Most multi-agent frameworks (LangGraph, CrewAI, AutoGen) are Python/Node libraries โ€” great for prototyping, hard to govern in production. EDDI approaches from the opposite direction: **a deterministic engine built to safely govern non-deterministic AI.**
  134. | Dimension | Typical Python/Node Frameworks | EDDI |
  135. | ------------------ | ---------------------------------------- | --------------------------------------------------------------------------- |
  136. | **Concurrency** | GIL or single-threaded event loop | Java 25 Virtual Threads โ€” true OS-level parallelism |
  137. | **Agent Logic** | Embedded in application code | Versioned JSON configurations โ€” update behavior without redeployment |
  138. | **Security Model** | Often relies on sandboxed code execution | No dynamic code execution at all; envelope-encrypted vault, SSRF protection |
  139. | **Compliance** | Requires custom implementation | GDPR, HIPAA, EU AI Act infrastructure built-in |
  140. | **Audit Trail** | Application-level logging | HMAC-SHA256 immutable ledger with cryptographic agent signing |
  141. | **Deployment** | pip/npm + manual infrastructure | One-command Docker install, Kubernetes/OpenShift-ready |
  142. > _"The engine is strict so the AI can be creative."_ โ€” [Project Philosophy](docs/project-philosophy.md)
  143. ---
  144. ## ๐Ÿ“ธ See It In Action
  145. <table>
  146. <tr>
  147. <td width="50%">
  148. <p align="center"><strong>๐Ÿ“Š Dashboard</strong></p>
  149. <img src="screenshots/eddi-v6-screenshot-dashboard-1.png" alt="EDDI Dashboard" />
  150. <p><em>Platform overview with active agents, workflows, quick actions, and recent conversations</em></p>
  151. </td>
  152. <td width="50%">
  153. <p align="center"><strong>๐Ÿค– Agent Fleet</strong></p>
  154. <img src="screenshots/eddi-v6-screenshot-agents-1.png" alt="Agents List" />
  155. <p><em>All deployed agents at a glance with status, descriptions, and one-click chat</em></p>
  156. </td>
  157. </tr>
  158. <tr>
  159. <td width="50%">
  160. <p align="center"><strong>๐Ÿ’ฌ Live Conversation</strong></p>
  161. <img src="screenshots/eddi-v6-screenshot-conversation-1.png" alt="Conversation View" />
  162. <p><em>Real-time conversation with visible actions, step timing, and tool calls</em></p>
  163. </td>
  164. <td width="50%">
  165. <p align="center"><strong>๐Ÿ—ฃ๏ธ Multi-Agent Debate</strong></p>
  166. <img src="screenshots/eddi-v6-screenshot-group-conversations-1.png" alt="Group Conversations" />
  167. <p><em>Peer Review with phased discussion: Opinion โ†’ Critique โ†’ Revision โ†’ Synthesis</em></p>
  168. </td>
  169. </tr>
  170. <tr>
  171. <td width="50%">
  172. <p align="center"><strong>๐Ÿ›ก๏ธ Secrets Vault</strong></p>
  173. <img src="screenshots/eddi-v6-screenshot-secret-vault-1.png" alt="Secrets Vault" />
  174. <p><em>Envelope-encrypted secrets with rotation tracking, checksums, and per-agent access control</em></p>
  175. </td>
  176. <td width="50%">
  177. <p align="center"><strong>๐Ÿ’ฐ Tenant Quotas</strong></p>
  178. <img src="screenshots/eddi-v6-screenshot-quotas-1.png" alt="Tenant Quotas" />
  179. <p><em>Rate limits, cost budgets, and live usage monitoring per tenant</em></p>
  180. </td>
  181. </tr>
  182. </table>
  183. <details>
  184. <summary><strong>More screenshots: LLM Config, Logs, User Memory, Schedules, Agent Detail</strong></summary>
  185. <table>
  186. <tr>
  187. <td width="50%">
  188. <p align="center"><strong>โšก LLM Task Configuration</strong></p>
  189. <img src="screenshots/eddi-v6-screenshot-agents-llm-config-1.png" alt="LLM Configuration" />
  190. <p><em>System prompt, model parameters, cascading, RAG, context window, and budget settings</em></p>
  191. </td>
  192. <td width="50%">
  193. <p align="center"><strong>๐Ÿ“‹ Real-Time Logs</strong></p>
  194. <img src="screenshots/eddi-v6-screenshot-logs-1.png" alt="Logs" />
  195. <p><em>Live log stream with per-call cost tracking, token counts, warnings, and errors</em></p>
  196. </td>
  197. </tr>
  198. <tr>
  199. <td width="50%">
  200. <p align="center"><strong>๐Ÿง  Persistent User Memory</strong></p>
  201. <img src="screenshots/eddi-v6-screenshot-user-data-1.png" alt="User Data" />
  202. <p><em>Cross-session memory with categorized entries, visibility scoping, and conflict detection</em></p>
  203. </td>
  204. <td width="50%">
  205. <p align="center"><strong>โฐ Scheduled Execution</strong></p>
  206. <img src="screenshots/eddi-v6-screenshot-schedules-1.png" alt="Schedules" />
  207. <p><em>Cron jobs and heartbeats with fire history, retry logic, and dead-letter tracking</em></p>
  208. </td>
  209. </tr>
  210. <tr>
  211. <td width="50%">
  212. <p align="center"><strong>๐Ÿ”ง Agent Detail</strong></p>
  213. <img src="screenshots/eddi-v6-screenshot-agents-detail-1.png" alt="Agent Detail" />
  214. <p><em>Full agent config: environments, workflows, A2A, security, capabilities, and memory policy</em></p>
  215. </td>
  216. <td width="50%">
  217. </td>
  218. </tr>
  219. </table>
  220. </details>
  221. ---
  222. ## โœจ Features
  223. ### ๐Ÿค– Multi-Agent Orchestration
  224. - ๐Ÿ”€ **Intelligent Routing** โ€” Direct conversations to different agents based on context, rules, and intent
  225. - ๐Ÿ—ฃ๏ธ **Group Conversations** โ€” Multi-agent debates with 7 built-in discussion styles: Round Table, Peer Review, Devil's Advocate, Delphi, Debate, Task Force, and Negotiation
  226. - ๐Ÿ”„ **Follow-up & Continue** โ€” After a group discussion completes, follow up with any specific member agent or continue all phases with a new question โ€” agents retain full context across rounds
  227. - ๐Ÿ’ฌ **Slack Integration** โ€” Deploy agents to Slack channels and run multi-agent debates directly in threads
  228. - ๐Ÿช† **Nested Groups** โ€” Compose groups of groups for tournament brackets, red-team vs blue-team, and panel reviews
  229. - ๐Ÿค– **Dynamic Agents** โ€” Create, recruit, and delegate to new agents at runtime during group discussions with configurable guardrails
  230. - ๐Ÿ—ณ๏ธ **Group Voting** โ€” `VOTE` phases collect explicit ballots (majority or approval, weighted, quorum-gated) and record a decision with the full tally, the raw ballots, and the losing side's dissents
  231. - ๐Ÿ“‹ **Shared Artifacts** โ€” A blackboard members co-edit through tools, with compare-and-set concurrency and declarative JSON-Schema, regex, or max-length validators โ€” never an LLM merge
  232. - ๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ **Humans as Members** โ€” A person can hold a seat in the group: their turn pauses the discussion until they answer, or the configured timeout policy resolves it
  233. - ๐ŸŽš๏ธ **Facilitator** โ€” An optional facilitator agent is briefed at checkpoints and picks one move from a config-enumerated list (end, extend, call a vote, recruit, escalate) โ€” bounded adaptation, never free-form orchestration
  234. - ๐Ÿค **Negotiation** โ€” Typed two-party bargaining: positions โ†’ proposals โ†’ a quoted concession ledger โ†’ signed acceptances, with arbitration skipped once agreement is reached
  235. - ๐ŸŽฏ **Bid-Based Assignment** โ€” Contract-Net-lite task auctions: eligible members bid blind in parallel, highest confidence wins, with deterministic tie-break and fallback to role assignment
  236. - ๐ŸŽ“ **Team Memory** โ€” A `RETRO` phase distils lessons into team-owned group memory, so they surface in every member's later discussions โ€” institutional knowledge that compounds run over run
  237. - ๐Ÿข **Standing Teams** โ€” A persistent workspace per group: a backlog that survives between discussions, cron cadences that pull from it, cross-run retry of unverified work, and running team metrics
  238. - ๐Ÿ“ฆ **Preset Group Templates** โ€” Five packaged, validated group configs (research pod, editorial team, ops task force, decision board, negotiation table) โ€” instantiate by assigning agents to named roles, not by hand-writing phases
  239. - ๐Ÿ“Š **Discussion Overview** โ€” The Manager and the Workforce board render a running discussion as a phase rail, a members ร— phases matrix, and a roster of one-line member stances, updated live ([details](docs/group-conversations.md#member-stances-the-overview-dashboard))
  240. - ๐Ÿ‘ฅ **Managed Conversations** โ€” Intent-based auto-routing with one conversation per user per intent ([details](docs/managed-agents.md))
  241. - ๐ŸŽฏ **Capability Matching** โ€” Discover and route to agents by skill, confidence score, and custom attributes
  242. - ๐Ÿง™ **Platform Operator** โ€” Meta-agent that reads and operates the deployment โ€” including creating other agents โ€” with every write behind a human approval gate ([how it works](docs/architecture.md#case-study-the-platform-operator))
  243. - ๐Ÿ” **Agent Version Following** โ€” Running conversations move to a newer agent version only when its author saved it as *compatible*; every other save is a breaking change, and the Manager previews what a deployment does to live conversations ([details](docs/deployment-management-of-agents.md#running-conversations-and-new-agent-versions))
  244. ### ๐Ÿง  LLM Provider Support (19 Providers)
  245. | Category | Providers |
  246. | -------------------- | --------------------------------------------------------------------- |
  247. | **Cloud APIs** | OpenAI ยท Anthropic Claude ยท Google Gemini ยท Mistral AI |
  248. | **Enterprise Cloud** | Azure OpenAI ยท Amazon Bedrock ยท Oracle GenAI ยท Google Vertex AI |
  249. | **Self-Hosted** | Ollama ยท Jlama ยท Hugging Face |
  250. | **OpenAI-compatible** | xAI Grok ยท DeepSeek ยท Moonshot Kimi ยท Alibaba Qwen ยท Z.ai GLM ยท MiniMax ยท OpenRouter ยท Groq |
  251. | **Any endpoint** | Anything else OpenAI-compatible (Cohere, gateways, etc.) via `baseUrl` |
  252. - ๐Ÿ”€ **Multi-Model Cascading** โ€” Start with cheap/fast models, escalate to powerful ones based on confidence ([details](#-smart-model-cascading))
  253. - ๐Ÿ“‹ **JSON Response Mode** โ€” `jsonResponseFormat` policy (`auto` | `on` | `off`) negotiates structured JSON output across all execution paths with provider-aware rules
  254. - ๐Ÿ”ง **Tool Calling** โ€” Native function/tool calling across all providers that support it
  255. - ๐Ÿ—„๏ธ **Tool Result Caching** โ€” Per-tool cache scoping (`GLOBAL`, `USER`, `CONVERSATION`) to avoid redundant calls; fail-safe to `USER` on misconfiguration
  256. ### ๐Ÿ”— Standards & Interoperability
  257. EDDI implements open standards โ€” not proprietary APIs:
  258. | Standard | Role | What It Enables |
  259. | -------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- |
  260. | **[MCP](https://modelcontextprotocol.io/)** (Model Context Protocol) | Server (108 tools) + Client | Control EDDI from Antigravity, Claude Desktop, Cursor, Windsurf, or any MCP client โ€” [setup guide](docs/mcp-server.md#client-configuration). On an authenticated instance `/mcp` is an OAuth protected resource, so clients [sign themselves in](docs/mcp-server.md#the-client-signs-itself-in-preferred). Connect agents to external [MCP tool servers](docs/mcp-client.md) |
  261. | **[A2A](https://google.github.io/A2A/)** (Agent-to-Agent Protocol) | Full implementation | Cross-platform agent communication, Agent Cards, and skill discovery |
  262. | **[OpenAPI](https://www.openapis.org/)** 3.1 | Native generation + consumption | Auto-generated spec. Paste any OpenAPI spec โ†’ get a fully deployed API-calling agent |
  263. | **OAuth 2.0 / OIDC** | Keycloak integration | Authentication, authorization, and multi-tenant isolation. Outbound, [connections](docs/connections.md) give agents per-user OAuth grants to external systems |
  264. | **OpenAI Chat Completions** | Server (`/v1`, off by default) | Deployed agents appear as OpenAI models to [Open WebUI](docs/open-webui-integration.md), the `openai` SDK, LangChain, LiteLLM, or any OpenAI-compatible client. A deployment that only wants generic chat can use Open WebUI as its front end; it then goes without approvals in the chat, quick replies and input fields, secret input, ratings, review notices, group discussions, memory transparency and branding โ€” [what `/v1` cannot carry](docs/open-webui-integration.md) |
  265. | **SSE** (Server-Sent Events) | Streaming transport | Token-by-token chat responses, including most tool-enabled turns, which stream over the provider's streaming transport instead of going silent until the tool loop finishes (a single-chunk fallback still applies to cascade agents, providers without a streaming builder, and a few other configurations) โ€” plus a live `tool_call` event for "Using {tool}โ€ฆ" status, group discussion feeds, and live log streaming |
  266. ### ๐Ÿ’ญ Memory & Context Management
  267. - ๐Ÿ’พ **Persistent User Memory** โ€” Agents remember facts, preferences, and context across conversations via structured key-value entries with visibility scoping (`self`, `group`, `global`)
  268. - ๐Ÿง  **LLM Memory Tools** โ€” Built-in tools agents can call to read, write, and search their own persistent memory; [guardrails](docs/user-memory.md#guardrails) keep the model to its own `self` memories unless the agent allows more
  269. - ๐Ÿ’ค **Dream Consolidation** โ€” Background memory maintenance: stale entry pruning, contradiction detection, and fact summarization (inspired by [Anthropic's](https://www.anthropic.com/research) research on background memory consolidation)
  270. - ๐ŸชŸ **Token-Aware Windowing** โ€” Intelligent context packing with model-specific tokenizer support and anchored opening steps
  271. - ๐Ÿ“ **Rolling Summary** โ€” Incremental LLM-powered summarization of older turns with a **Conversation Recall Tool** for drill-back into compressed history
  272. - ๐Ÿ”ง **Property Extraction** โ€” Config-driven slot-filling with `longTerm` / `conversation` / `step` scoping, plus `secret` for values that go straight into the vault โ€” EDDI's importance extraction mechanism
  273. - ๐Ÿ›ก๏ธ **Memory Policy (Commit Flags)** โ€” Strict write discipline marks failed task output as uncommitted (hidden from LLM context) and injects concise error digests for graceful degradation
  274. - ๐Ÿงน **Tool Context Ceiling** โ€” `maxToolContextTokens` caps tool output within a single turn (default 60k tokens), evicting oldest tool exchanges to prevent provider context-window errors while preserving tool-call pairing
  275. - ๐Ÿ”„ **Conversation State** โ€” Full history with undo/redo support
  276. ### ๐Ÿ“š RAG (Retrieval-Augmented Generation)
  277. - ๐Ÿ“ฆ **8 Embedding Providers** โ€” OpenAI, Azure OpenAI, Ollama, Mistral, Bedrock, Cohere, Google Gemini, Vertex AI โ€” queries and documents are embedded asymmetrically where the model supports it
  278. - ๐Ÿ—„๏ธ **6 Vector Stores** โ€” pgvector, Chroma, In-Memory, MongoDB Atlas, Elasticsearch, Qdrant
  279. - ๐Ÿ•ท๏ธ **Web Crawler Sources** โ€” A knowledge base can crawl a website itself: robots-aware, sitemap-driven, bounded by depth, page count and time budget, with deleted pages tombstoned on later runs ([details](docs/rag.md#ingestion-sources))
  280. - ๐Ÿ“„ **File Uploads** โ€” Upload PDF, Word, Excel, PowerPoint, CSV, HTML, Markdown and text files to a knowledge base; the content, not the file name, decides the format
  281. - โฑ๏ธ **Scheduled Ingestion** โ€” Each source runs on its own cron or on demand, with preview, purge and a run history of counters and errors โ€” all editable in the Manager's knowledge-base editor
  282. - ๐ŸŒ **httpCall RAG** โ€” Zero-infrastructure RAG via any search API (BM25, Elasticsearch, custom)
  283. - ๐Ÿ“ฅ **REST Ingestion API** โ€” Async document ingestion with status tracking and in-place replacement of an earlier version
  284. ### ๐Ÿ› ๏ธ Built-In AI Agent Tools
  285. | Tool | Description |
  286. | ---------------------------------------------- | ----------------------------------------------------------------------------- |
  287. | ๐Ÿ” **Web Search** | DuckDuckGo, Brave Search API, or Google Custom Search (until 2027-01-01) |
  288. | ๐Ÿงฎ **Calculator** | Sandboxed recursive-descent math parser (no `eval()`, no code injection) |
  289. | ๐ŸŒ **Web Scraper** | SSRF-protected, size-capped extraction of web pages as Markdown |
  290. | ๐Ÿ“„ **PDF Reader** | SSRF-protected document extraction |
  291. | โ˜๏ธ **Weather** ยท ๐Ÿ• **DateTime** | Real-time data tools |
  292. | ๐Ÿ“Š **Data Formatter** ยท ๐Ÿ“ **Text Summarizer** | Data transformation tools |
  293. | ๐Ÿ”Œ **HTTP Calls as Tools** | Expose your own REST APIs as LLM-callable tools with full security sandboxing |
  294. | ๐Ÿง  **User Memory** | Read/write/search persistent user memory |
  295. | ๐Ÿ”™ **Conversation Recall** | Drill back into summarized conversation history |
  296. | ๐Ÿ“Ž **Multimodal Attachments** | Image, PDF, audio, and video input with MIME-based routing |
  297. ### ๐Ÿ“Ž Multimodal Attachments
  298. - ๐Ÿ“ค **3 Input Paths** โ€” URL reference, base64 inline, or file upload (`POST /conversations/{id}/attachments` with multipart/form-data)
  299. - ๐Ÿ—„๏ธ **DB-Agnostic Storage** โ€” GridFS (MongoDB) or bytea (PostgreSQL) via `IAttachmentStore` SPI with grant-based access control and per-tenant quotas
  300. - ๐Ÿ“„ **Hybrid PDF Extraction** โ€” PDFs are auto-extracted to text (shared `AttachmentTextExtractor`) and forwarded as inline context to any LLM, not just vision models
  301. - ๐Ÿ” **readAttachment Tool** โ€” Agents can recall attachments from earlier turns in multi-turn conversations
  302. - ๐Ÿง  **Model Capability Gating** โ€” `ModelCapabilityService` routes images to vision-capable LLMs and falls back to text metadata for others
  303. - ๐Ÿ”€ **Content-Type Routing** โ€” `contentTypeMatcher` behavior rule condition routes `image/*`, `application/pdf`, etc. to different workflows
  304. - ๐Ÿ‘ฅ **Group Parity** โ€” Attachments fan out with grant injection so group member agents can access the original user's files
  305. - ๐Ÿ—‘๏ธ **GDPR Cleanup** โ€” `deleteByConversation()` cascades to attachment storage when conversations are erased
  306. ### โฐ Scheduled Execution & Heartbeats
  307. - ๐Ÿซ€ **Heartbeat Triggers** โ€” Periodic agent wake-ups at configurable intervals for proactive behavior (inspired by [OpenClaw's](https://openclaw.ai) heartbeat architecture)
  308. - โฒ๏ธ **Cron Scheduling** โ€” Standard cron expressions for timed agent execution
  309. - ๐Ÿ”„ **Conversation Strategies** โ€” `persistent` (reuse same conversation across fires) or `new` (fresh context each time)
  310. - ๐Ÿ“Š **Fire Logging** โ€” Complete execution history with status, duration, cost tracking, and retry logic
  311. - ๐ŸŒ™ **Dream Cycles** โ€” Scheduled background memory consolidation with cost ceilings per run
  312. ### ๐Ÿ“ˆ Smart Model Cascading
  313. - ๐Ÿ“‰ **Cost Optimization** โ€” Try cheap/fast models first, escalate to powerful models only when confidence is low
  314. - ๐Ÿ“Š **4 Confidence Strategies** โ€” Structured output, heuristic, judge model, or none
  315. - ๐Ÿ’ฐ **Per-Conversation Budgets** โ€” Automatic cost tracking with budget caps and eviction
  316. - ๐Ÿข **Tenant Cost Ceilings** โ€” Monthly cost budgets per tenant with automatic enforcement
  317. - ๐Ÿ”ข **Tenant Agent Quotas** โ€” `maxAgentsPerTenant` enforcement on agent deployment
  318. ### โœ‹ Human-in-the-Loop Governance
  319. - ๐Ÿšฆ **Turn-Level Approval** โ€” `PAUSE_CONVERSATION` action halts the entire pipeline; new user input returns `409 Conflict` until a human resumes
  320. - ๐Ÿ”ง **Per-Tool-Call Gating** โ€” Individual tool invocations can require human approval before execution, with glob-pattern allow/exempt lists across built-in, HTTP, MCP, A2A, dynamic, memory, and recall tools
  321. - ๐Ÿ‘ฅ **Group Phase Approval** โ€” Multi-agent discussion phases can require human sign-off at `PHASE` or `TASK` granularity
  322. - ๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ **Humans in the Room** โ€” Beyond approving, a human can be a full group member with their own speaking turn; a facilitator can also pause a discussion to put a question to a named principal
  323. - โฑ๏ธ **Timeout Policies** โ€” `WAIT_INDEFINITELY`, `AUTO_APPROVE`, `AUTO_REJECT`, or `ABORT` when humans don't respond in time
  324. - ๐Ÿ” **No-Progress Guard** โ€” Detects infinite approval loops (identical pause fingerprints after automated decisions) and breaks the cycle
  325. - ๐Ÿ’ฌ **Slack Approvals** โ€” Interactive Block Kit cards with redacted argument previews and approver whitelists
  326. - ๐Ÿ”Œ **MCP Approvals** โ€” External clients can list pending approvals and approve/reject via MCP tools
  327. - ๐Ÿ–ฅ๏ธ **Manager Approvals** โ€” One page lists pending conversation and group-phase approvals and resolves them
  328. - ๐Ÿ”„ **Crash Recovery** โ€” Pending approvals survive server restarts; timeout timers are re-armed automatically
  329. ### ๐Ÿ” Enterprise Security & Compliance
  330. <details open>
  331. <summary><strong>Security Architecture</strong></summary>
  332. - ๐Ÿฆ **Secrets Vault** โ€” Envelope encryption (PBKDF2 + AES-256-GCM) with tenant-scoped DEK/KEK rotation. Never plaintext in DB. Each secret names the agents allowed to use it, checked at deploy time, and that grant can be edited without re-entering the value ([details](docs/secrets-vault.md#agent-grants-allowedagents))
  333. - ๐Ÿ”— **Connections** โ€” One credential model for every outbound call: `${connection:name}` resolves per request to an org-wide key or the end user's own OAuth grant ([details](docs/connections.md))
  334. - ๐Ÿชช **Caller Identity** โ€” An HTTP call can act as the signed-in user with `${caller:token}`, released only to the caller's own origin or to EDDI itself and never persisted ([details](docs/httpcalls.md#calling-as-the-signed-in-user))
  335. - ๐Ÿคซ **Secret Context Values** โ€” A client can pass a credential as context with `"secret": true`: usable for one turn, never stored or returned ([details](docs/passing-context-information.md#secret-context-values))
  336. - ๐Ÿ›ก๏ธ **SSRF Protection** โ€” All tools validate URLs against private IPs, internal hostnames, and non-HTTP schemes before any request; credentialed requests don't follow redirects, and downloads are size-capped
  337. - ๐Ÿ”’ **Sandboxed Evaluation** โ€” Recursive-descent math parser only. No `eval()`, no script engines, no reflection-based execution
  338. - ๐Ÿ”‘ **OAuth 2.0 / Keycloak** โ€” Multi-tenant authentication, authorization, and role-based access control; the token audience is enforced and a token that names no user is refused
  339. - ๐Ÿ—‚๏ธ **Workspaces & Sharing** โ€” Opt-in per-user and per-team spaces for agents and their configuration, with explicit `USE` / `VIEW` / `EDIT` / `OWN` shares ([details](docs/workspaces.md))
  340. - ๐Ÿงพ **Restricted Templates** โ€” Runtime templates run in a locked-down Qute engine (allow-listed namespaces and sections, bounded output), and fetched data is never rendered as a template ([details](docs/security.md#runtime-template-engine))
  341. - โœ๏ธ **Agent Signing** โ€” Ed25519 cryptographic identity per agent; audit entries signed with agent private keys
  342. - ๐Ÿšซ **No Dynamic Code Execution** โ€” Custom logic runs in external MCP servers, outside the EDDI security perimeter
  343. </details>
  344. <details open>
  345. <summary><strong>Regulatory Compliance</strong></summary>
  346. | Regulation | EDDI Support |
  347. | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
  348. | **[EU AI Act](https://artificialintelligenceact.eu/)** | Immutable HMAC-SHA256 audit ledger, decision traceability, risk classification guidance |
  349. | **[GDPR](https://gdpr.eu/)** | Cascading data erasure (Art. 17), data portability (Art. 15/20), restriction of processing (Art. 18), per-category retention, pseudonymization |
  350. | **[CCPA](https://oag.ca.gov/privacy/ccpa)** | Right to delete, right to know, data portability |
  351. | **[HIPAA](https://www.hhs.gov/hipaa/)** | Deployment guide, BAA template, LLM provider BAA matrix, session timeout guidance |
  352. | **International** | PIPEDA ๐Ÿ‡จ๐Ÿ‡ฆ ยท LGPD ๐Ÿ‡ง๐Ÿ‡ท ยท APPI ๐Ÿ‡ฏ๐Ÿ‡ต ยท POPIA ๐Ÿ‡ฟ๐Ÿ‡ฆ ยท PDPA ๐Ÿ‡ธ๐Ÿ‡ฌ๐Ÿ‡น๐Ÿ‡ญ๐Ÿ‡ฒ๐Ÿ‡พ ยท PIPL ๐Ÿ‡จ๐Ÿ‡ณ compatibility documented |
  353. - ๐Ÿ“œ **Audit Ledger** โ€” Every agent decision recorded in a write-once, HMAC-secured, append-only ledger
  354. - ๐Ÿ” **Compliance Startup Checks** โ€” Advisory warnings on boot for TLS and database encryption gaps
  355. - ๐Ÿ—‘๏ธ **GDPR Orchestration** โ€” One-call cascading erasure across every store that holds a user's data (memories, conversations, attachments, group transcripts, schedules, OAuth grants, โ€ฆ) plus audit trail pseudonymization, reporting any step that did not complete
  356. - ๐Ÿ“ค **Data Portability** โ€” Complete user data export (memories, conversations, audit entries) via REST and MCP
  357. </details>
  358. ### โš™๏ธ Configuration-Driven Architecture
  359. - ๐Ÿ“„ **JSON Configs, Not Code** โ€” Agent behavior defined in versioned, diffable JSON documents
  360. - ๐Ÿ”ง **Lifecycle Pipeline** โ€” Pluggable task pipeline: Input โ†’ Parse โ†’ Rules โ†’ API/LLM โ†’ Output
  361. - ๐Ÿ“ฆ **Composable Agents** โ€” Agents assembled from reusable, version-controlled workflows and extensions
  362. - ๐Ÿงช **Behavior Rules** โ€” IF-THEN logic engine for routing, orchestration, and business logic
  363. - ๐Ÿ“ค **Import / Export** โ€” Agents portable as ZIP files with automatic secret scrubbing on export
  364. - ๐Ÿ”„ **Agent Sync** โ€” Live instance-to-instance sync with structural matching, content diffing, and selective resource picking โ€” no ZIP intermediary needed
  365. - ๐Ÿ“ **Prompt Snippets** โ€” Reusable, versioned system prompt building blocks available as `{snippets.safety_rules}`
  366. - ๐ŸŒ **Global Variables** โ€” Deployment-wide values such as a default model, referenced as `{vars.default-model}` in any config ([details](docs/global-variables.md))
  367. - ๐Ÿ“Ž **Content Type Routing** โ€” MIME-based behavior rule conditions for multimodal attachment routing
  368. ### ๐Ÿš€ Cloud-Native & Observable
  369. - ๐Ÿณ **One-Command Install** โ€” Interactive wizard sets up EDDI + database via Docker
  370. - โ˜ธ๏ธ **Kubernetes / OpenShift** โ€” Kustomize overlays, Helm charts, PDB, NetworkPolicy, and an HPA in cluster mode
  371. - ๐Ÿงฉ **Horizontal scaling** โ€” `eddi.messaging.type=nats` runs any number of replicas of the published image behind a plain round-robin load balancer: cluster-wide conversation leases with fencing, shared security and tool state in NATS JetStream KV, cross-node cancel/GDPR/undeploy, rolling updates without lost turns. See [Clustering](docs/clustering.md)
  372. - ๐Ÿ“Š **Prometheus & Grafana** โ€” 50+ Micrometer metrics at `/q/metrics` (tools, vault, memory, scheduling, conversations). Pre-built [Grafana dashboard](docs/monitoring/eddi-grafana-dashboard.json) included
  373. - ๐Ÿ”ญ **OpenTelemetry Tracing** โ€” Per-task distributed traces via OTLP (Jaeger, Tempo, Datadog). Every pipeline task emits a span named `eddi.pipeline.task` carrying `eddi.task.id`, `eddi.task.type`, `eddi.task.index`, `eddi.conversation.id` and `eddi.agent.id`. The equivalent *metric* tags are un-prefixed (`task.id`, `task.type`)
  374. - ๐Ÿค– **LLM Telemetry** โ€” Every model call, on every provider, streaming or not, is timed and counted (`eddi.llm.request.duration`, `eddi.llm.tokens`, `eddi.llm.request.errors`) and traced as a `gen_ai.client.inference` span
  375. - ๐Ÿฉบ **Health Checks** โ€” Liveness & readiness probes at `/q/health/live` and `/q/health/ready`
  376. - ๐Ÿ”„ **NATS JetStream** โ€” Cluster coordination: leases, shared KV state, cache-invalidation events and durable dead letters
  377. - ๐Ÿ›Ÿ **Error Handling & Recovery** โ€” Automatic retry with exponential backoff, MCP circuit breakers (open after 3 failures within 60 s), LLM response validation (`onEmpty` / `onTruncation` / `onRefusal`), streaming timeout retry, and admin endpoint to reset stuck conversations
  378. - โšก **Virtual Threads** โ€” Java 25 virtual threads for true OS-level concurrency (no Python GIL or Node.js event loop bottleneck)
  379. - ๐Ÿ—ƒ๏ธ **DB-Agnostic** โ€” Choose MongoDB or PostgreSQL; switch with one env var. Single Docker image for both
  380. - ๐Ÿ—๏ธ **Red Hat Certified** โ€” Container certification with automated preflight checks in CI/CD
  381. > **๐Ÿ“– Monitoring Guide:** See [docs/monitoring/monitoring-guide.md](docs/monitoring/monitoring-guide.md) for architecture overview, metrics reference, alerting rules, and a production checklist.
  382. ### ๐Ÿ–ฅ๏ธ Manager Dashboard & Chat UI
  383. The UIs live in this repository (`ui/manager`, `ui/workforce`, `ui/chat`) and are built into the EDDI jar and Docker image โ€” nothing to deploy separately.
  384. - ๐ŸŽจ **React 19 Manager** (`/manage`) โ€” Admin dashboard for agent building, testing, deployment, and monitoring, with the Platform Operator, an agent wizard, and editors for every resource type, including knowledge-base ingestion sources
  385. - ๐Ÿ‘ฅ **Workforce** (`/workforce`) โ€” The end-user app, its own lighter bundle: chats with agents and teams of agents in one sidebar, Home with starters, boards, member threads, a live discussion overview, and history; role-aware, with one sign-in shared with the Manager
  386. - ๐Ÿ’ฌ **Chat UI** (`/chat`) โ€” Standalone React chat with SSE streaming and Keycloak auth
  387. - โœ‹ **Approvals, Connections & Sharing** โ€” Pages for pending HITL approvals, connections and linked accounts, and sharing resources between users and teams
  388. - ๐Ÿ” **Audit Trail Viewer** โ€” Timeline-based compliance and debugging UI
  389. - ๐Ÿ“‹ **Logs Panel** โ€” Live SSE log streaming + searchable history
  390. - ๐Ÿ”‘ **Secrets Manager** โ€” Write-only vault UI with copy-reference support
  391. - ๐ŸŒ **11 Languages** โ€” English, German, Spanish, French, Portuguese, Chinese, Japanese, Korean, Arabic (RTL), Hindi, Thai
  392. ---
  393. ## ๐Ÿ“– Documentation
  394. | Guide | Description |
  395. | ------------------------------------------------------------ | -------------------------------------------------- |
  396. | **[Getting Started](docs/getting-started.md)** | Setup and first steps |
  397. | **[Developer Quickstart](docs/developer-quickstart.md)** | Build your first agent in 5 minutes |
  398. | **[Manager Dashboard](docs/agent-manager-gui.md)** | The built-in admin UI and the Workforce workspace |
  399. | **[Architecture](docs/architecture.md)** | Deep dive into EDDI's design and pipeline |
  400. | **[LLM Configuration](docs/langchain.md)** | Connecting to 19 LLM providers |
  401. | **[Behavior Rules](docs/behavior-rules.md)** | Configuring agent routing logic |
  402. | **[Agent Config Authoring](docs/agent-config-authoring.md)** | Rules and pitfalls for writing agent JSON |
  403. | **[HTTP Calls](docs/httpcalls.md)** | External API integration |
  404. | **[RAG](docs/rag.md)** | Knowledge bases, crawled and uploaded sources, retrieval |
  405. | **[MCP Server](docs/mcp-server.md)** | 108 tools for AI-assisted agent management |
  406. | **[MCP Client](docs/mcp-client.md)** | Connecting agents to external MCP servers |
  407. | **[A2A Protocol](docs/a2a-protocol.md)** | Agent-to-Agent peer communication |
  408. | **[OpenAI-Compatible API](docs/open-webui-integration.md)** | Agents as OpenAI models for Open WebUI & SDKs |
  409. | **[Slack Integration](docs/slack-integration.md)** | Deploy agents to Slack and run group discussions |
  410. | **[Connections](docs/connections.md)** | One credential model, including per-user OAuth |
  411. | **[Group Conversations](docs/group-conversations.md)** | Debate, voting, artifacts, standing teams |
  412. | **[User Memory](docs/user-memory.md)** | Cross-conversation fact retention |
  413. | **[Memory Policy](docs/memory-policy.md)** | Commit flags and strict write discipline |
  414. | **[Model Cascading](docs/model-cascade.md)** | Cost-optimized multi-model routing |
  415. | **[Human-in-the-Loop](docs/hitl.md)** | Approval gates, timeout policies, Slack & MCP surfaces |
  416. | **[Managed Agents](docs/managed-agents.md)** | Intent-based routing, one conversation per user |
  417. | **[Scheduling & Heartbeats](docs/scheduling.md)** | Cron schedules, heartbeats, dream consolidation |
  418. | **[Deployment Management](docs/deployment-management-of-agents.md)** | Deploying, undeploying, and agent version following |
  419. | **[Agent Sync](docs/agent-sync-guide.md)** | Live instance-to-instance sync and upgrade imports |
  420. | **[Import / Export](docs/import-export-an-agent.md)** | ZIP-based agent portability and merge |
  421. | **[Prompt Snippets](docs/prompt-snippets-guide.md)** | Reusable system prompt building blocks |
  422. | **[Attachments](docs/attachments-guide.md)** | Multimodal attachment pipeline |
  423. | **[Capability Matching](docs/capability-match-guide.md)** | A2A skill discovery and routing |
  424. | **[Security](docs/security.md)** | SSRF protection, sandboxing, and hardening |
  425. | **[Workspaces](docs/workspaces.md)** | Per-user and per-team isolation, and sharing |
  426. | **[Secrets Vault](docs/secrets-vault.md)** | Envelope encryption and auto-vaulting |
  427. | **[Global Variables](docs/global-variables.md)** | Deployment-wide values for every config |
  428. | **[Audit Ledger](docs/audit-ledger.md)** | EU AI Act-compliant audit trail |
  429. | **[Tenant Quotas](docs/tenant-quotas.md)** | Per-tenant usage limits, editable at runtime |
  430. | **[Kubernetes](docs/kubernetes.md)** | Deploy with Kustomize or Helm |
  431. | **[Configuration Reference](docs/configuration-reference.md)** | Every `eddi.*` property, its default and env var |
  432. | **[Upgrading from 5.x](docs/upgrading-from-5x.md)** | First boot of an EDDI 5 database on 6.x |
  433. | **[Upgrading from 6.4](docs/upgrading-from-6.4.md)** | What an existing 6.4 deployment must change for 6.5 |
  434. | **[Upgrading from 6.5](docs/upgrading-from-6.5.md)** | What a 6.5 deployment notices on 6.6 and 6.7 |
  435. | **[Monitoring & Tracing](docs/monitoring/monitoring-guide.md)** | Prometheus, Grafana, OpenTelemetry, alerting |
  436. | **[Red Hat & OpenShift](docs/redhat-openshift.md)** | RHEL support, certified container, automated release |
  437. | **[Full Documentation](https://docs.labs.ai/)** | Complete documentation site |
  438. ---
  439. ## ๐Ÿ“‹ Compliance & Privacy
  440. EDDI provides built-in infrastructure for regulatory compliance:
  441. | Guide | Covers |
  442. | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
  443. | **[GDPR / CCPA](docs/gdpr-compliance.md)** | Data erasure, export, Art. 18 restriction of processing, per-category retention, and consent guidance |
  444. | **[HIPAA](docs/hipaa-compliance.md)** | Healthcare deployment guide โ€” encryption, BAAs, LLM provider matrix, session management |
  445. | **[EU AI Act](docs/eu-ai-act-compliance.md)** | AI risk classification, decision traceability, immutable audit ledger |
  446. | **[Privacy & Data Processing](PRIVACY.md)** | Data flows, LLM provider matrix, international regulations (PIPEDA, LGPD, APPI, POPIA, PDPA, PIPL) |
  447. | **[Compliance Data Flow](docs/compliance-data-flow.md)** | Single-page data flow diagram for auditors |
  448. | **[Incident Response](docs/incident-response.md)** | Breach response runbook (GDPR 72h, CCPA 45 days, HIPAA 60 days) |
  449. ---
  450. ## ๐Ÿ—๏ธ Development
  451. ### Prerequisites
  452. | Tool | Version | Notes |
  453. | -------------- | ------- | ----------------------------------------------------------------- |
  454. | **Java (JDK)** | 25 | [Eclipse Temurin](https://adoptium.net/) recommended |
  455. | **Maven** | 3.9+ | Bundled via `mvnw` / `mvnw.cmd` wrapper โ€” no install needed |
  456. | **MongoDB** | 6.0+ | Local instance or Docker (`docker run -d -p 27017:27017 mongo:7`) |
  457. | **Docker** | Latest | For integration tests and container builds |
  458. | **Node.js** | โ€” | Not required: Maven downloads Node 26 into `ui/node/` to build the Manager, Workforce and Chat UIs. Install it only to run `npm run dev` in `ui/manager`, `ui/workforce` or `ui/chat`, after `npm ci` in `ui/` (one lockfile for all) |
  459. | **mise** | Optional | [`mise.toml`](mise.toml) pins the exact JDK, Maven and Node versions and offers the common commands as tasks (`mise run dev`, `mise run test`) |
  460. > **Windows users:** Replace `./mvnw` with `.\mvnw.cmd` in all commands below.
  461. ### Quarkus Dev Mode
  462. Dev mode starts the application with **live reload** โ€” code changes are picked up automatically without restarting:
  463. ```bash
  464. # Linux / macOS
  465. ./mvnw compile quarkus:dev '-Djvm.args=--add-modules=jdk.incubator.vector'
  466. # Windows (PowerShell)
  467. .\mvnw.cmd compile quarkus:dev '-Djvm.args=--add-modules=jdk.incubator.vector'
  468. ```
  469. `-Djvm.args` hands the forked dev JVM the same `--add-modules=jdk.incubator.vector` flag the container image sets. Only `jlama` (in-process) agents need it โ€” without it Jlama silently falls back to scalar tensor operations and answers far too slowly โ€” so you may drop it if you never run one. `mise run dev` passes it for you.
  470. Then open [http://localhost:7070](http://localhost:7070). The Quarkus Dev UI is available at [http://localhost:7070/q/dev-ui](http://localhost:7070/q/dev-ui).
  471. > **๐Ÿ’ก The UIs build with Maven, at packaging time.** Their sources live in `ui/manager`, `ui/workforce` and `ui/chat`. `./mvnw package` (and `verify`, `install`) builds them into the jar, a few minutes; `compile`, `test` and dev mode never touch npm, so dev mode serves `/manage` and `/workforce` only after a `package`. For frontend work run `npm ci` once in `ui/` (an npm workspace: one lockfile for every UI), then `npm run dev` in `ui/manager` (port 3000) or `ui/workforce` (port 3002), both proxying to the backend on 7070. Upgrading an older checkout? Run `./mvnw clean` once.
  472. Dev mode also enables:
  473. - **Continuous testing** โ€” press `r` in the terminal to re-run tests on changes
  474. - **Dev UI** โ€” browse endpoints, CDI beans, configuration, and health checks
  475. - **Live reload** โ€” Java and resource changes apply instantly
  476. > **๐Ÿ’ก Secrets Vault:** To use the secrets vault (storing API keys encrypted), set the master key before starting:
  477. >
  478. > ```bash
  479. > # Linux/macOS
  480. > export EDDI_VAULT_MASTER_KEY=my-dev-passphrase
  481. >
  482. > # Windows (PowerShell)
  483. > $env:EDDI_VAULT_MASTER_KEY = "my-dev-passphrase"
  484. >
  485. > # Or in a .env file (already in .gitignore)
  486. > echo "EDDI_VAULT_MASTER_KEY=my-dev-passphrase" > .env
  487. > ```
  488. >
  489. > Without this, the vault is disabled and secret management returns HTTP 503. Any passphrase works for local development, where a weak one only logs a warning; a production boot refuses a key shorter than 16 characters or a known placeholder. See [Secrets Vault](docs/secrets-vault.md) for production setup.
  490. ### Maven Command Reference
  491. | Command | What It Does |
  492. | ------------------------------------------------------------- | --------------------------------------------------------------------------- |
  493. | `./mvnw compile quarkus:dev '-Djvm.args=--add-modules=jdk.incubator.vector'` | **Start dev mode** with live reload (port 7070). The flag is for `jlama` agents โ€” see above |
  494. | `./mvnw compile` | Compile sources only (fast feedback). Also runs the two `validate`-phase style gates, so it **fails** on an unused import (Checkstyle) or an unformatted file (`formatter:validate`) โ€” neither edits your sources; run `./mvnw formatter:format` to fix formatting |
  495. | `./mvnw clean compile` | Clean build โ€” delete `target/` and recompile from scratch |
  496. | `./mvnw test` | Run **unit tests** (excludes `*IT.java` integration tests) |
  497. | `./mvnw package -DskipTests -DskipUi=true` | Build the jar **without** the Manager, Workforce and Chat UIs (`compile` and `test` never build them) |
  498. | `./mvnw verify` | Compile + unit tests + package. **Integration tests are skipped** โ€” `skipITs` defaults to `true` in `pom.xml` |
  499. | `./mvnw verify -DskipITs=false` | **Full build** โ€” adds the `*IT.java` integration tests (requires Docker). This is what CI runs |
  500. | `./mvnw validate` | Run the **blocking style gates** โ€” Checkstyle (`UnusedImports`/`RedundantImport` fail the build; `FileLength`/`LineLength` stay advisory) and `formatter:validate`, which reports unformatted files without touching them |
  501. | `./mvnw formatter:format` | **Auto-format** Java sources using the project Eclipse formatter โ€” the fix for a `formatter:validate` failure |
  502. | `./mvnw package -DskipTests` | Build the JAR without running tests (for `install.sh --local`) |
  503. | `./mvnw clean package -DskipTests` then `docker build -f src/main/docker/Dockerfile -t labsai/eddi:local .` | Build the app **+ Docker image** (the same Dockerfile CI builds) |
  504. | `./mvnw package -Plicense-gen -DskipTests` | Generate **third-party licenses** (Red Hat certification) |
  505. | `./mvnw quarkus:dev -Dsuspend '-Djvm.args=--add-modules=jdk.incubator.vector'` | Start dev mode and **wait for debugger** on port 5005 |
  506. | `./mvnw quarkus:dev -Ddebug=false '-Djvm.args=--add-modules=jdk.incubator.vector'` | Start dev mode **without** the debug agent |
  507. <details>
  508. <summary><strong>Code coverage</strong></summary>
  509. JaCoCo is configured to run automatically during `./mvnw test`. After tests complete, find the coverage report at:
  510. ```
  511. target/site/jacoco/index.html
  512. ```
  513. </details>
  514. <details>
  515. <summary><strong>Useful system properties</strong></summary>
  516. | Property | Default | Description |
  517. | ------------------------------------------- | --------------------------- | ---------------------------------------------- |
  518. | `-Dquarkus.http.port=<port>` | `7070` | Override the HTTP port |
  519. | `-Dmongodb.connectionString=<uri>` | dev: `mongodb://localhost:27017/eddi` | MongoDB connection, read by `PersistenceModule`. `quarkus.mongodb.connection-string` is a different key that only the health check reads |
  520. | `-Dmongodb.database=<name>` | `eddi` | MongoDB database name |
  521. | `-Dquarkus.profile=<profile>` | `dev` | Active Quarkus profile (`dev`, `test`, `prod`) |
  522. | `-DskipTests` | `false` | Skip all tests |
  523. | `-DskipITs` | `true` | Skip integration tests only |
  524. | `-DskipUi` | `false` | Skip the npm build of `ui/manager`, `ui/workforce` and `ui/chat` (the jar then serves no UI) |
  525. </details>
  526. ### Build & Docker
  527. ```bash
  528. # Build app + Docker image (the Dockerfile CI builds; it copies target/quarkus-app)
  529. ./mvnw clean package -DskipTests
  530. docker build -f src/main/docker/Dockerfile -t labsai/eddi:local .
  531. # Build without container (for install.sh --local)
  532. ./mvnw package -DskipTests
  533. # Generate third-party licenses (Red Hat certification)
  534. ./mvnw package -Plicense-gen -DskipTests
  535. ```
  536. ### โ˜ธ๏ธ Kubernetes
  537. No shipped manifest creates the `eddi-secrets` Secret that holds the vault master
  538. key โ€” a Secret in the manifests would be reconciled on every `kubectl apply` and
  539. overwrite a live key, making everything already encrypted with it undecryptable.
  540. So the Secret is created out-of-band, **before** the first apply. Without it the
  541. EDDI pod sits in `ContainerCreating` (`MountVolume.SetUp failed: secret
  542. "eddi-secrets" not found`) and never starts.
  543. ```bash
  544. # Kustomize overlays โ€” create the vault Secret first, then apply
  545. bash k8s/create-secrets.sh # PowerShell 7: pwsh -File .\k8s\create-secrets.ps1
  546. # ...plus the database credentials, which are no longer shipped: mongodb-secrets
  547. # (MongoDB runs authenticated) or postgres-secrets โ€” commands in the Kubernetes Guide
  548. kubectl apply -k k8s/overlays/mongodb/ # MongoDB backend
  549. kubectl apply -k k8s/overlays/postgres/ # PostgreSQL backend
  550. # Quickstart (one-file manifest; same Secret step, see the Kubernetes Guide)
  551. kubectl apply -f https://raw.githubusercontent.com/labsai/EDDI/main/k8s/quickstart.yaml
  552. # Helm (renders the Secret itself, so the key is a required value). Local,
  553. # port-forward shape without OIDC: the two opt-ins are required, see the guide.
  554. helm install eddi ./helm/eddi \
  555. --set eddi.vaultMasterKey="$(openssl rand -base64 24)" \
  556. --set mongodb.rootPassword="$(openssl rand -base64 24)" \
  557. --set eddi.security.allowUnauthenticatedMcp=true \
  558. --set eddi.security.allowUnauthenticatedSecretStore=true \
  559. --namespace eddi --create-namespace
  560. ```
  561. Includes overlays for auth (Keycloak), monitoring (Prometheus/Grafana), cluster mode (a three-node NATS JetStream cluster and three EDDI replicas), Ingress, and production hardening (PDB, NetworkPolicy).
  562. See the [Kubernetes Guide](docs/kubernetes.md) for details, including the Keycloak upgrade note for existing installs.
  563. ---
  564. ## ๐Ÿค Contributing
  565. We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) for details on setting up your development environment, code style, commit conventions, and the pull request process.
  566. Every PR is automatically checked by CI (build + tests), CodeQL (security), dependency review, and AI-powered code review.
  567. ## ๐Ÿ”’ Security
  568. EDDI ships with security-by-default for production deployments:
  569. - **Authentication enforced** โ€” `AuthStartupGuard` fails startup if OIDC is disabled in production without explicit opt-out; tokens must carry the `eddi-backend` audience and name a user
  570. - **Secrets encrypted at rest** โ€” Envelope encryption (PBKDF2 โ†’ AES-256-GCM) with per-deployment salt. Never plaintext in DB. A weak vault master key stops a production boot
  571. - **Credentials only where configured** โ€” A `${vault:โ€ฆ}`, `${connection:โ€ฆ}` or `${caller:โ€ฆ}` reference resolves only where the configuration wrote it, not when it arrives through conversation data (a value EDDI auto-vaulted itself is the one exception)
  572. - **SSRF protection** โ€” EDDI's own outbound HTTP (LLM tools, the crawler, OAuth, A2A, remote sync) goes through one facade, `OutboundHttp`, with private IP blocking, per-hop redirect validation, scheme enforcement and in-flight body caps
  573. - **Security headers** โ€” `X-Content-Type-Options`, `X-Frame-Options`, `Content-Security-Policy` configured out of the box
  574. - **Loopback by default** โ€” The Docker Compose files publish EDDI, Keycloak and the datastores on `127.0.0.1`, and the Helm chart and Kustomize overlays ship no default credentials
  575. - **CI/CD security gates** โ€” CI scans the code with:
  576. - **CodeQL** โ€” Semantic SAST analysis with `security-extended` queries, for the Java backend and the UIs
  577. - **Trivy** โ€” CVE scanning of filesystem dependencies on code changes, and of the Docker image before it is published (both blocking on CRITICAL/HIGH)
  578. - **Gitleaks** โ€” Git history scanning to prevent secret/credential leakage
  579. - **CycloneDX** โ€” SBOM generation for supply chain transparency, on pushes to `main` and release tags
  580. - **Jazzer** โ€” Coverage-guided fuzz testing (ClusterFuzzLite) for security-critical parsers (PathNavigator, MatchingUtilities, SafeJsonExpression), on PRs that touch Java sources and weekly
  581. - All actions SHA-pinned to prevent supply-chain attacks
  582. For vulnerability reports, see our [Security Policy](SECURITY.md). For architecture details, see [Security Architecture](docs/security.md).
  583. ## ๐Ÿ“œ Code of Conduct
  584. This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.