ContextGem: structured data extraction from documents

ContextGem is a free, open-source Python framework for turning document content into structured data. You describe the information you want, connect a suitable model, and receive typed results that your application can process. It is designed for developers building document workflows, rather than people looking for a hosted upload-and-chat interface.

What does ContextGem actually do?

Imagine reviewing service agreements to find payment terms, notice periods and monthly fees. Reading every agreement and copying values into a system takes time. With ContextGem, a developer defines those requirements once, then runs the extraction against documents and checks the returned values against their sources.

The framework, maintained by Shcherbak AI AS, handles extraction prompts, data models and validation around the models you configure. It can also request supporting passages and explanations. This makes it useful for document analysis, information intake and review workflows where a plain summary would leave too much work for the next step.

Extract passages, typed fields and checkable evidence

ContextGem separates two related tasks. An Aspect identifies the original passages about a topic, such as termination clauses. A Concept extracts a value or assessment, such as a notice period, a date or a classification. Concepts can apply to the whole document or to an aspect; nested aspects help focus the context.

Supported concept types include strings, numbers, dates, booleans, labels, ratings and JSON objects. For a fee table, a JSON-object concept could describe a service name, monthly fee and billing arrangement. These are programmatically usable values, rather than a free-form paragraph that another script must interpret.

For LLM extraction, enable references to paragraphs or sentences when reviewers need an audit trail, and request justifications when an explanation adds value. A reference helps locate the source; it does not prove that the model interpreted it correctly. Compare important values with the document before writing them into a production system.

Run a first document extraction in Python

Start with a small document whose expected answers you already know. The current installation documentation specifies Python 3.11–3.14, with additional platform exceptions.

1. Install the framework with pip install -U contextgem. For file conversion, install pip install -U "contextgem[docling]".
2. Create a Document(raw_text=...) for text. For a file, use Docling's DocumentConverter().convert(file), then pass result.document into Document.from_docling().
3. Add the aspects and concepts you need. Use precise descriptions, appropriate types and references for fields that require checking.
4. Configure DocumentLLM with a supported model and the provider credentials or local endpoint it requires. Keep API keys in environment variables.
5. Run doc = llm.extract_all(doc), then inspect doc.get_concept_by_name(...).extracted_items and the corresponding source references.
6. Test missing fields, ambiguous wording and several layouts before reusing the pipeline on a larger set.

The official quickstart contains complete examples. The Docling integration guide explains PDF, DOCX, PPTX, XLSX and HTML conversion, including retained document structure and available page references. File conversion quality still affects extraction quality.

Choose an LLM or a decision model for each task

Through LiteLLM, ContextGem supports documented cloud providers and local backends such as Ollama and LM Studio. An LLM handles open-ended values, reasoning and supported text or image inputs. Small local models may struggle with detailed extraction instructions, so check them on representative documents.

Decision models serve a narrower task: closed questions with boolean, label or rating answers, plus text-aspect selection. They return answer probabilities and support decision thresholds, rather than generating open-ended text. They do not provide the same image or arbitrary JSON extraction capabilities as an LLM.

Model groups can route different aspects and concepts to models by role and use fallbacks. Compare the outputs, latency and actual cost on your own examples before deciding which model handles each field.

Reuse the workflow without confusing it with document search

An ExtractionPipeline preserves reusable aspects and concepts. Documents, pipelines and supported model configurations can be serialized; to_dict() and to_json() make results easier to store or pass into another application. Your application still decides how to write those values into a database or spreadsheet.

The agent workflow guide covers extracting metadata during ingestion, exposing extraction as an agent tool and using closed questions at decision points. Output-language settings can control string answers and justifications while source references remain in their original language.

ContextGem reads individual documents in depth, optionally in paragraph batches. It does not itself search a document corpus or answer cross-document queries. Use it alongside a retrieval system when your application needs both document discovery and detailed extraction.

Understand software costs and document privacy

As checked on October 29, 2026, the framework is free under the Apache 2.0 license. Commercial use is subject to that license's conditions. Cloud model calls can carry separate provider charges; local inference requires your own compute. There is no universal ContextGem allowance or per-document price stated here.

The official security policy says ContextGem collects no telemetry and sends document content and generated prompts only to the models you configure. With cloud models, review that provider's retention and processing terms. With local models, check endpoint and fallback settings. Installation, sentence-segmentation models and pricing metadata can still involve public-data downloads, so local inference does not automatically mean every part of the environment is offline.

Frequently asked questions

Is ContextGem completely free to run?

The framework is free and open source. Paid model APIs, local hardware and your deployment costs remain separate; do not treat the software license as an unlimited inference plan.

Can it extract information from a PDF?

Yes, the documented file workflow uses Docling, then Document.from_docling(result.document). Inspect the converted content and extracted references, especially when the original file has difficult layouts or scans.

Can I use a local model for private documents?

Supported local backends include Ollama and LM Studio through LiteLLM. Configure the local endpoint deliberately, avoid unintended cloud fallbacks, and validate model quality and network requirements before processing sensitive material.

Does it replace RAG across a document collection?

It focuses on analyzing individual documents. Corpus search and cross-document retrieval require an additional system; ContextGem can supply structured data for that broader workflow.

Official resources and developer community

• Installation requirements: supported Python versions, Alpine/musl limitations and Intel Mac exceptions.
• Supported model backends: cloud and local configuration choices.
• GitHub Discussions: implementation questions and community discussion.
• Issue tracker: bugs and feature requests.
• Migration guide for version 1: changes affecting applications built on 0.x.