### Install Yosoi and Configure Environment

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/yosoi/quickstart.mdx

Install the Yosoi package using uv and configure your API provider keys in a .env file to enable LLM-based scraping.

```bash
uv add yosoi

# Add your provider key to .env
GROQ_KEY=your_groq_api_key
```

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

### CLI Usage Examples

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Examples demonstrating how to use the Yosoi Command Line Interface for various scraping tasks.

```APIDOC
## CLI Usage Examples

This section provides examples of how to use the Yosoi CLI for different scraping scenarios.

### Basic Extraction

Run a basic extraction using a built-in contract and outputting to JSON.

```bash
# Basic extraction with built-in Product contract
uv run yosoi --url https://example.com/products --contract Product --output json
```

### Explicit Model Selection

Specify a particular LLM model for the scraping process.

```bash
# With explicit model selection
uv run yosoi -m groq:llama-3.3-70b-versatile \
  --url https://example.com/catalog \
  --contract Product
```

### Multiple URLs and Concurrency

Process multiple URLs from a file with concurrent workers.

```bash
# Process multiple URLs from a file with concurrent workers
uv run yosoi --file urls.txt --contract NewsArticle --workers 5 --output csv
```

### Force Re-discovery

Bypass the cache and force the re-discovery of selectors.

```bash
# Force re-discovery of selectors (bypass cache)
uv run yosoi --url https://example.com --contract Product --force
```

### Debug Mode

Enable debug mode to save HTML snapshots for inspection.

```bash
# Debug mode - saves HTML snapshots to .yosoi/debug_html/
uv run yosoi --url https://example.com --contract Product --debug
```
```

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

### Install Yosoi using package managers

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Instructions for installing the Yosoi framework using common package managers like uv, pip, and Poetry.

```bash
# Using uv (recommended)
uv add yosoi

# Using pip
pip install yosoi

# Using Poetry
poetry add yosoi
```

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

### Install Yosoi from Source

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/yosoi/installation.mdx

Clones the Yosoi repository, navigates into the project directory, and installs dependencies. It includes an option to install all dependency groups.

```bash
git clone https://github.com/CascadingLabs/Yosoi
```

```bash
cd Yosoi
```

```bash
uv sync
```

```bash
uv sync --all-groups
```

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

### Install Yosoi Package

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/yosoi/installation.mdx

Installs the Yosoi package using various Python package managers. uv is recommended for its speed and environment management capabilities. pip and Poetry are also supported.

```bash
uv add yosoi
```

```bash
pip install yosoi
```

```bash
poetry add yosoi
```

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

### Configure LLM API Key and Model

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Example of setting up environment variables for LLM provider API keys and specifying a default model for Yosoi.

```bash
# Choose one provider - Yosoi auto-detects which key is available
GROQ_KEY=your_groq_api_key
# or GEMINI_KEY, OPENAI_KEY, CEREBRAS_KEY, OPENROUTER_KEY, etc.

# Optional: specify default model
YOSOI_MODEL=groq:llama-3.3-70b-versatile
```

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

### Load URLs from Files for Batch Processing (Python)

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Provides examples of using Yosoi's 'load_urls_from_file' function to efficiently load lists of URLs from various file formats. It supports plain text files (one URL per line), JSON arrays, CSV files, Excel spreadsheets, and Parquet files, simplifying batch processing workflows.

```python
import yosoi as ys

# Load from plain text (one URL per line)
urls = ys.load_urls_from_file('urls.txt')

# Load from JSON array
urls = ys.load_urls_from_file('urls.json')

# Load from CSV (extracts URL column)
urls = ys.load_urls_from_file('urls.csv')

# Load from Excel
urls = ys.load_urls_from_file('urls.xlsx')

# Load from Parquet
urls = ys.load_urls_from_file('urls.parquet')
```

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

### GET /contract/manifest

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Generates a markdown-formatted table documenting all fields and configuration settings for the contract.

```APIDOC
## GET /contract/manifest

### Description
Returns a markdown table that provides a comprehensive overview of all contract fields and their current configuration.

### Method
GET

### Endpoint
/contract/manifest

### Response
#### Success Response (200)
- **manifest** (str) - A string containing the markdown table representation.

#### Response Example
{
  "manifest": "| Field | Type | Config |\n|---|---|---|\n| name | str | required |" 
}
```

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

### CLI: Multi-URL Processing

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Example of processing multiple URLs from a file concurrently using the CLI, specifying the contract and number of workers.

```bash
uv run yosoi --file urls.txt --contract NewsArticle --workers 5 --output csv
```

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

### GET /contract/nested_contracts

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Retrieves child contract definitions.

```APIDOC
## GET /contract/nested_contracts

### Description
Returns a mapping of field names to child Contract classes for fields typed as Contract.

### Method
GET

### Endpoint
/contract/nested_contracts

### Response
#### Success Response (200)
- **contracts** (dict) - Map of field_name to child Contract class.

#### Response Example
{
  "user_profile": "ProfileContract"
}
```

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

### CLI: Basic Product Extraction

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Demonstrates basic command-line usage of Yosoi for extracting data using a built-in 'Product' contract and outputting as JSON.

```bash
uv run yosoi --url https://example.com/products --contract Product --output json
```

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

### GET /contract/root

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Retrieves the root selector defined on the contract class.

```APIDOC
## GET /contract/root

### Description
Returns the root selector entry if it has been explicitly configured on the contract class. Returns null if no root is defined.

### Method
GET

### Endpoint
/contract/root

### Response
#### Success Response (200)
- **root** (SelectorEntry | None) - The SelectorEntry object for the container, or null.

#### Response Example
{
  "root": {
    "selector": ".container",
    "type": "css"
  }
}
```

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

### Initialize YosoiConfig

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Demonstrates how to instantiate the YosoiConfig class by providing an LLM configuration and optional debug settings. This object is then used to initialize the main Pipeline.

```python
config = YosoiConfig(
    llm=ys.groq('llama-3.3-70b-versatile', api_key),
    debug=DebugConfig(save_html=False),
)
pipeline = Pipeline(config, contract=MyContract)
```

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

### Yosoi Configuration FAQs

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/manual-selectors.md

Guidelines for field definitions, selector pinning, and troubleshooting extraction behavior.

```APIDOC
## FAQ: Field Definitions

### Description
Clarification on the usage of `description` versus `hint` for AI field discovery.

### Details
- **description**: Defines what the field contains (e.g., "Product category"). Always required.
- **hint**: Defines where or how to find the field (e.g., "Usually in a breadcrumb"). Use when the field is ambiguous.

## FAQ: Pinned Selectors

### Description
Behavioral details regarding pinned selectors in Yosoi contracts.

### Key Concepts
- **Caching**: Pinned selectors are not cached; changes take effect immediately.
- **Failure Handling**: If a pinned selector fails to match, the system returns `None`. It does not attempt automatic re-discovery.
- **Syntax**: Use `ys.xpath()` for root elements. For individual fields, `selector=` currently supports CSS selectors.
```

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

### GET /contract/list_fields

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Retrieves a mapping of list-type fields and their inner types.

```APIDOC
## GET /contract/list_fields

### Description
Returns a dictionary mapping field names to their inner types for fields annotated as list[T].

### Method
GET

### Endpoint
/contract/list_fields

### Response
#### Success Response (200)
- **fields** (dict) - Map of field_name to inner_type.

#### Response Example
{
  "items": "str"
}
```

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

### GET /contract/is_grouped

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Checks if the current contract is configured for multi-item mode.

```APIDOC
## GET /contract/is_grouped

### Description
Returns a boolean indicating if the contract explicitly configures multi-item mode.

### Method
GET

### Endpoint
/contract/is_grouped

### Response
#### Success Response (200)
- **is_grouped** (boolean) - True if multi-item mode is enabled.

#### Response Example
{
  "is_grouped": true
}
```

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

### Configure LLM Providers with Yosoi (Python)

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Shows how to configure Large Language Model (LLM) providers using Yosoi. It covers auto-detection of providers from the environment, explicit provider specification, and detailed provider-specific configurations for services like Groq, OpenAI, Anthropic, Gemini, and Ollama. It also demonstrates using the unified 'provider()' function and creating a Yosoi pipeline with a custom configuration.

```python
import yosoi as ys

# Auto-detect provider from environment
config = ys.auto_config()

# Or specify provider explicitly
config = ys.auto_config(model='groq:llama-3.3-70b-versatile')

# Provider-specific configuration
groq_config = ys.YosoiConfig(
    llm=ys.groq('llama-3.3-70b-versatile')
)

openai_config = ys.YosoiConfig(
    llm=ys.openai('gpt-4o')
)

anthropic_config = ys.YosoiConfig(
    llm=ys.anthropic('claude-sonnet-4-6')
)

gemini_config = ys.YosoiConfig(
    llm=ys.gemini('gemini-2.0-flash')
)

# Local Ollama (no API key required)
ollama_config = ys.YosoiConfig(
    llm=ys.ollama('llama3')
)

# OpenRouter for unified access to multiple providers
openrouter_config = ys.YosoiConfig(
    llm=ys.openrouter('meta-llama/llama-3.3-70b-instruct:free')
)

# Use the unified provider() function
config = ys.YosoiConfig(
    llm=ys.provider('groq:llama-3.3-70b-versatile')
)

# Create pipeline with custom config
pipeline = ys.Pipeline(config, contract=ys.NewsArticle)
```

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

### GET /contract/selector_overrides

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Retrieves all selector overrides defined on fields via yosoi_selector.

```APIDOC
## GET /contract/selector_overrides

### Description
Returns a dictionary of selector overrides. Nested contract overrides are represented using flat {parent}_{child} keys.

### Method
GET

### Endpoint
/contract/selector_overrides

### Response
#### Success Response (200)
- **overrides** (dict[str, dict[str, str]]) - Mapping of field names to their specific selector configurations.

#### Response Example
{
  "primary": {
    "selector": "h1.title"
  },
  "user_profile": {
    "selector": ".profile-box"
  }
}
```

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

### Initialize LLM via Unified Provider String

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

The recommended method to configure an LLM using a provider-prefixed string. It automatically parses the provider and model, supporting various services like Groq, Gemini, and Ollama.

```python
import yosoi as ys

# Recommended usage
config = ys.provider('groq:llama-3.3-70b-versatile')
config = ys.provider('openrouter:meta-llama/llama-3.3-70b-instruct:free')
config = ys.provider('gemini:gemini-2.0-flash')
config = ys.provider('anthropic:claude-opus-4-5')
config = ys.provider('deepseek:deepseek-chat')
config = ys.provider('ollama:llama3')
```

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

### Configure Output via CLI

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/json-output.md

Demonstrates how to specify the output format using the --output flag in the Yosoi CLI. Supports single and multiple format exports.

```bash
uv run yosoi --url https://qscrape.dev/l1/news --contract NewsArticle --output json
uv run yosoi --url https://qscrape.dev/l1/news --contract NewsArticle --output json,csv
```

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

### GET /contract/selector_overrides

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Retrieves all selector overrides defined on fields via the yosoi_selector decorator.

```APIDOC
## GET /contract/selector_overrides

### Description
Returns a mapping of field names to their specific selector overrides. Nested contract overrides are represented using flat {parent}_{child} keys.

### Method
GET

### Endpoint
/contract/selector_overrides

### Response
#### Success Response (200)
- **overrides** (dict[str, dict[str, str]]) - A dictionary mapping field names to their selector configuration dictionaries.

#### Response Example
{
  "primary": {
    "selector": "h1.title"
  },
  "meta_description": {
    "selector": "meta[name='description']"
  }
}
```

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

### Export Multiple Formats in Python

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/json-output.md

Demonstrates how to pass a list of formats to the output_format parameter to generate multiple file types simultaneously.

```python
pipeline = ys.Pipeline(config, contract=Article, output_format=['json', 'csv'])
```

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

### GET /contract/field_hints

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Retrieves a dictionary of yosoi_hints for all fields, including expanded nested contract fields.

```APIDOC
## GET /contract/field_hints

### Description
Returns a mapping of flat field names to their corresponding yosoi_hint values. Nested contracts are automatically expanded using the {parent}_{child} naming convention.

### Method
GET

### Endpoint
/contract/field_hints

### Response
#### Success Response (200)
- **hints** (dict[str, str | None]) - A mapping of field names to hint strings.

#### Response Example
{
  "user_name": "string",
  "address_zipcode": "string"
}
```

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

### Configure LLM using Provider String

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Creates an LLM configuration from a single model string, automatically parsing the provider. This is the recommended method for configuring models. It supports various formats and providers like Groq, OpenRouter, Gemini, Anthropic, Deepseek, and Ollama. API keys can be provided explicitly or resolved from environment variables. Additional LLMConfig fields can be passed as keyword arguments.

```python
import yosoi as ys

# Example using preferred format
config = ys.provider('groq:llama-3.3-70b-versatile')
config = ys.provider('openrouter:meta-llama/llama-3.3-70b-instruct:free')
config = ys.provider('gemini:gemini-2.0-flash')
config = ys.provider('anthropic:claude-opus-4-5')
config = ys.provider('deepseek:deepseek-chat')
config = ys.provider('ollama:llama3')

# Example using provider/model format
config = ys.provider('groq/llama-3.3-70b-versatile')

# Example with explicit API key and additional arguments
config = ys.provider('groq:llama-3.3-70b-versatile', api_key='my-groq-api-key', temperature=0.7, max_tokens=1024)
```

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

### GET /contract/root

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Retrieves the root selector entry defined for the contract class, if one exists.

```APIDOC
## GET /contract/root

### Description
Returns the root selector entry for the repeating container element if explicitly set on the contract class.

### Method
GET

### Endpoint
/contract/root

### Response
#### Success Response (200)
- **root** (SelectorEntry | None) - The SelectorEntry object or null if not defined.

#### Response Example
{
  "root": {
    "selector": ".container",
    "type": "css"
  }
}
```

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

### Configure MoonshotAI (Kimi)

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Facilitates quick configuration for MoonshotAI (Kimi) models. Requires a model name and optionally an API key. The API key can be omitted, in which case it will be read from the MOONSHOT_API_KEY environment variable. Extra LLMConfig fields are supported through kwargs.

```python
def moonshotai(model_name: str, api_key: str | None = None, kwargs: Any = {}) -> LLMConfig:
    """Quick config for MoonshotAI (Kimi).
    **Args:**

    - `model_name` `str` — Moonshot model identifier (e.g. 'kimi-k2-0711-preview')
    - `api_key` `str | None` — Moonshot API key. If omitted, reads from MOONSHOT_API_KEY.
    - `**kwargs` `Any` — Additional LLMConfig fields.

    **Returns:** `LLMConfig` — Configured LLMConfig for MoonshotAI.
    """
    pass
```

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

### GET /contract/field_hints

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Retrieves a dictionary of field hints for the contract, with nested fields flattened using parent_child naming conventions.

```APIDOC
## GET /contract/field_hints

### Description
Returns a mapping of field names to their corresponding yosoi_hint. Nested contracts are expanded into flat keys using the format {parent}_{child}.

### Method
GET

### Endpoint
/contract/field_hints

### Response
#### Success Response (200)
- **field_hints** (dict[str, str | None]) - A dictionary where keys are field names and values are the associated hints.

#### Response Example
{
  "user_name": "The full name of the user",
  "address_street": "Street address component"
}
```

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

### Switching LLM Providers via Environment Variable

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/yosoi/quickstart.mdx

Demonstrates how to configure Yosoi to use a specific LLM provider and model by setting the `YOSOI_MODEL` environment variable. This is useful for persistent configuration.

```bash
export YOSOI_MODEL=groq:llama-3.3-70b-versatile
```

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

### Executing Yosoi Contracts via CLI

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/manual-selectors.md

Shows how to run a Yosoi extraction pipeline using the command line interface, specifying the URL and the contract file.

```bash
uv run python taxes.py
uv run yosoi --url https://qscrape.dev/l1/taxes --contract taxes.py:TaxRecord --output json
```

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

### GET /utils/load_urls

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/functions.md

Loads a list of URLs from a specified file path supporting multiple formats including JSON, CSV, and Parquet.

```APIDOC
## GET /utils/load_urls

### Description
Loads URLs from a file (JSON, plain text, CSV, Excel, Parquet, or Markdown).

### Method
GET

### Endpoint
/utils/load_urls

### Parameters
#### Query Parameters
- **filepath** (string) - Required - Path to file containing URLs.

### Response
#### Success Response (200)
- **urls** (list[str]) - List of URL strings.

#### Response Example
[
  "https://example.com/page1",
  "https://example.com/page2"
]
```

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

### Selector Cache File Structure

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/selectors.md

Example of the JSON structure stored in .yosoi/selectors/ for each domain, containing metadata about selector reliability and discovery source.

```json
{
  "title": {
    "primary": "h1.article-title",
    "fallback": "h1",
    "tertiary": null,
    "discovered_at": "2025-03-01T14:22:00Z",
    "last_verified_at": "2025-03-15T09:00:00Z",
    "last_failed_at": null,
    "failure_count": 0,
    "source": "discovered"
  }
}
```

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

### Switching LLM Providers in Yosoi CLI

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/yosoi/quickstart.mdx

Shows how to specify a different LLM provider and model when using the Yosoi command-line interface. This is done using the `--model` flag with a `provider:model` string.

```bash
yosoi --model groq:llama-3.3-70b-versatile
```

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

### MoonshotAI Configuration

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Provides a quick configuration for MoonshotAI (Kimi) models.

```APIDOC
## moonshotai

### Description
Quick config for MoonshotAI (Kimi).

### Method
```python
moonshotai
```

### Endpoint
N/A (Local Configuration Function)

### Parameters
#### Arguments
- **model_name** (str) - Required - Moonshot model identifier (e.g. 'kimi-k2-0711-preview')
- **api_key** (str | None) - Optional - Moonshot API key. If omitted, reads from MOONSHOT_API_KEY.
- **kwargs** (Any) - Optional - Additional LLMConfig fields.

### Returns
- **LLMConfig** - Configured LLMConfig for MoonshotAI.

### Example
```python
from yosoi.core.discovery.config import moonshotai

config = moonshotai(model_name='kimi-k2-0711-preview', api_key='YOUR_API_KEY')
```
```

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

### Get Root Selector - Python

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Retrieves the root selector if it has been explicitly set on the contract class. This is useful for identifying the primary repeating container element within a contract structure.

```python
def get_root() -> SelectorEntry | None:
    """Return the root selector if explicitly set on the contract class."""
    # Returns: SelectorEntry for the repeating container element, or None.
```

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

### Configure Alibaba Cloud DashScope

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Creates an LLMConfig for Alibaba Cloud DashScope. It accepts a model name and optional API key, falling back to environment variables if not provided.

```python
from yosoi.core.discovery.config import alibaba
config = alibaba(model_name="qwen-max", api_key="your-api-key")
```

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

### Process Multiple URLs with Yosoi

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

The process_urls function handles batch processing of URLs. It supports sequential or concurrent execution using taskiq and provides hooks for start and completion callbacks.

```python
from yosoi.core.pipeline import process_urls

async def run_batch():
    results = await process_urls(
        urls=["https://example.com", "https://example.org"],
        workers=2,
        max_fetch_retries=3
    )
    print(results)
```

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

### xAI (Grok) Configuration

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Enables quick configuration for xAI (Grok) models via the native xAI client, supporting API key authentication.

```APIDOC
## `xai`

`xai(model_name: str, api_key: str | None = None, kwargs: Any = {}) -> LLMConfig`

Quick config for xAI (Grok models via native xAI client).

**Args:**

- `model_name` (str) — xAI model identifier (e.g. 'grok-3', 'grok-3-mini')
- `api_key` (str | None) — xAI API key. If omitted, reads from XAI_API_KEY.
- `**kwargs` (Any) — Additional LLMConfig fields.

**Returns:** `LLMConfig` — Configured LLMConfig for xAI.
```

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

### auto_config

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/functions.md

Auto-detects the LLM provider and builds the configuration. It follows a resolution order to determine the model, starting from an explicit argument, then environment variables, and finally falling back to default providers.

```APIDOC
## `auto_config`

### Description
Auto-detect LLM provider and build config.

Resolution order:
1. Explicit ``model`` argument (``provider:model-name`` format)
2. ``$YOSOI_MODEL`` environment variable
3. First provider with an available API key
4. Groq default fallback

### Method
GET

### Endpoint
/api/auto_config

### Parameters
#### Query Parameters
- **model** (str | None) - Optional - Model string in ``provider:model-name`` format, or None.
- **debug** (bool) - Optional - Whether to enable debug HTML saving.

### Response
#### Success Response (200)
- **YosoiConfig** (object) - Validated YosoiConfig.

#### Error Response
- **ValueError** - On configuration errors (bad model format, no API key, etc.).
```

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

### Get Field Hints - Python

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Retrieves Yosoi hints for each flat field name, expanding nested contracts into a parent-child format. This is useful for understanding the structure and naming conventions of contract fields.

```python
def field_hints() -> dict[str, str | None]:
    """Return yosoi_hint per (flat) field name, expanding nested contracts to {parent}_{child}."""
    ...
```

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

### Configure LLM for SambaNova

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Provides a quick configuration for SambaNova LLMs. Requires a model name and optionally an API key. If the API key is omitted, it will be read from the SAMBANOVA_API_KEY environment variable. Additional LLMConfig fields can be passed as keyword arguments.

```python
import yosoi as ys

# Configure with model name and API key
config = ys.sambanova(model_name='Meta-Llama-3.3-70B-Instruct', api_key='my-sambanova-api-key')

# Configure using environment variable for API key
config = ys.sambanova(model_name='Meta-Llama-3.3-70B-Instruct')

# Configure with additional LLMConfig fields
config = ys.sambanova(model_name='Meta-Llama-3.3-70B-Instruct', temperature=0.8, max_tokens=2048)
```

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

### Get field descriptions

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Returns a dictionary mapping field names to their descriptions, excluding selector overrides. It handles nested contracts by flattening keys and adding scoping or co-location hints where applicable.

```python
field_descriptions() -> dict[str, str]
```

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

### Configure Output via Python Pipeline

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/json-output.md

Shows how to define the output format within a Yosoi Pipeline object using the output_format parameter. This allows for programmatic control over data persistence.

```python
import asyncio
import yosoi as ys

class Article(ys.Contract):
    title: str = ys.Title()
    author: str = ys.Author()

async def main():
    pipeline = ys.Pipeline(
        ys.auto_config(),
        contract=Article,
        output_format='json',
    )
    async for item in pipeline.scrape('https://qscrape.dev/l1/news'):
        print(item.get('title'))

asyncio.run(main())
```

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

### Configure Groq LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Enables quick configuration for Groq LLM services. Users need to specify the model name and can optionally provide their Groq API key. If the API key is omitted, it will attempt to read from the GROQ_API_KEY or GROQ_KEY environment variables. Additional LLMConfig fields can also be passed.

```python
from yosoi.core.discovery.config import groq

# Example usage:
config = groq(model_name='llama-3.3-70b-versatile', api_key='YOUR_GROQ_API_KEY')
print(config)
```

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

### Per-Element Coercion for list[float] in Python

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/list-fields.md

Demonstrates how type coercions are applied to each element of a list field. This example uses `ys.Price()` with `list[float]` to automatically strip currency symbols and convert values to floats.

```python
class PriceComparison(ys.Contract):
    name: str = ys.Title()
    vendor_prices: list[float] = ys.Price(description='Prices from different vendors')

raw = {'name': 'Widget', 'vendor_prices': ['$12.99', '£9.50', '€11.00']}
result = PriceComparison.model_validate(raw)
# result.vendor_prices == [12.99, 9.50, 11.00]
```

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

### Get Selector Overrides - Python

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Returns a dictionary of selector overrides defined on fields using the `yosoi_selector` attribute. This allows for custom CSS selectors to be applied to specific fields, including nested contracts which use flattened keys.

```python
def get_selector_overrides() -> dict[str, dict[str, str]]:
    """Return selector overrides defined on fields via ``yosoi_selector``."""
    # Returns: Mapping of field name to selector dict (e.g. ``{"primary": "h1.title"}``). 
    # Nested contract overrides use flat ``{parent}_{child}`` keys.
```

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

### Configure Ollama LLM (Local)

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Enables quick configuration for Ollama, allowing local LLM deployment. No API key is needed. The base URL defaults to 'http://localhost:11434' but can be overridden using 'extra_params' in kwargs. Requires a model name.

```python
from yosoi.core.discovery.config import LLMConfig

def ollama(model_name: str, kwargs: Any = {}) -> LLMConfig:
    """Quick config for Ollama (local).
    No API key required. Supply ``base_url`` via ``extra_params`` to override
    the default ``http://localhost:11434``.
    **Args:**
        model_name (str): Ollama model tag (e.g. 'llama3', 'mistral', 'qwen2.5')
        **kwargs (Any): Additional LLMConfig fields.
    **Returns:** LLMConfig: Configured LLMConfig for Ollama.
    """
    pass
```

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

### Configure xAI LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Enables quick configuration for xAI (Grok models) using the native xAI client. An API key can be provided directly or will be read from the XAI_API_KEY environment variable. Accepts a model name and additional LLMConfig fields.

```python
from yosoi.core.discovery.config import xai

# Example usage with API key:
xai_config = xai(model_name='grok-3', api_key='YOUR_XAI_API_KEY')

# Example usage without API key (reads from environment variable):
xai_config_env = xai(model_name='grok-3-mini')
```

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

### Save Extracted Data as JSON (Python)

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/multi-item.md

This example shows how to configure a Yosoi `Pipeline` to save extracted data in JSON format. When `output_format='json'` is specified, multi-item pages are saved as a JSON object with an 'items' array containing all extracted items.

```python
import yosoi as ys

# Assuming 'config' is a valid Yosoi configuration object and 'Product' is a defined Contract
# config = ys.Config(...)
# class Product(ys.Contract): ...

pipeline = ys.Pipeline(config, contract=Product, output_format='json')

# Subsequent scrape calls will save output to JSON files.
```

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

### Configure Google Gemini LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Creates an LLMConfig instance for Google Gemini. It supports multiple environment variables for the API key, including GEMINI_API_KEY, GEMINI_KEY, and GOOGLE_API_KEY.

```python
from yosoi.core.discovery.config import gemini

config = gemini(model_name='gemini-2.0-flash')
```

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

### Define Custom Per-Field Validators (Python)

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Illustrates how to define custom validation logic for specific fields within a Yosoi Contract using an inner 'Validators' class. These static methods are executed before type coercion, allowing for pre-processing like string truncation or case normalization. The example shows validation for 'title' and 'category' fields.

```python
import yosoi as ys

class BookStore(ys.Contract):
    title: str = ys.Title()
    price: float = ys.Price(hint='Book price including currency symbol')
    category: str = ys.Field(hint='Genre or category label')

    class Validators:
        @staticmethod
        def title(v: str) -> str:
            """Truncate very long titles to 60 characters."""
            return v[:60].rstrip() + ('...' if len(v) > 60 else '')

        @staticmethod
        def category(v: str) -> str:
            """Normalise category to title case."""
            return v.strip().title()

# Usage
raw = {
    'title': 'The Very Long Title That Goes On and On and Eventually Exceeds Sixty Characters',
    'price': '$1,234.56',
    'category': '  science fiction  ',
}
result = BookStore.model_validate(raw)
# result.title    == 'The Very Long Title That Goes On and On and Eventually...'
# result.price    == 1234.56
# result.category == 'Science Fiction'
```

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

### Extract Products via CLI

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/e-commerce.md

Use the built-in Product contract to extract catalogue data directly from the command line.

```bash
uv run yosoi --url https://qscrape.dev/l1/eshop --contract Product --output json
```

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

### Utilize Selector Types for Data Extraction (Python)

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Demonstrates the use of various selector types in Yosoi for specifying data extraction targets. It includes CSS selectors (default), XPath selectors for complex navigation, regex for pattern matching, JSON-LD for structured data, and an AI-discovered root for nested contracts. Examples show how to define these selectors directly or within a Contract's 'root' attribute.

```python
import yosoi as ys

# CSS selector (default and most common)
css_selector = ys.css('article.product_pod')

# XPath selector for complex navigation
xpath_selector = ys.xpath('//div[@class="product"]//h2')

# Regex for pattern-based extraction
regex_selector = ys.regex(r'<h2[^>]*>(.*?)</h2>')

# JSON-LD for structured data extraction
jsonld_selector = ys.jsonld('$.name')

# AI-discovered root for nested contracts
discover_root = ys.discover()

class Product(ys.Contract):
    root = ys.css('article.product-card')  # CSS root

    name: str = ys.Title()
    price: float = ys.Price()

class ComplexProduct(ys.Contract):
    root = ys.xpath('//section[@data-product-id]')  # XPath root

    name: str = ys.Title()
    price: float = ys.Price()
```

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

### POST /process_url

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Initiates the full pipeline process for a single URL, including fetching, AI-based selector discovery, verification, and storage.

```APIDOC
## POST /process_url

### Description
Processes a single URL by discovering, verifying, and saving selectors. This is a wrapper around the core scrape functionality.

### Method
POST

### Endpoint
/process_url

### Parameters
#### Request Body
- **url** (string) - Required - The target URL to process.
- **force** (boolean) - Optional - Force re-discovery even if selectors exist. Defaults to false.
- **max_fetch_retries** (integer) - Optional - Max fetch attempts. Defaults to 2.
- **max_discovery_retries** (integer) - Optional - Max AI discovery attempts. Defaults to 3.
- **skip_verification** (boolean) - Optional - Skip verification step. Defaults to false.
- **fetcher_type** (string) - Optional - Type of fetcher to use. Defaults to 'simple'.
- **output_format** (string/list) - Optional - Desired output format(s).

### Request Example
{
  "url": "https://example.com",
  "force": false,
  "max_fetch_retries": 2
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of successful processing.

#### Response Example
{
  "status": "success"
}
```

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

### Python: Synchronous URL Processing with Pipeline.process_url()

Source: https://context7.com/cascadinglabs/yosoi-docs/llms.txt

Illustrates synchronous processing of a single URL using `Pipeline.process_url()`, allowing fine-grained control over retries, verification, and fetcher types. Results are saved to disk.

```python
import asyncio
import yosoi as ys
from yosoi.models.defaults import Product

async def main():
    config = ys.auto_config()
    pipeline = ys.Pipeline(config, contract=Product, output_format='json')

    # Process URL with custom retry settings
    await pipeline.process_url(
        url='https://example.com/product/123',
        force=False,                  # Use cached selectors if available
        max_fetch_retries=2,          # Retry failed HTTP requests
        max_discovery_retries=3,      # Retry failed LLM discovery
        skip_verification=False,      # Verify selectors match the page
        fetcher_type='simple',        # Use simple HTTP fetcher
        output_format='json'          # Save output as JSON
    )

    # Results are saved to .yosoi/content/

asyncio.run(main())
```

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

### Nebius AI Studio Configuration

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Provides a quick configuration for Nebius AI Studio models.

```APIDOC
## nebius

### Description
Quick config for Nebius AI Studio.

### Method
```python
nebius
```

### Endpoint
N/A (Local Configuration Function)

### Parameters
#### Arguments
- **model_name** (str) - Required - Nebius model identifier (e.g. 'Qwen/Qwen3-235B-A22B-fast')
- **api_key** (str | None) - Optional - Nebius API key. If omitted, reads from NEBIUS_API_KEY.
- **kwargs** (Any) - Optional - Additional LLMConfig fields.

### Returns
- **LLMConfig** - Configured LLMConfig for Nebius.

### Example
```python
from yosoi.core.discovery.config import nebius

config = nebius(model_name='Qwen/Qwen3-235B-A22B-fast', api_key='YOUR_API_KEY')
```
```

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

### Configure Nebius AI Studio LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Provides a quick configuration for Nebius AI Studio models. It requires a model name and optionally an API key, falling back to the NEBIUS_API_API_KEY environment variable if not provided. Additional LLMConfig fields can be passed via kwargs.

```python
from yosoi.core.discovery.config import LLMConfig

def nebius(model_name: str, api_key: str | None = None, kwargs: Any = {}) -> LLMConfig:
    """Quick config for Nebius AI Studio.
    **Args:**
        model_name (str): Nebius model identifier (e.g. 'Qwen/Qwen3-235B-A22B-fast')
        api_key (str | None): Nebius API key. If omitted, reads from NEBIUS_API_KEY.
        **kwargs (Any): Additional LLMConfig fields.
    **Returns:** LLMConfig: Configured LLMConfig for Nebius.
    """
    pass
```

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

### Configure Local Ollama LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Sets up an LLMConfig for a local Ollama instance. No API key is required, and users can override the default base URL by passing a base_url in the additional keyword arguments.

```python
from yosoi.core.discovery.config import ollama

config = ollama(model_name="llama3", base_url="http://localhost:11434")
```

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

### Define Yosoi Types and Fields

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/types.md

Demonstrates the initialization of Yosoi type factories and the Field wrapper for AI-assisted data extraction. These constructors allow for configuration of scraping hints, selectors, and field constraints.

```python
from yosoi.types import Author, BodyText, Datetime, Field

# Basic type factories
author = Author(description="Author name")
body = BodyText(description="Article content")
date = Datetime(assume_utc=True, as_iso=True)

# Field wrapper with AI scraping hints
field = Field(
    hint="Find the main article title",
    frozen=True,
    selector=".article-title",
    delimiter=","
)
```

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

### OpenAI LLM Configuration

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Provides a quick configuration for OpenAI models.

```APIDOC
## `openai`

### Description
Quick config for OpenAI.

### Method
`openai(model_name: str, api_key: str | None = None, kwargs: Any = {}) -> LLMConfig`

### Parameters
#### Arguments
- **model_name** (str) - Required - OpenAI model identifier (e.g. 'gpt-4o', 'gpt-4o-mini')
- **api_key** (str | None) - Optional - OpenAI API key. If omitted, reads from OPENAI_API_KEY or OPENAI_KEY.
- **kwargs** (Any) - Optional - Additional LLMConfig fields.

### Returns
`LLMConfig` - Configured LLMConfig for OpenAI.
```

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

### XPath Selector

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Demonstrates how to create an XPath SelectorEntry using the xpath function.

```APIDOC
## POST /api/users

### Description
Creates a new user in the system.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the user.
- **email** (string) - Required - The email address of the user.

### Request Example
```json
{
  "name": "John Doe",
  "email": "john.doe@example.com"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the newly created user.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "id": "user-12345",
  "message": "User created successfully."
}
```
```

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

### Configure xAI (Grok) LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Facilitates quick configuration for xAI models, specifically Grok models accessed via the native xAI client. It requires the model name and optionally an API key. If the API key is omitted, it defaults to reading from the XAI_API_KEY environment variable. Extra LLMConfig fields can be provided using kwargs.

```python
from yosoi.core.discovery.config import LLMConfig

def xai(model_name: str, api_key: str | None = None, kwargs: Any = {}) -> LLMConfig:
    """Quick config for xAI (Grok models via native xAI client).
    **Args:**

    - `model_name` `str` — xAI model identifier (e.g. 'grok-3', 'grok-3-mini')
    - `api_key` `str | None` — xAI API key. If omitted, reads from XAI_API_KEY.
    - `**kwargs` `Any` — Additional LLMConfig fields.

    **Returns:** `LLMConfig` — Configured LLMConfig for xAI.
    """
    pass
```

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

### Automatic Root Discovery in Python

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/e-commerce.md

Configure a Yosoi contract without a root selector to allow the AI to automatically identify the repeating product container.

```python
import asyncio
import yosoi as ys

class Product(ys.Contract):
    name: str = ys.Title()
    price: float = ys.Price()
    rating: str = ys.Rating()

async def main():
    pipeline = ys.Pipeline(ys.auto_config(), contract=Product)

    async for item in pipeline.scrape('https://qscrape.dev/l1/eshop'):
        print(item.get('name'), item.get('price'))

asyncio.run(main())
```

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

### Configure GitHub Models LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Creates an LLMConfig instance for GitHub Models. It retrieves the required authentication token from the GITHUB_TOKEN environment variable if no key is explicitly passed.

```python
from yosoi.core.discovery.config import github

config = github(model_name='gpt-4o')
```

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

### Configure Nebius AI Studio LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Initializes an LLMConfig for Nebius AI Studio. It requires a model identifier and supports an optional API key, falling back to the NEBIUS_API_KEY environment variable.

```python
from yosoi.core.discovery.config import nebius

config = nebius(model_name="Qwen/Qwen3-235B-A22B-fast", api_key="your-api-key")
```

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

### POST /config/bedrock

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/helpers.md

Configures an LLMConfig object for AWS Bedrock using model ARN or ID.

```APIDOC
## POST /config/bedrock

### Description
Creates a configuration for AWS Bedrock. Credentials can be provided directly or resolved via environment variables (AWS_ACCESS_KEY_ID).

### Method
POST

### Endpoint
/config/bedrock

### Parameters
#### Request Body
- **model_name** (string) - Required - Bedrock model ARN or ID.
- **api_key** (string) - Optional - AWS access key ID.
- **kwargs** (object) - Optional - Additional parameters like region_name or aws_secret_access_key.

### Request Example
{
  "model_name": "anthropic.claude-3-5-sonnet-20241022-v2:0"
}

### Response
#### Success Response (200)
- **LLMConfig** (object) - Configured LLMConfig object for Bedrock.

#### Response Example
{
  "status": "success",
  "config": { "provider": "bedrock", "model": "anthropic.claude-3-5-sonnet-20241022-v2:0" }
}
```

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

### Configure Vercel AI LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Initializes an LLMConfig object for the Vercel AI provider. It requires a model name and optionally accepts an API key, checking AI_SDK_KEY or VERCEL_API_KEY environment variables if the key is omitted.

```python
from yosoi.core.discovery.config import vercel

config = vercel(model_name='vercel-model-id')
```

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

### Defining a Fully Manual Extraction Contract

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/guides/examples/manual-selectors.md

Shows how to create a contract where every field is pinned, resulting in zero LLM calls and purely deterministic extraction.

```python
class FullyPinned(ys.Contract):
    root = ys.css('div.item')
    title: str = ys.Title(selector='h2.title')
    price: float = ys.Price(selector='span.price')
    rating: str = ys.Rating(selector='div.stars')
```

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

### YosoiConfig

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/reference/classes.md

Top-level Yosoi configuration bundling LLM, debug, and telemetry settings.

```APIDOC
## YosoiConfig

### Description
Top-level Yosoi configuration bundling LLM, debug, and telemetry settings.

### Example
```python
config = YosoiConfig(
    llm=ys.groq('llama-3.3-70b-versatile', api_key),
    debug=DebugConfig(save_html=False),
)
pipeline = Pipeline(config, contract=MyContract)
```
```

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

### Configure SambaNova LLM

Source: https://github.com/cascadinglabs/yosoi-docs/blob/main/api-reference.md

Initializes an LLMConfig object for the SambaNova provider. It requires a model name and optionally accepts an API key, defaulting to the SAMBANOVA_API_KEY environment variable if not provided.

```python
from yosoi.core.discovery.config import sambanova

config = sambanova(model_name='Meta-Llama-3.3-70B-Instruct', api_key='your-api-key')
```