### Sync Dependencies with uv

Source: https://cascadinglabs.com/yosoi/installation

Install project dependencies using uv after cloning the repository.

```bash
uv sync
```

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

### Install Yosoi with pip

Source: https://cascadinglabs.com/yosoi/installation

Standard command to install Yosoi using pip. This is a viable alternative if you are not using uv.

```bash
pip install yosoi
```

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

### Sync All Dependency Groups with uv

Source: https://cascadinglabs.com/yosoi/installation

Optional command to install all dependency groups, including development and testing dependencies, using uv.

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

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

### Clone Yosoi Repository

Source: https://cascadinglabs.com/yosoi/installation

Clone the Yosoi project repository from GitHub to install from source.

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

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

### Navigate to Project Directory

Source: https://cascadinglabs.com/yosoi/installation

Change the current directory to the cloned Yosoi project folder.

```bash
cd Yosoi
```

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

### Configure Provider API Key

Source: https://cascadinglabs.com/yosoi/quickstart

Set your LLM provider's API key in the .env file in your project root. Supported providers include Groq, Gemini, OpenAI, and others.

```dotenv
GROQ_KEY=your_groq_api_key
# or GEMINI_KEY, OPENAI_KEY, CEREBRAS_KEY, OPENROUTER_KEY, etc.
```

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

### View Yosoi Local Storage Structure

Source: https://cascadinglabs.com/yosoi/configuration

The .yosoi/ directory is automatically created in the project root to manage cached selectors, logs, and output data.

```text
.yosoi/
  selectors/     # Cached selector JSON per domain
  logs/          # Run logs (run_YYYYMMDD_HHMMSS.log)
  debug_html/    # Extracted HTML snapshots (--debug only)
  content/       # Extracted output files (JSON, CSV, etc.)
  stats.json     # Cumulative LLM call and usage statistics
```

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

### Run Yosoi CLI for Discovery

Source: https://cascadinglabs.com/yosoi/quickstart

Use the 'uv run yosoi' command to perform web scraping. This command discovers selectors using an LLM, validates them, and saves them to the .yosoi/ directory. Subsequent runs will use cached selectors.

```bash
uv run yosoi -m groq:llama-3.3-70b-versatile --url https://qscrape.dev/l1/eshop/catalog/?cat=Forge%20%26%20Smithing --contract Product
```

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

### Add Yosoi with uv

Source: https://cascadinglabs.com/yosoi/installation

Use this command to add Yosoi as a dependency in your project when using uv for package management.

```bash
uv add yosoi
```

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

### Scrape a URL using Yosoi Python API

Source: https://cascadinglabs.com/yosoi/quickstart

Initialize a Yosoi Pipeline with configuration and a contract, then use the 'scrape' method to extract data from a given URL. Results are yielded asynchronously.

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


    async for item in pipeline.scrape('https://qscrape.dev/l1/eshop/catalog/?cat=Forge%20%26%20Smithing'):
        print(item.get('name'), item.get('price'))

asyncio.run(main())
```

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

### Add Yosoi with Poetry

Source: https://cascadinglabs.com/yosoi/installation

Command to add Yosoi as a dependency to your project managed by Poetry.

```bash
poetry add yosoi
```

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

### Define a Custom Contract in Python

Source: https://cascadinglabs.com/yosoi/quickstart

Create a Python class inheriting from 'yosoi.Contract' to define the data schema for scraping. Use Yosoi's field types for specific data extraction.

```python
import asyncio
import yosoi as ys



# This Contract is actually built-in, you can import from yosoi.models.defaults!
class Product(ys.Contract):
    """Contract for e-commerce product pages."""


    name: str = ys.Title(description='Product name or title')
    price: float | None = ys.Price(description='Product price (including currency symbol)')
    rating: float | None = ys.Rating(as_float=True, description='Star rating or review score (numeric, e.g. 4.2)')
    reviews_count: int | None = Field(description='Number of reviews or ratings')
    description: str = ys.BodyText(description='Product description or summary')
    availability: str = Field(description='Stock status (e.g. "In Stock", "Out of Stock")')

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.