# Contributing to BilgeAI

Thank you for your interest in contributing to BilgeAI! This guide will help you get started.

## Getting Started

### Prerequisites

- Python 3.10+
- Git

### Development Setup

```bash
# Fork and clone the repository
git clone https://github.com/<your-username>/bilge-ai.git
cd bilge-ai

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

## Development Workflow

1. **Create a branch** from `main`:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes** following the code standards below.

3. **Run tests and linting**:
   ```bash
   # Run all tests
   pytest tests/ -v

   # Run linter
   ruff check src/
   ruff format --check src/
   ```

4. **Commit** with a clear message:
   ```bash
   git commit -m "feat: add support for X"
   ```

5. **Push and open a Pull Request** against `main`.

## Commit Message Convention

We follow [Conventional Commits](https://www.conventionalcommits.org/):

| Prefix | Usage |
|--------|-------|
| `feat:` | New feature |
| `fix:` | Bug fix |
| `docs:` | Documentation only |
| `test:` | Adding or updating tests |
| `refactor:` | Code change that neither fixes a bug nor adds a feature |
| `perf:` | Performance improvement |
| `ci:` | CI/CD changes |
| `chore:` | Maintenance tasks |

## Code Standards

- **Linting**: ruff (configured in pyproject.toml)
- **Formatting**: ruff format
- **Type hints**: Use type annotations for all public functions
- **Tests**: Every new feature must include tests (pytest)
- **Lazy imports**: ML libraries (torch, transformers, peft) must be lazy-imported
- **Code comments and variables**: Always in English

### Test Guidelines

- Follow the **AAA pattern** (Arrange, Act, Assert)
- Unit tests go in `tests/unit/`
- Integration tests go in `tests/integration/`
- Use fixtures from `tests/conftest.py` when possible

## What to Contribute

### Good First Issues

Look for issues tagged with `good-first-issue`:

- Documentation improvements
- Additional PII patterns for the privacy scanner
- New GPU profile support
- Translations
- Bug fixes

### Feature Contributions

- New training templates (add to `src/bilgeai/generator/templates/`)
- New export formats (add to `src/bilgeai/cli/commands/export.py`)
- Plugins (use the plugin API documented in the README)
- LLM prompt improvements (see `src/bilgeai/llm/prompts.py`)

## Project Structure

```
src/bilgeai/
  cli/commands/    # CLI command implementations
  core/            # Config, exceptions, constants, logging
  profiler/        # Hardware profiling (CPU, GPU, RAM, disk)
  analyzer/        # Dataset, tokenizer, quality, privacy, LLM evaluator
  optimizer/       # GuardrailEngine + LLMOptimizer = HybridEngine, explainer
  generator/       # Jinja2 training script generation
  llm/             # LLM client (litellm), router, cost tracking
  hub/             # HuggingFace Hub integration
  memory/          # SQLite experiment store
  validation/      # Pre-flight checks, VRAM estimation
  plugins/         # Plugin system (ABC + manager)
tests/
  unit/            # Unit tests
  integration/     # CLI + E2E tests
  conftest.py      # Shared fixtures
```

## Pull Request Process

1. Ensure all tests pass and linting is clean
2. Update documentation if needed
3. Fill in the PR template
4. Request a review

## Code of Conduct

Please be respectful and constructive. We are building an inclusive community.

## Questions?

- Open a [GitHub Discussion](https://github.com/bugrabilge/bilge-ai/discussions)
- File an [Issue](https://github.com/bugrabilge/bilge-ai/issues)

## License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.
