fred-runtime 2.0.11__tar.gz → 3.1.0__tar.gz

{fred_runtime-2.0.11 → fred_runtime-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 2.0.11
+Version: 3.1.0
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -12,8 +12,8 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Operating System :: OS Independent
 Requires-Python: <3.13,>=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: fred-core>=2.0.5
-Requires-Dist: fred-sdk>=0.1.11
+Requires-Dist: fred-core>=3.1.0
+Requires-Dist: fred-sdk>=3.1.0
 Requires-Dist: alembic>=1.18.4
 Requires-Dist: deepagents>=0.4.11
 Requires-Dist: httpx>=0.28.1

{fred_runtime-2.0.11 → fred_runtime-3.1.0}/fred_runtime/app/__init__.py

@@ -22,7 +22,6 @@ from .agent_app import create_agent_app
 from .config import (
     AgentPodConfig,
     LangfuseObservabilityConfig,
-    MetricsBackend,
     PodAIConfig,
     PodAppConfig,
     PodObservabilityConfig,
@@ -40,7 +39,6 @@ from .config_loader import (
 __all__ = [
     "AgentPodConfig",
     "LangfuseObservabilityConfig",
-    "MetricsBackend",
     "PodAIConfig",
     "PodAppConfig",
     "PodObservabilityConfig",

{fred_runtime-2.0.11 → fred_runtime-3.1.0}/fred_runtime/app/agent_app.py

@@ -57,6 +57,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
 from fred_core.common.config_loader import get_config
 from fred_core.history.history_schema import ChatMessage
+from fred_core.kpi import KPIMiddleware
 from fred_core.kpi.kpi_writer_structures import KPIActor
 from fred_core.logs.log_setup import log_setup
 from fred_core.logs.memory_log_store import RamLogStore
@@ -110,10 +111,9 @@ from fred_runtime.runtime_support.checkpoints import load_checkpoint
 from ..common.structures import AgentSettingsLike
 from ..integrations.v2_runtime.adapters import (
     CompositeToolInvoker,
-    FredArtifactPublisher,
     FredKnowledgeSearchToolInvoker,
     FredMcpToolProvider,
-    FredResourceReader,
+    FredWorkspaceFs,
     KPIWriterMetricsAdapter,
     build_default_tracer,
 )
@@ -127,7 +127,11 @@ from ..runtime_support import refresh_user_access_token_from_keycloak
 from .config import AgentPodConfig
 from .container import build_pod_container
 from .context import AuditEventRecord, KpiTurnRecord, PodApplicationContext
-from .dependencies import attach_pod_container, get_pod_container
+from .dependencies import (
+    attach_pod_container,
+    get_pod_container,
+    get_pod_container_from_app,
+)
 from .observability_factory import bootstrap_observability
 
 logger = logging.getLogger(__name__)
@@ -656,11 +660,7 @@ def _build_runtime_services(
         binding=binding,
         settings=settings,
     )
-    artifact_publisher = FredArtifactPublisher(
-        binding=binding,
-        settings=settings,
-    )
-    resource_reader = FredResourceReader(
+    workspace_fs = FredWorkspaceFs(
         binding=binding,
         settings=settings,
     )
@@ -672,8 +672,7 @@ def _build_runtime_services(
             settings=settings,
             ports=AuthoredToolRuntimePorts(
                 chat_model_factory=runtime_config.chat_model_factory,
-                artifact_publisher=artifact_publisher,
-                resource_reader=resource_reader,
+                workspace_fs=workspace_fs,
                 fallback_tool_invoker=base_tool_invoker,
                 media_fetcher=_build_media_fetcher(binding=binding, settings=settings),
             ),
@@ -703,8 +702,7 @@ def _build_runtime_services(
         chat_model_factory=runtime_config.chat_model_factory,
         tool_invoker=tool_invoker,
         tool_provider=tool_provider,
-        artifact_publisher=artifact_publisher,
-        resource_reader=resource_reader,
+        workspace_fs=workspace_fs,
         checkpointer=runtime_config.checkpointer,
         agent_invoker=agent_invoker,
     )
@@ -850,6 +848,7 @@ class _McpCatalogResponse(BaseModel):
 class _ResolvedAgentInstance(BaseModel):
     agent_instance_id: str
     template_agent_id: str
+    display_name: str = ""
     owner_scope: str
     owner_user_id: str | None = None
     owner_team_id: str | None = None
@@ -862,6 +861,7 @@ class _ResolvedExecutionTarget:
     definition: ReActAgentDefinition | GraphAgentDefinition
     effective_agent_id: str
     team_id: str | None = None
+    agent_instance_name: str | None = None
 
 
 def _apply_runtime_tuning(
@@ -1050,6 +1050,7 @@ async def _resolve_agent_instance(
         ),
         effective_agent_id=resolution.agent_instance_id,
         team_id=resolution.owner_team_id,
+        agent_instance_name=resolution.display_name or None,
     )
 
 
@@ -1593,6 +1594,7 @@ def _emit_turn_completed(
     user_id: str,
     team_id: str | None,
     agent_instance_id: str | None,
+    agent_instance_name: str | None,
     template_agent_id: str | None,
     payloads: list[dict[str, Any]],
     turn_start: float,
@@ -1626,6 +1628,8 @@ def _emit_turn_completed(
         prom_dims: dict[str, str | None] = {
             "team_id": team_id,
             "template_agent_id": template_agent_id,
+            "agent_instance_id": agent_instance_id,
+            "agent_instance_name": agent_instance_name,
             "runtime_id": runtime_id,
             "model_name": outcome.model_name,
             "finish_reason": outcome.finish_reason,
@@ -1642,7 +1646,7 @@ def _emit_turn_completed(
                 "input_tokens": outcome.input_tokens,
                 "output_tokens": outcome.output_tokens,
             },
-            actor=KPIActor(type="system"),
+            actor=KPIActor(type="human", user_id=user_id),
         )
 
         if outcome.is_error:
@@ -1651,7 +1655,7 @@ def _emit_turn_completed(
                 type="counter",
                 value=1,
                 dims=prom_dims,
-                actor=KPIActor(type="system"),
+                actor=KPIActor(type="human", user_id=user_id),
             )
 
         # Append to container ring buffer (high-cardinality fields safe here).
@@ -1682,6 +1686,7 @@ async def _stream(
     access_token: str | None = None,
     *,
     team_id: str | None = None,
+    agent_instance_name: str | None = None,
     registry: Mapping[str, ReActAgentDefinition | GraphAgentDefinition] | None = None,
     security_enabled: bool = False,
     container: PodApplicationContext,
@@ -1734,6 +1739,7 @@ async def _stream(
         user_id=user_id,
         team_id=resolved_team_id,
         agent_instance_id=request.agent_instance_id,
+        agent_instance_name=agent_instance_name,
         template_agent_id=definition.agent_id,
         payloads=collected,
         turn_start=turn_start,
@@ -2627,6 +2633,7 @@ def _build_agent_router(
             user_id=user_id_str,
             team_id=target.team_id,
             agent_instance_id=request.agent_instance_id,
+            agent_instance_name=target.agent_instance_name,
             template_agent_id=target.definition.agent_id,
             payloads=payloads,
             turn_start=turn_start,
@@ -2730,6 +2737,7 @@ def _build_agent_router(
             user_id=user_id_str,
             team_id=target.team_id,
             agent_instance_id=request.agent_instance_id,
+            agent_instance_name=target.agent_instance_name,
             template_agent_id=target.definition.agent_id,
             payloads=payloads,
             turn_start=turn_start,
@@ -2840,6 +2848,7 @@ def _build_agent_router(
                 internal_req,
                 access_token=access_token,
                 team_id=target.team_id,
+                agent_instance_name=target.agent_instance_name,
                 registry=registry,
                 security_enabled=security_enabled,
                 container=container,
@@ -2966,7 +2975,7 @@ def create_agent_app(
             "enabled" if security_enabled else "disabled",
             "sql" if container.get_checkpointer() is not None else "none",
             "sql" if container.get_history_store() is not None else "none",
-            config.observability.metrics.value,
+            "prometheus" if config.observability.kpi.prometheus.enabled else "logging",
             list(registry.keys()),
         )
         yield
@@ -2992,6 +3001,13 @@ def create_agent_app(
         )
         logger.debug("[fred-runtime] CORS allow_origins=%s", authorized_origins)
 
+    # KPI middleware — writer is lazily resolved from app.state because the
+    # container (and its KPI writer) is only initialised during lifespan startup.
+    app.add_middleware(
+        KPIMiddleware,
+        kpi=lambda: get_pod_container_from_app(app).get_kpi_writer(),
+    )
+
     api_router = APIRouter(prefix=base_url)
     api_router.include_router(
         _build_agent_router(registry, security_enabled=security_enabled)

{fred_runtime-2.0.11 → fred_runtime-3.1.0}/fred_runtime/app/config.py

@@ -70,6 +70,7 @@ if TYPE_CHECKING:
     from fred_runtime.runtime_context import McpConfigurationLike
 
 from fred_core.common import (
+    KpiObservabilityConfig,
     OpenSearchStoreConfig,
     PostgresStoreConfig,
     TemporalSchedulerConfig,
@@ -120,26 +121,6 @@ class PodAppConfig(BaseModel):
         ),
     )
     gcu_version: str | None = None
-    metrics_address: str = "127.0.0.1"
-    metrics_port: int = 9000
-    kpi_process_metrics_interval_sec: int = Field(
-        default=0,
-        description=(
-            "Emit process and SQL pool KPIs every N seconds. Set 0 to disable "
-            "the background emitters."
-        ),
-    )
-    kpi_log_summary_interval_sec: float = Field(
-        default=0.0,
-        description=(
-            "Emit periodic KPI summary logs every N seconds for local benches. "
-            "Set 0 to disable."
-        ),
-    )
-    kpi_log_summary_top_n: int = Field(
-        default=0,
-        description="Top-N KPI summary rows to log. 0 means all / disabled.",
-    )
     openai_compat: bool = True
     """
     Enable the OpenAI-compatible /v1/chat/completions and /v1/models endpoints.
@@ -209,21 +190,6 @@ class TracerBackend(str, Enum):
     langfuse = "langfuse"
 
 
-class MetricsBackend(str, Enum):
-    """
-    Metrics emission backend for the agent pod.
-
-    - null       — no metrics, all timer events are dropped
-    - logging    — each timer is emitted as a structured log entry (default)
-    - prometheus — KPI/process metrics are exported in Prometheus format on the
-                   dedicated metrics port configured under `app`
-    """
-
-    null = "null"
-    logging = "logging"
-    prometheus = "prometheus"
-
-
 class LangfuseObservabilityConfig(BaseModel):
     """
     Langfuse connection settings.
@@ -245,14 +211,20 @@ class PodObservabilityConfig(BaseModel):
     Example:
         observability:
           tracer: logging       # null | logging | langfuse
-          metrics: logging      # null | logging | prometheus
+          kpi:
+            log:
+              enabled: true
+            prometheus:
+              enabled: false
+            opensearch:
+              enabled: false
           langfuse:
             host: "http://localhost:3001"
             # LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY in .env
     """
 
     tracer: TracerBackend = TracerBackend.logging
-    metrics: MetricsBackend = MetricsBackend.logging
+    kpi: KpiObservabilityConfig = Field(default_factory=KpiObservabilityConfig)
     langfuse: LangfuseObservabilityConfig = Field(
         default_factory=LangfuseObservabilityConfig
     )

{fred_runtime-2.0.11 → fred_runtime-3.1.0}/fred_runtime/app/context.py

@@ -24,16 +24,14 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, TypedDict
 
 from fred_core.kpi.base_kpi_writer import BaseKPIWriter
+from fred_core.kpi.kpi_factory import build_kpi_writer
 from fred_core.kpi.kpi_process import emit_process_kpis, emit_sql_pool_kpis
-from fred_core.kpi.kpi_writer import KPIDefaults, KPIWriter
-from fred_core.kpi.log_kpi_store import KpiLogStore
 from fred_core.kpi.noop_kpi_writer import NoOpKPIWriter
-from fred_core.kpi.prometheus_kpi_store import PrometheusKPIStore
 from fred_sdk.contracts.runtime import HistoryStorePort
 from prometheus_client import start_http_server
 from sqlalchemy.ext.asyncio import AsyncEngine
 
-from fred_runtime.app.config import AgentPodConfig, MetricsBackend
+from fred_runtime.app.config import AgentPodConfig
 
 if TYPE_CHECKING:
     pass
@@ -117,18 +115,11 @@ class PodApplicationContext:
     def initialize_kpi_writer(self) -> None:
         """Build the KPI writer from pod observability config."""
         config = self.configuration
-        backend = config.observability.metrics
-        if backend == MetricsBackend.null:
-            self._kpi_writer = NoOpKPIWriter()
-            return
-        store = KpiLogStore(level=config.app.log_level)
-        if backend == MetricsBackend.prometheus:
-            store = PrometheusKPIStore(delegate=store)  # type: ignore[arg-type]
-        self._kpi_writer = KPIWriter(
-            store=store,
-            defaults=KPIDefaults(static_dims={"service": "fred-runtime"}),
-            summary_interval_s=config.app.kpi_log_summary_interval_sec,
-            summary_top_n=config.app.kpi_log_summary_top_n,
+        self._kpi_writer = build_kpi_writer(
+            kpi_config=config.observability.kpi,
+            opensearch_config=config.storage.opensearch,
+            service_name="fred-runtime",
+            log_level=config.app.log_level,
         )
 
     async def initialize_sql(self) -> None:
@@ -160,25 +151,23 @@ class PodApplicationContext:
 
     def start_metrics_exporter(self) -> None:
         """Start the Prometheus scrape endpoint when configured."""
-        config = self.configuration
-        if config.observability.metrics != MetricsBackend.prometheus:
+        prom_cfg = self.configuration.observability.kpi.prometheus
+        if not prom_cfg.enabled:
             return
-        result = start_http_server(
-            config.app.metrics_port,
-            addr=config.app.metrics_address,
-        )
+        result = start_http_server(prom_cfg.port, addr=prom_cfg.address)
         self._metrics_exporter = result if isinstance(result, tuple) else None
         logger.info(
             "[fred-runtime] Prometheus metrics exporter ready at %s:%s",
-            config.app.metrics_address,
-            config.app.metrics_port,
+            prom_cfg.address,
+            prom_cfg.port,
         )
 
     async def start_kpi_tasks(self) -> None:
         """Start background KPI flush tasks (process + SQL pool health)."""
         kpi_writer = self.get_kpi_writer()
-        config = self.configuration
-        interval_s = float(config.app.kpi_process_metrics_interval_sec)
+        interval_s = float(
+            self.configuration.observability.kpi.process_metrics_interval_sec
+        )
         if interval_s <= 0 or isinstance(kpi_writer, NoOpKPIWriter):
             return
         tasks: list[asyncio.Task[None]] = [

{fred_runtime-2.0.11 → fred_runtime-3.1.0}/fred_runtime/app/observability_factory.py

@@ -51,7 +51,7 @@ from fred_core.portable import (
     set_tracer,
 )
 
-from .config import MetricsBackend, PodObservabilityConfig, TracerBackend
+from .config import PodObservabilityConfig, TracerBackend
 
 logger = logging.getLogger(__name__)
 
@@ -83,9 +83,9 @@ def bootstrap_observability(
     set_tracer(tracer)
     set_metrics_provider(metrics)
     logger.info(
-        "[fred-runtime] observability ready — tracer=%s metrics=%s",
+        "[fred-runtime] observability ready — tracer=%s prometheus=%s",
         config.tracer.value,
-        config.metrics.value,
+        config.kpi.prometheus.enabled,
     )
 
 
@@ -160,15 +160,10 @@ def _build_metrics(
     *,
     kpi_writer: BaseKPIWriter | None = None,
 ) -> MetricsProvider:
-    if config.metrics == MetricsBackend.null:
-        return MetricsProvider()
-    if config.metrics == MetricsBackend.logging:
-        return LoggingMetricsProvider()
-    if config.metrics == MetricsBackend.prometheus:
+    if config.kpi.prometheus.enabled:
         if kpi_writer is None:
             logger.warning(
-                "[fred-runtime] metrics=prometheus selected without a KPI writer"
-                " — falling back to logging"
+                "[fred-runtime] prometheus enabled without a KPI writer — falling back to logging"
             )
             return LoggingMetricsProvider()
         from fred_runtime.integrations.v2_runtime.adapters import (
@@ -176,8 +171,4 @@ def _build_metrics(
         )
 
         return cast(MetricsProvider, KPIWriterMetricsAdapter(kpi_writer))
-    logger.warning(
-        "[fred-runtime] Unknown metrics backend '%s' — falling back to logging",
-        config.metrics,
-    )
     return LoggingMetricsProvider()

{fred_runtime-2.0.11 → fred_runtime-3.1.0}/fred_runtime/common/context_aware_tool.py

@@ -163,23 +163,57 @@ class ContextAwareTool(BaseTool):
 
         tool_properties = self._get_tool_properties()
 
-        library_ids = get_document_library_tags_ids(context)
-        if library_ids and "document_library_tags_ids" in tool_properties:
-            kwargs["document_library_tags_ids"] = library_ids
-            logger.info(
-                "ContextAwareTool(%s) injecting library filter: %s",
-                self.name,
-                library_ids,
-            )
+        # Snapshot what the agent (or LLM) explicitly requested, so every decision
+        # below can be logged as "requested -> applied" with no ambiguity. The
+        # picker selection (RuntimeContext) is a default scope an agent may NARROW;
+        # an explicit per-call scope is respected, never silently overwritten.
+        caller_document_uids = kwargs.get("document_uids")
+        caller_library_ids = kwargs.get("document_library_tags_ids")
+        picker_document_uids = get_document_uids(context)
+        picker_library_ids = get_document_library_tags_ids(context)
+
+        # Document scope is the most specific selector. If the agent passed it,
+        # keep it verbatim; otherwise fill from the picker selection.
+        if "document_uids" in tool_properties:
+            if caller_document_uids:
+                logger.info(
+                    "ContextAwareTool(%s) document_uids: agent-scoped=%s (picker=%s NOT applied)",
+                    self.name,
+                    caller_document_uids,
+                    picker_document_uids,
+                )
+            elif picker_document_uids:
+                kwargs["document_uids"] = picker_document_uids
+                logger.info(
+                    "ContextAwareTool(%s) document_uids: applied picker selection=%s",
+                    self.name,
+                    picker_document_uids,
+                )
 
-        document_uids = get_document_uids(context)
-        if document_uids and "document_uids" in tool_properties:
-            kwargs["document_uids"] = document_uids
-            logger.info(
-                "ContextAwareTool(%s) injecting document filter: %s",
-                self.name,
-                document_uids,
-            )
+        # Library scope is broader than document scope. Inject the picker libraries
+        # only when the agent did not scope by library AND did not scope by document
+        # (a per-call document scope must not be widened back to whole libraries).
+        if "document_library_tags_ids" in tool_properties:
+            if caller_library_ids:
+                logger.info(
+                    "ContextAwareTool(%s) library: agent-scoped=%s (picker=%s NOT applied)",
+                    self.name,
+                    caller_library_ids,
+                    picker_library_ids,
+                )
+            elif caller_document_uids:
+                logger.info(
+                    "ContextAwareTool(%s) library: NOT injected — agent scoped by document_uids=%s",
+                    self.name,
+                    caller_document_uids,
+                )
+            elif picker_library_ids:
+                kwargs["document_library_tags_ids"] = picker_library_ids
+                logger.info(
+                    "ContextAwareTool(%s) library: applied picker selection=%s",
+                    self.name,
+                    picker_library_ids,
+                )
 
         session_id = context.session_id
         if (