### Development Installation of ContextGem

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/installation.md

Installs ContextGem from its source repository for development purposes. This involves cloning the Git repository, installing the uv tool if needed, and synchronizing all development dependencies.

```bash
git clone https://github.com/shcherbak-ai/contextgem.git
cd contextgem

# Install uv if you don't have it
pip install uv

# Install dependencies including development extras
uv sync --all-groups
```

--------------------------------

### Chat with Tools using ContextGem and Python

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/quickstart.md

This Python code illustrates how to enable LLM chat interactions with custom tools. It defines a tool handler, registers it, defines the tool's schema for the LLM, and configures a DocumentLLM to use these tools. The example shows sending a prompt that requires the tool to be invoked and processing the tool's response.

```python
import os

from contextgem import ChatSession, DocumentLLM, register_tool


# Define tool handlers and register them
@register_tool
def compute_invoice_total(items: list[dict]) -> str:
    total = 0
    for it in items:
        qty = float(it.get("qty", 0))
        price = float(it.get("price", 0))
        total += qty * price
    return str(total)


# OpenAI-compatible tool schema passed to the model
tools = [
    {
        "type": "function",
        "function": {
            "name": "compute_invoice_total",
            "description": "Compute invoice total as sum(qty*price) over items",
            "parameters": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "qty": {"type": "number"},
                                "price": {"type": "number"},
                            },
                            "required": ["qty", "price"],
                        },
                        "minItems": 1,
                    }
                },
                "required": ["items"],
            },
        },
    },
]


# Configure an LLM that supports tool use
llm = DocumentLLM(
    model="azure/gpt-4.1-mini",
    api_key=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_KEY"),
    api_version=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_VERSION"),
    api_base=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_BASE"),
    system_message="You are a helpful assistant.",  # override default system message for chat
    tools=tools,
)

# Maintain history across turns
session = ChatSession()

prompt = (
    "What's the invoice total for the items "
    "[{'qty':2.0,'price':3.5},{'qty':1.0,'price':3.0}]? "
    "Prices are in USD."
)

answer = llm.chat(prompt, chat_session=session)
print("Answer:", answer)
```

--------------------------------

### Lightweight LLM Chat Interface with ContextGem

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/quickstart.md

This Python code demonstrates initializing a DocumentLLM for chat, configuring an optional fallback LLM for enhanced reliability, and managing conversation history using ChatSession. It shows how to send single-turn chats and multi-turn conversations with text and optionally images.

```python
import os

from contextgem import DocumentLLM
from contextgem.public import ChatSession


# Initialize main LLM for chat
main_model = DocumentLLM(
    model="openai/gpt-4o",  # or another provider/model
    api_key=os.getenv("CONTEXTGEM_OPENAI_API_KEY"),  # your API key for the LLM provider
    system_message="",  # disable default system message for chat, or provide your own
)

# Optional: configure fallback LLM for reliability
fallback_model = DocumentLLM(
    model="openai/gpt-4o-mini",  # or another provider/model
    api_key=os.getenv("CONTEXTGEM_OPENAI_API_KEY"),  # your API key for the LLM provider
    is_fallback=True,
    system_message="",  # also disable default system message for fallback, or provide your own
)
main_model.fallback_llm = fallback_model


# Preserve conversation history across turns with a ChatSession
session = ChatSession()
first_response = main_model.chat(
    "Hi there!",
    # images=[Image(...)]  # optional: add images for vision models
    chat_session=session,
)
second_response = main_model.chat(
    "And what is EBITDA?",
    chat_session=session,
)
# or use async: `response = await main_model.chat_async(...)`

# Or send a chat message without a session (one-off message → response)
one_off_response = main_model.chat("Test")
```

--------------------------------

### Create and Use JsonObjectExample in Python

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/api/examples.md

Demonstrates how to create an instance of JsonObjectExample with sample JSON data and attach it to a JsonObjectConcept. This showcases how examples can guide LLM extraction by defining expected structures and content.

```python
from contextgem import JsonObjectConcept, JsonObjectExample

# Create a JSON object example
json_example = JsonObjectExample(
    content={
        "name": "John Doe",
        "education": "Bachelor's degree in Computer Science",
        "skills": ["Python", "Machine Learning", "Data Analysis"],
        "hobbies": ["Reading", "Traveling", "Gaming"],
    }
)

# Define a structure for JSON object concept
class PersonInfo:
    name: str
    education: str
    skills: list[str]
    hobbies: list[str]

# Attach JSON example to a JsonObjectConcept
json_concept = JsonObjectConcept(
    name="Candidate info",
    description="Structured information about a job candidate",
    structure=PersonInfo,  # Define the expected structure
    examples=[json_example],  # Attach the example to the concept (optional)
)
```

--------------------------------

### Basic LLM Setup and Extraction with ContextGem

Source: https://context7.com/shcherbak-ai/contextgem/llms.txt

This example demonstrates the basic setup and usage of DocumentLLM for extracting information from a document. It includes configuring the LLM model, setting parameters like temperature and max tokens, adding concepts to the document, performing extraction, and accessing the results along with cost and token usage.

```python
import os
from contextgem import Document, DocumentLLM, StringConcept

# Configure LLM
llm = DocumentLLM(
    model="openai/gpt-4o-mini",  # Format: provider/model-name
    api_key=os.environ.get("OPENAI_API_KEY"),
    temperature=0.3,  # Control randomness (0.0-1.0)
    max_tokens=4096,  # Max response tokens
    timeout=120,  # API timeout in seconds
    num_retries_failed_request=3,  # Retry on failure
    auto_pricing=True,  # Automatic cost calculation
    seed=42  # For more consistent outputs
)

# Prepare document
document = Document(raw_text="Your document text here...")
document.add_concepts([
    StringConcept(name="Key Findings", description="Main conclusions")
])

# Extract information
document = llm.extract_all(document)

# Access results
for item in document.concepts[0].extracted_items:
    print(item.value)

# Check costs and usage
print(f"Total cost: ${llm.total_cost}")
print(f"Total tokens: {llm.total_tokens}")
```

--------------------------------

### Access Extracted Information from Document Aspects and Concepts (Python)

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/quickstart.md

Demonstrates how to retrieve extracted items for specific aspects and concepts within a document object. This is useful for accessing pre-processed or analyzed information.

```python
print("Compensation aspect:")
print(
    doc.get_aspect_by_name("Compensation").extracted_items
)  # extracted aspect items with references to sentences
print("Annual Salary concept:")
print(
    doc.get_aspect_by_name("Compensation")
    .get_concept_by_name("Annual Salary")
    .extracted_items
)  # extracted concept items with references to sentences
```

--------------------------------

### Verify ContextGem Installation

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/installation.md

Checks if the ContextGem library has been installed correctly by importing it and printing its version. This command uses a short Python script executed directly from the command line.

```python
python -c "import contextgem; print(contextgem.__version__)"
```

--------------------------------

### Extract Concepts from Document Text (Python)

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/quickstart.md

Shows how to extract structured data (concepts) from the raw text of a document using a DocumentLLM. This involves defining a concept with its desired structure and then using the LLM to populate it from the document. Dependencies include the contextgem library and an LLM API key.

```python
# Quick Start Example - Extracting a concept from a document

import os

from contextgem import Document, DocumentLLM, JsonObjectConcept


# Example document instance
# Document content is shortened for brevity
doc = Document(
    raw_text=(
        "Statement of Work\n"
        "Project: Cloud Migration Initiative\n"
        "Client: Acme Corporation\n"
        "Contractor: TechSolutions Inc.\n\n"
        "Project Timeline:\n"
        "Start Date: March 1, 2025\n"
        "End Date: August 31, 2025\n\n"
        "Deliverables:\n"
        "1. Infrastructure assessment report (Due: March 15, 2025)\n"
        "2. Migration strategy document (Due: April 10, 2025)\n"
        "3. Test environment setup (Due: May 20, 2025)\n"
        "4. Production migration (Due: July 15, 2025)\n"
        "5. Post-migration support (Due: August 31, 2025)\n\n"
        "Budget: $250,000\n"
        "Payment Schedule: 20% upfront, 30% at midpoint, 50% upon completion\n"
    ),
)

# Define a document-level concept using e.g. JsonObjectConcept
# This will extract structured data from the entire document
doc_concept = JsonObjectConcept(
    name="Project Details",
    description="Key project information including timeline, deliverables, and budget",
    structure={
        "project_name": str,
        "client": str,
        "contractor": str,
        "budget": str,
        "payment_terms": str,
    },  # simply use a dictionary with type hints (including generic aliases and union types)
    add_references=True,
    reference_depth="paragraphs",
)

# Add the concept to the document
doc.add_concepts([doc_concept])
# (add more concepts to the document, if needed)

# Create an LLM for extraction
llm = DocumentLLM(
    model="openai/gpt-4o-mini",  # or any other LLM from e.g. Anthropic, etc.
    api_key=os.environ.get("CONTEXTGEM_OPENAI_API_KEY"),  # your API key
)

# Extract information from the document
extracted_concepts = llm.extract_concepts_from_document(doc)
# or use async version llm.extract_concepts_from_document_async(doc)

# Access extracted information
print("Project Details:")
print(
    extracted_concepts[0].extracted_items
)  # extracted concept items with references to paragraphs
# Or doc.get_concept_by_name("Project Details").extracted_items
```

--------------------------------

### Install ContextGem using uv

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/installation.md

Adds the ContextGem library to your project using the uv package installer, known for its speed. This command is an alternative to pip for managing Python packages.

```bash
uv add contextgem
```

--------------------------------

### Quick Start: Extract Anomalies with ContextGem

Source: https://github.com/shcherbak-ai/contextgem/blob/main/dev/readme.template.md

Demonstrates a quick start example using ContextGem to extract anomalies from a legal document. This Python code snippet showcases the library's ability to perform context-aware extraction, identifying subtle inconsistencies with source references and justifications.

```python
from contextgem import Document, Aspect, BooleanConcept, DocumentLLM

# Create a document instance
document = Document(raw_text="This is a sample legal document outlining terms and conditions, including a clause about intellectual property.")

# Define an aspect to extract specific sections
term_aspect = Aspect(
    name="Intellectual Property",
    description="Clauses related to intellectual property rights."
)

# Define a concept to check if the document is an NDA
is_nda_concept = BooleanConcept(
    name="Is NDA",
    description="Determines if the document is a Non-Disclosure Agreement."
)

# Add the aspect and concept to the document
document.add_aspects([term_aspect])
document.add_concepts([is_nda_concept])

# Initialize the LLM for extraction
llm = DocumentLLM(
    model="openai/gpt-5-mini",  # Replace with your desired model
    api_key="YOUR_API_KEY",      # Replace with your actual API key
)

# Run the extraction process
document = llm.extract_all(document)

# Access the extracted information (example)
# print("Intellectual Property Clauses:", document.aspects[0].extracted_items)
# print("Is NDA:", document.concepts[0].extracted_items)

```

--------------------------------

### Create and Use String Examples in Python

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/api/examples.md

Demonstrates how to create StringExample instances and attach them to a StringConcept for LLM extraction guidance. This requires the contextgem library.

```python
from contextgem import StringConcept, StringExample

# Create string examples
string_examples = [
    StringExample(content="X (Client)"),
    StringExample(content="Y (Supplier)"),
]

# Attach string examples to a StringConcept
string_concept = StringConcept(
    name="Contract party name and role",
    description="The name and role of the contract party",
    examples=string_examples,  # Attach the example to the concept (optional)
)
```

--------------------------------

### Extracting Specific Concepts from Aspects with ContextGem

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/quickstart.md

This Python snippet demonstrates how to extract a specific concept, such as 'Annual Salary', from a document using ContextGem. It defines an Aspect named 'Compensation' and within it, a StringConcept for 'Annual Salary', specifying its description and example format. An LLM then extracts instances of this concept from the document text.

```python
# Quick Start Example - Extracting a concept from an aspect

import os

from contextgem import Aspect, Document, DocumentLLM, StringConcept, StringExample


# Example document instance
# Document content is shortened for brevity
doc = Document(
    raw_text=(
        "Employment Agreement\n"
        "This agreement between TechCorp Inc. (Employer) and Jane Smith (Employee)...\n"
        "The employment shall commence on January 15, 2023 and continue until terminated...\n"
        "The Employee shall work as a Senior Software Engineer reporting to the CTO...\n"
        "The Employee shall receive an annual salary of $120,000 paid monthly...\n"
        "The Employee is entitled to 20 days of paid vacation per year...\n"
        "The Employee agrees to a notice period of 30 days for resignation...\n"
        "This agreement is governed by the laws of California...\n"
    ),
)

# Define an aspect with a specific concept, using natural language
doc_aspect = Aspect(
    name="Compensation",
    description="Clauses defining the compensation and benefits for the employee",
    reference_depth="sentences",
)

# Define a concept within the aspect
aspect_concept = StringConcept(
    name="Annual Salary",
    description="The annual base salary amount specified in the employment agreement",
    examples=[
        StringExample(
            content="$X per year",
        )
    ],
    add_references=True,
    reference_depth="sentences",
)

# Add the concept to the aspect
doc_aspect.add_concepts([aspect_concept])

# Add the aspect to the document
doc.add_aspects([doc_aspect])

# Create an LLM for extraction
llm = DocumentLLM(
    model="openai/gpt-4o-mini",
    api_key=os.environ.get("CONTEXTGEM_OPENAI_API_KEY"),
)

# Extract information from the document
doc = llm.extract_all(doc)

```

--------------------------------

### Extract Concepts from Document Vision (Images) (Python)

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/quickstart.md

Illustrates how to extract numerical data from an image within a document using a vision-capable LLM. This is particularly useful for processing documents like invoices. It requires the contextgem library, an image file, and an LLM API key for a vision model.

```python
# Quick Start Example - Extracting concept from a document with an image

import os
from pathlib import Path

from contextgem import Document, DocumentLLM, NumericalConcept, create_image


# Path adapted for testing
current_file = Path(__file__).resolve()
root_path = current_file.parents[4]
image_path = root_path / "tests" / "images" / "invoices" / "invoice.jpg"

# Create an image instance using the create_image utility
doc_image = create_image(image_path)

# Example document instance holding only the image
doc = Document(
    images=[doc_image],  # may contain multiple images
)

# Define a concept to extract the invoice total amount
doc_concept = NumericalConcept(
    name="Invoice Total",
    description="The total amount to be paid as shown on the invoice",
    numeric_type="float",
    llm_role="extractor_vision",  # use vision model
)

# Add concept to the document
doc.add_concepts([doc_concept])
# (add more concepts to the document, if needed)

# Create an LLM for extraction
llm = DocumentLLM(
    model="openai/gpt-4o-mini",  # Using a model with vision capabilities
    api_key=os.environ.get("CONTEXTGEM_OPENAI_API_KEY"),  # your API key
    role="extractor_vision",  # mark LLM as vision model
)

# Extract information from the document
extracted_concepts = llm.extract_concepts_from_document(doc)
# or use async version: await llm.extract_concepts_from_document_async(doc)

# Access extracted information
print("Invoice Total:")
print(extracted_concepts[0].extracted_items)  # extracted concept items

```

--------------------------------

### Extracting Termination Information with ContextGem LLM

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/quickstart.md

This snippet shows how to use ContextGem's DocumentLLM to extract structured information about employment agreement terminations. It defines aspects and sub-aspects related to termination rights and severance, then uses an LLM to populate these aspects from raw contract text. The extracted information can be accessed programmatically.

```python
import os

from contextgem import Aspect, Document, DocumentLLM

contract_text = """
EMPLOYMENT AGREEMENT
...
8. TERMINATION
8.1 Termination by the Company. The Company may terminate the Employee's employment for Cause at any time upon written notice. 
"Cause" shall mean: (i) Employee's material breach of this Agreement; (ii) Employee's conviction of a felony; or 
(iii) Employee's willful misconduct that causes material harm to the Company.
8.2 Termination by the Employee. The Employee may terminate employment for Good Reason upon 30 days' written notice to the Company. 
"Good Reason" shall mean a material reduction in Employee's base salary or a material diminution in Employee's duties.
8.3 Severance. If the Employee's employment is terminated by the Company without Cause or by the Employee for Good Reason, 
the Employee shall be entitled to receive severance pay equal to six (6) months of the Employee's base salary.
...
""".strip()

doc = Document(raw_text=contract_text)

# Define termination aspect with practical sub-aspects
termination_aspect = Aspect(
    name="Termination",
    description="Provisions related to the termination of employment",
    aspects=[
        Aspect(
            name="Company Termination Rights",
            description="Conditions under which the company can terminate employment",
        ),
        Aspect(
            name="Employee Termination Rights",
            description="Conditions under which the employee can terminate employment",
        ),
        Aspect(
            name="Severance Terms",
            description="Compensation or benefits provided upon termination",
        ),
    ],
)

# Add the aspect to the document. Sub-aspects are added with the parent aspect.
doc.add_aspects([termination_aspect])

# Create an LLM for extraction
llm = DocumentLLM(
    model="openai/gpt-4o-mini",
    api_key=os.environ.get(
        "CONTEXTGEM_OPENAI_API_KEY"
    ),
)

# Extract all information from the document
doc = llm.extract_all(doc)

# Get results with references in the document object
print("\nTermination aspect:\n")
termination_aspect = doc.get_aspect_by_name("Termination")
for sub_aspect in termination_aspect.aspects:
    print(sub_aspect.name)
    for item in sub_aspect.extracted_items:
        print(item.value)
    print("\n")

```

--------------------------------

### OpenAI Client Setup with Instructor Integration (Python)

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/vs_other_frameworks.md

Provides functions to initialize OpenAI clients, both synchronous and asynchronous, with the instructor library integrated. This setup is crucial for enabling Pydantic model parsing directly from LLM responses.

```python
import os
from openai import OpenAI
from openai import AsyncOpenAI
import instructor

def get_client(api_key=None):
    """Get an OpenAI client with instructor integrated"""
    api_key = api_key or os.environ.get("CONTEXTGEM_OPENAI_API_KEY", "")
    client = OpenAI(api_key=api_key)
    return instructor.from_openai(client)


async def get_async_client(api_key=None):
    """Get an AsyncOpenAI client with instructor integrated"""
    api_key = api_key or os.environ.get("CONTEXTGEM_OPENAI_API_KEY", "")
    client = AsyncOpenAI(api_key=api_key)
    return instructor.from_openai(client)

```

--------------------------------

### Install Dependencies and Development Extras with uv

Source: https://github.com/shcherbak-ai/contextgem/blob/main/CONTRIBUTING.md

This command uses the 'uv' package installer to synchronize project dependencies and install development-specific extras. Ensure 'uv' is installed before running this command.

```bash
# Install uv if you don't have it
pip install uv

# Install dependencies and development extras
uv sync --all-groups
```

--------------------------------

### Install ContextGem Package

Source: https://github.com/shcherbak-ai/contextgem/blob/main/dev/readme.template.md

Installs the ContextGem Python package using pip. This is the primary method for setting up the library in your Python environment.

```bash
pip install -U contextgem
```

--------------------------------

### ContextGem: Basic Concept Extraction Example

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/llms/llm_extraction_methods.md

This snippet demonstrates a basic setup for extracting concepts from documents using ContextGem. It imports necessary classes like `Document`, `DocumentLLM`, `NumericalConcept`, and `StringConcept`. This code serves as a starting point for users to integrate ContextGem into their projects for automated concept extraction.

```python
from contextgem import Document, DocumentLLM, NumericalConcept, StringConcept

```

--------------------------------

### Basic Document Initialization in ContextGem (Python)

Source: https://github.com/shcherbak-ai/contextgem/blob/main/README.md

A minimal example showing how to create a `Document` object with raw text, which is the first step in using ContextGem for information extraction.

```python
document = Document(raw_text="Non-Disclosure Agreement...")
```

--------------------------------

### DocumentLLM Initialization and Configuration

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/api/llms.md

Demonstrates how to create and configure DocumentLLM instances for specific roles like text extraction, including setting up fallback LLMs and optional pricing details.

```APIDOC
## DocumentLLM Initialization

### Description
Initializes a DocumentLLM instance with specified model, API key, role, and optional pricing details. Supports fallback LLM configuration.

### Method
`DocumentLLM(...)`

### Parameters
- **model** (str) - Required - The identifier for the LLM model to use.
- **api_key** (str) - Required - The API key for authenticating with the LLM provider.
- **role** (str) - Optional - The role assigned to this LLM instance (defaults to 'extractor_text').
- **pricing_details** (LLMPricing) - Optional - An object containing pricing information per million tokens.
- **auto_pricing** (bool) - Optional - If true, attempts to automatically fetch pricing data.
- **is_fallback** (bool) - Optional - If true, this LLM instance is designated as a fallback.
- **fallback_llm** (DocumentLLM) - Optional - Assigns a fallback LLM instance to this primary LLM.

### Request Example
```python
from contextgem import DocumentLLM, LLMPricing

text_extractor = DocumentLLM(
    model="openai/gpt-4o-mini",
    api_key="your-api-key",
    role="extractor_text",
    pricing_details=LLMPricing(
        input_per_1m_tokens=0.150,
        output_per_1m_tokens=0.600
    )
)

fallback_text_extractor = DocumentLLM(
    model="anthropic/claude-3-7-sonnet",
    api_key="your-anthropic-api-key",
    role="extractor_text",
    is_fallback=True
)

text_extractor.fallback_llm = fallback_text_extractor
```

### Response
(Initialization does not return a response, but configures the object)

```

--------------------------------

### Instantiate DocumentLLMGroup with LLMs and Output Language

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/api/llms.md

Demonstrates how to create a DocumentLLMGroup by initializing individual DocumentLLMs with specific roles, including fallback LLMs, and then assembling them into a group with a defined output language.

```python
from contextgem import DocumentLLM, DocumentLLMGroup

# Create a text extractor LLM with a fallback
text_extractor = DocumentLLM(
    model="openai/gpt-4o-mini",
    api_key="your-openai-api-key",  # Replace with your actual API key
    role="extractor_text",
)

# Create a fallback LLM for the text extractor
text_extractor_fallback = DocumentLLM(
    model="anthropic/claude-3-5-haiku",
    api_key="your-anthropic-api-key",  # Replace with your actual API key
    role="extractor_text",  # Must have the same role as the primary LLM
    is_fallback=True,
)

# Assign the fallback LLM to the primary text extractor
text_extractor.fallback_llm = text_extractor_fallback

# Create a text reasoner LLM
text_reasoner = DocumentLLM(
    model="openai/o3-mini",
    api_key="your-openai-api-key",  # Replace with your actual API key
    role="reasoner_text",  # For more complex tasks that require reasoning
)

# Create a vision extractor LLM
vision_extractor = DocumentLLM(
    model="openai/gpt-4o-mini",
    api_key="your-openai-api-key",  # Replace with your actual API key
    role="extractor_vision",  # For handling images
)

# Create a vision reasoner LLM
vision_reasoner = DocumentLLM(
    model="openai/gpt-5-mini",
    api_key="your-openai-api-key",
    role="reasoner_vision",  # For more complex vision tasks that require reasoning
)

# Create a DocumentLLMGroup with all four LLMs
llm_group = DocumentLLMGroup(
    llms=[text_extractor, text_reasoner, vision_extractor, vision_reasoner],
    output_language="en",  # All LLMs must have the same output language ("en" is default)
)
```

--------------------------------

### ContextGem: Extracting Aspects from Documents

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/llms/llm_extraction_methods.md

This Python code snippet demonstrates how to use the ContextGem library to extract aspects from a given text. It initializes a `DocumentLLM` and a `Document` object, then proceeds to extract aspects. This example requires the `contextgem` library to be installed.

```python
from contextgem import Aspect, Document, DocumentLLM


# Sample text content
text_content = """
TechCorp is a leading software development company founded in 2015 with headquarters in San Francisco.
The company specializes in cloud-based solutions and has grown to 500 employees across 12 countries.
Their flagship product, CloudManager Pro, serves over 10,000 enterprise clients worldwide.
TechCorp reported $50 million in revenue for 2023, representing a 25% growth from the previous year.
The company is known for its innovative AI-powered analytics platform and excellent customer support.
They recently expanded into the European market and plan to launch three new products in 2024.
"""

# Initialize DocumentLLM (replace with your actual LLM setup if needed)
# For demonstration, we assume a basic setup. Actual implementation might require API keys or specific model configurations.
doc_llm = DocumentLLM()

# Create a Document object from the text content
document = Document(text_content, llm=doc_llm)

# Example: Define an aspect to extract (replace with your actual aspect definitions)
# This is a placeholder; actual aspects would be defined based on the project's needs.
class CompanyInfoAspect(Aspect):
    def __init__(self):
        super().__init__(
            name="company_info",
            description="Extracts key information about the company.",
            extraction_params=["name", "founding_year", "headquarters", "employees", "revenue"]
        )

# Add the aspect to the document
company_aspect = CompanyInfoAspect()
document.add_aspect(company_aspect)

# Process the document to extract aspects
document.extract_aspects()

# Access the extracted information (example)
print(f"Extracted Aspect: {company_aspect.name}")
for item in company_aspect.extracted_items:
    print(f"  - {item}")

# The full return value description is provided in the text, detailing populated fields like extracted_items and reference_paragraphs.
```

--------------------------------

### Initialize Documents for Multi-LLM Pipeline

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/advanced_usage.md

Demonstrates the initial step of creating Document objects, such as 'doc1', which contain raw text. This is part of setting up multiple documents for processing within a single pipeline, potentially with different LLMs.

```python
# Construct documents

# Document 1 - Consultancy Agreement (shortened for brevity)
doc1 = Document(
    raw_text=(
        "Consultancy Agreement\n"
        "This agreement between Company A (Supplier) and Company B (Customer)...\n"
        "The term of the agreement is 1 year from the Effective Date...\n"
        "The Supplier shall provide consultancy services as described in Annex 2...\n"
        "The Customer shall pay the Supplier within 30 calendar days of receiving an invoice...\n"
        "All intellectual property created during the provision of services shall belong to the Customer...\n"
        "This agreement is governed by the laws of Norway...\n"
        "Annex 1: Data processing agreement...\n"
        "Annex 2: Statement of Work...\n"
        "Annex 3: Service Level Agreement...\n"
    ),
)

```

--------------------------------

### Build Documentation Live with Sphinx-Autobuild

Source: https://github.com/shcherbak-ai/contextgem/blob/main/CONTRIBUTING.md

Builds the documentation and starts a local development server with live reloading. This is recommended for active development as it automatically rebuilds and refreshes the browser on file changes. It serves documentation on http://localhost:9000 with pretty URLs.

```bash
# Live rebuild with auto-refresh on file changes
make livehtml
# Or on Windows: ./make.bat livehtml
```

--------------------------------

### Create LLM Group for Extraction and Reasoning in Python

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/advanced_usage.md

This snippet demonstrates how to initialize two DocumentLLM instances, one configured for text extraction and another for reasoning, and then combine them into a DocumentLLMGroup. It includes optional pricing details for cost tracking. This setup is essential for orchestrating complex document analysis tasks.

```python
import os
from contextgem.llm import DocumentLLM, LLMPricing, DocumentLLMGroup

# LLM for data extractionllm_extractor = DocumentLLM(
    model="openai/gpt-4o-mini",  # or any other LLM from e.g. Anthropic, etc.
    api_key=os.environ["CONTEXTGEM_OPENAI_API_KEY"],  # your API key
    role="extractor_text",  # signifies the LLM is used for data extraction tasks
    pricing_details=LLMPricing(
        input_per_1m_tokens=0.150,
        output_per_1m_tokens=0.600,
    ),
    # or set `auto_pricing=True` to automatically fetch pricing data from the LLM provider
)

# LLM for reasoning tasksllm_reasoner = DocumentLLM(
    model="openai/o3-mini",  # or any other LLM from e.g. Anthropic, etc.
    api_key=os.environ["CONTEXTGEM_OPENAI_API_KEY"],  # your API key
    role="reasoner_text",  # signifies the LLM is used for reasoning tasks
    pricing_details=LLMPricing(
        input_per_1m_tokens=1.10,
        output_per_1m_tokens=4.40,
    ),
    # or set `auto_pricing=True` to automatically fetch pricing data from the LLM provider
)

# Combine LLMs into a group for the pipelinellm_group = DocumentLLMGroup(llms=[llm_extractor, llm_reasoner])
```

--------------------------------

### Define and Extract Medical Assessment with JsonObjectConcept (Python)

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/concepts/json_object_concept.md

This Python code defines a Document object with a raw medical report, creates a JsonObjectConcept to structure the extraction of medical assessment data, and uses DocumentLLM to extract this structured data. Examples are provided to guide the LLM in mapping text to the JSON structure.

```python
from pprint import pprint
import os

from contextgem import Document, JsonObjectConcept, JsonObjectExample, DocumentLLM

medical_report = """
PATIENT ASSESSMENT
Date: March 15, 2023
Patient: John Doe (ID: 12345)

Vital Signs:
BP: 125/82 mmHg
HR: 72 bpm
Temp: 98.6°F
SpO2: 98%

Chief Complaint:
Patient presents with persistent cough for 2 weeks, mild fever in evenings (up to 100.4°F), and fatigue. 
No shortness of breath. Patient reports recent travel to Southeast Asia 3 weeks ago.

Assessment:
Physical examination shows slight wheezing in upper right lung. No signs of pneumonia on chest X-ray.
WBC slightly elevated at 11,500. Patient appears in stable condition but fatigued.

Impression:
1. Acute bronchitis, likely viral
2. Rule out early TB given travel history
3. Fatigue, likely secondary to infection

Plan:
- Rest for 5 days
- Symptomatic treatment with over-the-counter cough suppressant
- Follow-up in 1 week
- TB test ordered

Dr. Sarah Johnson, MD
"""
doc = Document(raw_text=medical_report)

medical_assessment_concept = JsonObjectConcept(
    name="Medical Assessment",
    description="Key information from a patient medical assessment",
    structure={
        "patient": {
            "id": str,
            "vital_signs": {
                "blood_pressure": str,
                "heart_rate": int,
                "temperature": float,
                "oxygen_saturation": int,
            },
        },
        "clinical": {
            "symptoms": list[str],
            "diagnosis": list[str],
            "travel_history": bool,
        },
        "treatment": {"recommendations": list[str], "follow_up_days": int},
    },
    examples=[
        JsonObjectExample(
            content={
                "patient": {
                    "id": "87654",
                    "vital_signs": {
                        "blood_pressure": "130/85",
                        "heart_rate": 68,
                        "temperature": 98.2,
                        "oxygen_saturation": 99,
                    },
                },
                "clinical": {
                    "symptoms": ["headache", "dizziness", "nausea"],
                    "diagnosis": ["Migraine", "Dehydration"],
                    "travel_history": False,
                },
                "treatment": {
                    "recommendations": [
                        "Hydration",
                        "Pain medication",
                        "Dark room rest",
                    ],
                    "follow_up_days": 14,
                },
            }
        ),
        JsonObjectExample(
            content={
                "patient": {
                    "id": "23456",
                    "vital_signs": {
                        "blood_pressure": "145/92",
                        "heart_rate": 88,
                        "temperature": 100.8,
                        "oxygen_saturation": 96,
                    },
                },
                "clinical": {
                    "symptoms": ["sore throat", "cough", "fever"],
                    "diagnosis": ["Strep throat", "Pharyngitis"],
                    "travel_history": True,
                },
                "treatment": {
                    "recommendations": ["Antibiotics", "Throat lozenges", "Rest"],
                    "follow_up_days": 7,
                },
            }
        ),
    ],
)

doc.add_concepts([medical_assessment_concept])

llm = DocumentLLM(
    model="azure/gpt-4.1",
    api_key=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_KEY"),
    api_version=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_VERSION"),
    api_base=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_BASE"),
)

medical_assessment_concept = llm.extract_concepts_from_document(doc)[0]

print("Extracted medical assessment:")
assessment = medical_assessment_concept.extracted_items[0].value
pprint(assessment)
```

--------------------------------

### Document Creation with Predefined Paragraphs

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/api/documents.md

Illustrates creating a Document instance by providing a list of pre-defined Paragraph objects.

```APIDOC
## POST /document/create/from_paragraphs

### Description
Creates a new document instance from a list of predefined Paragraph objects.

### Method
POST

### Endpoint
/document/create/from_paragraphs

### Parameters
#### Request Body
- **paragraphs** (list[Paragraph]) - Required - A list of Paragraph objects, each containing raw text.

### Request Example
```json
{
  "paragraphs": [
    {
      "raw_text": "This is the first paragraph."
    },
    {
      "raw_text": "This is the second paragraph with more content."
    },
    {
      "raw_text": "Final paragraph concluding the document."
    }
  ]
}
```

### Response
#### Success Response (200)
- **document_id** (str) - The unique identifier for the created document.

#### Response Example
```json
{
  "document_id": "doc_67890"
}
```
```

--------------------------------

### Extract Invoice Total from Document with Image using Python

Source: https://github.com/shcherbak-ai/contextgem/blob/main/dev/notebooks/docs/quickstart/quickstart_concept_document_vision.ipynb

This Python example demonstrates extracting a numerical concept ('Invoice Total') from a document containing an image. It utilizes the `contextgem` library, requiring an LLM with vision capabilities (e.g., 'openai/gpt-4o-mini') and an OpenAI API key. The output is the extracted numerical item representing the invoice total.

```python
# Quick Start Example - Extracting concept from a document with an image

import os
from pathlib import Path

from contextgem import Document, DocumentLLM, NumericalConcept, create_image


# Path adapted for testing
current_file = Path(__file__).resolve()
root_path = current_file.parents[4]
image_path = root_path / "tests" / "images" / "invoices" / "invoice.jpg"

# Create an image instance using the create_image utility
doc_image = create_image(image_path)

# Example document instance holding only the image
doc = Document(
    images=[doc_image],  # may contain multiple images
)

# Define a concept to extract the invoice total amount
doc_concept = NumericalConcept(
    name="Invoice Total",
    description="The total amount to be paid as shown on the invoice",
    numeric_type="float",
    llm_role="extractor_vision",  # use vision model
)

# Add concept to the document
doc.add_concepts([doc_concept])
# (add more concepts to the document, if needed)

# Create an LLM for extraction
llm = DocumentLLM(
    model="openai/gpt-4o-mini",  # Using a model with vision capabilities
    api_key=os.environ.get("CONTEXTGEM_OPENAI_API_KEY"),  # your API key
    role="extractor_vision",  # mark LLM as vision model
)

# Extract information from the document
extracted_concepts = llm.extract_concepts_from_document(doc)
# or use async version: await llm.extract_concepts_from_document_async(doc)

# Access extracted information
print("Invoice Total:")
print(extracted_concepts[0].extracted_items)  # extracted concept items
# or doc.get_concept_by_name("Invoice Total").extracted_items

```

--------------------------------

### Document Processing Pipeline Setup and Execution

Source: https://github.com/shcherbak-ai/contextgem/blob/main/docs/source/vs_other_frameworks.md

Python code demonstrating the setup and execution of a document processing pipeline using LlamaIndex. It includes initializing a CostTracker, creating a pipeline with default components, and processing two documents concurrently, measuring execution time.

```python
# Create cost tracker
cost_tracker = CostTracker()

# Create pipeline with default configuration - returns both pipeline and components
pipeline, pipeline_components = create_document_pipeline()

# Process documents
print("Processing document 1 with concurrency...")
start_time = time.time()
doc1_results = process_document(
    doc1_text, (pipeline, pipeline_components), cost_tracker, use_concurrency=True
)
print(f"Processing time: {time.time() - start_time:.2f} seconds")

print("Processing document 2 with concurrency...")
start_time = time.time()
doc2_results = process_document(
    doc2_text, (pipeline, pipeline_components), cost_tracker, use_concurrency=True
)
print(f"Processing time: {time.time() - start_time:.2f} seconds")

# Print results
print_document_results("Document 1 (Consultancy Agreement)", doc1_results)
print_document_results("Document 2 (Service Level Agreement)", doc2_results)
```

--------------------------------

### Install ContextGem Library

Source: https://github.com/shcherbak-ai/contextgem/blob/main/dev/notebooks/docs/aspects/aspect_with_sub_aspects.ipynb

Installs the ContextGem library using pip. This is the first step before using any of its functionalities. Ensure you have pip installed and an active internet connection.

```python
%pip install -U contextgem

```