POMA AI ⬣ Docs

Appearance

Grill Client API Reference ​

python
from poma import Grill

Grill is the synchronous client for the POMA Grill (RAG / hybrid-search) product. It is project-scoped and validates its API key prefix locally — see Authentication below.

For async code, use AsyncGrill.

Constructor ​

python
Grill(
    api_key: str | None = None,
    *,
    timeout: float = 600.0,
    client: httpx.Client | None = None,
)
ParameterDefaultNotes
api_keyNoneReads POMA_GRILL_API_KEY if omitted. Must start with poma_prod_gr_. Account keys (poma_acc_…) are rejected locally.
timeout600.0HTTP timeout in seconds, passed through to httpx.
clientNonePre-built httpx.Client to reuse a connection pool. Bearer header is set by the SDK either way.

Raises InvalidGrillApiKeyError when the resolved key is missing, has the account prefix, or has any other unexpected prefix.

Authentication ​

Grill requires a project-level key issued by POST /projects (with product:"grill"). The Bearer token is bound to one project namespace — every ingest, every search, every list goes against that namespace.

python
import os
os.environ["POMA_GRILL_API_KEY"] = "poma_prod_gr_…"

from poma import Grill
g = Grill()

Full provisioning flow: Grill Authentication.

Ingest methods ​

submit ​

python
submit(
    file_path: str | os.PathLike[str],
    *,
    base_url: str | None = None,
) -> str

Submit a document to Grill ingestion. Returns the job_id. Use this when you want to capture the job ID and collect later.

base_url is used by HTML inputs to resolve relative links against a known origin.

collect ​

python
collect(
    job_id: str,
    *,
    show_progress: bool = False,
    initial_delay: float = 2.0,
    poll_interval: float = 2.0,
    max_interval: float = 10.0,
) -> GrillIngestResult

Poll a previously submitted Grill job until it reaches done or failed. Streams progress through the status SSE channel and falls back to adaptive polling if streaming is unavailable.

Grill ingest does not produce a downloadable archive. To work with the indexed document, call list_docs() and match DocInfo.source_job_id to the job_id you collected.

ingest ​

python
ingest(
    file_path: str | os.PathLike[str],
    *,
    base_url: str | None = None,
    show_progress: bool = False,
    initial_delay: float = 2.0,
    poll_interval: float = 2.0,
    max_interval: float = 10.0,
) -> GrillIngestResult

Combined submit + collect — submit a document and wait for ingestion to finish in one call.

Search methods ​

python
search(
    query: str,
    *,
    doc_filter: str | None = None,
    exclude_doc_ids: list[str] | None = None,
    return_assets: bool | None = None,
    return_page_images: bool | None = None,
    min_relevance: float | None = None,
    max_tokens: int | None = None,
) -> GrillContext

Hybrid search across every document in the project namespace. Returns a GrillContext whose .context field is a prompt-ready XML + Markdown block.

ParameterEffect
doc_filterRestrict to one document by doc_id. For per-doc Q&A, prefer search_in_doc(...).
exclude_doc_idsDrop specific docs from the candidate set (e.g. recently superseded versions).
return_assetsInclude extracted assets (figures, tables) referenced by the matched chunks.
return_page_imagesInclude page-image URLs alongside the textual context.
min_relevanceFloor on relevance score; 0–1. Lower-relevance hits are dropped before token budgeting.
max_tokensServer-enforced budget for the returned context block.

search_in_doc ​

python
search_in_doc(
    query: str,
    doc_filter: str,
    *,
    exclude_doc_ids: list[str] | None = None,
    return_assets: bool | None = None,
    return_page_images: bool | None = None,
    min_relevance: float | None = None,
    max_tokens: int | None = None,
) -> GrillContext

Search scoped to one document. doc_filter is required here. Use for in-document chatbots, per-document summarization, and section-level retrieval.

Document methods ​

list_docs ​

python
list_docs() -> list[DocInfo]

Return every document currently indexed in the project namespace. Each DocInfo carries doc_id, filename, pages, and source_job_id.

get_doc ​

python
get_doc(doc_id: str) -> DocInfo

Look up one document by doc_id. Raises ValueError on empty input; returns 404 from the server as the standard ApiError.

delete_doc ​

python
delete_doc(doc_id: str) -> DeleteDocResponse

Remove a document from the project namespace. The response reports vectors_deleted and storage_deleted counts so you can verify the cleanup landed.

Lifecycle ​

close ​

python
close() -> None

Close the underlying httpx.Client. Also called automatically when used as a context manager:

python
with Grill() as g:
    g.ingest("doc.pdf")
# client closed on exit

Exceptions ​

ExceptionRaised when
InvalidGrillApiKeyErrorMissing / wrong-prefix API key — raised at construction, before any HTTP.
ApiErrorServer returned a non-2xx response. error.status_code and error.payload carry the detail.
InvalidResponseErrorServer response was unparseable or missing a required field (e.g. job_id from submit).

Full list: Exceptions.

See also ​