Source: http://www.poma-ai.com/docs/sdk/reference/grill

# 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](#authentication) below.

For async code, use [`AsyncGrill`](/sdk/reference/async-grill).

## Constructor

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

| Parameter | Default | Notes |
| --- | --- | --- |
| `api_key` | `None` | Reads `POMA_GRILL_API_KEY` if omitted. Must start with `poma_prod_gr_`. Account keys (`poma_acc_…`) are rejected locally. |
| `timeout` | `600.0` | HTTP timeout in seconds, passed through to `httpx`. |
| `client` | `None` | Pre-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](/grill/getting-started/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

### `search`

```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,
    target_tokens: int | 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.

| Parameter | Effect |
| --- | --- |
| `doc_filter` | Restrict to one document by `doc_id`. For per-doc Q&A, prefer `search_in_doc(...)`. |
| `exclude_doc_ids` | Drop specific docs from the candidate set (e.g. recently superseded versions). |
| `return_assets` | Return the cited documents' figures (and tables, where available) in the response `assets` field, keyed by `doc_id`. Images are base64 data URIs; resolved per document. |
| `min_relevance` | Relevance floor, 0–1 (default `0.3`). Higher = stricter; lower-relevance hits are dropped before token budgeting. |
| `target_tokens` | Soft token budget — the typical answer size (default `5000`). The knob to size a response. Can never exceed `max_tokens` (clamped down if it would). |
| `max_tokens` | Hard ceiling (default `15000`); only matters for tight multi-document clusters. Set it below `target_tokens` and the soft target is clamped down to match — the hard ceiling always wins. |

### `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,
    target_tokens: int | 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

| Exception | Raised when |
| --- | --- |
| `InvalidGrillApiKeyError` | Missing / wrong-prefix API key — raised at construction, before any HTTP. |
| `ApiError` | Server returned a non-2xx response. `error.status_code` and `error.payload` carry the detail. |
| `InvalidResponseError` | Server response was unparseable or missing a required field (e.g. `job_id` from `submit`). |

Full list: [Exceptions](/sdk/reference/exceptions).

## See also

- [Grill concept page](/sdk/concepts/grill) — workflow walkthrough.
- [`AsyncGrill`](/sdk/reference/async-grill) — async counterpart.
- [Grill product docs](/grill/) — endpoint-level reference, RetrievalContext format, billing.