hyperapi-demo / app.py
nchhaya's picture
Summary: Correct launch offer terms (Starter $1/month + 1,000 extra pages with HYPRAPI1K)
6b97d2d verified
Raw History Blame Contribute Delete
16.2 kB
"""
HyperAPI live demo (Hugging Face Space).
Try the five HyperAPI operations (classify, parse, extract, redact, split) on your own file or on
samples from the Hyperbots synthetic datasets. Calls are made server-side with the Space secret
HYPERAPI_KEY; the key never reaches the browser.
Built to put almost no load on the API:
* one API call at a time for the whole Space (global lock + Gradio queue with concurrency 1)
* at least MIN_INTERVAL seconds between API calls (default 65, matching the Free plan's 1 request/min)
* daily caps on API calls and billable pages (DAILY_CALLS, DAILY_PAGES), reset at midnight UTC
* a cool-down per visitor (VISITOR_COOLDOWN seconds)
* files up to 5 MB, PDFs up to 3 pages; results and upload keys are cached, so repeat runs make no API calls
* HyperAPI's own 24 h result cache is never bypassed (no force_refresh)
* on 401/402/403 the demo pauses itself for the day; on 429 it backs off
"""
import hashlib, json, os, re, threading, time, datetime
import requests
API = os.environ.get("HYPERAPI_BASE", "https://apis.hyperbots.com").rstrip("/")
HF = os.environ.get("HF_DATASETS_BASE", "https://huggingface.co/datasets/hyperbots-inc").rstrip("/")
KEY = os.environ.get("HYPERAPI_KEY", "").strip()
MIN_INTERVAL = float(os.environ.get("MIN_INTERVAL", "65"))
DAILY_CALLS = int(os.environ.get("DAILY_CALLS", "40"))
DAILY_PAGES = int(os.environ.get("DAILY_PAGES", "20"))
VISITOR_COOLDOWN = int(os.environ.get("VISITOR_COOLDOWN", "180"))
MAX_BYTES = 5 * 1024 * 1024
MAX_PDF_PAGES = 3
UA = "hyperapi-hf-demo/1.0"
OPS = {
"Classify": ("/v1/classify", {}),
"Parse": ("/v1/parse", {"mode": "fast", "include_image": "false"}),
"Extract (invoice / receipt)": ("/v1/extract", {}),
"Extract (your JSON schema)": ("/v1/extract", {"category": "non_financial"}),
"Redact PII": ("/v1/redact", {"mode": "redact", "output": "urls"}),
"Split bundle": ("/v1/split", {}),
}
# ------------------------------------------------------------------ guardrails
class Guard:
def __init__(self):
self.lock = threading.Lock()
self.last_call = 0.0
self.day = None
self.calls = 0
self.pages = 0
self.paused_reason = None
self.visitors = {}
self.result_cache = {} # (sha, op, schema) -> result dict
self.key_cache = {} # sha -> (document_key, expires_at)
def _roll_day(self):
today = datetime.datetime.utcnow().date()
if self.day != today:
self.day, self.calls, self.pages, self.paused_reason, self.visitors = today, 0, 0, None, {}
def status(self):
self._roll_day()
wait = max(0, int(self.last_call + MIN_INTERVAL - time.time())) if self.last_call else 0
return {"api_calls_today": self.calls, "daily_call_cap": DAILY_CALLS, "pages_today": self.pages, "daily_page_cap": DAILY_PAGES,
"seconds_until_next_call": wait, "paused": self.paused_reason}
def admit(self, visitor, pages_needed, calls_needed):
self._roll_day()
if not KEY:
return "The demo isn't configured yet (no HYPERAPI_KEY secret). Try the free sandbox at https://apis.hyperbots.com/sandbox."
if self.paused_reason:
return "The demo is paused for today (%s). Try the sandbox at https://apis.hyperbots.com/sandbox." % self.paused_reason
if self.calls + calls_needed > DAILY_CALLS or self.pages + pages_needed > DAILY_PAGES:
return "Today's demo budget is used up. Get a free key (30 pages/month) at https://apis.hyperbots.com/dashboard/register or try again tomorrow."
last = self.visitors.get(visitor, 0)
if time.time() - last < VISITOR_COOLDOWN:
return "Please wait %d s before your next run (fair use for everyone)." % (VISITOR_COOLDOWN - (time.time() - last))
return None
def call(self, method, path, paced=True, **kw):
"""One throttled HTTP call to HyperAPI. Caller must hold self.lock.
paced=False is used only for the operation call that follows this run's own upload."""
gap = time.time() - self.last_call
if paced and self.last_call and gap < MIN_INTERVAL:
time.sleep(MIN_INTERVAL - gap)
headers = kw.pop("headers", {})
headers.update({"X-API-Key": KEY, "User-Agent": UA})
try:
r = requests.request(method, API + path, headers=headers, timeout=150, **kw)
finally:
self.last_call = time.time()
self.calls += 1
if r.status_code in (401, 402, 403):
self.paused_reason = "HTTP %d from the API" % r.status_code
if r.status_code == 429:
ra = r.headers.get("Retry-After", "")
self.last_call = time.time() + (float(ra) if ra.replace(".", "").isdigit() else 120)
return r
GUARD = Guard()
def count_pdf_pages(data):
return max(1, len(re.findall(rb"/Type\s*/Page(?!s)", data)))
def run_operation(file_bytes, filename, op, schema_text, visitor="anon"):
"""Returns (summary_markdown, result_json, image_url_or_None)."""
if op not in OPS:
return "Unknown operation.", {}, None
if not file_bytes:
return "Upload a file or pick an example first.", {}, None
if len(file_bytes) > MAX_BYTES:
return "Files are limited to 5 MB in this demo.", {}, None
is_pdf = file_bytes[:5] == b"%PDF-"
pages = count_pdf_pages(file_bytes) if is_pdf else 1
if pages > MAX_PDF_PAGES:
return "PDFs are limited to %d pages in this demo (yours has %d)." % (MAX_PDF_PAGES, pages), {}, None
schema = None
if op == "Extract (your JSON schema)":
try:
schema = json.dumps(json.loads(schema_text or ""))
except ValueError:
return "The schema must be valid JSON, for example {\"policy_number\": null, \"claimant_name\": null}.", {}, None
sha = hashlib.sha256(file_bytes).hexdigest()
ck = (sha, op, schema)
if ck in GUARD.result_cache:
res = GUARD.result_cache[ck]
return summarize(op, res) + "\n\n_Served from the demo cache: no API call was made._", res, redacted_image(op, res)
content_type = "application/pdf" if is_pdf else ("image/png" if file_bytes[:4] == b"\x89PNG" else "image/jpeg")
kc = GUARD.key_cache.get(sha)
need_upload = not (kc and kc[1] > time.time())
with GUARD.lock:
msg = GUARD.admit(visitor, pages, 2 if need_upload else 1)
if msg:
return msg, GUARD.status(), None
GUARD.visitors[visitor] = time.time()
if need_upload:
r = GUARD.call("POST", "/v1/documents/upload", json={"filename": filename or ("upload.pdf" if is_pdf else "upload.jpg"), "content_type": content_type, "content_length": len(file_bytes)})
if r.status_code >= 300:
return "Upload request failed (HTTP %d). Please try later." % r.status_code, safe_json(r), None
meta = r.json()
put = requests.put(meta["upload_url"], data=file_bytes, headers={"Content-Type": content_type, "x-amz-server-side-encryption": "AES256"}, timeout=150)
if put.status_code >= 300:
return "Upload to storage failed (HTTP %d)." % put.status_code, {}, None
GUARD.key_cache[sha] = (meta["document_key"], time.time() + 23 * 3600)
doc_key = GUARD.key_cache[sha][0]
path, params = OPS[op]
form = {"document_key": doc_key}
if schema:
form["schema"] = schema
r = GUARD.call("POST", path, paced=not need_upload, params=params, files={k: (None, v) for k, v in form.items()})
res = safe_json(r)
if r.status_code >= 300:
return "The API returned HTTP %d. %s" % (r.status_code, "The demo has been paused for today." if GUARD.paused_reason else "Please try again later."), res, None
GUARD.pages += pages
GUARD.result_cache[ck] = res
return summarize(op, res), res, redacted_image(op, res)
def safe_json(r):
try:
return r.json()
except ValueError:
return {"status_code": r.status_code, "body": r.text[:500]}
def redacted_image(op, res):
if op != "Redact PII":
return None
pages = (res.get("result") or {}).get("pages") or []
return pages[0].get("image_url") if pages else None
def summarize(op, res):
r = res.get("result") or {}
meta = "\n\n`request_id` %s 路 model `%s` 路 %s ms" % (res.get("request_id"), res.get("model_used"), res.get("duration_ms"))
if op == "Classify":
lab = r.get("label") or r.get("document_type") or r.get("raw_label") or "unclassified"
lab = str(lab).replace("_", " ").title()
review = " 路 flagged for review" if r.get("needs_review") else ""
lines = ["**%s** (confidence %s%s)" % (lab, str(r.get("confidence") or "n/a").replace("_", " "), review)] + ["- %s: %s" % (c.get("label"), c.get("confidence")) for c in (r.get("candidates") or [])[:5]]
return "\n".join(lines) + meta
if op == "Parse":
ocr = r.get("ocr") or ""
return "**%d characters** of text across %d page(s).\n\n```\n%s\n```" % (len(ocr), len(r.get("pages") or []), ocr[:1500]) + meta
if op.startswith("Extract"):
ents = r.get("entities") if isinstance(r.get("entities"), dict) else r
rows = ["| Field | Value |", "|---|---|"] + ["| %s | %s |" % (k, json.dumps(v) if isinstance(v, (dict, list)) else v) for k, v in list(ents.items())[:40]]
li = r.get("line_items") or []
return "\n".join(rows) + ("\n\n%d line item(s)." % len(li) if li else "") + meta
if op == "Redact PII":
s = r.get("summary") or {}
return "Masked: " + (", ".join("%s 脳 %s" % (k, v) for k, v in s.items()) or "nothing found") + "\n\n```\n%s\n```" % (r.get("updated_text_block") or "")[:1200] + meta
if op == "Split bundle":
sp = ((r.get("segmentation") or {}).get("splits")) or []
return "\n".join(["| # | Type | Pages | Confidence |", "|---|---|---|---|"] + ["| %d | %s | %s-%s | %s |" % (i + 1, s.get("split_label"), s.get("start_page"), s.get("end_page"), s.get("confidence")) for i, s in enumerate(sp)]) + meta
return "Done." + meta
# ------------------------------------------------------------------ examples from the Hub datasets
EXAMPLES = [
("Stamped invoice", "synthetic-stamped-documents", "Extract (invoice / receipt)", lambda r: r["doc_type"] == "invoice"),
("Handwritten KYC form", "synthetic-handwritten-forms", "Extract (your JSON schema)", lambda r: r["doc_type"] == "kyc_form"),
("Bill of lading (classify)", "synthetic-doc-classification", "Classify", lambda r: r["doc_type"] == "bill_of_lading"),
("Patient intake form (redact)", "synthetic-pii-redaction", "Redact PII", lambda r: r["doc_type"] == "patient_intake_form"),
("Severely degraded scan (parse)", "synthetic-bad-scans", "Parse", lambda r: r["severity"] == "severe"),
]
EX_CACHE = {}
def load_example(name):
if name in EX_CACHE:
return EX_CACHE[name]
title, repo, op, pick = next(e for e in EXAMPLES if e[0] == name)
meta = requests.get("%s/%s/resolve/main/data/test/metadata.jsonl" % (HF, repo), headers={"Range": "bytes=0-600000", "User-Agent": UA}, timeout=60).text
row = None
for line in meta.split("\n")[:-1]:
try:
rr = json.loads(line)
except ValueError:
continue
if pick(rr):
row = rr; break
img = requests.get("%s/%s/resolve/main/data/test/%s" % (HF, repo, row["file_name"]), timeout=60).content
schema = ""
if op == "Extract (your JSON schema)":
gold = json.loads(row.get("labels") or "{}")
schema = json.dumps({k: None for k in list(gold.keys())[:12]}, indent=1)
path = "/tmp/" + row["file_name"]
with open(path, "wb") as f:
f.write(img)
gold_note = "Gold label: **%s**" % row.get("taxonomy_name", row.get("doc_type"))
EX_CACHE[name] = (path, op, schema, gold_note + " 路 from [%s](%s/%s)" % (repo, HF, repo))
return EX_CACHE[name]
# ------------------------------------------------------------------ UI
def build():
import gradio as gr
intro = """# 馃Ь HyperAPI live demo
Try **parse, extract, classify, split and redact** on an enterprise document. Upload a PDF or image (up to 5 MB, 3 pages) or pick a synthetic example.
This shared demo is rate-limited (one call at a time, daily caps), so a run can take about a minute. To test on your own files at your own pace, [get a free key](https://apis.hyperbots.com/dashboard/register?utm_source=huggingface&utm_medium=demo_space&utm_campaign=hyperapi_hf) or use the [sandbox](https://apis.hyperbots.com/sandbox?utm_source=huggingface&utm_medium=demo_space&utm_campaign=hyperapi_hf).
馃巵 **Launch offer: HyperAPI Starter is $1 a month** (300 pages a month), and code `HYPRAPI1K` adds 1,000 extra pages in your first month. [Get started](https://apis.hyperbots.com/pricing?utm_source=huggingface&utm_medium=demo_space&utm_campaign=hyperapi_hf&utm_content=promo_1k).
**Evaluating HyperAPI for production?** [Request a proof of concept](https://www.hyperbots.com/request-demo?utm_source=huggingface&utm_medium=demo_space&utm_campaign=hyperapi_hf) and we score it field by field on a sample of your real documents.
[HyperAPI on Hugging Face](https://huggingface.co/hyperbots-inc) 路 [Docs](https://apis.hyperbots.com/docs?utm_source=huggingface&utm_medium=demo_space&utm_campaign=hyperapi_hf) 路 [Open datasets](https://huggingface.co/collections/hyperbots-inc/hyperapi-enterprise-document-intelligence-6af6c8764547d894d4e1a3c4)"""
def on_example(name):
path, op, schema, note = load_example(name)
return path, op, schema, note
RESULT_CTA = (
"\n\n---\n**Want this on your own documents?** "
"[Start at $1 a month, plus 1,000 extra pages with code HYPRAPI1K](https://apis.hyperbots.com/pricing?utm_source=huggingface&utm_medium=demo_space&utm_campaign=hyperapi_hf&utm_content=promo_1k) or "
"[request a proof of concept](https://www.hyperbots.com/request-demo?utm_source=huggingface&utm_medium=demo_space&utm_campaign=hyperapi_hf) on a sample of your real files."
)
def on_run(file, op, schema, request: gr.Request):
if file is None:
return "Upload a file or pick an example first.", {}, None, GUARD.status()
path = file if isinstance(file, str) else file.name
with open(path, "rb") as f:
data = f.read()
visitor = hashlib.sha256(((request.client.host if request and request.client else "anon") + "hyperapi").encode()).hexdigest()[:16]
md, js, img = run_operation(data, os.path.basename(path), op, schema, visitor)
if js:
md = (md or "") + RESULT_CTA
return md, js, img, GUARD.status()
with gr.Blocks(title="HyperAPI live demo") as demo:
gr.Markdown(intro)
with gr.Row():
with gr.Column(scale=1):
ex = gr.Dropdown([e[0] for e in EXAMPLES], label="Pick an example (synthetic data)", value=None)
note = gr.Markdown()
file = gr.File(label="鈥r upload a PDF / image", file_types=[".pdf", ".png", ".jpg", ".jpeg"], type="filepath")
op = gr.Radio(list(OPS.keys()), value="Classify", label="Operation")
schema = gr.Code(label="JSON schema (for 'Extract (your JSON schema)')", language="json", value='{"policy_number": null, "claimant_name": null, "date_of_service": null, "amount_claimed": null}')
run = gr.Button("Run", variant="primary")
status = gr.JSON(label="Demo budget", value=GUARD.status())
with gr.Column(scale=1):
out_md = gr.Markdown(label="Result")
out_img = gr.Image(label="Redacted page", visible=True)
out_json = gr.JSON(label="Raw JSON response")
ex.change(on_example, ex, [file, op, schema, note])
run.click(on_run, [file, op, schema], [out_md, out_json, out_img, status], concurrency_limit=1)
demo.queue(default_concurrency_limit=1, max_size=8)
return demo
if os.environ.get("HYPERAPI_DEMO_NO_UI") != "1":
build().launch()