fred-sdk 3.4.2__tar.gz → 3.4.3__tar.gz

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-sdk
-Version: 3.4.2
+Version: 3.4.3
 Summary: Authoring SDK for Fred agents — graph, ReAct, and team agent primitives.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -12,7 +12,7 @@ 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>=3.4.1
+Requires-Dist: fred-core>=3.8.2
 Requires-Dist: pydantic<3.0.0,>=2.7.0
 Requires-Dist: langchain-core>=0.3.0
 Requires-Dist: langchain>=1.3.14

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk/authoring/authored_tool_runtime.py

@@ -316,7 +316,7 @@ def _coerce_tool_return(
     *,
     tool_ref: str,
     value: object,
-    context: "ToolContext",
+    context: ToolContext,
     success_message: str | None,
 ) -> ToolInvocationResult:
     """

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk/contracts/__init__.py

@@ -63,11 +63,7 @@ from .openai_compat import (
     OpenAIToolCall,
     OpenAIToolCallFunction,
 )
-from .prompt_utils import (
-    PROMPT_SAFE_TOKENS,
-    PromptTemplateError,
-    validate_prompt_template,
-)
+from .prompt_utils import PROMPT_SAFE_TOKENS
 from .runtime import RuntimeErrorEvent, TurnPersistedEvent
 from .ui_part_union import (
     BASE_UI_PARTS,
@@ -120,8 +116,6 @@ __all__ = [
     "OpenAIModelList",
     "OpenAIToolCall",
     "OpenAIToolCallFunction",
-    # Prompt template token registry and validation
+    # Prompt template token registry
     "PROMPT_SAFE_TOKENS",
-    "PromptTemplateError",
-    "validate_prompt_template",
 ]

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk/contracts/capability/manifest.py

@@ -391,6 +391,18 @@ class CapabilityCatalogEntry(BaseModel):
     # so the admin row shows no reasoning control at all (an administrator
     # cannot make a model reason). Always empty for kind="tool"/"agent".
     model_thinking_profile_ids: tuple[str, ...] = Field(default_factory=tuple)
+    # The ops-authored `settings.reasoning_effort` of the model's thinking
+    # profile — derived from the settings, the single source of truth (review
+    # 2026-08-12: no separate supported-efforts declaration). Displayed by the
+    # composer's reasoning menu as the level a reasoning turn actually runs
+    # with; None when no thinking profile ships the key. Only `kind="model"`
+    # entries populate it.
+    model_reasoning_effort: str | None = None
+    # The ops-authored `model_display_name` from `models_catalog.yaml` — the
+    # label the composer shows for this model. None = unnamed, and the
+    # frontend derives one from the capability id. Display only; nothing
+    # routes or authorizes on it. Only `kind="model"` entries populate it.
+    model_display_name: str | None = None
 
     @classmethod
     def from_manifest(

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk/contracts/context.py

@@ -42,7 +42,7 @@ from enum import Enum
 from typing import Annotated, Any, Dict, Literal, Optional
 
 from fred_core.store import VectorSearchHit
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 # NOTE: This module is the canonical home for portable context + UI parts.
 # Keep Link/Geo parts and RuntimeContext here to avoid circular imports.
@@ -99,7 +99,7 @@ class GeoPart(BaseModel):
 class TeamOperationRouteRule(BaseModel):
     """
     One team-authored model-routing override for a specific runtime operation
-    (`TEAM-ROUTING-POLICY-RFC.md` §3/§8). Lives in `fred-sdk` — not
+    or agent (`TEAM-ROUTING-POLICY-RFC.md` §3/§8). Lives in `fred-sdk` — not
     `fred-runtime` or `control-plane-backend` — because both of those already
     depend on `fred_sdk.contracts` and this type is shared verbatim by both:
     control-plane stores/validates it (`TeamRoutingPolicy`), fred-runtime
@@ -109,10 +109,24 @@ class TeamOperationRouteRule(BaseModel):
     model_config = ConfigDict(frozen=True)
 
     rule_id: str = Field(..., min_length=1)
-    operation: str = Field(..., min_length=1)
+    # Optional operation scope: when set, the rule only applies to this operation.
+    # None = applies to every operation (wildcard). Resolved by `resolve_team_override`
+    # alongside purpose/agent_id.
+    operation: str | None = None
     purpose: str | None = None
+    # Optional per-agent scope: when set, the rule only applies to this agent
+    # (matched against the request's `agent_id`). None = applies to every agent
+    # of the team (wildcard) — the historical behaviour, so existing rules are
+    # unchanged. Resolved by `resolve_team_override` alongside operation/purpose.
+    agent_id: str | None = None
     target_profile_id: str = Field(..., min_length=1)
 
+    @model_validator(mode="after")
+    def validate_at_least_one_criterion(self) -> "TeamOperationRouteRule":
+        if self.operation is None and self.agent_id is None:
+            raise ValueError("Rule must specify at least one of: operation, agent_id")
+        return self
+
 
 class RuntimeContext(BaseModel):
     """
@@ -239,6 +253,12 @@ class RuntimeContext(BaseModel):
             "guarantee: level 2 remains a ceiling this cannot raise (§5.3)."
         ),
     )
+    # NOTE (2026-08-12): a per-question `reasoning_effort` override was built
+    # and withdrawn the same day — providers disagree on accepted values
+    # (Mistral small 400s on low/medium), and the declaration machinery it
+    # required wasn't worth the surface. The effort a reasoning turn runs
+    # with is the ops-authored `settings.reasoning_effort` of the resolved
+    # profile, full stop; the user's choice is the boolean above.
 
     # Group D — Content and preferences (will migrate to proper homes over time)
     language: Optional[str] = None

fred_sdk-3.4.3/fred_sdk/contracts/prompt_utils.py

@@ -0,0 +1,55 @@
+# 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.
+
+"""
+Canonical prompt-template token registry.
+
+Why this module exists:
+- define the single source of truth for which {tokens} are substituted in
+  user-authored system prompts
+- let the renderer in fred-runtime import that token set, so the registry and
+  the substitution stay in sync automatically
+
+Why there is no validator here (#2277):
+- the renderer substitutes a token only when it is present in this registry and
+  otherwise leaves the matched text verbatim, so an unrecognized `{token}` is
+  already harmless — it renders as itself and cannot crash the agent
+- rejecting unknown tokens at save time was therefore a false positive: it
+  blocked prompts such as `Hello {name}` that would have rendered correctly,
+  with no in-product documentation or UI hint to warn the author
+- the accepted trade-off is that a typo (`{todya}`) now reaches the prompt as
+  literal text instead of being caught on write; that failure is visible to the
+  author in the agent's output
+
+How to use:
+- import PROMPT_SAFE_TOKENS to get the canonical {token} → description map
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# Canonical set of runtime tokens available in user-authored system prompts.
+# Key   = token name (used inside {…} in the prompt text).
+# Value = human-readable description, intended for a prompt-editor UI hint.
+#
+# To add a new supported token: add one entry here plus its runtime value in
+# `safe_prompt_token_map` (fred-runtime) — no other site needs to change.
+PROMPT_SAFE_TOKENS: Final[dict[str, str]] = {
+    "today": "ISO-8601 date at execution time (e.g. 2026-05-07)",
+    "response_language": "Human-readable response language (e.g. English, français)",
+    "session_id": "Active session identifier",
+    "user_id": "Authenticated user identifier",
+    "agent_id": "Agent definition identifier",
+}

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk/contracts/runtime.py

@@ -33,10 +33,11 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Annotated, Any, Generic, List, Literal, Protocol, TypeAlias, TypeVar
 
+from fred_core.history.history_schema import FinishReason, coerce_finish_reason
 from fred_core.kpi import BaseKPIWriter
 from fred_core.portable import MetricsProvider, Span, Tracer
 from fred_core.store import VectorSearchHit
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from .context import (
     AgentInvocationRequest,
@@ -310,7 +311,16 @@ class FinalRuntimeEvent(RuntimeEventBase):
     ui_parts: tuple[UiPart, ...] = ()
     model_name: str | None = None
     token_usage: dict[str, int] | None = None
-    finish_reason: str | None = None
+    finish_reason: FinishReason | None = None
+
+    # Same tolerant coercion as `ChatMetadata.finish_reason` (fred-core): a raw
+    # provider value that isn't already normalized (or one this build has never
+    # seen) must never fail this frozen model's construction — it degrades to
+    # `other` instead.
+    @field_validator("finish_reason", mode="before")
+    @classmethod
+    def _normalize_finish_reason(cls, v: object) -> FinishReason | None:
+        return coerce_finish_reason(v)
 
 
 class TurnPersistedEvent(RuntimeEventBase):
@@ -785,6 +795,30 @@ class DocumentTreeResult(FrozenModel):
     truncated: bool = False
 
 
+class DocumentLabelReference(FrozenModel):
+    """Lean document reference for a label-page result — just enough for a
+    capability to identify and chain into another tool (e.g. summarize by
+    uid), not a full document payload."""
+
+    document_uid: str
+    document_name: str
+
+
+class DocumentLabelPageResult(FrozenModel):
+    """Typed result of one paginated, exhaustive label resolution — the
+    flat sibling of `DocumentTreeResult`, for a caller that needs EVERY
+    document carrying a label rather than a folder-oriented, size-budgeted
+    view (see `DocumentTreePort.list_by_label`)."""
+
+    label: str = ""
+    documents: tuple[DocumentLabelReference, ...] = ()
+    total: int = 0
+    offset: int = 0
+    limit: int = 50
+    next_offset: int | None = None
+    has_more: bool = False
+
+
 class DocumentSummaryResult(FrozenModel):
     """Typed result of one on-demand document summarization."""
 
@@ -824,6 +858,10 @@ class DocumentTreePort(ABC):
     only — never a caller-supplied context, identity, or access token. Auth
     and identity come solely from the adapter's privately-captured per-turn
     binding, which never enters `CapabilityContext`.
+
+    Read-only projection over already-ingested documents — never a workspace,
+    never free-form files, never byte storage. Distinct from `workspace_fs`
+    (`RuntimeServices`), which is the mutable, persistent file domain.
     """
 
     @abstractmethod
@@ -842,6 +880,37 @@ class DocumentTreePort(ABC):
         by the session binding before calling Knowledge Flow, completing
         `turn_option ⊆ capability_config ⊆ session_binding`. Raises
         `DocumentPortCallError` on transport failure.
+
+        No business-label filtering here, deliberately: a folder tree renders
+        every folder in scope, size-budgeted to fit one response — the wrong
+        shape for "give me every document labeled X", which needs an
+        exhaustive, paginated answer instead. See `list_by_label` for that
+        need.
+        """
+
+    @abstractmethod
+    async def list_by_label(
+        self,
+        *,
+        label: str,
+        offset: int = 0,
+        limit: int = 50,
+    ) -> DocumentLabelPageResult:
+        """
+        Return one deterministic page of the documents carrying `label` —
+        exhaustive, paginated business-label resolution. This is the ONLY
+        label-search surface on this port: `tree()` does no label filtering
+        at all (see its docstring) — a folder tree answers "where", this
+        method answers "give me every document with this label", and mixing
+        the two into one size-budgeted response was the exact design mistake
+        this split undoes.
+
+        KNOWN GAP: does NOT accept `library_tag_ids` — Knowledge Flow's label
+        resolution (`MetadataService.get_document_uids_with_any_label`)
+        narrows only by the caller's document-level READ permission, never by
+        folder/library scope. Flagged, not silently implemented as a no-op
+        parameter; narrowing this is follow-up work, not yet built. Raises
+        `DocumentPortCallError` on transport failure.
         """
 
 
@@ -872,6 +941,102 @@ class DocumentSummarizePort(ABC):
         """
 
 
+class DocumentMarkdownResult(FrozenModel):
+    """
+    Typed result of one paginated read of a document's FULL parsed markdown
+    (DOCREAD-01).
+
+    Distinct from the two neighbouring shapes:
+    - `DocumentSummaryResult` is a lossy overview — this is the document
+      verbatim, nothing dropped;
+    - `DocumentRawContent` is the original uploaded bytes (a PDF/DOCX blob the
+      model cannot read as text) — this is the markdown Knowledge Flow parsed at
+      ingestion (`output.md`), directly usable by the model.
+
+    Pagination is the whole point (it is why `document_summarize`'s "half
+    answer" failure mode cannot recur here): `text` is one bounded window
+    `[offset : offset+max_chars]`, and `next_offset` is the offset to pass for
+    the next page or `None` once the end of the document has been reached — so
+    an exhaustive read always knows whether more text remains.
+    """
+
+    document_uid: str
+    text: str = ""
+    offset: int = 0
+    next_offset: int | None = None
+    total_chars: int = 0
+
+
+class DocumentMarkdownPort(ABC):
+    """
+    Capability-safe paginated read of a corpus document's FULL parsed markdown
+    by uid (DOCREAD-01). Same doctrine as `DocumentSummarizePort`: takes SCOPE
+    PARAMETERS only (the uid plus the page window) and NEVER a caller-supplied
+    context, identity, or access token — auth/identity come solely from the
+    adapter's privately-captured per-turn binding, and Knowledge Flow's own
+    per-document ReBAC is the real authorization gate. Document uids are
+    internal working identifiers: tools use them freely but never surface them
+    to the end user.
+    """
+
+    @abstractmethod
+    async def fetch_markdown(
+        self,
+        document_uid: str,
+        *,
+        offset: int = 0,
+        max_chars: int = 8000,
+    ) -> DocumentMarkdownResult:
+        """
+        Return one bounded page `[offset : offset+max_chars]` of the document's
+        full markdown. The result's `next_offset` is the offset to pass to read
+        the following page, or `None` when the end has been reached. Raises
+        `DocumentPortCallError` on transport failure.
+        """
+
+
+class DocumentExtractionResult(FrozenModel):
+    """Typed result of one server-side exhaustive extraction (DOCREAD-01 Phase 2).
+
+    `extraction` is the consolidated, de-duplicated list of every matching item
+    (markdown bullets, in document order) — produced by a map over EVERY chunk of
+    the document with a concatenate/de-dupe reduce, never a lossy summary.
+    """
+
+    document_uid: str
+    extraction: str = ""
+    item_count: int = 0
+    chunks_processed: int = 0
+    truncated: bool = False
+
+
+class DocumentExtractionPort(ABC):
+    """
+    Capability-safe server-side exhaustive extraction (DOCREAD-01 Phase 2). Same
+    doctrine as `DocumentSummarizePort`: the caller passes only the document uid
+    and the extraction instruction; identity stays private to the adapter and
+    Knowledge Flow's per-document ReBAC is the gate.
+
+    Unlike `DocumentMarkdownPort` (which streams pages for the AGENT to process,
+    N model calls), this runs the whole map-reduce on the Knowledge Flow side in
+    ONE call — so the agent never bursts many model calls of its own, and the
+    provider throttling is absorbed server-side (bounded concurrency + 429
+    backoff). Long-running; adapters use an extended read timeout.
+    """
+
+    @abstractmethod
+    async def extract(
+        self,
+        document_uid: str,
+        *,
+        instruction: str,
+    ) -> DocumentExtractionResult:
+        """
+        Exhaustively extract every item matching `instruction` from the document.
+        Raises `DocumentPortCallError` on transport failure.
+        """
+
+
 @dataclass(frozen=True, slots=True)
 class RuntimeServices:
     """
@@ -927,6 +1092,16 @@ class RuntimeServices:
     # the positional meaning of any field an external positional-argument
     # caller might already rely on.
     kpi_writer: BaseKPIWriter | None = None
+    # Paginated full-markdown read of a corpus document by uid (DOCREAD-01):
+    # powers the `document_verbatim` / `document_extract` capabilities. Same
+    # doctrine/optionality as the other document ports — the per-turn binding
+    # and raw access token stay private to the adapter. Appended after
+    # `kpi_writer` for the same positional-safety reason noted above.
+    document_markdown: DocumentMarkdownPort | None = None
+    # Server-side exhaustive extraction (DOCREAD-01 Phase 2): powers the
+    # `document_extract` capability's single-call path. Same doctrine/optionality
+    # as the other document ports.
+    document_extraction: DocumentExtractionPort | None = None
 
 
 InputModelT = TypeVar("InputModelT", bound=BaseModel)

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk/contracts/ui_part_union.py

@@ -97,6 +97,7 @@ def rebuild_ui_part_union(extra_parts: Sequence[type[BaseModel]] = ()) -> None:
             members.append(part)
     if tuple(members) == _current_members:
         return  # already the registered union — keep validators/caches warm
+    # codeql[py/unused-global-variable]
     _current_members = tuple(members)
     union = members[0] if len(members) == 1 else Union[tuple(members)]
     new_alias = Annotated[union, Field(discriminator="type")]

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-sdk
-Version: 3.4.2
+Version: 3.4.3
 Summary: Authoring SDK for Fred agents — graph, ReAct, and team agent primitives.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0
@@ -12,7 +12,7 @@ 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>=3.4.1
+Requires-Dist: fred-core>=3.8.2
 Requires-Dist: pydantic<3.0.0,>=2.7.0
 Requires-Dist: langchain-core>=0.3.0
 Requires-Dist: langchain>=1.3.14

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ tests/test_capability_contracts.py
 tests/test_conversational_memory.py
 tests/test_document_search_port_1906.py
 tests/test_execution_contracts.py
+tests/test_final_runtime_event_finish_reason.py
 tests/test_graph_choice_step.py
 tests/test_graph_models.py
 tests/test_hello.py

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/fred_sdk.egg-info/requires.txt

@@ -1,4 +1,4 @@
-fred-core>=3.4.1
+fred-core>=3.8.2
 pydantic<3.0.0,>=2.7.0
 langchain-core>=0.3.0
 langchain>=1.3.14

{fred_sdk-3.4.2 → fred_sdk-3.4.3}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "fred-sdk"
-version = "3.4.2"
+version = "3.4.3"
 description = "Authoring SDK for Fred agents — graph, ReAct, and team agent primitives."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Thales", email = "noreply@thalesgroup.com" }]
 dependencies = [
-  "fred-core>=3.4.1",
+  "fred-core>=3.8.2",
   "pydantic>=2.7.0,<3.0.0",
   "langchain-core>=0.3.0",
   "langchain>=1.3.14",

fred_sdk-3.4.3/tests/test_final_runtime_event_finish_reason.py

@@ -0,0 +1,43 @@
+# 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.
+
+"""
+Offline unit test: `FinalRuntimeEvent.finish_reason` — the live SSE contract
+must normalize a raw provider finish-reason value the same way `ChatMetadata`
+(fred-core, persisted history) does, and — being a frozen, `extra="forbid"`
+model — must never fail construction over a value this build doesn't
+recognize.
+"""
+
+from __future__ import annotations
+
+from fred_core.history.history_schema import FinishReason
+from fred_sdk.contracts.runtime import FinalRuntimeEvent
+
+
+def test_final_runtime_event_normalizes_a_raw_provider_value() -> None:
+    event = FinalRuntimeEvent.model_validate({"kind": "final", "finish_reason": "STOP"})
+    assert event.finish_reason is FinishReason.stop
+
+
+def test_final_runtime_event_coerces_an_unrecognized_value_to_other() -> None:
+    event = FinalRuntimeEvent.model_validate(
+        {"kind": "final", "finish_reason": "UNKNOWN_7"}
+    )
+    assert event.finish_reason is FinishReason.other
+
+
+def test_final_runtime_event_finish_reason_defaults_to_none() -> None:
+    event = FinalRuntimeEvent.model_validate({"kind": "final"})
+    assert event.finish_reason is None

fred_sdk-3.4.3/tests/test_prompt_utils.py

@@ -0,0 +1,80 @@
+# 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 fred_sdk.contracts.prompt_utils.
+
+The module is now a pure registry: save-time validation of unknown {tokens}
+was removed in #2277 because the fred-runtime renderer already preserves any
+token outside PROMPT_SAFE_TOKENS verbatim, making rejection a false positive.
+
+These tests pin the registry itself — its exact key set is a contract shared
+with `safe_prompt_token_map` in fred-runtime, and adding a key here without
+adding the matching runtime value would render that token as empty text.
+"""
+
+import fred_sdk.contracts.prompt_utils as prompt_utils
+from fred_sdk.contracts import PROMPT_SAFE_TOKENS as PROMPT_SAFE_TOKENS_REEXPORT
+
+PROMPT_SAFE_TOKENS = prompt_utils.PROMPT_SAFE_TOKENS
+
+# ---------------------------------------------------------------------------
+# PROMPT_SAFE_TOKENS registry
+# ---------------------------------------------------------------------------
+
+
+def test_safe_tokens_contains_expected_keys() -> None:
+    assert set(PROMPT_SAFE_TOKENS.keys()) == {
+        "today",
+        "response_language",
+        "session_id",
+        "user_id",
+        "agent_id",
+    }
+
+
+def test_safe_tokens_all_have_non_empty_descriptions() -> None:
+    for key, desc in PROMPT_SAFE_TOKENS.items():
+        assert desc, f"Token '{key}' has an empty description"
+
+
+def test_safe_tokens_are_simple_identifiers() -> None:
+    """
+    Every registry key must be a bare identifier.
+
+    The renderer matches `\\{([a-zA-Z_][a-zA-Z0-9_]*)\\}`; a key that does not
+    fit that shape could never be substituted and would silently do nothing.
+    """
+    for key in PROMPT_SAFE_TOKENS:
+        assert key.isidentifier(), f"Token '{key}' is not a simple identifier"
+
+
+def test_registry_is_re_exported_from_contracts_package() -> None:
+    assert PROMPT_SAFE_TOKENS_REEXPORT is PROMPT_SAFE_TOKENS
+
+
+# ---------------------------------------------------------------------------
+# Removed surface (#2277)
+# ---------------------------------------------------------------------------
+
+
+def test_validator_surface_is_gone() -> None:
+    """
+    The validator must not come back without a deliberate decision.
+
+    Re-adding save-time rejection would once again block prompts such as
+    `Hello {name}` that the renderer handles correctly.
+    """
+    assert not hasattr(prompt_utils, "validate_prompt_template")
+    assert not hasattr(prompt_utils, "PromptTemplateError")

fred_sdk-3.4.2/fred_sdk/contracts/prompt_utils.py

@@ -1,112 +0,0 @@
-# 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.
-
-"""
-Canonical prompt-template token registry and validation utilities.
-
-Why this module exists:
-- define the single source of truth for which {tokens} are supported in
-  user-authored system prompts
-- provide a validator that control-plane can call before persisting any
-  prompt field value, so broken templates are rejected at save time rather
-  than crashing the agent at execution time
-- let the renderer in fred-runtime import the same token set so the two
-  surfaces stay in sync automatically
-
-How to use:
-- import PROMPT_SAFE_TOKENS to get the canonical {token} → description map
-- call validate_prompt_template(text) before persisting a prompt field;
-  an empty return list means the template is safe to store
-"""
-
-from __future__ import annotations
-
-import re
-from typing import Final
-
-from pydantic import BaseModel
-
-# Matches only {simple_identifier} — no dots, no digits, no spaces, not empty.
-# This is the only pattern that can ever be a valid template token.
-_SIMPLE_TOKEN_RE: Final = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
-
-# Canonical set of runtime tokens available in user-authored system prompts.
-# Key   = token name (used inside {…} in the prompt text).
-# Value = human-readable description forwarded to the frontend in error messages.
-#
-# To add a new supported token: add one entry here. The renderer and validator
-# pick it up automatically — no other site needs to change.
-PROMPT_SAFE_TOKENS: Final[dict[str, str]] = {
-    "today": "ISO-8601 date at execution time (e.g. 2026-05-07)",
-    "response_language": "Human-readable response language (e.g. English, français)",
-    "session_id": "Active session identifier",
-    "user_id": "Authenticated user identifier",
-    "agent_id": "Agent definition identifier",
-}
-
-# Pre-built hint string included in error messages so users see the full list.
-_SUPPORTED_HINT: Final[str] = ", ".join(f"{{{k}}}" for k in PROMPT_SAFE_TOKENS)
-
-
-class PromptTemplateError(BaseModel):
-    """One validation error found in a prompt template."""
-
-    pattern: str
-    reason: str
-
-
-def validate_prompt_template(text: str) -> list[PromptTemplateError]:
-    """
-    Validate a user-authored prompt template text against PROMPT_SAFE_TOKENS.
-
-    Why this exists:
-    - prompt fields submitted via the control-plane API are stored before the
-      agent ever executes; without up-front validation a bad template silently
-      breaks the agent on the first chat message
-
-    How to use:
-    - call before persisting any field whose FieldSpec.type == "prompt"
-    - an empty return list means the template is safe to store
-    - a non-empty list means the create/update should be rejected with 422
-
-    Validation rule:
-    - any {simple_identifier} not in PROMPT_SAFE_TOKENS is an error
-    - non-simple brace patterns ({}, {0}, {toto.toto}, { x }) are not matched
-      and are silently preserved as literals by the renderer — no error raised,
-      because they cannot be confused with template tokens (they will never be
-      substituted and they no longer crash the renderer)
-
-    Example:
-    - validate_prompt_template("Today is {today}.")  →  []
-    - validate_prompt_template("Hello {name}!")      →  [PromptTemplateError(...)]
-    """
-    errors: list[PromptTemplateError] = []
-    seen: set[str] = set()
-
-    for match in _SIMPLE_TOKEN_RE.finditer(text):
-        token = match.group(1)
-        raw = match.group(0)
-        if token not in PROMPT_SAFE_TOKENS and raw not in seen:
-            seen.add(raw)
-            errors.append(
-                PromptTemplateError(
-                    pattern=raw,
-                    reason=(
-                        f"Unknown template token. "
-                        f"Supported tokens are: {_SUPPORTED_HINT}."
-                    ),
-                )
-            )
-
-    return errors

fred_sdk-3.4.2/tests/test_prompt_utils.py

@@ -1,167 +0,0 @@
-# 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 fred_sdk.contracts.prompt_utils.
-
-Ref: docs/backlog/BACKLOG.md §3d.9 (P1) — PROMPT_SAFE_TOKENS registry,
-     validate_prompt_template (unknown tokens → error, non-simple braces preserved),
-     crash-proof rendering for code braces and dotted-notation patterns.
-"""
-
-import pytest
-from fred_sdk.contracts.prompt_utils import (
-    PROMPT_SAFE_TOKENS,
-    validate_prompt_template,
-)
-
-# ---------------------------------------------------------------------------
-# PROMPT_SAFE_TOKENS registry
-# ---------------------------------------------------------------------------
-
-
-def test_safe_tokens_contains_expected_keys() -> None:
-    assert set(PROMPT_SAFE_TOKENS.keys()) == {
-        "today",
-        "response_language",
-        "session_id",
-        "user_id",
-        "agent_id",
-    }
-
-
-def test_safe_tokens_all_have_non_empty_descriptions() -> None:
-    for key, desc in PROMPT_SAFE_TOKENS.items():
-        assert desc, f"Token '{key}' has an empty description"
-
-
-# ---------------------------------------------------------------------------
-# Clean templates — no errors expected
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.parametrize(
-    "text",
-    [
-        "You are a helpful assistant.",
-        "Today is {today}.",
-        "Respond in {response_language}.",
-        "Session: {session_id}, User: {user_id}, Agent: {agent_id}.",
-        "All tokens: {today} {response_language} {session_id} {user_id} {agent_id}.",
-        # Code braces are not simple identifiers — preserved as literals, no error
-        "function main(workbook: ExcelScript.Workbook) { doSomething(); }",
-        # Dotted notation is not a simple identifier — left as literal, no error
-        "{toto.toto} should not be flagged",
-        # Empty brace not a simple identifier
-        "Use {} carefully",
-        # Positional placeholder not a simple identifier
-        "Value: {0}",
-        # Whitespace inside braces not a simple identifier
-        "{ not a token }",
-    ],
-)
-def test_clean_templates(text: str) -> None:
-    assert validate_prompt_template(text) == []
-
-
-# ---------------------------------------------------------------------------
-# Invalid templates — errors expected
-# ---------------------------------------------------------------------------
-
-
-def test_unknown_simple_token_single() -> None:
-    errors = validate_prompt_template("Hello {name}!")
-    assert len(errors) == 1
-    assert errors[0].pattern == "{name}"
-    assert "Unknown template token" in errors[0].reason
-    # Error message must list the supported tokens
-    for token in PROMPT_SAFE_TOKENS:
-        assert token in errors[0].reason
-
-
-def test_unknown_simple_token_multiple_distinct() -> None:
-    errors = validate_prompt_template("{foo} and {bar} are unknown")
-    patterns = {e.pattern for e in errors}
-    assert patterns == {"{foo}", "{bar}"}
-
-
-def test_unknown_simple_token_repeated_deduplicated() -> None:
-    errors = validate_prompt_template("{foo} again {foo}")
-    assert len(errors) == 1
-    assert errors[0].pattern == "{foo}"
-
-
-def test_mix_valid_and_invalid_tokens() -> None:
-    errors = validate_prompt_template("Today is {today} and {bad_token} here.")
-    assert len(errors) == 1
-    assert errors[0].pattern == "{bad_token}"
-
-
-def test_all_valid_tokens_produce_no_errors() -> None:
-    text = " ".join(f"{{{k}}}" for k in PROMPT_SAFE_TOKENS)
-    assert validate_prompt_template(text) == []
-
-
-# ---------------------------------------------------------------------------
-# Non-simple brace patterns are NOT flagged (renderer preserves them safely)
-# ---------------------------------------------------------------------------
-
-
-def test_dotted_notation_not_flagged() -> None:
-    assert validate_prompt_template("{object.attr}") == []
-
-
-def test_empty_braces_not_flagged() -> None:
-    assert validate_prompt_template("{}") == []
-
-
-def test_positional_placeholder_not_flagged() -> None:
-    assert validate_prompt_template("{0}") == []
-
-
-def test_whitespace_brace_not_flagged() -> None:
-    assert validate_prompt_template("{ spaces }") == []
-
-
-def test_code_block_not_flagged() -> None:
-    prompt = (
-        "You help users write Excel scripts. Example:\n"
-        "function main(workbook: ExcelScript.Workbook) {\n"
-        "    workbook.getActiveWorksheet().getCell(0, 0).setValue('Hello');\n"
-        "}"
-    )
-    assert validate_prompt_template(prompt) == []
-
-
-# ---------------------------------------------------------------------------
-# Edge cases
-# ---------------------------------------------------------------------------
-
-
-def test_empty_string_is_valid() -> None:
-    assert validate_prompt_template("") == []
-
-
-def test_no_braces_is_valid() -> None:
-    assert validate_prompt_template("Plain text without any braces.") == []
-
-
-def test_token_adjacent_to_punctuation() -> None:
-    errors = validate_prompt_template("Hi, {unknown}!")
-    assert len(errors) == 1
-    assert errors[0].pattern == "{unknown}"
-
-
-def test_known_token_at_start_and_end() -> None:
-    assert validate_prompt_template("{today} is a great day, {user_id}.") == []