nighthawk-python 0.3.1__tar.gz → 0.4.0__tar.gz

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/.claude/rules/docs.md

@@ -13,7 +13,7 @@ Each file has a distinct audience and scope. Content belongs in exactly one file
 |---|---|---|---|
 | `index.md` | First-time visitors | Project overview, motivation, workflow styles | What Nighthawk is and why. No API details, no how-to. |
 | `quickstart.md` | New users | Shortest path to running a Natural block | Setup, first example, backends table, credentials, troubleshooting. No deep explanations. |
-| `tutorial.md` | Users learning the system | Build understanding from first principles | Bindings, tools, control flow, composition, configuration, guidelines. Assumes quickstart is done. |
+| `tutorial.md` | Users learning the system | Build understanding from first principles | Bindings, functions and discoverability, control flow, composition, configuration, guidelines. Assumes quickstart is done. |
 | `design.md` | Implementors and advanced users | Canonical specification (target behavior) | Full technical detail: syntax rules, state layers, prompt rendering, tool contracts, outcome schema, frontmatter. |
 | `providers.md` | Users choosing and configuring models | Provider selection, Pydantic AI setup, custom backends | Provider categories, capability matrix, model identifiers, Pydantic AI model settings, step executor protocols. No coding-agent-backend-specific content. |
 | `coding-agent-backends.md` | Users of Claude Code or Codex backends | Coding agent backend configuration and features | Backend-specific settings, skills, MCP tool exposure, working directory, project-scoped files. |
@@ -43,6 +43,8 @@ Each file has a distinct audience and scope. Content belongs in exactly one file
 - When tutorial.md and design.md cover the same concept, tutorial.md shows the "what and how" with examples; design.md specifies the "exact rules and edge cases".
 - Keep code examples self-contained: a reader should understand the example without reading surrounding prose.
 - Built-in tool names (`nh_eval`, `nh_exec`, `nh_assign`) are implementation details. Only `design.md` may expose them. All other files describe behavior instead (e.g., "the LLM can set a new value" rather than "use `nh_assign`").
+- `@nh.tool` is discouraged. Binding functions are the preferred callable exposure mechanism. `design.md` documents `@nh.tool` as part of the specification. `tutorial.md` may mention it with a "prefer binding functions" note. All other files should not add examples, recommendations, or references to `@nh.tool`.
+- The PyPI package name is `nighthawk-python`. Always use `nighthawk-python` (not `nighthawk`) in `pip install` commands and extras references (e.g., `nighthawk-python[claude-code-sdk]`).
 
 ### index.md specifics
 
@@ -91,7 +93,7 @@ Each file has a distinct audience and scope. Content belongs in exactly one file
 - This file should be self-contained: a coding agent reading only this file should be able to write correct Nighthawk code without consulting other docs.
 - This file is consumed standalone (`@docs/for-coding-agents.md` in CLAUDE.md/AGENTS.md, GitHub raw URL, etc.). Do not assume sibling files exist at relative paths.
 - All external references to other docs use absolute URLs based on `site_url` from `mkdocs.yml` (currently `https://kurusugawa-computer.github.io/nighthawk-python/`). If `site_url` changes, update the URLs in this file.
-- `@nh.tool` is deprecated. Do not add examples, recommendations, or references to `@nh.tool` in this file. Binding functions are the only recommended callable exposure mechanism.
+- `@nh.tool` must not appear in this file (see General rule on `@nh.tool`). Binding functions are the only callable exposure mechanism presented here.
 - Filter content for coding-agent relevance. Omit infrastructure-level concerns (scoped overrides parameter lists, exception hierarchy beyond `ExecutionError`, observability/tracing) that do not affect how an agent writes Natural blocks or binding functions. Mention existence and link to Tutorial or Design for details.
 
 ### api.md specifics

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-20
+
+### Added
+- `nighthawk.testing` module with test executors and convenience factories for deterministic Natural function testing without LLM API calls.
+
+### Changed
+- Rewrote testing documentation in `tutorial.md` (Section 8) and `for-coding-agents.md` (Section 8): replaced incorrect `TestModel` usage with `nighthawk.testing` utilities, added testing strategy guidance distinguishing mock tests (Python logic) from integration tests (Natural block judgment).
+
 ## [0.3.1] - 2026-03-19
 
 ### Changed
@@ -49,7 +57,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.1.0...v0.2.0

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.3.1
+Version: 0.4.0
 Summary: An experimental Python library that embeds Natural blocks inside Python functions and executes them using an LLM.
 Project-URL: Repository, https://github.com/kurusugawa-computer/nighthawk-python
 Project-URL: Documentation, https://kurusugawa-computer.github.io/nighthawk-python/

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/docs/api.md

@@ -88,3 +88,7 @@
         - ErrorKind
         - ToolResultWrapperToolset
 
+## Testing
+
+::: nighthawk.testing
+

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/docs/coding-agent-backends.md

@@ -4,7 +4,7 @@ The `claude-code-sdk`, `claude-code-cli`, and `codex` backends delegate Natural
 
 Minimal configuration:
 
-```python
+```py
 from nighthawk.configuration import StepExecutorConfiguration
 
 # Claude Code (SDK)
@@ -62,7 +62,7 @@ pip install nighthawk-python[claude-code-sdk]
 
 ### Settings
 
-```python
+```py
 from nighthawk.backends.claude_code_sdk import ClaudeCodeSdkModelSettings
 
 configuration = StepExecutorConfiguration(
@@ -79,7 +79,7 @@ configuration = StepExecutorConfiguration(
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `permission_mode` | `"default"` \| `"acceptEdits"` \| `"plan"` \| `"bypassPermissions"` | `"default"` | Claude Code permission mode |
+| `permission_mode` | `"default"` \| `"acceptEdits"` \| `"plan"` \| `"bypassPermissions"` | `"default"` | Claude Code permission mode (always passed to the SDK) |
 | `setting_sources` | `list[SettingSource]` \| `None` | `None` | Setting source scopes to load (`SettingSource` is `"user"`, `"project"`, or `"local"`) |
 | `allowed_tool_names` | `tuple[str, ...]` \| `None` | `None` | Nighthawk tool names exposed to the model |
 | `claude_allowed_tool_names` | `tuple[str, ...]` \| `None` | `None` | Additional Claude Code native tool names to allow (SDK only; CLI does not support this field) |
@@ -108,7 +108,7 @@ The `claude` CLI must be installed separately (it is a system tool, not a Python
 
 ### Settings
 
-```python
+```py
 from nighthawk.backends.claude_code_cli import ClaudeCodeCliModelSettings
 
 configuration = StepExecutorConfiguration(
@@ -153,7 +153,7 @@ pip install nighthawk-python[codex]
 
 ### Settings
 
-```python
+```py
 from nighthawk.backends.codex import CodexModelSettings
 
 configuration = StepExecutorConfiguration(
@@ -213,7 +213,7 @@ Use the returned groups to set <:summary_markdown> as exactly 3 bullet points.
 
 Example Natural function that invokes the skill:
 
-```python
+```py
 import nighthawk as nh
 
 @nh.natural_function

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/docs/for-coding-agents.md

@@ -14,8 +14,6 @@ Key invariants:
 - Each Natural block executes independently. There is no implicit message history between blocks. Cross-block context must be explicit.
 - Write bindings (`<:name>`) are the only way the LLM commits values back into Python locals. The LLM is physically constrained to operate on interpreter-visible objects.
 
-## 2. When to use Natural blocks
-
 **Use Natural when the task requires LLM judgment** -- decisions that depend on interpretation, world knowledge, or subjective evaluation:
 
 - Classification and routing (e.g., categorize a support ticket).
@@ -32,7 +30,7 @@ Key invariants:
 
 **Decision rule:** if the correct output can be computed without an LLM, use Python. Natural blocks add latency, cost, and non-determinism.
 
-## 3. Writing Natural blocks
+## 2. Writing Natural blocks
 
 ### Anatomy
 
@@ -60,7 +58,11 @@ Each Natural block should make exactly one independent judgment. If a block make
 - Use f-string injection for static config, pre-formatted context, computed values.
 - Use `<name>` bindings for mutable state and objects the LLM needs to inspect or modify.
 
-## 4. Designing binding functions
+### Async
+
+Async natural functions work identically to sync ones, with two additions: expressions evaluated by tools may use `await`, and return values that are awaitable are automatically awaited before validation.
+
+## 3. Designing binding functions
 
 Binding functions (local or module-level callables) are the preferred way to expose functions to the LLM. The LLM discovers them from the LOCALS/GLOBALS sections of the prompt, rendered as their signature with the first docstring line as `# intent:`.
 
@@ -68,21 +70,11 @@ Binding functions (local or module-level callables) are the preferred way to exp
 
 Module-level names that are stable across invocations (constants, classes, utility functions) should stay in GLOBALS via `<name>` read bindings. Reserve function parameters for data that genuinely varies per call.
 
-Wrong -- `fetch_data` loses its signature in LOCALS:
-
-```python
-@nh.natural_function
-async def summarize(query: str, fetch_data: object) -> str:
-    result = ""
-    """natural
-    Use <fetch_data> to get data for <query> and set <:result>.
-    """
-    return result
-```
-
-Correct -- `fetch_data` keeps its full signature in GLOBALS:
+```py
+# Wrong -- fetch_data loses its signature in LOCALS:
+async def summarize(query: str, fetch_data: object) -> str: ...
 
-```python
+# Correct -- fetch_data keeps its full signature in GLOBALS:
 @nh.natural_function
 async def summarize(query: str) -> str:
     result = ""
@@ -96,7 +88,7 @@ async def summarize(query: str) -> str:
 
 Each parameter in a binding function signature is a decision point the LLM must evaluate. Compose complex operations in Python and expose simple binding functions:
 
-```python
+```py
 # Wrong -- too many parameters
 def find_items(category: str, min_score: float, max_score: float,
                tags: list[str], created_after: str, sort_by: str) -> list[dict]:
@@ -114,7 +106,7 @@ def find_top_items(category: str) -> list[dict]:
 
 Write short docstrings explaining intent and boundaries. The first line appears as `# intent:` in the prompt. Clear function names and accurate type annotations complete discoverability.
 
-## 5. Control flow and error handling
+## 4. Control flow and error handling
 
 ### Outcomes
 
@@ -132,7 +124,7 @@ Each Natural block returns exactly one outcome:
 
 Restrict allowed outcomes with YAML frontmatter:
 
-```python
+```py
 """natural
 ---
 deny: [raise, return]
@@ -145,7 +137,7 @@ Read <text> and set <:result> to a summary.
 
 The LLM signals errors via the `raise` outcome. Catch with standard Python:
 
-```python
+```py
 try:
     validate(data)
 except nh.ExecutionError as e:
@@ -154,13 +146,13 @@ except nh.ExecutionError as e:
 
 Custom exception types referenced in step locals or globals are available as raise targets. Catch `nh.ExecutionError` for Natural block failures; all Nighthawk exceptions inherit from `nh.NighthawkError`.
 
-## 6. Cross-block composition
+## 5. Cross-block composition
 
 ### The carry pattern
 
 Pass a mutable object as a read binding (`<carry>`, not `<:carry>`) and instruct the LLM to mutate it in-place:
 
-```python
+```py
 @nh.natural_function
 def step_1(carry: list[str]) -> int:
     result = 0
@@ -177,35 +169,16 @@ r2 = step_2(carry)   # carry now has 2 entries
 
 Critical: use `<carry>` (read binding), not `<:carry>` (write binding). Read bindings prevent rebinding, preserving the caller's reference.
 
-### Branching
+- Branch by copying the carry (`carry_a = carry.copy()`). Each copy continues independently.
+- When the carry's token footprint is too large, inject context via f-string instead ([Section 2](#interpolation)).
 
-Copy the carry to create independent branches:
-
-```python
-carry_a = carry.copy()
-carry_b = carry.copy()
-result_a = branch_add(carry_a)
-result_b = branch_multiply(carry_b)
-```
-
-### f-string injection as alternative
-
-When the carry's locals summary footprint is too large, inject pre-formatted context via f-string:
-
-```python
-f"""natural
-Prior context: {context_text}
-Set <:result> based on the context.
-"""
-```
-
-## 7. Execution configuration
+## 6. Execution configuration
 
 ### Run context
 
 Natural functions must be called inside `with nh.run(step_executor):`. For backend-specific settings, see [Coding agent backends](https://kurusugawa-computer.github.io/nighthawk-python/coding-agent-backends/).
 
-```python
+```py
 step_executor = nh.AgentStepExecutor.from_configuration(
     configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5-mini"),
 )
@@ -217,7 +190,7 @@ Use `nh.scope()` to override model, prompts, or context limits within an existin
 
 LOCALS and GLOBALS sections are bounded by `StepContextLimits`. When bindings are missing or truncated (`<snipped>`), adjust the limits:
 
-```python
+```py
 configuration = nh.StepExecutorConfiguration(
     model="openai-responses:gpt-5-mini",
     context_limits=nh.StepContextLimits(
@@ -227,113 +200,162 @@ configuration = nh.StepExecutorConfiguration(
 )
 ```
 
-## 8. Testing
+## 7. Testing
+
+### Testing strategy
+
+Mock tests exercise the Python logic around Natural blocks -- control flow, error handling, composition, binding wiring. They do **not** exercise the Natural blocks themselves. Since Natural blocks are the core of a Nighthawk application, mock tests alone are insufficient.
+
+| Layer | What it tests | What it cannot test |
+|---|---|---|
+| **Mock tests** (`nighthawk.testing`) | Python logic: control flow, error handling, composition, binding wiring | Natural block effectiveness, prompt quality, LLM behavior |
+| **Integration tests** (real LLM) | Whether the Natural block text actually produces correct judgments | Deterministic reproducibility (LLMs are non-deterministic) |
+
+**Guideline:** use mock tests to lock down the deterministic Python shell, then use integration tests to validate that each Natural block's prompt elicits the intended judgment. Do not rely on mock tests as the primary quality gate -- a mock test passes even when the Natural block text is completely wrong.
 
-Use Pydantic AI's `TestModel` for deterministic unit tests without API calls:
+### Mock tests
 
-```python
-from nighthawk.runtime.step_executor import AgentStepExecutor
-from nighthawk.configuration import StepExecutorConfiguration
-from pydantic_ai.models.test import TestModel
+`ScriptedExecutor` returns scripted responses and records every call. Use it for Python logic that surrounds Natural blocks.
 
-configuration = StepExecutorConfiguration(model="openai-responses:gpt-5-nano")
-executor = AgentStepExecutor(configuration=configuration, agent=TestModel())
+```py
+from nighthawk.testing import ScriptedExecutor, pass_response, raise_response
 
+executor = ScriptedExecutor(responses=[
+    pass_response(result="Three key points: ..."),
+])
 with nh.run(executor):
-    # Natural functions use TestModel -- deterministic, no API calls
-    ...
+    output = summarize("long document")
+
+assert output == "Three key points: ..."
+
+# Inspect what was passed to the executor
+call = executor.calls[0]
+assert "result" in call.binding_names        # write binding registered
+assert call.step_locals["text"] == "long document"  # locals visible
 ```
 
-## 9. Type boundary placement
+For multi-step functions, pass `default_response` to avoid enumerating every response:
 
-For deterministic functions (no Natural blocks), the type boundary is at the function entry point -- use typed inputs.
+```py
+executor = ScriptedExecutor(default_response=pass_response(result=""))
+```
 
-For judgment-heavy functions (containing Natural blocks), the type boundary moves inside the function. Accept flexible inputs at the entry point and let the Natural block interpret them into typed intermediates via write bindings:
+#### Outcome factories
 
-```python
-from pydantic import BaseModel
+| Factory | Outcome | Use case |
+|---|---|---|
+| `pass_response(**bindings)` | pass | Normal completion with binding values |
+| `raise_response(message, *, error_type=None)` | raise | Test error handling paths |
+| `return_response(reference_path, **bindings)` | return | Early return from Natural function |
+| `break_response()` | break | Exit enclosing loop |
+| `continue_response()` | continue | Skip to next iteration |
+
+```py
+# Error handling:
+executor = ScriptedExecutor(responses=[
+    raise_response("invalid input", error_type="ValueError"),
+])
+
+# Early return:
+executor = ScriptedExecutor(responses=[
+    return_response("result", result="early exit"),
+])
+```
 
-class ReviewVerdict(BaseModel):
-    approved: bool
-    reason: str
-    risk_level: str
+#### Callback executor
 
-@nh.natural_function
-def judge_review(review_data: str | nh.JsonableValue) -> ReviewVerdict:
-    verdict: ReviewVerdict
-    """natural
-    Analyze <review_data> and produce a structured <:verdict>.
-    """
-    return verdict
+`CallbackExecutor` delegates to a callback when response logic depends on input. Like `ScriptedExecutor`, it records calls in `executor.calls`:
+
+```py
+from nighthawk.testing import CallbackExecutor, StepCall, StepResponse
+
+def handler(call: StepCall) -> StepResponse:
+    text = call.step_locals.get("text", "")
+    if isinstance(text, str) and "urgent" in text:
+        return pass_response(priority="high")
+    return pass_response(priority="normal")
+
+executor = CallbackExecutor(handler)
+with nh.run(executor):
+    assert triage("urgent outage") == "high"
 ```
 
-## 10. Common mistakes to avoid
+#### Binding wiring verification
 
-| Mistake | Why it breaks | Fix |
-|---|---|---|
-| Pass a callable as a parameter with generic type (`object`, `Any`) | Signature erased in LOCALS; LLM cannot discover arguments | Reference via `<name>` read binding so it appears in GLOBALS with full signature |
-| Use `<:carry>` (write binding) for mutable context | Rebinding breaks the caller's reference | Use `<carry>` (read binding); mutate in-place |
-| Put two independent judgments in one block | Non-deterministic, hard to test, unclear contract | Split into two blocks connected by Python |
-| Use Natural for deterministic computation | Wastes latency/cost, adds non-determinism | Use Python |
-| Forget type annotations on write bindings | No validation or coercion at commit time | Always annotate `<:name>` bindings |
-| Duplicate module-level constants as function parameters | Moves stable values from GLOBALS to LOCALS, wastes tokens | Reference via `<name>` read binding |
+Use recorded calls to verify that the right data is visible to the LLM:
+
+```py
+executor = ScriptedExecutor(responses=[pass_response(result="")])
+with nh.run(executor):
+    process(query="test")
 
-## 11. Quick reference
+call = executor.calls[0]
+assert "helper" in call.step_globals   # binding function visible in GLOBALS
+assert "query" in call.step_locals     # parameter visible in LOCALS
+assert "result" in call.binding_names  # write binding registered
+```
 
-### Imports and setup
+### Integration tests
 
-```python
-import nighthawk as nh
+Integration tests call a real LLM and validate the judgment. This is where Natural block quality is actually tested.
 
+```py
 step_executor = nh.AgentStepExecutor.from_configuration(
     configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5-mini"),
 )
 with nh.run(step_executor):
-    ...
+    verdict = judge_review("The code has no error handling and uses eval().")
+
+assert not verdict.approved
+assert verdict.risk_level in ("high", "critical")
 ```
 
-### Natural function template
+For structured outputs, assert on type, value range, and semantic consistency rather than exact string matches. LLMs are non-deterministic; brittle equality checks cause flaky tests.
 
-```python
-@nh.natural_function
-def my_function(input_data: str) -> str:
-    result: str = ""
-    """natural
-    Read <input_data> and set <:result> to the processed output.
-    """
-    return result
+Gate integration tests behind an environment variable so they do not run in every CI job:
+
+```py
+import os
+import pytest
+
+if os.getenv("NIGHTHAWK_RUN_INTEGRATION_TESTS") != "1":
+    pytest.skip("Integration tests disabled", allow_module_level=True)
 ```
 
-### Async natural function
+## 8. Type boundary placement
 
-Async natural functions work identically to sync ones, with two additions: expressions evaluated by tools may use `await`, and return values that are awaitable are automatically awaited before validation.
+For deterministic functions (no Natural blocks), the type boundary is at the function entry point -- use typed inputs.
 
-```python
-@nh.natural_function
-async def my_async_function(text: str) -> str:
-    result: str = ""
-    """natural
-    Summarize <text> and set <:result>.
-    """
-    return result
-```
+For judgment-heavy functions (containing Natural blocks), the type boundary moves inside the function. Accept flexible inputs at the entry point and let the Natural block interpret them into typed intermediates via write bindings:
 
-### Binding function pattern
+```py
+from pydantic import BaseModel
 
-```python
-def helper(query: str) -> list[str]:
-    """Fetch items matching the query."""
-    ...
+class ReviewVerdict(BaseModel):
+    approved: bool
+    reason: str
+    risk_level: str
 
 @nh.natural_function
-def process(query: str) -> str:
-    result = ""
+def judge_review(review_data: str | nh.JsonableValue) -> ReviewVerdict:
+    verdict: ReviewVerdict
     """natural
-    Call <helper> with <query> and set <:result> to a summary of the results.
+    Analyze <review_data> and produce a structured <:verdict>.
     """
-    return result
+    return verdict
 ```
 
+## 9. Common mistakes to avoid
+
+| Mistake | Why it breaks | Fix |
+|---|---|---|
+| Pass a callable as a parameter with generic type (`object`, `Any`) | Signature erased in LOCALS; LLM cannot discover arguments | Reference via `<name>` read binding so it appears in GLOBALS with full signature |
+| Use `<:carry>` (write binding) for mutable context | Rebinding breaks the caller's reference | Use `<carry>` (read binding); mutate in-place |
+| Put two independent judgments in one block | Non-deterministic, hard to test, unclear contract | Split into two blocks connected by Python |
+| Use Natural for deterministic computation | Wastes latency/cost, adds non-determinism | Use Python |
+| Forget type annotations on write bindings | No validation or coercion at commit time | Always annotate `<:name>` bindings |
+| Duplicate module-level constants as function parameters | Moves stable values from GLOBALS to LOCALS, wastes tokens | Reference via `<name>` read binding |
+
 ## References
 
 - [Tutorial](https://kurusugawa-computer.github.io/nighthawk-python/tutorial/) -- learn Nighthawk from first principles (human-oriented).

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/docs/index.md

@@ -127,19 +127,7 @@ calculate_average([1, "2", "three", "cuatro", "五"])  # 3.0
 
 ## Natural blocks
 
-A Natural block is a Python docstring or a standalone string literal whose underlying string value begins with `natural\n`.
-
-Bindings:
-
-- `<name>` is a read binding.
-- `<:name>` is a write binding.
-
-Write bindings control which values are committed back into Python locals at Natural block boundaries.
-
-Interpolation:
-
-- Natural blocks are literal by default. Interpolation is opt-in via f-string syntax.
-- See [Tutorial Section 2](tutorial.md#2-providing-data-to-a-block) for details.
+A Natural block is a Python docstring or a standalone string literal beginning with `natural\n`. Inside the block, `<name>` read bindings expose Python values to the LLM, and `<:name>` write bindings let the LLM commit values back into Python locals. Natural blocks are literal by default; interpolation is opt-in via f-string syntax. See the [Tutorial](tutorial.md#2-providing-data-to-a-block) for details.
 
 ## References
 

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/docs/providers.md

@@ -2,7 +2,7 @@
 
 Nighthawk delegates Natural block execution to an LLM. The model is selected through the `model` field of `StepExecutorConfiguration` using the `provider:model` format:
 
-```python
+```py
 from nighthawk.configuration import StepExecutorConfiguration
 
 configuration = StepExecutorConfiguration(model="openai-responses:gpt-5-nano")
@@ -36,7 +36,7 @@ Any provider that [Pydantic AI supports](https://ai.pydantic.dev/models/overview
 
 Examples:
 
-```python
+```py
 # OpenAI
 configuration = StepExecutorConfiguration(model="openai-responses:gpt-5-nano")
 
@@ -71,7 +71,7 @@ See the [Pydantic AI documentation](https://ai.pydantic.dev/models/overview/) fo
 
 Pydantic AI providers accept standard Pydantic AI model settings via the `model_settings` field:
 
-```python
+```py
 configuration = StepExecutorConfiguration(
     model="openai-responses:gpt-5-nano",
     model_settings={"temperature": 0.5},
@@ -80,7 +80,7 @@ configuration = StepExecutorConfiguration(
 
 ## Coding agent backends
 
-The `claude-code-sdk`, `claude-code-cli`, and `codex` backends implement the Pydantic AI `Model` protocol internally but delegate inference to a coding agent CLI rather than a Pydantic AI provider. Install with `nighthawk[claude-code-sdk]`, `nighthawk[claude-code-cli]`, or `nighthawk[codex]`. See [Coding agent backends](coding-agent-backends.md) for configuration, skill behavior, and backend-specific settings.
+The `claude-code-sdk`, `claude-code-cli`, and `codex` backends implement the Pydantic AI `Model` protocol internally but delegate inference to a coding agent CLI rather than a Pydantic AI provider. Install with `nighthawk-python[claude-code-sdk]`, `nighthawk-python[claude-code-cli]`, or `nighthawk-python[codex]`. See [Coding agent backends](coding-agent-backends.md) for configuration, skill behavior, and backend-specific settings.
 
 ## Custom backends
 
@@ -88,7 +88,7 @@ Nighthawk's `SyncStepExecutor` and `AsyncStepExecutor` protocols define the step
 
 For most cases, wrap a Pydantic AI `Agent` using `AgentStepExecutor`:
 
-```python
+```py
 from pydantic_ai import Agent
 from nighthawk.runtime.step_executor import AgentStepExecutor
 
@@ -98,7 +98,7 @@ executor = AgentStepExecutor.from_agent(agent=agent)
 
 For full control, implement `AsyncStepExecutor` (or `SyncStepExecutor` for synchronous use) directly:
 
-```python
+```py
 from nighthawk.runtime.step_executor import AsyncStepExecutor
 from nighthawk.runtime.step_context import StepContext
 from nighthawk.runtime.step_contract import StepOutcome

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/docs/quickstart.md

@@ -78,8 +78,11 @@ See [Providers](providers.md) for the default and recommended models.
 Credential configuration for Pydantic AI providers follows [Pydantic AI conventions](https://ai.pydantic.dev/models/overview/). Common environment variables:
 
 - `OPENAI_API_KEY` — required for OpenAI models ([details](https://ai.pydantic.dev/models/openai/))
+- `ANTHROPIC_API_KEY` — required for Anthropic models ([details](https://ai.pydantic.dev/models/anthropic/))
 - `GOOGLE_API_KEY` — required for Google AI (Gemini API) models ([details](https://ai.pydantic.dev/models/gemini/))
 - Google Vertex AI uses Application Default Credentials, not an API key ([details](https://ai.pydantic.dev/models/gemini/#vertex-ai))
+- AWS Bedrock uses AWS credentials, not an API key ([details](https://ai.pydantic.dev/models/bedrock/))
+- `GROQ_API_KEY` — required for Groq models ([details](https://ai.pydantic.dev/models/groq/))
 
 ## Safety model
 
@@ -105,12 +108,3 @@ Set the environment variable before running: `export OPENAI_API_KEY=sk-xxxxxxxxx
 
 Install the required provider package. For Pydantic AI providers: `pip install pydantic-ai-slim[openai]`. For coding agent backends: `pip install nighthawk-python[claude-code-sdk]`.
 
-## Next Steps
-
-- **[Tutorial](tutorial.md)** — Learn Nighthawk from first principles.
-- **[Providers](providers.md)** — LLM providers and configuration.
-- **[Coding agent backends](coding-agent-backends.md)** — Claude Code and Codex backend configuration.
-- **[Design](design.md)** — Canonical specification.
-- **[API Reference](api.md)** — Auto-generated API documentation.
-- **[Roadmap](roadmap.md)** — Future directions.
-- **[For coding agents](for-coding-agents.md)** — Nighthawk development guide for coding agents (LLM reference).

{nighthawk_python-0.3.1 → nighthawk_python-0.4.0}/docs/roadmap.md

@@ -70,4 +70,4 @@ The f-string binding span validation uses a NUL byte (`\x00`) as a placeholder f
 ## Open questions
 
 - How to best represent tool results in the prompt for robust reasoning.
-- How to debug Natural blocks deterministically (unit testing is addressed via `TestModel`; debugging the LLM's reasoning path remains open).
+- How to debug Natural blocks deterministically (unit testing is addressed via `nighthawk.testing`; debugging the LLM's reasoning path remains open).