Alighieria Python SDK

Python client for the Alighieria API: upload a manuscript once, then run corrections, translations, dossiers, synopses, indexes, EPUBs, AI detection, plagiarism checks and marketing content on it.

Requires Python 3.10 or later.

pip install alighieria

Quickstart

Create an API key in the dashboard and export it as ALIGHIERIA_API_KEY. Keys are secret: use the SDK from your backend, never from a browser or a mobile app.

from alighieria import Alighieria

client = Alighieria()  # reads ALIGHIERIA_API_KEY

document = client.documents.upload(
    "the_long_winter.docx", title="The Long Winter", author="Ana Pérez"
).wait()

synopsis = client.synopses.create(document.id, word_count=300).wait()
print(synopsis.result().content)

Every workflow has the same three steps: upload a document, launch a job with its id, wait for the job and read or download the result.

Jobs

Uploads and generations run in the background. Launch methods return a Job right away:

run = client.corrections.create(document.id, correction_types=["editorial", "raccord"])

run.wait()  # polls until the run finishes
run.status  # "completed", "partial", "error" or "failed"
run.suites  # progress per correction family
run.raw["total_cost"]  # credits charged

run.download("corrected/")  # DOCX, PDF or IDML, in the format of the source
for finding in client.corrections.findings(run.id, family="editorial"):
    print(finding.page, finding.original, "->", finding.corrected)

wait() polls every 5 seconds at first and backs off to 30. It raises JobTimeoutError after an hour by default (timeout=None waits forever; the job keeps running either way) and JobFailedError if the job ends in error or failed. A partial job counts as finished.

To come back to a job later, keep its id:

run = client.corrections.retrieve("6650f1c2e4b0a1d2c3f4a5b6")

To wait for several jobs at once:

jobs = [client.synopses.create(doc_id) for doc_id in doc_ids]
client.jobs.wait_all(jobs)

What you can launch

Lists are plain Python lists: the SDK encodes doc_ids, contributors, excluded_domains, authors and subjects the way each endpoint expects.

Documents

client.documents.upload("book.pdf", title="Book", author="Author")
client.documents.upload(("guide.docx", data), title="House style", doc_type="guide")
client.documents.upload(file_url="https://example.com/book.epub", title="Book", author="Author")

# Text that is already digital needs no upload and is ready at once.
guide = client.documents.create_markdown(
    title="House style", content="# Serial commas\n...", collection="guides"
)

for document in client.documents.iter(search="winter"):
    print(document.id, document.title)

Uploads are free except PDFs, which cost 1 credit per 100 pages.

Conversations

conversation = client.conversations.create(document.id)
turn = client.conversations.send(conversation.id, "Where does the brother first appear?")
print(turn.assistant_message, turn.task_cost, turn.sources)

Turns answer synchronously and are charged by the text the assistant reads and writes.

Errors

import alighieria

try:
    client.synopses.create(doc_id)
except alighieria.InsufficientCreditsError:
    ...  # 402: top up or wait for the next reload
except alighieria.RateLimitError as error:
    ...  # 429: error.retry_after seconds
except alighieria.APIStatusError as error:
    print(error.status_code, error.code, error.message)

All of them inherit from AlighieriaError.

Retries and credits

The SDK retries a request up to twice, and only when a repeat cannot charge you twice:

• every 429 whose Retry-After is at most 60 seconds;
• failures to connect;
• timeouts and 5xx on reads, and on corrections.create and documents.create_markdown, which are sent with an idempotency key.

Other launches and conversation turns are never repeated after a timeout or a 5xx: the first attempt may have started. Before launching again, look for the job with client.jobs.list(source_id=doc_id).

Status polls have their own limit of 60 per minute. Lists and full reads (result(), findings(), documents.list(), jobs.list()) share 10 per minute, 30 per hour and 100 per day, so keep them out of tight loops. client.rate_limit holds the limit headers of the last response.

Async

AsyncAlighieria has the same methods, awaited:

import asyncio
from alighieria import AsyncAlighieria


async def main():
    async with AsyncAlighieria() as client:
        job = await client.synopses.create(doc_id)
        await job.wait()
        print((await job.result()).content)
        async for document in client.documents.iter():
            print(document.title)


asyncio.run(main())

Configuration

client = Alighieria(
    api_key="ak_...",  # default: ALIGHIERIA_API_KEY
    base_url="https://...",  # default: ALIGHIERIA_API_URL, then production
    timeout=60.0,  # per request; conversation turns use 120
    max_retries=2,
    poll_interval=5.0,
    max_poll_interval=30.0,
)

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy

Two parts of the package are generated, and the tests fail when either is out of date:

• src/alighieria/_generated.py comes from docs/openapi.public.v1.json: python scripts/generate_models.py after the spec changes.
• src/alighieria/_sync/ comes from src/alighieria/_async/: python scripts/unasync.py after editing the async client. Never edit _sync by hand.

examples/smoke.py and examples/smoke_async.py run a full cycle against a real API, with the sync and the async client, and spend credits.