nighthawk-python 0.6.0__tar.gz → 0.6.1__tar.gz

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1]
+
+### Added
+- Implicit type alias discovery: callable signatures in step locals and referenced globals are now scanned for PEP 695 `TypeAliasType` references, automatically including their definitions in the prompt globals section so the LLM can resolve type names like `-> Labels`.
+
+### Changed
+- `nh_eval` and `nh_assign` provided tools are now async, directly awaiting coroutines in async contexts instead of bridging through a background thread.
+
+## [0.6.0]
+
 ### Added
 - `nighthawk.resilience` module with composable function transformers for production resilience: `retrying` (tenacity-based), `fallback`, `vote`/`plurality`, `timeout`, `circuit_breaker`/`CircuitState`/`CircuitOpenError`.
   - `tenacity>=9` as a core dependency.
@@ -92,7 +102,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.5.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.1...HEAD
+[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
 [0.4.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.0...v0.3.1

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.6.0
+Version: 0.6.1
 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.6.1/docs/philosophy.ja.md

@@ -0,0 +1,172 @@
+# 設計思想
+
+Python がオーケストレーションを制御し、LLM は明示的な状態転送を伴う型付きブロックの内部で動作する。
+
+## 実行モデル
+
+Nighthawk は通常の Python 関数の内部に Natural ブロックを埋め込む。各ブロックは型付き境界である。読み取りバインディング (`<name>`) は Python 変数から入力状態を注入し、書き込みバインディング (`<:name>`) は型検証を経て出力状態をコミットし、バインディング関数はブロック実行中に LLM へ Python の呼び出し可能オブジェクトへのコンポーザブルなアクセスを提供する。Python がシーケンス制御 -- ループ、条件分岐、エラーハンドリング、リトライ -- を担い、LLM は各ブロック内部で動作する。ブロック間で暗黙的なメッセージ履歴が引き継がれることはない。
+
+```py
+def python_average(numbers):
+    return sum(numbers) / len(numbers)
+
+@nh.natural_function
+def calculate_average(numbers):
+    """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", "五"])  # 3.0
+```
+
+`<python_average>` のようなバインディング関数はプロンプト内でコンパクトなシグネチャ行として表示される。LLM の事前学習済み Python 知識により、JSON Schema やプロトコルのオーバーヘッドなしに、シグネチャだけで型、戻り値、合成について推論できる。定量的な比較については [ツール公開効率](#ツール公開効率) を参照。
+
+プロバイダーバックドエグゼキューターでは、各 Natural ブロックは型付きバインディングが主要な処理を担う単一の LLM 呼び出しである。書き込みバインディングが `Literal["positive", "negative", "neutral"]` として型付けされた感情分類器は、宣言された集合外の出力を拒否する -- 型アノテーションはヒントではなく、Pydantic 検証による実行時強制契約である。同じメカニズムは数値抽出 (`int`, `float`)、構造化パース (Pydantic モデル)、判断空間が有界な任意のタスクに適用される。ホストプログラムがループを所有するため、誤分類された結果はリトライ、ログ記録、フォールバックへの転送が可能であり -- すべて通常の Python で行える。
+
+[コーディングエージェントバックエンド](coding-agent-backends.md) では、同じ境界契約が適用されるが、各 Natural ブロックは自律的なエージェント実行となる。エージェントはファイルの読み取り、コマンドの実行、スキルの呼び出しが可能であり -- 型付きバインディングが Python への境界を越える際に何を通過させるかを強制する。人間が記述するワークフローを構造化する `scope()` や `run()` のコンテキストマネージャーは、コーディングエージェントがプログラム的にワークフローを構築する際にも同様に読解可能である。コーディングエージェントが Natural ブロック内で動作する場合、バインディング関数はプロンプト内で Python シグネチャとして表示される:
+
+```
+fetch_items: (category: str, limit: int = 10) -> list[Item]
+merge_results: (primary: list[Item], secondary: list[Item]) -> list[Item]
+```
+
+基盤となる LLM の事前学習済み Python 知識により、`Item` が属性を持つこと、戻り値がイテレーションやインデキシングをサポートすること、`merge_results` が `fetch_items` の出力を直接受け取れることを -- 型アノテーションだけから推論できる。同等の CLI ツール記述 (`fetch-items --category X --limit 10`) は呼び出し構文を伝えるが、出力構造は伝えない。モデルは出力形式を別途推論または発見する必要がある。
+
+コーディングエージェントバックエンドがこれを特に実用的にするのは、エージェントが推論された構造をワークフローコードの読解、ツールの呼び出し、実装の編集、`pytest` の実行、同一 Python コードベース内でのイテレーションに即座に適用できるためである。フレームワーク固有のツール、グラフシリアライゼーション形式、別の設定言語は不要である。
+
+## ハーネスはモデルより重要
+
+最も強い直接的証拠はエージェント型コーディングタスクから得られている。この原則をプロバイダーバックドの判断に拡張することは設計上の推論であり、測定された主張ではない。
+
+### 観察された証拠
+
+経験的証拠は、周囲のプログラムがモデルより重要であることを示唆している。Can Boluk の [2026年の実験](https://blog.can.ac/2026/02/12/the-harness-problem/) は、16 モデル x 3 編集ツール x 180 タスクでテストし、ハーネスのみの変更であるモデルの成功率が 6.7% から 68.3% に向上した -- モデル変更なしで10倍の改善である。LangChain も同様のパターンを報告しており (2026年)、ハーネス変更のみでコーディングエージェントの精度を 52.8% から 66.5% に改善した。
+
+Mitchell Hashimoto は 2026年2月に [この実践を「ハーネスエンジニアリング」と命名した](https://mitchellh.com/writing/my-ai-adoption-journey): 「エージェントがミスを犯すたびに、そのエージェントが二度とそのミスを犯さないようにソリューションをエンジニアリングする時間を取る。」 OpenAI は同月、[ハーネスファースト開発の詳細な記述](https://openai.com/index/harness-engineering/) を公開した。
+
+直接的な証拠は LLM 駆動のコード編集およびファイル管理タスクに関するものであり、ハーネス設計 (編集フォーマット、ツール構成、コンテキスト管理) がモデル選択よりも大きな改善をもたらした。これらのタスクはマルチステップのツール使用とファイル操作を含み、シングルターンの分類や抽出とは構造的に異なる。
+
+### Nighthawk の設計上の推論
+
+この原則をプロバイダーバックドの軽量判断 (感情分類、数値解釈) に拡張することは、経験的主張ではなく設計上の推論である。型付きバインディングは構造的にハルシネーションを制約し、レジリエンストランスフォーマーは一時的な障害を吸収するが、これらの利点は同じ統制された方法で独立に測定されていない。
+
+スコープにかかわらず、実践的な問いはハーネス改善がどのように表現されるかである。設定ファイルベースのガードレールシステム -- ルールファイル、ライフサイクルフック、パーミッションモード、ツールフィルタリング -- は動作の制限には効果的だが、動的なオーケストレーションを表現できない。すなわち、条件付きリトライ戦略、型レベルの入出力契約、スコープ依存のツール可視性、実行時状態に適応するプロンプトは表現できない。制約の語彙は設定フォーマットが許容する範囲に限定される。
+
+[実行モデル](#実行モデル) および以降のセクションで述べるプリミティブ -- 型付きバインディング、レジリエンストランスフォーマー、スコープ付き実行コンテキスト -- は、設定ではなく Python プログラミングを通じたこの原則の Nighthawk による実装である。
+
+## 設計上の帰結
+
+実行モデルでは、Python と LLM の推論の間の境界メカニズムとして型付きバインディングを導入した。以下のサブセクションでは、その選択からどのような設計上の帰結が生じるかを探る -- レジリエンスとスコーピングからツール公開、マルチエージェント協調、そして設計が受け入れるトレードオフまで。
+
+### コンポーザブル関数としてのレジリエンス
+
+プロダクション LLM アプリケーションには、一時的な障害、不安定な出力、プロバイダー障害に対処する戦略が必要である。ワークフローエンジンはリトライ、チェックポイント、Human-in-the-Loop をグラフランタイムに組み込む -- レジリエンスはオーケストレーション層と不可分である。Nighthawk は異なるアプローチを取る: レジリエンスプリミティブ (`nighthawk.resilience`) は任意の呼び出し可能オブジェクトをラップする通常の Python 関数トランスフォーマーである。各トランスフォーマーは関数を受け取り、同じシグネチャの新しい関数を返す。リトライ、フォールバック、投票、タイムアウト、サーキットブレーカーのロジックはネストによって合成される -- グラフ DSL なし、フレームワーク管理の状態なし、暗黙的なリトライポリシーなし。ホストがどの呼び出しをリトライするか、何回リトライするか、失敗時に何が起こるかを正確に制御する -- アプリケーションの他の部分と同じ Python デバッガー、pytest、コードレビューのワークフローを使用して。これはプロバイダーバックドの軽量判断と自律的なエージェント実行の両方に等しく適用される。使用パターンと合成の例については [パターン](patterns.md#resilience-patterns) を参照。
+
+### スコープ付き実行コンテキスト
+
+`run()` は実行境界を確立する: グローバル設定や暗黙的なスレッドローカルとしてではなく、明示的な Python `with` 文として現在のコンテキストにステップエグゼキューターをリンクする。`scope()` は既存の run 内で設定を狭める -- モデルオーバーライド、プロンプトサフィックス、エグゼキューター置換 -- それぞれネストされた `with` ブロック内でのみ有効となる。ネストは自然な Python のレキシカルスコーピングである: フレームワークランタイムではなくホストプログラムの制御フローが、任意の時点でどの設定がアクティブかを決定する。これは、実行時の動作がプロのみの指示や静的設定ではなく Python 構造に存在すべきという思想に直接つながる。詳細と例については [ランタイム設定](runtime-configuration.md) を参照。
+
+### ツール公開効率
+
+バインディング関数は JSON Schema オブジェクトや CLI 記述ではなく Python シグネチャであるため、ツールあたりのコンテキストコストは単一のシグネチャ行程度である。MCP ツール定義はリクエストごとの JSON Schema オーバーヘッドを伴い、公開ツール数に応じて増大する。CLI ツールは定義オーバーヘッドを削減するが、隠れたコストを伴う -- Mario Zechner の [2025年のベンチマーク](https://mariozechner.at/posts/2025-08-15-mcp-vs-cli/) によれば、Claude Code での CLI 呼び出しはコマンドごとのセキュリティ分類をトリガーし、同等の MCP 呼び出しよりも桁違いに多くのトークンを消費した。いずれのアプローチでも、モデルが実際のタスクを見る前にツールの配管に相当なコンテキスト予算が費やされる。
+
+**MCP** はツールをプロトコル層上の JSON Schema オブジェクトとして定義する。各ツール定義はリクエストごとにトークンを消費する。
+
+**CLI ツール** は LLM のシェルコマンドに関する事前学習済み知識を活用することで大幅に改善される。同等の CLI ツールの README は、わずか 225 トークンで同じ機能を記述できる。しかし、CLI は型なし文字列 I/O で動作する: 構造化データはテキストにシリアライズしてパースし直す必要があり、型安全性は強制ではなく慣例に依存し、テストにはシェルレベルのスキャフォールディングが必要である。CLI の出力構造は宣言されないため、LLM は学習データから推論する必要がある -- マルチステップのツール合成が構造的保証ではなく確率的想起に依存することになる。
+
+**Nighthawk のバインディング関数** は CLI の洞察をさらに一歩進める。LLM は bash と同様に Python も熟知している。バインディング関数はプロンプト内で単一のシグネチャ行として表示される:
+
+```
+find_top_items: (category: str) -> list[dict]  # Return the highest-scored recent items in a category.
+```
+
+これは単一のシグネチャ行程度であり -- 最もコンパクトな CLI 記述と同等のトークンコストだが、より高い情報密度を持つ。型アノテーションにより LLM は構造的に推論できる: `list[dict]` の戻り値はイテレーションとキーアクセスをサポートし、`Item` の戻り型は発見可能な属性を持ち、型付きパラメータは別のバインディング関数が何を受け入れるかを明確にする。同様のコンパクトさの CLI 記述は呼び出し構文を伝えるが、出力構造は学習データからの推論に委ねる。プロトコル層なし、シリアライゼーション境界なし、ツールごとの JSON Schema オーバーヘッドなし。同じ型アノテーションがオプションの静的解析 (pyright) のターゲットおよび Nighthawk のランタイム検証 (Pydantic 経由) のフックとして機能する。テスト、デバッグ、合成には標準的な Python ツールを使用する。
+
+| アプローチ | ツールあたりのコンテキストコスト | 情報密度 | 型安全性 | コンポーザビリティ | テスト | 相互運用性 |
+|---|---|---|---|---|---|---|
+| MCP | 高い (ツールごとの JSON Schema) | 低い (冗長なスキーマ) | スキーマレベル | フレームワーク依存 | フレームワーク固有 | 言語横断標準 |
+| CLI | 低い (事前学習済み知識) | 中程度 (出力は推論) | なし (文字列 I/O) | パイプ (線形、文字列ベース) | シェルスクリプト | 汎用 (任意のランタイム) |
+| バインディング関数 | 低い (シグネチャ1行) | 高い (型 + セマンティクス) | アノテーションベース (静的解析 + 書き込み境界のランタイム強制) | ネイティブ (関数合成) | pytest | Python のみ |
+
+### フレームワークなしのマルチエージェント協調
+
+マルチエージェントシステムは3つの構造的課題に直面する: エージェント間の状態伝達方法、エージェント間の隔離方法、複数エージェントの結果の統合方法。既存のワークフローエンジンはフレームワーク固有のメカニズムでこれらに対処する -- 通信にはグラフ状態、隔離にはマネージドランタイム、統合にはメッセージ集約 -- しかし、各ソリューションはユーザーをフレームワークの抽象化にロックインし、3つすべてを包括的に提供するフレームワークは存在しない。
+
+Nighthawk はマルチエージェントフレームワークではない。各課題に対して Python の既存エコシステムと合成するビルディングブロックである。
+
+**通信。** 関数内の Natural ブロック間では Python 変数が状態を引き継ぐ -- 読み取りバインディング (`<name>`) が値を公開し、書き込みバインディング (`<:name>`) が型検証付きで新しい値をコミットする。Natural 関数間の通信は通常の Python である: 戻り値、関数引数、共有データ構造。メッセージブローカーなし、グラフ状態なし、フレームワーク管理のチャネルなし。クロスプロセスまたは分散協調には、任意の Python ネイティブメカニズム (asyncio、キュー、タスクブローカー) が Natural 関数呼び出しをオーケストレートできる。なぜなら、それらは通常の Python の呼び出し可能オブジェクトだからである。
+
+**隔離。** Nighthawk はバインディング境界での論理的隔離を提供する: 読み取りバインディングは名前の再バインドを防ぎ、書き込みバインディングは型検証され、各 Natural ブロックは暗黙的なメッセージ履歴を持たない独立したステップコンテキストで実行される。読み取りバインディングはミュータブルオブジェクトのインプレース変更を防がない -- これは意図的であり、[キャリーパターン](patterns.md#the-carry-pattern) の基盤となっている。OS レベルの隔離 -- サンドボックス、ファイルシステムスコーピング、パーミッション制御 -- は実行バックエンドに委譲される。コーディングエージェントバックエンドは独自のサンドボックスモードと作業ディレクトリスコーピングを提供し、Nighthawk はそれらを設定するが再実装はしない。
+
+**結果統合。** レジリエンスモジュールは一般的なケースのためのコンポーザブルなパターンを提供する: 繰り返し呼び出しにおける多数決合意のための `vote`、順次の最初の成功連鎖のための `fallback`。ドメイン固有の統合 -- 複数エージェントからの編集の調整、異種出力の集約、競合の解決 -- はユーザーコードに属する。なぜなら、統合セマンティクスは本質的にドメイン依存だからである。Nighthawk の役割は、各エージェントの出力が型付けされ検証された Python オブジェクトとして境界を越え、統合ロジックが直接操作できることを保証することである。
+
+### トレードオフ
+
+境界中心の設計にはコストがある:
+
+- **Python ロックイン。** バインディング関数、型アノテーション、レジリエンストランスフォーマーは Python の構成要素である。Nighthawk は言語中立のプロトコルを提供しない。非 Python システムとの相互運用には明示的なブリッジング (例: Natural 関数をラップする REST エンドポイント) が必要である。
+- **呼び出しごとのコスト。** Natural ブロックの呼び出しごとに LLM を呼び出す。入力間でコストを償却するコンパイルステップは存在しない。決定論的な Python 関数で十分な高スループット・低判断タスクには、Natural ブロックは適切なツールではない。設計の根拠については [なぜ毎回評価するのか](#なぜ毎回評価するのか) を参照。
+- **インテグレーションテストは必須。** モックテストは Natural ブロック周辺の Python ロジックを検証するが、LLM が正しい判断を生成することの検証には実プロバイダーに対するインテグレーションテストが必要である。[二層テスト戦略](verification.md) はオプションではなく、判断を LLM に委譲することの構造的帰結である。
+- **手動オーケストレーション負担。** Nighthawk は分岐、リトライ、統合ロジック、リカバリーポリシーをグラフランタイムではなくユーザーコードに残す。これは「Python がすべてのフローを制御する」原則の直接的コストである。
+- **Python API 設計の規律。** バインディング関数はそのシグネチャ、型アノテーション、命名の質に依存する。API 設計が不適切だと、合成についての LLM の推論能力が低下する。
+
+## なぜ毎回評価するのか
+
+自然な疑問: Natural ブロックを一度使って同等の Python コードに変換し、以降の呼び出しで生成されたコードを実行すればよいのではないか? これにより呼び出しごとのレイテンシ、コスト、非決定性が排除される。
+
+答えは、Natural ブロックは決定論的コードに還元できないタスクのために存在するということである。「このレビューの感情を分類せよ」や「この曖昧なユーザー入力を解釈せよ」は、特定の入力、世界知識、コンテキストに依存する判断を必要とする。タスクが決定論的な Python として記述できるなら、そうすべきである -- これが核心的な設計原則である ([Natural ブロック](natural-blocks.md#responsibility-split) を参照)。
+
+一度きりのコンパイルにはさらなる構造的限界がある:
+
+- 生成されたコードはコンパイル時点の LLM の世界知識を固定してしまう。
+- 入力空間は無限である: 「りんご3個、卵1ダース、そして cinco naranjas」は、有限のコード生成では完全に予測できないオープンエンドの解釈を必要とする。
+- 生成されたコードの正しさの検証には最終的に LLM が必要であり -- 循環依存を生む。
+
+[コーディングエージェントバックエンド](coding-agent-backends.md) では、「毎回評価する」は各 Natural ブロック呼び出しごとに自律的エージェントを起動し、特定の入力に完全に適応することを意味する。呼び出しごとのコストは高いが、適応性も高い。
+
+Nighthawk はコンパイルではなく制約によって信頼性の懸念に対処する: 書き込みバインディングの型検証、許可する結果を制限する deny フロントマター、制御フローのための構造化アウトカムカインド、そして [二層テスト戦略](verification.md) (Python ロジックのモックテスト、Natural ブロックの有効性のインテグレーションテスト)。
+
+## 設計のランドスケープ
+
+現在の設計空間における3つのポジションが、オーケストレーションアプローチの幅を示している: オーケストレーションフレームワーク、文芸的プログラミングスタイルのハーネス、そして Nighthawk。
+
+### オーケストレーションフレームワーク
+
+**LangGraph、CrewAI、AutoGen。** LLM またはグラフランタイムが次に何が起こるかを決定する -- どのツールを呼び出すか、エージェント間のルーティング方法、いつ停止するか。契約はフレームワーク管理のスキーマ、ガードレール、ルーティング条件を通じて強制される。状態はメッセージとしてグラフを流れ、会話履歴はステップ間で暗黙的に蓄積される。
+
+### 文芸的プログラミングスタイルのハーネス
+
+**Agent Skills および類似のアプローチ。** オーケストレーションロジックはホストプログラムの型システムの外部に存在する -- 厳密な手続きのための埋め込みコードを伴う自然言語の指示の中に。制約は自然言語で表現され、確率的に強制される。オーケストレーションと状態が自然言語に存在する場合、プロンプト世界とコード世界の間で実行状態を同期させることは困難である。以下の例は状態同期の課題を示している:
+
+````md
+Compute the average using `calculate_average`.
+Convert the mixed representations before calling it.
+
+```py
+def calculate_average(numbers):
+    return sum(numbers) / len(numbers)
+```
+
+Target: `[1, "2", "three", "cuatro", "五"]`
+Store the computed average in `result`.
+````
+
+この指示は埋め込みコードを参照するが、`result` がどのようにホストプログラムに戻るかの明示的な境界は存在しない。ナラティブは値が後続のステップで利用可能であることを前提としているが、状態転送のメカニズムは暗黙的であり -- 読者は宣言された契約ではなく慣例から推論しなければならない。
+
+### Nighthawk
+
+ホスト Python プログラムがオーケストレーションを所有する。契約は Python の型で表現され、ランタイム検証、構造化アウトカム、明示的なブロック境界を通じて強制される。状態はブロック境界での明示的な転送を伴う Python 変数に存在する。全体の説明については [実行モデル](#実行モデル) を参照。
+
+| | オーケストレーションフレームワーク | 文芸的ハーネス | Nighthawk |
+|---|---|---|---|
+| 制御 | LLM がグラフ/ルーティングでオーケストレート | 自然言語の指示 | Python がすべてのフローを制御 |
+| 状態 | グラフ状態、メッセージ履歴 | プロンプトナラティブに埋め込み | Python ローカル変数、明示的バインディング |
+| ステップ間コンテキスト | 暗黙的 (会話が蓄積) | 暗黙的 (プロンプト継続) | 明示的 (バインディング、スコープ付きインジェクション) |
+| デバッグ | フレームワーク固有のツール | プロンプト検査 | Python デバッガー、pytest |
+| 制約モデル | ガードレール、ルーティング条件 | 自然言語 (確率的) | 型検証、deny フロントマター、構造化アウトカム |
+
+静的な制約システム -- AGENTS.md スタイルのルールファイル、ライフサイクルフック、パーミッションモード -- は上記のいずれのアプローチの周囲にもガードレール層として有用であるが、ランタイムオーケストレーションや型付き状態転送を代替するものではない。
+
+オーケストレーションフレームワークは、マルチエージェント協調がタスクの核心である場合、または蓄積された会話履歴が不可欠な場合 (例: チャットボット) により適している。文芸的プログラミングスタイルのハーネスは、オーケストレーションロジックが散文で最も自然に表現されるシナリオや、対象読者がコードではなく指示を記述する場合に適している。Nighthawk は、決定論的制御フローが離散的な判断ポイントを含む場合、LLM の推論を既存の Python コードベースに統合する場合、または各判断に厳密な入出力制約が必要な場合により適している。

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/evals/promptfoo/provider.py

@@ -413,6 +413,7 @@ def call_api(prompt: str, options: dict, context: dict) -> dict:  # noqa: ARG001
         step_locals=step_locals,
         binding_commit_targets=set(output_binding_names),
         read_binding_names=read_binding_names,
+        implicit_type_reference_names=frozenset(),
     )
 
     # -- Execute --

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.6.0"
+version = "0.6.1"
 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.6.0 → nighthawk_python-0.6.1}/src/nighthawk/runtime/prompt.py

@@ -318,9 +318,10 @@ def build_user_prompt(
     )
 
     references, program_text = extract_references_and_program(processed_natural_program)
+    augmented_global_references = set(references) | set(step_context.implicit_type_reference_names)
     globals_text = _render_globals_section(
         step_context=step_context,
-        references=references,
+        references=augmented_global_references,
         token_encoding=token_encoding,
         context_limits=context_limits,
         json_renderer_style=configuration.json_renderer_style,

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/src/nighthawk/runtime/runner.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
 import ast
+import functools
 import inspect
+import typing
+from collections.abc import Iterable
 from dataclasses import dataclass
 from types import FrameType
-from typing import TypedDict
+from typing import TypeAliasType, TypedDict
 
 from opentelemetry.trace import Span, Status, StatusCode
 from pydantic import TypeAdapter
@@ -56,13 +59,6 @@ def _infer_binding_types_from_initial_values(
     binding_name_to_type: dict[str, object],
     step_locals: dict[str, object],
 ) -> None:
-    """Replace ``object`` fallback types with types inferred from initial values.
-
-    When a binding has no explicit type annotation, the AST transformer assigns
-    ``object`` as a placeholder.  This function upgrades those entries to the
-    runtime type of the initial value so that ``TypeAdapter`` validation in
-    ``nh_assign`` can catch type mismatches and prompt the LLM to retry.
-    """
     for name, declared_type in binding_name_to_type.items():
         if declared_type is not object:
             continue
@@ -74,6 +70,69 @@ def _infer_binding_types_from_initial_values(
             binding_name_to_type[name] = inferred_type
 
 
+def _discover_implicit_type_alias_reference_names(
+    *,
+    step_locals: dict[str, object],
+    step_globals: dict[str, object],
+    input_binding_names: Iterable[str],
+) -> frozenset[str]:
+    discovered_names: set[str] = set()
+    seen: set[int] = set()
+
+    def _collect(annotation: object) -> None:
+        if isinstance(annotation, TypeAliasType):
+            name = annotation.__name__
+            if name in step_globals and name not in step_locals:
+                discovered_names.add(name)
+            return
+
+        if isinstance(annotation, str):
+            resolved = step_globals.get(annotation)
+            if isinstance(resolved, TypeAliasType) and annotation not in step_locals:
+                discovered_names.add(annotation)
+            return
+
+        annotation_id = id(annotation)
+        if annotation_id in seen:
+            return
+        seen.add(annotation_id)
+
+        for arg in typing.get_args(annotation):
+            _collect(arg)
+
+    def _scan_callable(value: object) -> None:
+        target = value.func if isinstance(value, functools.partial) else value
+        try:
+            hints = typing.get_type_hints(target, localns=step_globals)
+        except Exception:
+            try:
+                signature = inspect.signature(value)  # type: ignore[arg-type]
+            except (TypeError, ValueError):
+                return
+            hints = {}
+            for parameter in signature.parameters.values():
+                if parameter.annotation is not inspect.Parameter.empty:
+                    hints[parameter.name] = parameter.annotation
+            if signature.return_annotation is not inspect.Signature.empty:
+                hints["return"] = signature.return_annotation
+
+        for annotation in hints.values():
+            _collect(annotation)
+
+    for value in step_locals.values():
+        if callable(value):
+            _scan_callable(value)
+
+    step_locals_keys = step_locals.keys()
+    for name in input_binding_names:
+        if name not in step_locals_keys and name in step_globals:
+            value = step_globals[name]
+            if callable(value):
+                _scan_callable(value)
+
+    return frozenset(discovered_names)
+
+
 def _build_step_globals(
     python_globals: dict[str, object],
 ) -> dict[str, object]:
@@ -266,6 +325,11 @@ class Runner:
 
         binding_commit_targets = set(output_binding_names)
         read_binding_names = frozenset(input_binding_names) - binding_commit_targets
+        implicit_type_reference_names = _discover_implicit_type_alias_reference_names(
+            step_locals=step_locals,
+            step_globals=step_globals,
+            input_binding_names=input_binding_names,
+        )
 
         step_context = StepContext(
             step_id=_build_step_id(caller_frame=caller_frame),
@@ -273,6 +337,7 @@ class Runner:
             step_locals=step_locals,
             binding_commit_targets=binding_commit_targets,
             read_binding_names=read_binding_names,
+            implicit_type_reference_names=implicit_type_reference_names,
             binding_name_to_type=binding_name_to_type,
             tool_result_rendering_policy=tool_result_rendering_policy,
         )

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/src/nighthawk/runtime/step_context.py

@@ -47,6 +47,7 @@ class StepContext:
 
     binding_commit_targets: set[str]
     read_binding_names: frozenset[str]
+    implicit_type_reference_names: frozenset[str]
 
     # Ordinary user-provided binding (for example a global named "memory") may exist in step_locals.
 

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/src/nighthawk/testing.py

@@ -69,7 +69,7 @@ def _build_step_call(
     binding_names: list[str],
     allowed_step_kinds: tuple[str, ...],
 ) -> StepCall:
-    referenced_global_names = step_context.read_binding_names - step_context.step_locals.keys()
+    referenced_global_names = (step_context.read_binding_names | step_context.implicit_type_reference_names) - step_context.step_locals.keys()
     filtered_globals = {name: step_context.step_globals[name] for name in referenced_global_names if name in step_context.step_globals}
     return StepCall(
         natural_program=processed_natural_program,

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/src/nighthawk/tools/provided.py

@@ -7,7 +7,7 @@ from pydantic_ai import RunContext
 from pydantic_ai.tools import Tool
 
 from ..runtime.step_context import StepContext
-from .assignment import assign_tool, eval_expression
+from .assignment import assign_tool_async, eval_expression_async
 from .contracts import ToolBoundaryError
 
 
@@ -17,9 +17,9 @@ class ProvidedToolDefinition:
     tool: Tool[StepContext]
 
 
-def _eval_expression_or_raise(run_context: RunContext[StepContext], expression: str) -> object:
+async def _eval_expression_or_raise_async(run_context: RunContext[StepContext], expression: str) -> object:
     try:
-        return eval_expression(run_context.deps, expression)
+        return await eval_expression_async(run_context.deps, expression)
     except Exception as exception:
         raise ToolBoundaryError(kind="execution", message=str(exception), guidance="Fix the expression and retry.") from exception
 
@@ -27,19 +27,19 @@ def _eval_expression_or_raise(run_context: RunContext[StepContext], expression:
 def build_provided_tool_definitions() -> list[ProvidedToolDefinition]:
     metadata = {"nighthawk.provided": True}
 
-    def nh_assign(
+    async def nh_assign(
         run_context: RunContext[StepContext],
         target_path: str,
         expression: str,
     ) -> dict[str, Any]:
-        return assign_tool(
+        return await assign_tool_async(
             run_context.deps,
             target_path,
             expression,
         )
 
-    def nh_eval(run_context: RunContext[StepContext], expression: str) -> object:
-        return _eval_expression_or_raise(run_context, expression)
+    async def nh_eval(run_context: RunContext[StepContext], expression: str) -> object:
+        return await _eval_expression_or_raise_async(run_context, expression)
 
     return [
         ProvidedToolDefinition(

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/tests/backends/test_codex.py

@@ -300,6 +300,7 @@ def test_codex_model_contract_calls_tool_via_mcp(tmp_path: Path) -> None:
             step_locals={},
             binding_commit_targets=set(),
             read_binding_names=frozenset(),
+            implicit_type_reference_names=frozenset(),
         )
 
         from typing import cast

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/tests/docs/test_prompt_examples.py

@@ -67,6 +67,7 @@ def _build_prompt(
         step_locals=python_locals,
         binding_commit_targets=set(),
         read_binding_names=frozenset(),
+        implicit_type_reference_names=frozenset(),
     )
     return build_user_prompt(
         processed_natural_program=processed_natural_program,

{nighthawk_python-0.6.0 → nighthawk_python-0.6.1}/tests/execution/prompt_test_helpers.py

@@ -2,7 +2,10 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
+
 import nighthawk as nh
+from nighthawk.runtime.runner import _discover_implicit_type_alias_reference_names
 from nighthawk.runtime.step_context import StepContext
 from nighthawk.runtime.step_executor import build_user_prompt
 
@@ -27,13 +30,24 @@ class FakeAgent:
         return FakeRunResult(StepFinalResult(result=PassStepOutcome(kind="pass")))
 
 
-def build_step_context(*, python_globals: dict[str, object], python_locals: dict[str, object]) -> StepContext:
+def build_step_context(
+    *,
+    python_globals: dict[str, object],
+    python_locals: dict[str, object],
+    input_binding_names: Iterable[str] = (),
+) -> StepContext:
+    implicit_type_reference_names = _discover_implicit_type_alias_reference_names(
+        step_locals=python_locals,
+        step_globals=python_globals,
+        input_binding_names=input_binding_names,
+    )
     return StepContext(
         step_id="test",
         step_globals=python_globals,
         step_locals=python_locals,
         binding_commit_targets=set(),
         read_binding_names=frozenset(),
+        implicit_type_reference_names=implicit_type_reference_names,
     )