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.
• The client reads its API key from the POMA_API_KEY environment variable (or api_key=).
• Create a key in the POMA console at https://console.poma-ai.com, tab Project settings.
• This release talks to the POMA API v4 (https://api.poma-ai.com/v4).

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())

Retrieval and hybrid search

Hosted indexing and hybrid search (formerly Grill, poma.Grill) is now a separate package with its own API and repository, poma-ai/index4ai-sdk:

pip install index4ai

poma itself covers PrimeCut chunking and the LangChain / LlamaIndex / Qdrant integrations.

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 !