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.19.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.19.0
File Size Uploaded Provenance Actions
nighthawk_python-0.19.0.tar.gz 673.0 kB With provenance Details for nighthawk_python-0.19.0.tar.gz

Built distribution (wheel)

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

Total release size: 822.8 kB

Release files / nighthawk_python-0.19.0.tar.gz

Download URL nighthawk_python-0.19.0.tar.gz
Size 673.0 kB
Tags Source
SHA-256 checksum
How to use checksums
643de34b2f53a5c7fbb4fe57a1fd1037ac05c794867cddcfd212c72b9e5bf9e8
BLAKE2b-256 checksum
How to use checksums
4880b796b048fead5119030a7cb5f58e6bc737460d7b1678fde9020218bd3587
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 Nov 4, 2026.

Transparency log

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

Download URL nighthawk_python-0.19.0-py3-none-any.whl
Size 149.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3fab65f476b4074081b0784e73bcf8bde9fa64befd6b9d4e5ce5d2692062727b
BLAKE2b-256 checksum
How to use checksums
0616e5e9a912124e0969d7d0d450e397e6cea21a79bbb527835ddecbd9f3db75
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 Nov 4, 2026.

Transparency log

Security for nighthawk-python 0.19.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.19.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 Nov 4, 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