# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is the official Python SDK for the Payi REST API, generated by Stainless. It provides type-safe access to the Payi API with both synchronous (`Payi`) and asynchronous (`AsyncPayi`) clients.

**Important:** This is a generated SDK. Most code in `src/payi/` is auto-generated and may be regenerated. The `src/payi/lib/` and `examples/` directories are never modified by the generator and are safe for manual changes.

## Common Commands

```bash
# Install dependencies (uses uv package manager)
./scripts/bootstrap

# Run all tests (starts Prism mock server automatically)
./scripts/test

# Run a single test file
uv run pytest tests/test_client.py -v

# Run a specific test
uv run pytest tests/test_client.py::TestPayi::test_method_name -v

# Lint and type check
./scripts/lint

# Format code (with auto-fix)
./scripts/format --fix

# Build package
uv build
```

## Architecture

### Client Structure

```
src/payi/
├── _client.py          # Payi and AsyncPayi main client classes
├── _base_client.py     # HTTP client logic, retries, timeouts
├── resources/          # API resource implementations
│   ├── ingest.py
│   ├── limits/
│   ├── categories/
│   ├── use_cases/      # Has nested definitions sub-resource
│   ├── requests/       # Has request_id and response_id sub-resources
│   └── experiences/
└── types/              # Pydantic models for requests/responses
```

### Key Patterns

- Resources follow a nested structure: `client.use_cases.definitions.list()`
- All resources have sync and async variants (`SyncResource`, `AsyncResource`)
- Response types are in `types/` with `_params.py` suffix for request parameters
- Uses Pydantic for all models, supports both v1 and v2

### Testing

Tests run against Prism (OpenAPI mock server) on `http://localhost:4010`. The test script automatically starts Prism if not running. Tests use:
- `pytest-asyncio` for async tests (auto mode)
- `respx` for HTTP mocking
- `pytest-xdist` for parallel execution

### Type Checking

Three tools are used:
- **Ruff**: Linting and formatting (line length 120)
- **Pyright**: Strict mode type checking
- **MyPy**: Additional strict type checking

All three must pass for CI to succeed.
