docs/development/contributing.md

# Contributing

Thank you for your interest in contributing to the AI Imaging Agent! This guide will help you get started.

## Getting Started

### 1. Fork and Clone

```bash

# Fork the repository on GitHub

# Then clone your fork

git clone https://github.com/YOUR_USERNAME/ai-agent.git

cd ai-agent

```

### 2. Set Up Development Environment

```bash

# Create virtual environment

python -m venv .venv

source .venv/bin/activate  # On Windows: .venv\Scripts\activate



# Install in development mode

pip install -e ".[dev]"

```

### 3. Create a Branch

```bash

git checkout -b feature/your-feature-name

# or

git checkout -b fix/issue-description

```

## Development Workflow

### Making Changes

1. **Make your changes** in the appropriate module
2. **Test your changes** (see [Testing](testing.md))
3. **Update documentation** if needed
4. **Update CHANGELOG.md** following [Keep a Changelog](https://keepachangelog.com/) format

<!-- ### Code Style

We use standard Python tools for code quality:

#### Black

Code formatting:

```bash

black src/ tests/

```

#### Ruff

Linting:

```bash

ruff check src/ tests/

``` -->



#### Type Checking



MyPy for type checking:



```bash

mypy src/

```

### Running Tests

```bash

# Run all tests

pytest tests/



# Run specific test file

pytest tests/test_retrieval_pipeline.py



# Run with coverage

pytest --cov=ai_agent tests/

```

## Contribution Guidelines

### Code Quality

- **Follow PEP 8**: Use Black for formatting
- **Type hints**: Add type annotations to new functions
- **Docstrings**: Document all public functions and classes
- **Tests**: Add tests for new functionality
- **No warnings**: Fix any linter warnings before submitting

### Commit Messages

Use clear, descriptive commit messages:

```

feat: Add alternative search tool for agent



- Implement search_alternative tool

- Add retry logic for insufficient results

- Update agent prompt with tool description

```

**Format**:

- `feat:` New features
- `fix:` Bug fixes
- `docs:` Documentation changes
- `test:` Test additions/changes
- `refactor:` Code refactoring
- `chore:` Maintenance tasks

### Pull Requests

1. **Update CHANGELOG.md** under `[Unreleased]` section
2. **Write clear PR description** explaining changes
3. **Link related issues** if applicable
4. **Request review** from maintainers

**PR description template**:

```markdown

## Description

Brief description of changes



## Type of Change

- [ ] Bug fix

- [ ] New feature

- [ ] Documentation update

- [ ] Refactoring



## Testing

How to test these changes



## Checklist

- [ ] Code follows project style

- [ ] Tests added/updated

- [ ] Documentation updated

- [ ] CHANGELOG.md updated

```

## Areas to Contribute

### High Priority

- **Catalog expansion**: Add more imaging tools
- **Demo integration**: Improve Gradio Space execution and add new spaces for tools
- **Format support**: Add new image format handlers

<!-- ### Good First Issues

Look for issues tagged `good-first-issue` on GitHub:

- Bug fixes
- Documentation improvements
- Test coverage expansion
- Example scripts -->

### Feature Requests

Before implementing new features:

1. **Check existing issues** for similar requests
2. **Open an issue** to discuss the feature
3. **Get feedback** from maintainers
4. **Implement** after discussion

## Documentation

### Writing Documentation

Documentation lives in `docs/` and uses MkDocs Material.

```bash

# Install MkDocs

pip install mkdocs-material



# Serve locally

mkdocs serve



# Open http://127.0.0.1:8000

```

### Documentation Style

- Use **clear headings** and structure
- Include **code examples** where relevant
- Add **warnings** and **tips** for important information
- Keep **language simple** and accessible

## Adding Tools to Catalog

### Process

1. **Create tool entry** in `dataset/catalog.jsonl`:

```json

{

  "@type": "SoftwareSourceCode",

  "name": "ToolName",

  "description": "Tool description",

  "url": "https://github.com/user/tool",

  "license": "Apache-2.0",

  "keywords": ["segmentation", "CT"],

  "supportingData": {

    "modalities": ["CT"],

    "dimensions": ["3D"],

    "formats": ["DICOM"],

    "demo_url": "https://huggingface.co/spaces/user/tool"

  }

}

```

2. **Validate entry**:

```bash

# Check JSON syntax

python -c "import json; print(json.loads('YOUR_JSON_HERE'))"

```

3. **Update checksum**:

```bash

shasum dataset/catalog.jsonl > dataset/catalog.jsonl.sha1

```

4. **Sync catalog**:

```bash

ai_agent sync

```

5. **Test retrieval**:

```bash

ai_agent chat

# Try queries that should return your new tool

```

### Tool Criteria

Tools should:

- ✅ Be relevant to imaging analysis
- ✅ Be actively maintained
- ✅ Have clear documentation
- ✅ Preferably have a runnable demo
- ✅ Be open-source or have free tier

## Reporting Issues

### Bug Reports

Include:

- **Description** of the bug
- **Steps to reproduce**
- **Expected behavior**
- **Actual behavior**
- **Environment** (OS, Python version, etc.)
- **Logs** if available

### Feature Requests

Include:

- **Use case** for the feature
- **Proposed solution** (if you have one)
- **Alternatives considered**
- **Examples** of similar features

## Code Review Process

1. **Automated checks** run on PR (tests, linting)
2. **Maintainer review** provides feedback
3. **Address feedback** and update PR
4. **Approval** from maintainer(s)
5. **Merge** into main branch

## Release Process

Releases follow semantic versioning:

1. Update version in `pyproject.toml`
2. Update `CHANGELOG.md` with release date
3. Create git tag: `git tag v0.2.0`
4. Push tag: `git push origin v0.2.0`
5. GitHub Actions deploys documentation

## Getting Help

- **GitHub Discussions**: Ask questions
- **GitHub Issues**: Report bugs

## Code of Conduct

Be respectful and professional:

- Use welcoming and inclusive language
- Respect differing viewpoints
- Accept constructive criticism
- Focus on what's best for the community

## License

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

## Next Steps

- Review [Project Structure](structure.md)
- Learn about [Testing](testing.md)
- Read [Architecture Overview](../architecture/overview.md)