# Contributing to Hindsight

Thanks for your interest in contributing to Hindsight!

## Getting Started

1. Fork and clone the repository
   ```bash
   git clone git@github.com:vectorize-io/hindsight.git
   cd hindsight
   ```
2. Set up your environment:
   ```bash
   cp .env.example .env
   ```
   Edit the .env to add LLM API key and config as required

3. Install dependencies:
   ```bash
   # Python dependencies
   uv sync --directory hindsight-api/

   # Node dependencies (uses npm workspaces)
   npm install
   ```

## Development

### Running the API locally

```bash
./scripts/dev/start-api.sh
```

### Running the Control Plane locally

```bash
./scripts/dev/start-control-plane.sh
```

### Running the documentation locally

```bash
./scripts/dev/start-docs.sh
```

### Running tests

```bash
cd hindsight-api
uv run pytest tests/
```

### Code Style

We use [Ruff](https://docs.astral.sh/ruff/) for Python linting and formatting, and ESLint/Prettier for TypeScript.

#### Setting up git hooks (recommended)

Set up git hooks to automatically lint and format code before each commit:

```bash
./scripts/setup-hooks.sh
```

This configures git to use the hooks in `.githooks/`, which run all scripts in `scripts/hooks/` on commit. The lint hook runs in parallel:
- **Python**: `ruff check --fix`, `ruff format`, `ty check`
- **TypeScript**: `eslint --fix`, `prettier`

#### Manual linting and formatting

```bash
# Run all lints (same as pre-commit)
./scripts/hooks/lint.sh

# Or run individually for Python:
cd hindsight-api
uv run ruff check --fix .   # Lint and auto-fix
uv run ruff format .        # Format code
uv run ty check hindsight_api  # Type check
```

#### Style guidelines

- Use Python type hints
- Follow existing code patterns
- Keep functions focused and well-named

## Pull Requests

1. Create a feature branch from `main`
2. Make your changes
3. Run tests to ensure nothing breaks
4. Submit a PR with a clear description of changes

## Reporting Issues

Open an issue on GitHub with:
- Clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Environment details (OS, Python version)

## Questions?

Open a discussion on GitHub or reach out to the maintainers.