fred-runtime 0.1.0__tar.gz

fred_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: fred-runtime
+Version: 0.1.0
+Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
+Author-email: Thales <noreply@thalesgroup.com>
+License: Apache-2.0
+Project-URL: Homepage, https://fredk8.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.13,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fred-core>=1.3.1
+Requires-Dist: fred-sdk>=0.1.1
+Requires-Dist: fred-portable>=0.1.1
+Requires-Dist: langchain-mcp-adapters>=0.2.1
+Requires-Dist: langfuse>=3.0.0
+Requires-Dist: requests<3,>=2.32
+Provides-Extra: app
+Requires-Dist: fastapi>=0.116; extra == "app"
+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>=8.4.2; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Requires-Dist: ruff>=0.12.5; extra == "dev"
+
+# Fred Runtime
+
+`fred-runtime` provides platform adapters and infrastructure wiring for Fred v2 agents.
+
+It is the missing middle layer between:
+- `fred-sdk` (authoring + runtime contracts), and
+- backend implementations (databases, Knowledge Flow, MCP, tracing, checkpointers).
+
+## Why this package exists
+
+- Keep `fred-sdk` pure and portable.
+- Share runtime adapters across agentic backends and standalone agent apps.
+- Make it easy for external agent repos (like `rags-v2`) to run v2 agents with
+  consistent checkpointing and tool infrastructure.
+
+## Scope (initial)
+
+- SQL-backed checkpointer for LangGraph runtimes.
+- Runtime helper utilities extracted from agentic-backend.
+
+More runtime adapters will move here as the migration continues.

fred_runtime-0.1.0/README.md

@@ -0,0 +1,21 @@
+# Fred Runtime
+
+`fred-runtime` provides platform adapters and infrastructure wiring for Fred v2 agents.
+
+It is the missing middle layer between:
+- `fred-sdk` (authoring + runtime contracts), and
+- backend implementations (databases, Knowledge Flow, MCP, tracing, checkpointers).
+
+## Why this package exists
+
+- Keep `fred-sdk` pure and portable.
+- Share runtime adapters across agentic backends and standalone agent apps.
+- Make it easy for external agent repos (like `rags-v2`) to run v2 agents with
+  consistent checkpointing and tool infrastructure.
+
+## Scope (initial)
+
+- SQL-backed checkpointer for LangGraph runtimes.
+- Runtime helper utilities extracted from agentic-backend.
+
+More runtime adapters will move here as the migration continues.

fred_runtime-0.1.0/fred_runtime/__init__.py

@@ -0,0 +1,34 @@
+# 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.
+"""
+fred-runtime public surface.
+"""
+
+from .runtime_context import (
+    RuntimeConfig,
+    RuntimeContext,
+    RuntimeTimeouts,
+    get_runtime_context,
+    set_runtime_context,
+)
+from .runtime_support import FredSqlCheckpointer
+
+__all__ = [
+    "FredSqlCheckpointer",
+    "RuntimeConfig",
+    "RuntimeContext",
+    "RuntimeTimeouts",
+    "get_runtime_context",
+    "set_runtime_context",
+]

fred_runtime-0.1.0/fred_runtime/app/__init__.py

@@ -0,0 +1,23 @@
+# 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.
+"""
+Agent app factory — reusable FastAPI wiring for agent pods.
+
+Import from here:
+    from fred_runtime.app import create_agent_app, AgentAppSettings
+"""
+
+from .agent_app import AgentAppSettings, create_agent_app
+
+__all__ = ["AgentAppSettings", "create_agent_app"]

fred_runtime-0.1.0/fred_runtime/app/agent_app.py

@@ -0,0 +1,368 @@
+# 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.
+"""
+Reusable FastAPI app factory for Fred agent pods.
+
+Why this module exists:
+- every agent pod (rags-v2, future pods) needs identical SSE streaming plumbing:
+  RuntimeConfig wiring, BoundRuntimeContext construction, ReActRuntime lifecycle,
+  and a `POST /agents/execute/stream` endpoint
+- duplicating that across pods causes divergence bugs and maintenance overhead
+
+How to use it:
+- call `create_agent_app(registry, settings)` in your pod's `main.py`
+- the returned FastAPI app already exposes:
+    POST /api/v1/agents/execute/stream  — stream RuntimeEvent JSON over SSE
+    GET  /api/v1/agents                 — list registered agent IDs
+- pass `extra_routers` to mount additional domain-specific routers under /api/v1
+
+Example:
+    from fred_runtime.app import create_agent_app, AgentAppSettings
+    from myapp.agents.registry import REGISTRY
+    from myapp.settings import get_settings
+
+    app = create_agent_app(registry=REGISTRY, settings=get_settings())
+
+AgentAppSettings:
+- `AgentAppSettings` is a Protocol — any object (including pydantic BaseSettings
+  subclasses) that carries the required attributes satisfies it.
+- Required fields: knowledge_flow_url, chat_model_provider, chat_model_name.
+- Optional fields: google_api_key, openai_api_key, app_title, app_version.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+from fastapi import APIRouter, FastAPI, HTTPException, status
+from fastapi.responses import StreamingResponse
+from fred_sdk.contracts.context import (
+    BoundRuntimeContext,
+    PortableContext,
+    PortableEnvironment,
+    RuntimeContext,
+)
+from fred_sdk.contracts.models import ReActAgentDefinition
+from fred_sdk.contracts.react_contract import ReActInput, ReActMessage, ReActMessageRole
+from fred_sdk.contracts.runtime import ExecutionConfig, RuntimeServices
+from fred_sdk.react.react_runtime import ReActRuntime
+from pydantic import BaseModel, Field
+
+from fred_runtime.integrations.v2_runtime.adapters import DefaultFredChatModelFactory
+from fred_runtime.runtime_context import (
+    RuntimeConfig,
+    RuntimeTimeouts,
+    set_runtime_context,
+)
+from fred_runtime.runtime_context import RuntimeContext as FredRuntimeContext
+
+if TYPE_CHECKING:
+    from langchain_core.language_models.chat_models import BaseChatModel
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Settings contract — structural Protocol so any pydantic-settings subclass
+# satisfies it without inheriting from this class.
+# ---------------------------------------------------------------------------
+
+
+class AgentAppSettings:
+    """
+    Default values for the common agent pod settings fields.
+
+    Why a plain class rather than BaseSettings:
+    - fred-runtime must not pull in pydantic-settings as a required dependency
+    - pods supply their own Settings class (pydantic-settings, dataclass, etc.)
+      and it is accepted as long as it carries these attributes
+
+    How to use it:
+    - when using pydantic-settings, do NOT subclass AgentAppSettings directly —
+      just ensure your Settings class declares the same fields:
+
+        class Settings(BaseSettings):
+            knowledge_flow_url: str = "http://localhost:3000"
+            chat_model_provider: str = "google"
+            chat_model_name: str = "gemini-2.0-flash"
+            google_api_key: str = ""
+            openai_api_key: str = ""
+            app_title: str = "My Agent Pod"
+            app_version: str = "0.1.0"
+
+    - `create_agent_app` accepts any object with those attributes; the type
+      annotation is `AgentAppSettings` for documentation purposes only.
+    """
+
+    knowledge_flow_url: str = "http://localhost:3000"
+    chat_model_provider: str = "google"
+    chat_model_name: str = "gemini-2.0-flash"
+    google_api_key: str = ""
+    openai_api_key: str = ""
+    app_title: str = "Fred Agent Pod"
+    app_version: str = "0.1.0"
+
+
+# ---------------------------------------------------------------------------
+# Chat model provider builder
+# ---------------------------------------------------------------------------
+
+
+def _build_chat_model_provider(settings: Any):
+    """
+    Return a zero-argument factory for the configured chat model.
+
+    Why a callable rather than a direct instance:
+    - RuntimeConfig.chat_model_provider is lazy so the model is created on first
+      use and can be swapped per-environment via env vars
+    """
+
+    if getattr(settings, "chat_model_provider", "google") == "openai":
+
+        def _openai() -> BaseChatModel:
+            from langchain_openai import ChatOpenAI  # type: ignore[import-untyped]
+
+            return ChatOpenAI(
+                model=settings.chat_model_name,
+                api_key=settings.openai_api_key or None,
+            )
+
+        return _openai
+
+    def _google() -> BaseChatModel:
+        from langchain_google_genai import (
+            ChatGoogleGenerativeAI,  # type: ignore[import-untyped]
+        )
+
+        return ChatGoogleGenerativeAI(
+            model=settings.chat_model_name,
+            google_api_key=settings.google_api_key or None,
+        )
+
+    return _google
+
+
+# ---------------------------------------------------------------------------
+# SSE streaming helpers
+# ---------------------------------------------------------------------------
+
+
+class _AgentExecuteRequest(BaseModel):
+    """
+    Input payload for the SSE execution endpoint.
+
+    Example:
+    ```json
+    {"agent_id": "rags.sample.echo", "message": "hello"}
+    ```
+    """
+
+    agent_id: str = Field(..., min_length=1)
+    message: str = Field(..., min_length=1)
+    context: dict[str, Any] | None = None
+
+
+def _sse(payload: str) -> str:
+    return f"data: {payload}\n\n"
+
+
+async def _stream(
+    definition: ReActAgentDefinition,
+    request: _AgentExecuteRequest,
+) -> AsyncIterator[str]:
+    """
+    Execute a ReAct agent and yield SSE-framed RuntimeEvent JSON.
+
+    Why this is a standalone async generator:
+    - keeps the FastAPI endpoint thin (just returns StreamingResponse)
+    - raises no HTTPException — the endpoint already validated agent_id before
+      passing the definition in
+    """
+
+    request_id = str(uuid4())
+    ctx = request.context or {}
+    correlation_id = ctx.get("correlation_id", request_id)
+
+    portable_context = PortableContext(
+        request_id=request_id,
+        correlation_id=correlation_id,
+        actor=ctx.get("user_id", "anonymous"),
+        tenant=ctx.get("tenant", "default"),
+        environment=PortableEnvironment.DEV,
+        agent_id=definition.agent_id,
+        agent_name=definition.agent_id,
+        session_id=ctx.get("session_id"),
+        user_id=ctx.get("user_id"),
+    )
+
+    runtime_context = RuntimeContext(
+        session_id=ctx.get("session_id"),
+        user_id=ctx.get("user_id"),
+        language=ctx.get("language"),
+    )
+
+    binding = BoundRuntimeContext(
+        runtime_context=runtime_context,
+        portable_context=portable_context,
+    )
+
+    services = RuntimeServices(
+        chat_model_factory=DefaultFredChatModelFactory(),
+    )
+
+    runtime = ReActRuntime(definition=definition, services=services)
+    runtime.bind(binding)
+
+    try:
+        await runtime.activate()
+        executor = await runtime.get_executor()
+        react_input = ReActInput(
+            messages=(
+                ReActMessage(role=ReActMessageRole.USER, content=request.message),
+            ),
+        )
+        async for event in executor.stream(react_input, ExecutionConfig()):
+            yield _sse(event.model_dump_json())
+    except Exception as exc:
+        logger.exception(
+            "[fred-runtime] agent execution error agent_id=%s", definition.agent_id
+        )
+        yield _sse(json.dumps({"error": str(exc)}))
+    finally:
+        await runtime.dispose()
+
+
+# ---------------------------------------------------------------------------
+# Router builder
+# ---------------------------------------------------------------------------
+
+
+def _build_agent_router(registry: dict[str, ReActAgentDefinition]) -> APIRouter:
+    """
+    Build the FastAPI router for agent execution.
+
+    Why this is a function rather than a module-level router:
+    - the registry is provided at app-creation time, not import time
+    - each call produces an isolated router instance bound to that registry
+    """
+
+    router = APIRouter(prefix="/agents", tags=["Agents"])
+
+    @router.get("")
+    async def list_agents() -> list[str]:
+        """Return the agent IDs registered in this pod."""
+        return list(registry.keys())
+
+    @router.post("/execute/stream")
+    async def execute_stream(request: _AgentExecuteRequest) -> StreamingResponse:
+        """
+        Stream RuntimeEvent JSON over SSE for a single agent invocation.
+
+        POST /api/v1/agents/execute/stream
+        Body: {"agent_id": "...", "message": "...", "context": {...}}
+        Response: text/event-stream, each `data:` line is a RuntimeEvent JSON
+        """
+        definition = registry.get(request.agent_id)
+        if definition is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Unknown agent_id: {request.agent_id!r}. "
+                f"Known agents: {list(registry.keys())}",
+            )
+        return StreamingResponse(
+            _stream(definition, request),
+            media_type="text/event-stream",
+        )
+
+    return router
+
+
+# ---------------------------------------------------------------------------
+# Public factory
+# ---------------------------------------------------------------------------
+
+
+def create_agent_app(
+    registry: dict[str, ReActAgentDefinition],
+    settings: Any,
+    extra_routers: list[APIRouter] | None = None,
+) -> FastAPI:
+    """
+    Create a ready-to-serve FastAPI app for a Fred agent pod.
+
+    Why this exists:
+    - every agent pod needs the same SSE endpoint, RuntimeConfig wiring, and
+      lifespan hook — this factory provides all of it so pods contain zero
+      infrastructure code
+
+    How to use it:
+    - call from your pod's `main.py`, passing your agent registry and settings
+    - add `extra_routers` for domain-specific endpoints (e.g. information-system)
+
+    Example:
+    ```python
+    from fred_runtime.app import create_agent_app
+    from myapp.agents.registry import REGISTRY
+    from myapp.settings import get_settings
+    from myapp.api.router import domain_router
+
+    app = create_agent_app(
+        registry=REGISTRY,
+        settings=get_settings(),
+        extra_routers=[domain_router],
+    )
+    ```
+
+    Parameters:
+    - registry: maps agent_id → ReActAgentDefinition; built at startup, read-only at runtime
+    - settings: any object satisfying AgentAppSettings attributes
+    - extra_routers: additional APIRouter instances mounted under /api/v1
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        config = RuntimeConfig(
+            knowledge_flow_url=settings.knowledge_flow_url,
+            timeouts=RuntimeTimeouts(),
+            chat_model_provider=_build_chat_model_provider(settings),
+        )
+        set_runtime_context(FredRuntimeContext(config))
+        logger.info(
+            "Fred agent pod started — kf=%s model=%s/%s agents=%s",
+            settings.knowledge_flow_url,
+            getattr(settings, "chat_model_provider", "google"),
+            getattr(settings, "chat_model_name", "?"),
+            list(registry.keys()),
+        )
+        yield
+
+    app = FastAPI(
+        title=getattr(settings, "app_title", "Fred Agent Pod"),
+        version=getattr(settings, "app_version", "0.1.0"),
+        lifespan=lifespan,
+    )
+
+    api_router = APIRouter(prefix="/api/v1")
+    api_router.include_router(_build_agent_router(registry))
+
+    for extra in extra_routers or []:
+        api_router.include_router(extra)
+
+    app.include_router(api_router)
+    return app

fred_runtime-0.1.0/fred_runtime/common/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+"""
+Shared runtime helpers that depend on platform adapters.
+"""