fred-core 2.0.2__tar.gz → 2.0.4__tar.gz

{fred_core-2.0.2 → fred_core-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-core
-Version: 2.0.2
+Version: 2.0.4
 Summary: Core shared utilities for Fred backends (config, storage, security, and runtime helpers).
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -55,26 +55,26 @@ Requires-Dist: ruff>=0.12.5; extra == "dev"
 `fred-core` is the shared utility layer for Fred backends. It centralizes the
 foundational building blocks that must stay consistent across services.
 
-What it provides
-----------------
+## What it provides
+
 - Configuration helpers used by multiple backends.
 - Storage and session primitives.
 - Security and access-control utilities (ReBAC helpers, Keycloak helpers).
 - Common runtime helpers (logging, KPI, scheduling utilities).
 
-What it is not
--------------
+## What it is not
+
 - A full runtime or service on its own.
 - A public SDK for agent authoring (that is `fred-sdk`).
 
-Install
--------
+## Install
+
 ```bash
 pip install fred-core
 ```
 
-Usage (example)
----------------
+## Usage (example)
+
 Fred backends import shared helpers from `fred_core` to keep configuration and
 behavior aligned:
 
@@ -89,9 +89,15 @@ env_path = config_files.load_environment()
 yaml_path = config_files.resolve_config_file_path()
 ```
 
-Notes
------
+## Notes
+
 `fred-core` is designed for internal Fred services and adapters. If you are
 building agents or workflows, you likely want `fred-sdk` instead. In most
 cases, end users should not install `fred-core` directly because it is pulled
 in transitively by `fred-sdk`.
+
+## Development validation
+
+- `make test` runs the default offline test suite.
+- `make coverage-offline` runs the canonical offline coverage command with
+  terminal missing-line output.

{fred_core-2.0.2 → fred_core-2.0.4}/README.md

@@ -3,26 +3,26 @@
 `fred-core` is the shared utility layer for Fred backends. It centralizes the
 foundational building blocks that must stay consistent across services.
 
-What it provides
-----------------
+## What it provides
+
 - Configuration helpers used by multiple backends.
 - Storage and session primitives.
 - Security and access-control utilities (ReBAC helpers, Keycloak helpers).
 - Common runtime helpers (logging, KPI, scheduling utilities).
 
-What it is not
--------------
+## What it is not
+
 - A full runtime or service on its own.
 - A public SDK for agent authoring (that is `fred-sdk`).
 
-Install
--------
+## Install
+
 ```bash
 pip install fred-core
 ```
 
-Usage (example)
----------------
+## Usage (example)
+
 Fred backends import shared helpers from `fred_core` to keep configuration and
 behavior aligned:
 
@@ -37,9 +37,15 @@ env_path = config_files.load_environment()
 yaml_path = config_files.resolve_config_file_path()
 ```
 
-Notes
------
+## Notes
+
 `fred-core` is designed for internal Fred services and adapters. If you are
 building agents or workflows, you likely want `fred-sdk` instead. In most
 cases, end users should not install `fred-core` directly because it is pulled
 in transitively by `fred-sdk`.
+
+## Development validation
+
+- `make test` runs the default offline test suite.
+- `make coverage-offline` runs the canonical offline coverage command with
+  terminal missing-line output.

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/common/__init__.py

@@ -31,7 +31,6 @@ from .structures import (
     OwnerFilter,
     PostgresStoreConfig,
     PostgresTableConfig,
-    SQLStorageConfig,
     StoreConfig,
     TemporalSchedulerConfig,
 )
@@ -49,7 +48,6 @@ __all__ = [
     "OwnerFilter",
     "PostgresStoreConfig",
     "PostgresTableConfig",
-    "SQLStorageConfig",
     "StoreConfig",
     "TeamId",
     "PERSONAL_TEAM_ID",

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/common/fastapi_handlers.py

@@ -54,7 +54,7 @@ def register_exception_handlers(app: FastAPI) -> None:
         request: Request, exc: AuthorizationError
     ) -> JSONResponse:
         """Handle AuthorizationError by returning a 403 Forbidden response."""
-        logger.warning(f"Authorization denied for user {exc.user_id}: {exc}")
+        logger.warning("Authorization denied for user %s: %s", exc.user_id, exc)
         return JSONResponse(
             status_code=403,
             content={"detail": _authorization_detail_for_client(exc)},
@@ -66,7 +66,10 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle all unhandled exceptions by logging and returning 500."""
         logger.error(
-            f"Unhandled exception in {request.method} {request.url}: {exc}",
+            "Unhandled exception in %s %s: %s",
+            request.method,
+            request.url,
+            exc,
             exc_info=True,
         )
         return JSONResponse(

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/common/structures.py

@@ -14,10 +14,9 @@
 
 import os
 from enum import Enum
-from pathlib import Path
 from typing import Annotated, Any, Dict, Literal, Optional, Union
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field
 
 
 class OwnerFilter(str, Enum):
@@ -163,53 +162,10 @@ class InMemoryStoreConfig(BaseModel):
     type: Literal["memory"] = "memory"
 
 
-class SQLStorageConfig(BaseModel):
-    type: Literal["sql"] = "sql"
-    driver: str
-    mode: Literal["read_and_write", "read_only"]
-    database: Optional[str] = None
-    host: Optional[str] = None
-    port: Optional[int] = None
-    username: Optional[str] = Field(
-        default_factory=lambda: os.getenv("TABULAR_POSTGRES_USERNAME")
-    )
-    # Prefer TABULAR_POSTGRES_PASSWORD; fall back to legacy SQL_PASSWORD for backward compatibility.
-    password: Optional[str] = Field(
-        default_factory=lambda: os.getenv("TABULAR_POSTGRES_PASSWORD")
-    )
-    path: Optional[str] = None
-
-    @model_validator(mode="after")
-    def build_path(self) -> "SQLStorageConfig":
-        if not self.driver:
-            raise ValueError("Driver is required.")
-
-        if self.path:
-            # Facultatif : expanduser si tu veux supporter les "~"
-            self.path = str(Path(self.path).expanduser())
-        else:
-            if not self.database:
-                raise ValueError("Database name is required to build the path.")
-
-            auth = ""
-            if self.username:
-                auth = self.username
-                if self.password:
-                    auth += f":{self.password}"
-                auth += "@"
-
-            host = self.host or "localhost"
-            port = f":{self.port}" if self.port else ""
-            self.path = f"{auth}{host}{port}/{self.database}"
-
-        return self
-
-
 StoreConfig = Annotated[
     Union[
         DuckdbStoreConfig,
         OpenSearchIndexConfig,
-        SQLStorageConfig,
         LogStoreConfig,
         PostgresTableConfig,
         InMemoryStoreConfig,

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/common/utils.py

@@ -54,7 +54,7 @@ def raise_internal_error(logger: logging.Logger, msg: str, exc: Exception):
     """
 
     error_id = str(uuid.uuid4())[:8]
-    logger.exception(f"[{error_id}] {msg}")
+    logger.exception("[%s] %s", error_id, msg)
     raise HTTPException(
         status_code=500, detail=f"{msg}. Contact support with error ID: {error_id}."
     )

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/filesystem/minio_filesystem.py

@@ -79,7 +79,7 @@ class MinioFilesystem(BaseFilesystem):
 
         if not self.client.bucket_exists(bucket_name):
             self.client.make_bucket(bucket_name)
-            logger.info(f"Bucket '{bucket_name}' created.")
+            logger.info("[MINIO_SETUP] bucket=%s created", bucket_name)
 
     def _resolve_path(self, path: str) -> str:
         """

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/kpi/kpi_writer.py

@@ -161,7 +161,10 @@ class KPIWriter(BaseKPIWriter):
         try:
             self.store.ensure_ready()
         except Exception as e:
-            logger.warning(f"[KPI] ensure_ready failed (continuing best-effort): {e}")
+            logger.warning(
+                "[KPI] ensure_ready failed (continuing best-effort): %s",
+                e,
+            )
         self._start_summary_thread_if_enabled()
 
     # ---- generic emit --------------------------------------------------------

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/kpi/opensearch_kpi_store.py

@@ -155,14 +155,14 @@ class OpenSearchKPIStore(BaseKPIStore):
         try:
             if not self.client.indices.exists(index=self.index):
                 self.client.indices.create(index=self.index, body=KPI_INDEX_MAPPING)
-                logger.info(f"[OPENSEARCH][KPI] created index '{self.index}'.")
+                logger.info("[OPENSEARCH][KPI] created index '%s'", self.index)
             else:
-                logger.info(f"[OPENSEARCH][KPI] index '{self.index}' already exists.")
+                logger.info("[OPENSEARCH][KPI] index '%s' already exists.", self.index)
                 self._ensure_dim_mapping("service", {"type": "keyword"})
                 # Validate existing mapping matches expected mapping
                 validate_index_mapping(self.client, self.index, KPI_INDEX_MAPPING)
         except OpenSearchException as e:
-            logger.error(f"[OPENSEARCH][KPI] ensure_ready failed: {e}")
+            logger.error("[OPENSEARCH][KPI] ensure_ready failed: %s", e)
             raise
 
     def _ensure_dim_mapping(self, name: str, mapping: Dict[str, Any]) -> None:
@@ -191,7 +191,7 @@ class OpenSearchKPIStore(BaseKPIStore):
         try:
             self.client.index(index=self.index, body=event.to_doc())
         except OpenSearchException as e:
-            logger.error(f"[OPENSEARCH][KPI] index_event failed: {e}")
+            logger.error("[OPENSEARCH][KPI] index_event failed: %s", e)
             raise
 
     def bulk_index(self, events: List[KPIEvent]) -> None:
@@ -204,9 +204,11 @@ class OpenSearchKPIStore(BaseKPIStore):
         try:
             resp = self.client.bulk(body=actions)
             if resp.get("errors"):
-                logger.warning("[KPI] bulk_index completed with partial errors.")
+                logger.warning(
+                    "[OPENSEARCH][KPI] bulk_index completed with partial errors."
+                )
         except OpenSearchException as e:
-            logger.error(f"[OPENSEARCH][KPI] bulk_index failed: {e}")
+            logger.error("[OPENSEARCH][KPI] bulk_index failed: %s", e)
             raise
 
     # -- reads -----------------------------------------------------------------

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/logs/opensearch_log_store.py

@@ -157,13 +157,13 @@ class OpenSearchLogStore(BaseLogStore):
         try:
             if not self.client.indices.exists(index=self.index):
                 self.client.indices.create(index=self.index, body=LOG_INDEX_MAPPING)
-                logger.info(f"[LOG] created index '{self.index}'.")
+                logger.info("[OPENSEARCH][LOG] created index '%s'.", self.index)
             else:
-                logger.info(f"[LOG] index '{self.index}' already exists.")
+                logger.info("[OPENSEARCH][LOG] index '%s' already exists.", self.index)
                 # If you have a generic validator like KPI does, call it here:
                 # validate_index_mapping(self.client, self.index, LOG_INDEX_MAPPING)
         except OpenSearchException as e:
-            logger.error(f"[LOG] ensure_ready failed: {e}")
+            logger.error("[OPENSEARCH][LOG] ensure_ready failed: %s", e)
             raise
 
     # -- writes ----------------------------------------------------------------
@@ -171,7 +171,8 @@ class OpenSearchLogStore(BaseLogStore):
         try:
             self.client.index(index=self.index, body=_doc_from_event(event))
         except OpenSearchException as e:
-            raise e
+            logger.error("[OPENSEARCH][LOG] index_event failed: %s", e)
+            raise
 
     def bulk_index(self, events: List[LogEventDTO]) -> None:
         if not events:
@@ -183,9 +184,11 @@ class OpenSearchLogStore(BaseLogStore):
         try:
             resp = self.client.bulk(body=actions)
             if resp.get("errors"):
-                print("[LOG] bulk_index completed with partial errors.")
+                logger.warning(
+                    "[OPENSEARCH][LOG] bulk_index completed with partial errors."
+                )
         except OpenSearchException as e:
-            print(f"[LOG] bulk_index failed: {e}")
+            logger.error("[OPENSEARCH][LOG] bulk_index failed: %s", e)
             raise
 
     # -- reads -----------------------------------------------------------------

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/portable/observability.py

@@ -39,6 +39,7 @@ from __future__ import annotations
 
 import logging
 import time
+from collections.abc import Mapping
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from typing import Any, Generator
@@ -57,6 +58,24 @@ class Span:
     manager here because span lifetime often crosses await boundaries).
     """
 
+    @property
+    def span_id(self) -> str | None:
+        """
+        Return the backend span identifier when the implementation exposes one.
+
+        Why this exists:
+        - some tracing backends can create parent/child relationships only when
+          the caller can read a stable span id from the current span
+
+        How to use it:
+        - treat `None` as "this backend does not expose parent-linking ids"
+
+        Example:
+        - `if span.span_id is not None: trace_context["parent_span_id"] = span.span_id`
+        """
+
+        return None
+
     def set_attribute(self, key: str, value: Any) -> None:
         """Record one key/value attribute on this span."""
 
@@ -80,7 +99,11 @@ class Tracer:
     def start_span(
         self,
         name: str,
-        **attributes: Any,
+        *,
+        context: object | None = None,
+        attributes: Mapping[str, object] | None = None,
+        parent: Span | None = None,
+        **kwargs: object,
     ) -> Span:
         """Open a new span. Returns a no-op Span by default."""
         return Span()
@@ -106,8 +129,41 @@ class LoggingTracer(Tracer):
     def __init__(self, logger: logging.Logger | None = None) -> None:
         self._logger = logger or logging.getLogger("fred_core.traces")
 
-    def start_span(self, name: str, **attributes: Any) -> Span:
-        return _LoggingSpan(name=name, logger=self._logger, extra=attributes)
+    def start_span(
+        self,
+        name: str,
+        *,
+        context: object | None = None,
+        attributes: Mapping[str, object] | None = None,
+        parent: Span | None = None,
+        **kwargs: object,
+    ) -> Span:
+        """
+        Open a new logging-backed span.
+
+        Why this exists:
+        - runtime code passes structured attributes and optional parent spans
+          through one shared tracing seam
+
+        How to use it:
+        - pass `attributes=` for the canonical attribute bag
+        - optional `parent` contributes `parent_span_id` when available
+
+        Example:
+        - `tracer.start_span("agent.run", attributes={"agent_id": "demo"})`
+        """
+
+        del context
+        combined_attributes: dict[str, object] = dict(attributes or {})
+        combined_attributes.update(kwargs)
+        parent_span_id = parent.span_id if parent is not None else None
+        if parent_span_id is not None:
+            combined_attributes.setdefault("parent_span_id", parent_span_id)
+        return _LoggingSpan(
+            name=name,
+            logger=self._logger,
+            extra=combined_attributes,
+        )
 
 
 @dataclass

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/store/opensearch_mapping_validator.py

@@ -60,7 +60,7 @@ def validate_index_mapping(
             if field_name not in current_properties:
                 error_msg = f"Missing root field: '{field_name}'"
                 if allow_missing_fields:
-                    logger.warning(f"[OPENSEARCH][MAPPING] {error_msg}")
+                    logger.warning("[OPENSEARCH][MAPPING] %s", error_msg)
                 else:
                     mismatches.append(error_msg)
                 continue
@@ -76,20 +76,23 @@ def validate_index_mapping(
             error_msg = (
                 f"Index '{index_name}' has mapping validation errors: {mismatches}"
             )
-            logger.error(f"[OPENSEARCH][MAPPING] {error_msg}")
+            logger.error("[OPENSEARCH][MAPPING] %s", error_msg)
 
             if strict:
                 raise MappingValidationError(error_msg)
         else:
             logger.info(
-                f"[OPENSEARCH][MAPPING] Index '{index_name}' mapping validation passed"
+                "[OPENSEARCH][MAPPING] index '%s' mapping validation passed",
+                index_name,
             )
 
     except Exception as e:
         if isinstance(e, MappingValidationError):
             raise
         logger.error(
-            f"[MAPPING] Failed to validate mapping for index '{index_name}': {e}"
+            "[OPENSEARCH][MAPPING] validation failed for index '%s': %s",
+            index_name,
+            e,
         )
         if strict:
             raise MappingValidationError(

fred_core-2.0.4/fred_core/tests/common/test_fastapi_handlers.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from fred_core.common.fastapi_handlers import register_exception_handlers
+from fred_core.security.models import AuthorizationError, Resource
+
+
+def test_authorization_error_handler_returns_team_specific_detail(
+    caplog,
+) -> None:
+    app = FastAPI()
+    register_exception_handlers(app)
+
+    @app.get("/teams")
+    async def denied() -> None:
+        raise AuthorizationError(
+            user_id="alice",
+            action="can_update_agents",
+            resource=Resource.TEAM,
+        )
+
+    with caplog.at_level(logging.WARNING):
+        response = TestClient(app, raise_server_exceptions=False).get("/teams")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You are not allowed to manage agents in this team. Ask a team owner or manager."
+    }
+    assert "Authorization denied for user alice" in caplog.text
+
+
+def test_authorization_error_handler_humanizes_generic_resource_action() -> None:
+    app = FastAPI()
+    register_exception_handlers(app)
+
+    @app.get("/documents")
+    async def denied() -> None:
+        raise AuthorizationError(
+            user_id="alice",
+            action="read:global",
+            resource=Resource.DOCUMENTS,
+        )
+
+    response = TestClient(app, raise_server_exceptions=False).get("/documents")
+
+    assert response.status_code == 403
+    assert response.json() == {"detail": "You are not allowed to read global document."}
+
+
+def test_generic_exception_handler_returns_internal_server_error(caplog) -> None:
+    app = FastAPI()
+    register_exception_handlers(app)
+
+    @app.get("/explode")
+    async def explode() -> None:
+        raise RuntimeError("boom")
+
+    with caplog.at_level(logging.ERROR):
+        response = TestClient(app, raise_server_exceptions=False).get("/explode")
+
+    assert response.status_code == 500
+    assert response.json() == {"detail": "Internal server error"}
+    assert "Unhandled exception in GET http://testserver/explode: boom" in caplog.text

fred_core-2.0.4/fred_core/tests/filesystem/test_local_filesystem.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from fred_core.filesystem.local_filesystem import LocalFilesystem
+from fred_core.filesystem.structures import FilesystemResourceInfo
+
+
+@pytest.mark.asyncio
+async def test_local_filesystem_roundtrip_listing_and_grep(tmp_path: Path) -> None:
+    filesystem = LocalFilesystem(str(tmp_path))
+
+    await filesystem.mkdir("docs")
+    await filesystem.mkdir("docs/nested")
+    await filesystem.write("docs/readme.txt", "hello world")
+    await filesystem.write("docs/nested/notes.txt", "fred runtime notes")
+
+    assert await filesystem.print_root_dir() == str(tmp_path.resolve())
+    assert await filesystem.exists("docs/readme.txt") is True
+    assert await filesystem.read("docs/readme.txt") == b"hello world"
+    assert await filesystem.cat("docs/nested/notes.txt") == "fred runtime notes"
+
+    info = await filesystem.stat("docs/readme.txt")
+    assert info.path == "docs/readme.txt"
+    assert info.type == FilesystemResourceInfo.FILE
+    assert info.size == len("hello world")
+
+    listing = await filesystem.list("docs")
+    assert [entry.path for entry in listing] == [
+        "docs/nested",
+        "docs/nested/notes.txt",
+        "docs/readme.txt",
+    ]
+    assert listing[0].type == FilesystemResourceInfo.DIRECTORY
+    assert listing[1].type == FilesystemResourceInfo.FILE
+
+    matches = await filesystem.grep(r"fred\s+runtime", "docs")
+    assert matches == ["docs/nested/notes.txt"]
+
+
+@pytest.mark.asyncio
+async def test_local_filesystem_rejects_missing_parent_missing_file_and_escape(
+    tmp_path: Path,
+) -> None:
+    filesystem = LocalFilesystem(str(tmp_path))
+
+    with pytest.raises(FileNotFoundError, match="Parent directory does not exist"):
+        await filesystem.write("missing/readme.txt", "hello")
+
+    with pytest.raises(FileNotFoundError, match="missing.txt not found"):
+        await filesystem.stat("missing.txt")
+
+    with pytest.raises(PermissionError, match="Access outside of filesystem root"):
+        await filesystem.read("../escape.txt")
+
+
+@pytest.mark.asyncio
+async def test_local_filesystem_delete_and_empty_list_are_safe(
+    tmp_path: Path,
+) -> None:
+    filesystem = LocalFilesystem(str(tmp_path))
+
+    await filesystem.mkdir("docs")
+    await filesystem.write("docs/readme.txt", "hello")
+    await filesystem.delete("docs/readme.txt")
+    await filesystem.delete("docs/missing.txt")
+
+    assert await filesystem.exists("docs/readme.txt") is False
+    assert await filesystem.list("unknown") == []

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/tests/kpi/test_noop_kpi_writer.py

@@ -11,7 +11,7 @@ Focus: verify the contract is honoured, not that operations do nothing.
 
 from __future__ import annotations
 
-from fred_core.kpi.kpi_writer_structures import KPIActor
+from fred_core.kpi.kpi_writer_structures import Dims, KPIActor
 from fred_core.kpi.noop_kpi_writer import NoOpKPIWriter
 
 ACTOR = KPIActor(type="system")
@@ -61,7 +61,7 @@ class TestNoOpKPIWriterTimerContract:
         # mutation must not raise
 
     def test_timer_with_initial_dims_yields_copy(self) -> None:
-        initial = {"phase": "routing"}
+        initial: Dims = {"phase": "routing"}
         with self.writer.timer("test.timer", dims=initial, actor=ACTOR) as d:
             assert d["phase"] == "routing"
             d["extra"] = "added"

{fred_core-2.0.2 → fred_core-2.0.4}/fred_core/tests/logs/test_memory_log_store.py

@@ -10,10 +10,11 @@ Covers:
 from __future__ import annotations
 
 import time
+from typing import Literal
 
 import pytest
 
-from fred_core.logs.log_structures import LogEventDTO, LogFilter, LogQuery
+from fred_core.logs.log_structures import LogEventDTO, LogFilter, LogLevel, LogQuery
 from fred_core.logs.memory_log_store import RamLogStore, _parse_since
 
 # ---------------------------------------------------------------------------
@@ -25,7 +26,7 @@ def _event(
     msg: str,
     *,
     ts: float | None = None,
-    level: str = "INFO",
+    level: LogLevel = "INFO",
     logger: str = "app",
     service: str | None = None,
 ) -> LogEventDTO:
@@ -44,12 +45,12 @@ def _query(
     *,
     since: str = "now-1h",
     until: str | None = None,
-    level_at_least: str | None = None,
+    level_at_least: LogLevel | None = None,
     logger_like: str | None = None,
     service: str | None = None,
     text_like: str | None = None,
     limit: int = 500,
-    order: str = "asc",
+    order: "Literal['asc', 'desc']" = "asc",
 ) -> LogQuery:
     return LogQuery(
         since=since,