nighthawk-python 0.1.0__tar.gz

nighthawk_python-0.1.0/.claude/rules/coding.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "src/**/*.py"
+  - "tests/**/*.py"
+---
+
+# Coding standards
+
+- Avoid premature abstraction: new abstractions must be used by code in `src/` or `tests/` in the same change. Docs examples do not count.
+- Keep identifiers module-private (leading underscore) until clearly used from outside in non-test code. Export intentionally via `__all__`.
+- Pydantic-first: depend on Pydantic and Pydantic AI as required (non-optional) dependencies. Use `pydantic.BaseModel` and built-in features aggressively. Do not reimplement what either library provides (validation, coercion, parsing, schema, agent/tool abstractions).
+- Observability: `opentelemetry.trace` for spans at run/scope/step/tool boundaries. `logging` (logger `"nighthawk"`) for diagnostics. No `logfire` imports in `src/`; it is dev-only.
+- Type aliases: PEP 695 `type` statements for new type aliases.
+- No unnecessary subdirectories under `src/`. Do not add folders with only `__init__.py` + a single class without maintainer buy-in.

nighthawk_python-0.1.0/.claude/rules/docs.md

@@ -0,0 +1,104 @@
+---
+paths:
+  - "docs/**/*.md"
+---
+
+# Documentation rules
+
+## File roles and boundaries
+
+Each file has a distinct audience and scope. Content belongs in exactly one file; cross-reference rather than duplicate. Exception: `for-coding-agents.md` is standalone and condenses (distills) content from other files into actionable rules. This is distillation, not duplication.
+
+| File | Audience | Role | Scope boundary |
+|---|---|---|---|
+| `index.md` | First-time visitors | Project overview, motivation, workflow styles | What Nighthawk is and why. No API details, no how-to. |
+| `quickstart.md` | New users | Shortest path to running a Natural block | Setup, first example, backends table, credentials, troubleshooting. No deep explanations. |
+| `tutorial.md` | Users learning the system | Build understanding from first principles | Bindings, tools, control flow, composition, configuration, guidelines. Assumes quickstart is done. |
+| `design.md` | Implementors and advanced users | Canonical specification (target behavior) | Full technical detail: syntax rules, state layers, prompt rendering, tool contracts, outcome schema, frontmatter. |
+| `providers.md` | Users choosing and configuring models | Provider selection, Pydantic AI setup, custom backends | Provider categories, capability matrix, model identifiers, Pydantic AI model settings, step executor protocols. No coding-agent-backend-specific content. |
+| `coding-agent-backends.md` | Users of Claude Code or Codex backends | Coding agent backend configuration and features | Backend-specific settings, skills, MCP tool exposure, working directory, project-scoped files. |
+| `for-coding-agents.md` | Coding agents (LLMs) working on Nighthawk projects | Condensed development knowledge base | Nighthawk mental model, Natural block writing, binding function design, control flow, composition, testing, common mistakes. Not a human tutorial; an LLM reference. |
+| `api.md` | Developers using the library | Auto-generated API reference (mkdocstrings) | Public API surface only. Content comes from source docstrings; do not hand-edit. |
+| `roadmap.md` | Contributors and planners | Future directions | Ideas and desired directions only. Must not restate what is already implemented. |
+
+## What goes where (decision guide)
+
+- **Syntax rule or runtime contract?** -> `design.md`
+- **How to use a feature with examples?** -> `tutorial.md`
+- **Provider selection, Pydantic AI settings, or custom step executor?** -> `providers.md`
+- **Coding agent backend settings, skills, MCP, or working directory?** -> `coding-agent-backends.md`
+- **Backend-agnostic concept that applies across all providers?** -> `tutorial.md` (or `design.md` for strict contracts)
+- **First-time setup or "just make it work"?** -> `quickstart.md`
+- **Credential or authentication setup?** -> `quickstart.md` (Pydantic AI providers), `coding-agent-backends.md` (coding agent backends)
+- **Error types or exception hierarchy?** -> `design.md` (specification), `tutorial.md` (practical usage with examples)
+- **Not yet implemented?** -> `roadmap.md`
+- **Public API signature or docstring?** -> `api.md` (edit the source docstring, not api.md)
+- **Knowledge a coding agent needs to develop Nighthawk code?** -> `for-coding-agents.md`
+
+## Writing guidelines for docs/
+
+### General
+
+- Cross-reference with relative links (e.g., `[Section 5](tutorial.md#5-cross-block-composition)`) instead of duplicating content. Exception: `for-coding-agents.md` uses absolute URLs based on `site_url` from `mkdocs.yml` (see [for-coding-agents.md specifics](#for-coding-agentsmd-specifics)).
+- When tutorial.md and design.md cover the same concept, tutorial.md shows the "what and how" with examples; design.md specifies the "exact rules and edge cases".
+- Keep code examples self-contained: a reader should understand the example without reading surrounding prose.
+- Built-in tool names (`nh_eval`, `nh_exec`, `nh_assign`) are implementation details. Only `design.md` may expose them. All other files describe behavior instead (e.g., "the LLM can set a new value" rather than "use `nh_assign`").
+
+### index.md specifics
+
+- The documentation links list must stay in sync with the `nav` entries in `mkdocs.yml`.
+
+### quickstart.md specifics
+
+- Optimize for copy-paste. A new user should be able to run the first example within minutes.
+- Keep troubleshooting entries to common first-run errors only.
+
+### tutorial.md specifics
+
+- Assumes the reader has completed quickstart.md. Do not re-explain setup beyond a brief reminder.
+- Every section should teach one concept. Combine related ideas only when they share an example.
+- `<!-- prompt-example:name -->` markers are test anchors verified by `tests/docs/test_prompt_examples.py`. Never modify the content between a marker pair without updating the corresponding test.
+- Keep tutorial content backend-agnostic. Do not document backend-specific file layouts, provider credentials, or backend initialization variants here.
+- If a concept needs backend-specific setup, add a short pointer to `providers.md` or `coding-agent-backends.md` instead of duplicating configuration details.
+
+### design.md specifics
+
+- This is the specification. Implementation should match this document; if they diverge, prefer changing the implementation (see Section 0.1 alignment policy).
+- Use precise, unambiguous language. Avoid hedging ("usually", "typically") for specified behavior.
+- Structure: numbered sections, decision notes, implementation notes. Keep the hierarchy stable; other docs link to specific section anchors.
+
+### providers.md specifics
+
+- The capability matrix must clearly show which features require a coding agent backend.
+- Prefer concise, runnable setup snippets over conceptual narrative; link to `tutorial.md` for concept-first explanations.
+- For custom backends, show the recommended path (`AgentStepExecutor.from_agent`) first, then the direct protocol implementation as an alternative.
+- Credential details are not placed here. Pydantic AI provider credentials are delegated to the Pydantic AI documentation via external links.
+
+### coding-agent-backends.md specifics
+
+- Document shared capabilities (skills, MCP, working directory) once in a shared section, then keep per-backend sections focused on differences.
+- For external CLI integrations, separate:
+  - what Nighthawk configures and guarantees, and
+  - what is delegated to backend CLI rules.
+- Include a settings field table for each backend with type, default, and description columns.
+
+### for-coding-agents.md specifics
+
+- The reader is a coding agent (LLM), not a human. Write for immediate applicability, not progressive learning.
+- Condense principles from tutorial.md, design.md, and writing guidelines into actionable rules. Do not duplicate prose; distill into decision rules and patterns.
+- Include runnable code templates the agent can adapt directly.
+- Keep the "common mistakes" table current; add entries when recurring issues are observed.
+- This file should be self-contained: a coding agent reading only this file should be able to write correct Nighthawk code without consulting other docs.
+- This file is consumed standalone (`@docs/for-coding-agents.md` in CLAUDE.md/AGENTS.md, GitHub raw URL, etc.). Do not assume sibling files exist at relative paths.
+- All external references to other docs use absolute URLs based on `site_url` from `mkdocs.yml` (currently `https://kurusugawa-computer.github.io/nighthawk-python/`). If `site_url` changes, update the URLs in this file.
+
+### api.md specifics
+
+- Content comes from source docstrings. Edit the source code, not api.md directly.
+- Hand-editing is limited to `:::` directive structure (adding/removing sections, adjusting member filters).
+- When the same module appears in multiple sections, use `members` filters in `:::` directives to partition members and avoid duplicate rendering.
+
+### roadmap.md specifics
+
+- Future-facing only. Remove items once they are implemented.
+- Avoid implementation details; describe intent and motivation.

nighthawk_python-0.1.0/.claude/unset_envs.sh

@@ -0,0 +1,3 @@
+unset ANTHROPIC_API_KEY
+unset ANTHROPIC_AUTH_TOKEN
+unset ANTHROPIC_BASE_URL

nighthawk_python-0.1.0/.devcontainer/Dockerfile.devcontainer

@@ -0,0 +1,3 @@
+FROM mcr.microsoft.com/devcontainers/python:2-3.13-bookworm
+RUN curl -fsSL https://dl.yarnpkg.com/debian/pubkey.gpg \
+  | sudo gpg --batch --yes --dearmor -o /usr/share/keyrings/yarn-archive-keyring.gpg

nighthawk_python-0.1.0/.devcontainer/Dockerfile.litellm

@@ -0,0 +1,11 @@
+FROM python:3.13-slim
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+RUN pip install --no-cache-dir 'litellm[proxy]'
+EXPOSE 4000
+ENTRYPOINT [ \
+  "litellm", \
+  "--config", "/litellm-config.yaml", \
+  "--host", "0.0.0.0", \
+  "--port", "4000" \
+]

nighthawk_python-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+	"name": "Python 3.13 with Claude Code CLI",
+	"dockerComposeFile": "docker-compose.yaml",
+	"service": "devcontainer",
+	"workspaceFolder": "/workspace",
+	"shutdownAction": "stopCompose",
+	"features": {
+		"ghcr.io/devcontainers/features/docker-in-docker:2": {},
+		"ghcr.io/devcontainers/features/node:1": {}
+	},
+	"postCreateCommand": "npm install -g pyright @openai/codex && pip install --no-cache-dir uv && curl -fsSL https://claude.ai/install.sh | bash",
+	"remoteEnv": {
+		"ANTHROPIC_BASE_URL": "http://litellm:4000",
+		"ANTHROPIC_AUTH_TOKEN": "sk-dummy"
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"charliermarsh.ruff",
+				"Anthropic.claude-code"
+			]
+		}
+	}
+}

nighthawk_python-0.1.0/.devcontainer/docker-compose.yaml

@@ -0,0 +1,19 @@
+services:
+  devcontainer:
+    container_name: nighthawk-devcontainer
+    build:
+      context: .
+      dockerfile: Dockerfile.devcontainer
+    volumes:
+      - ..:/workspace:cached
+    command: sleep infinity
+
+  litellm:
+    container_name: nighthawk-litellm
+    build:
+      context: .
+      dockerfile: Dockerfile.litellm
+    env_file:
+      - ../.env
+    volumes:
+      - ./litellm-config.yaml:/litellm-config.yaml:ro

nighthawk_python-0.1.0/.devcontainer/litellm-config.yaml

@@ -0,0 +1,37 @@
+model_list:
+  - model_name: gpt-5.4
+    litellm_params:
+      model: openai/gpt-5.4
+      api_key: os.environ/OPENAI_API_KEY
+      reasoning_effort: "high"
+      additional_drop_params: ["context_management", "output_config"]
+  - model_name: gpt-5.4-codex
+    litellm_params:
+      model: openai/gpt-5.4-codex
+      api_key: os.environ/OPENAI_API_KEY
+      reasoning_effort: "high"
+      additional_drop_params: ["context_management", "output_config"]
+  - model_name: gpt-5.3-codex
+    litellm_params:
+      model: openai/gpt-5.3-codex
+      api_key: os.environ/OPENAI_API_KEY
+      reasoning_effort: "high"
+      additional_drop_params: ["context_management", "output_config"]
+  - model_name: claude-opus-*
+    litellm_params:
+      model: openai/gpt-5.3-codex
+      api_key: os.environ/OPENAI_API_KEY
+      reasoning_effort: "high"
+      additional_drop_params: ["context_management", "output_config"]
+  - model_name: claude-sonnet-*
+    litellm_params:
+      model: openai/gpt-5.3-codex
+      api_key: os.environ/OPENAI_API_KEY
+      additional_drop_params: ["context_management", "output_config"]
+  - model_name: claude-haiku-*
+    litellm_params:
+      model: openai/gpt-5-mini
+      api_key: os.environ/OPENAI_API_KEY
+      additional_drop_params: ["context_management", "output_config"]
+litellm_settings:
+  drop_params: true

nighthawk_python-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly
+ - package-ecosystem: "github-actions"
+   directory: "/"
+   schedule:
+     interval: weekly

nighthawk_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  workflow_call:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint and type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run pyright
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    continue-on-error: ${{ matrix.python-version != '3.13' }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups
+
+      - name: Run tests
+        run: uv run pytest -q
+
+  build:
+    name: Build distribution
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/

nighthawk_python-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/nighthawk/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

nighthawk_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: CI
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: ci
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nighthawk-python
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nighthawk_python-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+.agents/
+.claude/docs/
+*.local.json
+.vscode/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

nighthawk_python-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13