Nighthawk

Nighthawk is an experimental Python library exploring a clear separation:

• Use hard control (Python code) for strict procedure, verification, and deterministic flow.
• Use soft reasoning (an LLM or coding agent) for semantic interpretation inside small embedded "Natural blocks".

Python controls all flow; the LLM or coding agent is constrained to small Natural blocks with explicit input/output boundaries. 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 Providers.

Example

import nighthawk as nh

step_executor = nh.AgentStepExecutor.from_configuration(
    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-mini")
)

with nh.run(step_executor):

    @nh.natural_function
    def calculate_total(items: str) -> int:
        total = 0
        """natural
        Read <items> and set <:total> to the sum of all quantities mentioned.
        """
        return total

    print(calculate_total("three apples, a dozen eggs, and 5 oranges"))
    # => 20

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

Documentation

• Quickstart — Setup and first example.
• Tutorial — Learn from first principles.
• Practices — Guidelines, patterns, and testing.
• Providers — LLM providers and configuration.
• Coding agent backends — Claude Code and Codex integration.
• Philosophy — Design rationale and positioning.
• Design — Canonical specification.
• API Reference — Auto-generated API documentation.
• 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