nighthawk-python 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

nighthawk/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from . import oversight, resilience
 from .configuration import (
     StepContextLimits,
     StepExecutorConfiguration,
@@ -15,15 +16,26 @@ from .errors import (
 )
 from .json_renderer import JsonableValue, to_jsonable_value
 from .natural.decorator import natural_function
-from .runtime.scoping import ExecutionContext, UsageMeter, get_current_usage_meter, get_execution_context, get_step_executor, run, scope
+from .runtime.scoping import (
+    ExecutionRef,
+    UsageMeter,
+    get_current_usage_meter,
+    get_execution_ref,
+    get_implicit_references,
+    get_step_executor,
+    get_system_prompt_suffix_fragments,
+    get_user_prompt_suffix_fragments,
+    run,
+    scope,
+)
 from .runtime.step_context import StepContext, get_current_step_context
 from .runtime.step_executor import AgentStepExecutor, StepExecutor
 from .tools.registry import tool
 
 __all__ = [
     "AgentStepExecutor",
-    "ExecutionContext",
     "ExecutionError",
+    "ExecutionRef",
     "JsonableValue",
     "NaturalParseError",
     "NighthawkError",
@@ -38,9 +50,14 @@ __all__ = [
     "UsageMeter",
     "get_current_step_context",
     "get_current_usage_meter",
-    "get_execution_context",
+    "get_execution_ref",
+    "get_implicit_references",
     "get_step_executor",
+    "get_system_prompt_suffix_fragments",
+    "get_user_prompt_suffix_fragments",
+    "oversight",
     "natural_function",
+    "resilience",
     "run",
     "scope",
     "to_jsonable_value",

nighthawk/backends/_text_fallback.py

@@ -0,0 +1,141 @@
+"""Backend-private text-fallback formatting for multimodal content.
+
+Used by both the text-projected coding-agent backends (``text_projection``)
+and the MCP tool-return transport (``mcp_boundary``) to emit a consistent
+``<image>``/``<file>`` placeholder line followed by descriptive metadata when
+multimodal content cannot be carried natively by the transport.
+"""
+
+from __future__ import annotations
+
+from pydantic_ai.messages import (
+    AudioUrl,
+    BinaryContent,
+    DocumentUrl,
+    FileUrl,
+    ImageUrl,
+    UploadedFile,
+    VideoUrl,
+)
+
+
+def is_image_content(*, content: object) -> bool:
+    """Return True when *content* represents image media."""
+    if isinstance(content, ImageUrl):
+        return True
+    if isinstance(content, BinaryContent):
+        return content.is_image
+    if isinstance(content, UploadedFile):
+        media_type = content.media_type
+        return isinstance(media_type, str) and media_type.startswith("image/")
+    return False
+
+
+def _safe_file_url_media_type(*, content: FileUrl) -> str | None:
+    """Return ``content.media_type`` for a FileUrl, or ``None`` when unresolvable.
+
+    ``FileUrl.media_type`` is a pydantic-ai property that may raise
+    ``ValueError`` when the MIME type cannot be inferred from the URL and no
+    explicit ``media_type`` was supplied (for example ``VideoUrl`` pointing at
+    a YouTube-like URL with no extension).
+    """
+    try:
+        return content.media_type
+    except ValueError:
+        return None
+
+
+def format_file_url_as_text_lines(*, content: FileUrl) -> list[str]:
+    """Format ``FileUrl`` metadata lines for transports that need a text fallback.
+
+    Returns only the descriptive metadata lines (the ``"... URL: <url>"`` line
+    plus an optional ``"Media type: ..."`` line). The ``<image>`` / ``<file>``
+    placeholder is emitted by :func:`format_file_url_with_placeholder`; this
+    helper is exported separately for tests and for callers that already know
+    which placeholder to use.
+    """
+    if isinstance(content, ImageUrl):
+        label = "Image"
+        include_media_type = False
+    elif isinstance(content, AudioUrl):
+        label = "Audio"
+        include_media_type = True
+    elif isinstance(content, DocumentUrl):
+        label = "Document"
+        include_media_type = True
+    elif isinstance(content, VideoUrl):
+        label = "Video"
+        include_media_type = True
+    else:
+        label = "File"
+        include_media_type = True
+
+    rendered_line_list: list[str] = [f"{label} URL: {content.url}"]
+    if include_media_type:
+        media_type = _safe_file_url_media_type(content=content)
+        if media_type is not None:
+            rendered_line_list.append(f"Media type: {media_type}")
+    return rendered_line_list
+
+
+def format_unresolvable_content_text(
+    *,
+    content: UploadedFile | BinaryContent,
+    transport_label: str,
+) -> str:
+    """Build the fallback metadata text for content the transport cannot resolve.
+
+    Used only on the tool-return path. Spec §8.3 requires the rest of a
+    successful tool-return payload to be preserved and only the unresolvable
+    item replaced with explanatory text. Coding-agent user-prompt admission
+    rejects ``UploadedFile`` outright at the backend boundary instead (see
+    ``backends/base.py``), so this helper is not reused there.
+
+    ``BinaryContent`` reaches this helper only on transports that cannot carry
+    embedded bytes natively (today: MCP, for non-image/non-audio blobs).
+    Text-projected backends stage the bytes to a local file rather than fall
+    back to this metadata text.
+    """
+    if isinstance(content, UploadedFile):
+        return f"UploadedFile: provider={content.provider_name}, file_id={content.file_id} (not resolvable by {transport_label})"
+    return f"BinaryContent: identifier={content.identifier}, media_type={content.media_type} (embedded by this tool; not resolvable by {transport_label})"
+
+
+def format_file_url_with_placeholder(*, content: FileUrl) -> list[str]:
+    """Format ``FileUrl`` text-fallback lines including the ``<image>``/``<file>`` placeholder."""
+    placeholder = "<image>" if isinstance(content, ImageUrl) else "<file>"
+    return [placeholder, *format_file_url_as_text_lines(content=content)]
+
+
+def format_uploaded_file_with_placeholder(
+    *,
+    content: UploadedFile,
+    transport_label: str,
+) -> list[str]:
+    """Format ``UploadedFile`` fallback lines including placeholder.
+
+    Used by text-projected backends (coding-agent backends) that cannot resolve
+    provider-owned file references but still want to surface the failure as
+    inline content. The MCP transport intentionally bypasses this helper and
+    emits only the bare fallback text without a placeholder.
+    """
+    placeholder = "<image>" if is_image_content(content=content) else "<file>"
+    metadata_line_list = [format_unresolvable_content_text(content=content, transport_label=transport_label)]
+    if content.media_type is not None:
+        metadata_line_list.append(f"Media type: {content.media_type}")
+    return [placeholder, *metadata_line_list]
+
+
+def format_unresolvable_binary_content_with_placeholder(
+    *,
+    content: BinaryContent,
+    transport_label: str,
+) -> list[str]:
+    """Format unresolvable ``BinaryContent`` fallback lines including placeholder.
+
+    Used on transports that cannot carry embedded bytes natively (today: MCP,
+    for non-image/non-audio blobs). Text-projected backends stage the bytes to
+    a local file instead and do not use this helper.
+    """
+    placeholder = "<image>" if is_image_content(content=content) else "<file>"
+    return [placeholder, format_unresolvable_content_text(content=content, transport_label=transport_label)]

nighthawk/backends/base.py

@@ -1,15 +1,61 @@
 from __future__ import annotations
 
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Self
+from typing import TYPE_CHECKING, Any, Self
 
 from pydantic import BaseModel, ConfigDict, field_validator
 from pydantic_ai.exceptions import UnexpectedModelBehavior, UserError
-from pydantic_ai.messages import ModelMessage, ModelRequest, RetryPromptPart, SystemPromptPart, ToolReturnPart, UserPromptPart
+from pydantic_ai.messages import (
+    CachePoint,
+    ModelMessage,
+    ModelRequest,
+    RetryPromptPart,
+    SystemPromptPart,
+    TextContent,
+    ToolReturnPart,
+    UploadedFile,
+    UserContent,
+    UserPromptPart,
+    is_multi_modal_content,
+)
 from pydantic_ai.models import Model, ModelRequestParameters
 from pydantic_ai.settings import ModelSettings
 
-from .tool_bridge import ToolHandler, prepare_allowed_tools
+from ..configuration import TEXT_PROJECTED_TOOL_RESULT_PREVIEW_SYSTEM_PROMPT_FRAGMENT
+from ..runtime.prompt import resolve_step_system_prompt_template_text
+from .tool_bridge import ToolHandler, prepare_allowed_tools, resolve_current_tool_result_rendering_policy
+
+if TYPE_CHECKING:
+    from .text_projection import TextProjectedRequest
+
+type RequestPromptPart = tuple[UserContent, ...] | ToolReturnPart
+type RequestPromptPartList = list[RequestPromptPart]
+
+
+def _validate_coding_agent_user_prompt_content_item(*, item: UserContent, backend_label: str) -> None:
+    """Enforce the coding-agent-backend user-prompt admission policy.
+
+    This layers two checks:
+
+    1. Structural check (policy-free): reject anything outside the Pydantic AI
+       ``UserContent`` union (``str | TextContent | CachePoint | <multimodal>``).
+    2. Admission policy (coding-agent-specific): reject ``UploadedFile`` even
+       though it is a legal ``UserContent`` member, because coding-agent
+       backends cannot resolve provider-owned file references.
+
+    Only backends subclassing :class:`BackendModelBase` (the coding-agent
+    backends) route through this helper; provider-backed executors send
+    ``UserContent`` natively and bypass this path.
+    """
+    if isinstance(item, UploadedFile):
+        raise UserError(
+            f"{backend_label} does not support UploadedFile user prompt content; provider-owned uploaded files cannot be resolved by this backend"
+        )
+    if isinstance(item, str | TextContent | CachePoint) or is_multi_modal_content(item):
+        return
+    raise UserError(f"{backend_label} does not support user prompt content type {type(item).__name__}")
 
 
 def _find_most_recent_model_request(messages: list[ModelMessage]) -> ModelRequest:
@@ -27,20 +73,62 @@ def _collect_system_prompt_text(model_request: ModelRequest) -> str:
     return "\n\n".join(parts)
 
 
-def _collect_user_prompt_text(model_request: ModelRequest, *, backend_label: str) -> str:
-    parts: list[str] = []
+def _resolve_current_tool_result_max_tokens() -> int:
+    return resolve_current_tool_result_rendering_policy().tool_result_max_tokens
+
+
+def append_text_projected_tool_result_preview_prompt(*, system_prompt_text: str) -> str:
+    """Append the text-projected tool-result preview warning to a system prompt.
+
+    Backends should call this only after confirming that at least one Nighthawk
+    tool will actually be exposed to the model. If no tool is exposed, the
+    preview-loss caveat is irrelevant and adds prompt noise.
+    """
+    fragment = resolve_step_system_prompt_template_text(
+        template_text=TEXT_PROJECTED_TOOL_RESULT_PREVIEW_SYSTEM_PROMPT_FRAGMENT,
+        tool_result_max_tokens=_resolve_current_tool_result_max_tokens(),
+    )
+    if not system_prompt_text:
+        return fragment
+    return "\n".join([system_prompt_text, fragment])
+
+
+@dataclass(frozen=True)
+class PreparedRequestParts:
+    system_prompt_text: str
+    request_prompt_part_list: RequestPromptPartList
+
+
+@dataclass(frozen=True)
+class PreparedTextProjectedRequest:
+    system_prompt_text: str
+    user_prompt_text: str
+    projected_request: TextProjectedRequest
+
+
+def _normalize_user_prompt_content(content: str | Sequence[UserContent], *, backend_label: str) -> tuple[UserContent, ...]:
+    if isinstance(content, str):
+        return (content,)
+
+    normalized_content_list: list[UserContent] = []
+    for item in content:
+        _validate_coding_agent_user_prompt_content_item(item=item, backend_label=backend_label)
+        normalized_content_list.append(item)
+
+    return tuple(normalized_content_list)
+
+
+def _collect_request_prompt_part_list(model_request: ModelRequest, *, backend_label: str) -> RequestPromptPartList:
+    request_prompt_part_list: RequestPromptPartList = []
     for part in model_request.parts:
         if isinstance(part, UserPromptPart):
-            if isinstance(part.content, str):
-                parts.append(part.content)
-            else:
-                raise UserError(f"{backend_label} does not support non-text user prompts")
+            request_prompt_part_list.append(_normalize_user_prompt_content(part.content, backend_label=backend_label))
         elif isinstance(part, RetryPromptPart):
-            parts.append(part.model_response())
+            request_prompt_part_list.append((part.model_response(),))
         elif isinstance(part, ToolReturnPart):
-            raise UserError(f"{backend_label} does not support tool-return parts")
+            request_prompt_part_list.append(part)
 
-    return "\n\n".join(p for p in parts if p)
+    return request_prompt_part_list
 
 
 class BackendModelBase(Model):
@@ -63,7 +151,7 @@ class BackendModelBase(Model):
         *,
         messages: list[ModelMessage],
         model_request_parameters: ModelRequestParameters,
-    ) -> tuple[ModelRequest, str, str]:
+    ) -> PreparedRequestParts:
         if model_request_parameters.builtin_tools:
             raise UserError(f"{self.backend_label} does not support builtin tools")
 
@@ -78,11 +166,42 @@ class BackendModelBase(Model):
         if instructions:
             system_prompt_text = "\n\n".join([system_prompt_text, instructions]) if system_prompt_text else instructions
 
-        user_prompt_text = _collect_user_prompt_text(model_request, backend_label=self.backend_label)
+        request_prompt_part_list = _collect_request_prompt_part_list(model_request, backend_label=self.backend_label)
+        return PreparedRequestParts(
+            system_prompt_text=system_prompt_text,
+            request_prompt_part_list=request_prompt_part_list,
+        )
+
+    def _prepare_text_projected_request(
+        self,
+        *,
+        messages: list[ModelMessage],
+        model_request_parameters: ModelRequestParameters,
+        staging_root_directory: Path,
+        empty_prompt_exception_factory: Callable[[str], Exception],
+    ) -> PreparedTextProjectedRequest:
+        from .text_projection import project_request_prompt_part_list_to_text
+
+        prepared_request_parts = self._prepare_common_request_parts(
+            messages=messages,
+            model_request_parameters=model_request_parameters,
+        )
+        system_prompt_text = prepared_request_parts.system_prompt_text
+
+        projected_request = project_request_prompt_part_list_to_text(
+            prepared_request_parts.request_prompt_part_list,
+            staging_root_directory=staging_root_directory,
+        )
+        user_prompt_text = projected_request.prompt_text
         if user_prompt_text.strip() == "":
-            raise UserError(f"{self.backend_label} requires a non-empty user prompt")
+            projected_request.cleanup()
+            raise empty_prompt_exception_factory(f"{self.backend_label} requires a non-empty user prompt")
 
-        return model_request, system_prompt_text, user_prompt_text
+        return PreparedTextProjectedRequest(
+            system_prompt_text=system_prompt_text,
+            user_prompt_text=user_prompt_text,
+            projected_request=projected_request,
+        )
 
     async def _prepare_allowed_tools(
         self,

nighthawk/backends/claude_code_cli.py

@@ -17,9 +17,10 @@ from pydantic_ai.settings import ModelSettings
 from pydantic_ai.usage import RequestUsage
 
 from ..tools.registry import get_visible_tools
-from .base import BackendModelBase
+from .base import BackendModelBase, append_text_projected_tool_result_preview_prompt
 from .claude_code_settings import ClaudeCodeModelSettings
 from .mcp_server import mcp_server_if_needed
+from .text_projection import TextProjectedRequest, resolve_text_projection_staging_root_directory
 
 
 class ClaudeCodeCliModelSettings(ClaudeCodeModelSettings):
@@ -157,16 +158,24 @@ class ClaudeCodeCliModel(BackendModelBase):
     ) -> ModelResponse:
         system_prompt_file: IO[str] | None = None
         mcp_configuration_file: IO[str] | None = None
+        projected_request: TextProjectedRequest | None = None
 
         try:
             model_settings, model_request_parameters = self.prepare_request(model_settings, model_request_parameters)
+            claude_code_cli_model_settings = ClaudeCodeCliModelSettings.from_model_settings(model_settings)
+            staging_root_directory = resolve_text_projection_staging_root_directory(
+                working_directory=claude_code_cli_model_settings.working_directory,
+            )
 
-            _, system_prompt_text, user_prompt_text = self._prepare_common_request_parts(
+            prepared_projected_request = self._prepare_text_projected_request(
                 messages=messages,
                 model_request_parameters=model_request_parameters,
+                staging_root_directory=staging_root_directory,
+                empty_prompt_exception_factory=UserError,
             )
-
-            claude_code_cli_model_settings = ClaudeCodeCliModelSettings.from_model_settings(model_settings)
+            projected_request = prepared_projected_request.projected_request
+            system_prompt_text = prepared_projected_request.system_prompt_text
+            user_prompt_text = prepared_projected_request.user_prompt_text
 
             tool_name_to_tool_definition, tool_name_to_handler, allowed_tool_names = await self._prepare_allowed_tools(
                 model_request_parameters=model_request_parameters,
@@ -175,6 +184,7 @@ class ClaudeCodeCliModel(BackendModelBase):
             )
 
             if allowed_tool_names:
+                system_prompt_text = append_text_projected_tool_result_preview_prompt(system_prompt_text=system_prompt_text)
                 system_prompt_text = "\n".join(
                     [
                         system_prompt_text,
@@ -301,3 +311,5 @@ class ClaudeCodeCliModel(BackendModelBase):
             if mcp_configuration_file is not None:
                 with contextlib.suppress(Exception):
                     mcp_configuration_file.close()
+            if projected_request is not None:
+                projected_request.cleanup()