# Jev (/docs/frameworks/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. ```bash title="Terminal" pip install requests export SOCIALCRAWL_API_KEY=sc_your_key_here export AI_GATEWAY_API_KEY=your_gateway_key ``` ## Connect 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. ```python title="Python" 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"], confidence ``` ## Read 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. ```python title="Python" 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](/docs/errors.md) and [Credits](/docs/credits.md). ## 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. ```python title="Python" 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. ## Resources - [Comments](/docs/comments.md): Which call reads comments on each platform. - [AI agents](/docs/ai-agents.md): Machine-readable references and agent tool files. - [Errors](/docs/errors.md): What each error type means and which are safe to retry. - [Endpoint pricing](/docs/endpoint-pricing.md): The credit price of every endpoint.