# Programme Pulse

A small Flask app for chatting with live Airtable programme data and generating two-tier status reports (Manager Summary + Full Report) as Word documents.

Runs locally on port 5051 by default.

---

## What it does

- Loads tasks from one Airtable base (the Master tracker) and resource bookings from a second Airtable base.
- Lets you chat with the data through Claude. Streaming response, stop button, thumbs up/down feedback.
- Reads `.docx` meeting transcripts from `docs/Programme Pulse transcripts/` and uses them as supporting context.
- Generates two reports on demand: a Manager Summary and a Full Report. Both saved as `.docx` in `reports/`.
- Saves your stated preferences to `data/preferences.md` so future sessions remember them.

---

## Requirements

- Python 3.11 or newer
- An Anthropic API key
- Two Airtable bases with personal access tokens

---

## Setup

1. Create and activate a virtual environment.

   ```sh
   python3 -m venv .venv
   source .venv/bin/activate
   ```

2. Install dependencies.

   ```sh
   pip install -r requirements.txt
   ```

3. Copy the example env file and fill in your own keys.

   ```sh
   cp .env.example .env
   ```

   Open `.env` and add:
   - `ANTHROPIC_API_KEY`
   - `PULSE_AIRTABLE_API_KEY`, `PULSE_AIRTABLE_BASE_ID`, `PULSE_AIRTABLE_TABLE_ID` — the tasks base
   - `PULSE_RESOURCE_API_KEY`, `PULSE_RESOURCE_BASE_ID`, `PULSE_RESOURCE_TABLE_ID` — the resource booking base
   - `FLASK_SECRET_KEY` — any random string

4. Run the app.

   ```sh
   python web_app.py
   ```

   Or with gunicorn (recommended — streaming works better):

   ```sh
   gunicorn web_app:app --bind 0.0.0.0:5051 --worker-class gevent --workers 1 --timeout 300
   ```

5. Open http://localhost:5051 in your browser.

---

## Adding meeting transcripts

Drop Teams `.docx` transcript exports into `docs/Programme Pulse transcripts/`. The app picks them up on restart and feeds them to the chat and the reports as supporting narrative.

Each `.docx` is parsed paragraph by paragraph. One speaker turn per paragraph.

---

## Folder layout

```
web_app.py                 Flask entry point
src/
  airtable_client.py       Pulls tasks and bookings from Airtable
  analyzer.py              Health signal logic
  claude_client.py         Anthropic SDK wrapper, streaming
  preferences.py           Saves liked/disliked patterns
  prompts.py               System prompts and snapshot builders
  reporter.py              Word document generation
  transcripts.py           Parses .docx meeting transcripts
templates/index.html       The single-page UI
design/                    Fonts and design tokens
data/                      preferences.md lives here
docs/Programme Pulse transcripts/   Drop .docx files here
reports/                   Generated Word files land here
logs/                      Runtime logs
tests/                     Pytest suite
```

---

## Airtable schema notes

The tasks base must include these fields (rename the constants in `src/airtable_client.py` if your column names differ):
- Title / task name
- Owner (collaborator)
- Status / Progress
- Priority
- Due date
- Notes
- Last modified

The resource base needs:
- Resource name
- Project
- Division
- Start date, end date
- Hours
- Status
- Conflict flag

Open `src/airtable_client.py` to map field names to your own base.

---

## Running tests

```sh
pytest
```

---

## Deploying elsewhere

The app is stateless apart from `data/preferences.md`, `reports/`, and `logs/`. Mount those as volumes if you containerise it. The `Procfile` is set up for any platform that respects it (Heroku, Render, Fly, etc).

Set `PORT` via env var. Everything else is read from `.env` or the platform's secret store.