Use SocialCrawl with Jev
Give a Jev agent social media data, with the price shown before it spends.
Jev is TypeSafe's judgment model: it does not write text, it answers typed questions such as yes or no, one of a set, or a score, in a fraction of a second. SocialCrawl supplies the rows and Jev judges each one, so your code combines the answers. No SocialCrawl package is published, and both calls below are plain HTTP.
Setup
Install requests and set two keys. Create the SocialCrawl key in the dashboard under API Keys; it looks like sc_your_key_here. Jev is reached through the Vercel AI Gateway, so AI_GATEWAY_API_KEY is the only other key, and Jev calls bill to your gateway account, not to SocialCrawl credits.
pip install requests
export SOCIALCRAWL_API_KEY=sc_your_key_here
export AI_GATEWAY_API_KEY=your_gateway_keyConnect
Two helpers cover everything. sc reads SocialCrawl rows and judge sends one state and a map of typed questions to Jev. A question is a boolean, a choice or a score, and each is answered separately from the same state. On ai version 7 or later you can call experimental_evaluate with the model typesafe-ai/jev instead of the HTTP request.
import os
import requests
BASE = "https://www.socialcrawl.dev"
SC_HEADERS = {"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}
GATEWAY = "https://ai-gateway.vercel.sh/v4/ai/evaluation-model"
def sc(path: str, params: dict) -> dict:
r = requests.get(f"{BASE}{path}", headers=SC_HEADERS, params=params, timeout=60)
body = r.json()
if not body.get("success"):
err = body.get("error", {})
raise RuntimeError(f"SocialCrawl {r.status_code} {err.get('type')}: {err.get('message')}")
return body["data"]
def judge(state, questions: dict):
r = requests.post(
GATEWAY,
headers={
"Authorization": f"Bearer {os.environ['AI_GATEWAY_API_KEY']}",
"ai-gateway-auth-method": "api-key",
"ai-gateway-protocol-version": "0.0.1",
"ai-evaluation-model-specification-version": "4",
"ai-model-id": "typesafe-ai/jev",
},
json={"state": state, "questions": questions},
timeout=30,
)
r.raise_for_status()
body = r.json()
confidence = body.get("providerMetadata", {}).get("typesafe", {}).get("confidence", {})
return body["answers"], confidenceRead a profile and its posts
Price the call first with the free estimate, then read it. The hold is the most the call can take.
quote = sc("/v1/utility/estimate", {"id": "tiktok/profile/videos", "handle": "nasa"})
print("hold:", quote["hold"], "valid:", quote["valid"])
videos = sc("/v1/tiktok/profile/videos", {"handle": "nasa"})Keep spend in check
Quote every SocialCrawl call with /v1/utility/estimate and show the answer to the person who owns the key before you run it. Read a page at a time and stop when you have enough rows, and send max_credits on list endpoints so a walk stops where you set it. A 402 means the account is out of credits. Tell the user it is an offer to top up and stop, because a retry cannot succeed. See Errors and Credits.
Score comments for intent
Quote the comments call, read one page, and ask Jev two questions of each comment. Each question is narrow, and the policy for acting on the answers lives in code. Replace the URL with a real video from the profile above.
VIDEO_URL = "https://www.tiktok.com/@nasa/video/VIDEO_ID"
INTENT_MIN = 0.7 # start conservative and tune on labelled comments
print(sc("/v1/utility/estimate", {"id": "tiktok/post/comments", "url": VIDEO_URL})["hold"])
rows = sc("/v1/tiktok/post/comments", {"url": VIDEO_URL})["items"]
QUESTIONS = {
"wants_to_buy": {
"type": "boolean",
"instructions": "Does `comment` say the writer wants to buy, or ask where to buy or what it costs?",
},
"tone": {
"type": "score",
"instructions": "How warm is the writer's attitude in `comment`?",
"criteria": [
"The writer is hostile or complaining.",
"The writer is neutral or only asking a question.",
"The writer is warm or praising.",
],
},
}
for row in rows:
answers, confidence = judge({"comment": row}, QUESTIONS)
if answers["wants_to_buy"]["probability"] >= INTENT_MIN:
print("lead:", row, answers["tone"]["score"], confidence.get("tone"))A boolean near 0.5 means equally likely, not medium, so use the score for degrees. English works best, so test other languages on your own comments and watch the confidence. The gateway offers typesafe-ai/jev only, and it cannot pin a version, so check your threshold again when TypeSafe ships a new one.
