A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
Nighthawk
Nighthawk is a Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
- 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 for the full design rationale.
This repository is a compact reimplementation of the core ideas of Nightjar.
Installation
Prerequisites: Python 3.13+
pip install nighthawk-python pydantic-ai-slim[openai]
For other providers, see Pydantic AI providers.
Example
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")
)
with nh.run(step_executor):
@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"]) # 2.5
See the Quickstart for setup details, credentials, and troubleshooting.
Documentation
- Quickstart -- Setup and first example.
- Natural blocks -- Block anatomy, bindings, functions, and writing guidelines.
- Executors -- Choose an execution backend.
- Runtime configuration -- Scoping, patching, context limits, and execution identity.
- Patterns -- Outcomes, async, composition, resilience, and common mistakes.
- Verification -- Mock tests, integration tests, and OpenTelemetry tracing.
- Pydantic AI providers -- LLM provider configuration.
- Coding agent backends -- Claude Code and Codex integration.
- Specification -- Canonical specification.
- API Reference -- Auto-generated API documentation.
- For coding agents -- Development guide for coding agents (LLMs) building Python projects with Nighthawk.
- Philosophy -- Design rationale and positioning.
- Roadmap -- Future directions.
Development & Contributing
See CONTRIBUTING.md for setup, development commands, and contribution guidelines.
References
- Nightjar (upstream concept): https://github.com/psg-mit/nightjarpy
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file nighthawk_python-0.10.0.tar.gz.
File metadata
- Download URL: nighthawk_python-0.10.0.tar.gz
- Upload date:
- Size: 300.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
61f61bb8fd847e6f529633686d0bce581baedd1dee694773c6e67850146d4987
|
|
| MD5 |
257684957c4626ed88b77499aad094a4
|
|
| BLAKE2b-256 |
d130ca4ccd71c70099c26542687836772633af23ad4ac32b9cc86a00722373c6
|
Provenance
The following attestation bundles were made for nighthawk_python-0.10.0.tar.gz:
Publisher:
publish.yml on kurusugawa-computer/nighthawk-python
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
nighthawk_python-0.10.0.tar.gz -
Subject digest:
61f61bb8fd847e6f529633686d0bce581baedd1dee694773c6e67850146d4987 - Sigstore transparency entry: 1255837327
- Sigstore integration time:
-
Permalink:
kurusugawa-computer/nighthawk-python@89d98cf03f91ea97e1d1a02d2feb2d62fc2cda1f -
Branch / Tag:
refs/tags/v0.10.0 - Owner: https://github.com/kurusugawa-computer
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@89d98cf03f91ea97e1d1a02d2feb2d62fc2cda1f -
Trigger Event:
push
-
Statement type:
File details
Details for the file nighthawk_python-0.10.0-py3-none-any.whl.
File metadata
- Download URL: nighthawk_python-0.10.0-py3-none-any.whl
- Upload date:
- Size: 86.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9d4775fc66ba98fb765ea432946c2f193d16a324477c941dceb71d136be61657
|
|
| MD5 |
5cbbcaa9450de9963f62a2cbcd010d34
|
|
| BLAKE2b-256 |
24ae51b6592c2bb0bdfbedcb175a9e22cc21033dff5a903e4da483038a8e5fea
|
Provenance
The following attestation bundles were made for nighthawk_python-0.10.0-py3-none-any.whl:
Publisher:
publish.yml on kurusugawa-computer/nighthawk-python
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
nighthawk_python-0.10.0-py3-none-any.whl -
Subject digest:
9d4775fc66ba98fb765ea432946c2f193d16a324477c941dceb71d136be61657 - Sigstore transparency entry: 1255837411
- Sigstore integration time:
-
Permalink:
kurusugawa-computer/nighthawk-python@89d98cf03f91ea97e1d1a02d2feb2d62fc2cda1f -
Branch / Tag:
refs/tags/v0.10.0 - Owner: https://github.com/kurusugawa-computer
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@89d98cf03f91ea97e1d1a02d2feb2d62fc2cda1f -
Trigger Event:
push
-
Statement type:
