Python SDK - Pangram Labs

Installation

pip install pangram-sdk

Pangram

The main client class for interacting with the Pangram Labs API. PangramText remains available for legacy imports, but Pangram is the recommended client name.

Constructor

from pangram import Pangram

client = Pangram(api_key="your-api-key")

string

Your API key for Pangram Labs. If not provided, the PANGRAM_API_KEY environment variable will be used.

Raises ValueError if the API key is not provided and not set in the environment.

list_models()

List the detection models available to this API key.

available_models = client.list_models()
# e.g., ["default", "pangram-4"]

The returned list[str] preserves server order and reflects both the account’s entitlements and current model availability. Do not hard-code the catalog or assume every API key sees the same values. Use one returned selector as the keyword-only model argument on text and bulk requests.

The model argument is temporarily optional for backward compatibility. Omitting it preserves the existing wire payload, selects Pangram’s server default, and emits a DeprecationWarning. Pass model="default" or another value from list_models() in new code. The SDK will require explicit model selection after September 30, 2026.

predict()

Classify text as AI-generated, AI-assisted, or human-written. predict() submits an async inference task, polls until the task completes, and returns the completed task payload.

result = client.predict(
    text,
    public_dashboard_link=False,
    timeout=300,
    poll_interval=0.5,
    model="pangram-4",
)

Parameters

string

required

The text to be classified.

string

Keyword-only model selector returned by list_models(). Pass "default" to follow Pangram’s current default model.

boolean

default:"false"

Whether to include a public dashboard link in the completed response.

float

default:"300"

Maximum number of seconds to wait for the async task to complete.

float

default:"0.5"

Number of seconds to wait between polling attempts. Values below 0.1 are clamped to 0.1.

Returns A dictionary with the following fields after the task reaches STAGE_SUCCESS:

string

Terminal async task stage. Successful responses return "STAGE_SUCCESS".

string

The analyzed text returned by the model. Pangram 4 may normalize the submitted text before inference; window offsets refer to this value.

string

The API version identifier (e.g., "4.0" for Pangram 4).

string

Classification headline summarizing the result.

string

Long-form prediction string describing the classification.

string

Short-form prediction string. Pangram 4 returns "AI", "Human", or "Mixed".

float

Fraction of text classified as AI-written (0.0–1.0).

float

Fraction of text classified as AI-assisted (0.0–1.0).

float

Fraction of text classified as human-written (0.0–1.0).

integer

Number of text segments classified as AI.

integer

Number of text segments classified as AI-assisted.

integer

Number of text segments classified as human.

string

Dashboard link. Only present when public_dashboard_link is True.

list

List of text windows and their classifications. Each window contains:

Show Window object properties

string

The window text.

string

Classification label. Pangram 4 returns "AI-Generated", "AI-Assisted", or "Human Written".

float

AI assistance score (0.0–1.0), where 0 means no AI assistance and 1.0 means AI-generated.

string

Confidence level ("High", "Medium", "Low").

integer

Starting character index in the returned top-level text.

integer

End-exclusive character index in the returned top-level text.

integer

Number of words in the window.

integer

Token length of the window.

boolean

Whether Pangram 4’s humanizer head classified the window as humanized. Present on every Pangram 4 window.

float

Pangram 4 humanizer-head score from 0.0–1.0. Present on every Pangram 4 window.

Results remain normal dictionaries. Typed applications can import PredictionResult and PredictionWindow from pangram. Raises ValueError if the API returns an error, the task fails, or the response is invalid. Raises TimeoutError if the task does not complete before timeout.

predict_with_dashboard_link()

Classify text and include a public dashboard link in the completed response.

result = client.predict_with_dashboard_link(
    text,
    timeout=300,
    poll_interval=0.5,
    model="pangram-4",
)

This is equivalent to:

result = client.predict(
    text,
    public_dashboard_link=True,
    timeout=300,
    poll_interval=0.5,
    model="pangram-4",
)

The timeout, poll_interval, and keyword-only model parameters have the same behavior as predict().

submit_bulk()

Submit a Bulk API job for asynchronous AI detection across many inputs. Provide exactly one of text or items. Bulk jobs are processed asynchronously. Completion time depends on the number and length of submitted items and current system load. Use get_bulk_status() or wait_for_bulk() to monitor progress. Use text=[...] for plain string inputs, or items=[{"id": "...", "text": "..."}] when you want customer IDs returned with status and results. Do not pass both.

bulk = client.submit_bulk(
    items=[
        {"id": "row-001", "text": "First text to analyze"},
        {"id": "row-002", "text": "Second text to analyze"},
    ],
    model="pangram-4",
)

bulk_id = bulk["bulk_id"]

Parameters

list[string]

List of input texts. Use this shape when you do not need customer item IDs.

list[dict]

List of item dictionaries. Each item must include text and may include a unique customer-defined id.

string

Keyword-only model selector returned by list_models(). Applies to the entire bulk job; per-item model selectors are not supported.

Returns

string

The ID of the bulk job.

string

Initial status. Usually queued; returns failed if every item failed immediate validation.

integer

Total number of submitted items.

list

Items accepted for processing. Each item includes index, optional id, and task_id.

list

Items that failed immediate validation. Each item includes index, optional id, task_id: None, stage, and error.

wait_for_bulk()

Poll a bulk job until it reaches a terminal status.

status = client.wait_for_bulk(
    bulk_id,
    timeout=3600,
    poll_interval=0.5,
)

Terminal statuses are succeeded, failed, and partial. Completion time depends on the number and length of submitted items and current system load. Parameters

string

required

The bulk job ID returned by submit_bulk().

float

default:"3600"

Maximum number of seconds to wait for terminal completion.

float

default:"0.5"

Number of seconds to wait between polling attempts. Values below 0.1 are clamped to 0.1.

Returns The same dictionary returned by get_bulk_status() after the job reaches a terminal status. Raises TimeoutError if the job does not complete before timeout.

get_bulk_status()

Fetch the current status and counters for a bulk job.

status = client.get_bulk_status(bulk_id)

Returns

string

The ID of the bulk job.

string

One of queued, running, succeeded, failed, or partial.

integer

Total number of submitted items.

integer

Number of items accepted for processing.

integer

Number of items that completed successfully.

integer

Number of items that failed.

string

Job creation timestamp as Unix epoch seconds encoded as a string.

string

Job completion timestamp as Unix epoch seconds encoded as a string. None while the job is not terminal.

get_bulk_items()

Fetch paginated item metadata for a bulk job.

items = client.get_bulk_items(bulk_id, offset=0, limit=100)

Parameters

string

required

The bulk job ID returned by submit_bulk().

integer

default:"0"

Zero-based item offset.

integer

default:"100"

Maximum number of items to return. The API allows up to 1000.

Returns A dictionary containing bulk_id, offset, limit, total_items, and items. Each item includes index, optional id, task_id, stage, and optional error.

get_bulk_results()

Fetch all available results for a bulk job.

results = client.get_bulk_results(bulk_id)

for item in results["items"]:
    if item["result"] is not None:
        print(item["id"], item["result"]["prediction_short"])

for failed in results["failed_items"]:
    print(failed["id"], failed["error"])

Parameters

string

required

The bulk job ID returned by submit_bulk().

integer

default:"1000"

Number of submitted item slots to request per API call. The API allows up to 1000.

Returns A dictionary containing bulk_id, total_items, items, and failed_items aggregated across every results page. Successful completed items include result with the same shape returned by predict(). In-progress items have result set to None. get_bulk_results() materializes all pages into memory. For large jobs, use get_bulk_results_page() in a loop and process each page as it arrives. The SDK returns this dictionary as BulkResults; successful item results use PredictionResult.

get_bulk_results_page()

Fetch one paginated results page for a bulk job.

page = client.get_bulk_results_page(bulk_id, offset=0, limit=100)

Use this when you need incremental page-level inspection before fetching or storing the full result set.

offset = 0
limit = 1000

while True:
    page = client.get_bulk_results_page(bulk_id, offset=offset, limit=limit)
    for item in page["items"]:
        process(item)
    for failed in page["failed_items"]:
        handle_failure(failed)

    offset += limit
    if offset >= page["total_items"]:
        break

Parameters

string

required

The bulk job ID returned by submit_bulk().

integer

default:"0"

Zero-based submitted-item offset.

integer

default:"100"

Maximum number of submitted item slots to return. The API allows up to 1000.

Returns A dictionary containing bulk_id, offset, limit, total_items, items, and failed_items for the requested page. The SDK returns this dictionary as BulkResultsPage.

check_plagiarism()

Check text for potential plagiarism against a database of online content.

result = client.check_plagiarism(text)

Parameters

string

required

The text to check for plagiarism.

Returns A dictionary with the following fields:

string

The input text.

boolean

Whether plagiarism was detected.

list

List of detected plagiarized content with source URLs.

integer

Total number of sentences checked.

list

List of sentences detected as plagiarized.

float

Percentage of text detected as plagiarized.

Raises ValueError if the API returns an error.

Typed response contracts

The SDK ships a py.typed marker and exports its public TypedDict contracts from pangram:

from pangram import (
    BulkResultItem,
    BulkResultMetadata,
    BulkResults,
    BulkResultsPage,
    PredictionResult,
    PredictionWindow,
)

Type	Represents
`PredictionWindow`	One classified window, including optional Pangram 4 humanizer fields.
`PredictionResult`	A successful text prediction.
`BulkResultMetadata`	Status metadata shared by successful and failed bulk items.
`BulkResultItem`	Bulk item metadata plus its prediction when processing succeeds.
`BulkResultsPage`	One paginated bulk results response.
`BulkResults`	All bulk results pages aggregated by the SDK.

The runtime values remain ordinary dictionaries and lists; these types provide static checking without changing existing access patterns.

Deprecated Methods

The following SDK compatibility methods are deprecated and may be removed on August 1, 2026. Use predict() for one-off calls or submit_bulk() for asynchronous bulk jobs.

predict_short() Deprecated

Forwards to predict() and returns the current async result schema.

result = client.predict_short(text, model="pangram-4")

batch_predict() Deprecated

Calls predict() once per input text. Use submit_bulk() for asynchronous bulk jobs.

results = client.batch_predict(
    ["text one", "text two"],
    model="pangram-4",
)

Removed Legacy Methods

predict_extended() and predict_sliding_window() are no longer part of the current pangram-sdk. Use predict() for current AI detection and segment-level results.

​Installation

​Pangram

​Constructor

​list_models()

​predict()

​predict_with_dashboard_link()

​submit_bulk()

​wait_for_bulk()

​get_bulk_status()

​get_bulk_items()

​get_bulk_results()

​get_bulk_results_page()

​check_plagiarism()

​Typed response contracts

​Deprecated Methods

​predict_short() Deprecated

​batch_predict() Deprecated

​Removed Legacy Methods

Installation

Pangram

Constructor

list_models()

predict()

predict_with_dashboard_link()

submit_bulk()

wait_for_bulk()

get_bulk_status()

get_bulk_items()

get_bulk_results()

get_bulk_results_page()

check_plagiarism()

Typed response contracts

Deprecated Methods

predict_short() Deprecated

batch_predict() Deprecated

Removed Legacy Methods