# ContextGem

> ContextGem is a free, open-source framework for extracting structured data and insights from documents using LLMs and decision models: you describe what to extract as aspects and concepts, and ContextGem handles the prompts, the data models, the source references and the justifications.


2025, Shcherbak AI AS

## Pages

- [Welcome to ContextGem Documentation!](https://contextgem.shcherbak.ai/index.html.md): ContextGem is a free, open-source framework for extracting structured data and insights from documents using LLMs and decision models: start here for the guides, examples and API reference.
- [Why ContextGem?](https://contextgem.shcherbak.ai/motivation/index.html.md): Why ContextGem: the problems that extracting structured data from documents with LLMs involves, and how the framework solves them so that you describe only what to extract.
- [How it works](https://contextgem.shcherbak.ai/how_it_works/index.html.md): How ContextGem works: documents, aspects and concepts, how LLMs, decision models and model groups extract them, and what ContextGem is not (a RAG or an agent framework).
- [Installation](https://contextgem.shcherbak.ai/installation/index.html.md): How to install ContextGem with uv or pip, and what it requires.
- [Quickstart examples](https://contextgem.shcherbak.ai/quickstart/index.html.md): Complete, self-contained examples of extracting aspects and concepts from a document with ContextGem, with an LLM or a decision model, step by step.
- [Creating Documents](https://contextgem.shcherbak.ai/documents/document_config/index.html.md): How to create a Document from text, paragraphs or images, add aspects and concepts to it, give paragraphs additional context, locate paragraphs and sentences in it, and use SaT models without network access.
- [Aspect Extraction](https://contextgem.shcherbak.ai/aspects/aspects/index.html.md): How to extract aspects, the sections and topics of a document that you define, with sub-aspects, concepts and justifications, and how to read the extracted paragraphs or sentences.
- [Supported Concepts](https://contextgem.shcherbak.ai/concepts/supported_concepts/index.html.md): The concept types of ContextGem, each for one kind of data to extract: text, true/false values, numbers, dates, ratings, labels and JSON objects.
- [StringConcept](https://contextgem.shcherbak.ai/concepts/string_concept/index.html.md): How to extract text values, from names and titles to conclusions and findings, with StringConcept, including examples, references and justifications.
- [BooleanConcept](https://contextgem.shcherbak.ai/concepts/boolean_concept/index.html.md): How to get true/false answers about a document or an aspect with BooleanConcept, e.g. whether it contains a clause or meets a condition.
- [NumericalConcept](https://contextgem.shcherbak.ai/concepts/numerical_concept/index.html.md): How to extract or calculate numbers (integers, floats or both) from a document or an aspect with NumericalConcept.
- [DateConcept](https://contextgem.shcherbak.ai/concepts/date_concept/index.html.md): How to extract dates written in any format as datetime.date objects with DateConcept.
- [RatingConcept](https://contextgem.shcherbak.ai/concepts/rating_concept/index.html.md): How to rate a document or an aspect on a numerical scale that you define with RatingConcept.
- [JsonObjectConcept](https://contextgem.shcherbak.ai/concepts/json_object_concept/index.html.md): How to extract structured data as JSON objects with JsonObjectConcept, with a structure that you define as a dictionary or as classes, including nested ones.
- [LabelConcept](https://contextgem.shcherbak.ai/concepts/label_concept/index.html.md): How to classify a document or an aspect with predefined labels using LabelConcept, choosing exactly one label (multi-class) or any number of them (multi-label).
- [Extraction Pipelines](https://contextgem.shcherbak.ai/pipelines/extraction_pipelines/index.html.md): How to bundle aspects and concepts into a reusable ExtractionPipeline, apply it to many documents, and serialize it.
- [Supported LLMs](https://contextgem.shcherbak.ai/llms/supported_llms/index.html.md): ContextGem works with any cloud or local LLM that LiteLLM supports, e.g. from OpenAI, Anthropic, Google, Ollama or LM Studio, with or without reasoning.
- [Configuring LLM(s)](https://contextgem.shcherbak.ai/llms/llm_config/index.html.md): How to configure a DocumentLLM: the model and its credentials, fallback LLMs, retries, output token limits, sampling parameters, reasoning effort, model groups, and cost and usage tracking.
- [Extraction Methods](https://contextgem.shcherbak.ai/llms/llm_extraction_methods/index.html.md): The methods that extract aspects and concepts from a document or from its aspects with DocumentLLM, DocumentModelGroup and DocumentDecisionModel, and their parameters.
- [Chat with Tools](https://contextgem.shcherbak.ai/llms/chat_with_tools/index.html.md): How to give an LLM Python functions to call as tools in chat: registering them, how their schemas are built from type hints and docstrings, and how tool errors are handled.
- [Decision Models](https://contextgem.shcherbak.ai/decision_models/decision_models/index.html.md): How to extract aspects and Boolean, label and rating concepts with a decision model, which returns the probability of each answer instead of generating text, on its own or together with LLMs.
- [Advanced usage examples](https://contextgem.shcherbak.ai/advanced_usage/index.html.md): Complete examples of advanced ContextGem usage: aspects that contain concepts, extracting aspects and concepts together, and a pipeline that uses several LLMs over several documents.
- [Logging Configuration](https://contextgem.shcherbak.ai/logging_config/index.html.md): How to set the level and the output of the ContextGem logger with environment variables, change them at runtime, read the log format, and filter its Python warnings.
- [Choosing the Right LLM(s)](https://contextgem.shcherbak.ai/optimizations/optimization_choosing_llm/index.html.md): How to choose LLMs for your extraction, and how to send each aspect and concept to the model that suits it with model roles and concept modality.
- [Optimizing for Accuracy](https://contextgem.shcherbak.ai/optimizations/optimization_accuracy/index.html.md): How to improve extraction accuracy: a capable model, larger segmentation models, examples, justifications, fewer paragraphs, aspects and concepts per call, and a fallback model.
- [Optimizing for Speed](https://contextgem.shcherbak.ai/optimizations/optimization_speed/index.html.md): How to speed up extraction: concurrency, smaller models, decision models for closed questions, a fallback model, default parameters, and sparing use of justifications and sentence-level references.
- [Optimizing for Cost](https://contextgem.shcherbak.ai/optimizations/optimization_cost/index.html.md): How to lower the cost of extraction: cost-efficient models, decision models for closed questions, default parameters, sparing justifications, and usage and cost monitoring.
- [Dealing with Long Documents](https://contextgem.shcherbak.ai/optimizations/optimization_long_docs/index.html.md): How to extract from long documents: segmentation into paragraphs and sentences instead of chunks, long-context models, limits per call, and concurrency.
- [Troubleshooting Issues with Small Models](https://contextgem.shcherbak.ai/optimizations/optimization_small_llm_troubleshooting/index.html.md): Why small language models often fail at structured extraction with ContextGem, and how to mitigate, debug and test them.
- [Serializing objects and results](https://contextgem.shcherbak.ai/serialization/index.html.md): How to save and load documents, pipelines and models as dictionaries, JSON strings or JSON files, and what happens to the API credentials of models.
- [Migrating to v1.0](https://contextgem.shcherbak.ai/migration_v1/index.html.md): How to upgrade code and serialized data from earlier ContextGem versions to v1.0: renamed classes and parameters, model roles and concept modality, and other changes in behavior.
- [Documents](https://contextgem.shcherbak.ai/api/documents/index.html.md): API reference of Document, which holds the text, paragraphs and images of a document and the aspects and concepts to extract from it.
- [Aspects](https://contextgem.shcherbak.ai/api/aspects/index.html.md): API reference of Aspect, a section or topic of a document to extract, with its sub-aspects, concepts and extracted items.
- [Concepts](https://contextgem.shcherbak.ai/api/concepts/index.html.md): API reference of the concept classes: StringConcept, BooleanConcept, NumericalConcept, RatingConcept, JsonObjectConcept, DateConcept and LabelConcept.
- [Examples](https://contextgem.shcherbak.ai/api/examples/index.html.md): API reference of StringExample and JsonObjectExample, examples that guide the extraction of string and JSON object concepts.
- [LLMs](https://contextgem.shcherbak.ai/api/llms/index.html.md): API reference of DocumentLLM, which extracts aspects and concepts and chats with tools, and of ChatSession, which keeps the message history of a chat.
- [Decision models](https://contextgem.shcherbak.ai/api/decision_models/index.html.md): API reference of DocumentDecisionModel, which extracts aspects and Boolean, label and rating concepts with the probability of each answer.
- [Model groups](https://contextgem.shcherbak.ai/api/models/index.html.md): API reference of DocumentModelGroup, a group of LLMs and decision models with roles, each extracting the aspects and concepts of its role.
- [Data models](https://contextgem.shcherbak.ai/api/data_models/index.html.md): API reference of ModelPricing, the token prices of a model that its cost is calculated from.
- [Utility functions and classes](https://contextgem.shcherbak.ai/api/utils/index.html.md): API reference of the utility functions and classes: create_image, image_to_base64, reload_logger_settings and JsonObjectClassStruct.
- [Images](https://contextgem.shcherbak.ai/api/images/index.html.md): API reference of Image, an image that is attached to a document or makes up a document.
- [Paragraphs](https://contextgem.shcherbak.ai/api/paragraphs/index.html.md): API reference of Paragraph, a paragraph of a document with its text and sentences.
- [Sentences](https://contextgem.shcherbak.ai/api/sentences/index.html.md): API reference of Sentence, a sentence of a paragraph of a document.
- [Pipelines](https://contextgem.shcherbak.ai/api/pipelines/index.html.md): API reference of ExtractionPipeline, a reusable set of aspects and concepts to apply to documents.
- [Decorators](https://contextgem.shcherbak.ai/api/decorators/index.html.md): API reference of register_tool, the decorator that registers a Python function as a tool that an LLM can call in chat.
- [Exceptions and Warnings](https://contextgem.shcherbak.ai/api/exceptions/index.html.md): API reference of the exceptions that ContextGem raises (ModelAPIError, ModelExtractionError and LLMToolLoopLimitError, and their base class ContextGemError) and of ContextGemWarning, the category of its warnings.