# Privoid Action — local inference API

A minimal FastAPI service (`privoid_action_api/`) that serves the Action adapter on the original Granite base, or a
validated merged model, from **local files only**.

## Run

```powershell
cd Privoid-Action-1B
copy api\config.example.json api\config.json      # then set adapter_path to this repository's root folder
python -m privoid_action_api --config api\config.json --check-config
python -m privoid_action_api --config api\config.json
```

* Binds to `127.0.0.1:8095` by default. Any non-loopback host is refused unless `allow_non_loopback: true` is set.
* Startup sets `HF_HUB_OFFLINE=1` / `TRANSFORMERS_OFFLINE=1` before any Hugging Face import and loads with
  `local_files_only=True`. It never downloads, trains or prepares data. If artifacts are missing or invalid, the server
  still starts, `/health` reports `model_state: "unavailable"`, and `/extract` returns 503.
* The loader refuses adapters whose base is not Granite 4.0 1B.
* The model loads at startup (`load_on_startup: true`). One generation runs at a time (`max_concurrent: 1`, sized for
  a 12 GB GPU), with up to `max_queue` requests waiting.

## Endpoints

### `GET /health`
Process health. Never loads or downloads anything.
```json
{"status": "ok", "model_state": "ready", "request_id": "3f1c0a9e5b7d2c41"}
```
`model_state` is one of `not_loaded`, `loading`, `ready`, `unavailable`.

### `GET /model-info`
Model identity (base ID and revision, adapter folder name and a short weight hash), schema version, and limits
(`max_prompt_tokens`, `max_new_tokens`, `max_body_bytes`, timeout, concurrency, contract limits). Filesystem paths are
not exposed.

### `POST /extract`
Body: one transcript segment in the input schema (`docs/SCHEMA.md` §1). Example requests are in `examples/`:

```powershell
curl.exe -s -X POST http://127.0.0.1:8095/extract -H "content-type: application/json" `
     --data-binary "@examples/request_accepted_request.json"
```

Response 200 (abridged; the full illustrative response is in `examples/response_accepted_request.json`. It was produced
by the deterministic finalizer from a hand-written output, **not** by the model):
```json
{
  "request_id": "…", "schema_version": "1.0",
  "result": {
    "schema_version": "1.0", "meeting_id": "meeting-001",
    "actions": [{
      "id": "A1", "task": "Send the revised proposal.", "owner_speaker_ids": ["S2"], "owner_text": "Omar",
      "assignment_status": "accepted", "deadline_text": "Friday", "conditions": [], "status": "active",
      "evidence": [{"turn_id": "T1", "quote": "Omar, can you send the revised proposal by Friday?"},
                   {"turn_id": "T2", "quote": "Yes, I will send it by Friday."}],
      "needs_review": false, "review_reasons": [], "pipeline_flags": ["deadline_not_normalized"],
      "owner_names": ["Omar"], "deadline_normalized": null,
      "deadline_normalization": {"rule": null, "reason": "bare_weekday_ambiguous"}}],
    "decisions": [], "unresolved_requests": [], "rejected_records": []},
  "validation": {"raw_output_fully_valid": true, "rejected_record_count": 0, "grounded_record_count": 0},
  "usage": {"prompt_tokens": 882, "seconds": 1.9},
  "model": {"backend": "transformers", "base_model_id": "ibm-granite/granite-4.0-1b", "…": "…"},
  "notice": "Records are extracted from the transcript for human review. They do not create tasks, …"
}
```
(The `seconds` value above is a placeholder, not a measurement.)

### `POST /extract-meeting` (experimental, disabled by default)
Enable with `enable_meeting_endpoint: true`. The endpoint cuts the meeting into whole-turn segments
(`max_segment_tokens`, `segment_overlap_turns`), extracts each segment, and reconciles the results with the documented
rules (`docs/SCHEMA.md` §5). The response is marked `"experimental": true` and includes `segments`,
`reconciliation_log`, `limitations`, `segment_failures` and `complete`. Its quality is measured separately (notebook
§10.5). Cross-segment cancellations are flagged, not applied.

## Errors

All errors are JSON: `{"error": code, "message": text, "request_id": id, …}`. They never contain stack traces or
filesystem paths.

| Status | `error` | When |
|---|---|---|
| 400 | `invalid_json` | Body is not JSON |
| 413 | `input_too_large` | Body > `max_body_bytes`, a contract size limit, or prompt tokens > `max_prompt_tokens`. **Nothing is truncated**; split the transcript. |
| 422 | `invalid_input` | Schema problems (unknown speaker, duplicate turn ID, invalid date or timezone, control sequences …), listed in `problems` |
| 429 | `busy` | All slots busy and the wait queue is full |
| 502 | `model_output_invalid` | The model output was not one schema-valid JSON object. No records are returned and none are invented. |
| 503 | `model_unavailable` | Model not loaded (see the server log) |
| 504 | `timeout` | Generation exceeded `request_timeout_s`. Generation is also bounded by `max_new_tokens` and a matching `max_time`, and the slot stays occupied until the worker thread really finishes. |
| 500 | `internal_error` | Unexpected failure (details only in the server log, keyed by request ID) |

A record that fails validation (quote not found, unknown speaker, inconsistent status) is returned in
`result.rejected_records` with its errors, and `validation.raw_output_fully_valid` is `false`. Valid records are still
returned.

With `ground_evidence: true` (the default), quotes that the model tidied (fillers or repeated words dropped) or
attached to a neighbouring turn are first re-anchored to the transcript's verbatim words; see `docs/SCHEMA.md` §2.5.
Every record changed this way carries a pipeline flag, and `validation.grounded_record_count` counts them. Set
`ground_evidence: false` to reject such records instead.

## Privacy behaviour

* Transcript bodies are never logged and never written to disk. Log lines carry the request ID, path, status, latency,
  turn count, prompt-token count and validation counts only. Uvicorn's access log is disabled.
* No cloud fallback exists. The only network listener is the configured local address.
* Validation, and any constrained decoding a client might add, ensures the output is well-formed. It is **not proof of
  semantic correctness**: owners, statuses and deadlines must still be reviewed by a human before anyone acts on them.
* Extracted records never send messages, create tasks in external systems, or commit participants to anything.

Privacy of a deployment also depends on the surrounding application, its logs and storage, the host OS and its
telemetry, and the network configuration. Those are outside this API.

## Tests

`python -m unittest discover -s tests -t .` runs the API tests against a **mocked** backend. They cover every route,
error code, oversize rejection, invalid-output rejection, record-level rejection, timeouts, the concurrency bound, a full
queue (429), hidden internal errors, the loopback-only default, no transcript text in logs, and a check that importing
the API does not import torch/transformers/peft/trl. Real-model checks are in notebook §12 (`ALLOW_API_CHECKS`).