nighthawk-python 0.2.0__tar.gz → 0.3.0__tar.gz

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/.claude/rules/docs.md

@@ -91,6 +91,8 @@ 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.
+- 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.0/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "pyright-lsp@claude-plugins-official": true
+  }
+}

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-18
+
+### Added
+- `system_prompt_suffix_fragment_scope` and `user_prompt_suffix_fragment_scope` context managers for lightweight prompt fragment management without full scope overhead.
+- OpenTelemetry tracer now reports `instrumenting_library_version`.
+
+### Changed
+- Simplified OpenTelemetry span hierarchy: removed implicit `nighthawk.scope` spans and `nighthawk.step_executor` spans. `nighthawk.scope` spans are now emitted only for explicit `nh.scope()` calls.
+- `nighthawk.run` span no longer includes `scope.id` attribute; only `run.id` is emitted.
+- Trimmed `for-coding-agents.md` for coding-agent relevance: removed deprecated `@nh.tool` references, condensed exception hierarchy, scoped overrides, and added debugging context to `StepContextLimits`.
+
 ## [0.2.0] - 2026-03-16
 
 ### Added
@@ -30,6 +41,7 @@ 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.2.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.0...HEAD
+[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
 [0.1.0]: https://github.com/kurusugawa-computer/nighthawk-python/tree/v0.1.0

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/CONTRIBUTING.md

@@ -53,6 +53,23 @@ Then run with your `.env` loaded:
 set -a; source .env; set +a; uv run pytest -q
 ```
 
+### Trace inspection with otel-tui
+
+Nighthawk emits OpenTelemetry traces for step execution. You can inspect them
+locally using [otel-tui](https://github.com/ymtdzzz/otel-tui):
+
+```bash
+docker run --rm -it -p 4318:4318 --name otel-tui ymtdzzz/otel-tui:latest
+```
+
+Then run integration tests with the collector endpoint:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 uv run pytest -q tests/integration/
+```
+
+Traces appear in the otel-tui terminal UI in real time.
+
 ### Environment variables
 
 - `OPENAI_API_KEY`: Required for OpenAI integration tests (also requires `pydantic-ai-slim[openai]`).

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.2.0
+Version: 0.3.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.2.0 → nighthawk_python-0.3.0}/docs/for-coding-agents.md

@@ -64,10 +64,6 @@ Each Natural block should make exactly one independent judgment. If a block make
 
 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:`.
 
-### Prefer binding functions over `@nh.tool`
-
-`@nh.tool` is reserved strictly for cases requiring `RunContext[StepContext]` access. Binding functions incur no per-definition token overhead beyond a signature line. Always use binding functions unless `RunContext` access is needed.
-
 ### Keep locals minimal
 
 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.
@@ -156,11 +152,7 @@ except nh.ExecutionError as e:
     print(f"Validation failed: {e}")
 ```
 
-Custom exception types referenced in step locals or globals are available as raise targets.
-
-### Exception hierarchy
-
-All exceptions inherit from `NighthawkError`: `ExecutionError`, `NaturalParseError`, `ToolEvaluationError`, `ToolValidationError`, `ToolRegistrationError`.
+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
 
@@ -221,30 +213,9 @@ with nh.run(step_executor):
     result = my_natural_function(data)
 ```
 
-### Scoped overrides
-
-Use `nh.scope()` to override execution settings within an existing run. Each scope generates a new `scope_id` while keeping the current `run_id`.
-
-Parameters:
-
-- `step_executor_configuration`: replace the entire configuration.
-- `step_executor_configuration_patch`: partially override specific fields.
-- `step_executor`: replace the step executor entirely.
-- `system_prompt_suffix_fragment`: append text to the system prompt for the scope.
-- `user_prompt_suffix_fragment`: append text to the user prompt for the scope.
-
-```python
-with nh.scope(
-    step_executor_configuration_patch=nh.StepExecutorConfigurationPatch(
-        model="openai-responses:gpt-5-mini",
-    ),
-):
-    expensive_analysis(data)
-```
-
-### Context limits
+Use `nh.scope()` to override model, prompts, or context limits within an existing run. For details, see [Tutorial](https://kurusugawa-computer.github.io/nighthawk-python/tutorial/).
 
-LOCALS and GLOBALS sections are bounded by `StepContextLimits`. Configure via `StepExecutorConfiguration`:
+LOCALS and GLOBALS sections are bounded by `StepContextLimits`. When bindings are missing or truncated (`<snipped>`), adjust the limits:
 
 ```python
 configuration = nh.StepExecutorConfiguration(
@@ -304,7 +275,6 @@ def judge_review(review_data: str | nh.JsonableValue) -> ReviewVerdict:
 | 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 |
-| Use `@nh.tool` when a binding function suffices | Unnecessary per-definition token overhead | Use binding functions; reserve `@nh.tool` for `RunContext[StepContext]` access |
 | 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 |
 

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.2.0"
+version = "0.3.0"
 description = "An experimental Python library that embeds Natural blocks inside Python functions and executes them using an LLM."
 readme = "README.md"
 requires-python = ">=3.13"

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/src/nighthawk/runtime/scoping.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import importlib.metadata
 import uuid
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -36,7 +37,9 @@ STEP_ID = "step.id"
 TOOL_CALL_ID = "tool_call.id"
 
 
-_tracer = get_tracer_provider().get_tracer("nighthawk")
+_LIBRARY_VERSION = importlib.metadata.version("nighthawk-python")
+
+_tracer = get_tracer_provider().get_tracer("nighthawk", _LIBRARY_VERSION)
 
 
 @contextmanager
@@ -108,6 +111,26 @@ def get_user_prompt_suffix_fragments() -> tuple[str, ...]:
     return _user_prompt_suffix_fragments_var.get()
 
 
+@contextmanager
+def system_prompt_suffix_fragment_scope(fragment: str) -> Iterator[None]:
+    current = _system_prompt_suffix_fragments_var.get()
+    token = _system_prompt_suffix_fragments_var.set((*current, fragment))
+    try:
+        yield
+    finally:
+        _system_prompt_suffix_fragments_var.reset(token)
+
+
+@contextmanager
+def user_prompt_suffix_fragment_scope(fragment: str) -> Iterator[None]:
+    current = _user_prompt_suffix_fragments_var.get()
+    token = _user_prompt_suffix_fragments_var.set((*current, fragment))
+    try:
+        yield
+    finally:
+        _user_prompt_suffix_fragments_var.reset(token)
+
+
 def _resolve_agent_step_executor(step_executor: StepExecutor) -> AgentStepExecutor:
     from .step_executor import AgentStepExecutor
 
@@ -179,7 +202,6 @@ def run(
                 "nighthawk.run",
                 **{
                     RUN_ID: execution_context.run_id,
-                    SCOPE_ID: execution_context.scope_id,
                 },
             ):
                 yield

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/src/nighthawk/runtime/step_executor.py

@@ -13,13 +13,8 @@ from ..tools.registry import get_visible_tools
 from .async_bridge import run_coroutine_synchronously
 from .prompt import build_user_prompt, extract_references_and_program
 from .scoping import (
-    RUN_ID,
-    SCOPE_ID,
-    STEP_ID,
-    get_execution_context,
     get_system_prompt_suffix_fragments,
-    scope,
-    span,
+    system_prompt_suffix_fragment_scope,
 )
 from .step_context import (
     _MISSING,
@@ -315,25 +310,16 @@ class AgentStepExecutor:
             allowed_step_kinds=allowed_step_kinds,
         )
 
-        with scope(system_prompt_suffix_fragment=step_system_prompt_fragment):
-            execution_context = get_execution_context()
-            with (
-                span(
-                    "nighthawk.step_executor",
-                    **{
-                        RUN_ID: execution_context.run_id,
-                        SCOPE_ID: execution_context.scope_id,
-                        STEP_ID: step_context.step_id,
-                    },
-                ),
-                step_context_scope(step_context),
-            ):
-                result = await self._run_agent(
-                    user_prompt=user_prompt,
-                    step_context=step_context,
-                    toolset=toolset,
-                    structured_output_type=structured_output_type,
-                )
+        with (
+            system_prompt_suffix_fragment_scope(step_system_prompt_fragment),
+            step_context_scope(step_context),
+        ):
+            result = await self._run_agent(
+                user_prompt=user_prompt,
+                step_context=step_context,
+                toolset=toolset,
+                structured_output_type=structured_output_type,
+            )
 
         step_outcome = self._parse_agent_result(result)
         bindings = self._extract_bindings(binding_names=binding_names, step_context=step_context)

{nighthawk_python-0.2.0 → nighthawk_python-0.3.0}/tests/public/test_public_api.py

@@ -1,4 +1,5 @@
 import asyncio
+import importlib.metadata
 from collections.abc import Generator
 
 import pytest
@@ -26,7 +27,7 @@ def step_span_exporter() -> Generator[InMemorySpanExporter, None, None]:
     tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
 
     previous_tracer_provider = runtime_scoping._tracer
-    runtime_scoping._tracer = tracer_provider.get_tracer("nighthawk")
+    runtime_scoping._tracer = tracer_provider.get_tracer("nighthawk", importlib.metadata.version("nighthawk-python"))
     try:
         yield span_exporter
     finally:
@@ -428,3 +429,43 @@ def test_step_span_failure_event_structure_is_compact(step_span_exporter: InMemo
     assert "exception" in exception_event_name_set
     assert "nighthawk.step.failed" in exception_event_name_set
     assert len(step_span.events) == 2
+
+
+def test_run_span_has_only_run_id_attribute(step_span_exporter: InMemorySpanExporter) -> None:
+    with nh.run(StubExecutor(), run_id="attr-test"):
+
+        @nh.natural_function
+        def natural_value_function() -> int:
+            """natural
+            <:result>
+            {"step_outcome": {"kind": "pass"}, "bindings": {"result": 42}}
+            """
+            return result  # noqa: F821  # pyright: ignore[reportUndefinedVariable]
+
+        assert natural_value_function() == 42
+
+    run_span_list = [s for s in step_span_exporter.get_finished_spans() if s.name == "nighthawk.run"]
+    assert len(run_span_list) == 1
+    run_span = run_span_list[0]
+    assert _require_attribute_key_set(run_span) == {"run.id"}
+    assert _require_attribute_value(run_span, "run.id") == "attr-test"
+
+
+def test_no_implicit_scope_or_step_executor_spans(step_span_exporter: InMemorySpanExporter) -> None:
+    with nh.run(StubExecutor()):
+
+        @nh.natural_function
+        def natural_value_function() -> int:
+            """natural
+            <:result>
+            {"step_outcome": {"kind": "pass"}, "bindings": {"result": 7}}
+            """
+            return result  # noqa: F821  # pyright: ignore[reportUndefinedVariable]
+
+        assert natural_value_function() == 7
+
+    span_name_set = {s.name for s in step_span_exporter.get_finished_spans()}
+    assert "nighthawk.scope" not in span_name_set
+    assert "nighthawk.step_executor" not in span_name_set
+    assert "nighthawk.run" in span_name_set
+    assert "nighthawk.step" in span_name_set