Create geo_logging.py

geo_logging.py

@@ -0,0 +1,160 @@
+"""
+geo_logging.py
+----------------
+Purpose:
+    This module implements privacy-preserving telemetry for the
+    AI Recruiting Agent Hugging Face Space.
+
+    Its sole purpose is to measure anonymous usage and adoption
+    metrics in order to:
+      - Understand how the tool is being used
+      - Improve reliability and performance
+      - Gauge sense of real-world adoption
+      - Support research and evaluation of responsible AI practices
+
+Privacy Principles:
+    This module is explicitly designed to minimize data collection
+    and avoid storing any personally identifiable information (PII).
+
+    It DOES NOT collect or store:
+      - Raw IP addresses
+      - User names or Hugging Face account IDs
+      - Resume contents or job descriptions
+      - Emails, phone numbers, or file names
+      - Full user-agent strings or device fingerprints
+      - Any demographic attributes about users
+
+    It ONLY records:
+      - Approximate country and city (derived from IP, not stored)
+      - UTC timestamp of the event
+      - Space URL
+      - High-level event type (e.g., "app_open")
+      - Non-identifying, aggregate metadata (e.g., counts, booleans, latencies)
+
+    All usage logs are:
+      - Anonymized
+      - Append-only
+      - Persisted in a public Hugging Face Dataset repository (https://huggingface.co/datasets/19arjun89/ai_recruiting_agent_usage)
+      - Versioned via immutable commit history for auditability
+
+Ethical Safeguards:
+    - Logging failures never break application functionality
+    - No raw identifiers are persisted at any time
+    - All telemetry is optional and best-effort
+    - The system is intended for transparency and improvement,
+      not for surveillance or profiling
+
+Transparency:
+    A public-facing usage reporting Space will be provided to allow
+    independent verification of aggregate adoption metrics.
+
+Author:
+    Arjun Singh
+
+Last Updated:
+    2026-01-22
+"""
+
+
+import os
+import json
+from datetime import datetime
+import requests
+import gradio as gr
+from huggingface_hub import HfApi, hf_hub_url
+
+SPACE_URL = "https://huggingface.co/spaces/19arjun89/AI_Recruiting_Agent"
+USAGE_DATASET_REPO = "19arjun89/ai_recruiting_agent_usage"
+USAGE_JSONL_PATH = "usage/visits.jsonl"
+
+
+def _hf_api():
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        return None
+    return HfApi(token=token)
+
+
+def _download_text_if_exists(repo_id: str, path_in_repo: str) -> str:
+    try:
+        url = hf_hub_url(
+            repo_id=repo_id,
+            filename=path_in_repo,
+            repo_type="dataset"
+        )
+        r = requests.get(url, timeout=5)
+        if r.status_code == 200:
+            return r.text
+    except Exception:
+        pass
+    return ""
+
+
+def _get_client_ip(request: gr.Request) -> str:
+    if request:
+        xff = request.headers.get("x-forwarded-for")
+        if xff:
+            return xff.split(",")[0].strip()
+        if request.client:
+            return request.client.host
+    return ""
+
+
+def _geo_lookup(ip: str) -> dict:
+    try:
+        r = requests.get(f"https://ipapi.co/{ip}/json/", timeout=2)
+        if r.status_code == 200:
+            data = r.json()
+            return {
+                "country": data.get("country_name") or "Unknown",
+                "city": data.get("city") or "Unknown",
+            }
+    except Exception:
+        pass
+    return {"country": "Unknown", "city": "Unknown"}
+
+
+def append_visit_to_dataset(country: str, city: str):
+    api = _hf_api()
+    if not api:
+        return
+
+    existing = _download_text_if_exists(
+        USAGE_DATASET_REPO,
+        USAGE_JSONL_PATH
+    )
+
+    event = {
+        "ts_utc": datetime.utcnow().isoformat() + "Z",
+        "space_url": SPACE_URL,
+        "country": country,
+        "city": city,
+        "event": "visit",
+    }
+
+    new_content = (
+        existing.rstrip("\n") + "\n"
+        if existing.strip()
+        else ""
+    ) + json.dumps(event) + "\n"
+
+    try:
+        api.upload_file(
+            repo_id=USAGE_DATASET_REPO,
+            repo_type="dataset",
+            path_in_repo=USAGE_JSONL_PATH,
+            path_or_fileobj=new_content.encode("utf-8"),
+            commit_message="append visit log",
+        )
+    except Exception:
+        pass
+
+
+def record_visit(request: gr.Request):
+    ip = _get_client_ip(request)
+    geo = _geo_lookup(ip) if ip else {"country": "Unknown", "city": "Unknown"}
+    append_visit_to_dataset(
+        country=geo["country"],
+        city=geo["city"]
+    )
+    return