fred-pod 4.1.0__tar.gz

fred_pod-4.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,76 @@
+# 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/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-4.1.0/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-4.1.0/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-4.1.0/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")