nighthawk-python 0.12.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

nighthawk/__init__.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from . import oversight, resilience
+from .composition import UNSET, Extend, Merge, UnsetType
 from .configuration import (
     StepContextLimits,
     StepExecutorConfiguration,
@@ -8,31 +9,41 @@ from .configuration import (
 )
 from .errors import (
     ExecutionError,
+    NameConflictError,
     NaturalParseError,
     NighthawkError,
+    ToolDeclarationError,
     ToolEvaluationError,
-    ToolRegistrationError,
+    ToolNameConflictError,
     ToolValidationError,
 )
 from .json_renderer import JsonableValue, to_jsonable_value
-from .natural.decorator import natural_function
+from .natural.decorator import get_transformed_function, natural_function
 from .runtime.scoping import (
     ExecutionRef,
     UsageMeter,
-    get_current_usage_meter,
+    get_capabilities,
     get_execution_ref,
     get_implicit_references,
+    get_oversight,
     get_step_executor,
     get_system_prompt_suffix_fragments,
+    get_tools,
+    get_usage_meter,
     get_user_prompt_suffix_fragments,
     run,
     scope,
 )
-from .runtime.step_context import StepContext, get_current_step_context
+from .runtime.step_context import StepContext, get_step_context
 from .runtime.step_executor import AgentStepExecutor, StepExecutor
-from .tools.registry import tool
 
 __all__ = [
+    "UNSET",
+    "Extend",
+    "Merge",
+    "UnsetType",
+    "NameConflictError",
+    "ToolNameConflictError",
     "AgentStepExecutor",
     "ExecutionError",
     "ExecutionRef",
@@ -45,21 +56,24 @@ __all__ = [
     "StepExecutorConfiguration",
     "StepPromptTemplates",
     "ToolEvaluationError",
-    "ToolRegistrationError",
+    "ToolDeclarationError",
     "ToolValidationError",
     "UsageMeter",
-    "get_current_step_context",
-    "get_current_usage_meter",
+    "get_capabilities",
+    "get_step_context",
+    "get_usage_meter",
     "get_execution_ref",
     "get_implicit_references",
+    "get_oversight",
     "get_step_executor",
+    "get_tools",
     "get_system_prompt_suffix_fragments",
     "get_user_prompt_suffix_fragments",
     "oversight",
     "natural_function",
+    "get_transformed_function",
     "resilience",
     "run",
     "scope",
     "to_jsonable_value",
-    "tool",
 ]

nighthawk/backends/claude_code_cli.py

@@ -15,7 +15,7 @@ from pydantic_ai.profiles import ModelProfile
 from pydantic_ai.settings import ModelSettings
 from pydantic_ai.usage import RequestUsage
 
-from ..tools.registry import get_visible_tools
+from ..tools.declarations import get_visible_tools
 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

nighthawk/backends/claude_code_sdk.py

@@ -15,7 +15,7 @@ from pydantic_ai.settings import ModelSettings
 from pydantic_ai.usage import RequestUsage
 
 from ..json_renderer import to_jsonable_value
-from ..tools.registry import get_visible_tools
+from ..tools.declarations import get_visible_tools
 from .base import BackendModelBase, append_text_projected_tool_result_preview_prompt
 from .claude_code_settings import ClaudeCodeModelSettings
 from .mcp_boundary import call_tool_for_claude_code_sdk

nighthawk/backends/codex.py

@@ -16,7 +16,7 @@ from pydantic_ai.profiles.openai import OpenAIJsonSchemaTransformer
 from pydantic_ai.settings import ModelSettings
 from pydantic_ai.usage import RequestUsage
 
-from ..tools.registry import get_visible_tools
+from ..tools.declarations import get_visible_tools
 from .base import BackendModelBase, BackendModelSettings, append_text_projected_tool_result_preview_prompt
 from .mcp_server import mcp_server_if_needed
 from .text_projection import TextProjectedRequest, resolve_text_projection_staging_root_directory

nighthawk/backends/mcp_boundary.py

@@ -13,7 +13,7 @@ from pydantic_ai.messages import BinaryContent, FileUrl, TextContent, UploadedFi
 from ..runtime.step_context import (
     DEFAULT_TOOL_RESULT_RENDERING_POLICY,
     ToolResultRenderingPolicy,
-    get_current_step_context,
+    get_step_context,
     resolve_tool_result_rendering_policy,
 )
 from ..tools._tool_return_content import resolve_tool_return_segments
@@ -38,7 +38,7 @@ _logger = logging.getLogger("nighthawk")
 
 def _resolve_tool_result_rendering_policy() -> ToolResultRenderingPolicy:
     try:
-        step_context = get_current_step_context()
+        step_context = get_step_context()
     except Exception:
         return DEFAULT_TOOL_RESULT_RENDERING_POLICY
     return resolve_tool_result_rendering_policy(step_context.tool_result_rendering_policy)

nighthawk/composition.py

@@ -0,0 +1,59 @@
+"""Explicit inheritance and composition operations for execution scopes."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import ClassVar
+
+
+class UnsetType:
+    """The singleton type of :data:`UNSET`, representing an omitted argument."""
+
+    __slots__ = ()
+    _instance: ClassVar[UnsetType | None] = None
+
+    def __new__(cls) -> UnsetType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __copy__(self) -> UnsetType:
+        return self
+
+    def __deepcopy__(self, identity_to_copy: dict[int, object]) -> UnsetType:
+        return self
+
+
+UNSET = UnsetType()
+"""Inherit the enclosing scope value; also marks omitted rewrite fields."""
+
+
+@dataclass(frozen=True, init=False)
+class Extend[T]:
+    """Append a sequence to an inherited ordered collection, preserving entry identity."""
+
+    values: tuple[T, ...]
+
+    def __init__(self, values: Sequence[T]) -> None:
+        if not isinstance(values, Sequence) or isinstance(values, (str, bytes, bytearray)):
+            raise TypeError("Extend requires a sequence of entries")
+        object.__setattr__(self, "values", tuple(values))
+
+
+@dataclass(frozen=True, init=False)
+class Merge[T]:
+    """Merge named references with inherited references, checking conflicts by identity."""
+
+    name_to_value: Mapping[str, T]
+
+    def __init__(self, name_to_value: Mapping[str, T]) -> None:
+        if not isinstance(name_to_value, Mapping):
+            raise TypeError("Merge requires a name-to-value mapping")
+        if any(not isinstance(name, str) for name in name_to_value):
+            raise TypeError("Merge names must be strings")
+        object.__setattr__(self, "name_to_value", MappingProxyType(dict(name_to_value)))

nighthawk/configuration.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 from typing import Any
 
 import tiktoken
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, InstanceOf, field_serializer, field_validator
+from pydantic_ai.models import Model
+from pydantic_core import PydanticSerializationError
 
 from .json_renderer import JsonRendererStyle
 
@@ -113,7 +115,10 @@ class StepExecutorConfiguration(BaseModel):
     """Configuration for a step executor.
 
     Attributes:
-        model: Model identifier in "provider:model" format (e.g. "openai:gpt-4o").
+        model: Provider-qualified identifier or borrowed Pydantic AI Model instance.
+            Instances retain identity; the host owns client lifetime. Serialization
+            must explicitly exclude a live model field, including in nested records.
+            Configuration representations omit the model to avoid traversing credentials.
         model_settings: Provider-specific model settings. Accepts a dict or a
             backend-specific BaseModel instance (auto-converted to dict).
         prompts: Prompt templates for step execution.
@@ -128,7 +133,7 @@ class StepExecutorConfiguration(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    model: str = "openai-responses:gpt-5.4-nano"
+    model: str | InstanceOf[Model] = Field(default="openai-responses:gpt-5.6-luna", repr=False)
     model_settings: dict[str, Any] | BaseModel | None = None
 
     @field_validator("model_settings", mode="before")
@@ -147,8 +152,14 @@ class StepExecutorConfiguration(BaseModel):
 
     @field_validator("model")
     @classmethod
-    def _validate_model(cls, value: str) -> str:
-        return _validate_model_identifier(value)
+    def _validate_model(cls, value: str | Model) -> str | Model:
+        return _validate_model_identifier(value) if isinstance(value, str) else value
+
+    @field_serializer("model")
+    def _serialize_model(self, value: str | Model) -> str:
+        if not isinstance(value, str):
+            raise PydanticSerializationError("A runtime Model cannot be serialized; exclude the model field explicitly")
+        return value
 
     def resolve_token_encoding(self) -> tiktoken.Encoding:
         """Return the tiktoken encoding for this configuration.
@@ -160,7 +171,7 @@ class StepExecutorConfiguration(BaseModel):
         if self.tokenizer_encoding is not None:
             return tiktoken.get_encoding(self.tokenizer_encoding)
 
-        _, model_name = self.model.split(":", 1)
+        model_name = self.model.split(":", 1)[1] if isinstance(self.model, str) else self.model.model_name
 
         try:
             return tiktoken.encoding_for_model(model_name)

nighthawk/errors.py

@@ -21,5 +21,13 @@ class ToolValidationError(NighthawkError):
     """Raised when tool input validation fails."""
 
 
-class ToolRegistrationError(NighthawkError):
-    """Raised when tool registration fails."""
+class ToolDeclarationError(NighthawkError):
+    """Raised when a tool declaration is invalid."""
+
+
+class NameConflictError(NighthawkError):
+    """Raised when distinct declarations claim the same name."""
+
+
+class ToolNameConflictError(ToolDeclarationError, NameConflictError):
+    """Raised when tool declarations claim the same or a reserved name."""

nighthawk/natural/decorator.py

@@ -12,8 +12,7 @@ from typing import Any, cast
 from ..runtime.runner import Runner, StepEnvelope
 from ..runtime.scoping import get_step_executor
 from ..runtime.step_context import python_cell_scope, python_name_scope
-from ..tools.registry import call_scope
-from .blocks import find_natural_blocks
+from .blocks import extract_program, find_natural_blocks
 from .transform import transform_module_ast
 
 type NaturalFunctionCallable = Callable[..., Any]
@@ -239,33 +238,37 @@ def natural_function(func: NaturalFunctionCallable | None = None) -> NaturalFunc
 
     filename = inspect.getsourcefile(func) or "<nighthawk>"
 
+    # Runtime helpers referenced by the transformed body travel through the factory closure, not through
+    # module globals. The transformed function therefore shares ``func.__globals__`` with the original
+    # function: names defined in the module after decoration stay visible, and the module namespace is
+    # never polluted with helper names.
+    helper_name_to_value: dict[str, object] = {
+        "__nighthawk_runner__": _RunnerProxy(),
+        "__nh_extract_program__": extract_program,
+        "__nh_python_cell_scope__": python_cell_scope,
+    }
+    factory_name_to_value: dict[str, object] = {**name_to_value, **helper_name_to_value}
+
     factory_module = _build_transformed_factory_module(
         transformed_module=transformed_module,
         function_name=func.__name__,
-        name_to_value=name_to_value,
+        name_to_value=factory_name_to_value,
     )
     code = compile(factory_module, filename, "exec")
 
-    globals_namespace: dict[str, object] = dict(func.__globals__)
-    globals_namespace["__nighthawk_runner__"] = _RunnerProxy()
-    from .blocks import extract_program as _nh_extract_program
-
-    globals_namespace["__nh_extract_program__"] = _nh_extract_program
-    globals_namespace["__nh_python_cell_scope__"] = python_cell_scope
-
     module_namespace: dict[str, object] = {}
-    exec(code, globals_namespace, module_namespace)
+    exec(code, func.__globals__, module_namespace)
 
     factory = module_namespace.get("__nh_factory__")
     if not callable(factory):
         raise RuntimeError("Transformed factory not found after compilation")
 
-    transformed = factory(name_to_value)
+    transformed = factory(factory_name_to_value)
     if not callable(transformed):
         raise RuntimeError("Transformed function not found after factory execution")
 
     transformed_freevar_name_set = set(transformed.__code__.co_freevars)
-    captured_name_set = set(name_to_value.keys())
+    captured_name_set = set(factory_name_to_value.keys())
 
     unexpected_freevar_name_set = transformed_freevar_name_set - captured_name_set
     allowed_unexpected_freevar_name_set = {func.__name__}
@@ -274,7 +277,7 @@ def natural_function(func: NaturalFunctionCallable | None = None) -> NaturalFunc
             f"Transformed function freevars do not match captured names. freevars={transformed.__code__.co_freevars!r} captured={tuple(sorted(name_to_value.keys()))!r}"
         )
 
-    if transformed.__closure__ is None and name_to_value:
+    if transformed.__closure__ is None and transformed_freevar_name_set:
         raise RuntimeError("Transformed function closure is missing for captured names")
 
     if inspect.iscoroutinefunction(func):
@@ -282,20 +285,43 @@ def natural_function(func: NaturalFunctionCallable | None = None) -> NaturalFunc
 
         @wraps(func)
         async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
-            with call_scope():
-                if name_to_value:
-                    with python_name_scope(name_to_value):
-                        return await transformed_async(*args, **kwargs)
-                return await transformed_async(*args, **kwargs)
+            if name_to_value:
+                with python_name_scope(name_to_value):
+                    return await transformed_async(*args, **kwargs)
+            return await transformed_async(*args, **kwargs)
 
+        async_wrapper.__nighthawk_transformed_function__ = transformed  # type: ignore[attr-defined]
         return cast(NaturalFunctionCallable, async_wrapper)  # type: ignore[return-value]
 
     @wraps(func)
     def wrapper(*args: Any, **kwargs: Any) -> Any:
-        with call_scope():
-            if name_to_value:
-                with python_name_scope(name_to_value):
-                    return transformed(*args, **kwargs)
-            return transformed(*args, **kwargs)
+        if name_to_value:
+            with python_name_scope(name_to_value):
+                return transformed(*args, **kwargs)
+        return transformed(*args, **kwargs)
 
+    wrapper.__nighthawk_transformed_function__ = transformed  # type: ignore[attr-defined]
     return cast(NaturalFunctionCallable, wrapper)  # type: ignore[return-value]
+
+
+def get_transformed_function(function: Callable[..., object]) -> Callable[..., object]:
+    """Find a Natural function's compiled body through conventional wrapper chains.
+
+    Standard inspect.unwrap follows the original source. This accessor exposes the
+    transformed body for inspection; normal execution should use the decorated callable
+    to establish its runtime context. Invalid inputs and wrapper cycles raise TypeError.
+    """
+    current: object = function
+    seen_identity_set: set[int] = set()
+    while id(current) not in seen_identity_set:
+        seen_identity_set.add(id(current))
+        if isinstance(current, (staticmethod, classmethod)) or inspect.ismethod(current):
+            current = current.__func__
+            continue
+        transformed = getattr(current, "__nighthawk_transformed_function__", None)
+        if callable(transformed):
+            return transformed
+        current = getattr(current, "__wrapped__", None)
+        if current is None:
+            break
+    raise TypeError("Expected a Natural function or a conventional wrapper around one")

nighthawk/natural/transform.py

@@ -326,11 +326,9 @@ def build_runtime_call_and_assignments(
         statements.extend(ast.parse(f'if "{name}" in __nh_bindings__:\n    {name} = __nh_bindings__["{name}"]\n').body)
 
     # Add outcome extraction and dispatch.
-    statements.extend(ast.parse('__nh_step_outcome__ = __nh_envelope__["step_outcome"]').body)
+    statements.extend(ast.parse('__nh_step_outcome__ = __nh_envelope__["outcome"]').body)
 
-    outcome_source = (
-        'if __nh_step_outcome__ is not None:\n    if __nh_step_outcome__.kind == "return":\n        return __nh_envelope__["return_value"]\n'
-    )
+    outcome_source = 'if __nh_step_outcome__ is not None:\n    if __nh_step_outcome__.kind == "return":\n        return __nh_step_outcome__.value\n'
     if is_in_loop:
         outcome_source += (
             '    if __nh_step_outcome__.kind == "break":\n        break\n    if __nh_step_outcome__.kind == "continue":\n        continue\n'

nighthawk/oversight.py

@@ -5,37 +5,16 @@ from dataclasses import dataclass
 from types import MappingProxyType
 
 from opentelemetry.trace import get_current_span
-from pydantic import BaseModel
 
+from .composition import UNSET, UnsetType
 from .errors import NighthawkError
 from .runtime.scoping import ExecutionRef
-from .runtime.step_contract import StepKind, StepOutcome
+from .runtime.step_contract import StepKind
+from .runtime.step_result import Break, Continue, Pass, Raise, Return, StepResult
 
 
-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]
+def _reference_mapping(name_to_value: Mapping[str, object]) -> Mapping[str, object]:
+    return MappingProxyType(dict(name_to_value))
 
 
 class OversightRejectedError(NighthawkError):
@@ -53,17 +32,25 @@ class ToolCall:
         object.__setattr__(
             self,
             "argument_name_to_value",
-            _snapshot_mapping(self.argument_name_to_value),
+            _reference_mapping(self.argument_name_to_value),
         )
 
 
 @dataclass(frozen=True)
-class StepCommitProposal:
+class StepCommit:
+    """Validated step result presented to ``Oversight.inspect_step_commit`` before it is committed.
+
+    ``binding_name_to_value`` holds the write bindings after Pydantic validation and coercion.
+    ``outcome`` is a resolved variant. Values retain type and identity in shallow
+    read-only mapping views. Trusted hooks must not mutate these references; use
+    Rewrite for changes and copy or serialize explicitly for durable history.
+    """
+
     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]
+    outcome: StepResult
+    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]
@@ -72,17 +59,12 @@ class StepCommitProposal:
         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),
+            _reference_mapping(self.input_binding_name_to_value),
         )
         object.__setattr__(
             self,
-            "proposed_binding_name_to_value",
-            _snapshot_mapping(self.proposed_binding_name_to_value),
+            "binding_name_to_value",
+            _reference_mapping(self.binding_name_to_value),
         )
         object.__setattr__(
             self,
@@ -92,7 +74,7 @@ class StepCommitProposal:
         object.__setattr__(
             self,
             "binding_name_to_type",
-            _snapshot_mapping(self.binding_name_to_type),
+            _reference_mapping(self.binding_name_to_type),
         )
 
 
@@ -108,24 +90,29 @@ class Reject:
 
 @dataclass(frozen=True)
 class Rewrite:
-    rewritten_step_outcome: StepOutcome | None = None
-    rewritten_binding_name_to_value: Mapping[str, object] | None = None
+    """Replace supplied commit fields; UNSET inherits and explicit None is a return.
+
+    A mapping replaces all writes. A return_value patch requires an existing Return.
+    Use outcome=Return(value=...) to change another allowed outcome into a return.
+    Replacements are validated before commit without replaying return expressions.
+    """
+
+    outcome: StepResult | UnsetType = UNSET
+    binding_name_to_value: Mapping[str, object] | UnsetType = UNSET
+    return_value: object = UNSET
     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")
+        if not isinstance(self.outcome, (UnsetType, Pass, Return, Break, Continue, Raise)):
+            raise TypeError("Rewrite outcome must be a resolved StepResult or UNSET")
+        if self.outcome is not UNSET and self.return_value is not UNSET:
+            raise ValueError("Rewrite cannot supply both outcome and return_value")
+        if not isinstance(self.binding_name_to_value, UnsetType):
+            if not isinstance(self.binding_name_to_value, Mapping):
+                raise TypeError("Rewrite binding_name_to_value must be a mapping or UNSET")
+            object.__setattr__(self, "binding_name_to_value", _reference_mapping(self.binding_name_to_value))
+        if self.outcome is UNSET and self.binding_name_to_value is UNSET and self.return_value is UNSET:
+            raise ValueError("Rewrite must change outcome, binding_name_to_value, or return_value")
 
 
 type ToolCallDecision = Accept | Reject
@@ -135,7 +122,7 @@ 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
+    inspect_step_commit: Callable[[StepCommit], StepCommitDecision] | None = None
 
 
 def record_oversight_decision(
@@ -168,13 +155,19 @@ def record_oversight_decision(
 
 
 __all__ = [
+    "Pass",
+    "Return",
+    "Break",
+    "Continue",
+    "Raise",
+    "StepResult",
     "Accept",
     "Oversight",
     "OversightRejectedError",
     "Reject",
     "Rewrite",
+    "StepCommit",
     "StepCommitDecision",
-    "StepCommitProposal",
     "ToolCall",
     "ToolCallDecision",
 ]

nighthawk/resilience/_budget.py

@@ -11,7 +11,7 @@ from opentelemetry.trace import get_current_span
 from pydantic_ai.usage import RunUsage
 
 from ..errors import NighthawkError
-from ..runtime.scoping import get_current_usage_meter
+from ..runtime.scoping import _optional_usage_meter
 
 _logger = logging.getLogger("nighthawk.resilience")
 
@@ -43,7 +43,7 @@ class BudgetExceededError(NighthawkError):
 
 
 def _get_usage_snapshot() -> RunUsage | None:
-    usage_meter = get_current_usage_meter()
+    usage_meter = _optional_usage_meter()
     if usage_meter is None:
         return None
     return usage_meter.snapshot()