Spaces:
Running on Zero
Running on Zero
Download returnguard/service.py from RajTheBuilder/ReturnGuard: direct link, hf CLI and curl.
- Browser
- Download file 10.1 kB
-
https://huggingface.co/spaces/RajTheBuilder/ReturnGuard/resolve/main/returnguard/service.py
- Command line
-
hf download hf://spaces/RajTheBuilder/ReturnGuard/returnguard/service.py
-
curl -L -o service.py https://huggingface.co/spaces/RajTheBuilder/ReturnGuard/resolve/main/returnguard/service.py
10.1 kB
| """Application services behind the web API: customer accounts, delivery registration | |
| (the order is created at delivery time), asynchronous return processing with an audit | |
| trail, and an on-demand Gemini second opinion.""" | |
| import logging | |
| import re | |
| from concurrent.futures import ThreadPoolExecutor | |
| from datetime import datetime, timedelta, timezone | |
| from PIL import Image, UnidentifiedImageError | |
| from returnguard import config, imaging, llm, pipeline, storage | |
| from returnguard.agents import identity, inspector | |
| from returnguard.embeddings import view_features | |
| from returnguard.explain import llm_error_text | |
| log = logging.getLogger(__name__) | |
| _executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="return-pipeline") | |
| EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[A-Za-z]{2,}$") | |
| class InputError(ValueError): | |
| """Bad request data; the message is safe to show to the user.""" | |
| class ForbiddenError(InputError): | |
| """The signed-in customer may not act on this resource.""" | |
| # ββ customer accounts ββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def normalize_email(email: str) -> str: | |
| email = (email or "").strip().lower() | |
| if not EMAIL_RE.match(email): | |
| raise InputError("Enter a valid email address.") | |
| return email | |
| def normalize_phone(phone: str) -> str: | |
| digits = re.sub(r"\D", "", phone or "") | |
| if len(digits) == 12 and digits.startswith("91"): | |
| digits = digits[2:] | |
| elif len(digits) == 11 and digits.startswith("0"): | |
| digits = digits[1:] | |
| if len(digits) != 10: | |
| raise InputError("Enter a 10-digit mobile number.") | |
| return digits | |
| def sign_up(email: str, phone: str) -> dict: | |
| email, phone = normalize_email(email), normalize_phone(phone) | |
| if storage.find_customer_by_email(email): | |
| raise InputError("An account with this email already exists. Sign in instead.") | |
| return storage.create_customer(email, phone) | |
| def sign_in(email: str, phone: str) -> dict: | |
| email, phone = normalize_email(email), normalize_phone(phone) | |
| customer = storage.find_customer_by_email(email) | |
| if customer is None or customer["phone"] != phone: | |
| raise InputError("No account matches this email and phone number.") | |
| return customer | |
| def public_customer(c: dict) -> dict: | |
| return {"customer_id": c["customer_id"], "email": c["email"], "phone": "β’β’β’β’β’β’" + c["phone"][-4:], | |
| "created_at": c["created_at"]} | |
| # ββ images on disk βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def _load_all(files: dict) -> dict: | |
| images = {} | |
| for angle in config.ANGLES: | |
| data = files.get(angle) | |
| if not data: | |
| raise InputError("All three photos (front, back, side) are required.") | |
| try: | |
| images[angle] = imaging.load_image(data) | |
| except (UnidentifiedImageError, OSError): | |
| raise InputError(f"The {angle} upload is not a readable image.") | |
| return images | |
| def order_dir(order_id: int): | |
| return config.IMAGE_DIR / "orders" / str(order_id) | |
| def return_dir(order_id: int, return_id: int): | |
| """Return photos live inside their order: data/images/orders/<order_id>/returns/<return_id>/.""" | |
| return order_dir(order_id) / "returns" / str(return_id) | |
| def _save(images: dict, cutouts: dict, folder): | |
| folder.mkdir(parents=True, exist_ok=True) | |
| for angle in config.ANGLES: | |
| images[angle].save(folder / f"{angle}.jpg", "JPEG", quality=90) | |
| cutouts[angle].save(folder / f"{angle}_cutout.png") | |
| # ββ delivery βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def register_delivery(files: dict, customer_id: str, product_name: str, category: str, | |
| delivered_days_ago: int = 0, on_stage=None) -> dict: | |
| """on_stage(key, detail) is called as each step starts, so the UI can show live progress.""" | |
| stage = on_stage or (lambda key, detail="": None) | |
| if category not in config.RETURN_WINDOW_DAYS: | |
| raise InputError(f"Unknown category '{category}'.") | |
| images = _load_all(files) | |
| cutouts = {} | |
| for i, a in enumerate(config.ANGLES, 1): | |
| stage("background", f"{a} view ({i}/{len(config.ANGLES)})") | |
| cutouts[a] = imaging.remove_background(images[a]) | |
| stage("quality", "blur and framing") | |
| quality = {a: imaging.assess_quality(images[a], cutouts[a]) for a in config.ANGLES} | |
| bad = [f"{a.capitalize()}: {q.problem}" for a, q in quality.items() if not q.ok] | |
| if bad: | |
| raise InputError(" ".join(bad)) | |
| features = {} | |
| for i, a in enumerate(config.ANGLES, 1): | |
| stage("embeddings", f"{a} view ({i}/{len(config.ANGLES)})") | |
| features[a] = view_features(cutouts[a]).to_dict() | |
| stage("save", "") | |
| delivered_at = (datetime.now(timezone.utc) - timedelta(days=max(0, delivered_days_ago))).isoformat(timespec="seconds") | |
| order_id = storage.create_order(customer_id, product_name, category, delivered_at, features) | |
| _save(images, cutouts, order_dir(order_id)) | |
| stage("labels", f"order #{order_id}") | |
| try: | |
| fp, rec = identity.fingerprint(cutouts) | |
| fingerprint = fp.model_dump() | |
| except llm.LLMError as err: | |
| log.warning("fingerprint unavailable for order %s: %s", order_id, err) | |
| fingerprint, rec = None, err.record | |
| storage.set_fingerprint(order_id, fingerprint) | |
| storage.add_audit(order_id, None, "delivery_registered", { | |
| "quality": {a: q.__dict__ for a, q in quality.items()}, "fingerprint": fingerprint, "llm_call": rec.to_dict()}) | |
| order = storage.get_order(order_id, with_features=False) | |
| order["fingerprint_error"] = None if fingerprint else llm_error_text(rec.error) | |
| return order | |
| # ββ return βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def start_return(order_id: int, files: dict, reason: str, customer_id: str) -> int: | |
| order = storage.get_order(order_id) | |
| if order is None: | |
| raise InputError(f"Order #{order_id} does not exist. Register the delivery first.") | |
| if order["customer_id"] != customer_id: | |
| raise ForbiddenError(f"Order #{order_id} belongs to another customer. Sign in with that account to return it.") | |
| if reason not in config.RETURN_REASONS: | |
| raise InputError("Choose a return reason from the list.") | |
| images = _load_all(files) | |
| return_id = storage.create_return(order_id, reason) | |
| folder = return_dir(order_id, return_id) | |
| folder.mkdir(parents=True, exist_ok=True) | |
| for angle, img in images.items(): | |
| img.save(folder / f"{angle}.jpg", "JPEG", quality=90) | |
| _executor.submit(_process_return, return_id, order, images, reason) | |
| return return_id | |
| def _delivery_cutouts(order_id: int) -> dict: | |
| return {a: Image.open(order_dir(order_id) / f"{a}_cutout.png").convert("RGBA") for a in config.ANGLES} | |
| def _process_return(return_id: int, order: dict, images: dict, reason: str): | |
| try: | |
| result, state = pipeline.run(order, _delivery_cutouts(order["order_id"]), images, reason, return_id=return_id, | |
| on_progress=lambda node: storage.add_progress(return_id, node)) | |
| folder = return_dir(order["order_id"], return_id) | |
| for angle, cut in state["return_cutouts"].items(): | |
| cut.save(folder / f"{angle}_cutout.png") | |
| for stage in ("quality", "policy", "history", "screen", "identity", "inspection", "decision"): | |
| if result.get(stage) is not None: | |
| storage.add_audit(order["order_id"], return_id, stage, result[stage]) | |
| storage.add_audit(order["order_id"], return_id, "llm_calls", {"calls": result["llm_calls"]}) | |
| d = result["decision"] | |
| storage.finish_return(return_id, d["decision"], d["risk_score"], result) | |
| except Exception as err: # never leave a return stuck in PROCESSING | |
| log.exception("return %s failed", return_id) | |
| storage.finish_return(return_id, "ERROR", None, None, error=f"{type(err).__name__}: {err}") | |
| def second_opinion(return_id: int, customer_id: str) -> dict: | |
| """Run the visual inspector on a finished return that didn't need it. Informational: | |
| the original decision and its audit trail stay unchanged.""" | |
| ret = storage.get_return(return_id) | |
| if ret is None or not ret["result"]: | |
| raise InputError("This return has not finished processing yet.") | |
| if ret["customer_id"] != customer_id: | |
| raise ForbiddenError("This return belongs to another customer.") | |
| folder = return_dir(ret["order_id"], return_id) | |
| if not (folder / "front_cutout.png").exists(): | |
| raise InputError("The return photos for this return are not available.") | |
| order = storage.get_order(ret["order_id"], with_features=False) | |
| returned = {a: Image.open(folder / f"{a}_cutout.png").convert("RGBA") for a in config.ANGLES} | |
| reason_text = config.RETURN_REASONS.get(ret["reason"], ret["reason"]) | |
| try: | |
| insp, rec = inspector.inspect(_delivery_cutouts(ret["order_id"]), returned, order.get("fingerprint"), | |
| order["category"], reason_text) | |
| opinion = {"ok": True, "inspection": insp.model_dump(), "call": rec.to_dict()} | |
| except llm.LLMError as err: | |
| opinion = {"ok": False, "error": err.record.error, "call": err.record.to_dict()} | |
| result = ret["result"] | |
| result["second_opinion"] = opinion | |
| storage.update_result(return_id, result) | |
| storage.add_audit(ret["order_id"], return_id, "second_opinion", opinion) | |
| return opinion | |