POMA AI ⬣ Docs

Appearance

python
from poma import PrimeCut

PrimeCut is the main synchronous client for new SDK integrations.

Constructor ​

python
PrimeCut(
    api_key: str | None = None,
    *,
    timeout: float = 600.0,
    client: httpx.Client | None = None,
)

If api_key is omitted, the client reads POMA_API_KEY.

Methods ​

submit ​

python
submit(
    file_path,
    *,
    base_url: str | None = None,
    show_progress: bool = False,
    eco: bool = False,
) -> str

Submit a document and return the job ID.

show_progress is accepted for compatibility and ignored.

Set eco=True to target the eco ingestion endpoints without switching methods.

collect ​

python
collect(
    job_id: str,
    *,
    show_progress: bool = False,
    initial_delay: float = 5.0,
    poll_interval: float = 3.0,
    max_interval: float = 15.0,
    download_dir = None,
    filename: str | None = None,
) -> PomaResult

Collect a submitted job and return typed PomaResult.

collect(...) tries the status SSE stream first and falls back to adaptive polling if streaming is unavailable.

submit_eco ​

python
submit_eco(
    file_path,
    *,
    base_url: str | None = None,
) -> str

Deprecated alias for submit(..., eco=True).

poll ​

python
poll(
    job_id: str,
    *,
    initial_delay: float = 5.0,
    poll_interval: float = 3.0,
    max_interval: float = 15.0,
    show_progress: bool = False,
    download_dir = None,
    filename: str | None = None,
) -> PomaArchive

Deprecated polling helper. It skips SSE and returns PomaArchive instead of PomaResult.

ingest ​

python
ingest(
    file_path,
    *,
    base_url: str | None = None,
    initial_delay: float = 5.0,
    sse: bool | None = None,
    poll_interval: float = 3.0,
    max_interval: float = 15.0,
    show_progress: bool = False,
    download_dir = None,
    filename: str | None = None,
) -> PomaResult

Submit, collect, download, and unpack in one call.

ingest_eco ​

python
ingest_eco(
    file_path,
    *,
    base_url: str | None = None,
    initial_delay: float = 5.0,
    sse: bool | None = None,
    poll_interval: float = 3.0,
    max_interval: float = 15.0,
    show_progress: bool = False,
    download_dir = None,
    filename: str | None = None,
) -> PomaResult

Run the same flow against the eco endpoints.

Passing sse=False is still supported, but it is deprecated because collect() now chooses the transport automatically.

read_status_sse ​

python
read_status_sse(
    job_id: str,
    *,
    show_progress: bool = False,
    download_dir = None,
    filename: str | None = None,
) -> PomaArchive

Deprecated low-level SSE helper.

handle_job_status ​

python
handle_job_status(
    job_id: str,
    status_data: dict[str, Any],
    *,
    show_progress: bool = False,
    download_dir = None,
    filename: str | None = None,
) -> PomaArchive | StateProcessing | StatePending

Deprecated low-level status parser kept for compatibility.

create_cheatsheet ​

python
create_cheatsheet(
    relevant_chunksets: list[dict[str, Any]],
    all_chunks: list[dict[str, Any]],
) -> str

Deprecated helper. Use generate_cheatsheets(...) and read the first item's content.

create_cheatsheets ​

python
create_cheatsheets(
    relevant_chunksets: list[dict[str, Any]],
    all_chunks: list[dict[str, Any]],
) -> list[dict[str, Any]]

Deprecated helper. Use the top-level generate_cheatsheets(...).

close ​

Close the underlying httpx.Client.

PrimeCut also supports context-manager usage:

python
with PrimeCut() as client:
    result = client.ingest("example.pdf")

For asyncio apps, use AsyncPrimeCut.