{"id":28903737,"url":"https://github.com/thalesgroup/fred","last_synced_at":"2026-05-11T11:08:02.028Z","repository":{"id":299047247,"uuid":"984154305","full_name":"ThalesGroup/fred","owner":"ThalesGroup","description":"the UI and agentic backend of the fred innovation track","archived":false,"fork":false,"pushed_at":"2026-05-02T05:31:26.000Z","size":42767,"stargazers_count":49,"open_issues_count":18,"forks_count":15,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2026-05-02T06:32:00.403Z","etag":null,"topics":["agentic-ai","langchain","langgraph","model"],"latest_commit_sha":null,"homepage":"https://fredk8.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThalesGroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-05-15T13:32:22.000Z","updated_at":"2026-05-02T05:29:03.000Z","dependencies_parsed_at":"2026-01-23T13:04:00.755Z","dependency_job_id":"bec4a76e-0da1-4d22-b493-67948304d71c","html_url":"https://github.com/ThalesGroup/fred","commit_stats":null,"previous_names":["thalesgroup/fred"],"tags_count":87,"template":false,"template_full_name":"ThalesGroup/template-project","purl":"pkg:github/ThalesGroup/fred","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Ffred","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Ffred/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Ffred/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Ffred/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThalesGroup","download_url":"https://codeload.github.com/ThalesGroup/fred/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Ffred/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32892012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","langchain","langgraph","model"],"created_at":"2025-06-21T12:06:11.702Z","updated_at":"2026-05-11T11:08:02.018Z","avatar_url":"https://github.com/ThalesGroup.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fred\n\nBefore you even know what fred is about, there are two key references to know: \n- [Who does what](https://github.com/orgs/ThalesGroup/projects/8/views/4)\n- [Fred deployment factory](https://github.com/fred-agent/fred-deployment-factory)\n\n\nFred is a production-ready platform for building and operating multi-agent AI applications. It is designed around two complementary goals:\n\n- **A complete runtime platform** — auth, session management, document ingestion, team access control, observability, and Kubernetes-ready deployment, all integrated and ready to use.\n- **A structured agent authoring SDK** — a constrained, typed authoring model (v2 SDK) that lets domain engineers write reliable agents without having to design a distributed runtime from scratch.\n\nFred is composed of four components:\n\n- a **Python agentic backend** (`agentic-backend`) — multi-agent runtime, session orchestration, streaming, MCP tool integration\n- a **Python knowledge flow backend** (`knowledge-flow-backend`) — document ingestion, vectorization, and retrieval\n- a **Python control plane backend** (`control-plane-backend`) — team and user management, access policy, agent registry\n- a **React frontend** (`frontend`) — chat interface and agent management UI\n\nThe repository also includes an [academy](./academy/README.md) with sample MCP servers and agents to get started quickly.\n\nSee the project site: \u003chttps://fredk8.dev\u003e\n\nContents:\n\n- [Getting started](#getting-started)\n  - [Development environment setup](#development-environment-setup)\n    - [Option 1 (recommended): Let the Dev Container do it for you!](#option-1-recommended-let-the-dev-container-do-it-for-you)\n    - [Option 2: Native mode i.e. install everything locally](#option-2-native-mode-ie-install-everything-locally)\n    - [Advanced developer tips](#advanced-developer-tips)\n  - [Model configuration](#model-configuration)\n  - [Start Fred components](#start-fred-components)\n  - [Head for the Fred UI!](#head-for-the-fred-ui)\n- [k3d Local Deployment](#k3d-local-deployment)\n- [Production mode](#production-mode)\n- [Agent authoring (v2 SDK)](#agent-authoring-v2-sdk)\n- [Agent coding academy](#agent-coding-academy)\n- [Advanced configuration](#advanced-configuration)\n- [Core Architecture and Licensing Clarity](#core-architecture-and-licensing-clarity)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [Community](#community)\n- [Contacts](#contacts)\n\n## Getting started\n\nTo ensure a smooth first-time experience, Fred’s maintainers designed Dev Container/Native startup to require no additional external components (except, of course, to LLM APIs).\n\nBy default, using either Dev Container or native startup:\n\n- Fred stores all data locally using **SQLite** for SQL/metadata and **ChromaDB** for vectors/embeddings. (DuckDB has been deprecated.) Data includes metrics, chat conversations, document uploads, and embeddings.\n- Authentication and authorization are mocked.\n\n\u003e **Note:**  \n\u003e Accross all setup modes, a common requirement is to have access to Large Language Model (LLM) APIs via a model provider. Supported options include:\n\u003e\n\u003e - **Public OpenAI APIs:** Connect using your OpenAI API key.\n\u003e - **Private Ollama Server:** Host open-source models such as Mistral, Qwen, Gemma, and Phi locally or on a shared server.\n\u003e - **Private Azure AI Endpoints:** Connect using your Azure OpenAI key.\n\u003e\n\u003e Detailed instructions for configuring your chosen model provider are provided [below](#model-configuration).\n\n### Development environment setup\n\nChoose how you want to prepare Fred's development environment:\n\n#### Option 1 (recommended): Let the Dev Container do it for you!\n\n\u003cdetails\u003e\n  \u003csummary\u003eDetails\u003c/summary\u003e\n\nPrefer an isolated environment with everything pre-installed?\n\nThe Dev Container setup takes care of all dependencies related to agentic backend, knowledge-flow backend, and frontend components.\n\n##### Prerequisites\n\n| Tool                                                                | Purpose                             |\n| ------------------------------------------------------------------- | ----------------------------------- |\n| **Docker** / Docker Desktop                                         | Runs the container                  |\n| **VS Code**                                                         | Primary IDE                         |\n| **Dev Containers extension** (`ms-vscode-remote.remote-containers`) | Opens the repo inside the container |\n\n##### Open the container\n\n1. Clone (or open) the repository in VS Code.\n2. Press \u003ckbd\u003eF1\u003c/kbd\u003e → **Dev Containers: Reopen in Container**.\n\nWhen the terminal prompt appears, the workspace is ready but you still need to run the different services with `make run` as specified in the [next section](#start-fred-components). Ports `8000` (Agentic backend), `8111` (Knowledge Flow backend), and `5173` (Frontend (vite)) are automatically forwarded to the host.\n\n##### Rebuilds \u0026 troubleshooting\n\n- Rebuild the container: \u003ckbd\u003eF1\u003c/kbd\u003e → _Dev Containers: Rebuild Container_\n- Dependencies feel stale? Delete the relevant `.venv` or `frontend/node_modules` inside the container, then rerun the associated `make` target.\n- Need to change API keys or models? Update the backend `.env` files inside the container and restart the relevant service. See [Model configuration](#model-configuration) for more details.\n\n\u003c/details\u003e\n\n#### Option 2: Native mode i.e. install everything locally\n\n\u003cdetails\u003e\n  \u003csummary\u003eDetails\u003c/summary\u003e\n\n\u003e Note: Note that this native mode only applies to Unix-based OS (e.g., Mac or Linux-related OS).\n\n##### Prerequisites\n\n\u003cdetails\u003e\n  \u003csummary\u003eFirst, make sure you have all the requirements installed\u003c/summary\u003e\n\n| Tool         | Type                       | Version                                                                                             | Install hint                                                                                |\n| ------------ | -------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| Pyenv        | Python installer           | latest                                                                                              | [Pyenv installation instructions](https://github.com/pyenv/pyenv#installation)              |\n| Python       | Programming language       | 3.12.8                                                                                              | Use `pyenv install 3.12.8`                                                                  |\n| python3-venv | Python venv module/package | matching                                                                                            | Bundled with Python 3 on most systems; otherwise `apt install python3-venv` (Debian/Ubuntu) |\n| nvm          | Node installer             | latest                                                                                              | [nvm installation instructions](https://github.com/nvm-sh/nvm#installing-and-updating)      |\n| Node.js      | Programming language       | 22.13.0                                                                                             | Use `nvm install 22.13.0`                                                                   |\n| Make         | Utility                    | system                                                                                              | Install via system package manager (e.g., `apt install make`, `brew install make`)          |\n| yq           | Utility                    | system                                                                                              | Install via system package manager                                                          |\n| SQLite       | Local RDBMS engine         | ≥ 3.35.0                                                                                            | Install via system package manager                                                          |\n| Pandoc       | 2.9.2.1                    | [Pandoc installation instructions](https://pandoc.org/installing.html)                              | For DOCX document ingestion                                                                 |\n| LibreOffice  | Headless doc converter     | [LibreOffice installation instructions](https://www.libreoffice.org/download/download-libreoffice/) | Required for PPTX vision enrichment (`pptx -\u003e pdf`) via the `soffice` command                                                                |\n| libmagic     | Identifies file types by content | Install via system package manager (e.g., `apt install libmagic1`, `brew install libmagic`)         | To check file type                                                                          |\n\n  \u003cdetails\u003e\n    \u003csummary\u003eDependency details\u003c/summary\u003e\n\n```mermaid\ngraph TD\n    subgraph FredComponents[\"Fred Components\"]\n      style FredComponents fill:#b0e57c,stroke:#333,stroke-width:2px  %% Green Color\n        Agentic[\"agentic-backend\"]\n        Knowledge[\"knowledge-flow-backend\"]\n        Frontend[\"frontend\"]\n    end\n\n    subgraph ExternalDependencies[\"External Dependencies\"]\n      style ExternalDependencies fill:#74a3d9,stroke:#333,stroke-width:2px  %% Blue Color\n        Venv[\"python3-venv\"]\n        Python[\"Python 3.12.8\"]\n        SQLite[\"SQLite\"]\n        Pandoc[\"Pandoc\"]\n        libmagic[\"libmagic\"]\n        Pyenv[\"Pyenv (Python installer)\"]\n        Node[\"Node 22.13.0\"]\n        NVM[\"nvm (Node installer)\"]\n    end\n\n    subgraph Utilities[\"Utilities\"]\n      style Utilities fill:#f9d5e5,stroke:#333,stroke-width:2px  %% Pink Color\n        Make[\"Make utility\"]\n        Yq[\"yq (YAML processor)\"]\n    end\n\n    Agentic --\u003e|depends on| Python\n    Agentic --\u003e|depends on| Knowledge\n    Agentic --\u003e|depends on| Venv\n\n    Knowledge --\u003e|depends on| Python\n    Knowledge --\u003e|depends on| Venv\n    Knowledge --\u003e|depends on| Pandoc\n    Knowledge --\u003e|depends on| SQLite\n    Knowledge --\u003e|depends on| libmagic\n\n    Frontend --\u003e|depends on| Node\n\n    Python --\u003e|depends on| Pyenv\n\n    Node --\u003e|depends on| NVM\n\n```\n\n  \u003c/details\u003e\n\n\u003c/details\u003e\n\n##### Clone the repo\n\n```bash\ngit clone https://github.com/ThalesGroup/fred.git\ncd fred\n```\n\u003e Note: the PPTX vision enrichment path in `knowledge-flow-backend` requires LibreOffice to be installed locally and the `soffice` command to be available in `PATH`. On Debian/Ubuntu, this can be installed with `apt install libreoffice`.\n\n\u003c/details\u003e\n\n#### Advanced developer tips\n\n\u003e Prerequisites:\n\u003e\n\u003e - [Visual Studio Code](https://code.visualstudio.com/)\n\u003e - VS Code extensions:\n\u003e   - **Python** (ms-python.python)\n\u003e   - **Pylance** (ms-python.vscode-pylance)\n\nTo get full VS Code Python support (linting, IntelliSense, debugging, etc.) across our repo, we provide:\n\n\u003cdetails\u003e\n  \u003csummary\u003e1. A VS Code workspace file `fred.code-workspace` that loads all sub‑projects.\u003c/summary\u003e\n\nAfter cloning the repo, you can open Fred's VS Code workspace with `code .vscode/fred.code-workspace`\n\nWhen you open Fred's VS Code workspace, VS Code will load four folders:\n\n- `fred` – for any repo‑wide files, scripts, etc\n- `agentic-backend` – first Python backend\n- `knowledge-flow-backend` – second Python backend\n- `fred-core` - a common python library for both python backends\n- `frontend` – UI\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e2. Per‑folder `.vscode/settings.json` files in each Python backend to pin the interpreter.\u003c/summary\u003e\n\nEach backend ships its own virtual environment under .venv. We’ve added a per‑folder VS Code setting (see for instance `agentic_backend/.vscode/settings.json`) to automatically pick it:\n\nThis ensures that as soon as you open a Python file under agentic_backend/ (or knowledge_flow_backend/), VS Code will:\n\n- Activate that folder’s virtual environment\n- Provide linting, IntelliSense, formatting, and debugging using the correct Python\n\u003c/details\u003e\n\n### Model configuration\n\n#### Model configuration (Agentic Backend)\n\nModel configuration for the agentic backend lives in **`agentic-backend/config/models_catalog.yaml`**. This file is separate from `configuration.yaml` and owns the full model setup: named profiles, provider settings, shared HTTP client limits, and routing rules.\n\n**Profiles** are named model configurations. Each profile declares a provider, a model name, and optional settings (temperature, timeouts, retries). Profiles are referenced by `profile_id`.\n\n**Defaults** declare which profile to use per capability when no rule matches:\n\n```yaml\ndefault_profile_by_capability:\n  chat: default.chat.openai.prod\n  language: default.language.openai.prod\n```\n\n**Routing rules** allow policy-based model selection based on team, agent, or operation context. Rules are evaluated in order; the first match wins:\n\n```yaml\nrules:\n  - rule_id: team-a-uses-ollama\n    capability: chat\n    team_id: team-a\n    operation: routing\n    target_profile_id: chat.ollama.mistral\n\n  - rule_id: graph-g1-json-validation\n    capability: chat\n    agent_id: internal.graph.g1\n    operation: json_validation_fc\n    target_profile_id: chat.azure_apim.gpt4o\n```\n\nThis makes it possible to route different teams, agents, or operation types to different models — including mixing providers — without changing any agent code.\n\nFor details on all supported match criteria (`team_id`, `agent_id`, `user_id`, `operation`, `purpose`) see [`docs/platform/LLM_ROUTING_FRED.md`](./docs/platform/LLM_ROUTING_FRED.md).\n\n#### Set it up according to your development environment\n\nNo matter which development environment you choose, both backends rely on `.env` files for secrets and `configuration.yaml` / `models_catalog.yaml` for settings:\n\n- Agentic backend: `agentic-backend/config/.env`, `configuration.yaml`, and `models_catalog.yaml`\n- Knowledge Flow backend: `knowledge-flow-backend/config/.env` and `configuration.yaml`\n\n1. **Copy the templates (skip if they already exist).**\n\n   ```bash\n   cp agentic-backend/config/.env.template agentic-backend/config/.env\n   cp knowledge-flow-backend/config/.env.template knowledge-flow-backend/config/.env\n   ```\n\n2. **Edit the `.env` files** to set the API keys, base URLs, and deployment names that match your model provider.\n\n3. **Update each backend’s `configuration.yaml`** so the `provider`, `name`, and optional settings align with the same provider. Use the recipes below as a starting point.\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpenAI\u003c/summary\u003e\n\n\u003e **Note:** Out of the box, Fred is configured to use OpenAI public APIs with the following models:\n\u003e\n\u003e - agentic backend: chat model `gpt-4o`\n\u003e - knowledge flow backend: chat model `gpt-4o-mini` and embedding model `text-embedding-3-large`\n\u003e\n\u003e If you plan to use Fred with these OpenAI models, you don't have to perform the `yq` commands below—just make sure the `.env` files contain your key.\n\n- agentic backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.ai.default_chat_model.provider = \"openai\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.name = \"\u003cyour-openai-model-name\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval 'del(.ai.default_chat_model.settings)' -i agentic-backend/config/configuration.yaml\n    ```\n\n- knowledge flow backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.chat_model.provider = \"openai\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.name = \"\u003cyour-openai-model-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.chat_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n  - Embedding model\n\n    ```bash\n    yq eval '.embedding_model.provider = \"openai\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.name = \"\u003cyour-openai-model-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.embedding_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n- Copy-paste your `OPENAI_API_KEY` value in both `.env` files.\n\n  \u003e ⚠️ An `OPENAI_API_KEY` from a free OpenAI account unfortunately does not work.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eAzure OpenAI\u003c/summary\u003e\n\n- agentic backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.ai.default_chat_model.provider = \"azure-openai\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.name = \"\u003cyour-azure-openai-deployment-name\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval 'del(.ai.default_chat_model.settings)' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_endpoint = \"\u003cyour-azure-openai-endpoint\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_openai_api_version = \"\u003cyour-azure-openai-api-version\u003e\"' -i agentic-backend/config/configuration.yaml\n    ```\n\n- knowledge flow backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.chat_model.provider = \"azure-openai\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.name = \"\u003cyour-azure-openai-deployment-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.chat_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_endpoint = \"\u003cyour-azure-openai-endpoint\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_openai_api_version = \"\u003cyour-azure-openai-api-version\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n  - Embedding model\n\n    ```bash\n    yq eval '.embedding_model.provider = \"azure-openai\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.name = \"\u003cyour-azure-openai-deployment-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.embedding_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_endpoint = \"\u003cyour-azure-openai-endpoint\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_openai_api_version = \"\u003cyour-azure-openai-api-version\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n  - Vision model\n\n    ```bash\n    yq eval '.vision_model.provider = \"azure-openai\"' -i knowledge_flow_backend/config/configuration.yaml\n    yq eval '.vision_model.name = \"\u003cyour-azure-openai-deployment-name\u003e\"' -i knowledge_flow_backend/config/configuration.yaml\n    yq eval 'del(.vision_model.settings)' -i knowledge_flow_backend/config/configuration.yaml\n    yq eval '.vision_model.settings.azure_endpoint = \"\u003cyour-azure-openai-endpoint\u003e\"' -i knowledge_flow_backend/config/configuration.yaml\n    yq eval '.vision_model.settings.azure_openai_api_version = \"\u003cyour-azure-openai-api-version\u003e\"' -i knowledge_flow_backend/config/configuration.yaml\n    ```\n\n- Copy-paste your `AZURE_OPENAI_API_KEY` value in both `.env` files.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eOllama\u003c/summary\u003e\n\n- agentic backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.ai.default_chat_model.provider = \"ollama\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.name = \"\u003cyour-ollama-model-name\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval 'del(.ai.default_chat_model.settings)' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.base_url = \"\u003cyour-ollama-endpoint\u003e\"' -i agentic-backend/config/configuration.yaml\n    ```\n\n- knowledge flow backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.chat_model.provider = \"ollama\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.name = \"\u003cyour-ollama-model-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.chat_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.base_url = \"\u003cyour-ollama-endpoint\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n  - Embedding model\n\n    ```bash\n    yq eval '.embedding_model.provider = \"ollama\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.name = \"\u003cyour-ollama-model-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.embedding_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.base_url = \"\u003cyour-ollama-endpoint\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eAzure OpenAI via Azure APIM\u003c/summary\u003e\n\n- agentic backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.ai.default_chat_model.provider = \"azure-apim\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.name = \"\u003cyour-azure-openai-deployment-name\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval 'del(.ai.default_chat_model.settings)' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_ad_client_id = \"\u003cyour-azure-apim-client-id\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_ad_client_scope = \"\u003cyour-azure-apim-client-scope\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_apim_base_url = \"\u003cyour-azure-apim-endpoint\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_apim_resource_path = \"\u003cyour-azure-apim-resource-path\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_openai_api_version = \"\u003cyour-azure-openai-api-version\u003e\"' -i agentic-backend/config/configuration.yaml\n    yq eval '.ai.default_chat_model.settings.azure_tenant_id = \"\u003cyour-azure-tenant-id\u003e\"' -i agentic-backend/config/configuration.yaml\n    ```\n\n- knowledge flow backend configuration\n\n  - Chat model\n\n    ```bash\n    yq eval '.chat_model.provider = \"azure-apim\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.name = \"\u003cyour-azure-openai-deployment-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.chat_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_ad_client_id = \"\u003cyour-azure-apim-client-id\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_ad_client_scope = \"\u003cyour-azure-apim-client-scope\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_apim_base_url = \"\u003cyour-azure-apim-endpoint\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_apim_resource_path = \"\u003cyour-azure-apim-resource-path\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_openai_api_version = \"\u003cyour-azure-openai-api-version\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.chat_model.settings.azure_tenant_id = \"\u003cyour-azure-tenant-id\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n  - Embedding model\n\n    ```bash\n    yq eval '.embedding_model.provider = \"azure-apim\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.name = \"\u003cyour-azure-openai-deployment-name\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval 'del(.embedding_model.settings)' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_ad_client_id = \"\u003cyour-azure-apim-client-id\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_ad_client_scope = \"\u003cyour-azure-apim-client-scope\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_apim_base_url = \"\u003cyour-azure-apim-endpoint\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_apim_resource_path = \"\u003cyour-azure-apim-resource-path\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_openai_api_version = \"\u003cyour-azure-openai-api-version\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    yq eval '.embedding_model.settings.azure_tenant_id = \"\u003cyour-azure-tenant-id\u003e\"' -i knowledge-flow-backend/config/configuration.yaml\n    ```\n\n- Copy-paste your `AZURE_AD_CLIENT_SECRET` and `AZURE_APIM_SUBSCRIPTION_KEY` values in both `.env` files.\n\n\u003c/details\u003e\n\n### Start Fred components\n\n```bash\n# standalone mode (single-process backend: control-plane + agentic + knowledge-flow)\nmake run-app\n```\n\n```bash\n# split APIs mode (agentic:8000, knowledge-flow:8111, control-plane:8222)\nmake run-multi\n```\n\n```bash\n# default command (alias of `run-app`)\nmake run\n```\n\n```bash\n# backward-compatible alias\nmake run-app-multi\n```\n\n```bash\n# split APIs mode + all Temporal workers (requires Temporal running)\nmake run-multi-workers\n```\n\nRun a single backend API from repository root:\n\n```bash\nmake run-control-plane\nmake run-agentic\nmake run-knowledge-flow\n```\n\nOr run each component from its own folder:\n\n```bash\n# knowledge-flow backend\ncd knowledge-flow-backend \u0026\u0026 make run\n```\n\n```bash\n# agentic backend\ncd agentic-backend \u0026\u0026 make run\n```\n\n```bash\n# control-plane backend\ncd control-plane-backend \u0026\u0026 make run\n```\n\n```bash\n# frontend\ncd frontend \u0026\u0026 make run\n```\n\n### Head for the Fred UI!\n\nOpen \u003chttp://localhost:5173\u003e in your browser.\n\n## k3d Local Deployment\n\nFred can be deployed locally into a [k3d](https://k3d.io) Kubernetes cluster using Helm. This mode mirrors a production-like setup while keeping everything on your machine.\n\n### Prerequisites\n\n| Tool | Purpose | Install |\n|------|---------|---------|\n| **Docker** | Container runtime | [docs](https://docs.docker.com/get-docker/) |\n| **k3d** | Local Kubernetes clusters | `curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh \\| bash` |\n| **Helm** | Kubernetes package manager | [docs](https://helm.sh/docs/intro/install/) |\n| **kubectl** | Kubernetes CLI | [docs](https://kubernetes.io/docs/tasks/tools/) |\n\nYou also need the infrastructure stack deployed via the [fred-deployment-factory](https://github.com/ThalesGroup/fred-deployment-factory) repository. Follow its README to run `make k3d-up`.\n\n### Host Configuration\n\n\u003e [!IMPORTANT]\n\u003e You **must** add `keycloak` to your `/etc/hosts` file so your browser can reach the Keycloak server running inside k3d:\n\u003e\n\u003e ```\n\u003e 127.0.0.1 localhost keycloak\n\u003e ```\n\u003e\n\u003e Without this entry, authentication will not work because the browser cannot resolve the `keycloak` hostname.\n\n### Deploying\n\n```bash\n# 1. Set your OpenAI API key in the values file\n#    Edit deploy/local/k3d/values-local.yaml and fill OPENAI_API_KEY\n\n# 2. Build, import images into k3d, and deploy via Helm (all-in-one)\nmake k3d-deploy\n```\n\n### Makefile Targets\n\n| Target | Description |\n|--------|-------------|\n| `make k3d-build` | Build Docker images for all services (agentic-backend, knowledge-flow-backend, frontend) |\n| `make k3d-import` | Import built images into the k3d cluster |\n| `make k3d-deploy` | All-in-one: build + import + deploy |\n| `make k3d-deploy-only` | Deploy/upgrade the Helm chart only (images must already be imported) |\n| `make k3d-undeploy` | Uninstall the Helm release |\n| `make k3d-status` | Show pod and service status in the `fred` namespace |\n| `make k3d-logs-agentic` | Tail logs for the agentic-backend |\n| `make k3d-logs-kf` | Tail logs for the knowledge-flow-backend |\n| `make k3d-logs-frontend` | Tail logs for the frontend |\n\n### Accessing the Application\n\nOnce deployed, open \u003chttp://localhost:8088\u003e in your browser. The Traefik Ingress routes all traffic through a single port:\n\n| Path | Service |\n|------|---------|\n| `/` | Frontend |\n| `/agentic/*` | Agentic backend |\n| `/knowledge-flow/*` | Knowledge Flow backend |\n| `/realms/*` | Keycloak (authentication) |\n\nOther infrastructure services remain accessible on their usual ports:\n\n| Service | URL |\n|---------|-----|\n| Keycloak | \u003chttp://keycloak:8080\u003e |\n| Temporal UI | \u003chttp://localhost:8233\u003e |\n| MinIO Console | \u003chttp://localhost:9001\u003e |\n| OpenSearch Dashboards | \u003chttp://localhost:5601\u003e |\n\n## Production mode\n\n\u003e [!IMPORTANT]\n\u003e **Access-control reminder (shared environments):**\n\u003e Keycloak app roles and team ReBAC rights are different controls.\n\u003e For the Fred access model and deployment bootstrap rules, see [`docs/platform/REBAC.md`](./docs/platform/REBAC.md).\n\nFor production deployments (Kubernetes, VMs, on-prem or cloud), refer to:\n\n- [`docs/platform/DEPLOYMENT_GUIDE.md`](./docs/platform/DEPLOYMENT_GUIDE.md) – high-level deployment guide (components, configuration, external dependencies).\n- [`docs/platform/DEPLOYMENT_GUIDE_OPENSEARCH.md`](./docs/platform/DEPLOYMENT_GUIDE_OPENSEARCH.md) – OpenSearch-specific requirements. Use this only if you choose OpenSearch over the new PostgreSQL/pgvector option.\n- [`docs/platform/REBAC.md`](./docs/platform/REBAC.md) – high-level access model (RBAC/ReBAC/organization/bootstrap).\n\nThe rest of this `README.md` focuses on local developer setup and model configuration.\n\n## Agent authoring (v2 SDK)\n\nFred includes a structured agent authoring SDK designed for domain engineers and platform teams who need to write reliable, testable agents without re-implementing execution infrastructure.\n\nThe v2 SDK provides two authoring styles:\n\n- **ReAct / profile agents** — for focused, tool-driven agents with a small state surface. Declare a role, a tool set, and a few instructions. The SDK owns the execution loop.\n- **Graph agents** — for multi-step business workflows with explicit state, conditional routing, and human-in-the-loop confirmation gates. The business flow is expressed as a typed graph; the SDK handles streaming, checkpointing, and HITL interrupts.\n\nBoth styles support MCP tool integration and run on the same runtime.\n\nStart with the [agent authoring guide (v2)](./docs/authoring/AGENTS.md). For the design philosophy behind the SDK, see [SDK V2 positioning](./docs/authoring/SDK-V2-POSITIONING.md).\n\n## Agent coding academy\n\nThe [academy](./academy/README.md) contains sample MCP servers and standalone applications to experiment with agent development outside the main platform. The [academy agents](./agentic-backend/agentic_backend/academy/ACADEMY.md) provide ready-to-run agent examples inside the agentic backend.\n\n## Advanced configuration\n\n### System Architecture\n\n| Component              | Location                    | Role                                                                 |\n| ---------------------- | --------------------------- | -------------------------------------------------------------------- |\n| Frontend UI            | `./frontend`                | React chat interface and agent management UI                         |\n| Agentic backend        | `./agentic-backend`         | Multi-agent runtime, session orchestration, streaming, MCP tools     |\n| Knowledge Flow backend | `./knowledge-flow-backend`  | Document ingestion, vectorization, and retrieval                     |\n| Control Plane backend  | `./control-plane-backend`   | Team and user management, access policy, agent registry              |\n\n### Configuration Files\n\n| File                                                | Purpose                                                 | Tip                                                                 |\n| --------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |\n| `agentic-backend/config/.env`                       | Secrets (API keys, passwords). Not committed to Git.    | Copy `.env.template` to `.env` and fill in any missing values.      |\n| `knowledge-flow-backend/config/.env`                | Same as above                                           | Same as above                                                       |\n| `control-plane-backend/config/.env`                 | Same as above                                           | Same as above                                                       |\n| `agentic-backend/config/configuration.yaml`         | Functional settings (providers, agents, feature flags). | -                                                                   |\n| `knowledge-flow-backend/config/configuration.yaml`  | Same as above                                           | -                                                                   |\n| `control-plane-backend/config/configuration.yaml`   | Team/user policy settings.                              | -                                                                   |\n\n### Supported Model Providers\n\n| Provider                    | How to enable                                                                                                |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------ |\n| OpenAI (default)            | Add `OPENAI_API_KEY` to `config/.env`; Adjust `configuration.yaml`                                           |\n| Azure OpenAI                | Add `AZURE_OPENAI_API_KEY` to `config/.env`; Adjust `configuration.yaml`                                     |\n| Azure OpenAI via Azure APIM | Add `AZURE_APIM_SUBSCRIPTION_KEY` and `AZURE_AD_CLIENT_SECRET` to `config/.env`; Adjust `configuration.yaml` |\n| Ollama (local models)       | Adjust `configuration.yaml`                                                                                  |\n\nSee `agentic-backend/config/configuration.yaml` (section `ai:`) and `knowledge-flow-backend/config/configuration.yaml` (sections `chat_model:` and `embedding_model:`) for concrete examples.\n\n### Advanced Integrations\n\n- Enable Keycloak or another OIDC provider for authentication\n- Persistence options:\n  - **Laptop / dev (default):** SQLite for metadata + ChromaDB for vectors (embedded, no external services)\n  - **Production:** PostgreSQL + pgvector for metadata/vectors, and optionally MinIO/S3 + OpenSearch if you prefer that stack\n\n## Core Architecture and Licensing Clarity\n\nThe four components described above form the _entirety of the Fred platform_. By default they run self-contained on a laptop using **SQLite + ChromaDB** (no external services).\n\nFred is modular: you can optionally add Keycloak/OpenFGA, MinIO/S3, OpenSearch, and PostgreSQL/pgvector for production-grade persistence.\n\nPersistence options:\n\n- **Dev/laptop (default):** SQLite for all SQL stores, ChromaDB for vectors, local filesystem for blobs.\n- **Production (recommended):** PostgreSQL + pgvector for SQL + vectors; optionally pair with MinIO/S3 + OpenSearch if you prefer that stack.\n\n## Documentation\n\n- Generic information\n\n  - [Main docs](https://fredk8.dev/docs)\n  - [Features overview](./docs/platform/FEATURES.md)\n\n- Agentic backend\n\n  - [Agentic backend README](./agentic-backend/README.md)\n  - [Agentic Architecture](./agentic-backend/docs/RUNTIME_ARCHITECTURE.md)\n  - [Agentic backend agentic design](./agentic-backend/docs/AGENTS.md)\n  - [MCP capabilities for agent](./agentic-backend/docs/MCP.md)\n\n- Agent authoring (v2 SDK)\n\n  - [Agent authoring guide (v2)](./docs/authoring/AGENTS.md)\n  - [SDK V2 positioning — design philosophy](./docs/authoring/SDK-V2-POSITIONING.md)\n  - [V2 agent creation — React vs Graph](./docs/platform/V2_AGENT_CREATION.md)\n\n- Architecture RFCs\n\n  - [SDK V2 for industrial-grade agents](./docs/rfc/SDK-V2-RFC.md)\n  - [Distributed agent architecture](./docs/rfc/DISTRIBUTED-AGENT-ARCHITECTURE-RFC.md)\n\n- Knowledge Flow backend\n\n  - [Knowledge Flow backend README](./knowledge_flow_backend/README.md)\n\n- Frontend\n\n  - [Frontend README](./frontend/README.md)\n\n- Security-related topics\n\n  - [Security overview](./docs/platform/SECURITY.md)\n  - [Keycloak](./docs/platform/KEYCLOAK.md)\n\n- Developer and contributors guides\n\n  - [Developer Contract (humans + AI)](./docs/platform/DEVELOPER_CONTRACT.md)\n  - [Platform Runtime Map (API apps + Temporal apps)](./docs/platform/PLATFORM_RUNTIME_MAP.md)\n  - [Developer Tools](./developer_tools/README.md)\n  - [Code of Conduct](./docs/CODE_OF_CONDUCT.md)\n  - [Python Coding Guide](./docs/platform/PYTHON_CODING_GUIDELINES.md)\n  - [Contributing](./docs/CONTRIBUTING.md)\n\n### Licensing Note\n\nFred is released under the **Apache License 2.0**. It does \\*not embed or depend on any LGPLv3 or copyleft-licensed components. Optional integrations (like OpenSearch or Weaviate) are configured externally and do not contaminate Fred's licensing.\nThis ensures maximum freedom and clarity for commercial and internal use.\n\nIn short: Fred is 100% Apache 2.0, and you stay in full control of any additional components.\n\nSee the [LICENSE](LICENSE.md) for more details.\n\n## Contributing\n\nWe welcome pull requests and issues. Start with the [Contributing guide](./CONTRIBUTING.md).\n\n## Community\n\nJoin the discussion on our [Discord server](https://discord.gg/F6qh4Bnk)!\n\n[![Join our Discord](https://img.shields.io/badge/chat-on%20Discord-7289da?logo=discord\u0026logoColor=white)](https://discord.gg/F6qh4Bnk)\n\n## Contacts\n\n- \u003calban.capitant@thalesgroup.com\u003e\n- \u003cfabien.le-solliec@thalesgroup.com\u003e\n- \u003cflorian.muller@thalesgroup.com\u003e\n- \u003csimon.cariou@thalesgroup.com\u003e\n- \u003cdimitri.tombroff@thalesgroup.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthalesgroup%2Ffred","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthalesgroup%2Ffred","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthalesgroup%2Ffred/lists"}