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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 2.0.10
+Version: 2.0.11
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0

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

@@ -563,6 +563,21 @@ class LocalRegistryAgentInvoker(AgentInvokerPort):
 
         context_dict = request.context.model_dump(mode="json")
         context_dict.setdefault("execution_action", ExecutionGrantAction.EXECUTE.value)
+        # RFC AGENT-INVOKE: apply the caller's per-call scope onto the callee's
+        # retrieval context. These keys are read back when the callee's
+        # RuntimeContext is built, so they narrow its document/library/search world.
+        # Scope narrows only; the callee still runs under the delegated identity.
+        if request.scope is not None:
+            if request.scope.document_uids is not None:
+                context_dict["selected_document_uids"] = list(
+                    request.scope.document_uids
+                )
+            if request.scope.library_ids is not None:
+                context_dict["selected_document_libraries_ids"] = list(
+                    request.scope.library_ids
+                )
+            if request.scope.search_policy is not None:
+                context_dict["search_policy"] = request.scope.search_policy
         execute_request = _AgentExecuteRequest.model_construct(
             agent_id=request.agent_id,
             agent_instance_id=None,

{fred_runtime-2.0.10 → fred_runtime-2.0.11}/fred_runtime/graph/graph_runtime.py

@@ -36,7 +36,7 @@ import uuid
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
 from contextlib import asynccontextmanager, nullcontext
 from dataclasses import dataclass, field
-from typing import Protocol, cast
+from typing import Any, Protocol, cast
 
 from fred_core.portable import MetricsProvider
 from fred_sdk.contracts.context import (
@@ -47,6 +47,7 @@ from fred_sdk.contracts.context import (
     BoundRuntimeContext,
     ConversationTurn,
     FetchedResource,
+    InvocationScope,
     PublishedArtifact,
     ResourceFetchRequest,
     ResourceScope,
@@ -90,7 +91,7 @@ from langchain_core.messages import BaseMessage
 from langchain_core.runnables import RunnableConfig
 from langchain_core.tools import BaseTool
 from langgraph.checkpoint.base import Checkpoint, CheckpointMetadata, empty_checkpoint
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 
 from fred_runtime.runtime_support.checkpoints import (
     AsyncCheckpointReader,
@@ -100,6 +101,84 @@ from fred_runtime.runtime_support.model_metadata import runtime_metadata_from_me
 
 logger = logging.getLogger(__name__)
 
+# RFC AGENT-INVOKE: typed agent invocation — how many times invoke_agent re-asks a
+# callee for a valid JSON object before giving up and returning structured=None.
+_STRUCTURED_OUTPUT_MAX_ATTEMPTS = 2
+
+
+def _structured_output_instruction(schema: dict[str, Any]) -> str:
+    """Instruction appended to the callee message asking for schema-conformant JSON."""
+    return (
+        "\n\nIMPORTANT: Respond with ONLY a single valid JSON object that conforms to "
+        "this JSON Schema. No prose, no explanation, no markdown code fences:\n"
+        + json.dumps(schema, ensure_ascii=False)
+    )
+
+
+def _try_json_object(text: str) -> dict[str, Any] | None:
+    """Parse ``text`` as JSON, returning it only if it is a JSON object."""
+    try:
+        parsed = json.loads(text)
+    except (ValueError, TypeError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _extract_json_object(text: str) -> dict[str, Any] | None:
+    """Best-effort extraction of a single JSON object from an agent's free text.
+
+    Tries, in order: the whole string, a fenced ``` block, then the first balanced
+    ``{...}`` span. Returns ``None`` if nothing parses to an object.
+    """
+    if not text:
+        return None
+    candidate = text.strip()
+    obj = _try_json_object(candidate)
+    if obj is not None:
+        return obj
+
+    fence = candidate.find("```")
+    if fence != -1:
+        rest = candidate[fence + 3 :]
+        if rest[:4].lower() == "json":
+            rest = rest[4:]
+        end = rest.find("```")
+        if end != -1:
+            obj = _try_json_object(rest[:end].strip())
+            if obj is not None:
+                return obj
+
+    start = candidate.find("{")
+    while start != -1:
+        depth = 0
+        for index in range(start, len(candidate)):
+            char = candidate[index]
+            if char == "{":
+                depth += 1
+            elif char == "}":
+                depth -= 1
+                if depth == 0:
+                    obj = _try_json_object(candidate[start : index + 1])
+                    if obj is not None:
+                        return obj
+                    break
+        start = candidate.find("{", start + 1)
+    return None
+
+
+def _coerce_structured_payload(
+    content: str, output_schema: type[BaseModel]
+) -> dict[str, Any] | None:
+    """Extract + validate a callee's text into ``output_schema``; ``None`` on failure."""
+    parsed = _extract_json_object(content)
+    if parsed is None:
+        return None
+    try:
+        return output_schema.model_validate(parsed).model_dump(mode="json")
+    except ValidationError:
+        return None
+
+
 GraphNodeHandler = Callable[
     [BaseModel, GraphNodeContext], GraphNodeResult | Awaitable[GraphNodeResult]
 ]
@@ -683,7 +762,16 @@ class _GraphNodeExecutionContext:
         message: str,
         *,
         prior_turns: tuple[ConversationTurn, ...] = (),
+        output_schema: type[BaseModel] | None = None,
+        scope: InvocationScope | None = None,
     ) -> AgentInvocationResult:
+        """Invoke another registered agent for one turn (RFC AGENT-INVOKE).
+
+        When ``output_schema`` is given the callee is asked for a JSON object of that
+        shape; the validated payload is attached to ``result.structured`` (with a
+        bounded retry, ``None`` if it could not be coerced). When ``scope`` is given,
+        the callee's retrieval world is narrowed for this call only.
+        """
         agent_invoker = self.services.agent_invoker
         if agent_invoker is None:
             raise RuntimeError(
@@ -694,6 +782,13 @@ class _GraphNodeExecutionContext:
 
         self.emit_status("invoke_agent", detail=agent_id)
 
+        schema_dict = (
+            output_schema.model_json_schema() if output_schema is not None else None
+        )
+        max_attempts = (
+            _STRUCTURED_OUTPUT_MAX_ATTEMPTS if output_schema is not None else 1
+        )
+
         span = _start_runtime_span(
             services=self.services,
             binding=self.binding,
@@ -704,6 +799,7 @@ class _GraphNodeExecutionContext:
                 "target_agent_id": agent_id,
             },
         )
+        result: AgentInvocationResult | None = None
         try:
             with _graph_phase_timer(
                 metrics=self.services.metrics,
@@ -716,14 +812,49 @@ class _GraphNodeExecutionContext:
                     "target_agent_id": agent_id,
                 },
             ) as kpi_dims:
-                result = await agent_invoker.invoke(
-                    AgentInvocationRequest(
-                        agent_id=agent_id,
-                        message=message,
-                        context=self.binding.portable_context,
-                        prior_turns=prior_turns,
+                for attempt in range(max_attempts):
+                    effective_message = message
+                    if schema_dict is not None:
+                        effective_message = message + _structured_output_instruction(
+                            schema_dict
+                        )
+                        if attempt > 0:
+                            effective_message = (
+                                "Your previous response was not a valid JSON object. "
+                                + effective_message
+                            )
+                    result = await agent_invoker.invoke(
+                        AgentInvocationRequest(
+                            agent_id=agent_id,
+                            message=effective_message,
+                            context=self.binding.portable_context,
+                            prior_turns=prior_turns,
+                            scope=scope,
+                            output_schema=schema_dict,
+                        )
+                    )
+                    if output_schema is None or result.is_error:
+                        break
+                    structured = _coerce_structured_payload(
+                        result.content, output_schema
+                    )
+                    if structured is not None:
+                        result = result.model_copy(update={"structured": structured})
+                        break
+
+                assert result is not None
+                if (
+                    output_schema is not None
+                    and not result.is_error
+                    and result.structured is None
+                ):
+                    logger.warning(
+                        "invoke_agent(%s): could not coerce output to %s after %d "
+                        "attempt(s); returning structured=None",
+                        agent_id,
+                        output_schema.__name__,
+                        max_attempts,
                     )
-                )
                 if result.is_error:
                     kpi_dims["status"] = "error"
                     if span is not None:
@@ -737,6 +868,7 @@ class _GraphNodeExecutionContext:
         finally:
             if span is not None:
                 span.end()
+        assert result is not None
         return result
 
     async def publish_text(

{fred_runtime-2.0.10 → fred_runtime-2.0.11}/fred_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 2.0.10
+Version: 2.0.11
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0

{fred_runtime-2.0.10 → fred_runtime-2.0.11}/fred_runtime.egg-info/SOURCES.txt

@@ -90,6 +90,7 @@ tests/test_context_aware_tool.py
 tests/test_conversational_memory.py
 tests/test_eval_collector.py
 tests/test_eval_trace.py
+tests/test_graph_runtime_invoke_agent.py
 tests/test_graph_runtime_observability.py
 tests/test_history.py
 tests/test_kf_workspace_client.py

{fred_runtime-2.0.10 → fred_runtime-2.0.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fred-runtime"
-version = "2.0.10"
+version = "2.0.11"
 description = "Runtime adapters and infrastructure wiring for Fred v2 agents."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{fred_runtime-2.0.10 → fred_runtime-2.0.11}/tests/test_agent_app.py

@@ -39,6 +39,7 @@ from fred_sdk.authoring import ReActAgent, tool
 from fred_sdk.authoring.api import ToolContext
 from fred_sdk.contracts.context import (
     AgentInvocationRequest,
+    InvocationScope,
     PortableContext,
     PortableEnvironment,
 )
@@ -994,6 +995,98 @@ def test_local_registry_invoker_reuses_runtime_execute_projection(monkeypatch) -
     assert context["execution_action"] == "execute"
 
 
+def test_local_registry_invoker_applies_invocation_scope(monkeypatch) -> None:
+    """
+    RFC AGENT-INVOKE: a per-call ``InvocationScope`` narrows the callee's retrieval.
+
+    Why this exists:
+    - typed/scoped agent invocation lets one agent restrict the callee to specific
+      documents/libraries; the scope must reach the callee's RuntimeContext, which is
+      built from the context dict the invoker forwards
+    - this proves the scope fields land on that context dict (and only when given)
+
+    How to use it:
+    - run in the default offline `fred-runtime` test suite
+    """
+
+    seen: dict[str, object] = {}
+
+    async def _fake_iterate_runtime_event_payloads(
+        definition,
+        request,
+        access_token=None,
+        *,
+        team_id=None,
+        registry=None,
+        exchange_id=None,
+    ):
+        _ = (definition, access_token, team_id, registry, exchange_id)
+        seen["context"] = dict(request.context or {})
+        yield {"kind": "final", "sequence": 0, "content": "ok"}
+
+    monkeypatch.setattr(
+        agent_app_module,
+        "_iterate_runtime_event_payloads",
+        _fake_iterate_runtime_event_payloads,
+    )
+
+    definition = _EchoAgent()
+    invoker = agent_app_module.LocalRegistryAgentInvoker(
+        registry={definition.agent_id: definition},
+        access_token="token-1",
+    )
+
+    def _portable() -> PortableContext:
+        return PortableContext(
+            request_id="req-1",
+            correlation_id="corr-1",
+            actor="alice",
+            tenant="tenant-a",
+            environment=PortableEnvironment.DEV,
+            trace_id="trace-1",
+            session_id="session-1",
+            user_id="alice",
+            team_id="fredlab",
+        )
+
+    # With scope → narrowing fields land on the forwarded context dict.
+    asyncio.run(
+        invoker.invoke(
+            AgentInvocationRequest(
+                agent_id=definition.agent_id,
+                message="hello",
+                context=_portable(),
+                scope=InvocationScope(
+                    document_uids=["doc-a", "doc-b"],
+                    library_ids=["lib-1"],
+                    search_policy="strict",
+                ),
+            )
+        )
+    )
+    context = seen["context"]
+    assert isinstance(context, dict)
+    assert context["selected_document_uids"] == ["doc-a", "doc-b"]
+    assert context["selected_document_libraries_ids"] == ["lib-1"]
+    assert context["search_policy"] == "strict"
+
+    # Without scope → no narrowing keys are injected (no regression).
+    seen.clear()
+    asyncio.run(
+        invoker.invoke(
+            AgentInvocationRequest(
+                agent_id=definition.agent_id,
+                message="hello",
+                context=_portable(),
+            )
+        )
+    )
+    context = seen["context"]
+    assert isinstance(context, dict)
+    assert "selected_document_uids" not in context
+    assert "search_policy" not in context
+
+
 def test_resume_rejects_non_pending_checkpoint(monkeypatch, tmp_path) -> None:
     """
     Ensure resume requests fail fast when the checkpoint is not waiting for input.

fred_runtime-2.0.11/tests/test_graph_runtime_invoke_agent.py

@@ -0,0 +1,154 @@
+# 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.
+
+"""Tests for typed, scoped agent invocation (RFC AGENT-INVOKE).
+
+Covers the JSON-coercion helpers and ``GraphNodeContext.invoke_agent``'s structured
+output + per-call scope + bounded-retry behaviour against a fake invoker.
+"""
+
+import asyncio
+
+from fred_sdk.contracts.context import (
+    AgentInvocationRequest,
+    AgentInvocationResult,
+    BoundRuntimeContext,
+    InvocationScope,
+    PortableContext,
+    PortableEnvironment,
+    RuntimeContext,
+)
+from fred_sdk.contracts.runtime import AgentInvokerPort, RuntimeServices
+from pydantic import BaseModel
+
+from fred_runtime.graph.graph_runtime import (
+    _GraphNodeExecutionContext,
+    _coerce_structured_payload,
+    _extract_json_object,
+)
+
+
+class _Extraction(BaseModel):
+    component: str
+    version: str | None = None
+
+
+class _FakeInvoker(AgentInvokerPort):
+    """Records requests and replays a fixed list of response contents."""
+
+    def __init__(self, contents: list[str]) -> None:
+        self._contents = contents
+        self.requests: list[AgentInvocationRequest] = []
+
+    async def invoke(self, request: AgentInvocationRequest) -> AgentInvocationResult:
+        index = min(len(self.requests), len(self._contents) - 1)
+        self.requests.append(request)
+        return AgentInvocationResult(
+            agent_id=request.agent_id, content=self._contents[index]
+        )
+
+
+def _context(invoker: AgentInvokerPort) -> _GraphNodeExecutionContext:
+    binding = BoundRuntimeContext(
+        runtime_context=RuntimeContext(session_id="s", user_id="u", team_id="t"),
+        portable_context=PortableContext(
+            request_id="r",
+            correlation_id="c",
+            actor="u",
+            tenant="t",
+            environment=PortableEnvironment.DEV,
+            session_id="s",
+            user_id="u",
+            team_id="t",
+        ),
+    )
+    return _GraphNodeExecutionContext(
+        binding=binding,
+        services=RuntimeServices(agent_invoker=invoker),
+        model=None,
+        model_resolver=None,
+        graph_agent_id="caller",
+        node_id="node-1",
+        allowed_tool_refs=frozenset(),
+        runtime_tools={},
+        tuning_values={},
+    )
+
+
+# --- pure helpers ---------------------------------------------------------
+
+
+def test_extract_json_object_handles_plain_fenced_and_embedded() -> None:
+    assert _extract_json_object('{"a": 1}') == {"a": 1}
+    assert _extract_json_object('```json\n{"a": 2}\n```') == {"a": 2}
+    assert _extract_json_object('text {"a": 3} more') == {"a": 3}
+    assert _extract_json_object("no json") is None
+    # a bare JSON array is not an object
+    assert _extract_json_object("[1, 2, 3]") is None
+
+
+def test_coerce_structured_payload_validates_against_schema() -> None:
+    assert _coerce_structured_payload('{"component": "nginx"}', _Extraction) == {
+        "component": "nginx",
+        "version": None,
+    }
+    # missing required field → no coercion
+    assert _coerce_structured_payload('{"version": "1"}', _Extraction) is None
+
+
+# --- invoke_agent: structured output + scope + retry ----------------------
+
+
+def test_invoke_agent_returns_validated_structured_payload() -> None:
+    invoker = _FakeInvoker(['{"component": "nginx", "version": "1.25"}'])
+    ctx = _context(invoker)
+
+    result = asyncio.run(
+        ctx.invoke_agent("callee", "is nginx installed?", output_schema=_Extraction)
+    )
+
+    assert result.structured == {"component": "nginx", "version": "1.25"}
+    assert len(invoker.requests) == 1
+    # the callee was asked for schema-conformant JSON, and the schema travelled too
+    assert "JSON Schema" in invoker.requests[0].message
+    assert invoker.requests[0].output_schema is not None
+
+
+def test_invoke_agent_retries_then_gives_up_with_none() -> None:
+    invoker = _FakeInvoker(["not json", "still not json"])
+    ctx = _context(invoker)
+
+    result = asyncio.run(
+        ctx.invoke_agent("callee", "extract", output_schema=_Extraction)
+    )
+
+    assert result.structured is None
+    assert len(invoker.requests) == 2  # bounded retry happened
+    assert result.is_error is False  # text answer still returned
+
+
+def test_invoke_agent_forwards_scope_and_stays_backward_compatible() -> None:
+    invoker = _FakeInvoker(["plain text answer"])
+    ctx = _context(invoker)
+
+    scope = InvocationScope(document_uids=["doc-1"], search_policy="strict")
+    result = asyncio.run(ctx.invoke_agent("callee", "hi", scope=scope))
+
+    assert result.content == "plain text answer"
+    assert result.structured is None  # no schema requested
+    assert len(invoker.requests) == 1
+    assert invoker.requests[0].scope == scope
+    assert invoker.requests[0].output_schema is None
+    # message is untouched when no schema is requested
+    assert invoker.requests[0].message == "hi"