nighthawk-python 0.7.0__tar.gz → 0.8.0__tar.gz

{nighthawk_python-0.7.0 → nighthawk_python-0.8.0}/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0]
+
+### Added
+- Unit tests covering prompt token-budget injection: system prompt resolves `$tool_result_max_tokens`, and custom user prompt templates can resolve the same placeholder.
+
+### Changed
+- Default step system prompt now states that tool result `value` is a preview and includes the injected max-token limit.
+- User prompt template rendering now uses `Template.safe_substitute`, aligned with system prompt injection behavior and compatible with optional `$tool_result_max_tokens` placeholders.
+
 ## [0.7.0]
 
 ### Added
@@ -118,8 +127,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.7.0...HEAD
-[0.6.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.1...v0.7.0
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.4.0...v0.5.0

{nighthawk_python-0.7.0 → nighthawk_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.7.0
+Version: 0.8.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/

{nighthawk_python-0.7.0 → nighthawk_python-0.8.0}/docs/for-coding-agents.md

@@ -273,6 +273,8 @@ Do not inject untrusted raw text into Natural source. If input is user-controlle
 Rules:
 
 - The model sees callable signatures from both LOCALS and GLOBALS.
+- For object read bindings, the model also sees a capability view: object header, public methods (with signatures), and public fields (with typed previews).
+- Object capability views expose public members only. Private/dunder members are omitted, and properties are not evaluated.
 - Put per-invocation data in function parameters. Put stable, reusable capabilities at module level.
 - Do not annotate callable parameters as `object` or `Any` -- this erases the signature the model needs:
 

{nighthawk_python-0.7.0 → nighthawk_python-0.8.0}/docs/specification.md

@@ -103,7 +103,7 @@ The condensed coding agent guide (`for-coding-agents.md`) is a derivative docume
     - `step_user_prompt_template`: user prompt template.
 - `StepContextLimits`
     - Limits for rendering dynamic context into the LLM prompt.
-    - Fields: `locals_max_tokens`, `locals_max_items`, `globals_max_tokens`, `globals_max_items`, `value_max_tokens`, `tool_result_max_tokens`.
+    - Fields: `locals_max_tokens`, `locals_max_items`, `globals_max_tokens`, `globals_max_items`, `value_max_tokens`, `object_max_methods`, `object_max_fields`, `object_field_value_max_tokens`, `tool_result_max_tokens`.
 - `JsonableValue`
     - Type alias for JSON-serializable Python values (`dict | list | str | int | float | bool | None`).
 - `ExecutionContext`
@@ -254,12 +254,49 @@ Ordering:
 
 Rendering format:
 
-- Non-callable values: `name: type_name = json_value`, where `json_value` is the compact JSON rendering of the value (bounded by `context_limits.value_max_tokens`).
+- `TypeAliasType` values (PEP 695): `name: type = underlying_type`.
 - Callable values: `name: (signature)`, where `(signature)` is the result of `inspect.signature`. Type annotations are included when available (e.g., `(base: int, bonus: int) -> int`).
     - If the callable has a meaningful docstring, the first line is appended as `# first_line`.
-    - If multiple callable entries share the same signature text, each is annotated with `# disambiguation: use name` to help the LLM distinguish them.
+    - If the callable is async, `async` is appended in metadata comments.
+    - If multiple callable entries share the same signature text, each is annotated with `# disambiguation: use name`.
     - If the signature cannot be resolved (e.g., `__signature__` raises), the entry renders as `name: <callable; signature-unavailable>`.
-- `TypeAliasType` values (PEP 695): `name: type = underlying_type`.
+- Object capability values (non-callable, non-scalar, non-container values):
+    - Header line: `name: object = TypeName`.
+    - Public method lines: `name.method: (signature)` using callable rules above.
+    - Public field lines: `name.field: type_name = json_value`.
+    - Public means names that do not start with `_`; private and dunder names are excluded.
+    - Properties are not evaluated.
+    - Field discovery uses safe sources: instance `__dict__`, dataclass fields, Pydantic model fields, and readable public `__slots__` entries.
+    - Class attributes that are public and non-callable are included as fields.
+    - Method expansion is bounded by `context_limits.object_max_methods`; field expansion is bounded by `context_limits.object_max_fields`; each field value preview is bounded by `context_limits.object_field_value_max_tokens`.
+    - If object member limits are exceeded, explicit omission lines are added: `name.<methods>: <snipped N public methods>` and/or `name.<fields>: <snipped N public fields>`.
+- Other non-callable values: `name: type_name = json_value`, where `json_value` is bounded by `context_limits.value_max_tokens`.
+
+Callable disambiguation considers both top-level callable entries and object method entries in the same section.
+
+Ordering:
+
+- Top-level entries are rendered in lexicographic order by top-level name.
+- Object methods and fields are rendered in lexicographic order by member name.
+- Methods are rendered before fields for each object entry.
+- If a section-level budget prevents rendering all top-level entries, `<snipped>` is appended at the end of the section.
+
+Safety:
+
+- Prompt rendering does not call user methods.
+- Prompt rendering does not evaluate properties or descriptors requiring attribute execution.
+- Slot and field access failures are ignored for rendering purposes.
+
+Token budgeting:
+
+- Section budgets remain governed by `locals_max_tokens` / `globals_max_tokens` and item budgets by `locals_max_items` / `globals_max_items`.
+- Object method and field expansion is additionally governed by object-specific limits listed above.
+- Line-level token counting includes newline separators during budget checks.
+
+Observability:
+
+- Section-level token truncation emits `prompt_context_truncated` logs with section, reason, and configured max token details.
+- Object member omission due to object-specific member limits does not emit a separate log event.
 
 Truncation:
 
@@ -421,7 +458,7 @@ Atomicity requirement:
 #### 8.3.1. Supporting types (internal)
 
 - `ToolBoundaryError`: Exception carrying `kind` (ErrorKind), `message`, and optional `guidance`. Raised by tool implementations to signal structured failures.
-- `ToolResultRenderingPolicy`: Frozen dataclass controlling how tool results are rendered (tokenizer encoding name, max tokens, JSON renderer style).
+- `ToolResultRenderingPolicy`: Frozen dataclass controlling how tool result previews are rendered (tokenizer encoding name, max tokens, JSON renderer style).
 
 ### 8.4. Execution contract (final JSON)
 
@@ -691,7 +728,7 @@ Instance attributes:
 - `configuration: StepExecutorConfiguration` — the resolved configuration.
 - `agent_is_managed: bool` — `True` when the agent was built internally from the configuration, `False` when provided externally via `from_agent`.
 - `token_encoding` — tiktoken encoding resolved from the configuration.
-- `tool_result_rendering_policy: ToolResultRenderingPolicy` — policy for rendering tool results, derived from configuration.
+- `tool_result_rendering_policy: ToolResultRenderingPolicy` — policy for rendering tool result previews, derived from configuration.
 
 ### 14.3. Custom backends
 

{nighthawk_python-0.7.0 → nighthawk_python-0.8.0}/evals/promptfoo/prompts/eval_default.txt

@@ -22,4 +22,4 @@ Trust boundaries:
 
 Notes:
 - In async Natural functions, expressions may use `await`.
-- Tool calls return {"value": ..., "error": ...}. Values may contain … where content was omitted. Check "error" for failures.
+- Tool calls return {"value": ..., "error": ...}; "value" is a preview (max $tool_result_max_tokens tokens), so persist large/intermediate data via nh_assign and inspect with focused nh_eval reads.

{nighthawk_python-0.7.0 → nighthawk_python-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.7.0"
+version = "0.8.0"
 description = "A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks."
 readme = "README.md"
 requires-python = ">=3.13"

{nighthawk_python-0.7.0 → nighthawk_python-0.8.0}/src/nighthawk/configuration.py

@@ -32,7 +32,7 @@ Trust boundaries:
 
 Notes:
 - In async Natural functions, expressions may use `await`.
-- Tool calls return {"value": ..., "error": ...}. Values may contain \u2026 where content was omitted. Check "error" for failures.
+- Tool calls return {"value": ..., "error": ...}; "value" is a preview (max $tool_result_max_tokens tokens), so persist large/intermediate data via nh_assign and inspect with focused nh_eval reads.
 """
 
 
@@ -81,8 +81,11 @@ class StepContextLimits(BaseModel):
         locals_max_items: Maximum items rendered in the locals section.
         globals_max_tokens: Maximum tokens for the globals section.
         globals_max_items: Maximum items rendered in the globals section.
-        value_max_tokens: Maximum tokens for a single value rendering.
-        tool_result_max_tokens: Maximum tokens for a tool result rendering.
+        value_max_tokens: Maximum tokens for a single value preview.
+        object_max_methods: Maximum public methods rendered for one object capability view.
+        object_max_fields: Maximum public fields rendered for one object capability view.
+        object_field_value_max_tokens: Maximum tokens for one object field value preview.
+        tool_result_max_tokens: Maximum tokens for a tool result preview.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
@@ -94,6 +97,9 @@ class StepContextLimits(BaseModel):
     globals_max_items: int = Field(default=40, ge=1)
 
     value_max_tokens: int = Field(default=200, ge=1)
+    object_max_methods: int = Field(default=16, ge=0)
+    object_max_fields: int = Field(default=16, ge=0)
+    object_field_value_max_tokens: int = Field(default=120, ge=1)
     tool_result_max_tokens: int = Field(default=1_200, ge=1)