nighthawk-python 0.9.0__py3-none-any.whl → 0.10.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,15 @@ 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_step_executor, 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 +39,11 @@ __all__ = [
     "UsageMeter",
     "get_current_step_context",
     "get_current_usage_meter",
-    "get_execution_context",
+    "get_execution_ref",
     "get_step_executor",
+    "oversight",
     "natural_function",
+    "resilience",
     "run",
     "scope",
     "to_jsonable_value",

nighthawk/backends/mcp_server.py

@@ -23,6 +23,7 @@ from pydantic_ai import RunContext
 from pydantic_ai.exceptions import UnexpectedModelBehavior
 from pydantic_ai.tools import ToolDefinition
 
+from ..errors import NighthawkError
 from ..runtime.step_context import (
     DEFAULT_TOOL_RESULT_RENDERING_POLICY,
     StepContext,
@@ -203,7 +204,7 @@ async def mcp_server_if_needed(
     parent_otel_context = otel_context.get_current()
     parent_run_context = get_current_run_context()
     if parent_run_context is None:
-        raise RuntimeError("Codex MCP tool server requires an active RunContext")
+        raise NighthawkError("Codex MCP tool server requires an active RunContext")
     typed_parent_run_context = cast(RunContext[StepContext], parent_run_context)
     tool_result_rendering_policy = typed_parent_run_context.deps.tool_result_rendering_policy
     if tool_result_rendering_policy is None:

nighthawk/backends/tool_bridge.py

@@ -20,13 +20,10 @@ from pydantic_ai.messages import RetryPromptPart
 from pydantic_ai.models import ModelRequestParameters
 from pydantic_ai.toolsets.function import FunctionToolset
 
+from ..errors import NighthawkError
 from ..runtime.step_context import DEFAULT_TOOL_RESULT_RENDERING_POLICY, StepContext, ToolResultRenderingPolicy
 from ..runtime.tool_calls import generate_tool_call_id, run_tool_instrumented
-from ..tools.contracts import (
-    ToolBoundaryError,
-    ToolResult,
-    render_tool_result_json_text,
-)
+from ..tools.contracts import ToolBoundaryError, render_tool_result_json_text
 from ..tools.execution import ToolResultWrapperToolset
 
 type ToolHandler = Callable[[dict[str, Any]], Awaitable[str]]
@@ -44,7 +41,7 @@ def get_current_run_context_required() -> RunContext[StepContext]:
 
     run_context = get_current_run_context()
     if run_context is None:
-        raise RuntimeError("Nighthawk tool boundaries require an active RunContext")
+        raise NighthawkError("Nighthawk tool boundaries require an active RunContext")
     return cast(RunContext[StepContext], run_context)
 
 
@@ -71,6 +68,7 @@ async def execute_tool_call(
     *,
     tool_name: str,
     tool: Any,
+    toolset: ToolResultWrapperToolset,
     arguments: dict[str, Any],
     run_context: RunContext[StepContext],
     tool_call_id: str,
@@ -102,7 +100,7 @@ async def execute_tool_call(
             ).model_response()
 
         try:
-            tool_result = await tool.toolset.call_tool(tool_name, validated_arguments, run_context, tool)
+            tool_result = await toolset.call_tool(tool_name, validated_arguments, run_context, tool)
         except (ModelRetry, CallDeferred, ApprovalRequired):
             raise
         except ToolBoundaryError as exception:
@@ -121,6 +119,9 @@ async def execute_tool_call(
                 encoding=encoding,
                 style=rendering_policy.json_renderer_style,
             )
+        except NighthawkError:
+            # Preserve host-invariant failures as Python exceptions; these are not LLM-recoverable tool-call errors and must propagate to the host.
+            raise
         except Exception as exception:
             return render_tool_result_json_text(
                 value=None,
@@ -134,10 +135,10 @@ async def execute_tool_call(
                 style=rendering_policy.json_renderer_style,
             )
 
-    if isinstance(tool_result, ToolResult):
+    if isinstance(tool_result, dict) and set(tool_result.keys()) == {"value", "error"}:
         return render_tool_result_json_text(
-            value=tool_result.value,
-            error=None,
+            value=tool_result["value"],
+            error=tool_result["error"],
             max_tokens=rendering_policy.tool_result_max_tokens,
             encoding=encoding,
             style=rendering_policy.json_renderer_style,
@@ -193,6 +194,7 @@ async def build_tool_name_to_handler(
                 return await execute_tool_call(
                     tool_name=tool_name,
                     tool=tool,
+                    toolset=toolset,
                     arguments=arguments,
                     run_context=tool_run_context,
                     tool_call_id=tool_call_id,

nighthawk/oversight.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from opentelemetry.trace import get_current_span
+from pydantic import BaseModel
+
+from .errors import NighthawkError
+from .runtime.scoping import ExecutionRef
+from .runtime.step_contract import StepKind, StepOutcome
+
+
+def _snapshot_value(value: object) -> object:
+    if isinstance(value, BaseModel):
+        return value.model_copy(deep=True)
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _snapshot_value(item) for key, item in value.items()})
+    if isinstance(value, tuple):
+        return tuple(_snapshot_value(item) for item in value)
+    if isinstance(value, list):
+        return tuple(_snapshot_value(item) for item in value)
+    if isinstance(value, set):
+        return frozenset(_snapshot_value(item) for item in value)
+    if isinstance(value, frozenset):
+        return frozenset(_snapshot_value(item) for item in value)
+    return value
+
+
+def _snapshot_mapping(name_to_value: Mapping[str, object]) -> Mapping[str, object]:
+    return MappingProxyType({name: _snapshot_value(value) for name, value in name_to_value.items()})
+
+
+def _snapshot_optional_step_outcome(step_outcome: StepOutcome | None) -> StepOutcome | None:
+    if step_outcome is None:
+        return None
+    return _snapshot_value(step_outcome)  # type: ignore[return-value]
+
+
+class OversightRejectedError(NighthawkError):
+    """Raised when oversight rejects a tool call or step commit."""
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    execution_ref: ExecutionRef
+    tool_name: str
+    argument_name_to_value: Mapping[str, object]
+    processed_natural_program: str
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "argument_name_to_value",
+            _snapshot_mapping(self.argument_name_to_value),
+        )
+
+
+@dataclass(frozen=True)
+class StepCommitProposal:
+    execution_ref: ExecutionRef
+    processed_natural_program: str
+    input_binding_name_to_value: Mapping[str, object]
+    proposed_step_outcome: StepOutcome
+    proposed_binding_name_to_value: Mapping[str, object]
+    allowed_step_kinds: tuple[StepKind, ...]
+    output_binding_name_set: frozenset[str]
+    binding_name_to_type: Mapping[str, object]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "input_binding_name_to_value",
+            _snapshot_mapping(self.input_binding_name_to_value),
+        )
+        object.__setattr__(
+            self,
+            "proposed_step_outcome",
+            _snapshot_value(self.proposed_step_outcome),
+        )
+        object.__setattr__(
+            self,
+            "proposed_binding_name_to_value",
+            _snapshot_mapping(self.proposed_binding_name_to_value),
+        )
+        object.__setattr__(
+            self,
+            "output_binding_name_set",
+            frozenset(self.output_binding_name_set),
+        )
+        object.__setattr__(
+            self,
+            "binding_name_to_type",
+            _snapshot_mapping(self.binding_name_to_type),
+        )
+
+
+@dataclass(frozen=True)
+class Accept:
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class Reject:
+    reason: str
+
+
+@dataclass(frozen=True)
+class Rewrite:
+    rewritten_step_outcome: StepOutcome | None = None
+    rewritten_binding_name_to_value: Mapping[str, object] | None = None
+    reason: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "rewritten_step_outcome",
+            _snapshot_optional_step_outcome(self.rewritten_step_outcome),
+        )
+        if self.rewritten_binding_name_to_value is not None:
+            object.__setattr__(
+                self,
+                "rewritten_binding_name_to_value",
+                _snapshot_mapping(self.rewritten_binding_name_to_value),
+            )
+        if self.rewritten_step_outcome is None and self.rewritten_binding_name_to_value is None:
+            raise ValueError("Rewrite must change rewritten_step_outcome or rewritten_binding_name_to_value")
+
+
+type ToolCallDecision = Accept | Reject
+type StepCommitDecision = Accept | Reject | Rewrite
+
+
+@dataclass(frozen=True)
+class Oversight:
+    inspect_tool_call: Callable[[ToolCall], ToolCallDecision] | None = None
+    inspect_step_commit: Callable[[StepCommitProposal], StepCommitDecision] | None = None
+
+
+def record_oversight_decision(
+    *,
+    subject: str,
+    verdict: str,
+    execution_ref: ExecutionRef,
+    tool_name: str | None = None,
+    reason: str | None = None,
+) -> None:
+    current_span = get_current_span()
+    if not current_span.is_recording():
+        return
+    if execution_ref.step_id is None:
+        raise NighthawkError("Oversight decision events require ExecutionRef.step_id")
+
+    attributes: dict[str, str] = {
+        "run.id": execution_ref.run_id,
+        "scope.id": execution_ref.scope_id,
+        "step.id": execution_ref.step_id,
+        "nighthawk.oversight.subject": subject,
+        "nighthawk.oversight.verdict": verdict,
+    }
+    if tool_name:
+        attributes["tool.name"] = tool_name
+    if reason:
+        attributes["nighthawk.oversight.reason"] = reason
+
+    current_span.add_event("nighthawk.oversight.decision", attributes)
+
+
+__all__ = [
+    "Accept",
+    "Oversight",
+    "OversightRejectedError",
+    "Reject",
+    "Rewrite",
+    "StepCommitDecision",
+    "StepCommitProposal",
+    "ToolCall",
+    "ToolCallDecision",
+]

nighthawk/resilience/__init__.py

@@ -8,9 +8,8 @@ Import directly from this module::
 
     from nighthawk.resilience import retrying, fallback, vote, timeout, budget, circuit_breaker
 
-These primitives are **not** re-exported from the top-level ``nighthawk``
-namespace.  See [Patterns: Resilience patterns](https://kurusugawa-computer.github.io/nighthawk-python/patterns/#resilience-patterns)
-for usage patterns and composition examples.
+The ``nighthawk.resilience`` module is available as ``nh.resilience`` after ``import nighthawk as nh``. Individual resilience primitives are **not** re-exported from the top-level ``nighthawk`` namespace.
+See [Patterns: Resilience patterns](https://kurusugawa-computer.github.io/nighthawk-python/patterns/#resilience-patterns) for usage patterns and composition examples.
 """
 
 from __future__ import annotations

nighthawk/resilience/_vote.py

@@ -53,12 +53,9 @@ def vote(
 ):
     """Create a majority voting transformer.
 
-    Calls the wrapped function *count* times and aggregates results
-    using the *decide* function.
+    Calls the wrapped function *count* times and aggregates results using the *decide* function.
 
-    For async functions, all calls execute concurrently via
-    :func:`asyncio.gather`. For sync functions, calls execute
-    sequentially.
+    For async functions, all calls execute concurrently via :func:`asyncio.gather`. For sync functions, calls execute sequentially.
 
     Args:
         count: Number of times to call the function.
@@ -80,6 +77,10 @@ def vote(
         raise ValueError("vote count must be at least 1")
 
     effective_min_success = min_success if min_success is not None else math.ceil(count / 2)
+    if effective_min_success < 1:
+        raise ValueError("vote min_success must be at least 1")
+    if effective_min_success > count:
+        raise ValueError("vote min_success must be less than or equal to count")
 
     def decorator[**P, R](function: Callable[P, R]) -> Callable[P, R]:
         if inspect.iscoroutinefunction(function):

nighthawk/runtime/prompt.py

@@ -18,7 +18,7 @@ from .scoping import (
     RUN_ID,
     SCOPE_ID,
     STEP_ID,
-    get_execution_context,
+    get_execution_ref,
     get_user_prompt_suffix_fragments,
 )
 from .step_context import _MISSING, StepContext, resolve_name_in_step_context
@@ -469,9 +469,9 @@ def _render_reference_and_value_list_section(
                 "nighthawk.prompt_context.max_tokens": section_max_tokens,
             }
             try:
-                execution_context = get_execution_context()
-                log_attributes[RUN_ID] = execution_context.run_id
-                log_attributes[SCOPE_ID] = execution_context.scope_id
+                execution_ref = get_execution_ref()
+                log_attributes[RUN_ID] = execution_ref.run_id
+                log_attributes[SCOPE_ID] = execution_ref.scope_id
             except Exception:
                 pass
             logging.getLogger("nighthawk").info("prompt_context_truncated %s", log_attributes)