Belal0101/Resources_extractor

CareerGPS Resource Finder API

Finds Arabic/English YouTube videos, articles/docs, and practice resources for a curriculum node, and returns validated (non-hallucinated) URLs.

Secrets (set in Space Settings -> Repository secrets)

Endpoints

Base URL: https://<your-username>-<space-name>.hf.space

GET /health

Liveness check.

POST /v1/nodes/process

Synchronous — call this from CareerGPS when a new curriculum node is created.

curl -X POST https://<space-url>/v1/nodes/process \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_AUTH_TOKEN" \
  -d '{
        "id": "css-flexbox",
        "title": "CSS Flexbox",
        "description": "Laying out elements with display: flex.",
        "search_query": "CSS flexbox tutorial"
      }'

Response:

{
  "node_id": "css-flexbox",
  "resources": {
    "youtube_ar": {"url": "...", "title": "...", "source": "...", "reason": "..."},
    "youtube_en": {"url": "...", "title": "...", "source": "...", "reason": "..."},
    "article":    {"url": "...", "title": "...", "source": "...", "reason": "..."},
    "practice":   {"url": "...", "title": "...", "source": "...", "reason": "..."}
  }
}

Any category can be null if nothing reachable/relevant was found — flag those for manual review in your CareerGPS admin panel.

Note: this call makes several external API requests (YouTube + Google CSE

• —Anthropic) per node, so expect ~10-30 seconds latency. Call it from a background job/queue in your backend, not from a user-facing request path.

POST /v1/nodes/process-batch

Fire many nodes at once; runs in the background inside the Space, returns a job_id immediately.

curl -X POST https://<space-url>/v1/nodes/process-batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_AUTH_TOKEN" \
  -d '{"nodes": [{"id": "css-flexbox", "title": "CSS Flexbox"}, {"id": "js-promises", "title": "JavaScript Promises"}]}'

Response: {"job_id": "...", "total": 2}

GET /v1/jobs/{job_id}

Poll until "status": "done", then read "results".

curl https://<space-url>/v1/jobs/<job_id> -H "X-API-Key: $API_AUTH_TOKEN"

Important limitations of this Space

• —No persistent storage. Job results live in memory only and are lost on restart/redeploy. CareerGPS's backend must save the response itself — this Space is a finder, not the resource database.
• —Concurrency: free HF Spaces have limited CPU and no autoscaling. For a handful of nodes at a time this is fine; for hundreds, batch them slowly (the pipeline already sleeps between external API calls) or upgrade the Space's hardware tier.
• —Rate limits belong to your API keys, not the Space — YouTube (10k units/day) and Google CSE (100 free queries/day) quotas apply regardless of where this runs.
• —Always set API_AUTH_TOKEN — HF Spaces are public URLs by default.