fred-runtime 2.0.3__tar.gz → 2.0.7__tar.gz

{fred_runtime-2.0.3 → fred_runtime-2.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 2.0.3
+Version: 2.0.7
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -58,8 +58,9 @@ fred-runtime       Platform adapters + pod factory (this package)
 ```
 
 **Rule of thumb:**
-- Write agent logic in `fred-sdk`.  
-- Write infrastructure adapters (DB, MCP server, Keycloak, object store) in `fred-runtime`.  
+
+- Write agent logic in `fred-sdk`.
+- Write infrastructure adapters (DB, MCP server, Keycloak, object store) in `fred-runtime`.
 - `fred-sdk` must stay importable on a bare laptop with no services running.
 
 ---
@@ -79,15 +80,15 @@ app    = create_agent_app(registry=REGISTRY, config=config)
 
 `create_agent_app` returns a FastAPI application that exposes:
 
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `{base_url}/agents/execute` | Single-turn execution — returns final JSON |
-| `POST` | `{base_url}/agents/execute/stream` | Streaming SSE execution — yields `RuntimeEvent` objects |
-| `GET`  | `{base_url}/agents` | List registered agent IDs |
-| `GET`  | `{base_url}/agents/sessions` | List session IDs for a user |
-| `GET`  | `{base_url}/agents/sessions/{id}/messages` | Full conversation history for a session |
-| `GET`  | `/v1/models` | OpenAI model list (agent IDs as model names) |
-| `POST` | `/v1/chat/completions` | OpenAI chat completions — works with Open WebUI, openai-python SDK, etc. |
+| Method | Path                                       | Description                                                              |
+| ------ | ------------------------------------------ | ------------------------------------------------------------------------ |
+| `POST` | `{base_url}/agents/execute`                | Single-turn execution — returns final JSON                               |
+| `POST` | `{base_url}/agents/execute/stream`         | Streaming SSE execution — yields `RuntimeEvent` objects                  |
+| `GET`  | `{base_url}/agents`                        | List registered agent IDs                                                |
+| `GET`  | `{base_url}/agents/sessions`               | List session IDs for a user                                              |
+| `GET`  | `{base_url}/agents/sessions/{id}/messages` | Full conversation history for a session                                  |
+| `GET`  | `/v1/models`                               | OpenAI model list (agent IDs as model names)                             |
+| `POST` | `/v1/chat/completions`                     | OpenAI chat completions — works with Open WebUI, openai-python SDK, etc. |
 
 The OpenAI-compatible `/v1` surface is **enabled by default**.  
 Set `app.openai_compat: false` in `configuration.yaml` to disable it for internal pods.
@@ -99,11 +100,11 @@ the SQL checkpointer. The session ID is the LangGraph `thread_id`.
 
 ### `fred_runtime.runtime_support` — Infrastructure adapters
 
-| Module | What it provides |
-|--------|-----------------|
-| `sql_checkpointer` | Durable LangGraph checkpointer backed by SQLite (dev) or PostgreSQL (prod) |
-| `user_token_refresher` | Transparent Keycloak token refresh for long-lived agent sessions |
-| `request_context_helpers` | FastAPI dependency helpers for extracting user/session context |
+| Module                    | What it provides                                                           |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `sql_checkpointer`        | Durable LangGraph checkpointer backed by SQLite (dev) or PostgreSQL (prod) |
+| `user_token_refresher`    | Transparent Keycloak token refresh for long-lived agent sessions           |
+| `request_context_helpers` | FastAPI dependency helpers for extracting user/session context             |
 
 ---
 
@@ -119,16 +120,16 @@ Providers: OpenAI, Azure OpenAI, Mistral, Ollama, and any LangChain-compatible b
 
 HTTP clients that connect agent tools to the Fred platform services:
 
-| Client | Connects to |
-|--------|------------|
-| `kf_http_client` | Knowledge Flow REST API (generic) |
-| `kf_vectorsearch_client` | Vector search / retrieval |
-| `kf_markdown_media_client` | Document content (Markdown + media) |
-| `kf_workspace_client` | Workspace and library management |
-| `kf_logs_client` | Audit log retrieval |
-| `kf_fast_text_client` | FastText classification |
-| `mcp_runtime` / `mcp_toolkit` | MCP server lifecycle and tool injection |
-| `context_aware_tool` | Tool base class that propagates the runtime context (user, team, token) |
+| Client                        | Connects to                                                             |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `kf_http_client`              | Knowledge Flow REST API (generic)                                       |
+| `kf_vectorsearch_client`      | Vector search / retrieval                                               |
+| `kf_markdown_media_client`    | Document content (Markdown + media)                                     |
+| `kf_workspace_client`         | Workspace and library management                                        |
+| `kf_logs_client`              | Audit log retrieval                                                     |
+| `kf_fast_text_client`         | FastText classification                                                 |
+| `mcp_runtime` / `mcp_toolkit` | MCP server lifecycle and tool injection                                 |
+| `context_aware_tool`          | Tool base class that propagates the runtime context (user, team, token) |
 
 ---
 
@@ -176,9 +177,9 @@ or overridden with `--base-url` / `FRED_AGENT_POD_URL`.
 
 Every Fred pod uses the same two-file convention:
 
-| File | Purpose |
-|------|---------|
-| `.env` (path from `ENV_FILE`) | Secrets: API keys, DB URLs, Keycloak credentials |
+| File                                           | Purpose                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------ |
+| `.env` (path from `ENV_FILE`)                  | Secrets: API keys, DB URLs, Keycloak credentials                   |
 | `configuration.yaml` (path from `CONFIG_FILE`) | App settings: port, base URL, LLM routing, observability, security |
 
 Minimal `configuration.yaml` for a local pod:
@@ -190,6 +191,7 @@ app:
   host: "0.0.0.0"
   port: 8010
   log_level: "info"
+  limit_concurrency: 200
   metrics_address: "127.0.0.1"
   metrics_port: 9115
   kpi_process_metrics_interval_sec: 10
@@ -208,6 +210,10 @@ When `observability.metrics: prometheus` is enabled, `create_agent_app(...)`
 starts a dedicated Prometheus exporter on `app.metrics_address:app.metrics_port`
 and restores the shared Fred KPI pipeline, including process and SQL pool KPIs.
 
+Set `app.limit_concurrency: null` to disable Uvicorn connection limiting, or a
+positive integer to reject excess concurrent HTTP and WebSocket connections
+with `503` before application code runs.
+
 ---
 
 ## Installation
@@ -229,6 +235,7 @@ Requires Python 3.12.
 A minimal pod is three files:
 
 **`main.py`**
+
 ```python
 from fred_runtime.app import create_agent_app, load_agent_pod_config
 from myapp.registry import REGISTRY
@@ -238,19 +245,27 @@ app = create_agent_app(registry=REGISTRY, config=config)
 ```
 
 **`__main__.py`**
+
 ```python
 import uvicorn
 from fred_runtime.app import load_agent_pod_config
 
 def main():
     config = load_agent_pod_config()
-    uvicorn.run("myapp.main:app", host=config.app.host, port=config.app.port, reload=True)
+    uvicorn.run(
+        "myapp.main:app",
+        host=config.app.host,
+        port=config.app.port,
+        limit_concurrency=config.app.limit_concurrency,
+        reload=True,
+    )
 
 if __name__ == "__main__":
     main()
 ```
 
 **`registry.py`**
+
 ```python
 from fred_sdk.contracts.models import ReActAgentDefinition
 
@@ -267,11 +282,11 @@ See [fred-samples](https://github.com/ThalesGroup/fred) for a working reference
 
 ## Related packages
 
-| Package | PyPI | Role |
-|---------|------|------|
-| `fred-core` | [pypi](https://pypi.org/project/fred-core/) | Pure utilities — logging, model factories, embeddings, portable observability |
-| `fred-sdk` | [pypi](https://pypi.org/project/fred-sdk/) | Agent authoring — ReAct, Graph, tool contracts |
-| `fred-runtime` | [pypi](https://pypi.org/project/fred-runtime/) | This package |
+| Package        | PyPI                                           | Role                                                                          |
+| -------------- | ---------------------------------------------- | ----------------------------------------------------------------------------- |
+| `fred-core`    | [pypi](https://pypi.org/project/fred-core/)    | Pure utilities — logging, model factories, embeddings, portable observability |
+| `fred-sdk`     | [pypi](https://pypi.org/project/fred-sdk/)     | Agent authoring — ReAct, Graph, tool contracts                                |
+| `fred-runtime` | [pypi](https://pypi.org/project/fred-runtime/) | This package                                                                  |
 
 ---
 

{fred_runtime-2.0.3 → fred_runtime-2.0.7}/README.md

@@ -23,8 +23,9 @@ fred-runtime       Platform adapters + pod factory (this package)
 ```
 
 **Rule of thumb:**
-- Write agent logic in `fred-sdk`.  
-- Write infrastructure adapters (DB, MCP server, Keycloak, object store) in `fred-runtime`.  
+
+- Write agent logic in `fred-sdk`.
+- Write infrastructure adapters (DB, MCP server, Keycloak, object store) in `fred-runtime`.
 - `fred-sdk` must stay importable on a bare laptop with no services running.
 
 ---
@@ -44,15 +45,15 @@ app    = create_agent_app(registry=REGISTRY, config=config)
 
 `create_agent_app` returns a FastAPI application that exposes:
 
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `{base_url}/agents/execute` | Single-turn execution — returns final JSON |
-| `POST` | `{base_url}/agents/execute/stream` | Streaming SSE execution — yields `RuntimeEvent` objects |
-| `GET`  | `{base_url}/agents` | List registered agent IDs |
-| `GET`  | `{base_url}/agents/sessions` | List session IDs for a user |
-| `GET`  | `{base_url}/agents/sessions/{id}/messages` | Full conversation history for a session |
-| `GET`  | `/v1/models` | OpenAI model list (agent IDs as model names) |
-| `POST` | `/v1/chat/completions` | OpenAI chat completions — works with Open WebUI, openai-python SDK, etc. |
+| Method | Path                                       | Description                                                              |
+| ------ | ------------------------------------------ | ------------------------------------------------------------------------ |
+| `POST` | `{base_url}/agents/execute`                | Single-turn execution — returns final JSON                               |
+| `POST` | `{base_url}/agents/execute/stream`         | Streaming SSE execution — yields `RuntimeEvent` objects                  |
+| `GET`  | `{base_url}/agents`                        | List registered agent IDs                                                |
+| `GET`  | `{base_url}/agents/sessions`               | List session IDs for a user                                              |
+| `GET`  | `{base_url}/agents/sessions/{id}/messages` | Full conversation history for a session                                  |
+| `GET`  | `/v1/models`                               | OpenAI model list (agent IDs as model names)                             |
+| `POST` | `/v1/chat/completions`                     | OpenAI chat completions — works with Open WebUI, openai-python SDK, etc. |
 
 The OpenAI-compatible `/v1` surface is **enabled by default**.  
 Set `app.openai_compat: false` in `configuration.yaml` to disable it for internal pods.
@@ -64,11 +65,11 @@ the SQL checkpointer. The session ID is the LangGraph `thread_id`.
 
 ### `fred_runtime.runtime_support` — Infrastructure adapters
 
-| Module | What it provides |
-|--------|-----------------|
-| `sql_checkpointer` | Durable LangGraph checkpointer backed by SQLite (dev) or PostgreSQL (prod) |
-| `user_token_refresher` | Transparent Keycloak token refresh for long-lived agent sessions |
-| `request_context_helpers` | FastAPI dependency helpers for extracting user/session context |
+| Module                    | What it provides                                                           |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `sql_checkpointer`        | Durable LangGraph checkpointer backed by SQLite (dev) or PostgreSQL (prod) |
+| `user_token_refresher`    | Transparent Keycloak token refresh for long-lived agent sessions           |
+| `request_context_helpers` | FastAPI dependency helpers for extracting user/session context             |
 
 ---
 
@@ -84,16 +85,16 @@ Providers: OpenAI, Azure OpenAI, Mistral, Ollama, and any LangChain-compatible b
 
 HTTP clients that connect agent tools to the Fred platform services:
 
-| Client | Connects to |
-|--------|------------|
-| `kf_http_client` | Knowledge Flow REST API (generic) |
-| `kf_vectorsearch_client` | Vector search / retrieval |
-| `kf_markdown_media_client` | Document content (Markdown + media) |
-| `kf_workspace_client` | Workspace and library management |
-| `kf_logs_client` | Audit log retrieval |
-| `kf_fast_text_client` | FastText classification |
-| `mcp_runtime` / `mcp_toolkit` | MCP server lifecycle and tool injection |
-| `context_aware_tool` | Tool base class that propagates the runtime context (user, team, token) |
+| Client                        | Connects to                                                             |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `kf_http_client`              | Knowledge Flow REST API (generic)                                       |
+| `kf_vectorsearch_client`      | Vector search / retrieval                                               |
+| `kf_markdown_media_client`    | Document content (Markdown + media)                                     |
+| `kf_workspace_client`         | Workspace and library management                                        |
+| `kf_logs_client`              | Audit log retrieval                                                     |
+| `kf_fast_text_client`         | FastText classification                                                 |
+| `mcp_runtime` / `mcp_toolkit` | MCP server lifecycle and tool injection                                 |
+| `context_aware_tool`          | Tool base class that propagates the runtime context (user, team, token) |
 
 ---
 
@@ -141,9 +142,9 @@ or overridden with `--base-url` / `FRED_AGENT_POD_URL`.
 
 Every Fred pod uses the same two-file convention:
 
-| File | Purpose |
-|------|---------|
-| `.env` (path from `ENV_FILE`) | Secrets: API keys, DB URLs, Keycloak credentials |
+| File                                           | Purpose                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------ |
+| `.env` (path from `ENV_FILE`)                  | Secrets: API keys, DB URLs, Keycloak credentials                   |
 | `configuration.yaml` (path from `CONFIG_FILE`) | App settings: port, base URL, LLM routing, observability, security |
 
 Minimal `configuration.yaml` for a local pod:
@@ -155,6 +156,7 @@ app:
   host: "0.0.0.0"
   port: 8010
   log_level: "info"
+  limit_concurrency: 200
   metrics_address: "127.0.0.1"
   metrics_port: 9115
   kpi_process_metrics_interval_sec: 10
@@ -173,6 +175,10 @@ When `observability.metrics: prometheus` is enabled, `create_agent_app(...)`
 starts a dedicated Prometheus exporter on `app.metrics_address:app.metrics_port`
 and restores the shared Fred KPI pipeline, including process and SQL pool KPIs.
 
+Set `app.limit_concurrency: null` to disable Uvicorn connection limiting, or a
+positive integer to reject excess concurrent HTTP and WebSocket connections
+with `503` before application code runs.
+
 ---
 
 ## Installation
@@ -194,6 +200,7 @@ Requires Python 3.12.
 A minimal pod is three files:
 
 **`main.py`**
+
 ```python
 from fred_runtime.app import create_agent_app, load_agent_pod_config
 from myapp.registry import REGISTRY
@@ -203,19 +210,27 @@ app = create_agent_app(registry=REGISTRY, config=config)
 ```
 
 **`__main__.py`**
+
 ```python
 import uvicorn
 from fred_runtime.app import load_agent_pod_config
 
 def main():
     config = load_agent_pod_config()
-    uvicorn.run("myapp.main:app", host=config.app.host, port=config.app.port, reload=True)
+    uvicorn.run(
+        "myapp.main:app",
+        host=config.app.host,
+        port=config.app.port,
+        limit_concurrency=config.app.limit_concurrency,
+        reload=True,
+    )
 
 if __name__ == "__main__":
     main()
 ```
 
 **`registry.py`**
+
 ```python
 from fred_sdk.contracts.models import ReActAgentDefinition
 
@@ -232,11 +247,11 @@ See [fred-samples](https://github.com/ThalesGroup/fred) for a working reference
 
 ## Related packages
 
-| Package | PyPI | Role |
-|---------|------|------|
-| `fred-core` | [pypi](https://pypi.org/project/fred-core/) | Pure utilities — logging, model factories, embeddings, portable observability |
-| `fred-sdk` | [pypi](https://pypi.org/project/fred-sdk/) | Agent authoring — ReAct, Graph, tool contracts |
-| `fred-runtime` | [pypi](https://pypi.org/project/fred-runtime/) | This package |
+| Package        | PyPI                                           | Role                                                                          |
+| -------------- | ---------------------------------------------- | ----------------------------------------------------------------------------- |
+| `fred-core`    | [pypi](https://pypi.org/project/fred-core/)    | Pure utilities — logging, model factories, embeddings, portable observability |
+| `fred-sdk`     | [pypi](https://pypi.org/project/fred-sdk/)     | Agent authoring — ReAct, Graph, tool contracts                                |
+| `fred-runtime` | [pypi](https://pypi.org/project/fred-runtime/) | This package                                                                  |
 
 ---
 

{fred_runtime-2.0.3 → fred_runtime-2.0.7}/fred_runtime/app/_catalogs.py

@@ -39,7 +39,7 @@ from typing import Any, Literal
 
 import yaml
 from fred_sdk.contracts.models import MCPServerConfiguration
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from .config import AgentPodConfig
 
@@ -114,6 +114,36 @@ class _McpCatalog(_CatalogFile):
     version: Literal["v1"] = "v1"
     servers: list[MCPServerConfiguration] = Field(default_factory=list)
 
+    @model_validator(mode="after")
+    def _reject_duplicate_server_ids(self) -> "_McpCatalog":
+        """
+        Reject duplicate MCP server ids in one catalog.
+
+        Why this exists:
+        - the managed-agent contract now stores per-server config keyed by MCP
+          server id, so duplicates would make selection and config resolution
+          ambiguous and unsafe
+
+        How to use it:
+        - triggered automatically during `_McpCatalog.model_validate(...)`
+
+        Example:
+        - `load_mcp_catalog("./config/mcp_catalog.yaml")`
+        """
+
+        seen: set[str] = set()
+        duplicates: list[str] = []
+        for server in self.servers:
+            if server.id in seen and server.id not in duplicates:
+                duplicates.append(server.id)
+            seen.add(server.id)
+        if duplicates:
+            duplicates_text = ", ".join(repr(server_id) for server_id in duplicates)
+            raise ValueError(
+                f"Duplicate MCP server id(s) in catalog: {duplicates_text}"
+            )
+        return self
+
 
 def _load_yaml_mapping(path: Path) -> dict[str, Any]:
     """