hailer 0.1.1__tar.gz

hailer-0.1.1/.config/hailer/README.md

@@ -0,0 +1,43 @@
+# Project context for Hailer
+
+This folder holds the context, skills and prompts that Hailer gives to the AI agent for
+**this** project. Commit it alongside the notebook so the whole team gets the same setup.
+
+```
+.config/hailer/
+├── hailer.toml   (optional: the project config can live here instead of the repo root)
+├── context/      always-on: every *.md here is sent to the model at the start of each session
+├── skills/       on-demand: <name>/SKILL.md (+ reference/, scripts/) loaded only when needed
+└── prompts/      reusable prompts: /prompt <name> [args]
+```
+
+## context/
+
+Short Markdown files with facts the agent should always know: what the datasets are, column
+meanings, conventions, house style. Files are loaded in filename order (prefix with `00-`,
+`10-` to control it) and concatenated up to the `max_context_bytes` limit in `hailer.toml`.
+
+**Everything in `context/` is sent to the configured model endpoint every session.** Do not
+put credentials, customer data or anything you would not paste into a chat with the model.
+Hailer warns at startup if a file looks like it contains a key or token.
+
+## skills/
+
+Skills use the Agent Skills format shared by Codex and Claude: a folder with a `SKILL.md`
+whose frontmatter has `name` and `description`, plus optional `reference/` and `scripts/`.
+Hailer puts only the name and description in the agent's instructions; the body is loaded
+when the task matches (the agent calls `load_skill`) or when you type `/skill <name>`.
+
+Write the `description` as the trigger: *when* to use the skill and *what* it produces.
+
+## prompts/
+
+Plain Markdown prompts. `{{args}}` is replaced with whatever follows the name:
+
+```
+You > /prompt monthly-pack 2025-06
+```
+
+## Reloading
+
+`/reload` re-reads this folder without restarting the session. `/context` shows what is loaded.

hailer-0.1.1/.config/hailer/context/00-example.md

@@ -0,0 +1,30 @@
+# PRA101 analysis: team context
+
+> This file is sent to the model endpoint at the start of every Hailer session.
+> Keep it factual and short. No credentials, no customer names, no row-level data.
+
+## What the data is
+
+- Monthly extracts of the PRA101 (capital+) return, one Parquet file per month in `data/`.
+- Filenames encode the period as `YY-MM`, e.g. `25-03 pra101.parquet` is March 2025.
+  The data itself has **no** period column; Hailer adds one when loading several months.
+- Later months may add columns. Treat a missing column in an older month as null, not an error.
+
+## Column meanings
+
+| column | meaning |
+|---|---|
+| `exposure_class` | Regulatory exposure class: Corporate, Retail, Institution, Sovereign, Equity, Other |
+| `counterparty_id` | Anonymised counterparty key; stable across months |
+| `default_flag` | `true` when the exposure is in default. "Exclude defaults" means `default_flag == false` |
+| `exposure_value` | Exposure at default in GBP |
+| `rwa` | Risk-weighted assets in GBP |
+| `risk_weight` | Effective risk weight (`rwa / exposure_value`); present from 2025-04 onwards |
+
+## Conventions
+
+- "Latest month" means the most recent period present in `data/`, not the calendar month.
+- Month-on-month movement is `latest - previous`; percentages are relative to the previous month.
+- Report RWA in £m with one decimal (e.g. £1,234.5m). Keep tables to the top 10 rows unless asked.
+- Prefer Polars; use DuckDB SQL when joining across many monthly files.
+- Charts: bar for breakdowns by class, line for trends over periods. Label axes with units.

hailer-0.1.1/.config/hailer/prompts/monthly-pack.md

@@ -0,0 +1,17 @@
+Produce the monthly PRA101 pack for period {{args}} (use the latest period if none is given).
+
+In the marimo notebook, add or update these sections, reusing existing variables and cells
+where they already exist:
+
+1. **Periods available**: a small table of the months found in `data/` and their row counts.
+2. **Headline**: total RWA and exposure value for the period and the previous month, with
+   movement in £m and %.
+3. **Movement by exposure class**: table sorted by absolute movement, plus a bar chart.
+4. **Top 10 movers**: counterparties with the largest absolute RWA movement between the two
+   months (join on `counterparty_id`), showing both months and the movement.
+5. **Data quality notes**: rows with null `exposure_class`, negative `rwa`, or
+   `exposure_value == 0`, counted per month.
+
+Then reply in the terminal with a five-line summary: total movement, the largest driver, the
+second-largest driver, anything unusual in the data-quality notes, and what you added to the
+notebook. Do not paste tables into the terminal.

hailer-0.1.1/.config/hailer/skills/example-skill/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pra101-month-on-month
+description: >-
+  Compare the two latest PRA101 months and explain what drives the RWA movement,
+  producing a movement table, an exposure-class breakdown and a chart in the marimo
+  notebook. Use when the user asks what changed, what is driving RWA, or for a
+  month-on-month comparison.
+---
+
+# PRA101 month-on-month movement
+
+## When to use
+
+The user asks any of: "compare the latest two months", "what's driving the RWA increase",
+"break the movement down by exposure class", "show me the biggest movers".
+
+## Steps
+
+1. `list_periods` to confirm which months exist and whether columns differ between them.
+2. In the notebook, reuse the existing `files`/`df` variables if a previous turn created them
+   (`notebook_cells` shows what exists). Otherwise create one cell that loads all months with
+   `load_periods(scan_period_files(DATA_DIR, "pra101"))` and keeps the `period` column.
+3. Create (or edit) a cell `mom` that aggregates `rwa` and `exposure_value` by `period` and
+   `exposure_class`, pivots the latest two periods side by side, and adds `movement` and
+   `movement_pct` columns. Sort by absolute movement, descending.
+4. Create a cell that shows `mom` with `mo.ui.table`, and a cell with a bar chart of
+   `movement` by `exposure_class` (Altair via `mo.ui.altair_chart`, or `df.plot`).
+5. If the user says "exclude defaults", filter `default_flag == False` in the loading cell and
+   let the dependent cells re-run; do not create a second copy of the pipeline.
+6. Run the checks in `reference/checks.md` before summarising.
+7. In the terminal, give a two-sentence summary (largest driver, total movement in £m and %),
+   then list what was added to the notebook.
+
+## Notebook hygiene
+
+- One owning cell per public name (`files`, `df`, `mom`, `chart`); edit the owner, never redefine.
+- Use `_` prefixed names for intermediates.
+- Keep `hide_code=False` for analysis cells so the user can read the code.

hailer-0.1.1/.config/hailer/skills/example-skill/reference/checks.md

@@ -0,0 +1,15 @@
+# Reconciliation checks for a month-on-month comparison
+
+Run these in the scratchpad (not as notebook cells) before summarising. Print only the
+check name and pass/fail with the numbers involved.
+
+1. **Totals reconcile.** Sum of `movement` across exposure classes equals
+   `total_rwa(latest) - total_rwa(previous)` to within £1.
+2. **No period leakage.** The `period` column only contains the two periods being compared.
+3. **Class coverage.** Every `exposure_class` present in either month appears in the table;
+   a class missing from one month shows 0 for that month, not null.
+4. **Defaults handled consistently.** If defaults are excluded, both months are filtered with
+   the same predicate (`default_flag == False`); state the number of rows excluded per month.
+5. **Schema evolution.** If a column exists only in the latest month (e.g. `risk_weight`),
+   do not use it in the comparison unless the user asks; mention it once in the summary.
+6. **Sign convention.** `movement > 0` means RWA increased in the latest month.

hailer-0.1.1/.github/workflows/members-only.yml

@@ -0,0 +1,37 @@
+# Close pull requests from outside the organization.
+#
+# GitHub has no setting that stops people opening pull requests on a public
+# repository, so this closes pull requests from outsiders, leaving a short comment.
+#
+# A pull request is kept when its head branch lives in this repository (only people
+# with write access can push one, so forks are the only route for outsiders) or when
+# GitHub reports the author as OWNER, MEMBER or COLLABORATOR. The branch check comes
+# first because the event payload only reports MEMBER for *public* org memberships;
+# a member whose membership is private shows up as CONTRIBUTOR or NONE, which is
+# how this workflow once closed a member's own pull request.
+#
+# pull_request_target runs on the base branch with a write token. It never checks
+# out or runs code from the pull request, so that token is not exposed to it.
+
+name: Members only
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  guard:
+    name: Close pull requests from non-members
+    if: ${{ github.event.pull_request.head.repo.full_name != github.repository && !contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.pull_request.author_association) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment and close
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          gh pr comment "$PR" --repo "$GITHUB_REPOSITORY" --body "Thanks for the interest. This repository only accepts pull requests from members of the OpenAfterHours organization, so this one has been closed automatically. Please open an issue to discuss the change instead."
+          gh pr close "$PR" --repo "$GITHUB_REPOSITORY"

hailer-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+# Publish a release to PyPI.
+#
+# Triggered by the vX.Y.Z tag that `uv run python -m scripts.release` pushes after the
+# tests pass locally. Runs the test suite again on every supported platform
+# (test.yml) and builds the sdist and wheel; only if both succeed does it publish
+# through the "pypi" environment using PyPI trusted publishing (OIDC, no API token
+# to store) and then create the GitHub release with the distributions attached.
+#
+# PyPI's trusted publisher for this project is configured as:
+#   owner OpenAfterHours, repository hailer, workflow release.yml, environment pypi.
+# Renaming this file or the environment breaks publishing.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests
+    uses: ./.github/workflows/test.yml
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.1.0 # setup-uv publishes no floating major tag
+        with:
+          python-version: "3.12"
+
+      - name: Check that the tag matches the package version
+        id: version
+        run: |
+          version="$(uv version --short --color never)"
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match the pyproject.toml version ${version}"
+            exit 1
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: [test, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hailer/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write # mint the OIDC token PyPI trusted publishing exchanges for an upload token
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub release
+    needs: [build, publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create the release with the distributions attached
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          flags=()
+          case "$VERSION" in
+            *[a-z]*) flags+=(--prerelease) ;;
+          esac
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "hailer $VERSION" \
+            --generate-notes \
+            "${flags[@]}"

hailer-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,39 @@
+# Run the test suite.
+#
+# Runs on pushes to main and on pull requests, and is called by release.yml so a
+# release cannot be published to PyPI unless the suite passes on every platform
+# here. The suite is offline (no API key, marimo server, Codex process or network).
+
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pytest (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.1.0 # setup-uv publishes no floating major tag
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+
+      - name: Install the project and the dev dependencies
+        run: uv sync --locked
+
+      - name: Run the tests
+        run: uv run --locked pytest

hailer-0.1.1/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+
+# uv / virtualenv
+.venv/
+uv.lock.bak
+
+# Hailer runtime state (thread ids, logs) — never commit
+.hailer/
+*.log
+
+# Data files stay local
+data/*
+!data/.gitkeep
+!data/README.md
+
+# marimo
+__marimo__/
+.marimo/
+
+# Secrets — never commit
+.env
+*.key
+*.pem
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db