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")

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.

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,
)

Parameters

text

string

required

The text to be classified.

public_dashboard_link

boolean

default:"false"

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

timeout

float

default:"300"

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

poll_interval

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:

stage

string

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

text

string

The input text.

version

string

The API version identifier (e.g., "3.0").

headline

string

Classification headline summarizing the result.

prediction

string

Long-form prediction string describing the classification.

prediction_short

string

Short-form prediction string ("AI", "AI-Assisted", "Human", "Mixed").

fraction_ai

float

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

fraction_ai_assisted

float

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

fraction_human

float

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

num_ai_segments

integer

Number of text segments classified as AI.

num_ai_assisted_segments

integer

Number of text segments classified as AI-assisted.

num_human_segments

integer

Number of text segments classified as human.

dashboard_link

string

Dashboard link. Only present when public_dashboard_link is True.

windows

list

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

Show Window object properties

text

string

The window text.

label

string

Classification label (e.g., "AI-Generated", "Moderately AI-Assisted").

ai_assistance_score

float

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

confidence

string

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

start_index

integer

Starting character index in the original text.

end_index

integer

Ending character index in the original text.

word_count

integer

Number of words in the window.

token_length

integer

Token length of the window.

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)

This is equivalent to:

result = client.predict(text, public_dashboard_link=True, timeout=300, poll_interval=0.5)

The timeout and poll_interval 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"},
])

bulk_id = bulk["bulk_id"]

Parameters

text

list[string]

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

items

list[dict]

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

Returns

bulk_id

string

The ID of the bulk job.

status

string

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

total_items

integer

Total number of submitted items.

accepted_items

list

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

failed_items

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

bulk_id

string

required

The bulk job ID returned by submit_bulk().

timeout

float

default:"3600"

Maximum number of seconds to wait for terminal completion.

poll_interval

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

bulk_id

string

The ID of the bulk job.

status

string

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

total_items

integer

Total number of submitted items.

accepted

integer

Number of items accepted for processing.

succeeded

integer

Number of items that completed successfully.

failed

integer

Number of items that failed.

created_at

string

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

completed_at

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

bulk_id

string

required

The bulk job ID returned by submit_bulk().

offset

integer

default:"0"

Zero-based item offset.

limit

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

bulk_id

string

required

The bulk job ID returned by submit_bulk().

page_size

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.

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

bulk_id

string

required

The bulk job ID returned by submit_bulk().

offset

integer

default:"0"

Zero-based submitted-item offset.

limit

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.

check_plagiarism()

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

result = client.check_plagiarism(text)

Parameters

text

string

required

The text to check for plagiarism.

Returns A dictionary with the following fields:

text

string

The input text.

plagiarism_detected

boolean

Whether plagiarism was detected.

plagiarized_content

list

List of detected plagiarized content with source URLs.

total_sentences

integer

Total number of sentences checked.

plagiarized_sentences

list

List of sentences detected as plagiarized.

percent_plagiarized

float

Percentage of text detected as plagiarized.

Raises ValueError if the API returns an error.

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)

batch_predict() Deprecated

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

results = client.batch_predict(["text one", "text two"])

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

​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()

​Deprecated Methods

​predict_short() Deprecated

​batch_predict() Deprecated

​Removed Legacy Methods

Installation

Pangram

Constructor

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()

Deprecated Methods

predict_short() Deprecated

batch_predict() Deprecated

Removed Legacy Methods