ContextGem icon

ContextGem

ContextGem is a free, open-source Python framework that extracts structured data and insights from document text and images using LLMs and decision models. It helps developers build reusable extraction pipelines with typed outputs, source references, and optional justifications.

ContextGem

Document extraction with LLMs and decision models

ContextGem is a free, open-source Python framework for extracting structured data and insights from documents with large language models and decision models. It packages prompt generation, data-model validation, source mapping, justifications, and multi-step orchestration into a declarative pipeline that can be reused and serialized.

Users describe the aspects and concepts they want to extract from document text or images. LLMs can produce typed answers and reasoning-oriented values, while decision models handle supported closed questions such as yes/no, labels, and ratings by returning probabilities for possible answers. Extracted items can be linked back to source paragraphs or sentences, which helps readers inspect where a result came from.

Key features

Declarative extraction

Describe aspects and concepts in code; the framework generates the extraction prompts rather than requiring users to write them manually.

Typed outputs

Return text, numbers, dates, booleans, labels, ratings, and JSON objects as typed, validated items.

Source references and justifications

Map extracted items to the paragraphs or sentences that support them, with optional justifications for the result.

Nested document context

Organize extraction around aspects, sub-aspects, and concepts so model processing can focus on relevant parts of a document.

Model routing

Route each aspect or concept to an appropriate LLM or decision model, with model fallback available through a model group.

Probability-based decisions

Use decision models for supported closed questions and receive probabilities for possible answers, with a configurable decision threshold.

Use cases

  • Contract analysis

    Define payment terms, fees, anomalies, entities, or other contract concepts and return the relevant passages with optional justifications for review.

  • Document classification at scale

    Process repeated document batches with closed questions such as Boolean, label, or rating classifications when a fast, lower-cost decision-model answer is sufficient.

  • Structured data pipelines

    Extract structured fields such as dates, numbers, labels, and JSON objects from business documents for use in downstream Python workflows.

  • Auditable document review

    Investigate findings in reports or agreements by tracing each extracted item to the paragraph or sentence where it appears.

  • Mixed-model extraction

    Combine model types in one pipeline: use an LLM for open-ended or reasoning-heavy questions and a decision model for suitable closed questions.

Pros and Cons

Pros

  • Declarative descriptions reduce the need to write and maintain extraction prompts manually.
  • Typed validation and source references make extracted results easier to inspect and use in downstream workflows.
  • Supports both reasoning-oriented LLM extraction and probability-based decision-model workflows.
  • Can work with cloud or local model providers, subject to provider configuration and supported interfaces.

Cons

  • The framework depends on configuring a compatible cloud or local model, and model quality can affect extraction results.
  • The project recommends testing smaller local LLMs on sample documents because they may not consistently follow detailed extraction instructions.
  • The current package metadata requires Python 3.11 or newer; Python 3.10 is no longer supported.

FAQ

How do you get started with ContextGem?

Install the package with `uv add contextgem` or `pip install -U contextgem`. For PDF, DOCX, and other file conversion through Docling, the project documents `uv add "contextgem[docling]"`. You then create a `Document`, describe aspects or concepts to extract, configure a model, and call the extraction workflow.

How does the extraction workflow work?

You describe the information to extract instead of writing prompts directly. ContextGem generates prompts, validates results into typed items, and can attach references to source paragraphs or sentences. The example workflow uses `DocumentLLM.extract_all(doc)` to run extraction.

When should you use an LLM versus a decision model?

LLMs can extract open values and answers that require reasoning, including aspects and concept types from text and images. Decision models are intended for closed questions such as Boolean, label, and rating concepts from text; they return probabilities for possible answers rather than generated text.

Which model providers can ContextGem use?

The project supports cloud or local LLMs through LiteLLM, with examples including OpenAI, Anthropic, Google, Azure OpenAI, xAI, Ollama, and LM Studio. It also documents decision-model support including TypeSafe Jev, OpenAI Decisions API, and Microsoft Foundry. The exact availability and configuration depend on the selected provider.

What runtime and model limitations should users check?

The current project metadata requires Python 3.11 or newer and below 3.15. The repository notes that Python 3.10 is no longer supported in the 1.0 migration guidance. Smaller local LLMs may not follow detailed extraction instructions reliably, so the documentation recommends testing them on a sample of documents.

Quick Facts

Category
Developer tool; document intelligence
License
Apache-2.0
Language
Python
Supported runtime
Python 3.11 to below 3.15
Input types
Document text and, for LLM extraction, images
Distribution
Open-source package on GitHub