# Lightning Report Service

Tiny FastAPI wrapper around `create_docx_report()`. Lets the n8n workflow produce reports that are **byte-identical** to the CLI (`batch_generate.py`) output, since it uses the same code path.

## Why this exists

n8n 2.x's self-hosted Python Code node runs in a sandbox that strips common builtins (`hasattr`, `getattr`, etc.) and restricts imports, making it impossible to host the 3,500+ line reporting pipeline in a node. This service runs outside the sandbox and is called over HTTP.

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/health` | Liveness probe |
| `POST` | `/generate` | Accepts the `Report: Build Payload` JSON, returns a DOCX binary |

### Request body for `/generate`

Mirrors the `Report: Build Payload` Set node. Required keys:

```json
{
  "customer_name": "Example Wind Farm",
  "timezone": "Europe/Istanbul",
  "centroid_lat": 40.5,
  "centroid_lon": 29.7,
  "boundary_m": 20000,
  "rings": { "r1": 2000, "r2": 4000, "r3": 6000, "r4": 8000 },
  "ring_colors": ["#B71C1C", "#F94144", "#F8961E", "#90BE6D"],
  "t_start": 1729000000000,
  "t_end":   1729010000000,
  "n_strikes": 1234,
  "strikes":  [ { "latitude": ..., "longitude": ..., "peakCurrent": ..., "type": "0", "captured": "2026-04-22T13:00:00Z" } ],
  "turbines": [ { "name": "T1", "latitude": ..., "longitude": ..., "unit_power_mwm": 3.6, ... } ],

  "gemini_text": "optional — if provided, used verbatim; else the service calls Gemini or falls back",
  "storm_records": [ { "cell_polygon_wkt": "POLYGON(...)", "lightning_severity": "medium", "effective_time": "...", "expire_time": "..." } ]
}
```

The adapter is forgiving about column names: it accepts `lat`/`latitude`, `lng`/`longitude`/`lon`, `current`/`peakCurrent`/`peak_current`, `p_type`/`type`, `local_time`/`captured`/`timestamp`.

### Response

- `Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document`
- `Content-Disposition: attachment; filename="<slug>_<start>_<end>_report.docx"`
- Headers: `X-Report-Filename`, `X-Report-Customer`, `X-Report-Strikes`

## Running locally

```bash
cd lightning_report
python -m pip install -r requirements.txt -r report_service/requirements.txt
uvicorn report_service.main:app --host 0.0.0.0 --port 8000
```

Sanity check:

```bash
curl -sS http://127.0.0.1:8000/health
```

## Running with Docker (alongside n8n)

```bash
cd lightning_report
docker compose -f report_service/docker-compose.yml up --build -d
docker logs -f lightning-report-service
```

The compose file attaches the service to an external network named `n8n`. Check your actual network name with `docker network ls` and adjust the `name:` field if needed. Once attached, the n8n container can reach the service at `http://report-service:8000`.

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `LOG_LEVEL` | `INFO` | Uvicorn/service log level |
| `GEMINI_API_KEY` | _(unset)_ | Only used if n8n doesn't send `gemini_text` in the payload. If unset, the service falls back to the deterministic commentary in `src/reporting/gemini_commentary.py` |
| `GEMINI_MODEL` | `gemini-1.5-flash` | Only used when the service calls Gemini itself |

## n8n configuration

In the n8n workflow, the `Report: Generate DOCX` HTTP Request node points at:

```
={{ $env.REPORT_SERVICE_URL || 'http://report-service:8000' }}/generate
```

- If n8n and the service share a Docker network, the default hostname works.
- Otherwise, set `REPORT_SERVICE_URL` as an n8n environment variable (e.g. `http://192.168.1.10:8000`).

Response format is set to `file` with output property `report`, which the downstream Slack node uploads directly.

## Gemini commentary handoff

The existing n8n branch already has a `Report: Gemini Commentary` HTTP Request node that calls Gemini. Its text is forwarded to this service as `gemini_text`. When present, the service skips its own Gemini call and plugs the text straight into `create_docx_report()`'s commentary slot via a scoped monkey-patch on `generate_gemini_paragraph`.

If you'd rather let the service handle Gemini end-to-end, you can delete the `Report: Gemini Commentary` node from the n8n workflow and point `Report: Build Payload` directly at `Report: Fetch Thunderstorms`.