Python package

pangram.text_classifier module

class pangram.text_classifier.PangramText(api_key: str | None = None)

Bases: object

__init__(api_key: str | None = None) → None

A classifier for text inputs using the Pangram Labs API.

Parameters:

api_key (str, optional) – Your API key for the Pangram Labs. If not provided, the environment variable PANGRAM_API_KEY will be used.

Raises:

ValueError – If the API key is not provided and not set in the environment.

predict(text: str, public_dashboard_link: bool = False, timeout: float = 300, poll_interval: float = 0.5) → Dict

Classify text as AI-, AI-assisted, or human-written.

Submits the text to Pangram’s async inference endpoint, waits for completion, and returns analysis with windowed results.

Parameters:

  • text (str) – The text to be classified.

  • public_dashboard_link (bool) – Whether to include a public dashboard link in the completed response. Defaults to False.

  • timeout (float) – Maximum seconds to wait for the async task to complete. Defaults to 300.

  • poll_interval (float) – Seconds to wait between polling attempts. Values below 0.1 are clamped to 0.1. Defaults to 0.5.

Returns:

Pangram analysis with AI-assistance detection as a dict with the following fields:

  • stage (str): The terminal async task stage, normally “STAGE_SUCCESS”.

  • text (str): The input text.

  • version (str): The API version identifier (e.g., “3.0”).

  • headline (str): Classification headline summarizing the result.

  • prediction (str): Long-form prediction string describing the classification.

  • prediction_short (str): 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 (int): Number of text segments classified as AI.

  • num_ai_assisted_segments (int): Number of text segments classified as AI-assisted.

  • num_human_segments (int): Number of text segments classified as human.

  • dashboard_link (str): A link to the dashboard page containing the full classification result, if requested.

  • windows (list): List of text windows and their classifications. Each window contains:

    • text (str): The window text.

    • label (str): Descriptive classification label (e.g., “AI-Generated”, “Moderately AI-Assisted”).

    • ai_assistance_score (float): Score detailing the level of AI assistance within the window (0.0-1.0), where 0 means no AI assistance and 1.0 means AI-generated.

    • confidence (str): Confidence level for the classification (“High”, “Medium”, “Low”).

    • start_index (int): Starting character index in the original text.

    • end_index (int): Ending character index in the original text.

    • word_count (int): Number of words in the window.

    • token_length (int): Token length of the window.

Return type:

Dict

Raises:

  • ValueError – If the API returns an error or if the response is invalid

  • TimeoutError – If the async task does not complete before timeout

predict_short(text: str) → Dict

Classify text using the main async prediction endpoint.

Deprecated since version This: compatibility alias forwards to predict(). Use predict() directly for Pangram’s current response schema. This method may be removed on August 1, 2026.

Parameters:

text (str) – The text to be classified.

Returns:

The same classification result returned by predict().

Return type:

Dict

batch_predict(text_batch: List[str]) → List[Dict]

Classify a batch of text as AI-, AI-assisted, or human-written.

This method iterates through the batch and calls predict() for each text.

Deprecated since version This: compatibility method forwards to predict() once per input text. Use predict() directly. This method may be removed on August 1, 2026.

Parameters:

text_batch (List[str]) – A list of strings to be classified.

Returns:

A list of classification results from the API for each text in the batch. Each result is a dict with the same fields as returned by predict().

Return type:

List[Dict]

Classify text as AI-, AI-assisted, or human-written.

Submits the text to Pangram’s async inference endpoint, waits for completion, and returns analysis with a public dashboard link.

Parameters:

text (str) – The text to be classified.

Returns:

The classification result from the API, as a dict with the following fields:

  • text (string): The classified text.

  • dashboard_link (string): A link to a dashboard page containing the classification result.

  • stage (string): The terminal async task stage, normally “STAGE_SUCCESS”.

  • prediction (string): Long-form prediction string describing the classification.

  • prediction_short (string): Short-form prediction string.

  • 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).

  • windows (list): List of text windows and their classifications.

Return type:

dict

check_plagiarism(text: str) → Dict

Check text for potential plagiarism by comparing it against a vast database of online content.

Parameters:

text (str) – The text to check for plagiarism.

Returns:

A dictionary containing the plagiarism check results, including:

  • text (str): The input text.

  • plagiarism_detected (bool): Whether plagiarism was detected

  • plagiarized_content (List): List of detected plagiarized content with sources

  • total_sentences (int): Total number of sentences checked

  • plagiarized_sentences (List): List of sentences detected as plagiarized

  • percent_plagiarized (float): Percentage of text detected as plagiarized

Return type:

Dict

Raises:

ValueError – If the API returns an error or if the response is invalid