""" 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="…or 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()