README.md

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