Nighthawk is an experimental Python library exploring a clear separation between hard control (Python code) for strict procedure and deterministic flow, and soft reasoning (an LLM) for semantic interpretation inside small embedded "Natural blocks". It is a compact reimplementation of the core ideas of Nightjar.

Prerequisites: Python 3.13+

Install Nighthawk and a provider:

pip install nighthawk-python pydantic-ai-slim[openai]

Save as quickstart.py:

import nighthawk as nh

step_executor = nh.AgentStepExecutor.from_configuration(
    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5-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"))

Run with your API key:

export OPENAI_API_KEY=sk-xxxxxxxxx
python quickstart.py
# => 20

For backends, credentials, model identifiers, and detailed guidance, see the documentation site.

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

• Nightjar (upstream concept): https://github.com/psg-mit/nightjarpy