Metadata-Version: 2.4
Name: pangram-sdk
Version: 0.3.0
Summary: 
License-File: LICENSE
Author: Max Spero
Author-email: max@pangramlabs.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: requests (>=2.33.0,<3.0.0)
Requires-Dist: urllib3 (>=2.7.0,<3.0.0)
Description-Content-Type: text/markdown

# Pangram Labs Python Package

### Installation
```
pip install pangram-sdk
```

### Add your API key
Add your API key as an environment variable, or pass it directly to the
Pangram constructor.
```
export PANGRAM_API_KEY=<your API key>
```
```
from pangram import Pangram
# If the environment variable PANGRAM_API_KEY is set:
pangram_client = Pangram()

# Otherwise, pass the API key directly:
my_api_key = ''  # Fill this in with your API key.
pangram_client = Pangram(api_key=my_api_key)
```

### Make a request

Main prediction method (AI-assistance detection and segment-level analysis):
```
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']  # e.g., "AI-Generated", "Moderately AI-Assisted"
    ai_assistance_score = window['ai_assistance_score']
    confidence = window['confidence']  # "High", "Medium", "Low"
```
`predict()` submits to Pangram's async inference API and waits for the result before returning.
Use `predict(text, public_dashboard_link=True)` or `predict_with_dashboard_link(text, timeout=300, poll_interval=0.5)` to include a `dashboard_link` in the completed result.

### Submit a Bulk API job

Use the Bulk API for asynchronous AI detection across many inputs.
Submit either a list of strings with `text` or a list of objects with `items`.
Item `id` values are optional customer IDs 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.

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

Bulk jobs can also be inspected without waiting:

```
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:

```
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
```

### Building Documentation

Install docs dependencies and build:
```
poetry install --with docs
cd docs && make html
```

Questions? Email [support@pangram.com](mailto:support@pangram.com)!

