Skip to content

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

# 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

# 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

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)
  3. Update documentation if needed
  4. Update CHANGELOG.md following Keep a Changelog format

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.

# 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:
{
  "@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"
  }
}
  1. Validate entry:
# Check JSON syntax
python -c "import json; print(json.loads('YOUR_JSON_HERE'))"
  1. Update checksum:
shasum dataset/catalog.jsonl > dataset/catalog.jsonl.sha1
  1. Sync catalog:
ai_agent sync
  1. Test retrieval:
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