Skip to main content

PyPI PyPI Stats license issue resolution

Nighthawk

nighthawk-logo

Nighthawk is a Python library that makes natural-language judgment composable with ordinary Python functions. It is designed for AI agents to construct and improve programs whose functions can be reused across tasks.

Use Natural blocks for interpretation, classification, and other judgments; combine actions, constraints, and verification through Python functions and existing libraries. Python owns the surrounding control flow, state, and recovery. The same typed boundaries support provider-backed LLM calls and coding-agent executions.

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: list[float]) -> float:
    return sum(numbers) / len(numbers)


@nh.function
def calculate_average(numbers: list[object]) -> float:
    result: float = 0.0
    """execute
    Map each element of <numbers> to the number it represents,
    then compute <:result> by calling <python_average> with the mapped list.
    """
    return result


with nh.run(execution_model="openai-responses:gpt-6-luna"):
    print(calculate_average([1, "2", "three", "cuatro"]))  # 2.5

Natural interprets the mixed representations, python_average performs the deterministic calculation, and the output binding validates result as a float before Python resumes. Type validation constrains the result's shape; it does not prove the interpretation is correct.

See the Quickstart for setup details, credentials, and troubleshooting.

When to use Nighthawk

Nighthawk fits Python programs whose functions need model judgment inside ordinary control flow, where shared bindings, validated writeback, and execution boundaries reduce the work of building, revising, and reusing those functions. It composes with other approaches: an orchestration runtime can call Nighthawk functions as ordinary Python, a block can delegate to a coding agent that follows its native instruction files and skills, and Pydantic and Pydantic AI supply value contracts and model interaction.

Prefer another approach when:

  • Explicit rules determine the result: write Python.
  • Python with a model library meets the same needs with less total burden.
  • You need the library itself to provide framework-managed routing, durable conversation state, or language-neutral orchestration: choose a runtime that supplies them and use Nighthawk functions within it where useful.
  • You need the library itself to isolate untrusted programs: choose a host or backend that supplies that boundary before using Nighthawk within it.

Philosophy explains the purpose and design principles; Design drivers describes how to evaluate the expected benefits.

Embedding in an application

Hosts can admit whole function calls, select models without losing scoped controls, and observe block outcomes and model usage. See Runtime configuration for usage and execution boundaries for the guarantees. The host integration guide includes executable examples that run without credentials.

Documentation

Development & Contributing

See CONTRIBUTING.md for setup, development commands, and contribution guidelines.

Inspired by Nightjar.

Metadata

Release files for nighthawk-python 0.18.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nighthawk-python 0.18.0
File Size Uploaded Provenance Actions
nighthawk_python-0.18.0.tar.gz 668.6 kB With provenance Details for nighthawk_python-0.18.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nighthawk-python 0.18.0
File Interpreter ABI Platform Actions
nighthawk_python-0.18.0-py3-none-any.whl Python 3 none any Details for nighthawk_python-0.18.0-py3-none-any.whl

Total release size: 825.6 kB

Release files / nighthawk_python-0.18.0.tar.gz

Download URL nighthawk_python-0.18.0.tar.gz
Size 668.6 kB
Tags Source
SHA-256 checksum
How to use checksums
991e54ba090ab48770de65f5d1c5ac8b59c73fb36fd9c029a0ea6a2c10eb7717
BLAKE2b-256 checksum
How to use checksums
44674709b7f2b043ba23ca308849d209eab1f1adab7e297ffe317afb1a54ff09
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / nighthawk_python-0.18.0-py3-none-any.whl

Download URL nighthawk_python-0.18.0-py3-none-any.whl
Size 157.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b48344cb9dcd35bce14fcc1fe39fc25b1a8e31334e0029e2e6a14333ce88bc31
BLAKE2b-256 checksum
How to use checksums
5e205b111451d51917837bfd0bf32cca512d881ff452eeca67e037f732c5033d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for nighthawk-python 0.18.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for nighthawk_python-0.18.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page