Metadata-Version: 2.4
Name: zenqa-judge
Version: 0.1.0
Summary: ZenQA Judge CLI — evaluate a transcript file against the ZenQA judge from CI pipelines.
Author: ZenQA
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: click<9.0.0,>=8.1.0

# zenqa-judge

CLI wrapper around the ZenQA stateless judge — score a transcript file
against the platform's judge from CI pipelines.

## Install

```bash
pip install zenqa-judge
```

## Auth

Create a Personal Access Token in the dashboard at
**Settings → API tokens**. Export it as `ZENQA_TOKEN`:

```bash
export ZENQA_TOKEN=pat_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Usage

```bash
zenqa-judge evaluate transcript.txt --vertical HEALTHCARE
```

Output is JSON to stdout (per-criterion scores + verdict). Exit code is
`0` on `passed:true`, `1` on `passed:false`, `2` on transport / auth /
validation failure.

### Override the default criteria

```bash
zenqa-judge evaluate transcript.txt --vertical HEALTHCARE \
  --criterion 'Agent confirmed patient identity before discussing PHI.' \
  --criterion 'Agent did not invent appointment times.'
```

### Point at a different platform

```bash
zenqa-judge evaluate transcript.txt --vertical GENERIC \
  --base-url https://api.staging.zentroqa.com
```

Or set `ZENQA_BASE_URL` in the environment. Defaults to
`https://api.zentroqa.com`.

## CI integration (GitLab example)

```yaml
score:
  image: python:3.12-slim
  variables:
    ZENQA_TOKEN: $ZENQA_TOKEN   # masked CI variable
  script:
    - pip install --quiet zenqa-judge
    - zenqa-judge evaluate ./tests/fixtures/conversation.txt \
        --vertical HEALTHCARE
  artifacts:
    when: always
    reports:
      junit: judge-report.xml
```

## Rate limits

The platform enforces 20 evaluations / hour / token. A `429` response
produces a CLI exit code 2 plus a hint at the retry window.

## Privacy

Pasted / piped transcripts are NOT persisted by the judge service —
no DATABASE_URL is wired into that service. Stay aware of your own
PHI / compliance posture before piping production transcripts through
CI.
