shcherbak-ai/contextgem

ContextGem – Structured extraction from documents with LLMs and decision models

What it is – An open‑source Python library that lets you pull structured facts out of any text (or image‑containing) document. You describe what you want (aspects and concepts) in plain language, and ContextGem builds the prompts, calls the appropriate model, validates the typed output, and returns each fact together with the exact paragraph or sentence it came from and, optionally, a justification.

Why it matters – Traditional LLM pipelines require you to hand‑craft prompts, write validation code, and manually map answers back to their source. ContextGem bundles all that into a declarative pipeline you can reuse and serialize. It also supports decision models – fast, low‑cost classifiers that answer closed‑question types (yes/no, label, rating) and return probabilities, letting you mix reasoning‑heavy LLM calls with cheap, high‑throughput models.

Key features

• No prompt writing – Write a description of the aspect or concept; ContextGem generates the prompt.
• Typed, validated output – Supports strings, numbers, dates, booleans, labels, ratings, and JSON objects.
• Source tracing – Every extracted item includes the paragraph/sentence it was taken from and, on request, a brief justification.
• Nested context – Define aspects (large sections) and sub‑aspects, then attach concepts that focus on those sections.
• Model routing – Send open‑ended extraction to an LLM (via LiteLLM) and closed‑question extraction to a decision model (e.g., TypeSafe Jev, OpenAI Decisions API).
• Probability answers – Decision models return a probability distribution for each possible answer, letting you set thresholds.
• Batch processing – Reads every paragraph of a document (no retrieval step), optionally in user‑defined batch sizes.

How it works (high‑level)

1. Wrap your content in a Document object (plain text, images, or both).
2. Declare what to extract:
   • Aspects pull out whole paragraphs/sentences matching a topic.
   • Concepts extract typed values (strings, numbers, booleans, labels, etc.) from the whole document or from a specific aspect.
3. Run a model:
   • DocumentLLM for LLM‑based extraction.
   • DocumentDecisionModel for decision‑model extraction.
   • Or a model group that routes each aspect/concept to the appropriate model.
4. Get results – The returned Document contains extracted_items with values, source references, justifications, and (for decision models) probability scores.

Quick example (LLM)

from contextgem import Document, Aspect, StringConcept, DocumentLLM

doc = Document(raw_text="...contract text...")

doc.add_aspects([Aspect(name="Payment terms", description="Clauses on payments")])

doc.add_concepts([
    StringConcept(
        name="Anomalies",
        description="Anomalous statements",
        add_references=True,
        reference_depth="sentences",
        add_justifications=True,
        justification_depth="brief",
    )
])

llm = DocumentLLM(model="openai/gpt-6-luna", api_key="…")
result = llm.extract_all(doc)
print(result.get_aspect_by_name("Payment terms").extracted_items)
print(result.get_concept_by_name("Anomalies").extracted_items)

The aspect returns the exact payment‑clause paragraph; the concept returns each anomaly with its source sentence and a short justification.

Quick example (decision model)

from contextgem import Document, Aspect, BooleanConcept, LabelConcept, DocumentDecisionModel

doc = Document(raw_text="...service agreement...")

doc.add_aspects([Aspect(name="Termination", description="Clauses on termination")])

doc.add_concepts([
    BooleanConcept(name="Termination for convenience", description="Can it be ended without cause?"),
    LabelConcept(
        name="Notice form",
        description="Form of termination notice",
        labels=["Written", "Email", "Any form", "Not specified"],
        classification_type="multi_class",
    ),
])

model = DocumentDecisionModel(model="typesafe/jev-latest", api_key="…")
result = model.extract_all(doc)
print(result.get_aspect_by_name("Termination").extracted_items)
print(result.get_concept_by_name("Termination for convenience").extracted_items)
print(result.get_concept_by_name("Notice form").extracted_items)

Each paragraph gets a yes/no probability for the aspect, and concepts return probabilities for the chosen label.

Installation – pip install -U contextgem (or uv add contextgem).

Documentation & resources – Full docs at https://contextgem.shcherbak.ai, quick‑start guide, migration guide for v1.0, and extensive testing (unit, property‑based, and evaluation against reference extractions).

---

ContextGem is a genuine AI‑focused project that combines LLMs and specialized decision models to automate reliable, traceable data extraction from documents.