Pangram Labs Quickstart Guide
===================================

Usage
-----

Install `pangram`
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    pip install pangram-sdk

Add your API key
~~~~~~~~~~~~~~~~

Either export it as an environment variable:

.. code-block:: bash

    export PANGRAM_API_KEY=<your API key>

Or pass it directly to the constructor:

.. code:: python

    from pangram import Pangram

    my_api_key = ''  # Fill this in with your API key.
    pangram_client = Pangram(api_key=my_api_key)

Make a request
~~~~~~~~~~~~~~

Main prediction
~~~~~~~~~~~~~~~
Returns detailed analysis with AI-assistance detection and segment-level metrics
The SDK submits to Pangram's async inference API and waits for the completed result.

.. code:: python

    from pangram import Pangram

    pangram_client = Pangram()
    result = pangram_client.predict(text)
    stage = result['stage']  # "STAGE_SUCCESS" after predict() completes.

    # 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']

Upload files
~~~~~~~~~~~~
Use ``predict_file()`` or ``predict_files()`` when you want Pangram to extract
text from ``.docx``, ``.pdf``, or ``.rtf`` documents and create AI detection
results. Each result includes the extracted text, prediction fields,
window-level analysis, and the uploaded ``filename``. Set
``public_dashboard_link=True`` to include a ``dashboard_link``.

.. code:: python

    from pangram import Pangram

    pangram_client = Pangram()

    result = pangram_client.predict_file(
        "path/to/document.docx",
        public_dashboard_link=True,
    )

    print(result["dashboard_link"])
    print(result["prediction_short"])
    print(result["filename"])

To upload multiple files in one request:

.. code:: python

    results = pangram_client.predict_files(
        ["path/to/first.docx", "path/to/second.pdf"],
        public_dashboard_link=True,
    )

    for result in results:
        print(result["dashboard_link"])

Submit a Bulk API job
~~~~~~~~~~~~~~~~~~~~~
Use the Bulk API for asynchronous AI detection across many inputs. Submit either
a ``text`` list or an ``items`` list. ``items`` can include customer-defined
``id`` values that are returned with item status and results.

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.

.. code:: python

    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"},
    ])

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

You can also inspect jobs without waiting:

.. code:: python

    status = pangram_client.get_bulk_status(bulk_id)
    items = pangram_client.get_bulk_items(bulk_id, offset=0, limit=100)
    results_page = pangram_client.get_bulk_results_page(bulk_id, offset=0, limit=100)

For large jobs, use ``get_bulk_results_page()`` in a loop instead of
``get_bulk_results()`` to process one page at a time without holding the full
result set in memory:

.. code:: python

    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

Check for Plagiarism
~~~~~~~~~~~~~~~~~~~~~

The plagiarism detection API helps you identify potential plagiarism by comparing text against a vast database of online content:

.. code:: python

    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 plagiarism detection 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