Fred

Fred is an open-source platform for putting a team to work with AI agents on its own documents — with the identity, access control, audit and evaluation that regulated work actually requires, from a laptop to an air-gapped cluster.

The tools most people already know — Claude Code, Codex and the like — make one person remarkably effective. Fred is built for the case where that isn't enough: the data can't leave, and the result has to belong to a team, not to an individual.

A team, its corpus, then its agents — in that order. Governance sits underneath rather than bolted on top, because the AI Act, GDPR and your security team leave no other option.

Apache 2.0 end to end. No licence, no hosted tier, nothing to sign. A third party can install the whole thing without us — that is deliberate.

The default PDF/PPTX pipeline uses pypdf, Docling and pypdfium2. PyMuPDF is available only through an explicit extra/image variant and processor selection. Third-party packages retain their own licenses; see Licensing Note.

For local development above deployment-factory, follow the local delegation and startup guide. The shared assistant workflow is the Fred skill.

How Fred is structured

Fred has two complementary faces:

• A hosted platform — control plane, knowledge flow, chat frontend, auth, team access control, observability, and Kubernetes-ready deployment, all integrated and ready to use.
• An open agent model — a typed SDK and lightweight runtime that let teams ship independent agent pods, registered with the platform and operated alongside it without forking the core.

It is built around three platform applications and a publishable SDK stack:

Layer	Package	Role
Platform	apps/control-plane-backend	Teams, sessions, agent enrollment, product APIs, ExecutionGrant issuance
Platform	apps/knowledge-flow-backend	Document ingestion, vectorization, retrieval
Platform	frontend	React chat UI (SSE streaming, rich markdown, math, Mermaid) and agent management UI
Agent pods	apps/fred-agents	First-party agent pod — the reference implementation and production execution surface
Agent pods	fred-samples	Example third-party pods — ship your own agents independently
Libraries	libs/fred-sdk	Agent authoring SDK — ReAct and graph agents, tools, HITL, execution contracts
Libraries	libs/fred-runtime	Pod factory — FastAPI, SSE streaming, checkpointing, CLI (fred-agents-cli)
Libraries	libs/fred-core	Shared infrastructure — SQL, KPI, security, config

New to the codebase? Open docs/ARCHITECTURE.html in your browser for a guided architecture walkthrough — mental models, a 20-minute reading path, and the design decisions that explain everything else. (GitHub shows raw HTML; open it locally or via VSCode Live Preview.)

The key design principle: the control plane, knowledge flow backend, and frontend are the stable platform. Agent pods — fred-agents or any team's own pod built with fred-sdk + fred-runtime — are independently deployable and register themselves with the control plane. You can ship new agents without touching the platform.

agentic-backend is still present during migration but no new features go there. Execution moves to fred-agents / fred-runtime; product/session/admin moves to control-plane-backend. See docs/backlog/BACKLOG.md for migration status.

See the project site: https://site.fredlab.dev

Contents:

• Getting started
  • Development environment setup
    • Option 1 (recommended): Let the Dev Container do it for you!
    • Option 2: Native mode i.e. install everything locally
    • Advanced developer tips
  • Model configuration
  • Start Fred components
  • Head for the Fred UI!
• k3d Local Deployment
• Production mode
• Agent authoring (v2 SDK)
• Agent coding academy
• Advanced configuration
• Core Architecture and Licensing Clarity

Getting started

Two key references before diving in:

• How do you test it? — clone, run, and know in five steps whether this checkout actually works
• Who does what
• Fred deployment factory

Testing or developing locally? Don't stop after starting the apps. Every tool and agent template is admin-gated by default — right after provisioning the demo platform, every team has an empty toolbox until an admin explicitly authorizes it. See TESTING.md steps 3–4.

To 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).

By default, using either Dev Container or native startup:

• 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.
• Authentication and authorization are mocked.

Note:
Accross all setup modes, a common requirement is to have access to Large Language Model (LLM) APIs via a model provider. Supported options include:

• Public OpenAI APIs: Connect using your OpenAI API key.
• Private Ollama Server: Host open-source models such as Mistral, Qwen, Gemma, and Phi locally or on a shared server.
• Private Azure AI Endpoints: Connect using your Azure OpenAI key.

Detailed instructions for configuring your chosen model provider are provided below.

Development environment setup

Choose how you want to prepare Fred's development environment:

Option 1 (recommended): Let the Dev Container do it for you!

Prefer an isolated environment with everything pre-installed?

The Dev Container setup takes care of all dependencies related to knowledge-flow backend, control-plane backend, fred-agents pod, and frontend components.

Prerequisites

Tool	Purpose
Docker / Docker Desktop	Runs the container
VS Code	Primary IDE
Dev Containers extension (ms-vscode-remote.remote-containers)	Opens the repo inside the container

Open the container

1. Clone (or open) the repository in VS Code.
2. Press F1 → Dev Containers: Reopen in Container.

When 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. Ports 8000 (fred-agents pod), 8111 (Knowledge Flow backend), 8222 (Control Plane backend), and 5173 (Frontend) are automatically forwarded to the host.

Rebuilds & troubleshooting

• Rebuild the container: F1 → Dev Containers: Rebuild Container
• Dependencies feel stale? Delete the relevant .venv or frontend/node_modules inside the container, then rerun the associated make target.
• Need to change API keys or models? Update the backend .env files inside the container and restart the relevant service. See Model configuration for more details.

Option 2: Native mode i.e. install everything locally

Note: Note that this native mode only applies to Unix-based OS (e.g., Mac or Linux-related OS).

Prerequisites

Tool	Type	Version	Install hint
Pyenv	Python installer	latest	Pyenv installation instructions
Python	Programming language	3.12.8	Use pyenv install 3.12.8
python3-venv	Python venv module/package	matching	Bundled with Python 3 on most systems; otherwise apt install python3-venv (Debian/Ubuntu)
nvm	Node installer	latest	nvm installation instructions
Node.js	Programming language	22.13.0	Use nvm install 22.13.0
Make	Utility	system	Install via system package manager (e.g., apt install make, brew install make)
yq	Utility	system	Install via system package manager
SQLite	Local RDBMS engine	≥ 3.35.0	Install via system package manager
Pandoc	2.9.2.1	Pandoc installation instructions	For DOCX document ingestion
LibreOffice	Headless doc converter	LibreOffice installation instructions	Required for PPTX vision enrichment (pptx -> pdf) via the soffice command
libmagic	Identifies file types by content	Install via system package manager (e.g., apt install libmagic1, brew install libmagic)	To check file type

graph TD
    subgraph FredComponents["Fred Components"]
      style FredComponents fill:#b0e57c,stroke:#333,stroke-width:2px  %% Green Color
        FredAgents["apps/fred-agents"]
        ControlPlane["apps/control-plane-backend"]
        Knowledge["knowledge-flow-backend"]
        Frontend["frontend"]
    end

    subgraph ExternalDependencies["External Dependencies"]
      style ExternalDependencies fill:#74a3d9,stroke:#333,stroke-width:2px  %% Blue Color
        Venv["python3-venv"]
        Python["Python 3.12.8"]
        SQLite["SQLite"]
        Pandoc["Pandoc"]
        libmagic["libmagic"]
        Pyenv["Pyenv (Python installer)"]
        Node["Node 22.13.0"]
        NVM["nvm (Node installer)"]
    end

    subgraph Utilities["Utilities"]
      style Utilities fill:#f9d5e5,stroke:#333,stroke-width:2px  %% Pink Color
        Make["Make utility"]
        Yq["yq (YAML processor)"]
    end

    FredAgents -->|depends on| Python
    FredAgents -->|depends on| Venv
    ControlPlane -->|depends on| Python
    ControlPlane -->|depends on| Venv

    Knowledge -->|depends on| Python
    Knowledge -->|depends on| Venv
    Knowledge -->|depends on| Pandoc
    Knowledge -->|depends on| SQLite
    Knowledge -->|depends on| libmagic

    Frontend -->|depends on| Node

    Python -->|depends on| Pyenv

    Node -->|depends on| NVM

Clone the repo

git clone https://github.com/ThalesGroup/fred.git
cd fred

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.

Advanced developer tips

Prerequisites:

• Visual Studio Code
• VS Code extensions:
  • Python (ms-python.python)
  • Pylance (ms-python.vscode-pylance)

To get full VS Code Python support (linting, IntelliSense, debugging, etc.) across our repo, we provide:

After cloning the repo, you can open Fred's VS Code workspace with code .vscode/fred.code-workspace

When you open Fred's VS Code workspace, VS Code will load these folders:

• fred – repo-wide files and scripts
• apps/fred-agents – first-party agent pod
• apps/control-plane-backend – control plane backend
• knowledge-flow-backend – knowledge flow backend
• libs/fred-core, libs/fred-sdk, libs/fred-runtime – shared libraries
• frontend – React UI

Each backend ships its own virtual environment under .venv. We’ve added a per‑folder VS Code setting (see for instance apps/fred-agents/.vscode/settings.json) to automatically pick it:

This ensures that as soon as you open a Python file inside any backend or library folder, VS Code will:

• Activate that folder’s virtual environment
• Provide linting, IntelliSense, formatting, and debugging using the correct Python

Model configuration

Model configuration (Agent pods)

Model configuration for agent pods lives in apps/fred-agents/config/models_catalog.yaml (and equivalently in any third-party pod). This file is separate from configuration.yaml and owns the pod's chat profiles, provider settings, shared HTTP client limits, local default, and optional static per-agent overrides.

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.

Defaults declare which profile to use when no more specific choice applies:

default_profile_by_capability:
  chat: default.chat.openai.prod

Static overrides let a pod operator select a different chat profile for a specific agent:

agent_profile_overrides:
  internal.graph.g1: chat.azure_apim.gpt4o

Platform-wide and team choices are configured through control-plane. The V1 policy is chat-only and uses a deterministic default/per-agent fallback chain; there are no operation, purpose, or query-classification rules.

For the exact precedence, multi-pod rules, and administrator/team workflows, see LLM_ROUTING_FRED.md.

Set it up according to your development environment

All backends rely on .env files for secrets and configuration.yaml / models_catalog.yaml for settings:

• fred-agents pod: apps/fred-agents/config/.env, configuration.yaml, and models_catalog.yaml
• Knowledge Flow backend: apps/knowledge-flow-backend/config/.env and configuration.yaml
• Control Plane backend: apps/control-plane-backend/config/.env and configuration.yaml

1. Copy the templates (skip if they already exist).

   cp apps/fred-agents/config/.env.template apps/fred-agents/config/.env
   cp apps/knowledge-flow-backend/config/.env.template apps/knowledge-flow-backend/config/.env
   cp apps/control-plane-backend/config/.env.template apps/control-plane-backend/config/.env
   

2. Edit the .env files to set the API keys, base URLs, and deployment names that match your model provider.

3. 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.

Note: Out of the box, Fred is configured to use OpenAI public APIs with the following models:

• fred-agents pod: chat model gpt-4o (or whatever profile is set as default in models_catalog.yaml)
• knowledge flow backend: chat model gpt-4o-mini and embedding model text-embedding-3-large

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.

• fred-agents pod configuration

  Edit apps/fred-agents/config/models_catalog.yaml. Find the profile you want to use (or add one) and set provider: openai and name: <your-openai-model-name>. Then set it as the default_profile_by_capability.chat default.

• knowledge flow backend configuration

  • Chat model

    yq eval '.chat_model.provider = "openai"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.name = "<your-openai-model-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.chat_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    

  • Embedding model

    yq eval '.embedding_model.provider = "openai"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.name = "<your-openai-model-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.embedding_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    

• Copy-paste your OPENAI_API_KEY value in both .env files.

  ⚠️ An OPENAI_API_KEY from a free OpenAI account unfortunately does not work.

• fred-agents pod configuration

  Edit apps/fred-agents/config/models_catalog.yaml. Find or add a profile with provider: azure-openai, name: <deployment-name>, and settings.azure_endpoint / settings.azure_openai_api_version. Set it as the default_profile_by_capability.chat default.

• knowledge flow backend configuration

  • Chat model

    yq eval '.chat_model.provider = "azure-openai"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.name = "<your-azure-openai-deployment-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.chat_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_endpoint = "<your-azure-openai-endpoint>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_openai_api_version = "<your-azure-openai-api-version>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    

  • Embedding model

    yq eval '.embedding_model.provider = "azure-openai"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.name = "<your-azure-openai-deployment-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.embedding_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_endpoint = "<your-azure-openai-endpoint>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_openai_api_version = "<your-azure-openai-api-version>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    

  • Vision model

    yq eval '.vision_model.provider = "azure-openai"' -i knowledge_flow_backend/config/configuration.yaml
    yq eval '.vision_model.name = "<your-azure-openai-deployment-name>"' -i knowledge_flow_backend/config/configuration.yaml
    yq eval 'del(.vision_model.settings)' -i knowledge_flow_backend/config/configuration.yaml
    yq eval '.vision_model.settings.azure_endpoint = "<your-azure-openai-endpoint>"' -i knowledge_flow_backend/config/configuration.yaml
    yq eval '.vision_model.settings.azure_openai_api_version = "<your-azure-openai-api-version>"' -i knowledge_flow_backend/config/configuration.yaml
    

• Copy-paste your AZURE_OPENAI_API_KEY value in both .env files.

• fred-agents pod configuration

  Edit apps/fred-agents/config/models_catalog.yaml. Add or update a profile with provider: openai, name: <your-ollama-model-name>, and settings.base_url: <your-ollama-endpoint>. Set it as the default_profile_by_capability.chat default.

• knowledge flow backend configuration

  • Chat model

    yq eval '.chat_model.provider = "ollama"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.name = "<your-ollama-model-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.chat_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.base_url = "<your-ollama-endpoint>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    

  • Embedding model

    yq eval '.embedding_model.provider = "ollama"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.name = "<your-ollama-model-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.embedding_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.base_url = "<your-ollama-endpoint>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    

• fred-agents pod configuration

  Edit apps/fred-agents/config/models_catalog.yaml. Add or update a profile with provider: azure-apim and the required settings fields (azure_ad_client_id, azure_ad_client_scope, azure_apim_base_url, azure_apim_resource_path, azure_openai_api_version, azure_tenant_id). Set it as the default profile.

• knowledge flow backend configuration

  • Chat model

    yq eval '.chat_model.provider = "azure-apim"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.name = "<your-azure-openai-deployment-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.chat_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_ad_client_id = "<your-azure-apim-client-id>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_ad_client_scope = "<your-azure-apim-client-scope>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_apim_base_url = "<your-azure-apim-endpoint>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_apim_resource_path = "<your-azure-apim-resource-path>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_openai_api_version = "<your-azure-openai-api-version>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.chat_model.settings.azure_tenant_id = "<your-azure-tenant-id>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    

  • Embedding model

    yq eval '.embedding_model.provider = "azure-apim"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.name = "<your-azure-openai-deployment-name>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval 'del(.embedding_model.settings)' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_ad_client_id = "<your-azure-apim-client-id>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_ad_client_scope = "<your-azure-apim-client-scope>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_apim_base_url = "<your-azure-apim-endpoint>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_apim_resource_path = "<your-azure-apim-resource-path>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_openai_api_version = "<your-azure-openai-api-version>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    yq eval '.embedding_model.settings.azure_tenant_id = "<your-azure-tenant-id>"' -i apps/knowledge-flow-backend/config/configuration.yaml
    

Start Fred components

# standalone mode (single-process backend: control-plane + agentic + knowledge-flow)
make run-app

# split APIs mode (agentic:8000, knowledge-flow:8111, control-plane:8222)
make run-multi

# default command (alias of `run-app`)
make run

# backward-compatible alias
make run-app-multi

# split APIs mode + all Temporal workers (requires Temporal running)
make run-multi-workers

Run a single backend API from repository root:

make run-control-plane
make run-fred-agents
make run-knowledge-flow

Or run each component from its own folder:

# knowledge-flow backend
cd apps/knowledge-flow-backend && make run

# fred-agents pod
cd apps/fred-agents && make run

# control-plane backend
cd apps/control-plane-backend && make run

# frontend
cd frontend && make run

Head for the Fred UI!

Open http://localhost:5173 in your browser.

k3d Local Deployment

Fred runs in a local k3d cluster with this repository's Helm chart (deploy/charts/fred), the one every deployment starts from, published or from this checkout. The image build is in deploy/k3d/; the k3d instance itself - its infrastructure, Fred's k3d values (k3d-apps/fred/) and the commands - lives in fred-deployment-factory. The complete walkthrough, from a clean machine to a logged-in platform_admin, is its docs/LOCAL-DEVELOPMENT.md → "k3d: the full stack in Kubernetes".

In short, from fred-deployment-factory:

make k3d-up                           # the infrastructure, once
make k3d-app APP=fred                 # the published release, no checkout (RELEASE=<version> for another)
make k3d-app APP=fred DIR=<this checkout>   # build this checkout, deploy it; rerun after any change

The model API key comes from the environment (OPENAI_API_KEY=<key> make k3d-app ... once), or with DIR from apps/fred-agents/config/.env (make setup-env here, once). Fred is then on http://localhost:8088. The first time, register on its login page and follow the token-retrieval instruction printed by make k3d-app: you become platform_admin.

Production mode

[!IMPORTANT] Access-control reminder (shared environments): Keycloak app roles and team ReBAC rights are different controls. For the Fred access model and deployment bootstrap rules, see docs/platform/REBAC.md.

For production deployments (Kubernetes, VMs, on-prem or cloud), refer to:

• docs/platform/DEPLOYMENT_GUIDE.md – high-level deployment guide (components, configuration, external dependencies).
• docs/platform/DEPLOYMENT_GUIDE_OPENSEARCH.md – OpenSearch-specific requirements. Use this only if you choose OpenSearch over the new PostgreSQL/pgvector option.
• docs/platform/REBAC.md – high-level access model (RBAC/ReBAC/organization/bootstrap).

The rest of this README.md focuses on local developer setup and model configuration.

Agent authoring (v2 SDK)

Fred 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.

The v2 SDK provides two authoring styles:

• 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.
• 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.

Both styles support MCP tool integration and run on the same runtime.

Start with the agent authoring guide (v2). For the design philosophy behind the SDK, see SDK V2 positioning.

Agent coding academy

The academy contains sample MCP servers and standalone applications to experiment with agent development outside the main platform. The fred-samples repository provides ready-to-run example pods built with fred-sdk + fred-runtime.

Advanced configuration

System Architecture

Platform applications:

Component	Location	Role
Frontend UI	./frontend	React chat UI (SSE streaming, rich markdown/math/Mermaid) and agent management UI
Knowledge Flow backend	./apps/knowledge-flow-backend	Document ingestion, vectorization, and retrieval
Control Plane backend	./apps/control-plane-backend	Teams, users, agent enrollment, session metadata, ExecutionGrant issuance

Agent pods:

Component	Location	Role
fred-agents	./apps/fred-agents	First-party agent pod — reference implementation and production execution surface
(your pod)	your repo	Any pod built with fred-sdk + fred-runtime and registered with the control plane

Shared libraries (published to PyPI):

Component	Location	Role
fred-pod	./libs/fred-pod/README.md	Pod floor — configuration, identity, naming
fred-core	./libs/fred-core	Shared infrastructure — SQL, KPI, security
fred-sdk	./libs/fred-sdk	Agent authoring SDK — contracts, graph, tools, HITL
fred-runtime	./libs/fred-runtime	Pod factory — FastAPI, SSE streaming, checkpointing, CLI
fred-capability-*	./libs/capabilities	First-party capabilities, one package each — a pod installs those it offers

Each package has its own version. From the repository root, prepare the next release from the previous stable code tag, then publish against PyPI:

make python-release-plan BASE_TAG=code/vX.Y.Z
make prepare-python-release BASE_TAG=code/vX.Y.Z \
  CAPABILITY_PACKAGES="fred-capability-documents" \
  CAPABILITY_MANIFESTS="libs/capabilities/fred-capability-documents/fred_capability_documents/document_summarize/capability.py"
make publish-libs-dry-run
PYPI_TOKEN=... make publish-libs

Select only changed capability packages and affected manifests; leave those arguments empty when none changed. fred-pod requires POD_CHANGED=true if its package changed. Review the version and lockfile diff before release approval. PyPI publication requires separate authorization. It uploads the packages whose version is above PyPI's latest and stops, before any upload, if a package at PyPI's latest version does not build the published wheel. See the release strategy for the full sequence.

agentic-backend (./agentic-backend) remains during migration. Do not add new features there.

Configuration Files

File	Purpose	Tip
apps/fred-agents/config/.env	Secrets (API keys, passwords). Not committed to Git.	Copy .env.template to .env and fill in any missing values.
apps/knowledge-flow-backend/config/.env	Same as above	Same as above
apps/control-plane-backend/config/.env	Same as above	Same as above
apps/fred-agents/config/models_catalog.yaml	Chat profiles, local default/agent overrides, provider settings.	Edit profiles and set default_profile_by_capability.chat.
apps/fred-agents/config/configuration.yaml	Pod runtime settings (base URL, feature flags, MCP catalog).	-
apps/knowledge-flow-backend/config/configuration.yaml	Chat/embedding/vision model settings, ingestion options.	-
apps/control-plane-backend/config/configuration.yaml	Team/user policy settings, runtime catalog sources.	-

Supported Model Providers

Provider	How to enable
OpenAI (default)	Add OPENAI_API_KEY to apps/fred-agents/config/.env; add a profile in models_catalog.yaml
Azure OpenAI	Add AZURE_OPENAI_API_KEY to .env; add a profile with provider: azure-openai in models_catalog.yaml
Azure OpenAI via Azure APIM	Add AZURE_APIM_SUBSCRIPTION_KEY and AZURE_AD_CLIENT_SECRET to .env; add profile with provider: azure-apim
Ollama (local models)	Add a profile with provider: openai and settings.base_url: <ollama-endpoint> in models_catalog.yaml

See apps/fred-agents/config/models_catalog.yaml and apps/knowledge-flow-backend/config/configuration.yaml (sections chat_model: and embedding_model:) for concrete examples. Full routing documentation: docs/platform/LLM_ROUTING_FRED.md.

Advanced Integrations

• Enable Keycloak or another OIDC provider for authentication

  Frontend security is backend-driven.
  The frontend first loads static /config.json, then calls the public control-plane /control-plane/v1/frontend/config endpoint for the effective user_auth and gcu_version values. Real Keycloak OIDC is enabled from the backend security.user configuration; when disabled for local dev, the frontend mints local dev tokens while keeping the same app code paths. Static branding stays in frontend config.json properties. See apps/frontend/README.md for details.

• Persistence options:

  • Laptop / dev (default): SQLite for metadata + ChromaDB for vectors (embedded, no external services)
  • Production: PostgreSQL + pgvector for metadata/vectors, and optionally MinIO/S3 + OpenSearch if you prefer that stack

Core Architecture and Licensing Clarity

The platform applications and the fred-agents pod form the default Fred deployment. By default they run self-contained on a laptop using SQLite + ChromaDB (no external services).

Fred is modular: you can optionally add Keycloak/OpenFGA, MinIO/S3, OpenSearch, and PostgreSQL/pgvector for production-grade persistence.

Persistence options:

• Dev/laptop (default): SQLite for all SQL stores, ChromaDB for vectors, local filesystem for blobs.
• Production (recommended): PostgreSQL + pgvector for SQL + vectors; optionally pair with MinIO/S3 + OpenSearch if you prefer that stack.

Documentation

• Generic information

  • Main docs
  • Features overview

• fred-agents pod and runtime libraries

  • fred-agents README
  • fred-runtime (pod factory)
  • fred-sdk (authoring SDK)
  • fred-core (shared infrastructure)

• Agent authoring (v2 SDK)

  • Agent authoring guide (v2)
  • SDK V2 positioning — design philosophy
  • V2 agent creation — React vs Graph

• Architecture RFCs

  • SDK V2 for industrial-grade agents
  • Agent-to-agent invocation — current contract (§14)
  • Multi-agent memory hardening

• Knowledge Flow backend

Licensing Note

Fred's own code is released under the Apache License 2.0. Optional integrations (like OpenSearch) are configured externally and do not contaminate Fred's licensing.

Fred currently depends on a small number of third-party Python packages under copyleft licenses, tracked under LICENSE-01/LICENSE-02/LICENSE-03. Full detail, severity assessment, and remediation status for each: docs/swift/COPYLEFT-DEPENDENCIES.md.

• pymupdf / pymupdf4llm are optional under AGPL-3.0 or Artifex commercial terms. The locked extra also includes pymupdf-layout, under PolyForm Noncommercial 1.0.0; it is not covered by an AGPL-only assessment. These packages are excluded from ordinary development installs and the standard Knowledge Flow image. See installation and deployment and issue #3159.
• psycopg2-binary / psycopg (PostgreSQL driver, fred-core / knowledge-flow-backend) — LGPL-3.0-only, used as an unmodified, dynamically imported package (not statically linked or embedded).
• jwcrypto (transitive, via python-keycloak's admin client, fred-core / control-plane-backend / knowledge-flow-backend / fred-agents) — LGPL-3.0-or-later, used as an unmodified, dynamically imported package; never directly invoked by Fred's own code (Fred's JWT verification path uses PyJWT).

If your use case requires a fully copyleft-free dependency tree, audit these packages before deployment.

See the LICENSE for more details.

Contributing

We welcome pull requests and issues. Start with the Contributing guide.

Community

Join the discussion on our Discord server!

Contacts

• [email protected]
• [email protected]
• [email protected]
• [email protected]