nighthawk-python 0.13.0__tar.gz → 0.15.0__tar.gz

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/.claude/rules/docs.md

@@ -77,7 +77,7 @@ List only topics that commonly drift across multiple files or are easy to mispla
 - Terminology: "task" = structural unit (contract), "judgment" = cognitive act. Use "one task per block".
 - Code examples: self-contained and understandable without surrounding prose.
 - Built-in tools (`nh_eval`, `nh_assign`): implementation details. Only `specification.md` may expose them.
-- Native tools (`nh.scope(tools=...)`): `specification.md` documents as spec, `runtime-configuration.md` documents usage and the role split with `implicit_references`, `natural-blocks.md` may mention it with a "prefer binding functions" note, all others must not reference it.
+- Native tools (`nh.scope(tools=...)`): `specification.md` documents as spec, `runtime-configuration.md` documents usage and the role split with `task_references`, `natural-blocks.md` may mention it with a "prefer binding functions" note, all others must not reference it.
 - Package name: always `nighthawk-python` in `pip install` commands.
 - When renaming a document or changing its role, update all inbound references, routing rules here, relevant `tests/docs`, and navigation metadata if applicable.
 - When a governance file under `docs/` is not meant for publication, its MkDocs handling must be explicit.
@@ -222,11 +222,9 @@ Pages in the Getting started, Patterns & verification, and Configuration nav gro
 - `prompt-example` anchors live in `natural-blocks.md` by default (`basic-binding`, `fstring-injection`, `local-function-signature`, `global-function-reference`). Exception: `carry-pattern` lives in `patterns.md` (cross-block composition). Test file: `tests/docs/test_prompt_examples.py`.
 - `for-coding-agents.md` operational examples and core doctrine are guarded by `tests/docs/test_coding_agent_examples.py`. Update the tests when changing executable guidance or non-negotiable rules.
 - When a docs change invalidates an existing test, first decide whether the docs or the test is the canonical truth for that claim, then update both sides to match.
-- Docs architecture regression tests (`tests/docs/test_docs_architecture.py`):
-  - Fail on stale references to deleted/renamed docs (`guide.md`, `design.md`, `providers.md`).
-  - Guard the canonical example relationship between `index.md` and `README.md` via fenced-code-block extraction + normalized exact match.
-  - Guard selected canonical-owner expectations where drift is likely.
-  - Automate `mkdocs.yml` nav entries vs `docs/` file existence as a pytest case.
-  - Guard that obsolete canonical pages do not remain published accidentally alongside their replacements.
+- `tests/docs/test_integrity.py` checks the shared README/index example, navigation targets, and explicit API member inventories.
+- `tests/docs/test_links.py` builds the published site and checks internal links and anchors against rendered HTML, including absolute links to this documentation site.
+- `tests/docs/test_runtime_examples.py` executes marked examples from runtime configuration, embedded execution, and verification, including against the installed wheel.
+- Test current links and executable claims; do not maintain lists of obsolete API names, document paths, or exact governance prose.
 - `mkdocs build` must succeed without `--strict`. Warnings are acceptable.
 - All internal relative links must resolve.

nighthawk_python-0.15.0/.claude/rules/evals.md

@@ -0,0 +1,10 @@
+---
+paths:
+  - "evals/**"
+---
+
+# Evaluations
+
+- Comments and docstrings: follow `.claude/rules/python.md`.
+- Under `evals/promptfoo/`, follow `.claude/rules/promptfoo.md`.
+- Files under `evals/*/evidence/` are dated records. Exclude them from comment cleanups and do not rewrite them.

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/.claude/rules/promptfoo.md

@@ -58,7 +58,7 @@ Eval prompts are experimental copies of production code. Keep them in sync; dive
 | `evals/promptfoo/prompts/eval_default.txt` | `configuration.py:DEFAULT_STEP_SYSTEM_PROMPT_TEMPLATE` |
 | `evals/promptfoo/prompts/eval_coding_agent.txt` | No single counterpart; coding agent backends receive this prompt via `system_prompt_file` config. |
 | Suffix variants in `evals/promptfoo/provider.py` (`_build_suffix_*`) | `step_contract.py:build_step_system_prompt_suffix_fragment` |
-| Tool presets in `evals/promptfoo/provider.py` (`_build_tool_preset`) | `tools/registry.py` + `tools/assignment.py` |
+| Tool presets in `evals/promptfoo/provider.py` (`_build_tool_preset`) | `tools/provided.py` (names and descriptions) + `tools/declarations.py` (registration) |
 
 ## Eval evidence
 

nighthawk_python-0.15.0/.claude/rules/python.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Comments and docstrings
+
+Write a comment or docstring only for a fact that the code, names, signatures, types, specification, and tests do not convey.
+
+## Write
+
+- Why a choice was made, especially an intentionally non-obvious one.
+- Upstream library behavior that the code depends on or works around.
+- Platform, process, or environment constraints.
+- Concurrency, cancellation, ordering, and lifetime invariants.
+
+## Do not write
+
+- Restatements of what the code does, including step-by-step narration.
+- Section dividers or heading comments; group code with classes, modules, or name prefixes instead.
+- Planning Ids, phases, or history ("used to", "now").
+- Citations of specification section numbers or test file paths; tests pin specified behavior.
+- Type information already present in annotations.
+
+## Form
+
+- Keep each comment and docstring compact; prefer one line.
+- Use semantic line breaks.
+
+## Text that is not a comment
+
+The following text is consumed at runtime or serves as test data.
+Change it only as a deliberate behavior change:
+
+- Natural docstrings (`"""natural ...`).
+- Docstrings of binding functions and tools, which LLMs may read.
+- Docstrings of Pydantic models that enter LLM-facing JSON schemas, such as `StepFinalResult`.
+- Fixture docstrings that tests assert on or expose to Natural blocks.
+
+Tool directives (`noqa`, `type: ignore`, `pyright: ignore`) are outside these rules.

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/.claude/rules/src.md

@@ -7,11 +7,19 @@ paths:
 
 - Prefer concrete code. Add a new abstraction only when the same change uses it from non-test code.
 - Default to module-private names. Export via `__all__` only for stable non-test consumers.
-- If a change expands or changes public API, update or confirm `tests/public/`.
+- If a change expands or changes public API, update the behavior owner tests and confirm export resolution in `tests/test_public_api.py`.
 - Prefer async implementations in `runtime/` and `backends/`; keep sync bridges only at compatibility boundaries.
 - Reuse the existing `NighthawkError` hierarchy before adding a new exception class.
 - Prefer Pydantic (`BaseModel`, `TypeAdapter`) and Pydantic AI primitives over custom validation, parsing, schema, or agent/tool plumbing.
 - Use `opentelemetry.trace` spans at run/scope/step/tool boundaries and `logging.getLogger("nighthawk")` for diagnostics. Do not import `logfire` in `src/`.
 - Use PEP 695 `type` statements for new type aliases.
 - Ask before adding a new `src/` subpackage for a single module.
-- Follow `CONTRIBUTING.md` § Docstring Guide for docstring scope and format.
+
+## Comments and docstrings
+
+Follow `.claude/rules/python.md`. Additionally:
+
+- Public API means the objects rendered by `docs/api.md`. Follow `CONTRIBUTING.md` "Docstring Guide" for their format.
+- Keep examples in `docs/`, not in docstrings.
+- Write an internal docstring only for a fact the code does not convey; otherwise omit it.
+- Write a module docstring only when it states a responsibility boundary that the module name does not convey.

nighthawk_python-0.15.0/.claude/rules/tests.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "tests/**"
+---
+
+# Testing (pytest)
+
+- Prefer deterministic pytest coverage by default. Use helpers from `nighthawk.testing` before reaching for live LLM calls.
+- Use `StubExecutor` from `tests/support/executors.py` only for envelope and runtime parser checks; prefer `nighthawk.testing` for normal Natural-function tests.
+- Keep live-LLM tests in `tests/integration/` and behind the documented environment gates.
+- For Python behavior changes, add or update pytest coverage in the same change and run `uv run pytest -q`.
+- If a change affects public API or README examples, update the behavior owner tests and confirm `tests/test_public_api.py`. If it affects docs examples or anchors, confirm `tests/docs/`.
+- If a change affects prompt rendering, system prompt text, suffix generation, or tool exposure behavior, follow `.claude/rules/promptfoo.md`.
+
+## Comments and docstrings
+
+Follow `.claude/rules/python.md`. Additionally:
+
+- Group tests with test classes or test name prefixes, not divider comments.
+- Write a test docstring only for a non-obvious reason, such as pinned upstream behavior.
+- Write a module docstring only for an operational fact that `tests/README.md` does not document.

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/.github/workflows/ci.yml

@@ -19,13 +19,17 @@ jobs:
     name: Lint and type check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # setup-uv publishes no floating major tag since v8, so pin an exact release.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           python-version: "3.13"
+          # Same dependency set and cache key as "test (3.13)". Only that job
+          # saves the entry; concurrent writers race to reserve the same key.
+          save-cache: false
 
       - name: Install dependencies
         run: uv sync --all-extras --all-groups
@@ -48,11 +52,12 @@ jobs:
         python-version: ["3.13", "3.14"]
     continue-on-error: ${{ matrix.python-version != '3.13' }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # Sole writer of the per-Python-version dependency cache.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -67,15 +72,27 @@ jobs:
     needs: [lint, test]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # Keep packaging and its fresh installation check independent of the
+      # source test job's dependency cache.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: false
 
       - name: Build sdist and wheel
         run: uv build
 
+      - name: Verify documented examples against the installed wheel
+        run: |
+          uv sync --all-groups
+          uv venv "$RUNNER_TEMP/nighthawk-distribution"
+          uv pip install --python "$RUNNER_TEMP/nighthawk-distribution/bin/python" dist/*.whl
+          NIGHTHAWK_DISTRIBUTION_PYTHON="$RUNNER_TEMP/nighthawk-distribution/bin/python" \
+            uv run pytest -q tests/docs/test_runtime_examples.py
+
       - name: Upload distribution artifacts
         uses: actions/upload-artifact@v6
         with:

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/.github/workflows/docs.yml

@@ -24,9 +24,15 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
-      - uses: astral-sh/setup-uv@v7
+      # setup-uv publishes no floating major tag since v8, so pin an exact release.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+          # The docs group is a subset of the cache "test (3.13)" saves under
+          # this key, so restore it here but never overwrite it.
+          save-cache: false
 
       - name: Install dependencies
         run: uv sync --group docs

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/.github/workflows/publish.yml

@@ -24,7 +24,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifacts
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: python-package-distributions
           path: dist/

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/.gitignore

@@ -8,6 +8,7 @@ evals/promptfoo/outputs/
 evals/promptfoo/*.json
 evals/promptfoo/*.html
 evals/promptfoo/*.csv
+evals/model_tools/outputs/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -224,4 +225,4 @@ marimo/_lsp/
 __marimo__/
 
 # Streamlit
-.streamlit/secrets.toml
+.streamlit/secrets.toml

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/AGENTS.md

@@ -17,6 +17,8 @@
 
 ### Rules
 
+- 改行 (line wrapping) は fixed column で hard-wrap しない.
+  - User が column 上限を明示しない限り, 文末 / clause 区切り / list item など意味の区切りでのみ改行する (semantic line break).
 - Use full words in all identifiers unless listed above.
 - Disallowed abbreviations: `ctx` -> `context`, `cfg` -> `configuration`, `repo` -> `repository`, `opts` -> `options`, `ref` -> `reference`.
 - Map/Dict: `(adjective + "_")* + key + "_to_" + value`.
@@ -33,14 +35,14 @@ A Python 3.13+ library embedding a "Natural" DSL inside Python functions, execut
 
 Natural DSL sources and included markdown are trusted, repository-managed assets. Do not wire untrusted user input into Natural blocks or template preprocessing.
 
-### Repository layout
+ExecPlans: write under `.agents/execplans/` only on request; follow `.agents/PLANS.md`.
 
-- `src/nighthawk/`: Library package.
-- `tests/`: Pytest suite.
-- `docs/`: User-facing documentation (MkDocs).
-- `.agents/`: `execplans/` (on request only), `PLANS.md` (format spec).
-- `.devcontainer/`: Devcontainer definition.
-- `pyproject.toml`, `uv.lock`: Metadata and locked dependencies.
+### Design references
+
+- Read [Philosophy](docs/philosophy.md) when making architectural decisions about function composition, Python integration, agent authorship, accumulated capability, or Core responsibility.
+- Read [Design drivers](docs/design-drivers.md) when using application requirements to justify Core changes or deciding which information belongs in this workspace.
+- Use [Specification](docs/specification.md) for supported behavior and [Roadmap](docs/roadmap.md) for exploratory directions; application scenarios do not establish runtime guarantees.
+- Treat Nighthawk-based development tooling as an application; its presence here does not make it a public library feature.
 
 ## Development workflow
 

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/CHANGELOG.md

@@ -7,6 +7,113 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0]
+
+### Added
+
+- Immutable `StepDefinition` declarations and synchronous/asynchronous embedded step execution use explicit host namespaces and keep validated writeback inside the ordinary lifecycle boundary.
+- Shared binding inference and ordered validation expose `MISSING_ANNOTATION` and structured binding errors through `nighthawk.runtime`.
+
+- Exact Natural definition lookup, optional whole-function call handlers, inert function model declarations, and preserving executor model resolution.
+
+- `StepEnvironment` separates Python lexical bindings, inherited working state, scoped task references, and tracked step assignments, with source-qualified lookup and progressing discovery.
+- Replaceable `ContextBuilder` presentation and shared static value inspection preserve application helper-name collisions and complete discovery continuations, including pages nested in ordinary containers.
+- Common operation admission, awaited inspection, serialized execution, and completion records cover evaluation, assignment, return-expression resolution, and native tools. Failed tool argument admission retains its identity and original exception.
+- Lifecycle start and operation notifications support asynchronous handlers alongside terminal delivery.
+- `ExecutionReference.parent_step_execution_id` correlates joined child steps with their active parent.
+
+### Changed
+
+- Breaking: `ScriptedExecutor` records and rejects unexpected invocations after its response sequence is exhausted. Supply an explicit `default_response=pass_response()` or another response when repetition is intended.
+
+- Breaking: deterministic test responses use resolved `StepResult` values. Replace `return_response("'bug'")` with `return_response("bug")`, `return_response("result", result=42)` with `return_response(42, result=42)`, and `raise_response("failed", error_type="ValueError")` with `raise_response("failed", error_type=ValueError)`. Direct `StepResponse` construction uses `Return(value)`, `Raise(message, error_type)`, `Pass()`, `Break()`, or `Continue()` from `nighthawk.runtime`; strings are never evaluated as expressions.
+
+- Refreshed locked dependencies, including Pydantic 2.14.1, OpenAI 3.31.0, MCP 2.3.0, and Logfire 5.2.0.
+- `task_references` replaces `implicit_references`. Injection remains separate from Python module globals.
+- Executors accept one `StepRequest` and return a resolved `StepCandidate`. Finalization validates all initialized declared outputs, rejects undeclared proposals, and independently validates return values. An initial `Raise` discards pending writes.
+- Commit rewrites validate supplied replacements once without repeating inspection or expression effects; supplied output mappings replace the full selected mapping.
+- Dotted assignment requires an ordinary Pydantic field with `validate_assignment=True`. Right-hand-side evaluation precedes live attribute traversal, and earlier effects are not rolled back on failure.
+- Ordinary application and propagated validator exceptions cross model and backend boundaries unchanged. Runtime input errors and explicit Pydantic AI control signals retain their recovery paths.
+- `Oversight.inspect_operation` replaces both tool-call and return-expression inspection hooks with one `OperationRequest` boundary.
+- Output contracts use supported explicit annotations before initial-value inference; unresolved required annotations fail preparation rather than weakening validation.
+- Lexical support is bounded to source-available functions, live defining-module globals, and existing closure cells, including declared global/nonlocal output writeback. Natural text alone does not capture an otherwise inaccessible outer variable. Parent-state inheritance covers joined child calls; deferred generated expressions and children that outlive their parent have no lifetime guarantee.
+- Integrated Natural execution contracts into the specification and usage guides, with practical parent/child examples and explicit validation, inheritance, and host-delivery boundaries. The README and landing-page example now demonstrate typed output validation.
+- Reframed the philosophy around AI agents building, composing, evaluating, and improving reusable capabilities through Python and Natural, with a compact statement of purpose and Core inclusion criteria.
+- Expanded design drivers with capability construction and reuse scenarios, success conditions, comparisons against ordinary Python and model libraries, and evidence-based decisions about guidance, reusable libraries, simplification, or Core changes.
+
+### Fixed
+
+- Dynamic annotation validation uses explicit `TypeForm[object]` casts at Pydantic `TypeAdapter` boundaries, restoring type-checking compatibility with Pydantic 2.14 without changing runtime validation. Declared `typing-extensions` as a direct dependency.
+- Error-handling guides distinguish Natural-selected exceptions, recoverable tool errors, and finalization failures. Published handlers are executed against deterministic runtime responses.
+- Tests follow environment, prompt, executor, and model-selection ownership; scope tests use current composition terminology and avoid duplicate replacement checks or fixed instrumentation names.
+
+- `run()` and `scope()` reject invalid executor objects before changing the active execution context.
+- Tool-return content projection receives an explicit rendering policy; MCP discovery content respects the caller's selected policy.
+- Verification guidance captures actual model request messages instead of claiming full-prompt DEBUG logging. Published internal links and anchors are checked against the rendered MkDocs site.
+
+- Source instrumentation retains defaults, live closure cells and globals, Python unbound-name behavior, and application names that resemble generated helpers.
+- Variadic output bindings validate their tuple or dictionary elements, preserving `Annotated` constraints and unpacked collection contracts.
+- Python 3.14 callable descriptions recover source annotation spelling without invoking deferred evaluators. Natural decoration preserves deferred annotations, and global-output preparation obtains deferred module contracts.
+- Ordered model tool batches and coding-agent callbacks preserve per-step operation order and stop after terminal operation failure.
+- Native model batches also order argument validation before each corresponding body, preventing later validators from running ahead of an earlier rejection. A scoped Pydantic AI 2.37 compatibility adapter preserves its completion strategies; the dependency range is bounded to that minor series.
+- Coding-agent callbacks use the request's event loop and captured scope; process and transport failures preserve their originating exceptions.
+- Interrupted asynchronous notifications and synchronous bridge shutdown wait for actual owned cleanup completion. `interruption_delivery_timeout` requests notification cancellation but no longer bounds total cleanup time, including handlers that suppress cancellation.
+- Bridge startup interruption joins already launched workers, and asynchronous generator shutdown failures remain inspectable in the propagated exception chain.
+- Caller interruption and notification timeouts preserve cleanup that a notification has already entered through its own cancellation.
+- Synchronous bridge interruption also preserves a root task's existing cancellation cleanup, including its final effects and exception chain.
+- Rejected synchronous DSL returns preserve borrowed application coroutines; only Core-created unstarted await wrappers are disposed.
+
+### Removed
+
+- Unused public `ToolEvaluationError` and `ToolValidationError` classes. Handle finalization failures through `ExecutionError`, independent binding validation through `BindingValidationError`, and application exceptions by their original types; recoverable model tool failures remain structured observations.
+- `scope(implicit_references=...)` and `get_implicit_references()`; use scoped task references and the active step environment.
+- `Oversight.inspect_tool_call`, `Oversight.inspect_return_expression`, and the associated `ToolCall`, `ToolCallDecision`, and `ReturnExpression` types.
+- `Rewrite.return_value`; replace a return through `Rewrite.outcome`.
+- The executor protocol's separate program, context, binding, and control arguments and outcome/bindings tuple result; use `StepRequest` and `StepCandidate`.
+
+### Migration notes for hosts
+
+These changes apply after 0.14.0; earlier release sections describe their own APIs.
+The removed entry points have no compatibility aliases.
+
+| Before | After |
+| --- | --- |
+| `nh.scope(implicit_references=task_name_to_value)` | `nh.scope(task_references=task_name_to_value)`; task injection no longer overrides Python globals. Omission, `UNSET`, replacement, and `Merge` keep their composition roles. |
+| `nh.get_implicit_references()` | During a step, use `nh.get_step_context().environment.task_name_to_value`. Outside a step, retain the task mapping supplied by the host; there is no run-only replacement getter. |
+| `inspect_tool_call(ToolCall)` / `inspect_return_expression(ReturnExpression)` | Install `inspect_operation(operation: OperationRequest)`, returning `Accept` or `Reject`, directly or asynchronously. Inspect `operation.kind` and the applicable expression/tool fields; ordinary helper calls through evaluation have kind `"evaluation"`. |
+| `ToolCallDecision` | Use `Accept` or `Reject` for operation decisions; `StepCommitDecision` additionally permits `Rewrite`. |
+| `Rewrite(return_value=value)` | `Rewrite(outcome=Return(value))`, importing `Return` from `nighthawk.runtime`. Use `Return(None)` for an explicit `None`, subject to the return contract. |
+| `run_step(...)` / `run_step_async(...)` with separate boundary arguments and a tuple result | Accept keyword-only `request: StepRequest` and return `StepCandidate(outcome=..., binding_name_to_value=...)`. Import both types and resolved outcomes from `nighthawk.runtime`; read live values through `request.step_context.environment`. |
+| An outer value mentioned only in Natural text | Pass it explicitly, establish an existing cell with a valid `nonlocal` declaration, or inject a task reference. |
+
+Custom executors still pass through mandatory finalization.
+Ordinary helper exceptions now propagate to Python; return a domain observation when an expected failure should be handled by the model.
+See the [executor contract](docs/specification.md#14-step-executor), [environment boundaries](docs/specification.md#81-state-layers-python-locals-and-step-locals), and [host configuration guide](docs/runtime-configuration.md#oversight-in-scopes) for complete semantics.
+
+## [0.14.0]
+
+### Added
+
+- Scoped `nh.lifecycle.StepLifecycle` delivers typed completion, DSL raise, failure, or interruption records after generated caller assignments. Hosts can record one terminal event and translate failures with explicit exception chaining.
+- `Oversight.inspect_return_expression` approves expressions before core evaluation, await, and return validation.
+- `StepDeliveryError` supports host storage adapters without claiming persistence succeeded.
+
+### Changed
+
+- `ExecutionReference` and `get_execution_reference` replace the abbreviated identity API. `step_execution_id` identifies each invocation; `source_location` identifies its source. StepContext, inspection, testing observations, terminal records, and spans share this identity.
+- Runtime internal exceptions, including preparation and await failures, now propagate through `ExecutionError.step_failed` with the original exception as cause. Rejection is a classified failure. DSL exceptions remain distinct.
+- Completion tracing follows actual caller assignments. Cancellation retains priority if terminal delivery fails. Delivery errors never retry execution or undo effects.
+- Natural functions preserve original closure cells for nonlocal assignments and source locations for generated execution.
+
+### Fixed
+
+- Lifecycle handlers can rethrow an already-recorded host exception or interruption without replacing its original cause with a self-reference.
+- Host integration guidance distinguishes one delivery attempt from ledger deduplication and explains the validation, await, and rewrite limits of name-only return approval.
+
+### Removed
+
+- `ExecutionRef`, `get_execution_ref`, and `step_id`, without compatibility aliases. Span attributes use `step.execution.id` and `step.source_location`.
+
 ## [0.13.0]
 
 ### Added
@@ -240,7 +347,9 @@ Invalid initial results fail before oversight; use resilience retries to recover
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.13.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.12.0...v0.13.0
 [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

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/CONTRIBUTING.md

@@ -45,15 +45,29 @@ uv run pyright
 uv run pytest -q       # quiet output
 ```
 
+Test ownership and helper conventions are documented in [tests/README.md](tests/README.md).
+
+### Design and application evidence
+
+Use [Philosophy](docs/philosophy.md) for design principles and [Specification](docs/specification.md) for supported runtime contracts.
+[Design drivers](docs/design-drivers.md) defines which application information belongs in this workspace and how to distinguish conceptual scenarios from verified behavior.
+When proposing Core changes, show the application composition that exposes the general execution need.
+Nighthawk-based development checks are an application of the library; adopting a local check does not make it a public feature or a requirement for library users.
+
 ### Integration tests
 
 The full setup command installs the OpenAI provider development dependency.
-Run integration tests with your `.env` loaded:
+Integration tests are opt-in; loading credentials alone does not enable them.
+Run OpenAI integration tests with your `.env` loaded:
 
 ```bash
-set -a; source .env; set +a; uv run pytest -q
+NIGHTHAWK_OPENAI_INTEGRATION_TESTS=1 uv run --env-file .env pytest -q tests/integration/
 ```
 
+Add `NIGHTHAWK_OPENAI_MULTIMODAL_INTEGRATION_TESTS=1` to include the image cases.
+Coding agent tests use their respective flags: `NIGHTHAWK_CODEX_INTEGRATION_TESTS=1`, `NIGHTHAWK_CLAUDE_SDK_INTEGRATION_TESTS=1`, or `NIGHTHAWK_CLAUDE_CLI_INTEGRATION_TESTS=1`.
+Their executables and authentication must be available in the test environment.
+
 ### Trace inspection with otel-tui
 
 Nighthawk emits OpenTelemetry traces for step execution. You can inspect them
@@ -130,15 +144,10 @@ Use [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-
 
 ### Scope
 
-Write docstrings only for public API members exported via `__all__` in `src/nighthawk/__init__.py`, plus public classes and functions in these modules:
+This guide covers the public API: the objects rendered by `docs/api.md`.
 
-- `nighthawk.errors`
-- `nighthawk.configuration`
-- `nighthawk.backends.claude_code_sdk`
-- `nighthawk.backends.claude_code_cli`
-- `nighthawk.backends.codex`
-
-Do not write docstrings for names prefixed with `_` (module-private).
+Other docstrings, including those for names prefixed with `_`, are written only for facts the code does not convey and stay compact.
+See `.claude/rules/python.md` for the rules that apply to all comments and docstrings.
 
 ### Structure
 
@@ -153,7 +162,8 @@ Required. Use imperative mood ("Return ...", "Start ...", "Register ..."). Keep
 | `Args` | One or more parameters exist. Do not repeat type information already present in annotations. |
 | `Returns` / `Yields` | Return value is not `None`, or carries meaning that is not obvious from the type alone. |
 | `Raises` | The function raises exceptions that callers are expected to catch. |
-| `Example` | Required for decorators (`natural_function`, `tool`) and context managers (`run`, `scope`). Optional for everything else. |
+
+Do not add an `Example` section; examples live in `docs/`.
 
 #### Classes
 
@@ -196,19 +206,7 @@ def run(
         run_id: Optional identifier for the run. If not provided, a ULID is
             generated automatically.
 
-    Yields:
-        None
-
     Raises:
         RuntimeError: If called while another run is already active.
-
-    Example:
-        ```python
-        executor = AgentStepExecutor.from_configuration(
-            configuration=StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"),
-        )
-        with nighthawk.run(executor):
-            result = my_natural_function()
-        ```
     """
 ```

{nighthawk_python-0.13.0 → nighthawk_python-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.13.0
+Version: 0.15.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,7 +20,7 @@ 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>=2.37.0
+Requires-Dist: pydantic-ai-slim<2.38,>=2.37.0
 Requires-Dist: pydantic>=2.13.3
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: tenacity>=9.1.4
@@ -44,14 +44,11 @@ Description-Content-Type: text/markdown
 <img src="https://github.com/kurusugawa-computer/nighthawk-python/raw/main/docs/assets/nighthawk_logo-128x128.png" alt="nighthawk-logo" width="128px" margin="10px"></img>
 </div>
 
-Nighthawk is a Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
+Nighthawk is a Python library that makes natural-language judgment composable with ordinary Python functions.
 
-- **Hard control** (Python code): strict procedure, verification, and deterministic flow.
-- **Soft reasoning** (an LLM or coding agent): semantic interpretation inside small embedded "Natural blocks".
-
-The same mechanism handles lightweight LLM judgments ("classify this sentiment") and autonomous agent executions ("refactor this module and write tests"). See **[Philosophy](https://kurusugawa-computer.github.io/nighthawk-python/philosophy/)** for the full design rationale.
-
-This repository is a compact reimplementation of the core ideas of [Nightjar](https://github.com/psg-mit/nightjarpy).
+Use Natural blocks for interpretation, classification, and other judgments; combine actions, constraints, and verification through Python functions and existing libraries.
+Python owns the surrounding control flow, state, and recovery.
+The same typed boundaries support provider-backed LLM calls and coding-agent executions.
 
 ## Installation
 
@@ -69,7 +66,7 @@ For other providers, see [Pydantic AI providers](https://kurusugawa-computer.git
 import nighthawk as nh
 
 
-def python_average(numbers):
+def python_average(numbers: list[float]) -> float:
     return sum(numbers) / len(numbers)
 
 
@@ -78,38 +75,39 @@ step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExe
 with nh.run(step_executor):
 
     @nh.natural_function
-    def calculate_average(numbers):
+    def calculate_average(numbers: list[object]) -> float:
+        result: float = 0.0
         """natural
         Map each element of <numbers> to the number it represents,
         then compute <:result> by calling <python_average> with the mapped list.
         """
         return result
 
-    calculate_average([1, "2", "three", "cuatro"])  # 2.5
+    print(calculate_average([1, "2", "three", "cuatro"]))  # 2.5
 ```
 
+Natural interprets the mixed representations, `python_average` performs the deterministic calculation, and the output binding validates `result` as a `float` before Python resumes.
+Type validation constrains the result's shape; it does not prove the interpretation is correct.
+
 See the **[Quickstart](https://kurusugawa-computer.github.io/nighthawk-python/quickstart/)** for setup details, credentials, and troubleshooting.
 
+## Embedding in an application
+
+Hosts can admit whole function calls, select models without losing scoped controls, and observe block outcomes and model usage.
+See [Runtime configuration](https://kurusugawa-computer.github.io/nighthawk-python/runtime-configuration/) for usage and [execution boundaries](https://kurusugawa-computer.github.io/nighthawk-python/specification/#embedded-execution-boundaries) for the guarantees.
+The [runtime configuration guide](https://kurusugawa-computer.github.io/nighthawk-python/runtime-configuration/#whole-function-admission) includes executable host-integration examples that run without credentials.
+
 ## Documentation
 
-- **[Quickstart](https://kurusugawa-computer.github.io/nighthawk-python/quickstart/)** -- Setup and first example.
-- **[Natural blocks](https://kurusugawa-computer.github.io/nighthawk-python/natural-blocks/)** -- Block anatomy, bindings, functions, and writing guidelines.
-- **[Executors](https://kurusugawa-computer.github.io/nighthawk-python/executors/)** -- Choose an execution backend.
-- **[Runtime configuration](https://kurusugawa-computer.github.io/nighthawk-python/runtime-configuration/)** -- Scoping, patching, context limits, and execution identity.
-- **[Patterns](https://kurusugawa-computer.github.io/nighthawk-python/patterns/)** -- Outcomes, async, composition, resilience, and common mistakes.
-- **[Verification](https://kurusugawa-computer.github.io/nighthawk-python/verification/)** -- Mock tests, integration tests, and OpenTelemetry tracing.
-- **[Pydantic AI providers](https://kurusugawa-computer.github.io/nighthawk-python/pydantic-ai-providers/)** -- LLM provider configuration.
-- **[Coding agent backends](https://kurusugawa-computer.github.io/nighthawk-python/coding-agent-backends/)** -- Claude Code and Codex integration.
-- **[Specification](https://kurusugawa-computer.github.io/nighthawk-python/specification/)** -- Canonical specification.
-- **[API Reference](https://kurusugawa-computer.github.io/nighthawk-python/api/)** -- Auto-generated API documentation.
-- **[For coding agents](https://kurusugawa-computer.github.io/nighthawk-python/for-coding-agents/)** -- Development guide for coding agents (LLMs) building Python projects with Nighthawk.
-- **[Philosophy](https://kurusugawa-computer.github.io/nighthawk-python/philosophy/)** -- Design rationale and positioning.
-- **[Roadmap](https://kurusugawa-computer.github.io/nighthawk-python/roadmap/)** -- Future directions.
+- [Quickstart](https://kurusugawa-computer.github.io/nighthawk-python/quickstart/) -- Install and run a Natural function.
+- [Natural blocks](https://kurusugawa-computer.github.io/nighthawk-python/natural-blocks/) -- Design prompts, bindings, and Python helpers.
+- [Patterns](https://kurusugawa-computer.github.io/nighthawk-python/patterns/) and [Verification](https://kurusugawa-computer.github.io/nighthawk-python/verification/) -- Compose, test, and debug workflows.
+- [Specification](https://kurusugawa-computer.github.io/nighthawk-python/specification/) and [API reference](https://kurusugawa-computer.github.io/nighthawk-python/api/) -- Runtime contracts and public interfaces.
+- [For coding agents](https://kurusugawa-computer.github.io/nighthawk-python/for-coding-agents/) -- A compact operational guide.
+- [Philosophy](https://kurusugawa-computer.github.io/nighthawk-python/philosophy/) and [Design drivers](https://kurusugawa-computer.github.io/nighthawk-python/design-drivers/) -- Principles, application needs, and Core responsibility.
 
 ## Development & Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, development commands, and contribution guidelines.
 
-## References
-
-- Nightjar (upstream concept): https://github.com/psg-mit/nightjarpy
+Inspired by [Nightjar](https://github.com/psg-mit/nightjarpy).