Skip to main content
DetectAI is a question that sends text to Pangram and returns its full JSON response as a Python dictionary. Use it to analyze scenario text or an earlier answer, then pass the result to another question or use its fields in survey rules. It uses Pangram directly; an LLM does not answer the detection question. DetectAI and QuestionDetectAI are two names for the same class. The question type used by the registry and serialized definitions is detect_ai.

Set up the SDK and key

Install the SDK in the Python environment where you run EDSL:
Get your key from Pangram’s API console. Add PANGRAM_API_KEY to your local .env file, which EDSL loads when it initializes. To enter the key without displaying it and preserve other entries in that file:
You can also supply PANGRAM_API_KEY as an environment variable. The SDK reads the key but does not provide a CLI that retrieves it or writes .env. Keep .env out of version control. If EDSL is already imported in a notebook, restart the kernel after changing .env, or explicitly reload it with dotenv.load_dotenv(override=True).

Analyze supplied text

Pass the text to analyze through question_text, just as you supply input to other question types. Both question_name and question_text are required:
Model("test") supplies the job’s model slot; DetectAI bypasses it and makes a real Pangram request. This example needs a Pangram key but no LLM provider key. To analyze scenario data, reference the chosen field explicitly in question_text. The field name is yours to choose:
There is no implicit scenario field or separate text argument.

Pipe answers into and out of DetectAI

This survey generates an essay, sends that answer to Pangram, then asks an LLM to interpret the returned analysis. The essay and review questions require model access.
Place the source question before DetectAI and any consumers after it. Piping works without adding survey memory. In templates, detection.answer is the whole dictionary; | tojson formats it as JSON text. Use {{ detection.answer.fraction_ai }} for a single field.

Use detection fields in skip rules

To ask review only when at least half of the text is classified as AI-generated, add this rule to the survey before running it:
The condition is evaluated before review; when it is true, that question is skipped. The rule substitutes the answer dictionary, then reads its fraction_ai field. The older expression detection['fraction_ai'] < 0.5 also works, but EDSL converts it to the template form with a warning. The threshold is an example routing choice. For more branching patterns, see Survey logic and piping.

Use DetectAI in a human survey

In a human survey, a DetectAI question is answered automatically when a respondent reaches it. Respondents never see it, and you don’t need a Pangram key: the analysis is charged to your credits at $0.05 per 100 words, rounded up per analysis. The question’s timeout and poll_interval don’t apply; each analysis is given up to four minutes. If the text to analyze is blank, for example because the respondent left the source question empty or skipped it, the respondent can’t continue the survey. To avoid this, add a skip rule on the source answer:
The rule skips detection when essay was skipped, or its answer is empty or only whitespace. is None comes first so a skipped answer is never split. Later questions that read detection, in templates or rules, should allow for it having been skipped.

Work with the returned JSON

EDSL preserves the response dictionary, including nested window data and any additional fields returned by Pangram. Common fields include: The fraction fields describe portions of the text, not the probability that a particular person used AI. Consult the Pangram SDK reference for the response fields available in your version. DetectAI calls predict(model="default", public_dashboard_link=False) and returns the completed response.

Save and reload

Question definitions support dictionary and JSON round-trips, preserving the explicit question_text input:
For durable .ep packages, save the containing Survey or Jobs object. Standalone questions use .json or .json.gz, not .ep:
Templates, timing settings, survey rules, and nested Pangram answers survive serialization. The API key is never included in the question definition. Reading saved results needs no Pangram call; executing a reloaded question reads the key from that execution environment. See Saving objects.

Parameters and execution behavior

Both timing values must be finite positive numbers. The SDK polls until the analysis completes; EDSL runs that blocking operation in a worker thread so it does not block the survey event loop. disable_remote_inference=True runs the EDSL job locally, but DetectAI still sends its input to Pangram. A remote worker needs the DetectAI implementation, the SDK, and PANGRAM_API_KEY in its own environment; saving or submitting a question does not transfer your local key. Pangram bills detection requests separately. EDSL’s LLM cost estimate does not include these charges, and its LLM cache does not cache detection responses. Repeated interviews, models, iterations, or retries can therefore make additional Pangram calls. Missing credentials, a missing SDK, empty rendered text, SDK timeouts, and API failures are reported as errors rather than classification answers. Use stop_on_exception=True, as in the examples, to surface errors immediately while setting up a job.