> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expectedparrot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detect AI with Pangram

> Analyze text with DetectAI, pipe Pangram JSON into follow-up questions, and route surveys using detection results.

`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:

```bash theme={null}
python -m pip install --upgrade pangram-sdk
```

Get your key from [Pangram's API console](https://www.pangram.com/apikey). 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:

```bash theme={null}
python -c 'from getpass import getpass; from dotenv import set_key; set_key(".env", "PANGRAM_API_KEY", getpass("Pangram API key: "))'
```

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:

```python theme={null}
from edsl import DetectAI, Model

passage = (
    "Yesterday I walked to the corner bakery before work. The owner was still "
    "setting out trays, and the windows were fogged from the ovens. I bought "
    "a loaf of rye bread and waited while she looked for a paper bag large "
    "enough to hold it. Outside, a delivery driver had parked across the bike "
    "lane. Two cyclists went around the truck, and one stopped to help the "
    "driver pick up a box that had split open on the pavement. I arrived at "
    "the office a few minutes late, carrying warm bread instead of my usual coffee."
)
detection = DetectAI(question_name="detection", question_text=passage)
results = detection.by(Model("test")).run(
    disable_remote_inference=True,
    stop_on_exception=True,
)
analysis = results.select("answer.detection").to_list()[0]
print(analysis["fraction_ai"])
```

`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:

```python theme={null}
from edsl import Scenario

templated = DetectAI("document_detection", question_text="{{ document }}")
job = templated.by(Scenario({"document": passage}))
```

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](https://docs.expectedparrot.com/en/latest/api_keys.md).

```python theme={null}
from edsl import DetectAI, Model, QuestionFreeText, Survey

essay = QuestionFreeText(
    "essay", "Write a 150-word essay about how cities change over time."
)
detection = DetectAI("detection", question_text="{{ essay.answer }}")
review = QuestionFreeText(
    "review",
    "Interpret this Pangram analysis: {{ detection.answer | tojson }}. "
    "The fraction classified as AI-generated is {{ detection.answer.fraction_ai }}.",
)
survey = Survey([essay, detection, review])
model = Model()
piped_results = survey.by(model).run(
    disable_remote_inference=True,
    stop_on_exception=True,
)
piped_results.select("answer.essay", "answer.detection", "answer.review")
```

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**:

```python theme={null}
survey.add_skip_rule("review", "{{ detection.answer }}['fraction_ai'] < 0.5")
```

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](https://docs.expectedparrot.com/en/latest/guides/survey_logic.md).

## Use DetectAI in a human survey

In a [human survey](https://docs.expectedparrot.com/en/latest/humanize.md), 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:

```python theme={null}
survey.add_skip_rule(
    "detection",
    "{{ essay.answer }} is None or {{ essay.answer }}.split() == []",
)
```

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:

| Field | Meaning |
| - | - |
| `stage` | Completion status; normally `STAGE_SUCCESS`. |
| `version` | Pangram model version used for the analysis. |
| `headline` | Summary classification. |
| `fraction_ai` | Fraction of text classified as AI-generated. |
| `fraction_ai_assisted` | Fraction classified as AI-assisted. |
| `fraction_human` | Fraction classified as human-written. |
| `windows` | Segment-level analysis, including labels and text offsets. |

The fraction fields describe portions of the text, not the probability that a
particular person used AI. Consult the
[Pangram SDK reference](https://pangram.readthedocs.io/en/latest/api/pangram.html)
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:

```python theme={null}
from edsl import DetectAI, QuestionBase

question_data = detection.to_dict()
restored_question = QuestionBase.from_dict(question_data)
detection.save("detection.json")
loaded_question = DetectAI.load("detection.json")
```

For durable `.ep` packages, save the containing Survey or Jobs object. Standalone
questions use `.json` or `.json.gz`, not `.ep`:

```python theme={null}
from edsl import Survey, Results

survey.save("detection-survey.ep")
loaded_survey = Survey.load("detection-survey.ep")
results.save("detection-results.ep")
loaded_results = Results.load("detection-results.ep")
assert loaded_results.select("answer.detection").to_list()[0] == analysis
```

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](https://docs.expectedparrot.com/en/latest/guides/saving_objects.md).

## Parameters and execution behavior

| Parameter | Default | Purpose |
| - | - | - |
| `question_name` | Required | Name used in result columns, piping, and rules. |
| `question_text` | Required | Literal text or an explicit EDSL template to analyze. |
| `timeout` | `300` | SDK timeout for waiting for completion, in seconds. |
| `poll_interval` | `0.5` | Requested interval between SDK polling attempts, in seconds. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.