Metadata-Version: 2.4
Name: nighthawk-python
Version: 0.7.0
Summary: A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
Project-URL: Repository, https://github.com/kurusugawa-computer/nighthawk-python
Project-URL: Documentation, https://kurusugawa-computer.github.io/nighthawk-python/
Project-URL: Changelog, https://github.com/kurusugawa-computer/nighthawk-python/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/kurusugawa-computer/nighthawk-python/issues
Author-email: "Kurusugawa Computer Inc." <oss@kurusugawa.jp>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,dsl,llm,natural-language,openai,prompt-engineering,pydantic-ai,structured-output
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: headson>=0.16.1
Requires-Dist: pydantic-ai-slim>=1.68
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Requires-Dist: tenacity>=9
Requires-Dist: tiktoken>=0.12
Provides-Extra: claude-code-cli
Requires-Dist: mcp>=1.26; extra == 'claude-code-cli'
Provides-Extra: claude-code-sdk
Requires-Dist: claude-agent-sdk==0.1.48; extra == 'claude-code-sdk'
Provides-Extra: codex
Requires-Dist: mcp>=1.26; extra == 'codex'
Description-Content-Type: text/markdown

[![PyPI](https://img.shields.io/pypi/v/nighthawk-python)](https://pypi.org/project/nighthawk-python)
[![PyPI Stats](https://img.shields.io/pypi/dm/nighthawk-python)](https://pypistats.org/packages/nighthawk-python)
[![license](https://img.shields.io/github/license/kurusugawa-computer/nighthawk-python.svg)](https://github.com/kurusugawa-computer/nighthawk-python/blob/main/LICENSE)
[![issue resolution](https://img.shields.io/github/issues-closed-raw/kurusugawa-computer/nighthawk-python)](https://github.com/kurusugawa-computer/nighthawk-python/issues)

# Nighthawk

<div align="center">
<img src="https://github.com/kurusugawa-computer/nighthawk-python/raw/main/docs/assets/nighthawk_logo-128x128.png" alt="nighthawk-logo" width="128px" margin="10px"></img>
</div>

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](https://kurusugawa-computer.github.io/nighthawk-python/philosophy/)** for the full design rationale.

This repository is a compact reimplementation of the core ideas of [Nightjar](https://github.com/psg-mit/nightjarpy).

## Installation

Prerequisites: Python 3.13+

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

For other providers, see [Pydantic AI providers](https://kurusugawa-computer.github.io/nighthawk-python/pydantic-ai-providers/).

## Example

```py
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](https://kurusugawa-computer.github.io/nighthawk-python/quickstart/)** for setup details, credentials, and troubleshooting.

## Documentation

- **[Quickstart](https://kurusugawa-computer.github.io/nighthawk-python/quickstart/)** -- Setup and first example.
- **[Natural blocks](https://kurusugawa-computer.github.io/nighthawk-python/natural-blocks/)** -- Block anatomy, bindings, functions, and writing guidelines.
- **[Executors](https://kurusugawa-computer.github.io/nighthawk-python/executors/)** -- Choose an execution backend.
- **[Runtime configuration](https://kurusugawa-computer.github.io/nighthawk-python/runtime-configuration/)** -- Scoping, patching, context limits, and execution identity.
- **[Patterns](https://kurusugawa-computer.github.io/nighthawk-python/patterns/)** -- Outcomes, async, composition, resilience, and common mistakes.
- **[Verification](https://kurusugawa-computer.github.io/nighthawk-python/verification/)** -- Mock tests, integration tests, and OpenTelemetry tracing.
- **[Pydantic AI providers](https://kurusugawa-computer.github.io/nighthawk-python/pydantic-ai-providers/)** -- LLM provider configuration.
- **[Coding agent backends](https://kurusugawa-computer.github.io/nighthawk-python/coding-agent-backends/)** -- Claude Code and Codex integration.
- **[Specification](https://kurusugawa-computer.github.io/nighthawk-python/specification/)** -- Canonical specification.
- **[API Reference](https://kurusugawa-computer.github.io/nighthawk-python/api/)** -- Auto-generated API documentation.
- **[For coding agents](https://kurusugawa-computer.github.io/nighthawk-python/for-coding-agents/)** -- Development guide for coding agents (LLMs) building Python projects with Nighthawk.
- **[Philosophy](https://kurusugawa-computer.github.io/nighthawk-python/philosophy/)** -- Design rationale and positioning.
- **[Roadmap](https://kurusugawa-computer.github.io/nighthawk-python/roadmap/)** -- Future directions.

## Development & Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, development commands, and contribution guidelines.

## References

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