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

{nighthawk_python-0.11.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.11.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.11.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.11.0 → nighthawk_python-0.12.0}/CHANGELOG.md

@@ -7,6 +7,15 @@ 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
@@ -179,7 +188,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.11.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

{nighthawk_python-0.11.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

{nighthawk_python-0.11.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.11.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.87.0
+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.27.0; 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.27.0; 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.11.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.11.0 → nighthawk_python-0.12.0}/docs/coding-agent-backends.md

@@ -45,7 +45,7 @@ Coding agent backends do not receive native VLM-style user-prompt multimodal inp
 - `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. 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.
+- 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.
@@ -281,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.11.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.11.0 → nighthawk_python-0.12.0}/docs/natural-blocks.md

@@ -139,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
@@ -171,7 +173,21 @@ 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).
 
-For the normative rendering and transport rules, including dotted-reference hoisting and the remaining v0.11.0 nesting restrictions, see [Specification Section 8.2](specification.md#82-locals-summary).
+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
 
@@ -180,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 = ""
@@ -219,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 = ""
@@ -296,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
@@ -375,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)
 ```
@@ -392,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
@@ -470,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.11.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: