fred-pod 4.1.0__py3-none-any.whl

fred_pod/__init__.py

@@ -0,0 +1,135 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+What a Fred component needs to *be* a pod: configuration, identity, naming.
+
+A Knowledge Base pod, a capability pod, an MCP server pod and an agent pod all
+read a `configuration.yaml`, get a machine-to-machine token and name things
+under a prefix they own. That floor is this distribution, and it depends on
+four third-party packages — pydantic, PyYAML, python-dotenv, httpx.
+
+"What do I need to run a Fred component?" → `fred-pod`.
+"What do I need to build an agent?" → `fred-core` / `fred-sdk`.
+
+Unlike `fred-core`, importing this package is cheap and stays cheap: a
+separate distribution cannot import what it does not depend on, so the
+boundary is enforced by the build rather than by discipline.
+"""
+
+from fred_pod.common.config_files import ConfigFiles
+from fred_pod.common.config_loader import (
+    TConfig,
+    get_config,
+    load_configuration_with_config_files,
+    parse_yaml_mapping_file,
+)
+from fred_pod.common.naming import (
+    CONTRIBUTED_NAME_PATTERN,
+    KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX,
+    MAX_NAME_CHARS,
+    PREFIX_PATTERN,
+    InvalidContributedName,
+    knowledge_base_catalog_id,
+    knowledge_base_name_from_catalog_id,
+    prefix_covers,
+    require_contributed_name,
+)
+from fred_pod.common.structures import (
+    BaseModelWithId,
+    DuckdbStoreConfig,
+    InMemoryStoreConfig,
+    KpiLogSinkConfig,
+    KpiObservabilityConfig,
+    KpiOpenSearchSinkConfig,
+    KpiPrometheusSinkConfig,
+    LogStoreConfig,
+    ModelConfiguration,
+    OpenSearchIndexConfig,
+    OpenSearchStoreConfig,
+    OwnerFilter,
+    PostgresStoreConfig,
+    PostgresTableConfig,
+    StoreConfig,
+    TemporalSchedulerConfig,
+)
+from fred_pod.security.backend_to_backend_auth import (
+    M2MAuthConfig,
+    M2MBearerAuth,
+    M2MTokenProvider,
+    make_m2m_asgi_client,
+)
+from fred_pod.security.structure import (
+    LOCAL_DEV_CLIENT_ID,
+    SERVICE_AGENT_ROLE,
+    KeycloakUser,
+    M2MSecurity,
+    OpenFgaRebacConfig,
+    RebacBaseConfig,
+    RebacConfiguration,
+    SecurityConfiguration,
+    UserSecurity,
+    is_service_agent,
+)
+
+__all__ = [
+    # Configuration
+    "ConfigFiles",
+    "TConfig",
+    "get_config",
+    "load_configuration_with_config_files",
+    "parse_yaml_mapping_file",
+    # Naming
+    "CONTRIBUTED_NAME_PATTERN",
+    "KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX",
+    "MAX_NAME_CHARS",
+    "PREFIX_PATTERN",
+    "InvalidContributedName",
+    "knowledge_base_catalog_id",
+    "knowledge_base_name_from_catalog_id",
+    "prefix_covers",
+    "require_contributed_name",
+    # Configuration models
+    "BaseModelWithId",
+    "DuckdbStoreConfig",
+    "InMemoryStoreConfig",
+    "KpiLogSinkConfig",
+    "KpiObservabilityConfig",
+    "KpiOpenSearchSinkConfig",
+    "KpiPrometheusSinkConfig",
+    "LogStoreConfig",
+    "ModelConfiguration",
+    "OpenSearchIndexConfig",
+    "OpenSearchStoreConfig",
+    "OwnerFilter",
+    "PostgresStoreConfig",
+    "PostgresTableConfig",
+    "StoreConfig",
+    "TemporalSchedulerConfig",
+    # Identity
+    "LOCAL_DEV_CLIENT_ID",
+    "SERVICE_AGENT_ROLE",
+    "KeycloakUser",
+    "M2MAuthConfig",
+    "M2MBearerAuth",
+    "M2MSecurity",
+    "M2MTokenProvider",
+    "OpenFgaRebacConfig",
+    "RebacBaseConfig",
+    "RebacConfiguration",
+    "SecurityConfiguration",
+    "UserSecurity",
+    "is_service_agent",
+    "make_m2m_asgi_client",
+]

fred_pod/common/__init__.py

@@ -0,0 +1,85 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Configuration, naming, and the models every component's configuration uses."""
+
+from fred_pod.common.config_files import ConfigFiles
+from fred_pod.common.config_loader import (
+    TConfig,
+    get_config,
+    load_configuration_with_config_files,
+    parse_yaml_mapping_file,
+)
+from fred_pod.common.naming import (
+    CONTRIBUTED_NAME_PATTERN,
+    KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX,
+    MAX_NAME_CHARS,
+    PREFIX_PATTERN,
+    InvalidContributedName,
+    knowledge_base_catalog_id,
+    knowledge_base_name_from_catalog_id,
+    prefix_covers,
+    require_contributed_name,
+)
+from fred_pod.common.structures import (
+    BaseModelWithId,
+    DuckdbStoreConfig,
+    InMemoryStoreConfig,
+    KpiLogSinkConfig,
+    KpiObservabilityConfig,
+    KpiOpenSearchSinkConfig,
+    KpiPrometheusSinkConfig,
+    LogStoreConfig,
+    ModelConfiguration,
+    OpenSearchIndexConfig,
+    OpenSearchStoreConfig,
+    OwnerFilter,
+    PostgresStoreConfig,
+    PostgresTableConfig,
+    StoreConfig,
+    TemporalSchedulerConfig,
+)
+
+__all__ = [
+    "CONTRIBUTED_NAME_PATTERN",
+    "KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX",
+    "MAX_NAME_CHARS",
+    "PREFIX_PATTERN",
+    "BaseModelWithId",
+    "ConfigFiles",
+    "DuckdbStoreConfig",
+    "InMemoryStoreConfig",
+    "InvalidContributedName",
+    "KpiLogSinkConfig",
+    "KpiObservabilityConfig",
+    "KpiOpenSearchSinkConfig",
+    "KpiPrometheusSinkConfig",
+    "LogStoreConfig",
+    "ModelConfiguration",
+    "OpenSearchIndexConfig",
+    "OpenSearchStoreConfig",
+    "OwnerFilter",
+    "PostgresStoreConfig",
+    "PostgresTableConfig",
+    "StoreConfig",
+    "TConfig",
+    "TemporalSchedulerConfig",
+    "get_config",
+    "knowledge_base_catalog_id",
+    "knowledge_base_name_from_catalog_id",
+    "load_configuration_with_config_files",
+    "parse_yaml_mapping_file",
+    "prefix_covers",
+    "require_contributed_name",
+]

fred_pod/common/config_files.py

@@ -0,0 +1,135 @@
+# Copyright Thales 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import logging
+import os
+
+from dotenv import load_dotenv
+
+
+class ConfigFiles:
+    """Resolve and track startup config paths for Fred backends.
+
+    Why this exists:
+    - Every backend starts the same way: load environment variables, then load a
+      YAML configuration file.
+    - Developers and operators should see the exact files that were used.
+
+    Example:
+    - `ENV_FILE=./config/.env.prod`
+    - `CONFIG_FILE=./config/configuration_prod.yaml`
+    """
+
+    def __init__(
+        self,
+        *,
+        logger: logging.Logger,
+        default_env_file: str = "./config/.env",
+        default_config_file: str = "./config/configuration.yaml",
+        env_var_name: str = "ENV_FILE",
+        config_var_name: str = "CONFIG_FILE",
+        log_prefix: str = "[CONFIG]",
+    ) -> None:
+        """Create a resolver with Fred defaults.
+
+        Example:
+        - Keep defaults for regular startup.
+        - Override `default_config_file` in tests to point to a fixture.
+        """
+        self._logger = logger
+        self._default_env_file = default_env_file
+        self._default_config_file = default_config_file
+        self._env_var_name = env_var_name
+        self._config_var_name = config_var_name
+        self._log_prefix = log_prefix
+        self._loaded_env_file_path: str | None = None
+        self._loaded_config_file_path: str | None = None
+
+    def get_loaded_env_file_path(self) -> str | None:
+        """Return the effective env file path used at runtime.
+
+        Example:
+        - Returns `./config/.env` when no override is provided.
+        - Returns `/etc/fred/agentic.env` in a production deployment override.
+        """
+        return self._loaded_env_file_path
+
+    def get_loaded_config_file_path(self) -> str | None:
+        """Return the effective YAML config file path used at runtime.
+
+        Example:
+        - `./config/configuration.yaml` in local mode.
+        - `./config/configuration_worker.yaml` for worker startup.
+        """
+        return self._loaded_config_file_path
+
+    def load_environment(self, dotenv_path: str | None = None) -> str:
+        """Load environment variables from the selected env file.
+
+        Selection order:
+        1. Explicit `dotenv_path` argument.
+        2. `ENV_FILE` environment variable.
+        3. Default `./config/.env`.
+
+        Example:
+        - Calling `load_environment()` with `ENV_FILE=./config/.env.prod`
+          loads production secrets and returns that path.
+        """
+        env_path = dotenv_path or os.getenv(self._env_var_name, self._default_env_file)
+        if load_dotenv(env_path):
+            self._logger.info(
+                "%s Loaded environment variables from: %s",
+                self._log_prefix,
+                env_path,
+            )
+        else:
+            self._logger.warning(
+                "%s No .env file found at: %s",
+                self._log_prefix,
+                env_path,
+            )
+        self._loaded_env_file_path = env_path
+        return env_path
+
+    def resolve_config_file_path(self, config_file: str | None = None) -> str:
+        """Resolve and validate the YAML configuration path.
+
+        Selection order:
+        1. Explicit `config_file` argument.
+        2. `CONFIG_FILE` environment variable.
+        3. Default `./config/configuration.yaml`.
+
+        Raises:
+        - `FileNotFoundError` if the resolved file does not exist.
+        """
+        resolved = config_file or os.getenv(
+            self._config_var_name, self._default_config_file
+        )
+        if not os.path.exists(resolved):
+            raise FileNotFoundError(f"Configuration file not found: {resolved}")
+        return resolved
+
+    def mark_config_loaded(self, config_file: str) -> None:
+        """Record and log the configuration file effectively loaded.
+
+        Example:
+        - After parsing `configuration_prod.yaml`, call this method so startup
+          logs and diagnostics expose the exact profile in use.
+        """
+        self._loaded_config_file_path = config_file
+        self._logger.info(
+            "%s Loaded configuration from: %s", self._log_prefix, config_file
+        )

fred_pod/common/config_loader.py

@@ -0,0 +1,91 @@
+# Copyright Thales 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import sys
+from typing import Callable, TypeVar
+
+import yaml
+from pydantic import ValidationError
+
+from .config_files import ConfigFiles
+
+TConfig = TypeVar("TConfig")
+
+
+def _render_config_error_banner(config_file: str, error: Exception) -> None:
+    """Print a loud, unmissable configuration-error banner to stderr.
+
+    A misconfigured service must not start silently and fail later with an
+    opaque error inside a request handler. We surface the root cause in red at
+    startup. Colours are emitted only on a TTY so log files stay clean.
+    """
+    use_colour = sys.stderr.isatty()
+    red = "\033[1;31m" if use_colour else ""
+    reset = "\033[0m" if use_colour else ""
+    bar = "=" * 78
+
+    if isinstance(error, ValidationError):
+        details = "\n".join(
+            f"  - {' -> '.join(str(p) for p in err['loc']) or '(root)'}: {err['msg']}"
+            for err in error.errors()
+        )
+    else:
+        details = f"  - {error}"
+
+    print(
+        f"\n{red}{bar}\n"
+        f"  CONFIGURATION ERROR — refusing to start\n"
+        f"  file: {config_file}\n"
+        f"{bar}{reset}\n"
+        f"{details}\n"
+        f"{red}{bar}{reset}\n",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def parse_yaml_mapping_file(config_file: str) -> dict:
+    """Load a YAML file and ensure it is a non-empty mapping."""
+    with open(config_file, encoding="utf-8") as file:
+        payload = yaml.safe_load(file)
+    if payload is None:
+        raise ValueError(f"Configuration file is empty: {config_file}")
+    if not isinstance(payload, dict):
+        raise ValueError(f"Configuration file must be a mapping object: {config_file}")
+    return payload
+
+
+def load_configuration_with_config_files(
+    config_files: ConfigFiles,
+    parser: Callable[[str], TConfig],
+    dotenv_path: str | None = None,
+) -> TConfig:
+    """Load env + config path using ConfigFiles and parse via callback."""
+    config_files.load_environment(dotenv_path)
+    config_file = config_files.resolve_config_file_path()
+    try:
+        configuration = parser(config_file)
+    except (ValidationError, ValueError) as exc:
+        # Render the root cause in red and stop, rather than letting an opaque
+        # traceback (or a deferred runtime 401) bury what is wrong.
+        _render_config_error_banner(config_file, exc)
+        raise SystemExit(1) from exc
+    config_files.mark_config_loaded(config_file)
+    return configuration
+
+
+def get_config():
+    raise NotImplementedError("This dependency have to be override by the backend")

fred_pod/common/naming.py

@@ -0,0 +1,110 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+How everything a contributor adds to Fred is named.
+
+One rule for agents, Knowledge Bases and applications: a dotted name under a
+prefix its contributor owns — `fred.github.assistant`, `fred.samples.local-folder`,
+`thales.prism.triage`. Uniqueness comes from owning the prefix, the way Java
+packages and Maven group ids work, so no registry has to be kept and no operator
+arbitrates a name.
+
+Ownership is a prefix test, never a split: a name is not cut into parts, it is
+checked against the prefixes a caller owns. That is why no separator is needed,
+and why prefixes may be of any depth.
+
+Full rationale: docs/swift/platform/CONFIGURATION_AND_POLICY_CONVENTIONS.md
+"""
+
+from __future__ import annotations
+
+import re
+
+# A run of letters/digits, then any number of single-separator groups. Written
+# this way so the pattern alone rejects a leading, trailing or doubled separator
+# — `a__b`, `a--b`, `-a`, `a_` — without a second check a caller could forget.
+_SEGMENT = r"[a-z0-9]+(?:[_-][a-z0-9]+)*"
+
+#: A prefix a contributor owns. One segment or more: `fred`, `fred.samples`.
+PREFIX_PATTERN = rf"^{_SEGMENT}(?:\.{_SEGMENT})*$"
+
+#: A contributed name. Two segments or more: a prefix, then what it names.
+CONTRIBUTED_NAME_PATTERN = rf"^{_SEGMENT}(?:\.{_SEGMENT})+$"
+
+MAX_NAME_CHARS = 255
+
+_NAME_RE = re.compile(CONTRIBUTED_NAME_PATTERN)
+
+
+class InvalidContributedName(ValueError):
+    """Raised when a name or prefix does not follow the contributor rule."""
+
+
+def require_contributed_name(name: str) -> str:
+    """Return the name, or say precisely why it cannot be one."""
+    if len(name) > MAX_NAME_CHARS:
+        raise InvalidContributedName(
+            f"name is longer than {MAX_NAME_CHARS} characters: {name!r}"
+        )
+    if "__" in name:
+        raise InvalidContributedName(
+            f"name must not contain a double underscore: {name!r}"
+        )
+    if _NAME_RE.match(name) is None:
+        raise InvalidContributedName(
+            "name must be lowercase dotted segments, at least two, each starting "
+            f"and ending on a letter or digit: {name!r}"
+        )
+    return name
+
+
+def prefix_covers(prefix: str, name: str) -> bool:
+    """Whether a client owning `prefix` may write `name`.
+
+    A segment boundary is required, so owning `fred.sample` does not reach
+    `fred.samples.local-folder`. Kept as one function because the dispatching
+    side and the publishing side must decide this identically.
+    """
+    return name == prefix or name.startswith(f"{prefix}.")
+
+
+#: The key prefix Knowledge Base definitions reserve in the shared catalog.
+KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX = "kb__"
+
+
+def knowledge_base_catalog_id(name: str) -> str:
+    """Return the key this definition takes in the shared administration catalog.
+
+    The catalog is one flat dictionary shared with capabilities, agents and
+    applications, so each kind reserves a prefix and no two kinds can collide in
+    it. That prefix is an internal key, never part of the contributed name.
+    """
+
+    return f"{KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX}{name}"
+
+
+def knowledge_base_name_from_catalog_id(catalog_id: str) -> str:
+    """Return the contributed name a catalog key carries.
+
+    A removal, not a split: the name keeps whatever depth its contributor chose,
+    and nothing here has to guess where a prefix ends.
+    """
+
+    if not catalog_id.startswith(KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX):
+        raise ValueError(f"Not a Knowledge Base catalog id: {catalog_id!r}")
+    name = catalog_id[len(KNOWLEDGE_BASE_CATALOG_NAMESPACE_PREFIX) :]
+    if not name:
+        raise ValueError(f"Knowledge Base catalog id carries no name: {catalog_id!r}")
+    return name

fred_pod/common/structures.py

@@ -0,0 +1,247 @@
+# Copyright Thales 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from enum import Enum
+from typing import Annotated, Any, Dict, Literal, Optional, Union
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class OwnerFilter(str, Enum):
+    """Filter resources by ownership type.
+
+    - PERSONAL: resources where the user is directly owner/editor/viewer (not via team)
+    - TEAM: resources owned by a specific team (requires team_id parameter)
+    """
+
+    PERSONAL = "personal"
+    TEAM = "team"
+
+
+class BaseModelWithId(BaseModel):
+    id: str
+
+
+class TemporalSchedulerConfig(BaseModel):
+    host: str = "localhost:7233"
+    namespace: str = "default"
+    task_queue: str = "default"
+    workflow_id_prefix: str = "task"
+    connect_timeout_seconds: Optional[int] = 5
+    rpc_timeout_seconds: Optional[int] = Field(
+        default=10,
+        description="Deadline applied to individual Temporal RPC calls (start_workflow, describe) "
+        "so a stuck Temporal frontend cannot hang the caller indefinitely.",
+    )
+    ingestion_workflow_parallelism: int = Field(
+        default=3,
+        ge=1,
+        description="Max number of files launched in parallel per parent ingestion workflow.",
+    )
+    ingestion_max_concurrent_workflow_tasks: int = Field(
+        default=3,
+        ge=1,
+        description="Max concurrent Temporal workflow tasks processed by a worker process.",
+    )
+    ingestion_max_concurrent_activities: int = Field(
+        default=3,
+        ge=1,
+        description="Max concurrent Temporal activities processed by a worker process.",
+    )
+
+
+class ModelConfiguration(BaseModel):
+    provider: Optional[str] = Field(
+        None, description="Provider of the AI model, e.g., openai, ollama, azure."
+    )
+    name: Optional[str] = Field(None, description="Model name, e.g., gpt-4o, llama2.")
+    settings: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description=(
+            "Additional provider-specific settings, "
+            "e.g. Azure endpoint/API version or Vertex AI project/location."
+        ),
+    )
+
+
+class OpenSearchStoreConfig(BaseModel):
+    host: str = Field(..., description="OpenSearch host URL")
+    username: str = Field(..., description="Username from env")
+    password: Optional[str] = Field(
+        default_factory=lambda: os.getenv("OPENSEARCH_PASSWORD"),
+        description="Password from env",
+    )
+    secure: bool = Field(default=False, description="Use TLS (https)")
+    verify_certs: bool = Field(default=False, description="Verify TLS certs")
+
+    @model_validator(mode="after")
+    def _require_password(self) -> "OpenSearchStoreConfig":
+        """Fail fast at config load if OpenSearch is configured without credentials.
+
+        Reaching this validator means a ``storage.opensearch`` block is present in
+        the active configuration, so the service genuinely depends on OpenSearch.
+        A missing password only surfaces later as an opaque HTTP 401 deep inside a
+        request handler — we convert it into an actionable startup failure instead.
+        """
+        if not self.password:
+            raise ValueError(
+                f"OpenSearch is configured (host={self.host!r}, username="
+                f"{self.username!r}) but no password was provided. "
+                "Set the OPENSEARCH_PASSWORD environment variable (in your .env) "
+                "to the OpenSearch password for this user, or remove the "
+                "storage.opensearch block if OpenSearch is not used."
+            )
+        return self
+
+
+class OpenSearchIndexConfig(BaseModel):
+    type: Literal["opensearch"]
+    index: str = Field(..., description="OpenSearch index name")
+
+
+class LogStoreConfig(BaseModel):
+    type: Literal["log"]
+    level: str = Field(..., description="Logging level")
+
+
+class DuckdbStoreConfig(BaseModel):
+    type: Literal["duckdb"]
+    duckdb_path: str = Field(..., description="Path to the DuckDB database file.")
+
+
+class PostgresStoreConfig(BaseModel):
+    type: Literal["postgres"] = "postgres"
+    host: Optional[str] = Field(default=None, description="PostgreSQL host")
+    port: int = 5432
+    sqlite_path: Optional[str] = Field(
+        default=None,
+        description="Path to the SQLite database file (for local dev/testing).",
+    )
+    database: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = Field(
+        default_factory=lambda: os.getenv("FRED_POSTGRES_PASSWORD")
+    )
+    echo: bool = Field(default=False, description="SQLAlchemy echo flag.")
+    pool_size: Optional[int] = Field(
+        default=None, description="Optional pool size for the engine."
+    )
+    max_overflow: Optional[int] = Field(
+        default=None,
+        description="Optional max_overflow for SQLAlchemy pool (defaults to SQLAlchemy's 10 if unset).",
+    )
+    pool_timeout: Optional[int] = Field(
+        default=None,
+        description="Seconds to wait for a connection from the pool before timing out.",
+    )
+    pool_recycle: Optional[int] = Field(
+        default=None,
+        description="Recycle connections after this many seconds (prevents stale TCP / server timeouts).",
+    )
+    pool_pre_ping: Optional[bool] = Field(
+        default=None,
+        description="Enable SQLAlchemy pool_pre_ping to evict stale connections.",
+    )
+    connect_args: Optional[dict[str, Any]] = Field(
+        default=None, description="Optional connect_args passed to SQLAlchemy."
+    )
+
+    def dsn(self) -> str:
+        return f"postgresql://{self.username}:{self.password}@{self.host}:{self.port}/{self.database}"
+
+    def async_dsn(self) -> str:
+        return f"postgresql+asyncpg://{self.username}:{self.password}@{self.host}:{self.port}/{self.database}"
+
+
+class PostgresTableConfig(BaseModel):
+    # Allow reusing the same table-oriented config for local SQLite runs.
+    type: Literal["postgres"]
+    table: Optional[str] = Field(
+        default=None,
+        description="Table name used by the store. Deprecated: stores now use fixed table names.",
+    )
+    prefix: Optional[str] = Field(
+        default=None,
+        description="Optional prefix applied to the table name. Deprecated: stores now use fixed table names.",
+    )
+
+
+class InMemoryStoreConfig(BaseModel):
+    """
+    Minimal config for in-memory stores (dev/test only).
+    """
+
+    type: Literal["memory"] = "memory"
+
+
+StoreConfig = Annotated[
+    Union[
+        DuckdbStoreConfig,
+        OpenSearchIndexConfig,
+        LogStoreConfig,
+        PostgresTableConfig,
+        InMemoryStoreConfig,
+    ],
+    Field(discriminator="type"),
+]
+
+
+# ---------------------------------------------------------------------------
+# KPI observability config — shared across all backends
+# ---------------------------------------------------------------------------
+
+
+class KpiLogSinkConfig(BaseModel):
+    enabled: bool = False
+    level: str = "info"
+    summary_interval_sec: float = 0.0
+    summary_top_n: int = 0
+
+
+class KpiPrometheusSinkConfig(BaseModel):
+    enabled: bool = True
+    port: int = 9000
+    address: str = "127.0.0.1"
+
+
+class KpiOpenSearchSinkConfig(BaseModel):
+    enabled: bool = True
+    index: str = "kpi-index"
+
+
+class KpiObservabilityConfig(BaseModel):
+    """
+    KPI sink configuration shared across all Fred backends.
+
+    Defaults enable Prometheus + OpenSearch (prod-ready out of the box).
+    For local dev, disable both and enable log instead:
+
+        observability:
+          kpi:
+            log:
+              enabled: true
+            prometheus:
+              enabled: false
+            opensearch:
+              enabled: false
+    """
+
+    log: KpiLogSinkConfig = Field(default_factory=KpiLogSinkConfig)
+    prometheus: KpiPrometheusSinkConfig = Field(default_factory=KpiPrometheusSinkConfig)
+    opensearch: KpiOpenSearchSinkConfig = Field(default_factory=KpiOpenSearchSinkConfig)
+    process_metrics_interval_sec: int = Field(
+        default=10,
+        description="Emit process/SQL-pool KPIs every N seconds. 0 to disable.",
+    )

fred_pod/security/__init__.py

@@ -0,0 +1,51 @@
+# Copyright Thales 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Identity: who a pod is to Fred, and who a caller is to a pod."""
+
+from fred_pod.security.backend_to_backend_auth import (
+    M2MAuthConfig,
+    M2MBearerAuth,
+    M2MTokenProvider,
+    make_m2m_asgi_client,
+)
+from fred_pod.security.structure import (
+    LOCAL_DEV_CLIENT_ID,
+    SERVICE_AGENT_ROLE,
+    KeycloakUser,
+    M2MSecurity,
+    OpenFgaRebacConfig,
+    RebacBaseConfig,
+    RebacConfiguration,
+    SecurityConfiguration,
+    UserSecurity,
+    is_service_agent,
+)
+
+__all__ = [
+    "LOCAL_DEV_CLIENT_ID",
+    "SERVICE_AGENT_ROLE",
+    "KeycloakUser",
+    "M2MAuthConfig",
+    "M2MBearerAuth",
+    "M2MSecurity",
+    "M2MTokenProvider",
+    "OpenFgaRebacConfig",
+    "RebacBaseConfig",
+    "RebacConfiguration",
+    "SecurityConfiguration",
+    "UserSecurity",
+    "is_service_agent",
+    "make_m2m_asgi_client",
+]

fred_pod/security/backend_to_backend_auth.py

@@ -0,0 +1,152 @@
+# Copyright Thales 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+import typing as t
+
+import httpx
+from httpx import Request, Response
+from pydantic import BaseModel
+
+# The shape httpx.ASGITransport accepts. Any ASGI application qualifies —
+# FastAPI is one — and naming it this way keeps FastAPI out of the pod floor.
+_ASGIMessage = t.MutableMapping[str, t.Any]
+ASGIApp = t.Callable[
+    [
+        _ASGIMessage,
+        t.Callable[[], t.Awaitable[_ASGIMessage]],
+        t.Callable[[_ASGIMessage], t.Awaitable[None]],
+    ],
+    t.Awaitable[None],
+]
+
+# A tool or pod calling a Fred API has no user bearer, so it needs a service
+# token (client_credentials) or the call 401s. It lives in fred-pod because every
+# pod needs it and none should install the agents platform to get it.
+
+
+class M2MAuthConfig(BaseModel):
+    """
+    Minimal config for client-credentials flow.
+    keycloak_realm_url: the *realm* URL, same one you already use for JWKS
+                        (e.g., https://kc.example/realms/myrealm)
+    client_id:          confidential client ID (e.g., "knowledge")
+    secret_env:         env var name that stores the client secret (e.g., "KEYCLOAK_KNOWLEDGE_FLOW_CLIENT_SECRET")
+    scope:              optional Keycloak scopes (rarely needed)
+    """
+
+    keycloak_realm_url: str
+    client_id: str
+    secret_env: str
+    scope: str | None = None
+
+    @property
+    def token_url(self) -> str:
+        # Mirrors how you compute JWKS: realm/protocol/openid-connect/token
+        return f"{self.keycloak_realm_url}/protocol/openid-connect/token"
+
+
+class M2MTokenProvider:
+    """
+    Caches and refreshes a Keycloak client-credentials token.
+    Thread-safe (async) and cheap to reuse across calls.
+    """
+
+    def __init__(self, cfg: M2MAuthConfig):
+        self.cfg = cfg
+        self._secret = os.getenv(cfg.secret_env, "")
+        self._lock = asyncio.Lock()
+        self._token: str | None = None
+        self._exp: int = 0  # epoch seconds
+
+    async def get_token(self) -> str:
+        now = int(time.time())
+        if self._token and now < self._exp - 30:
+            return self._token
+
+        async with self._lock:
+            # double-check inside lock
+            now = int(time.time())
+            if self._token and now < self._exp - 30:
+                return self._token
+
+            if not self._secret:
+                # Fail fast: missing secret will otherwise cause confusing 401s
+                raise RuntimeError(
+                    f"Missing Keycloak client secret in env: {self.cfg.secret_env}"
+                )
+
+            form = {
+                "grant_type": "client_credentials",
+                "client_id": self.cfg.client_id,
+                "client_secret": self._secret,
+            }
+            if self.cfg.scope:
+                form["scope"] = self.cfg.scope
+
+            async with httpx.AsyncClient(timeout=10.0) as c:
+                r = await c.post(self.cfg.token_url, data=form)
+                r.raise_for_status()
+                payload = r.json()
+
+            token = payload.get("access_token")
+            expires_in = int(payload.get("expires_in", 60))
+
+            if not isinstance(token, str) or not token:
+                raise RuntimeError("Auth server did not return a valid access_token")
+
+            self._token = token
+            self._exp = now + expires_in
+
+            # Guarantee to the outside world that we return str
+            assert self._token is not None
+            return self._token
+
+
+class M2MBearerAuth(httpx.Auth):
+    """
+    httpx.Auth that injects 'Authorization: Bearer <service_token>'.
+
+    Important: httpx expects an *async generator* here. We yield the request
+    after mutating headers, which avoids the common type errors.
+    """
+
+    requires_request_body = True
+    requires_response_body = False
+
+    def __init__(self, provider: M2MTokenProvider):
+        self._provider = provider
+
+    async def async_auth_flow(
+        self, request: Request
+    ) -> t.AsyncGenerator[Request, Response]:
+        token = await self._provider.get_token()
+        request.headers["Authorization"] = f"Bearer {token}"
+        yield request  # httpx performs the request; we don't need the response hook here.
+
+
+def make_m2m_asgi_client(app: ASGIApp, auth: httpx.Auth) -> httpx.AsyncClient:
+    """
+    In-process client for self-calls via ASGITransport (no network).
+    """
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app, raise_app_exceptions=False),
+        base_url="http://apiserver",
+        timeout=15.0,
+        auth=auth,
+    )

fred_pod/security/structure.py

@@ -0,0 +1,153 @@
+# Copyright Thales 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Annotated, List, Literal, Union
+
+from pydantic import AnyHttpUrl, AnyUrl, BaseModel, Field
+
+
+class KeycloakUser(BaseModel):
+    """Represents an authenticated Keycloak user."""
+
+    uid: str
+    username: str
+    roles: list[str]
+    email: str | None = None
+    client_id: str | None = Field(
+        default=None,
+        description=(
+            "The token's authorized party (`azp`). Set for a client-credentials "
+            "identity, so a caller can be checked against one exact client "
+            "rather than a broad service role."
+        ),
+    )
+
+    def __repr_args__(self):
+        # Directly identifying data must never reach a log line, and an
+        # f-string/log call interpolating this model (or anything containing
+        # it) goes through repr — not model_dump() — so redacting here, not
+        # only at each log call site, is what actually closes the leak
+        # (docs/swift/platform/OBSERVABILITY-AND-AUDIT.md §7: "Directly
+        # identifying | user email, full name | Nowhere"). Explicit `.email`
+        # access for a genuine need (e.g. sending mail) is unaffected — this
+        # only changes str()/repr().
+        for name, value in super().__repr_args__():
+            yield (name, "<redacted>" if name == "email" and value else value)
+
+
+# Keycloak app role carried by backend service identities (agentic, knowledge-flow,
+# control-plane, and the evaluation worker). Identity marker, not a ReBAC relation:
+# nothing is stored in OpenFGA for it.
+SERVICE_AGENT_ROLE = "service_agent"
+
+# The `azp` a mock user carries when authentication is disabled, so routes
+# gated on an exact client stay reachable in local development.
+LOCAL_DEV_CLIENT_ID = "local-dev"
+
+
+def is_service_agent(user: KeycloakUser) -> bool:
+    """Return True when the caller is a service identity (holds ``service_agent``).
+
+    Identity predicate on the JWT (reads ``user.roles``) — not a ReBAC check.
+    Used by execution-authorization enforcement points (fred-runtime and the
+    control-plane) to recognize the evaluation worker for team ``can_read``,
+    scoped to the request ``team_id`` (RFC EVAL-AUTH, Solution A). No OpenFGA
+    tuple links the service to a team.
+    """
+    return SERVICE_AGENT_ROLE in (user.roles or [])
+
+
+class M2MSecurity(BaseModel):
+    """Configuration for machine-to-machine authentication."""
+
+    enabled: bool = True
+    realm_url: AnyUrl
+    client_id: str
+    audience: str | None = None
+    secret_env_var: str = "M2M_CLIENT_SECRET"
+
+
+class UserSecurity(BaseModel):
+    """Configuration for user authentication."""
+
+    enabled: bool = True
+    realm_url: AnyUrl
+    client_id: str
+
+
+class RebacBaseConfig(BaseModel):
+    enabled: bool = Field(
+        default=True,
+        description="To disable ReBAC checks (do not disable in production). If OIDC (UserSecurity and M2MSecurity) ReBAC check will be disabled even if this is true.",
+    )
+
+
+class OpenFgaRebacConfig(RebacBaseConfig):
+    """Configuration for an OpenFGA-backed relationship engine."""
+
+    type: Literal["openfga"] = "openfga"
+    api_url: AnyHttpUrl = Field(
+        ...,
+        description="Base URL for the OpenFGA HTTP API (e.g. https://fga.example.com)",
+    )
+    store_name: str = Field(
+        default="fred", description="Name of the OpenFGA store to use"
+    )
+    authorization_model_id: str | None = Field(
+        default=None,
+        description="Optional authorization model ID to use for read operations. Will be overridden if sync_schema_on_init is True.",
+    )
+    create_store_if_needed: bool = Field(
+        default=True,
+        description="Create the OpenFGA store if it does not already exist",
+    )
+    sync_schema_on_init: bool = Field(
+        default=True,
+        description="Synchronize the authorization model when creating the engine",
+    )
+    token_env_var: str = Field(
+        default="OPENFGA_API_TOKEN",
+        description="Environment variable that stores the OpenFGA API token",
+    )
+    timeout_millisec: int | None = Field(
+        default=5000,
+        description=(
+            "Timeout in milliseconds for OpenFGA API requests. Defaults to 5000 so a "
+            "stalled OpenFGA call fails fast with an error instead of hanging the request "
+            "indefinitely (set to None only to explicitly disable the timeout)."
+        ),
+    )
+    headers: dict[str, str] | None = Field(
+        default=None,
+        description="Static HTTP headers to send with each OpenFGA API request",
+    )
+
+
+RebacConfiguration = Annotated[Union[OpenFgaRebacConfig], Field(discriminator="type")]
+
+
+class SecurityConfiguration(BaseModel):
+    m2m: M2MSecurity
+    user: UserSecurity
+    authorized_origins: List[AnyHttpUrl] = []
+    rebac: RebacConfiguration | None = None
+    profile: Literal["c3"] | None = Field(
+        default=None,
+        description=(
+            "Hardened security profile (RUNTIME-07). 'c3' forces strict JWT "
+            "issuer/audience validation, forbids no-security/mock-admin, and "
+            "requires OpenFGA ReBAC enabled (pod-side authorization, fail-closed) "
+            "— failing startup otherwise. The control-plane issues no signed grant."
+        ),
+    )

fred_pod-4.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: fred-pod
+Version: 4.1.0
+Summary: What a Fred component needs to be a pod: configuration, identity, naming.
+Author-email: Thales <noreply@thalesgroup.com>
+License: Apache-2.0
+Project-URL: Homepage, https://site.fredlab.dev
+Project-URL: Repository, https://github.com/ThalesGroup/fred
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3.0.0,>=2.5.2
+Requires-Dist: python-dotenv<2.0.0,>=1.0.1
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: dev
+Requires-Dist: bandit>=1.8.6; extra == "dev"
+Requires-Dist: basedpyright==1.31.0; extra == "dev"
+Requires-Dist: detect-secrets>=1.5.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Requires-Dist: pytest-socket>=0.7.0; extra == "dev"
+Requires-Dist: ruff<0.16,>=0.12.5; extra == "dev"
+
+# fred-pod
+
+What a Fred component needs to *be* a pod: **configuration, identity, naming**.
+
+A Knowledge Base pod, a capability pod, an MCP server pod and an agent pod all read a
+`configuration.yaml`, get a machine-to-machine token, and name things under a prefix they
+own. That floor is this distribution.
+
+| Question | Answer |
+| --- | --- |
+| What do I need to *run* a Fred component? | `fred-pod` |
+| What do I need to *build an agent*? | `fred-core` / `fred-sdk` |
+
+## Why it is its own distribution
+
+`fred-core` declares 31 runtime dependencies — pandas, pyarrow, google-cloud-storage, minio,
+opensearch-py, sqlalchemy, asyncpg, azure-identity, fastapi, and a client for every LLM
+provider. That is the right list for the agents/LLM platform `fred-core` is. It is the wrong
+list for a pod whose job is one PROPFIND and a few GETs.
+
+Extras were the obvious alternative and were rejected for one reason: **a boundary the build
+does not enforce erodes.** `fred-core` reached 31 dependencies precisely because nothing
+stopped it. Nothing would stop an `import pandas` landing in `structures.py` next month
+either, and nobody would notice. A separate distribution cannot import what it does not
+depend on — the rule keeps itself.
+
+It showed its worth immediately: `config_loader.py` has always done `import yaml`, and
+`fred-core` never declared PyYAML. It worked because something else happened to pull it in.
+Here it is declared, because here it had to be.
+
+## The dependency list is the contract
+
+```
+pydantic   python-dotenv   pyyaml   httpx
+```
+
+Four packages. Adding a fifth is a decision someone makes on purpose, in a diff, and that is
+the whole point. If a change to this library needs a heavier import, the change belongs in
+`fred-core`, not here.
+
+## Layout
+
+```
+fred_pod/
+├── common/
+│   ├── naming.py          contributed names, prefixes, catalog ids
+│   ├── structures.py      configuration models (scheduler, stores, KPI sinks)
+│   ├── config_files.py    resolving configuration.yaml and its .env
+│   └── config_loader.py   loading and validating it into a Pydantic model
+└── security/
+    ├── structure.py                security configuration models, KeycloakUser
+    └── backend_to_backend_auth.py  M2M token provider and httpx auth
+```
+
+The paths mirror `fred_core`'s on purpose: a call site migrates by swapping the prefix
+`fred_core.` → `fred_pod.` and nothing else.
+
+## Compatibility
+
+`fred-core` depends on `fred-pod` and re-exports every name it moved, at both the package
+top level and the original submodule paths. Existing code keeps working unchanged; imports
+migrate opportunistically.
+
+```python
+from fred_pod import ConfigFiles, KeycloakUser, M2MTokenProvider
+from fred_pod.common.naming import require_contributed_name
+```
+
+## Development
+
+```
+make dev            # install with the local monorepo checkout
+make test           # offline unit tests
+make code-quality   # ruff, bandit, detect-secrets, basedpyright
+make publish        # build and upload to PyPI (needs PYPI_TOKEN)
+```

fred_pod-4.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+fred_pod/__init__.py,sha256=PyNu6l2xjpROtOn3eWjRSFGDMq2z7mc8X22UAGZ3Vu0,3881
+fred_pod/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fred_pod/common/__init__.py,sha256=eOkTJhuesdiRFLbj1oKuYi9GU16tMoYh35yzSstTxL8,2431
+fred_pod/common/config_files.py,sha256=5ZV2FAEhZe7ZrfbJGngNjXHorNCtmm33PznAlbnbNvs,4743
+fred_pod/common/config_loader.py,sha256=F4ZezOU84GZIiJvrs7b-CtH-tIsYTClpWJF1Tyi8oJY,3133
+fred_pod/common/naming.py,sha256=UDmfG-QGIHGDa7CYJGN5dREP5HDfKlQ-_2JURXq1vPQ,4260
+fred_pod/common/structures.py,sha256=OukWTTsFTKuCnAG27OdvvjBeJ-MTZwl-OLsOh0-K7Hk,8517
+fred_pod/security/__init__.py,sha256=qVwrfjp_9z-pM8M2SvPXE3baCjAJiN1-oN9z577Zyx0,1397
+fred_pod/security/backend_to_backend_auth.py,sha256=YDW15IntxdQ6OAKD6IGH8MUz6yvS28PakR5I13ls5Bs,5150
+fred_pod/security/structure.py,sha256=hWqsGeq295t4Ht9QY_KrLeDBuYGf7ZKa7RIU0egEn_c,5770
+fred_pod-4.1.0.dist-info/METADATA,sha256=bxcow3PfiwMX9o87ANgWQJB_9rfrxMAuoMsbAE6mawE,4225
+fred_pod-4.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fred_pod-4.1.0.dist-info/top_level.txt,sha256=tmTvVg6fqlDopKUFNmXfWd5VG5I2kG6sJc5oyJtCgOY,9
+fred_pod-4.1.0.dist-info/RECORD,,

fred_pod-4.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fred_pod-4.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fred_pod