nighthawk-python 0.8.0__tar.gz → 0.9.0__tar.gz

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/.github/workflows/docs.yml

@@ -46,4 +46,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Redesigned `nh.scope()` around `mode` semantics (`"inherit"` default, `"replace"` for explicit replacement).
+- Scope prompt suffix arguments now use list-based forms: `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments`.
+
+### Removed
+- Removed `step_executor_configuration_patch` from `nh.scope()`.
+- Removed `StepExecutorConfigurationPatch` from the public API.
+
+### Fixed
+- Clarified and aligned docs/tests for scope merge vs replace behavior.
+
 ## [0.8.0]
 
 ### Added

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.8.0
+Version: 0.9.0
 Summary: A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
 Project-URL: Repository, https://github.com/kurusugawa-computer/nighthawk-python
 Project-URL: Documentation, https://kurusugawa-computer.github.io/nighthawk-python/

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/docs/api.md

@@ -14,7 +14,6 @@
         - scope
         - AgentStepExecutor
         - StepExecutorConfiguration
-        - StepExecutorConfigurationPatch
         - StepPromptTemplates
         - StepContextLimits
         - JsonableValue

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/docs/for-coding-agents.md

@@ -146,8 +146,12 @@ with nh.run(fast_executor):
         report = write_analysis_report(ticket_text, product_summary)
 ```
 
-`implicit_references` can inject global helper functions as block capabilities.
-Nested scopes still merge additively (set union by key).
+- `implicit_references` inject helper functions as block capabilities.
+- `nh.scope()` must run inside `nh.run()`; it keeps `run_id` and creates a new `scope_id`.
+- `mode` affects only `system_prompt_suffix_fragments`, `user_prompt_suffix_fragments`, and `implicit_references`.
+- `inherit`: suffix lists append; `implicit_references` merge with conflict check (same key + different object => `NighthawkError`).
+- `replace`: explicit list/mapping fully replace; `[]`/`{}` clear; `None` keeps inherited value.
+- `step_executor` / `step_executor_configuration` are resolved independently of `mode`.
 
 ## 4. The standard contract shape
 

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/docs/runtime-configuration.md

@@ -2,7 +2,7 @@
 
 > This page assumes you have completed [Executors](executors.md).
 
-This page covers how to configure execution at runtime: scoping, configuration patching, prompt suffix fragments, context limits, JSON rendering, and execution identity. These settings are independent of executor choice and apply equally to Pydantic AI providers and coding agent backends.
+This page covers how to configure execution at runtime: scoping modes, prompt suffix fragments, context limits, JSON rendering, and execution identity. These settings are independent of executor choice and apply equally to Pydantic AI providers and coding agent backends.
 
 ## Scoped overrides with `nh.scope()`
 
@@ -11,17 +11,20 @@ Use `nh.scope()` to override execution settings within an existing run. Each sco
 ```py
 with nh.run(step_executor):
 
-    # Override model for a specific section
+    # Inherit mode (default): merge/append into current scope state
     with nh.scope(
-        step_executor_configuration_patch=nh.StepExecutorConfigurationPatch(
+        step_executor_configuration=nh.StepExecutorConfiguration(
             model="openai-responses:gpt-5.4-mini",
         ),
     ) as scoped_executor:
         expensive_analysis(data)
 
-    # Append a system prompt suffix for a section
+    # Replace mode: replace only explicitly provided values
+    # None means "no change". [] / {} means "clear".
     with nh.scope(
-        system_prompt_suffix_fragment="Always respond in formal English.",
+        mode="replace",
+        system_prompt_suffix_fragments=["Always respond in formal English."],
+        implicit_references={},
     ):
         formal_summary(text)
 
@@ -29,31 +32,35 @@ with nh.run(step_executor):
     with nh.scope(step_executor=another_executor):
         specialized_step(data)
 
-    # Add implicit global references for this scope (merged across nested scopes)
+    # Add implicit global references for this scope
     with nh.scope(implicit_references={"search_repository": search_repository}):
         typed_labeling_step(ticket_text)
 ```
 
 Parameters:
 
+- `mode`: scope composition mode. Default: `"inherit"`.
 - `step_executor_configuration`: replace the entire configuration.
-- `step_executor_configuration_patch`: partially override specific fields.
 - `step_executor`: replace the step executor entirely.
-- `system_prompt_suffix_fragment`: append text to the system prompt for the scope.
-- `user_prompt_suffix_fragment`: append text to the user prompt for the scope.
-- `implicit_references`: add implicit global references for this scope as a name-to-value mapping. Nested scopes merge references additively (set union by key).
+- `system_prompt_suffix_fragments`: scope-level system suffix fragments.
+- `user_prompt_suffix_fragments`: scope-level user suffix fragments.
+- `implicit_references`: scope-level implicit global references.
 
-Use `step_executor_configuration` when you want a full configuration replacement for a scope.
-Use `step_executor_configuration_patch` for targeted changes (for example, switching only the model).
-Use `step_executor` to swap the executor implementation for that scope.
-Use `system_prompt_suffix_fragment` and `user_prompt_suffix_fragment` to append one-off scope-level prompt text.
-Use `implicit_references` when a step should always expose specific globals even without explicit `<name>` bindings.
+Mode semantics:
+
+- `mode="inherit"` (default):
+  - `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments` are appended.
+  - `implicit_references` are merged additively with conflict checks.
+- `mode="replace"`:
+  - `None` means no change.
+  - Explicit `[]` or `{}` clears inherited list/dict values.
+  - Explicit list/dict values (for example `[e1, e2]` or `{k1: v1, k2: v2}`) fully replace inherited values.
 
 The context manager yields the resolved `StepExecutor` for the scope.
 
-`StepExecutorConfiguration` also accepts `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments` (tuples of strings) as baseline suffix fragments for the whole run. Scope-level fragments are appended after configuration-level fragments.
+`StepExecutorConfiguration` also accepts `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments` (tuples of strings) as baseline suffix fragments for the whole run. In `mode="inherit"`, scope-level fragments are appended after configuration-level fragments.
 
-## Additive scoped implicit references
+## Scoped implicit references
 
 `implicit_references` can inject global helper functions as step capabilities:
 
@@ -65,8 +72,72 @@ with nh.run(step_executor):
         triage_issue(ticket_text)
 ```
 
-Nested scopes merge names additively (set union by key).
+In `mode="inherit"` (default), nested scopes merge additively with conflict checks.
+In `mode="replace"`, explicit mappings fully replace inherited mappings.
+
+```py
+with nh.run(step_executor), nh.scope(implicit_references={"parent": search_repository}):
+    with nh.scope(mode="replace", implicit_references={}):
+        triage_issue(ticket_text)
+```
+
+The inner scope above clears inherited implicit references.
+
+```py
+with nh.scope(mode="replace", implicit_references={"child": search_repository}):
+    triage_issue(ticket_text)
+```
+
+This fully replaces inherited references with the provided mapping.
+
+```py
+with nh.scope(mode="replace", implicit_references=None):
+    triage_issue(ticket_text)
+```
+
+This keeps inherited references unchanged.
+
+## Prompt suffix fragments in scopes
+
+Use list values when setting scope-level suffix fragments:
+
+```py
+with nh.run(step_executor):
+    with nh.scope(system_prompt_suffix_fragments=["Use concise answers."]):
+        summarize_ticket(ticket_text)
+```
+
+`user_prompt_suffix_fragments` follows the same rules.
+
+```py
+with nh.scope(user_prompt_suffix_fragments=["Focus on actionable output."]):
+    summarize_ticket(ticket_text)
+```
+
+In `mode="inherit"`, provided lists are appended.
+In `mode="replace"`, provided lists fully replace inherited lists.
+
+```py
+with nh.run(step_executor), nh.scope(system_prompt_suffix_fragments=["parent"]):
+    with nh.scope(mode="replace", system_prompt_suffix_fragments=["child_1", "child_2"]):
+        summarize_ticket(ticket_text)
+```
+
+Pass `[]` to clear inherited fragments.
+
+```py
+with nh.scope(mode="replace", system_prompt_suffix_fragments=[]):
+    summarize_ticket(ticket_text)
+```
+
+Pass `None` to keep inherited fragments unchanged.
+
+```py
+with nh.scope(mode="replace", system_prompt_suffix_fragments=None):
+    summarize_ticket(ticket_text)
+```
 
+The same `replace` semantics apply to `user_prompt_suffix_fragments`.
 ## Mixing executors
 
 Use `nh.scope(step_executor=...)` to switch executors within a single run. This is the standard pattern for mixing a cheap classifier with a deep autonomous step:

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/docs/specification.md

@@ -91,9 +91,6 @@ The condensed coding agent guide (`for-coding-agents.md`) is a derivative docume
     - `json_renderer_style`: [headson](https://github.com/kantord/headson) rendering style used in prompt context and tool result envelopes. Default: `"default"`. Available values: `"strict"` (valid JSON, no annotations), `"default"` (pseudo-JSON with omission markers like `…`), `"detailed"` (JS-like with inline comments such as `// N more`).
     - `system_prompt_suffix_fragments`: optional baseline system prompt suffix fragments for this executor configuration.
     - `user_prompt_suffix_fragments`: optional baseline user prompt suffix fragments for this executor configuration.
-- `StepExecutorConfigurationPatch`
-    - Partial override object for scoped configuration updates.
-    - Supports patching model, model settings, templates, limits, renderer style, tokenizer encoding, and prompt suffix fragment tuples.
 
 ### 5.3. Supporting types
 
@@ -589,13 +586,18 @@ API:
     - Uses provided `run_id` when given; otherwise generates a new `run_id` (trace root).
     - Always generates a fresh `scope_id`.
     - Can be used even when no step executor is currently set.
-- `nighthawk.scope(*, step_executor_configuration: StepExecutorConfiguration | None = None, step_executor_configuration_patch: StepExecutorConfigurationPatch | None = None, step_executor: StepExecutor | None = None, system_prompt_suffix_fragment: str | None = None, user_prompt_suffix_fragment: str | None = None) -> Iterator[StepExecutor]`
+- `nighthawk.scope(*, mode: Literal["inherit", "replace"] = "inherit", step_executor_configuration: StepExecutorConfiguration | None = None, step_executor: StepExecutor | None = None, system_prompt_suffix_fragments: Sequence[str] | None = None, user_prompt_suffix_fragments: Sequence[str] | None = None, implicit_references: Mapping[str, object] | None = None) -> Iterator[StepExecutor]`
     - Enter a nested scope within the current run.
     - Requires an existing step executor.
     - Generates a new `scope_id` (keeps the current `run_id`).
-    - Only specified fields are overridden for the duration of the `with`.
-    - `system_prompt_suffix_fragment`: optional string appended to the system prompt for the duration of the scope.
-    - `user_prompt_suffix_fragment`: optional string appended to the user prompt for the duration of the scope.
+    - `mode="inherit"` (default):
+        - Appends prompt suffix fragment lists.
+        - Merges `implicit_references` additively with conflict checks.
+    - `mode="replace"`:
+        - Replaces provided list/mapping values.
+        - `None` means no change.
+        - Explicit `[]` / `{}` clears inherited list/mapping values.
+        - Explicit list/mapping values (for example `[e1, e2]` or `{k1: v1, k2: v2}`) fully replace inherited values.
     - Yields the resolved `StepExecutor` for the scope.
 - `nighthawk.get_step_executor() -> StepExecutor`
     - Get the current step executor. Raises if unset.

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.8.0"
+version = "0.9.0"
 description = "A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks."
 readme = "README.md"
 requires-python = ">=3.13"

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/src/nighthawk/__init__.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 from .configuration import (
     StepContextLimits,
     StepExecutorConfiguration,
-    StepExecutorConfigurationPatch,
     StepPromptTemplates,
 )
 from .errors import (
@@ -32,7 +31,6 @@ __all__ = [
     "StepContextLimits",
     "StepExecutor",
     "StepExecutorConfiguration",
-    "StepExecutorConfigurationPatch",
     "StepPromptTemplates",
     "ToolEvaluationError",
     "ToolRegistrationError",

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/src/nighthawk/configuration.py

@@ -160,44 +160,3 @@ class StepExecutorConfiguration(BaseModel):
             return tiktoken.encoding_for_model(model_name)
         except Exception:
             return tiktoken.get_encoding("o200k_base")
-
-
-class StepExecutorConfigurationPatch(BaseModel):
-    """Partial override for StepExecutorConfiguration.
-
-    Non-None fields replace the corresponding fields in the target configuration.
-
-    Attributes:
-        model: Model identifier override.
-        model_settings: Model settings override. Accepts a dict or a
-            backend-specific BaseModel instance (auto-converted to dict).
-        prompts: Prompt templates override.
-        context_limits: Context limits override.
-        json_renderer_style: JSON renderer style override.
-        tokenizer_encoding: Tokenizer encoding override.
-        system_prompt_suffix_fragments: System prompt suffix fragments override.
-        user_prompt_suffix_fragments: User prompt suffix fragments override.
-    """
-
-    model_config = ConfigDict(extra="forbid", frozen=True)
-
-    model: str | None = None
-    model_settings: dict[str, Any] | BaseModel | None = None
-
-    @field_validator("model_settings", mode="before")
-    @classmethod
-    def _normalize_model_settings(cls, value: Any) -> dict[str, Any] | None:
-        if isinstance(value, BaseModel):
-            return value.model_dump()
-        return value
-
-    prompts: StepPromptTemplates | None = None
-    context_limits: StepContextLimits | None = None
-    json_renderer_style: JsonRendererStyle | None = None
-    tokenizer_encoding: str | None = None
-    system_prompt_suffix_fragments: tuple[str, ...] | None = None
-    user_prompt_suffix_fragments: tuple[str, ...] | None = None
-
-    def apply_to(self, configuration: StepExecutorConfiguration) -> StepExecutorConfiguration:
-        """Apply non-None fields to the given configuration and return a new copy."""
-        return configuration.model_copy(update=self.model_dump(exclude_none=True))

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/src/nighthawk/runtime/scoping.py

@@ -2,17 +2,17 @@ from __future__ import annotations
 
 import importlib.metadata
 import threading
-from collections.abc import Iterator, Mapping
+from collections.abc import Iterator, Mapping, Sequence
 from contextlib import contextmanager
 from contextvars import ContextVar
 from copy import copy
 from dataclasses import dataclass, replace
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 from opentelemetry.trace import Span, get_tracer_provider
 from pydantic_ai.usage import RunUsage
 
-from ..configuration import StepExecutorConfiguration, StepExecutorConfigurationPatch
+from ..configuration import StepExecutorConfiguration
 from ..errors import NighthawkError
 from ..tools.registry import tool_scope
 from ..ulid import generate_ulid
@@ -295,24 +295,28 @@ def run(
 @contextmanager
 def scope(
     *,
+    mode: Literal["inherit", "replace"] = "inherit",
     step_executor_configuration: StepExecutorConfiguration | None = None,
-    step_executor_configuration_patch: StepExecutorConfigurationPatch | None = None,
     step_executor: StepExecutor | None = None,
-    system_prompt_suffix_fragment: str | None = None,
-    user_prompt_suffix_fragment: str | None = None,
+    system_prompt_suffix_fragments: Sequence[str] | None = None,
+    user_prompt_suffix_fragments: Sequence[str] | None = None,
     implicit_references: ImplicitReferenceNameToValue | None = None,
 ) -> Iterator[StepExecutor]:
-    """Open a nested scope that can override the step executor or its configuration.
+    """Open a nested scope that can override the active execution context.
 
-    Must be called inside an active run context. Creates a new scope_id while inheriting the run_id from the parent context.
+    Must be called inside an active run context. Creates a new ``scope_id`` while inheriting the ``run_id`` from the parent context.
 
     Args:
+        mode: Scope composition mode. ``"inherit"`` appends/merges values into the current scope. ``"replace"`` fully replaces provided list/dict values.
+            In both modes, ``None`` means no change.
         step_executor_configuration: Full replacement configuration for the step executor.
-        step_executor_configuration_patch: Partial override applied on top of the current configuration.
         step_executor: Replacement step executor for this scope.
-        system_prompt_suffix_fragment: Additional text appended to the system prompt.
-        user_prompt_suffix_fragment: Additional text appended to the user prompt.
-        implicit_references: Additional implicit global references merged into this scope and inherited by nested scopes.
+        system_prompt_suffix_fragments: Additional system prompt suffix fragments.
+            In ``mode="inherit"``, fragments are appended. In ``mode="replace"``, provided fragments fully replace the current fragments.
+        user_prompt_suffix_fragments: Additional user prompt suffix fragments.
+            In ``mode="inherit"``, fragments are appended. In ``mode="replace"``, provided fragments fully replace the current fragments.
+        implicit_references: Implicit global references for this scope.
+            In ``mode="inherit"``, values are merged with conflict checks. In ``mode="replace"``, provided mappings fully replace the current mapping.
 
     Yields:
         The step executor active within this scope.
@@ -321,9 +325,9 @@ def scope(
         ```python
         with nighthawk.run(executor):
             with nighthawk.scope(
-                step_executor_configuration_patch=StepExecutorConfigurationPatch(
-                    model="openai:gpt-5.4-mini",
-                ),
+                mode="replace",
+                implicit_references={},
+                system_prompt_suffix_fragments=["Use concise answers."],
             ) as scoped_executor:
                 result = my_natural_function()
         ```
@@ -332,31 +336,13 @@ def scope(
     current_execution_context = get_execution_context()
 
     next_step_executor = current_step_executor
-
     if step_executor is not None:
         next_step_executor = step_executor
 
-    has_configuration_update = any(
-        value is not None
-        for value in (
-            step_executor_configuration,
-            step_executor_configuration_patch,
-        )
-    )
-
-    if has_configuration_update:
-        current_agent_step_executor = _resolve_agent_step_executor(next_step_executor)
-        next_configuration = current_agent_step_executor.configuration
-
-        if step_executor_configuration is not None:
-            next_configuration = step_executor_configuration
-
-        if step_executor_configuration_patch is not None:
-            next_configuration = step_executor_configuration_patch.apply_to(next_configuration)
-
+    if step_executor_configuration is not None:
         next_step_executor = _replace_step_executor_with_configuration(
             next_step_executor,
-            configuration=next_configuration,
+            configuration=step_executor_configuration,
         )
 
     next_execution_context = replace(
@@ -364,27 +350,36 @@ def scope(
         scope_id=generate_ulid(),
     )
 
-    next_system_fragments = _system_prompt_suffix_fragments_var.get()
-    next_user_fragments = _user_prompt_suffix_fragments_var.get()
+    next_system_prompt_suffix_fragments = _system_prompt_suffix_fragments_var.get()
+    next_user_prompt_suffix_fragments = _user_prompt_suffix_fragments_var.get()
     next_implicit_reference_name_to_value = _implicit_reference_name_to_value_var.get()
 
-    if system_prompt_suffix_fragment is not None:
-        next_system_fragments = (*next_system_fragments, system_prompt_suffix_fragment)
+    if system_prompt_suffix_fragments is not None:
+        if mode == "inherit":
+            next_system_prompt_suffix_fragments = (*next_system_prompt_suffix_fragments, *system_prompt_suffix_fragments)
+        else:
+            next_system_prompt_suffix_fragments = tuple(system_prompt_suffix_fragments)
 
-    if user_prompt_suffix_fragment is not None:
-        next_user_fragments = (*next_user_fragments, user_prompt_suffix_fragment)
+    if user_prompt_suffix_fragments is not None:
+        if mode == "inherit":
+            next_user_prompt_suffix_fragments = (*next_user_prompt_suffix_fragments, *user_prompt_suffix_fragments)
+        else:
+            next_user_prompt_suffix_fragments = tuple(user_prompt_suffix_fragments)
 
     if implicit_references is not None:
-        next_implicit_reference_name_to_value = _merge_implicit_reference_name_to_value_with_conflict_check(
-            next_implicit_reference_name_to_value,
-            implicit_references,
-        )
+        if mode == "inherit":
+            next_implicit_reference_name_to_value = _merge_implicit_reference_name_to_value_with_conflict_check(
+                next_implicit_reference_name_to_value,
+                implicit_references,
+            )
+        else:
+            next_implicit_reference_name_to_value = dict(implicit_references)
 
     with tool_scope():
         step_executor_token = _step_executor_var.set(next_step_executor)
         execution_context_token = _execution_context_var.set(next_execution_context)
-        system_fragments_token = _system_prompt_suffix_fragments_var.set(next_system_fragments)
-        user_fragments_token = _user_prompt_suffix_fragments_var.set(next_user_fragments)
+        system_fragments_token = _system_prompt_suffix_fragments_var.set(next_system_prompt_suffix_fragments)
+        user_fragments_token = _user_prompt_suffix_fragments_var.set(next_user_prompt_suffix_fragments)
         implicit_reference_name_to_value_token = _implicit_reference_name_to_value_var.set(next_implicit_reference_name_to_value)
         try:
             with span(

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/tests/execution/test_runtime.py

@@ -616,7 +616,7 @@ def test_natural_function_can_override_step_executor_configuration_model_within_
             """
             first_model_identifier = observed_model_identifier  # noqa: F821  # pyright: ignore[reportUndefinedVariable]
 
-            with nh.scope(step_executor_configuration_patch=nh.StepExecutorConfigurationPatch(model="openai-responses:gpt-5.4-mini")):
+            with nh.scope(step_executor_configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-mini")):
                 """natural
                 <:observed_model_identifier>
                 Record the current model identifier.
@@ -653,7 +653,7 @@ def test_natural_function_rejects_step_executor_configuration_updates_for_non_ag
 
         @nh.natural_function
         def f() -> None:
-            with nh.scope(step_executor_configuration_patch=nh.StepExecutorConfigurationPatch(model="openai-responses:gpt-5.4-mini")):
+            with nh.scope(step_executor_configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-mini")):
                 pass
 
         with pytest.raises(NighthawkError, match="AgentStepExecutor"):

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/tests/integration/test_llm_integration.py

@@ -74,7 +74,7 @@ def test_system_prompt_suffix_fragments():
         ),
     )
 
-    with nh.run(step_executor), nh.scope(system_prompt_suffix_fragment="Hello suffix"):
+    with nh.run(step_executor), nh.scope(system_prompt_suffix_fragments=["Hello suffix"]):
 
         @nh.natural_function
         def f() -> int:
@@ -97,7 +97,7 @@ def test_user_prompt_suffix_fragments():
         ),
     )
 
-    with nh.run(step_executor), nh.scope(user_prompt_suffix_fragment="Hello suffix"):
+    with nh.run(step_executor), nh.scope(user_prompt_suffix_fragments=["Hello suffix"]):
 
         @nh.natural_function
         def f() -> int:

{nighthawk_python-0.8.0 → nighthawk_python-0.9.0}/tests/public/test_public_api.py

@@ -145,7 +145,7 @@ def test_scope_implicit_references_additive_across_nested_scopes() -> None:
         assert runtime_scoping.get_implicit_reference_name_to_value() == {}
 
 
-def test_scope_implicit_references_rejects_conflicting_values() -> None:
+def test_scope_implicit_references_rejects_conflicting_values_in_inherit_mode() -> None:
     with (
         nh.run(StubExecutor()),
         nh.scope(implicit_references={"shared": object()}),
@@ -163,6 +163,110 @@ def test_scope_implicit_references_accepts_mapping() -> None:
         assert set(runtime_scoping.get_implicit_reference_name_to_value().keys()) == {"one", "two"}
 
 
+def test_scope_replace_mode_none_keeps_inherited_implicit_references() -> None:
+    parent_function = object()
+
+    with nh.run(StubExecutor()), nh.scope(implicit_references={"parent": parent_function}), nh.scope(mode="replace", implicit_references=None):
+        assert runtime_scoping.get_implicit_reference_name_to_value() == {"parent": parent_function}
+
+
+def test_scope_replace_mode_explicit_empty_mapping_clears_implicit_references() -> None:
+    parent_function = object()
+
+    with nh.run(StubExecutor()), nh.scope(implicit_references={"parent": parent_function}), nh.scope(mode="replace", implicit_references={}):
+        assert runtime_scoping.get_implicit_reference_name_to_value() == {}
+
+
+def test_scope_replace_mode_replaces_implicit_references_mapping() -> None:
+    parent_function = object()
+    replacement_function = object()
+
+    with (
+        nh.run(StubExecutor()),
+        nh.scope(implicit_references={"parent": parent_function}),
+        nh.scope(mode="replace", implicit_references={"replacement": replacement_function}),
+    ):
+        assert runtime_scoping.get_implicit_reference_name_to_value() == {"replacement": replacement_function}
+
+
+def test_scope_replace_mode_none_keeps_inherited_prompt_suffix_fragments() -> None:
+    with nh.run(StubExecutor()), nh.scope(system_prompt_suffix_fragments=["parent"]), nh.scope(mode="replace", system_prompt_suffix_fragments=None):
+        assert runtime_scoping.get_system_prompt_suffix_fragments() == ("parent",)
+
+
+def test_scope_replace_mode_explicit_empty_prompt_suffix_fragments_clears() -> None:
+    with nh.run(StubExecutor()), nh.scope(system_prompt_suffix_fragments=["parent"]), nh.scope(mode="replace", system_prompt_suffix_fragments=[]):
+        assert runtime_scoping.get_system_prompt_suffix_fragments() == ()
+
+
+def test_scope_replace_mode_replaces_prompt_suffix_fragments() -> None:
+    with (
+        nh.run(StubExecutor()),
+        nh.scope(system_prompt_suffix_fragments=["parent"]),
+        nh.scope(mode="replace", system_prompt_suffix_fragments=["child_1", "child_2"]),
+    ):
+        assert runtime_scoping.get_system_prompt_suffix_fragments() == ("child_1", "child_2")
+
+
+def test_scope_mode_defaults_to_inherit() -> None:
+    with nh.run(StubExecutor()), nh.scope(implicit_references={"parent": object()}), nh.scope(implicit_references={"child": object()}):
+        assert set(runtime_scoping.get_implicit_reference_name_to_value().keys()) == {"parent", "child"}
+
+
+def test_scope_replace_mode_replaces_step_executor_configuration() -> None:
+    class FakeAgent:
+        def run_sync(self, *args, **kwargs):  # type: ignore[no-untyped-def]
+            _ = args
+            _ = kwargs
+            raise AssertionError
+
+    first_configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano")
+    second_configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-mini")
+
+    with (
+        nh.run(nh.AgentStepExecutor.from_agent(agent=FakeAgent(), configuration=first_configuration)),
+        nh.scope(mode="replace", step_executor_configuration=second_configuration),
+    ):
+        scoped_step_executor = nh.get_step_executor()
+        assert isinstance(scoped_step_executor, AgentStepExecutor)
+        assert scoped_step_executor.configuration == second_configuration
+
+
+def test_scope_replace_mode_none_keeps_inherited_step_executor() -> None:
+    with nh.run(StubExecutor()):
+        parent_step_executor = nh.get_step_executor()
+        with nh.scope(mode="replace", step_executor=None):
+            child_step_executor = nh.get_step_executor()
+        assert child_step_executor is parent_step_executor
+
+
+def test_scope_inherit_mode_appends_prompt_suffix_fragments() -> None:
+    with (
+        nh.run(StubExecutor()),
+        nh.scope(system_prompt_suffix_fragments=["parent"]),
+        nh.scope(mode="inherit", system_prompt_suffix_fragments=["child"]),
+    ):
+        assert runtime_scoping.get_system_prompt_suffix_fragments() == ("parent", "child")
+
+
+def test_scope_inherit_mode_rejects_invalid_implicit_reference_conflicts() -> None:
+    with (
+        nh.run(StubExecutor()),
+        nh.scope(implicit_references={"shared": object()}),
+        pytest.raises(NighthawkError, match="Conflict for implicit reference"),
+        nh.scope(mode="inherit", implicit_references={"shared": object()}),
+    ):
+        pass
+
+
+def test_scope_mode_validation_is_enforced_by_typing_contract() -> None:
+    with nh.run(StubExecutor()):
+        with nh.scope(mode="inherit"):
+            pass
+        with nh.scope(mode="replace"):
+            pass
+
+
 def test_run_configuration_model_default_applies():
     configuration = nh.StepExecutorConfiguration()
     assert configuration.model == "openai-responses:gpt-5.4-nano"