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: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:
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 throughquestion_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:
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.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 askreview only when at least half of the text is classified as
AI-generated, add this rule to the survey before running it:
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’stimeout 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:
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 explicitquestion_text input:
.ep packages, save the containing Survey or Jobs object. Standalone
questions use .json or .json.gz, not .ep:
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.