### Initialize Semlib Session in Python

Source: https://github.com/anishathalye/semlib/blob/master/docs/quickstart.ipynb

Initializes a Semlib session for interacting with LLM functionalities. This is the first step before using any other Semlib features. It requires the 'semlib' library to be installed.

```python
from semlib import Bare, Session

session = Session()
```

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

### Prompt LLM for Structured Output with Semlib

Source: https://github.com/anishathalye/semlib/blob/master/docs/quickstart.ipynb

Uses the session.prompt method to query an LLM and retrieve structured data. It supports specifying the expected return type for parsing LLM responses. Requires an active Semlib session.

```python
presidents: list[str] = await session.prompt(
    "Who were the 39th through 42nd presidents of the United States? Return the name only.",
    return_type=Bare(list[str])
)
presidents
```

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

### Manage Semlib Sessions

Source: https://context7.com/anishathalye/semlib/llms.txt

Demonstrates how to initialize a Session with custom configurations such as model selection, concurrency limits, and caching strategies. Includes examples for checking costs and clearing caches.

```python
import asyncio
from semlib import Session, InMemoryCache, OnDiskCache, Bare

async def main():
    # Basic session with defaults (uses OPENAI_API_KEY and gpt-4o)
    session = Session()

    # Session with custom model and concurrency
    session = Session(
        model="anthropic/claude-sonnet-4-20250514",
        max_concurrency=5
    )

    # Session with in-memory cache
    session = Session(cache=InMemoryCache())

    # Session with persistent on-disk cache
    session = Session(cache=OnDiskCache("cache.db"))

    # Use the session
    result = await session.prompt("What is the capital of France?")
    print(result)  # "The capital of France is Paris."

    # Check total API cost
    print(f"Total cost: ${session.total_cost():.4f}")

    # Clear cache if needed
    session.clear_cache()

asyncio.run(main())
```

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

### Install Dependencies with Pip

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Installs the necessary Python libraries, semlib and arxiv, using pip. This is a prerequisite for running the recommendation pipeline.

```python
%pip install semlib arxiv
```

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

### Install Python Packages

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Installs the 'semlib' and 'marker-pdf' Python packages. 'semlib' is used for semantic operations, and 'marker-pdf' is a dependency for converting PDF files to Markdown.

```python
%pip install semlib marker-pdf
```

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

### Install Semlib via pip

Source: https://github.com/anishathalye/semlib/blob/master/README.md

The standard command to install the Semlib package from the Python Package Index.

```bash
pip install semlib
```

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

### Install Semlib library

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/airline-support/index.ipynb

Installs the Semlib package via pip to enable LLM-based data processing operations.

```python
%pip install semlib
```

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

### Transform List Items with Semlib Map

Source: https://github.com/anishathalye/semlib/blob/master/docs/quickstart.ipynb

Transforms each item in a list based on a prompt template using the session.map method. It can specify the return type for the transformed items. Requires an active Semlib session and a list of items.

```python
ages: list[int] = await session.map(
    presidents,
    template="How old was {} when he took office?",
    return_type=Bare(int)
)
ages
```

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

### Pull Ollama Models

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Downloads the 'gpt-oss:20b' and 'qwen3:8b' models from Ollama. These models are required for the information extraction and structuring steps. Ensure Ollama is installed and running before executing these commands.

```bash
!ollama pull gpt-oss:20b
!ollama pull qwen3:8b
```

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

### Sort List Items by Criterion with Semlib

Source: https://github.com/anishathalye/semlib/blob/master/docs/quickstart.ipynb

Sorts a list of items based on a specified ranking criterion using the session.sort method. Allows for reverse sorting to get the highest ranked items first. Requires an active Semlib session and a list of items.

```python
await session.sort(presidents, by="right-leaning", reverse=True)  # highest first
```

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

### Get Total LLM Cost with Semlib

Source: https://github.com/anishathalye/semlib/blob/master/docs/quickstart.ipynb

Retrieves the total cost of all LLM calls made within the current session using the session.total_cost method. This is useful for monitoring API usage expenses. Requires an active Semlib session.

```python
f"${session.total_cost():.3f}"
```

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

### Display Top 10 Criticisms with Details (Python)

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

This Python code iterates through the top 10 criticisms, formats citation strings, and prints the criticism count, summary, sample citations, and a detailed review example. It requires pre-defined lists for citations, reviews, and feedback counts.

```python
for feedback, i in by_count[:10]:
    sorted_citations = sorted(citations[i + 1])
    cite_str = f"{', '.join([str(c) for c in sorted_citations][:3])}, ..."
    print(f"({len(citations[i + 1])}) {feedback} [{cite_str}]\n")
    some_cite = sorted_citations[min(i * 10, len(sorted_citations) - 1)]  # get some variety
    print(f"    Review {some_cite}: {reviews[some_cite]['Review_Text']}\n\n")
```

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

### Initialize Semlib Session

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/airline-support/index.ipynb

Configures a Semlib session with an on-disk cache and specifies the LLM provider. This setup allows for persistent storage of LLM responses and model selection.

```python
from semlib import OnDiskCache, Session

session = Session(cache=OnDiskCache("cache.db"), model="openai/gpt-4o-mini")
```

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

### Filter List Items by Criterion with Semlib

Source: https://github.com/anishathalye/semlib/blob/master/docs/quickstart.ipynb

Filters a list of items based on a given criterion using the session.filter method. Supports negating the filter condition. Requires an active Semlib session and a list of items.

```python
await session.filter(presidents, by="former actor", negate=True)
```

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

### Perform Semantic Data Operations with Semlib

Source: https://github.com/anishathalye/semlib/blob/master/docs/index.md

Demonstrates how to use Semlib's functional primitives to process data using natural language instructions. The examples show prompting for a list, sorting by a semantic criteria, finding an item, and mapping over a list to extract specific information.

```python
presidents = await prompt(
    "Who were the 39th through 42nd presidents of the United States?",
    return_type=Bare(list[str])
)

await sort(presidents, by="right-leaning", reverse=True)  # highest first
# ['Ronald Reagan', 'George H. W. Bush', 'Bill Clinton', 'Jimmy Carter']

await find(presidents, by="former actor")
# 'Ronald Reagan'

await map(
    presidents,
    "How old was {} when he took office?",
    return_type=Bare(int),
)
# [52, 69, 64, 46]
```

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

### Display Filtered Paper Count and Examples

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Calculates and prints the number of irrelevant papers filtered out and displays the titles of the first five such papers to verify the filter's effectiveness. This helps in assessing the quality of the filtering process.

```python
print(f"Filtered out {len(papers) - len(relevant)} irrelevant papers, including:")

for paper in list({i.title for i in papers} - {i.title for i in relevant})[:5]:
    print(f"- {paper}")
```

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

### Download and Preview arXiv Papers

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Fetches a batch of arXiv papers using the `get_papers` function with specified categories and date range. It then prints the total number of papers found and displays the title and a truncated abstract of the first paper as an example. This demonstrates how to use the data fetching function and inspect the results.

```python
papers = get_papers(["cs.AI", "cs.LG"], date(2025, 8, 29), date(2025, 9, 4))

print(f"Number of papers: {len(papers)}\n")
print(f"Example title: {papers[0].title}\n")
print(f"Example abstract: {papers[0].summary[:400].replace('\n', ' ')}...")
```

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

### Configuring via environment variables

Source: https://context7.com/anishathalye/semlib/llms.txt

The library supports configuration through standard environment variables, allowing users to define default models, concurrency limits, and API keys for various providers.

```python
import os

# Set default model
os.environ["SEMLIB_DEFAULT_MODEL"] = "anthropic/claude-sonnet-4-20250514"

# Set max concurrency for API requests
os.environ["SEMLIB_MAX_CONCURRENCY"] = "5"

# API keys for different providers
os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."
```

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

### Download and Unzip Resume Dataset

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Downloads the resume dataset from Kaggle and unzips it. This command fetches the raw resume files, which are in PDF format, for further processing.

```bash
!curl -s -L -o resume-dataset.zip https://www.kaggle.com/api/v1/datasets/download/snehaanbhawal/resume-dataset
!unzip -q -o resume-dataset.zip
```

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

### Convert education text to structured data

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Maps previously extracted education text into the EducationInfo Pydantic model using a smaller, structured-output compatible LLM.

```python
educations = await session.map(
    education_texts,
    """
Given the following description of an individual's education, extract the university, graduation year, degree, and area of study.

{}
""".strip(),
    return_type=EducationInfo,
    model="ollama_chat/qwen3:8b",
)

educations[0]
```

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

### Execute LLM Prompts with Structured Outputs

Source: https://context7.com/anishathalye/semlib/llms.txt

Shows how to retrieve LLM responses as raw strings, Pydantic models, or specific types using the Bare marker. Covers both session-based calls and standalone utility functions.

```python
import asyncio
from pydantic import BaseModel
from semlib import Session, Bare
from semlib.prompt import prompt, prompt_sync

class Person(BaseModel):
    name: str
    age: int

async def main():
    session = Session()

    # Get raw string response
    response = await session.prompt("What is the capital of France?")
    print(response)  # "The capital of France is Paris."

    # Get structured Pydantic model response
    person = await session.prompt("Who is Barack Obama?", return_type=Person)
    print(person)  # Person(name='Barack Obama', age=62)

    # Get bare value (int, list, etc.)
    answer = await session.prompt("What is 2+2?", return_type=Bare(int))
    print(answer)  # 4

    # Get list of values
    primes = await session.prompt(
        "List the first 5 prime numbers",
        return_type=Bare(list[int])
    )
    print(primes)  # [2, 3, 5, 7, 11]

    # Override model for specific call
    result = await session.prompt(
        "Explain quantum computing",
        model="openai/gpt-4o-mini"
    )

    # Standalone async function (creates temporary session)
    result = await prompt("What is 2+2?", return_type=Bare(int))

    # Synchronous version
    result = prompt_sync("What is 2+2?", return_type=Bare(int))

asyncio.run(main())
```

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

### Apply language model prompts to items with semlib

Source: https://context7.com/anishathalye/semlib/llms.txt

Shows how to apply a prompt template to single items or collections. Supports string templates, callable templates, and structured output parsing via Pydantic models.

```python
import asyncio
from pydantic import BaseModel
from semlib import Session, Bare
from semlib.apply import apply, apply_sync

class Summary(BaseModel):
    title: str
    key_points: list[str]

async def main():
    session = Session()

    # Basic apply with bare return type
    total = await session.apply(
        [1, 2, 3, 4, 5],
        template="What is the sum of these numbers: {}?",
        return_type=Bare(int)
    )
    print(total)  # 15

    # Apply with string template
    description = await session.apply(
        "Python",
        template="Describe {} in one sentence."
    )
    print(description)

    # Apply with callable template
    result = await session.apply(
        {"language": "Python", "year": 1991},
        template=lambda d: f"When was {d['language']} created? It was created in {d['year']}. Is this correct?",
        return_type=Bare(bool)
    )
    print(result)  # True

    # Apply with Pydantic model return type
    summary = await session.apply(
        "Machine learning is a subset of artificial intelligence...",
        template="Summarize this text: {}",
        return_type=Summary
    )
    print(summary)

    # Standalone async function
    result = await apply([1, 2, 3], "Sum: {}", return_type=Bare(int))

    # Synchronous version
    result = apply_sync([1, 2, 3], "Sum: {}", return_type=Bare(int))

asyncio.run(main())
```

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

### Initialize Semlib Session with Cache

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Initializes a Semlib Session, which provides a context for Semlib operations. It configures the session to cache Large Language Model (LLM) responses on disk using OnDiskCache, improving performance for repeated runs. It also shows how to set the OpenAI API key if it's not already in the environment.

```python
import semlib
from semlib import OnDiskCache, Session

session = Session(cache=OnDiskCache("cache.db"))

# Uncomment the following lines and set your OpenAI API key if not already set in your environment

# import os
# os.environ["OPENAI_API_KEY"] = "..."
```

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

### Reduce iterables with language models using semlib

Source: https://context7.com/anishathalye/semlib/llms.txt

Demonstrates how to aggregate an iterable into a single value using LLM-based logic. Supports basic reduction, initial values, associative tree-based reduction for concurrency, and custom node handling with Box.

```python
import asyncio
from semlib import Session, Bare, Box
from semlib.reduce import reduce, reduce_sync

async def main():
    session = Session()

    # Basic reduce - sum word numbers
    total = await session.reduce(
        ["one", "three", "seven", "twelve"],
        "{} + {} = ?",
        return_type=Bare(int)
    )
    print(total)  # 23

    # Reduce with initial value
    primes = await session.reduce(
        range(20),
        template=lambda acc, n: f"If {n} is prime, append it to this list: {acc}.",
        initial=[],
        return_type=Bare(list[int]),
        model="openai/o4-mini"
    )
    print(primes)  # [2, 3, 5, 7, 11, 13, 17, 19]

    # Associative reduce (tree-based, concurrent, O(log n) depth)
    primes = await session.reduce(
        [[i] for i in range(20)],
        template=lambda acc, n: f"Compute the union of these two sets, then remove non-primes: {acc} and {n}",
        return_type=Bare(list[int]),
        associative=True
    )
    print(primes)  # [2, 3, 5, 7, 11, 13, 17, 19]

    # Using Box to distinguish leaf nodes from internal nodes
    reviews = [
        "The instructions are confusing.",
        "It's so loud!",
        "Great microwave, heats food evenly.",
        "The turntable is too small.",
    ]

    def template(a, b):
        if isinstance(a, Box) and isinstance(b, Box):
            return f'''
            Consider these two product reviews and return actionable improvements:
            - Review 1: {a.value}
            - Review 2: {b.value}'''
        if not isinstance(a, Box) and not isinstance(b, Box):
            return f'''
            Combine these two lists of improvements, de-duplicating:
            # List 1: {a}
            # List 2: {b}'''
        ideas = b if isinstance(a, Box) else a
        review = a.value if isinstance(a, Box) else b.value
        return f'''
        Update these improvements based on the review:
        # Ideas: {ideas}
        # Review: {review}'''

    result = await session.reduce(
        [Box(r) for r in reviews],
        template=template,
        associative=True
    )
    print(result)

    # Standalone async function
    result = await reduce(["a", "b", "c"], "{} + {}")

    # Synchronous version
    result = reduce_sync(["a", "b", "c"], "{} + {}")

asyncio.run(main())
```

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

### Download and extract dataset

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

Downloads the Disneyland reviews dataset from Kaggle and extracts the contents using shell commands.

```bash
!curl -s -L -o disneyland-reviews.zip https://www.kaggle.com/api/v1/datasets/download/arushchillar/disneyland-reviews
!unzip -q -o disneyland-reviews.zip
```

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

### Convert PDFs to Markdown

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Converts a subset of PDF resumes to Markdown format using the Marker library. It initializes a PdfConverter and processes the first 10 files in the 'data/data/ENGINEERING' directory, storing the Markdown content in the 'texts' list. This step may require downloading ML models for Marker.

```python
import os

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict

converter = PdfConverter(
    artifact_dict=create_model_dict(),
)

directory = "data/data/ENGINEERING"
files = sorted(os.listdir(directory))[:10]
texts = []
for file in files:
    rendered = converter(os.path.join(directory, file))
    texts.append(rendered.markdown)
```

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

### Preview Resume Markdown

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Prints the first 1000 characters of the first processed resume's Markdown content. This allows for a quick inspection of the conversion quality and potential parsing errors.

```python
print(f"{texts[0][:1000]}...")
```

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

### Define Formatting Instructions

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

This constant defines a set of instructions for formatting output, emphasizing succinctness and single-idea bullet points. It is used in various text generation tasks.

```python
FORMATTING_INSTRUCTIONS = """Ensure that each bullet point is as succinct as possible, representing a single logical idea. Write separate criticisms as separate bullet points. Combine any similar criticism into the same bullet point. Output your answer as a single-level bulleted list with no other formatting."""
```

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

### Compare items using language models

Source: https://context7.com/anishathalye/semlib/llms.txt

Demonstrates how to compare two items using the Session object or standalone functions. It supports custom criteria, task definitions, and template customization, returning an Order enum indicating the relative relationship.

```python
import asyncio
from semlib import Session
from semlib.compare import compare, compare_sync, Task, Order

async def main():
    session = Session()

    # Basic comparison (returns Order enum)
    result = await session.compare("twelve", "seventy two")
    print(result)  # Order.LESS (twelve < seventy two)

    # Comparison with criteria
    result = await session.compare(
        "California condor",
        "Bald eagle",
        by="wingspan"
    )
    print(result)  # Order.GREATER (condor has larger wingspan)

    # Custom template with task specification
    result = await session.compare(
        "proton",
        "electron",
        template="Which is smaller, (A) {} or (B) {}?",
        task=Task.CHOOSE_LESSER
    )
    print(result)  # Order.GREATER (electron is smaller, so proton > electron)

    # Standalone async function
    result = await compare("gold", "silver", by="value")

    # Synchronous version
    result = compare_sync("gold", "silver", by="value")

asyncio.run(main())
```

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

### Parse and Format Criticism Items using Semlib

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

Uses Semlib's session.apply and Bare annotation to convert a raw string into a list of strings via an LLM. The resulting list is then formatted into a numbered string for display purposes.

```python
criticism_items = await session.apply(
    merged_criticism, "Turn this list into a JSON array of strings.\n\n{}", return_type=Bare(list[str])
)

numbered_criticism = "\n".join(f"{i + 1:d}. {item}" for i, item in enumerate(criticism_items))
print(numbered_criticism)
```

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

### Initialize Semlib Session

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

Configures a Semlib session with disk caching, a specific LLM model, and high concurrency settings to handle large-scale API requests.

```python
from semlib import Bare, Box, OnDiskCache, Session

session = Session(cache=OnDiskCache("cache.db"), model="openai/gpt-4o-mini", max_concurrency=100)
```

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

### Execute Session Reduce with Associative Operator (Python)

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

This code snippet demonstrates how to initiate a `session.reduce()` call with a list of criticisms wrapped in `Box` objects. It specifies the `merge_template` function and sets `associative=True` for efficient reduction.

```python
merged_criticism = await session.reduce(map(Box, criticism), template=merge_template, associative=True)
```

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

### Display First 5 Research Papers in Python

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

This Python code snippet iterates through the first 5 sorted research results and prints each formatted paper using the `format_paper` function. It's useful for displaying top or initial findings.

```python
for i, p in enumerate(sorted_results[:5]):
    print(f"{i + 1}. {format_paper(p)}\n\n")

```

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

### Initialize Semlib Session

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Initializes a Semlib Session with an on-disk cache and configures the default model to 'ollama_chat/gpt-oss:20b'. This session object is used for subsequent Semlib operations, and the cache helps store LLM responses to speed up repeated computations.

```python
from semlib import OnDiskCache, Session

session = Session(cache=OnDiskCache("cache.db"), model="ollama_chat/gpt-oss:20b")
```

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

### Define LLM Comparison Prompt Template

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Defines a template string used by the LLM to perform pairwise comparisons between two research papers based on provided user interests.

```python
COMPARISON_TEMPLATE = """
You are a research assistant. Help me pick a research paper to read, based on what is most relevant to my interests and what is most likely to be high-quality work based on the title, authors, and abstract.

You will be given context on my interests, and two paper abstracts.

My research interests include:

- Machine learning and artificial intelligence
- Systems
- Security
- Formal methods

Here is paper Option A:

<option A>
{}
</option A>

Here is paper Option B:

<option B>
{}
</option B>

Choose the option (either A or B) that is more relevant to my interests and likely to be a high-quality work.
""".strip()
```

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

### Download and Preview Dataset

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/airline-support/index.ipynb

Fetches a JSON dataset of airline support tickets from a remote URL and prints a summary of the data. This validates the data structure before processing.

```python
import json
import urllib

tickets = json.loads(
    urllib.request.urlopen(
        "https://gist.githubusercontent.com/anishathalye/9d13b58d7ea820b11bcbe8c7b5704649/raw/7f0ae3f64f1107553a2f1f425473899104b3d4f8/airline_support_chats_kaggle.json"
    ).read()
)

print(f"Total number of tickets: {len(tickets)}")
print()
print(f"Example ticket text: {tickets[0]['text'][:400]}...")
```

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

### Compute citations using LLM mapping

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

Defines a prompt template to identify substantiated criticism within reviews and executes the mapping process using Semlib's session.map. It returns structured data as a list of integers representing the indices of substantiated criticism.

```python
def citation_template(review: dict[str, str]) -> str:
    return f"""
Which of the following pieces of criticism, if any, about Disneyland California is substantiated by the following review?

<criticism>
{numbered_criticism}
</criticism>

<review>
{review["Review_Text"]}
</review>

Respond with a list of the numbers of the pieces of criticism that are substantiated by the review.
""".strip()

per_review_citations = await session.map(reviews, citation_template, return_type=Bare(list[int]))
```

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

### Calculate Session Cost

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Retrieves and formats the total cost incurred by the Semlib session operations.

```python
f"${session.total_cost():.2f}"
```

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

### Generate Complaint Report using Semlib apply

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/airline-support/index.ipynb

Utilizes Semlib's `apply` method to process a list of extracted complaints. It prompts an LLM to analyze all complaints together, summarize common issues, and highlight differences across frustration levels, generating a consolidated report.

```python
report = await session.apply(
    enumerate(complaints),
    lambda c: f"""
Here are some complaints found in the dataset:

{"

".join(map(format_complaint, c))}

Summarize the common complaints across all tickets, and highlight how they differ across frustration levels.
""".strip(),
)
```

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

### Perform LLM-powered data operations using Semlib

Source: https://github.com/anishathalye/semlib/blob/master/README.md

Demonstrates using Semlib's functional primitives such as prompt, sort, find, and map to process data via natural language instructions. These functions handle the underlying LLM interactions and return structured data types.

```python
>>> presidents = await prompt(
...     "Who were the 39th through 42nd presidents of the United States?",
...     return_type=Bare(list[str])
... )

>>> await sort(presidents, by="right-leaning", reverse=True)
['Ronald Reagan', 'George H. W. Bush', 'Bill Clinton', 'Jimmy Carter']

>>> await find(presidents, by="former actor")
'Ronald Reagan'

>>> await map(
...     presidents,
...     "How old was {} when he took office?",
...     return_type=Bare(int),
... )
[52, 69, 64, 46]
```

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

### Filter resumes by degree type

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Processes the structured education list to align with original files and filters for candidates holding a Master's degree.

```python
all_educations: list[EducationInfo | None] = []
i = 0
for text in all_education_texts:
    if text != "(none)":
        all_educations.append(educations[i])
        i += 1
    else:
        all_educations.append(None)

masters = []
for file, edu in zip(files, all_educations, strict=False):
    if edu is not None and edu.degree == "Master":
        masters.append((file, edu))

print(f"Found {len(masters)} resumes with a Master's degree:\n")
for file, edu in masters:
    print(f"- {os.path.join(directory, file)}: {edu.university}, {edu.graduation_year}, {edu.area}")
```

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

### Define structured education schema

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Defines a Pydantic model to enforce structured output for educational data. It uses typing.Literal to restrict degree values to a specific set of options.

```python
from typing import Literal
import pydantic

class EducationInfo(pydantic.BaseModel):
    university: str | None
    graduation_year: int | None
    degree: Literal["Associate", "Bachelor", "Master", "Doctorate"] | None
    area: str | None
```

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

### Merge Templates for Criticism Summarization (Python)

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

The `merge_template` function merges different types of criticism data (raw or summarized) into a cohesive summary. It handles cases where inputs are both raw criticism, both summaries, or a mix of both, using the provided `FORMATTING_INSTRUCTIONS`.

```python
def merge_template(a: str | Box[str], b: str | Box[str]) -> str:
    if isinstance(a, Box) and isinstance(b, Box):
        # both are leaf nodes in the reduction tree (raw criticism)
        return f"""
Consider the following two lists of criticisms about Disneyland California, and return a bulleted list summarizing the criticism from the two lists.

<criticism 1>
{a.value}
</criticism 1>

<criticism 2>
{b.value}
</criticism 2>

{FORMATTING_INSTRUCTIONS}
""".strip()
    if not isinstance(a, Box) and not isinstance(b, Box):
        # both are internal nodes in the reduction tree (summaries)
        return f"""
Consider the following two lists summarizing criticism about Disneyland California, combine them into a single summary of criticism.

<criticism summary 1>
{a}
</critisim summary 1>

<criticism summary 2>
{b}
</criticism summary 2>

{FORMATTING_INSTRUCTIONS}
""".strip()
    # when the tree isn't perfectly balanced, there will be cases where one input is a leaf node and the other is an internal node
    # so we need to handle the case where one input is a raw criticism and the other is a summary
    if isinstance(a, Box) and not isinstance(b, Box):
        feedback = b
        criticism = a.value
    if not isinstance(a, Box) and isinstance(b, Box):
        feedback = a
        criticism = b.value
    return f"""
Consider the following summary of criticism about Disneyland California, and the following criticism from a single individual. Merge that individual's criticism into the summary.

<criticism summary>
{feedback}
</criticism summary>

<criticism>
{criticism}
</criticism>

{FORMATTING_INSTRUCTIONS}
""".strip()
```

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

### Find minimum and maximum items semantically

Source: https://context7.com/anishathalye/semlib/llms.txt

Shows how to identify the smallest or largest item in an iterable using semantic comparisons. Supports custom criteria, complex objects via templates, and provides both async and sync execution methods.

```python
import asyncio
from semlib import Session
from semlib.extrema import min, max, min_sync, max_sync
from dataclasses import dataclass

async def main():
    session = Session()

    # Find minimum by criteria
    shortest_wavelength = await session.min(
        ["blue", "red", "green"],
        by="wavelength"
    )
    print(shortest_wavelength)  # 'blue'

    # Find maximum by criteria
    best_passer = await session.max(
        ["LeBron James", "Kobe Bryant", "Magic Johnson"],
        by="assists"
    )
    print(best_passer)  # 'Magic Johnson'

    # Custom template for complex comparisons
    @dataclass
    class City:
        name: str
        country: str

    cities = [
        City("Tokyo", "Japan"),
        City("New York", "USA"),
        City("London", "UK")
    ]

    largest = await session.max(
        cities,
        template=lambda a, b: f"Which city has more people, (A) {a.name} or (B) {b.name}?",
    )
    print(largest)  # City(name='Tokyo', country='Japan')

    # Standalone async and sync functions
    result = await min(["elephant", "mouse", "dog"], by="size")
    result = min_sync(["elephant", "mouse", "dog"], by="size")

asyncio.run(main())
```

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

### Extract education text from resumes using LLM

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/resume-filtering/index.ipynb

Uses the semlib session map to extract raw education information from a list of resume texts. It utilizes a high-capacity model to identify university, year, degree, and area of study as unstructured text.

```python
all_education_texts = await session.map(
    texts,
    """
Given a resume, extract the university, graduation year, degree, and area of study for the most advanced degree the individual has.

If some of this information is not present, omit it. If no university education is present, return \"(none)\".

Resume:

{}
""".strip(),
)

education_texts = [i for i in all_education_texts if i != "(none)"]
print(education_texts[0])
```

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

### Map Iterable with Language Model - Python

Source: https://context7.com/anishathalye/semlib/llms.txt

Maps a prompt template over an iterable, sending each item to a language model and collecting the responses. Supports various return types including strings, integers, Pydantic models, and lists of integers. It also offers standalone async and synchronous map functions with concurrency control.

```python
import asyncio
from pydantic import BaseModel
from semlib import Session, Bare
from semlib.map import map, map_sync

class Person(BaseModel):
    name: str
    age: int

async def main():
    session = Session()

    # Basic map with string template (returns list of strings)
    colors = await session.map(
        ["apple", "banana", "kiwi"],
        template="What color is {}? Reply in a single word."
    )
    print(colors)  # ['Red.', 'Yellow.', 'Green.']

    # Map with bare return type
    ages = await session.map(
        ["Barack Obama", "Angela Merkel", "Emmanuel Macron"],
        template="How old was {} when they took office?",
        return_type=Bare(int)
    )
    print(ages)  # [47, 51, 39]

    # Map with Pydantic model return type
    people = await session.map(
        ["Barack Obama", "Angela Merkel"],
        template="Who is {}?",
        return_type=Person
    )
    print(people)  # [Person(name='Barack Obama', age=62), Person(name='Angela Merkel', age=69)]

    # Map with callable template for complex formatting
    prime_factors = await session.map(
        [42, 1337, 2025],
        template=lambda n: f"What are the unique prime factors of {n}?",
        return_type=Bare(list[int])
    )
    print(prime_factors)  # [[2, 3, 7], [7, 191], [5, 81]]

    # Standalone async function with concurrency control
    results = await map(
        ["cat", "dog", "bird"],
        "Describe a {} in one sentence.",
        max_concurrency=3
    )

    # Synchronous version
    results = map_sync(["cat", "dog"], "Describe a {}.")

asyncio.run(main())

```

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

### Implementing caching for API efficiency

Source: https://context7.com/anishathalye/semlib/llms.txt

Semlib provides InMemoryCache and OnDiskCache to prevent redundant API calls. InMemoryCache is volatile, while OnDiskCache persists data across program executions using SQLite.

```python
import asyncio
from semlib import Session, InMemoryCache, OnDiskCache

async def main():
    # In-memory cache
    memory_cache = InMemoryCache()
    session = Session(cache=memory_cache)

    result1 = await session.prompt("What is 2+2?")
    print(f"Cache size: {len(memory_cache)}")  # 1

    result2 = await session.prompt("What is 2+2?")
    print(result1 == result2)  # True

    session.clear_cache()

    # On-disk cache
    disk_cache = OnDiskCache("semlib_cache.db")
    session = Session(cache=disk_cache)

    result = await session.prompt("Explain quantum computing")
    print(f"Cache entries: {len(disk_cache)}")

    disk_cache.clear()

asyncio.run(main())
```

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

### Find items in an iterable using semantic criteria

Source: https://context7.com/anishathalye/semlib/llms.txt

Uses semantic evaluation to identify the first matching item in a collection. Supports negation, custom templates, and both async/sync execution modes.

```python
import asyncio
from semlib import Session
from semlib.find import find, find_sync

async def main():
    session = Session()

    # Basic find with criteria
    actor = await session.find(
        ["Tom Hanks", "Tom Cruise", "Tom Brady"],
        by="actor?"
    )
    print(actor)

    # Find with negate
    non_actor = await session.find(
        ["Tom Hanks", "Tom Cruise", "Tom Brady"],
        by="actor?",
        negate=True
    )
    print(non_actor)

    # Find with custom callable template
    non_palindrome = await session.find(
        [(123, 321), (384, 483), (134, 431)],
        template=lambda pair: f"Is {pair[0]} backwards {pair[1]}?",
        negate=True
    )
    print(non_palindrome)

    # Standalone functions
    result = await find(["apple", "carrot", "banana"], by="vegetable?")
    result_sync = find_sync(["apple", "carrot", "banana"], by="vegetable?")

asyncio.run(main())
```

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

### Execute Semantic Sort Operation

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Performs the sorting of a list of papers using the Semlib session, specifying the conversion function, prompt template, sorting algorithm, and LLM model.

```python
sorted_results = await session.sort(
    relevant,
    to_str=to_str,
    template=COMPARISON_TEMPLATE,
    algorithm=semlib.sort.QuickSort(randomized=False),
    model="openai/gpt-4.1-mini",
)
```

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

### Fetch arXiv Papers by Category and Date

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Defines a function to retrieve arXiv paper metadata based on specified categories and a date range. It constructs a query for the arxiv.py library and returns a list of paper results. Dependencies include the datetime module and the arxiv library.

```python
from datetime import date

import arxiv


def get_papers(categories: list[str], start_date: date, end_date: date) -> list[arxiv.Result]:
    query_cat = " OR ".join(f"cat:{cat}" for cat in categories)
    query_date = f"submittedDate:[{start_date.strftime('%Y%m%d')} TO {end_date.strftime('%Y%m%d')}]"
    query = f"({query_cat}) AND {query_date}"
    search = arxiv.Search(query)
    client = arxiv.Client()
    return list(client.results(search))
```

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

### Convert Paper Metadata to String

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

A helper function that converts an arxiv.Result object into a formatted string representation for the LLM to process.

```python
def to_str(paper: arxiv.Result) -> str:
    return f"""
Title: {paper.title}
Authors: {", ".join(author.name for author in paper.authors)}
Abstract: {paper.summary}
""".strip()
```

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

### Extracting primitive types with Bare

Source: https://context7.com/anishathalye/semlib/llms.txt

The Bare class allows for the extraction of primitive types like integers, lists, and dictionaries directly from LLM responses without needing a Pydantic model. It supports optional class and field naming to influence the model's output generation.

```python
import asyncio
from semlib import Session, Bare

async def main():
    session = Session()

    # Extract an integer
    result = await session.prompt("What is 2+2?", return_type=Bare(int))
    print(result)  # 4

    # Extract a list of integers
    primes = await session.prompt(
        "List the first 5 prime numbers",
        return_type=Bare(list[int])
    )
    print(primes)  # [2, 3, 5, 7, 11]

    # Extract a list of floats
    temps = await session.prompt(
        "Give me 3 random temperatures in Celsius",
        return_type=Bare(list[float])
    )
    print(temps)  # [23.5, -5.2, 37.0]

    # Influence model output using class_name and field_name
    primes = await session.prompt(
        "Give me a list",
        return_type=Bare(
            list[int],
            class_name="list_of_three_values",
            field_name="primes"
        )
    )
    print(primes)  # [2, 3, 5]

    # Extract a boolean
    is_valid = await session.prompt(
        "Is Python a programming language?",
        return_type=Bare(bool)
    )
    print(is_valid)  # True

    # Extract a dictionary
    info = await session.prompt(
        "Return the name and age of Barack Obama as a dict",
        return_type=Bare(dict[str, str])
    )
    print(info)  # {'name': 'Barack Obama', 'age': '62'}

asyncio.run(main())
```

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

### Extract criticism using Semlib map

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/disneyland-reviews/index.ipynb

Uses the Semlib map method to process each review through an LLM prompt to identify and extract specific criticisms.

```python
extracted_criticism = await session.map(
    reviews,
    template=lambda r: f"""
Extract any criticism from this review of Disneyland California, as a succinct bulleted list. If there is none, respond '(none)'.

{r["Review_Text"]}
""".strip(),
)
```

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

### Display Markdown Report

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/airline-support/index.ipynb

Renders a Markdown-formatted report within a notebook environment using `IPython.display.display_markdown`. This allows for immediate visualization of the generated analysis results.

```python
from IPython.display import display_markdown

display_markdown(report, raw=True)  # type:ignore[no-untyped-call]
```

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

### Filter Irrelevant Papers with Semlib

Source: https://github.com/anishathalye/semlib/blob/master/docs/examples/arxiv-recommendations/index.ipynb

Filters a list of papers to remove those matching specified topics. It uses the `session.filter` method with a custom template and a low-cost model. The `negate=True` argument ensures papers *not* matching the criteria are kept. This process can take approximately 30 seconds.

```python
relevant = await session.filter(
    papers,
    template=lambda p: f"""
Your task is to determine if the following academic paper is on any of the following topics.

Paper title: {p.title}
Paper abstract: {p.summary}

It the paper about any of the following topics?

- Medicine
- Healthcare
- Biology
- Chemistry
- Physics
""".strip(),
    model="openai/gpt-4.1-nano",
    negate=True,
)
```