ContextGem: declarative LLM extraction with sentence-level source references
ContextGem: Effortless LLM extraction from documents
At a glance
- What is it?
- ContextGem is an Apache-2.0 Python framework that turns a natural-language description of what to pull out of a document into prompts, a Pydantic-style data model and citation back to the source text. It is aimed at legal, contract and document-analysis pipelines where knowing where a value came from matters as much as the value itself.
- Who is it for?
- Adopt ContextGem if you are extracting structured fields from long documents and you need the output tied back to specific paragraphs or sentences, or if you are tired of maintaining hand-written extraction prompts and their validation models separately. Do not adopt it if you need a general-purpose agent framework, or if your extraction task is a single short prompt over a short string, where the abstraction cost is not repaid.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem ContextGem targets: extraction that has to be traceable
Getting a language model to return a JSON object is not the hard part. The hard part is everything around it. You write a prompt, then you write a model to validate what comes back, then you write code to map each field to the part of the document it came from, then you write a pipeline to run several of these steps in order, then you add token accounting. ContextGem's README describes this exact list as the motivation for the project, and the framework's answer is to let you describe what to extract in natural language and handle the how itself. The audience is narrow and identifiable: teams doing contract analysis, legal document review and general document intelligence, where a field without a source reference is not usable. The repository topics list contract-analysis, legaltech and document-intelligence alongside the generic llm and nlp tags, which matches the README's own quick-start example about extracting anomalies from a legal document. If your extraction target is a short string with no provenance requirement, this is a heavier tool than you need.
Aspects and concepts: the two abstractions the whole framework rests on
The README names two building blocks. Aspects are the topics, themes or categories you identify inside a document; concepts are the specific things you extract, described as entities, facts, conclusions or assessments. The relationship between them is the interesting part. Aspects can contain concepts, and aspects can contain other aspects, which the README calls hierarchical aspects and nested context extraction. So the model is a tree: you declare a top-level aspect, declare concepts that live inside it, and the framework generates the prompts and the data model for each level. The README states that extraction results carry paragraph- and sentence-level references and automatic justifications. That is the mechanism that distinguishes this from a plain structured-output wrapper. A concept is not just a value; it is a value plus a pointer into the source plus a stated reason. The README also mentions a unified, serializable document storage model, which implies intermediate document state can be persisted rather than held only in memory, though the README does not describe the serialization format. What the README does not explain is how the framework decides which part of a long document to send to the model for a given concept, or how it handles a document that exceeds a context window. Those are the questions I would want answered before running this on a 300-page contract.
Installation and the shape of a first pipeline
Installation is a single command. The README gives two forms: uv add contextgem with uv, which the project recommends, or pip install -U contextgem. The package supports Python 3.10 through 3.14 according to the version badge. The README's quick start is a legal-document example that extracts anomalies, which it describes as a complex concept requiring contextual understanding. The README text is truncated at that point, so the full code sample is not available in the supplied material and I will not reconstruct it. What can be said from the repository layout is that the project uses Pydantic v2 (the badge is present) and that the framework's own abstractions sit on top of it, so the extracted data model is likely a Pydantic model under the hood. The README does not list required environment variables or provider configuration keys in the portion available, so I cannot state which API keys you need or how the LLM is selected. That is a documentation gap worth checking on contextgem.dev before you plan an integration.
Where the abstraction leaks: cost, providers and long documents
The framework's selling point is that it handles prompt writing, validation modelling and pipeline orchestration. That is also where the risk sits. Every one of those generated steps is a model call, and the README mentions tracking usage across LLMs as one of the problems ContextGem solves, which confirms that usage tracking is in scope but says nothing about how many calls a given extraction produces. A hierarchical aspect tree with concepts at several levels implies at least one call per level, and possibly more where the framework needs a second pass to locate references or produce justifications. On a large document this multiplies quickly. The second limitation is provider coupling: the README's feature list talks about LLMs in the plural and about tracking usage across them, but the available material does not name a supported provider or describe how to swap one for another. If your organisation has a fixed provider or a self-hosted model, verify support before adopting. The third is that the framework is opinionated about structure. If your extraction does not decompose into aspects and concepts, you will be fighting the abstraction rather than using it. A flat set of twenty unrelated fields pulled from a short email is not a good fit.
ContextGem against a direct provider SDK call
The obvious alternative is not another framework. It is calling your LLM provider's SDK directly with a hand-written prompt and a schema. The difference in approach is concrete. With a direct call you control the exact prompt text, you decide how the document is chunked, and you know precisely how many requests you are making and what each one costs. With ContextGem you hand over prompt construction and validation modelling to the framework in exchange for less code and, per the README, automatic source references and justifications that you would otherwise have to build yourself. Neither is strictly better. A direct call is the right choice when the extraction is stable, the document is short and provenance does not matter, because then the framework's generated prompts are an extra layer you cannot easily inspect or tune. ContextGem earns its place when the extraction is complex enough that hand-maintaining prompts and their matching validation models has become the actual bottleneck, and when the sentence-level references are a product requirement rather than a nice-to-have. The README's own framing, that reliable extraction typically involves writing prompts, designing validation models, mapping outputs back to sources and orchestrating multi-step pipelines, is a fair description of the work you are choosing to delegate.
Licence, releases and what maintenance actually costs
ContextGem is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files intact. That covers the framework code. It does not cover the model provider you point it at, and it does not cover the documents you feed through it. If your documents are contracts or client material, the data protection question is between you and your provider, not something the Apache grant addresses. I am not giving legal advice here; read the licence text and your provider terms. On maintenance, the release cadence is visible in the supplied material: v0.25.1 in June 2026, v0.26.0 in late July 2026, v0.27.0 in mid August 2026. Three releases in roughly ten weeks, all in the 0.x range. A 0.x version number is a signal that the public API can still move between minor releases, so pinning a version in your dependency file is the sensible default rather than tracking main. The repository also carries CI, CodeQL, a licence-compatibility check and an OpenSSF Best Practices badge, which indicates the project runs automated checks on itself. None of that tells you whether a future release will rename the aspect or concept classes you depend on. The upgrade cost is therefore mostly the cost of reading release notes and re-running your extraction tests whenever you bump the pin.
Who should pick this up, and what to check first
The fit is a Python team with a document corpus and a provenance requirement. Legal tech, contract review, and any pipeline where a reviewer will ask where a number came from. The framework's aspect and concept model maps naturally onto that work, and the sentence-level references are the feature that would otherwise take weeks to build and keep correct. The misfit is a team that wants a general agent framework, or one whose extraction is a single flat prompt over a short input. ContextGem is a document extraction framework and the README does not present it as anything broader. Before writing production code, check the full quick-start example on contextgem.dev since the README copy in this material is truncated, confirm which LLM providers are supported and what credentials they require, and run one hierarchical extraction on a document at the upper end of your size range to see how the call count and latency behave. If the provider list does not include your model, the decision is made for you.
Editorial conclusion
Adopt ContextGem if you are extracting structured fields from long documents and you need the output tied back to specific paragraphs or sentences, or if you are tired of maintaining hand-written extraction prompts and their validation models separately. Do not adopt it if you need a general-purpose agent framework, or if your extraction task is a single short prompt over a short string, where the abstraction cost is not repaid. Before committing, verify three things against the current documentation: which LLM providers the framework supports and what credentials they need, how the aspect and concept nesting behaves on a document of your own size, and whether the serializable document storage model fits the way you persist intermediate results. The Apache-2.0 licence keeps the framework itself permissive, but your provider terms and the data you send to them sit outside that grant.
Community notes