Your model accepts 8K, 128K, or 200K tokens — your documents don't care. Annual reports, BRDs, legal contracts, log archives, codebases: they all blow past the window, and naive truncation silently drops the facts you need.

LongLoom splits the problem the way humans do — read in chunks, extract, combine, condense — as a LangGraph pipeline with measured information preservation, over any LLM you already use and any storage you already run.

              ┌───────────────┐
 big document ─► CHUNK + STORE ─► every byte persisted (SQLite / Postgres / Mongo / …)
              └───────┬───────┘
                      ▼   MAP      one LLM call per chunk — verbatim or summarizing
              ┌───────────────┐
              │  map results  │
              └───────┬───────┘
                      ▼   MERGE   window-sized hierarchical combine calls
              ┌───────────────┐           (scales past any single context window)
              │  merged draft │
              └───────┬───────┘
                      ▼   REPAIR  bounded condensation loop, only if still too big
              ┌───────────────┐
              │ final result  │  +  verification: every fact accounted for
              └───────────────┘

Install

From PyPI — the usual way:

pip install longloom                 # core: 2 dependencies only
pip install "longloom[all]"          # batteries included (all providers + databases)
pip install "longloom[tiktoken,nvidia]"   # pick exactly what you need

Extras: [tiktoken] [nvidia] [openai] [postgres] [mysql] [mongodb] [supabase] [databases] [dev]

Python ≥ 3.10.

From source (contributors or pinned forks):

git clone https://github.com/sumitnemade/longloom && cd longloom
pip install -e ".[dev]"              # editable install + test tooling
pytest tests/ -v                     # 48 tests; network-dependent ones self-skip

60-second quickstart

import os
from longloom import MapReduceProcessor, SQLiteContextStore, init_llm

processor = MapReduceProcessor(
    llm=init_llm("nvidia", "nvidia/nemotron-3-ultra-550b-a55b",
                 api_key=os.environ["NVIDIA_API_KEY"],   # your app owns the key
                 thinking=False),
    store=SQLiteContextStore("ctx.db"),
    max_chunk_tokens=3000,
    max_context_tokens=8192,          # your model's real window
)

result = processor.process(
    annual_report,                    # 50K tokens? 500K? doesn't matter
    task="Summarize the key findings",
)
print(result["final_result"])
print(f"{result['num_chunks']} chunks · {result['total_input_tokens']:,} tokens · "
      f"{result['repair_attempts']} repairs")

Every run is persisted and queryable afterwards:

processor.search_session(result["session_id"], "revenue")   # which chunks mention it
processor.retrieve_chunks(result["session_id"])              # original text, byte-faithful
processor.get_session_info(result["session_id"])             # chunk/token stats

When facts must not be lost

Summarizing prompts measurably drop facts (we measured 2–10% on messy documents — different facts every run). When you need everything:

from longloom import PromptTemplates

processor = MapReduceProcessor(
    llm=llm,
    store=store,
    prompts=PromptTemplates.for_extraction(),   # verbatim line-copy mode
    ...
)

Measured result: 100% fact preservation (41/41 planted facts in a log/JSON/ email/table/document mix — stable across repeated real-LLM runs on NVIDIA and OpenAI). The trade-off is output length: extraction copies, it doesn't compress. Summaries → DEFAULT_PROMPTS; completeness → for_extraction().

Any LLM

init_llm("nvidia",    "nvidia/nemotron-3-ultra-550b-a55b",
         api_key=os.environ["NVIDIA_API_KEY"], thinking=False)
init_llm("openai",    "gpt-4o-mini", api_key=os.environ["OPENAI_API_KEY"])
init_llm("anthropic", "claude-sonnet-4-20250514", api_key=os.environ["ANTHROPIC_API_KEY"])
init_llm("groq" | "mistral" | "deepseek" | "together", ..., api_key=...)
init_llm("ollama", "llama3.1")                               # no key needed

🔐 Keys are constructor arguments, never environment reads. LongLoom itself never touches os.environ for credentials — your application reads the secret (vault, env, wherever) and passes it explicitly. Explicit beats implicit when credentials are involved.

…or bring your own: any LangChain BaseChatModel, or a bare function — the minimum contract is str → str:

processor = MapReduceProcessor(llm=lambda prompt: my_gateway(prompt), store=store)

Custom / self-hosted endpoints (vLLM, LiteLLM, Azure APIM, gateways)

llm = init_llm(
    "custom", "acme-internal-model",
    base_url="http://vllm.internal:8000/v1",
    headers={"X-Tenant": "acme", "X-Trace-Id": "tr-1"},   # custom headers on every call
    api_key="internal-token",      # optional — local servers may need none
)

Wire-verified: requests hit your base_url with your headers attached, and usage metadata from the endpoint flows into the observability events.

Provider quirks are handled for you: NVIDIA reasoning models get real model IDs, a thinking toggle, and a content=None starvation guard; OpenAI extra_body and temperature restrictions are abstracted away.

Any storage

from longloom import create_store

store = create_store("sqlite:///ctx.db")                     # default, single file
store = create_store("postgresql://user:pw@host/longloom")
store = create_store("mysql://user:pw@host/longloom")
store = create_store("mongodb://host:27017/longloom")
store = create_store("https://myteam.supabase.co")           # + SUPABASE_KEY
store = create_store("json://data")                          # human-readable JSONL
store = create_store("memory://")                            # ephemeral

All backends pass the identical contract suite (round-trip, filters, budget, upsert idempotency, search, stats, delete).

Embedding in existing databases

No dedicated database needed — LongLoom lives inside your tables with your column names, next to your application's own data:

store = create_store(
    "postgresql://app@host/mydb",        # the database you already run
    table="app_document_chunks",         # your table
    columns={                            # your column names
        "id": "chunk_pk", "content": "text_body",
        "metadata": "meta_json", "session_id": "sess",
    },
    namespace="support-agent",           # several apps share one table safely
    init_schema=False,                   # your migrations own the DDL
)

Same table, two apps, zero cross-talk — namespaces isolate sessions even with identical session IDs. See examples/17_embed_existing_database.py.

Built for production

Honest limits

• Map/merge aggregates; it doesn't reason globally — detect_conflicts=True flags contradictions, but reconciling them is a human decision.
• A single line larger than the chunk budget is still hard-split (at whitespace, so identifier tokens survive) — multi-line records can span chunk seams.
• Async support is thread-offloaded (process_async), not a native async graph.
• MSSQL/Oracle dialects are SQL-generation-tested; live-server verification is on the roadmap.
• tiktoken approximates non-OpenAI tokenizers — keep 2× headroom on chunk sizes.

Examples — every claim is a runnable script

git clone https://github.com/sumitnemade/longloom && cd longloom
pip install -e ".[dev]"
export NVIDIA_API_KEY=...        # or OPENAI_API_KEY=...
python examples/run_all.py       # 17 examples; skips gracefully what's missing

Test it yourself

pip install -e ".[dev]"
pytest tests/ -v                       # 50 tests; network-dependent ones self-skip
NVIDIA_API_KEY=... pytest tests/ -v    # + real NVIDIA, Postgres, MySQL, MongoDB
OPENAI_API_KEY=... pytest tests/ -v    # + real OpenAI end-to-end

FAQ

Do I need LangChain? Only langchain-core (a lightweight dependency). Your LLM can even be a plain function.

What if my output is bigger than the window? The repair loop condenses it, and the merge stage itself groups results hierarchically — oversized inputs are the library's job, not yours.

Can I run the map phase in parallel? Yes — max_workers=8 on the processor. Pacing and retries are shared and lock-guarded across workers.

A run crashed halfway — do I start over? No: process(..., resume=True) reuses the checkpointed map results and maps only the missing chunks.

Is my data sent anywhere? Only to the LLM provider you configure. Storage stays in whatever database you chose.

Why not just use a 200K-token model? Cost, latency, and attention decay. Chunked extraction is cheaper per token and verifiably complete — and LongLoom works with any window, so you're never locked to a model generation.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md for setup and conventions (every fix ships with a test; honest verification is the house style). By participating you agree to the Code of Conduct.

License

MIT — © The LongLoom Maintainers