POMA: Preserving Optimal Markdown Architecture

Quick-Start Guide

Installation

Requires Python 3.10+. Install the core package:

pip install poma

For different integrations:

pip install 'poma[langchain]'
pip install 'poma[llamaindex]'
pip install 'poma[qdrant]'

# Or LangChain/LlamaIndex/Qdrant including example extras:
pip install 'poma[all]'

• You may also want: pip install python-dotenv to load API keys from a .env file.
• API keys required (POMA_API_KEY) for the POMA AI client via environment variables.
• To request a POMA_API_KEY, please contact us at sdk@poma-ai.com

Usage

from poma import PrimeCut, generate_cheatsheets

pc = PrimeCut(api_key="your_key")

# Ingest a document — submits the file, polls, and returns typed results
result = pc.ingest("document.pdf")

print(result.chunksets[0])
print(result.chunks[0].content)

# Eco ingestion uses the same flow against the eco endpoints
eco_result = pc.ingest_eco("document.pdf")

To test this flow from the command line (requires POMA_API_KEY in the environment):

python -m poma document.pdf          # run both ingest and ingest_eco
python -m poma path/to/file.pdf      # custom file
python -m poma document.pdf --no-eco   # standard ingest only
python -m poma document.pdf --eco     # eco ingest only

Generate cheatsheets as a top-level utility:

cheatsheets = generate_cheatsheets(
    relevant_chunksets=result.chunksets,
    all_chunks=result.chunks,
)
print(cheatsheets[0]["content"])

If you already have a .poma archive, unpack it directly:

from poma import unpack

archived_result = unpack("document.poma")
print(archived_result.chunks[0].content)

Async clients use the same API shape:

import asyncio

from poma import AsyncPrimeCut


async def main() -> None:
    async with AsyncPrimeCut(api_key="your_key") as pc:
        result = await pc.ingest("document.pdf")
        print(result.chunksets[0])


asyncio.run(main())

Grill (RAG / hybrid search)

Grill ingests documents into a per-project namespace and serves prompt-ready retrieval context for RAG.

Auth note: Grill endpoints require a project-level key (prefix poma_proj_gr_...), not the account-level POMA_API_KEY. Set POMA_GRILL_API_KEY in your environment. The SDK validates the prefix at construction and raises InvalidGrillApiKeyError if you accidentally use the wrong one.

from poma import Grill

g = Grill()  # reads POMA_GRILL_API_KEY

# 1. Ingest a document. Grill indexes it into your project namespace
#    (no archive download). `result.status == "done"` when ready.
#    Attach up to 64 categorical labels for query-time filtering, and
#    two integer fields (e.g. a timestamp / revision) for range queries.
result = g.ingest(
    "document.pdf",
    labels=["year:1982", "source:treasury"],
    meta_int_1=1672531200,
)
print(result.job_id, result.status, result.usage)

# 1b. Or let Grill fetch the file itself from a public URL — no upload.
#     Optionally POST a webhook when the job finishes; the value is
#     "<url>|<header>:<value>|..." (server caps it at 1024 chars).
result = g.ingest(
    remote_url="https://example.com/document.pdf",
    completion="https://example.com/hook|x-api-key:secret",
)

# 2. Run hybrid search across all documents in the namespace.
#    Returns a prompt-ready XML+Markdown block — drop it into an LLM prompt.
#    Optionally narrow by labels: labels_any (match any) / labels_all (match all).
ctx = g.search(
    "How do I configure retries?",
    target_tokens=2048,
    labels_all=["source:treasury"],
    meta_int_1_gte=1640995200,  # range filter on the integer metadata
)
print(ctx.context)

# 3. List, inspect, and delete documents in the namespace.
#    To find the doc you just ingested, match source_job_id to the job_id.
for doc in g.list_docs():
    print(doc.doc_id, doc.filename, doc.pages)

deleted = g.delete_doc(doc.doc_id)
print(deleted.vectors_deleted, deleted.storage_deleted)

The async client mirrors the same surface:

import asyncio
from poma import AsyncGrill


async def main() -> None:
    async with AsyncGrill() as g:
        ctx = await g.search_in_doc("summarize section 3", "doc_abc123")
        print(ctx.context)


asyncio.run(main())

Example Implementations

All examples, integrations, and additional information can be found in our GitHub repository: poma-ai/poma

We provide example implementations to help you get started with POMA AI:

• example.py — A standalone implementation for documents, showing the basic POMA AI workflow with simple keyword-based retrieval
• example_langchain.py — Integration with LangChain, demonstrating how easy it is to use POMA AI with LangChain
• example_llamaindex.py — Integration with LlamaIndex, showing how simple it is to use POMA AI with LlamaIndex

Note: The integration examples use OpenAI embeddings. Make sure to set your OPENAI_API_KEY environment variable, or replace the embeddings with your preferred ones.

All examples follow the same two-phase process (ingest → retrieve) but demonstrate different integration options for your RAG pipeline.

! Please do NOT send any sensitive and/or personal information to POMA AI endpoints without having a signed contract & DPA !