(tools/reports)=
# Activity Reports

QuantEcon is adopting **semi-automation** workflows that summarise activity across the
organization and draft content for review. These are deliberately *human-in-the-loop*: the
automation generates a report, an issue, or a draft pull request, and a maintainer reviews
(and edits) it before anything is published. Nothing is auto-published.

The automation lives in:

**[QuantEcon/reports-activity](https://github.com/QuantEcon/reports-activity)**

The repository ships a GitHub Action (`action.yml`) wrapping an org-agnostic
`generate-report.sh` engine, plus the scheduled workflows described below. There are two
tracks built on the same engine — an **internal reporting** track and a **public news** track.
The repository README and `docs/` hold the full operational detail.

## What it tracks

For every repository in the organization, over a chosen time window, the engine collects:

- Open issues (snapshot) and issues opened / closed in the period
- Pull requests opened / merged in the period
- Direct commits and releases
- Per-repository activity summaries, with external repositories optionally tracked

Each run also emits a structured `report-data.json` for downstream tooling, and can produce a
curated `highlights.md` (theme-grouped notable items, a noise rollup, and a split between
software releases and lecture publishes).

## Internal status reports

These cover **all** organization activity (including internal repositories) and record the
results inside the `reports-activity` repository.

| Workflow | Cadence | Output |
|---|---|---|
| `weekly-report.yml` | Weekly (Sun 08:00 UTC) | Opens an issue in `reports-activity` with the `status-report` label |
| `monthly-report.yml` | Monthly (1st, 06:00 UTC) | Opens a PR archiving `reports/<YYYY-MM>-monthly/` |

## Public news drafts

A separate **public-only** track drafts posts for [quantecon.org/news](https://quantecon.org/news/)
and opens them as a **draft pull request against [QuantEcon/website](https://github.com/QuantEcon/website)**
for editorial review — news is public and must never publish automatically. Because this track is
public-only it structurally cannot read private org repositories, so private activity can never
reach a public draft.

| Workflow | Cadence | Output |
|---|---|---|
| `news-weekly.yml` | Weekly (Sun 08:55 UTC) | Draft PR to `QuantEcon/website` covering lecture/book publishes and quantecon.org changes |
| `news-watch.yml` | Daily | Draft PR announcing any library release from the previous day |

Lecture and book posts are *publish-anchored* — a site appears only in the period it actually
cut a `publish-*` release (i.e. went live), with the updated material linked underneath. Library
releases are treated as events and picked up by the daily watcher rather than held for the weekly
digest.

## LLM narratives

Both tracks can use Claude to draft short, human-readable summaries (the report
`highlights` narrative and the per-site news summaries). This requires an organization
`ANTHROPIC_API_KEY`. For the internal reports the narrative is optional — highlights still render
without it. For the **news** track it is required (`--require-llm`): if the key is missing or
unusable the drafter writes nothing and the workflow opens an alert issue rather than drafting a
rough, non-LLM fallback post.

## Authentication

Each workflow uses the **least-privilege** credential it needs, so scopes stay minimal:

- **Reading private org repos** (internal track) uses a short-lived token minted from an
  org-owned GitHub App with read-only `Contents` / `Metadata` / `Pull requests` access.
- **Posting back** into `reports-activity` (the weekly issue, the monthly PR) uses the default
  repo-scoped `GITHUB_TOKEN`.
- **Opening the website PR** (news track) uses a separate App installed on `QuantEcon/website`
  only, with `Contents` + `Pull requests: write`.

```{seealso}
- {ref}`GitHub Actions Workflows <tools/github-actions>` — the CI/CD automation behind lecture and
  manual builds.
- {ref}`Repository Backups <tools/backups>` — the other organization-level automation.
- For full configuration, CLI options, and the secret setup, see the
  [reports-activity README](https://github.com/QuantEcon/reports-activity#readme) and its
  [`docs/`](https://github.com/QuantEcon/reports-activity/tree/main/docs).
```