nighthawk-python 0.10.0__tar.gz → 0.12.0__tar.gz

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/.claude/rules/docs.md

@@ -39,7 +39,7 @@ Public API documentation layering:
 | `coding-agent-backends.md` | Backend users | Backend reference | Backend-specific settings, shared capabilities, skills, MCP tool exposure, working directory, troubleshooting. |
 | `for-coding-agents.md` | Coding agents (LLMs) | Operational guide | Condensed, decision-oriented rules derived from human-oriented docs. Self-contained with absolute URLs. |
 | `specification.md` | Implementors | Canonical spec | Syntax, state layers, tools, outcomes, frontmatter, runtime semantics, observability contract, and custom backend capability/protocol semantics. Numbered section headings. |
-| `philosophy.md` | Evaluators | Design rationale | Execution model, harness evidence, design consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination, tradeoffs), runtime evaluation rationale, design landscape. |
+| `philosophy.md` | Evaluators | Design rationale | Execution model, design landscape, boundary-first consequences, trust and safety boundaries, tradeoffs, and runtime evaluation rationale. |
 | `api.md` | Developers | API reference | Auto-generated from docstrings, including protocol and extension-hook symbols. |
 | `roadmap.md` | Contributors | Future directions | Ideas only. Remove when implemented. |
 | `docs/AGENTS.md` | Coding agents editing docs | Documentation governance | Canonical ownership, page roles, routing rules, and docs test invariants. Symlink to `.claude/rules/docs.md`. |
@@ -171,7 +171,7 @@ Pages in the Getting started, Patterns & verification, and Configuration nav gro
 
 **`philosophy.md`**
 
-- Owns the cumulative argument: execution model, harness evidence, design consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination, tradeoffs), runtime evaluation rationale, and design landscape.
+- Owns the cumulative argument: execution model, design landscape, boundary-first consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination), trust and safety boundaries, tradeoffs, and runtime evaluation rationale.
 - External references acceptable. Prefer stable URLs with enough inline context to survive link rot.
 - No how-to code examples for patterns in `natural-blocks.md` or `patterns.md`. Exception: positioning examples may reuse function names from those pages.
 

nighthawk_python-0.12.0/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,14 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:4.1.0": {
+      "version": "4.1.0",
+      "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:7d979c4a36d595eb4ab79909caa3f396daf3b6152dcf38e8328ea4eff42206c7",
+      "integrity": "sha256:7d979c4a36d595eb4ab79909caa3f396daf3b6152dcf38e8328ea4eff42206c7"
+    },
+    "ghcr.io/devcontainers/features/node:2.1.0": {
+      "version": "2.1.0",
+      "resolved": "ghcr.io/devcontainers/features/node@sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857",
+      "integrity": "sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857"
+    }
+  }
+}

nighthawk_python-0.12.0/.devcontainer/devcontainer.json

@@ -0,0 +1,16 @@
+{
+	"name": "Python 3.13",
+	"image": "mcr.microsoft.com/devcontainers/python:3-3.13-bookworm",
+	"features": {
+		"ghcr.io/devcontainers/features/docker-in-docker:4.1.0": {},
+		"ghcr.io/devcontainers/features/node:2.1.0": {}
+	},
+	"postCreateCommand": "/bin/sh .devcontainer/postCreateCommand.sh",
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"charliermarsh.ruff"
+			]
+		}
+	}
+}

nighthawk_python-0.12.0/.devcontainer/postCreateCommand.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+sudo apt-get update && export DEBIAN_FRONTEND=noninteractive \
+&& sudo apt-get -y install --no-install-recommends ripgrep fzf bubblewrap \
+&& sudo apt-get clean \
+&& sudo rm -rf /var/lib/apt/lists/*
+
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+uv sync
+
+npm install -g pyright
+
+curl -LsSf https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh
+curl -LsSf https://claude.ai/install.sh | bash

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/.github/dependabot.yml

@@ -6,6 +6,12 @@
 
 version: 2
 updates:
+ - package-ecosystem: "uv"
+   directory: "/"
+   schedule:
+     interval: weekly
+   cooldown:
+     default-days: 7
  - package-ecosystem: "devcontainers"
    directory: "/"
    schedule:

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/.github/workflows/docs.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Build docs
         run: uv run mkdocs build
 
-      - uses: actions/upload-pages-artifact@v4
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: site
 

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0]
+
+### Changed
+- Clarified the boundary-first philosophy page.
+- Clarified multimodal documentation and specification.
+- Raised the minimum Pydantic AI version to 2.37.0 and migrated coding-agent backends to its native-tool and structured-instruction APIs.
+- Raised the MCP minimum version to 2.1.1 and migrated the embedded tool server and content types to the MCP 2 API.
+- Updated the Claude Agent SDK integration to 0.2.151.
+
+## [0.11.0]
+
+### Added
+- Native Pydantic AI multimodal binding support for Natural block prompts, including `BinaryContent`, URL-based media, `UploadedFile`, and explicit dotted multimodal references.
+- Multimodal tool-result transport for coding-agent backends, preserving mixed text/media order and carrying MCP image/audio content natively where supported.
+- Public scope snapshot getters: `get_implicit_references`, `get_system_prompt_suffix_fragments`, and `get_user_prompt_suffix_fragments`.
+
+### Changed
+- Coding-agent backends now text-project multimodal user prompts into local file paths or URL placeholders while provider-backed executors pass `UserContent` natively.
+- Tool results now retain `ToolOutcome` payloads through backend boundaries so multimodal-capable transports can render native content before falling back to JSON previews.
+- Optimize Natural block runtime prompt
+- Update dependencies
+
+### Fixed
+- Cleaned up staged multimodal prompt files when text projection fails before a projected request is returned.
+
 ## [0.10.0]
 
 ### Added
@@ -163,7 +188,9 @@ 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.10.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.7.0...v0.8.0

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/CONTRIBUTING.md

@@ -12,6 +12,14 @@
 uv sync --all-extras --all-groups
 ```
 
+`uv` manages the project virtual environment in `.venv`. Do not create or
+activate a separate virtual environment; run project commands through `uv run`.
+The `.venv` directory is generated and ignored by Git. It can be deleted to
+rebuild the local environment, and the next `uv sync` or `uv run` recreates it.
+
+Declare project dependencies in `pyproject.toml` through `uv add`, rather than
+installing them directly into `.venv` with `uv pip install`.
+
 If you see a `uv` warning about hardlinking (common in containers or cross-filesystem workspaces), suppress it with:
 
 ```bash
@@ -39,13 +47,8 @@ uv run pytest -q       # quiet output
 
 ### Integration tests
 
-Integration tests require provider packages and API keys. Install the provider you need:
-
-```bash
-uv pip install pydantic-ai-slim[openai]
-```
-
-Then run with your `.env` loaded:
+The full setup command installs the OpenAI provider development dependency.
+Run integration tests with your `.env` loaded:
 
 ```bash
 set -a; source .env; set +a; uv run pytest -q
@@ -81,6 +84,7 @@ PFOO="cd evals/promptfoo && PROMPTFOO_PYTHON=\"$(uv python find)\" npx promptfoo
 |---|---|
 | `eval $PFOO eval` | Full regression (all backends, all tests) |
 | `eval $PFOO eval -c promptfooconfig-prompt-ab.yaml` | Prompt A/B test (gpt-5.4-mini only) |
+| `eval $PFOO eval -c promptfooconfig-nano-sanity.yaml --no-cache` | Default-model sanity check (gpt-5.4-nano only) |
 | `eval $PFOO eval -c promptfooconfig-agents.yaml` | Coding agent backends (reduced test set) |
 | `eval $PFOO eval -c promptfooconfig.yaml --filter-pattern "P-BIND-001"` | Single test |
 | `eval $PFOO eval -c promptfooconfig.yaml --filter-providers "claude-code-cli"` | Single backend |
@@ -90,6 +94,7 @@ PFOO="cd evals/promptfoo && PROMPTFOO_PYTHON=\"$(uv python find)\" npx promptfoo
 
 - `promptfooconfig.yaml` — Regression: winner prompt combo across openai-responses, claude-code-cli, and codex backends. All test cases.
 - `promptfooconfig-prompt-ab.yaml` — A/B testing: 4 prompt/tool variants on gpt-5.4-mini. All test cases.
+- `promptfooconfig-nano-sanity.yaml` — Default-model sanity check on openai-responses:gpt-5.4-nano. All test cases.
 - `promptfooconfig-agents.yaml` — Coding agent only: claude-code-cli and codex with reduced test set.
 
 #### Directory layout

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.10.0
+Version: 0.12.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/
@@ -20,17 +20,17 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: headson>=0.16.1
-Requires-Dist: pydantic-ai-slim>=1.68
-Requires-Dist: pydantic>=2
-Requires-Dist: pyyaml>=6
-Requires-Dist: tenacity>=9
-Requires-Dist: tiktoken>=0.12
+Requires-Dist: pydantic-ai-slim>=2.37.0
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: tiktoken>=0.12.0
 Provides-Extra: claude-code-cli
-Requires-Dist: mcp>=1.26; extra == 'claude-code-cli'
+Requires-Dist: mcp>=2.1.1; extra == 'claude-code-cli'
 Provides-Extra: claude-code-sdk
-Requires-Dist: claude-agent-sdk==0.1.48; extra == 'claude-code-sdk'
+Requires-Dist: claude-agent-sdk==0.2.151; extra == 'claude-code-sdk'
 Provides-Extra: codex
-Requires-Dist: mcp>=1.26; extra == 'codex'
+Requires-Dist: mcp>=2.1.1; extra == 'codex'
 Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/nighthawk-python)](https://pypi.org/project/nighthawk-python)
@@ -68,12 +68,12 @@ For other providers, see [Pydantic AI providers](https://kurusugawa-computer.git
 ```py
 import nighthawk as nh
 
+
 def python_average(numbers):
     return sum(numbers) / len(numbers)
 
-step_executor = nh.AgentStepExecutor.from_configuration(
-    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano")
-)
+
+step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"))
 
 with nh.run(step_executor):
 

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/README.md

@@ -33,12 +33,12 @@ For other providers, see [Pydantic AI providers](https://kurusugawa-computer.git
 ```py
 import nighthawk as nh
 
+
 def python_average(numbers):
     return sum(numbers) / len(numbers)
 
-step_executor = nh.AgentStepExecutor.from_configuration(
-    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano")
-)
+
+step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"))
 
 with nh.run(step_executor):
 

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/docs/api.md

@@ -22,7 +22,10 @@
         - get_current_step_context
         - get_current_usage_meter
         - get_execution_ref
+        - get_implicit_references
         - get_step_executor
+        - get_system_prompt_suffix_fragments
+        - get_user_prompt_suffix_fragments
         - resilience
         - UsageMeter
         - oversight

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/docs/coding-agent-backends.md

@@ -38,6 +38,18 @@ All three backends provide capabilities not available with Pydantic AI providers
 - **Callable discoverability:** Same rules as [Natural blocks](natural-blocks.md#functions-and-discoverability).
 - **Project-scoped files:** The CLI loads its own project files (CLAUDE.md, AGENTS.md) from `working_directory`.
 
+### Multimodal inputs
+
+Coding agent backends do not receive native VLM-style user-prompt multimodal input. Nighthawk projects multimodal prompt content into the CLI text channel instead:
+
+- `BinaryContent` is staged to a local file and referenced in the prompt with `<image>` / `<file>` plus a local file path.
+- URL-based content (`ImageUrl`, `AudioUrl`, `DocumentUrl`, `VideoUrl`) is referenced by URL in the projected prompt text.
+- `UploadedFile` user-prompt content is rejected because these backends cannot resolve provider-owned file identifiers. Tool results still preserve the rest of the payload and replace only the `UploadedFile` item with explanatory fallback text.
+- Tool results cross the backend boundary as MCP content. Image (`BinaryContent.is_image`) and audio (`BinaryContent.is_audio`) items travel natively as `ImageContent` / `AudioContent`; all other `BinaryContent` and `FileUrl` items project to `TextContent` so the MCP path stays symmetric with the text-projected prompt path. Native MCP video carriage is intentionally unsupported for now because video-modal requirements are unstable; document carriage also remains text-projected unless a future backend advertises an explicit capability. When mixed top-level text/multimodal tool-result sequences preserve their original order they satisfy the same `UserContent` rule used for prompt hoisting. The user prompt itself remains text-projected for these backends.
+- When a successful tool result splits to no text and no user content, the projected prompt stays header-only rather than inserting the preview JSON envelope.
+
+This differs from provider-backed executors that can pass a `tuple[UserContent, ...]` to a multimodal-capable provider API directly.
+
 ### Working directory
 
 All three backends accept `working_directory` in their model settings. This absolute path determines:
@@ -269,6 +281,7 @@ Example Natural function that invokes the skill:
 ```py
 import nighthawk as nh
 
+
 @nh.natural_function
 def summarize_feedback(feedback_items: list[str]) -> str:
     def group_feedback_by_topic(feedback_items: list[str]) -> dict[str, list[str]]:

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/docs/for-coding-agents.md

@@ -14,6 +14,7 @@ You are expected to write, review, and debug Python code that uses Nighthawk as
 - Prefer explicit, typed write bindings. Runtime inference exists for unannotated write bindings, but new code should not rely on it.
 - Keep outputs narrow and typed, especially when using coding agent backends. A block may do broad internal work, but the Python boundary should stay small.
 - When prompt context is truncated and you see `<snipped>`, first reduce context surface or split the block. Increase `StepContextLimits` only after simplification fails.
+- Explicit dotted multimodal references such as `<holder.photo>` can still be omitted under tight `locals_max_items` / `locals_max_tokens`; resize budgets rather than assuming hoisting is unconditional.
 
 ## 2. First decision: should this be Natural at all?
 

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/docs/index.md

@@ -14,12 +14,12 @@ The same mechanism handles lightweight LLM judgments ("classify this sentiment")
 ```py
 import nighthawk as nh
 
+
 def python_average(numbers):
     return sum(numbers) / len(numbers)
 
-step_executor = nh.AgentStepExecutor.from_configuration(
-    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano")
-)
+
+step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"))
 
 with nh.run(step_executor):
 
@@ -61,7 +61,7 @@ The LLM interprets the mixed-format input list via `<numbers>`, calls the Python
 
 ## Background and project
 
-- **[Philosophy](philosophy.md)** -- Design rationale: execution model, harness evidence, design consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination, tradeoffs), runtime evaluation rationale, and design landscape.
+- **[Philosophy](philosophy.md)** -- Design rationale: execution model, design landscape, boundary-first consequences, trust and safety boundaries, tradeoffs, and runtime evaluation rationale.
 - **[Roadmap](roadmap.md)** -- Future directions and open questions.
 
 ## Origins

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/docs/natural-blocks.md

@@ -63,6 +63,7 @@ Three sections:
 
 - **`<<<NH:PROGRAM>>>`** -- your Natural block text (after sentinel removal and `textwrap.dedent`).
 - **`<<<NH:LOCALS>>>`** -- step locals, rendered alphabetically as `name: type = value`.
+  Nighthawk renders the full current locals snapshot by design; control context size by deciding which locals exist before the block.
 - **`<<<NH:GLOBALS>>>`** -- module-level names referenced via `<name>` that are not in step locals.
 
 ### One block, one task
@@ -138,11 +139,13 @@ Write bindings can use Pydantic models for structured output with automatic vali
 ```py
 from pydantic import BaseModel
 
+
 class ReviewVerdict(BaseModel):
     approved: bool
     reason: str
     risk_level: str
 
+
 @nh.natural_function
 def judge_review(review_data: str) -> ReviewVerdict:
     verdict: ReviewVerdict
@@ -161,6 +164,31 @@ When the LLM assigns a value to `verdict`, Nighthawk validates and coerces it to
 
 Read and write bindings are rendered identically in the LOCALS section (e.g., `name: type = value`). The `<name>` vs `<:name>` distinction in the Natural program text is the signal that tells the LLM which names it may update. At runtime, Nighthawk enforces the distinction: read bindings block rebinding, while write bindings allow rebinding and commit values back to Python locals.
 
+### Multimodal bindings
+
+A binding may hold a Pydantic AI multimodal value -- `BinaryContent`, `ImageUrl`, `AudioUrl`, `DocumentUrl`, `VideoUrl`, or `UploadedFile`. These are first-class binding values: reference them with `<name>` like any other binding, and Nighthawk renders the inline placeholder (`<image>` for image media, `<file>` otherwise) in the LOCALS or GLOBALS line. Explicit dotted leaf references use the same mechanism, and dotted `list` / `tuple` leaves are hoisted when they satisfy the same `UserContent` rule as top-level bindings. `UploadedFile` is only usable as native user-prompt content on provider-backed executors that can resolve the provider-owned file reference; coding-agent backends reject it at the user-prompt boundary.
+
+Transport depends on the executor:
+
+- Provider-backed executors that accept Pydantic AI `UserContent` send the value natively to the VLM API.
+- Coding-agent backends text-project the value (staged local files or URL references). See [Coding agent backends: multimodal inputs](coding-agent-backends.md#multimodal-inputs).
+
+Nested multimodal values inside dicts, models, and objects are not recursively hoisted. Keep the prompt boundary explicit by lifting the media-bearing leaf into a helper variable before the Natural block:
+
+```py
+def summarize_report(report: Report) -> str:
+    report_scan = report.attachments.scan_image
+    summary = ""
+    """natural
+    Read <report_scan> and summarize the visual evidence in <:summary>.
+    """
+    return summary
+```
+
+This keeps the media selection visible in ordinary Python, avoids accidental traversal of large object graphs, and lets normal LOCALS budgeting decide whether the helper variable is rendered.
+
+For the normative rendering and transport rules, including dotted-reference hoisting and nested multimodal behavior, see [Specification Section 8.2](specification.md#82-locals-summary).
+
 ### f-string injection
 
 Inline f-string blocks embed Python expressions directly into the Natural program text. The expression is evaluated when Python evaluates the f-string -- before the LLM sees the prompt.
@@ -168,6 +196,7 @@ Inline f-string blocks embed Python expressions directly into the Natural progra
 ```py
 PROJECT_POLICY = ["safety-first", "concise-output", "cite-assumptions"]
 
+
 @nh.natural_function
 def choose_policy(post: str) -> str:
     selected_policy = ""
@@ -207,10 +236,12 @@ Member accesses and function results work too:
 ```py
 from pydantic import BaseModel
 
+
 class Config(BaseModel):
     max_length: int = 100
     style: str = "formal"
 
+
 @nh.natural_function
 def generate(config: Config, topic: str) -> str:
     output = ""
@@ -284,6 +315,7 @@ When a Natural block references a module-level name via `<name>`, it appears in
 def python_average(numbers):
     return sum(numbers) / len(numbers)
 
+
 @nh.natural_function
 def calculate_average(numbers):
     """natural
@@ -323,6 +355,8 @@ python_average: (numbers)
 
 Function parameters and local variables appear in LOCALS. Module-level names referenced via `<name>` that are _not_ in locals appear in GLOBALS. Nighthawk renders callable entries with their full signature and docstring intent -- but only when type information is available.
 
+This is a deliberate tradeoff: LOCALS stays a flat, predictable snapshot of what Python has already bound. If you want less prompt context, keep fewer locals alive at the block boundary. Section truncation still follows the normal lexicographic rendering order, so under tight budgets an explicitly referenced dotted multimodal leaf can still be omitted along with any other later entry.
+
 When you pass a module-level callable as a function parameter with a generic type (`object`, `Any`, or no annotation), the name moves from GLOBALS to LOCALS and **its signature is erased**. The LLM cannot discover the correct arguments or return type.
 
 The principle extends beyond callables. Any module-level name that is stable across invocations -- constants, classes, utility functions -- should stay in GLOBALS via `<name>` read bindings rather than being pulled into LOCALS via parameters or local assignments. Reserve function parameters for data that genuinely varies per call.
@@ -361,11 +395,13 @@ For deterministic functions (no Natural blocks), the boundary is at the function
 ```py
 from pydantic import BaseModel
 
+
 class ScoreInput(BaseModel):
     base: int
     bonus: int
     multiplier: float = 1.0
 
+
 def compute_score(score_input: ScoreInput) -> int:
     return int((score_input.base + score_input.bonus) * score_input.multiplier)
 ```
@@ -378,11 +414,13 @@ For judgment-heavy functions (containing Natural blocks), the boundary moves *in
 from pydantic import BaseModel
 from nighthawk import JsonableValue
 
+
 class ReviewVerdict(BaseModel):
     approved: bool
     reason: str
     risk_level: str
 
+
 @nh.natural_function
 def judge_review(review_data: str | JsonableValue) -> ReviewVerdict:
     verdict: ReviewVerdict
@@ -456,6 +494,7 @@ def get_feedback_summary(topic: str, max_items: int = 10) -> str:
     items = fetch_feedback(topic=topic, limit=max_items)
     return format_summary(items)
 
+
 # Natural block sees only what it needs
 @nh.natural_function
 def analyze_feedback(topic: str) -> str:

{nighthawk_python-0.10.0 → nighthawk_python-0.12.0}/docs/patterns.md

@@ -117,6 +117,7 @@ def validate(data: str) -> str:
     """
     return result
 
+
 try:
     validate("corrupted-input")
 except nh.ExecutionError as e:
@@ -131,6 +132,7 @@ When a Natural block references exception types visible in step locals or global
 class InputError(Exception):
     pass
 
+
 @nh.natural_function
 def strict_validate(data: str) -> str:
     result = ""
@@ -140,6 +142,7 @@ def strict_validate(data: str) -> str:
     """
     return result
 
+
 try:
     strict_validate("bad")
 except InputError as e:
@@ -165,6 +168,7 @@ async def summarize_async(text: str) -> str:
     """
     return result
 
+
 summary = await summarize_async("A long document about climate change...")
 ```
 
@@ -181,6 +185,7 @@ async def fetch_data(query: str) -> list[str]:
     """Fetch data matching the query from an external API."""
     ...
 
+
 @nh.natural_function
 async def analyze(query: str) -> str:
     result = ""
@@ -199,6 +204,7 @@ Async natural functions are ordinary coroutines, so you can run multiple Natural
 ```py
 import asyncio
 
+
 @nh.natural_function
 async def classify(text: str) -> str:
     label: str = ""
@@ -207,6 +213,7 @@ async def classify(text: str) -> str:
     """
     return label
 
+
 async def classify_batch(texts: list[str]) -> list[str]:
     return list(await asyncio.gather(*(classify(t) for t in texts)))
 ```
@@ -242,6 +249,7 @@ def step_1(carry: list[str]) -> int:
     """
     return result
 
+
 @nh.natural_function
 def step_2(carry: list[str]) -> int:
     result = 0
@@ -253,9 +261,10 @@ def step_2(carry: list[str]) -> int:
     """
     return result
 
+
 carry: list[str] = []
-r1 = step_1(carry)   # carry now has 1 entry
-r2 = step_2(carry)   # carry now has 2 entries
+r1 = step_1(carry)  # carry now has 1 entry
+r2 = step_2(carry)  # carry now has 2 entries
 ```
 
 Any mutable object works -- `list`, `dict`, Pydantic models, custom classes.
@@ -293,7 +302,7 @@ seed_step(carry)
 carry_a = carry.copy()
 carry_b = carry.copy()
 
-result_a = branch_add(carry_a)       # diverges from here
+result_a = branch_add(carry_a)  # diverges from here
 result_b = branch_multiply(carry_b)  # independent path
 ```
 
@@ -443,9 +452,11 @@ For monetary budgets, supply a `cost_function` that converts `RunUsage` to a flo
 ```py
 from pydantic_ai.usage import RunUsage
 
+
 def dollar_cost(usage: RunUsage) -> float:
     return usage.input_tokens * 3e-6 + usage.output_tokens * 15e-6
 
+
 budgeted = budget(cost=1.00, cost_function=dollar_cost)(classify)
 ```
 
@@ -459,7 +470,7 @@ Prevent repeated calls to a failing service. After `fail_threshold` consecutive
 from nighthawk.resilience import circuit_breaker, CircuitState
 
 protected_api = circuit_breaker(fail_threshold=5, reset_timeout=60)(call_api)
-protected_api.state    # CircuitState.CLOSED
+protected_api.state  # CircuitState.CLOSED
 protected_api.reset()  # manual reset
 ```
 
@@ -471,11 +482,11 @@ All transformers produce callables with the original signature, so they compose
 
 ```py
 robust_classify = fallback(
-    retrying(attempts=2)(                      # 3. Retry the voted call
-        vote(count=3)(classify_gpt4)           # 2. Vote 3x with GPT-4
-    ),                                         # 1. Try GPT-4 first
-    retrying(attempts=2)(classify_mini),       # 4. Fall back to mini
-    default="unknown",                         # 5. Last resort
+    retrying(attempts=2)(  # 3. Retry the voted call
+        vote(count=3)(classify_gpt4)  # 2. Vote 3x with GPT-4
+    ),  # 1. Try GPT-4 first
+    retrying(attempts=2)(classify_mini),  # 4. Fall back to mini
+    default="unknown",  # 5. Last resort
 )
 
 result = robust_classify(text)
@@ -499,6 +510,7 @@ Recommended composition order (innermost to outermost):
 ```py
 from functools import lru_cache
 
+
 @lru_cache(maxsize=256)
 @nh.natural_function
 def classify(text: str) -> str: