# LangExtract - Deep Dive

> **TL;DR**: LangExtract is Google's open-source Python library that uses LLMs to extract structured data from unstructured text - with a critical difference: every extraction is mapped to its exact source location. No training, no hallucination mysteries, just "show me where you got that." 17.6k GitHub stars and counting.

---

## What Is LangExtract?

**LangExtract** is an LLM-powered information extraction library that:

1. **Extracts structured data** from unstructured text (documents, notes, reviews)
2. **Provides source grounding** - every extraction links to exact character positions
3. **Requires no training** - just give examples of what you want
4. **Works with multiple LLMs** - Gemini, OpenAI, Claude, or local models

### The Problem It Solves

Traditional extraction approaches have critical limitations:

| Approach | Problem |
|----------|---------|
| **Regex** | Can't understand context or relationships |
| **spaCy/NLTK** | Great for standard entities, but needs retraining for custom ones |
| **Generic LLM calls** | Hallucinations, inconsistent output, no source verification |
| **Custom ML models** | Requires extensive training data and expertise |

**LangExtract's insight**: What if you could just *show* an LLM a few examples and it would extract similar patterns - while telling you exactly where it found each piece of information?

---

## The Key Innovation: Source Grounding

This is what makes LangExtract special. Every extraction includes:

```python
Extraction(
    extraction_class="medication",      # What type of thing
    extraction_text="Metformin",        # The actual text
    start_offset=23,                    # Starts at character 23
    end_offset=32,                      # Ends at character 32
    attributes={"dosage": "500mg"}      # Additional structured data
)
```

**Why this matters**:

| Use Case | Why Source Grounding Helps |
|----------|---------------------------|
| **Healthcare** | Verify medication info came from the actual clinical note |
| **Legal** | Prove which clause a contract term came from |
| **Finance** | Audit trail for extracted financial data |
| **Research** | Cite exactly where information was found |
| **Debugging** | See why the model extracted what it did |

---

## How It Works

### The Three-Step Workflow

```
┌─────────────────────────────────────────────────────────────────────┐
│                    LANGEXTRACT PIPELINE                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   STEP 1: Define What You Want                                      │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │  Prompt: "Extract medications and dosages"                  │   │
│   │  Examples: Show 2-3 examples of the pattern                 │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                              ↓                                      │
│   STEP 2: LLM Extraction with Grounding                             │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │  Document → Chunks → Parallel LLM Processing                │   │
│   │  → Multi-pass extraction → Merge results                    │   │
│   │  → Calculate source offsets                                 │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                              ↓                                      │
│   STEP 3: Structured Output with Verification                       │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │  Extractions with exact character positions                 │   │
│   │  → Interactive HTML visualization                           │   │
│   │  → JSON export for downstream processing                    │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Basic Code Example

```python
import langextract as lx

# 1. Define what you want to extract
prompt = "Extract character names and their emotions from the text"

# 2. Provide a few examples
examples = [
    lx.data.ExampleData(
        text="ROMEO: But soft! What light through yonder window breaks?",
        extractions=[
            lx.data.Extraction(
                extraction_class="character",
                extraction_text="ROMEO"
            ),
            lx.data.Extraction(
                extraction_class="emotion",
                extraction_text="wonder"
            )
        ]
    )
]

# 3. Run extraction
result = lx.extract(
    text_or_documents=your_document,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash"
)

# 4. Results include source locations
for extraction in result.extractions:
    print(f"Found '{extraction.extraction_text}' at chars {extraction.start_offset}-{extraction.end_offset}")
```

---

## Key Features

### 1. Few-Shot Learning (No Training Required)

Instead of:
- Collecting training data
- Annotating thousands of examples
- Training and fine-tuning models
- Deploying and maintaining pipelines

You just:
- Write a description of what you want
- Provide 2-3 examples
- Run extraction

**Time to first extraction**: Minutes, not weeks.

### 2. Precise Source Grounding

Every extraction maps to exact character positions:

```
Original text: "Patient takes Metformin 500mg twice daily"
                          ▲         ▲
                     start=14   end=23

Extraction: "Metformin" at positions 14-23
```

This enables:
- **Verification**: Click through to see the source
- **Highlighting**: Visual display of where data came from
- **Auditing**: Complete traceability for compliance

### 3. Long Document Handling

LangExtract handles documents up to **millions of tokens** through:

| Technique | How It Helps |
|-----------|--------------|
| **Intelligent chunking** | Splits documents while preserving context |
| **Parallel processing** | Up to 10 workers processing chunks simultaneously |
| **Multi-pass extraction** | Multiple independent passes catch more entities |
| **Result merging** | Deduplicates and combines results from all passes |

**Benchmark**: 12% higher recall than single-pass approaches on million-token documents.

### 4. Multiple LLM Support

| Provider | Models | Notes |
|----------|--------|-------|
| **Google Gemini** | gemini-2.5-flash, gemini-2.5-pro | Recommended, supports schema constraints |
| **OpenAI** | gpt-4o, gpt-4-turbo | Good quality, no schema constraints |
| **Anthropic** | Claude models | Via community provider |
| **Ollama** | Gemma, Llama, Mistral | Local, no API key needed |
| **Custom** | Any provider | Plugin architecture |

### 5. Interactive Visualization

Generate HTML reports that:
- Highlight extracted entities in context
- Allow clicking through to source locations
- Handle thousands of entities efficiently
- Work in Jupyter, Colab, or as standalone files

```python
# Generate visualization
html = lx.visualize("results.jsonl")

# Display in Jupyter
from IPython.display import HTML
HTML(html)
```

### 6. Multi-Language Support

- **20+ languages** supported
- **Special CJK support** (Chinese, Japanese, Korean) in v1.1.1
- **99.9% accuracy** on standard datasets and code-mixed scenarios

---

## Real-World Use Cases

### 1. Healthcare: Clinical Notes

```python
prompt = """Extract medication information:
- Medication name
- Dosage
- Frequency
- Route of administration"""

examples = [
    lx.data.ExampleData(
        text="Start Metformin 500mg PO BID for diabetes",
        extractions=[
            lx.data.Extraction(
                extraction_class="medication",
                extraction_text="Metformin",
                attributes={
                    "dosage": "500mg",
                    "route": "PO",
                    "frequency": "BID"
                }
            )
        ]
    )
]
```

**Why source grounding matters**: Medical decisions require verified information. Knowing exactly where "Metformin" was mentioned in the clinical note is critical.

### 2. Customer Reviews

```python
prompt = """Extract from customer reviews:
- Product name and model
- Issue or complaint
- Sentiment (positive/negative)"""

# Process hundreds of reviews in parallel
results = lx.extract(
    text_or_documents=all_reviews,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash",
    max_workers=10
)
```

**Benefit**: Understand relationships - "MacBook Pro 2021" + "battery drain" stay connected, not just individual entities.

### 3. Legal Documents

```python
prompt = """Extract contract terms:
- Party names
- Obligations
- Dates and deadlines
- Penalty clauses"""
```

**Why source grounding matters**: Legal teams need to verify which clause contains each obligation.

### 4. Research Papers

```python
prompt = """Extract from scientific papers:
- Methods used
- Key findings
- Datasets mentioned
- Limitations acknowledged"""
```

**Benefit**: Build literature reviews with automatic citation of source locations.

---

## Installation & Setup

### Quick Start

```bash
# Install via pip
pip install langextract

# Set API key (for Gemini)
export LANGEXTRACT_API_KEY="your-gemini-api-key"
```

### Using Different Models

**Gemini (Recommended)**:
```python
result = lx.extract(
    text_or_documents=text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash"
)
```

**OpenAI**:
```python
result = lx.extract(
    text_or_documents=text,
    prompt_description=prompt,
    examples=examples,
    model_id="gpt-4o",
    api_key=os.environ.get('OPENAI_API_KEY'),
    fence_output=True,
    use_schema_constraints=False
)
```

**Local with Ollama** (no API key):
```bash
# First, run Ollama
ollama pull gemma2:2b
ollama serve
```

```python
result = lx.extract(
    text_or_documents=text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemma2:2b",
    model_url="http://localhost:11434",
    timeout=300
)
```

---

## LangExtract vs Alternatives

### vs spaCy

| Aspect | LangExtract | spaCy |
|--------|------------|-------|
| **Custom entities** | Just provide examples | Requires retraining |
| **Speed** | Slower (LLM inference) | Very fast |
| **Source grounding** | Precise character mapping | No |
| **Context understanding** | Excellent | Limited |
| **Best for** | Complex, domain-specific | Standard NER, high-speed |

### vs Generic LLM Calls

| Aspect | LangExtract | DIY LLM Extraction |
|--------|------------|-------------------|
| **Hallucinations** | Reduced through grounding | Common problem |
| **Source verification** | Built-in | Manual implementation |
| **Long documents** | Automatic chunking | Context limit issues |
| **Output format** | Guaranteed schema | Often inconsistent |

### vs LangChain/LlamaIndex

| Tool | Focus |
|------|-------|
| **LangExtract** | Structured extraction with source grounding |
| **LangChain** | Complex workflows and agent chains |
| **LlamaIndex** | Search and RAG applications |

LangExtract can be used *within* LangChain workflows as a specialized extraction component.

---

## Performance

### Benchmarks

| Metric | Result |
|--------|--------|
| **Long document recall** | 12% higher than single-pass |
| **Precision (Gemini-2.5-pro)** | >95% |
| **Language accuracy** | 99.9% on standard datasets |
| **Romeo & Juliet test** | 500+ entities from 147K chars in <3 min |

### Configuration for Performance

```python
result = lx.extract(
    text_or_documents=large_document,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-pro",    # More powerful model
    max_workers=10,                # Parallel processing
    num_passes=3                   # Multiple passes for recall
)
```

---

## How This Helps Us Achieve Our Goals

Looking at our "Software Development in the Age of AI" repository, LangExtract connects directly to our mission:

### 1. **Structured Data from Unstructured Sources**

| Development Task | LangExtract Application |
|-----------------|------------------------|
| Requirements analysis | Extract structured requirements from docs |
| Bug report parsing | Extract issue details, steps to reproduce |
| Code review analysis | Extract patterns from review comments |
| Documentation mining | Extract API signatures, parameters |

### 2. **Complements Our Other Deep Dives**

| Deep Dive | Connection |
|-----------|------------|
| **olmOCR** | olmOCR extracts text from PDFs → LangExtract structures it |
| **Data Formulator** | Both transform unstructured → structured data |
| **MCP Servers** | LangExtract could power an MCP for document extraction |
| **DeepAgents** | LangExtract as a tool within agent workflows |

### 3. **The Source Grounding Philosophy**

Our repo emphasizes **transparency** in AI-assisted development. LangExtract embodies this:
- No black-box extraction
- Every piece of data traceable to source
- Verification possible at any point

### 4. **Practical Tool for Our Community**

When working with:
- Technical specifications
- Customer feedback
- Log files
- Documentation

LangExtract provides reliable extraction with proof of where information came from.

---

## Quick Reference

### Installation

```bash
pip install langextract
export LANGEXTRACT_API_KEY="your-key"
```

### Basic Usage

```python
import langextract as lx

result = lx.extract(
    text_or_documents=text,
    prompt_description="Extract X, Y, Z",
    examples=[...],
    model_id="gemini-2.5-flash"
)

for e in result.extractions:
    print(f"{e.extraction_class}: {e.extraction_text} [{e.start_offset}:{e.end_offset}]")
```

### Key Parameters

| Parameter | Purpose |
|-----------|---------|
| `model_id` | Which LLM to use |
| `max_workers` | Parallel processing (default: 10) |
| `num_passes` | Extraction passes for recall |
| `timeout` | Seconds to wait for response |
| `fence_output` | Wrap output in code fences |

---

## Key Links

| Resource | URL |
|----------|-----|
| GitHub Repository | https://github.com/google/langextract |
| Official Website | https://langextract.com/ |
| PyPI Package | https://pypi.org/project/langextract/ |
| Google Developers Blog | https://developers.googleblog.com/en/introducing-langextract-a-gemini-powered-information-extraction-library/ |
| Health AI Docs | https://developers.google.com/health-ai-developer-foundations/libraries/langextract |
| DataCamp Tutorial | https://www.datacamp.com/tutorial/langextract |

---

## Quick Stats

| Metric | Value |
|--------|-------|
| Creator | Google (open-source, community maintained) |
| First Release | August 2024 |
| GitHub Stars | 17,600+ |
| GitHub Forks | 1,200+ |
| License | Apache 2.0 |
| Current Version | 1.1.1 |
| Supported Languages | 20+ (including CJK) |
| LLM Backends | Gemini, OpenAI, Anthropic, Ollama, custom |

---

## Bottom Line

LangExtract solves a fundamental problem in AI-powered text processing:

> "The LLM extracted this information - but can you prove where it came from?"

**Yes.** Every extraction includes exact character positions in the source.

**Why this matters**:
- Healthcare can't use extracted medication data without verification
- Legal can't cite contract terms without knowing which clause
- Research can't claim findings without traceable sources
- Developers can't debug extraction without seeing the source

**Key differentiator**: While other tools focus on *what* was extracted, LangExtract focuses on *where* it came from.

For our repository focused on AI-assisted development, LangExtract represents a mature approach to the extraction problem - one where transparency and verifiability are built into the core architecture, not bolted on as an afterthought.

---

*Document created: January 2026*
*Sources: [GitHub - google/langextract](https://github.com/google/langextract), [Google Developers Blog](https://developers.googleblog.com/en/introducing-langextract-a-gemini-powered-information-extraction-library/), [langextract.com](https://langextract.com/), [DataCamp Tutorial](https://www.datacamp.com/tutorial/langextract)*
