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

# Python Quickstart

> Get started with the Pangram Python SDK in minutes

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    pip install pangram-sdk
    ```
  </Step>

  <Step title="Configure your API key">
    You can provide your API key in two ways.

    **Option 1: Environment variable**

    ```bash theme={null}
    export PANGRAM_API_KEY=<your API key>
    ```

    **Option 2: Pass directly to the constructor**

    ```python theme={null}
    from pangram import Pangram

    pangram_client = Pangram(api_key="your-api-key")
    ```
  </Step>

  <Step title="Discover available models">
    Model availability is specific to your API key. Retrieve the current catalog instead of hard-coding it.

    ```python theme={null}
    available_models = pangram_client.list_models()
    print(available_models)  # e.g., ["default", "pangram-4"]
    ```

    Use one returned value as the keyword-only `model` argument on text and bulk requests.
  </Step>

  <Step title="Detect AI-generated text">
    ### Main prediction

    Returns detailed analysis with AI-assistance detection and segment-level metrics.
    The SDK submits an async inference task and waits for the completed result before returning.

    ```python theme={null}
    from pangram import Pangram

    pangram_client = Pangram()
    result = pangram_client.predict(text, model="pangram-4")
    stage = result['stage']  # "STAGE_SUCCESS" after predict() completes.
    version = result['version']  # "4.0" for Pangram 4.

    # Analysis with AI-assistance detection.
    fraction_ai = result['fraction_ai']
    fraction_ai_assisted = result['fraction_ai_assisted']
    fraction_human = result['fraction_human']
    num_ai_segments = result['num_ai_segments']

    # Access individual window classifications
    for window in result['windows']:
        label = window['label']
        ai_assistance_score = window['ai_assistance_score']
        confidence = window['confidence']
        is_humanized = window['is_humanized']
        humanizer_score = window['humanizer_score']
    ```

    ### Dashboard link

    ```python theme={null}
    from pangram import Pangram

    pangram_client = Pangram()
    result = pangram_client.predict(
        text,
        public_dashboard_link=True,
        model="pangram-4",
    )
    dashboard_link = result['dashboard_link']
    ```
  </Step>

  <Step title="Analyze many texts with the Bulk API">
    Use the Bulk API for asynchronous AI detection across many inputs.
    Submit the job, wait for a terminal status, then fetch results.
    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.

    ```python theme={null}
    from pangram import Pangram

    pangram_client = Pangram()

    bulk = pangram_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"]
    status = pangram_client.wait_for_bulk(bulk_id, poll_interval=2)
    results = pangram_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"])
    ```

    For large jobs, process one results page at a time:

    ```python theme={null}
    offset = 0
    limit = 1000

    while True:
        page = pangram_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
    ```
  </Step>

  <Step title="Check for plagiarism">
    The plagiarism detection API checks text against a vast database of online content:

    ```python theme={null}
    from pangram import Pangram

    pangram_client = Pangram()

    text = "Text to check for plagiarism"
    result = pangram_client.check_plagiarism(text)

    if result['plagiarism_detected']:
        print(f"Plagiarism detected! {result['percent_plagiarized']}% of the text may be plagiarized.")
        for content in result['plagiarized_content']:
            print(f"Found match at {content['source_url']}")
            print(f"Matched text: {content['matched_text']}")
    ```

    The response includes:

    * Whether plagiarism was detected
    * List of plagiarized content with source URLs
    * Total number of sentences checked
    * List of plagiarized sentences
    * Percentage of text that was plagiarized
  </Step>
</Steps>

<Warning>
  For backward compatibility, the SDK temporarily permits omitted model selection, preserves the existing wire payload, and emits a `DeprecationWarning`. Pass `model="default"` or another value from `list_models()` in new code. The argument will be required after September 30, 2026.
</Warning>

## Deprecated Methods

<Warning>
  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.
</Warning>

* `predict_short()` — Forwards to `predict()` and returns the current async result schema
* `batch_predict()` — Calls `predict()` once per input text