README.md

---
title: Touchdown Compression Classifier
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---

# Touchdown Compression Classifier

Free CPU Hugging Face Space scaffold for the managed prompt compression API.

Phase 1 serves deterministic deletion-only compression with receipts. The
planned classifier backbone is `microsoft/deberta-v3-small`; the API reports
classifier status honestly until a trained KEEP/DROP head or ONNX export is
mounted.

Endpoints:

- `GET /health`
- `POST /v1/compress`
- `POST /v1/classify`

Live Space:

- `https://wchen22-touchdown-compression-classifier.hf.space`
- Verified 2026-06-11 with HF CLI: runtime stage `RUNNING`, hardware
  `cpu-basic`, domain `READY`, repo/runtime SHA
  `0dfe65a6c82c9e7fa37d2c4a32c8eda3ed4e96d7`.
- The deployed scaffold supports chunked ONNX artifact inference for long
  prompts. Use `hf spaces info wchen22/touchdown-compression-classifier --format
  json` for the current repo/runtime SHA.
- Live smoke:
  `python3 scripts/smoke_compression_api.py --base-url https://wchen22-touchdown-compression-classifier.hf.space --include-classify --include-batch --include-messages --include-gzip`
  validates `/health`, `/v1/classify`, single `/v1/compress`, and managed
  `inputs[]` batch, managed `messages[]`, plus gzipped JSON request/response
  transport.
- Real-corpus API benchmark:
  `python3 scripts/benchmark_compression_api.py --base-url https://wchen22-touchdown-compression-classifier.hf.space --input-jsonl benchmarks/prompts/real/kv_stress_seed.jsonl --limit 4 --tokenizer-model Qwen/Qwen2.5-7B-Instruct --require-exact-tokens`.
  This calls hosted `/v1/compress` over real prompt rows and fails the run if
  receipts return estimated token counts. Use this before claiming real-token
  savings.
- Full deployment receipt:
  `python3 scripts/verify_compression_space.py --expected-sha <sha> --out reports/generated/compression_space/hf_space_verification.json`
  validates HF runtime metadata, repo/runtime SHA agreement, API smoke, and
  remote/local Space file parity.
- Fresh local receipts are written under
  `reports/generated/compression_space/`; run the full verifier with the
  current Space SHA to check runtime, API smoke, and remote/local file parity.
  Current live receipt:
  `reports/generated/compression_space/hf_space_verification_2026-06-11-managed-messages.json`.
- Latest live result: `/v1/compress` saved 27/102 estimated tokens;
  managed `inputs[]` returned `input_count=2`, `succeeded=2`, `failed=0`,
  managed `messages[]` returned `message_count=2` with system-role protection,
  gzip transport returned `response_content_encoding=gzip`, and `/v1/classify`
  returned KEEP-only DeBERTa tokenizer labels. Receipts include
  removed-span/char totals, classifier DROP block reasons, tool-schema
  preservation counts when `tools` or `tool_schemas` are supplied, and
  `/health` idempotency TTL reporting.
  Matching `Idempotency-Key` retries replay the first in-memory response;
  payload conflicts return HTTP 409. This is per-process memory on the Space,
  not a durable distributed store.
  The HTTP surface accepts `Content-Encoding: gzip` request bodies and gzip
  responses for `Accept-Encoding: gzip` or gzipped requests. If an ingress
  strips the standard content-encoding header, also send
  `X-Touchdown-Content-Encoding: gzip`.
- `/v1/classify` is tokenizer/fallback KEEP-only until a trained KEEP/DROP head
  is mounted. `/v1/compress` is rules-first deletion-only compression with
  safety receipts. The Space app supports both single `input` requests and
  managed `inputs[]` batches with per-item receipts and partial-error rows.
  `/v1/compress` now accepts `tokenizer_model`; when the tokenizer loads,
  receipts report `token_count_exact=true`, `token_count_method=tokenizer`, and
  the requested model. If it cannot load, receipts remain estimated and the
  benchmark `--require-exact-tokens` gate fails.
- Mount `classifier_manifest.json`, tokenizer files, and optional `model.onnx`;
  set `TOUCHDOWN_CLASSIFIER_ARTIFACT_DIR` to let the Space use artifact DROP
  labels through ONNX Runtime or the manifest fallback. ONNX labels are
  evaluated in chunked windows using manifest `max_length` and `stride`; mounted
  ONNX labels expose `keep_score`, `drop_score`, and `drop_score_threshold`.
  DROP spans still pass through protected-span and deletion-only safety gates.

Deploy:

```bash
hf auth login
./deploy.sh <namespace>/touchdown-compression-classifier
```

Free CPU Spaces are enough for this scaffold; production traffic should move to
paid or owned infrastructure after validation.