# Contributing to Yera

Thank you for your interest in contributing to Yera! This guide will help you get set up for development.

## Development Setup

### Prerequisites

- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/) package manager

### Getting Started

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd yera
   ```

2. **Install dependencies**
   ```bash
   uv sync --group dev
   ```

3. **Install pre-commit hooks**
   ```bash
   uv run pre-commit install
   ```

That's it! You're ready to start developing.

### UI development

For contributors working on the yera UI, the frontend hot-reloads when you run the dev server:

```bash
# Terminal 1: Start UI dev server
cd web/yera-chat
npm run dev

# Terminal 2: 
# Set env var
export YERA_UI_DIST="your/path/Yera/web/yera-chat/dist"
# Start backend
yera dev --dev-ui
```

## Code Quality

This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting, configured in `pyproject.toml`. The pre-commit hooks will automatically:

- Run the linter and fix issues where possible
- Format your code consistently

### Manual code quality checks

You can also run these tools manually:

```bash
# Run linter
uv run ruff check

# Run linter with auto-fix
uv run ruff check --fix

# Run formatter
uv run ruff format

# Run all pre-commit hooks on all files
uv run pre-commit run --all-files
```

## Running Tests

```bash
# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

# Run specific test file
uv run pytest tests/test_example.py
```

Note: Tests marked with `@pytest.mark.large_gguf` are excluded by default as they require manual setup.

## Jupyter Development

If you're working with notebooks:

```bash
uv sync --group jupyter
uv run jupyter lab
```

## Dependency Management

This project uses uv for dependency management:

- **Add a runtime dependency**: `uv add package-name`
- **Add a dev dependency**: `uv add --group dev package-name`
- **Add a jupyter dependency**: `uv add --group jupyter package-name`

## Submitting Changes

1. Create a new branch for your feature/fix
2. Make your changes
3. Ensure all tests pass and code quality checks succeed
4. Submit a pull request

The pre-commit hooks will ensure your code meets the project's quality standards before each commit.

## Getting Help

If you run into any issues with the development setup, please open an issue or reach out to the maintainers.

## Building Yera

Build the sdist and wheel (to `Yera/dist`):

```bash
./scripts/release/build_package.sh
```

### Manually validating the build

Navigate to `/tmp`:

```bash
cd /tmp
```

Create and activate venv:

```bash
uv venv .venv
source .venv/bin/activate
```

Install yera wheel to venv:

```bash
uv pip install /path/to/repo/Yera/dist/yera-0.1.0-py3-none-any.whl
```

Copy agent over for testing:

```bash
cp /path/to/repo/Yera/stories/internal/agents/input_blocks.py
```

Run Yera!

```bash
yera dev
```
