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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nighthawk_python-0.12.0.tar.gz (337.7 kB view details)

Uploaded Sep 2, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

nighthawk_python-0.12.0-py3-none-any.whl (104.4 kB view details)

Uploaded Sep 2, 2026 Python 3

File details

Details for the file nighthawk_python-0.12.0.tar.gz.

File metadata

Download URL: nighthawk_python-0.12.0.tar.gz
Upload date: Sep 2, 2026
Size: 337.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nighthawk_python-0.12.0.tar.gz
Algorithm	Hash digest
SHA256	`0af17f4df47a84e2ca24cf285a8b41b413a23c77f6fed96ccbd683f0a1c6abaf`
MD5	`56e64d59f0dfcb6b01d4dc5c9113456d`
BLAKE2b-256	`09a95ca5b42f4b26075f977cf41e3ceb63511a4041ef2f3a7ff9752f5f1e6c5a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for nighthawk_python-0.12.0.tar.gz:

Publisher: publish.yml on kurusugawa-computer/nighthawk-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: nighthawk_python-0.12.0.tar.gz
- Subject digest: 0af17f4df47a84e2ca24cf285a8b41b413a23c77f6fed96ccbd683f0a1c6abaf
- Sigstore transparency entry: 2688484131
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: kurusugawa-computer/nighthawk-python@cf20b3d195ad35e5a15e007ebfe2f12fae0d5e75
- Branch / Tag: refs/tags/v0.12.0
- Owner: https://github.com/kurusugawa-computer
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@cf20b3d195ad35e5a15e007ebfe2f12fae0d5e75
- Trigger Event: push