# Contributing to sklearn-diagnose

Thank you for your interest in contributing to sklearn-diagnose! This document provides guidelines and information for contributors.

## Getting Started

### Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/leockl/sklearn-diagnose.git
   cd sklearn-diagnose
   ```

2. Create a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. Install development dependencies:
   ```bash
   pip install -e ".[dev]"
   ```

4. Run tests to verify setup:
   ```bash
   pytest
   ```

## Development Workflow

### Code Style

We use the following tools to maintain code quality:

- **black** for code formatting
- **ruff** for linting
- **mypy** for type checking

Before submitting a PR, run:
```bash
black sklearn_diagnose tests
ruff check sklearn_diagnose tests
mypy sklearn_diagnose
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=sklearn_diagnose

# Run specific test file
pytest tests/unit_test_diagnose.py

# Run specific test
pytest tests/unit_test_diagnose.py::TestBasicFunctionality::test_diagnose_logistic_regression
```

### Writing Tests

- All new features should include tests
- Tests go in the `tests/` directory
- Follow existing test patterns (use pytest fixtures, descriptive names)
- Aim for high coverage of edge cases
- Chatbot tests are included in `tests/unit_test_diagnose.py` (classes: `TestChatAgent`, `TestChatbotLauncher`, `TestFastAPIEndpoints`)

### Frontend Development

The interactive chatbot uses a React + Vite frontend bundled with the Python package.

#### Development Setup

1. Install Node.js dependencies:
   ```bash
   cd frontend
   npm install
   ```

2. Start the development server:
   ```bash
   npm run dev
   ```
   The frontend will run on `http://localhost:8001` and proxy API requests to `http://localhost:8000`.

3. In a separate terminal, run the Python backend:
   ```bash
   python tests/example_diagnose.py
   ```

#### Building for Production

To update the bundled frontend in the Python package:

```bash
cd frontend
npm run build
```

This creates production files in `frontend/dist/` which are automatically copied to `sklearn_diagnose/server/static/` and included in the pip package via `MANIFEST.in`.

#### Frontend Structure

```
frontend/
├── src/
│   ├── components/      # React components
│   │   ├── Header.jsx
│   │   ├── ChatInterface.jsx
│   │   ├── MessageList.jsx
│   │   ├── MessageBubble.jsx
│   │   └── DiagnosisPanel.jsx
│   ├── hooks/          # Custom React hooks
│   │   └── useChat.js
│   ├── services/       # API client
│   │   └── api.js
│   └── App.jsx         # Main app component
├── vite.config.js      # Vite configuration
└── tailwind.config.js  # Tailwind CSS configuration
```

#### Frontend Testing

When making frontend changes:

1. Test in development mode (`npm run dev`)
2. Build for production (`npm run build`)
3. Test the bundled version by running `python tests/example_diagnose.py`
4. Verify the chatbot works at `http://localhost:8000`

## Architecture Overview

sklearn-diagnose follows an LLM-driven architecture with both batch and interactive modes:

```
Layer 1: Signal Extractors (core/signals.py)
    ↓ Deterministic statistics
Layer 2: LLM Hypothesis Generation (llm/client.py)
    ↓ Failure modes with confidence and severity
Layer 3: LLM Recommendation Generation (llm/client.py)
    ↓ Actionable recommendations
Layer 4: LLM Summary Generation (llm/client.py)
    ↓ Human-readable summaries
Layer 5: Interactive Chatbot (server/chat_agent.py + frontend)
    ↓ Web-based Q&A interface
```

### Key Principles

1. **Evidence-first**: All hypotheses are based on quantitative signals
2. **LLM-powered**: Hypothesis detection, recommendations, and summaries are generated by LLM
3. **Read-only**: Never modify the estimator or input data
4. **Confidence-weighted**: Express uncertainty with confidence scores (0.0 - 0.95)
5. **Example-guided**: LLM uses example templates as guidance for recommendations
6. **Interactive**: Chatbot provides conversational access to diagnosis results

## Submitting Changes

### Pull Request Process

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Make your changes
4. Add/update tests as needed
5. Run the full test suite
6. Update documentation if needed
7. Submit a pull request

### PR Guidelines

- Keep PRs focused on a single change
- Write clear commit messages
- Include tests for new functionality
- Update README.md if adding new features
- Reference any related issues

### Commit Message Format

```
type: short description

Longer description if needed.

Fixes #123
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

## Adding New Failure Modes

To add a new failure mode detection:

1. Add the mode to `FailureMode` enum in `core/schemas.py`
2. Create detection function in `core/hypotheses.py` (e.g., `_check_new_mode()`)
3. Add to `generate_hypotheses()` function
4. Add recommendation templates in `core/recommendations.py`
5. Write tests for the new detection

## Questions?

- Open an issue for bugs or feature requests
- Use discussions for questions and ideas

## License

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