Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
270 lines (202 loc) · 7.03 KB

CONTRIBUTING.md

File metadata and controls

270 lines (202 loc) · 7.03 KB
Raw

Contributing to Agentic Proposal Generator

Thank you for your interest in contributing! This project welcomes contributions from everyone.

Getting Started

Prerequisites

  • Python 3.10 or higher
  • UV package manager
  • Git
  • Anthropic API key for live testing (optional - mock tests don't need it)
  • Familiarity with Claude Agent SDK and async Python

Development Setup

  1. Fork and clone the repository

    git clone https://github.com/yourusername/agentic-proposal-generator.git
cd agentic-proposal-generator

  2. Set up development environment

    # UV handles virtual environment automatically
uv sync --all-extras

  3. Configure environment (optional for mock tests)

    cp .env.example .env
# Edit .env with your Anthropic API key (only needed for live tests)

  4. Install pre-commit hooks

    uv pip install pre-commit
pre-commit install

  5. Verify setup

    # Run mock tests (fast, free, no API key needed)
uv run pytest tests/unit tests/integration -v

# Optionally run example (requires API key)
uv run python example_usage.py

Development Workflow

Code Style

  • Follow PEP 8 (enforced by Black + Ruff)
  • Use type hints for all functions
  • Add docstrings to all public methods (Google style)
  • Keep functions focused and well-named
  • Use async/await for agent operations

Testing

# Run mock tests (development - fast, free, no API)
uv run pytest tests/unit tests/integration -v

# Run with coverage
uv run pytest tests/unit tests/integration --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/unit/test_solutions_engineer.py -v

# Run live tests (⚠️ costs money!)
export ANTHROPIC_API_KEY='your-key'
uv run pytest tests/manual/ -v

Important: Always use mock tests during development. Only run live tests before major releases.

Code Quality Checks

# Format code
uv run black .
uv run isort .

# Lint
uv run ruff check . --fix

# Type check
uv run mypy src/agentic_proposal_generator

# Security scan
uv run bandit -r src/agentic_proposal_generator

# Run all checks (same as pre-commit)
pre-commit run --all-files

Making Changes

  1. Create a feature branch

    git checkout -b feature/your-feature-name

  2. Make your changes

    • Follow existing code patterns
    • Add mock tests for new features
    • Update documentation as needed
    • Test thoroughly with mock tests

  3. Commit your changes

    git add .
git commit -m "Add: brief description of changes"

    Pre-commit hooks will run automatically. If they fail:

    • Fix issues
    • git add the changes
    • Retry commit

  4. Push and create pull request

    git push origin feature/your-feature-name

Types of Contributions

Bug Reports

When filing a bug report, please include:

  • Python version
  • Operating system
  • Steps to reproduce
  • Error messages and stack trace
  • Sample transcript (if relevant)
  • Expected vs actual behavior

Feature Requests

For feature requests, please:

  • Describe the use case
  • Explain why this would be valuable
  • Provide examples if possible
  • Consider impact on existing functionality
  • Think about backwards compatibility

Code Contributions

Areas where we welcome contributions:

  • Bug fixes
  • Performance improvements
  • Documentation improvements
  • New agent capabilities
  • Additional output formats
  • Enhanced error handling
  • Test coverage improvements
  • Cost optimization features

Code Guidelines

Architecture

The project uses a 5-agent multi-specialist system:

  1. SolutionsEngineerAgent - Extracts requirements
  2. SolutionArchitectAgent - Designs technical solution
  3. CommercialAnalystAgent - Creates pricing & ROI
  4. ProposalWriterAgent - Synthesizes final proposal
  5. QualityReviewerAgent - Reviews and approves

Agents run in parallel where possible (phases 1-3) for speed.

Key Principles

  • Parallel Execution - Run independent agents concurrently
  • Event-Driven - Emit events for progress tracking
  • Cost Optimization - Use Haiku for extraction, Sonnet for creative tasks
  • Type Safety - Use type hints and Pydantic models
  • Testing - Mock tests for development, live tests for validation
  • Human-in-the-Loop - Support human review and revisions

Adding New Features

Adding a New Agent

  1. Create agent class in src/agentic_proposal_generator/agents/
  2. Create agent definition in .claude/agents/[name].md
  3. Add to __init__.py exports
  4. Update orchestrator to include agent
  5. Add mock response in tests/fixtures/mock_responses.py
  6. Create unit tests in tests/unit/test_[agent_name].py
  7. Update integration tests if needed
  8. Update documentation

Adding a New Feature

  1. Analysis Phase - Understand existing codebase
  2. Design Phase - Plan how feature fits in
  3. Mock First - Add mock data/responses
  4. Implementation - Write clean, tested code
  5. Testing - Add comprehensive unit/integration tests
  6. Documentation - Update relevant docs
  7. Validation - Test with live API (sparingly)

Documentation

When making changes that affect user-facing functionality:

  1. Update README.md - For feature changes
  2. Update HUMAN_REVIEW.md - For review workflow changes
  3. Add docstrings - For new classes/functions

Pull Request Process

  1. Fill out the PR template completely
  2. Reference related issues using keywords like "Fixes #123"
  3. Provide clear description of what changed and why
  4. Include test results showing all tests pass
  5. Update documentation as needed
  6. Ensure CI passes (GitHub Actions will run automatically)

PR Checklist

  • Code follows project style guidelines (Black, isort, ruff)
  • Self-review completed
  • Mock tests added for new features
  • All tests pass (pytest tests/unit tests/integration)
  • Documentation updated
  • No API keys or secrets in commits
  • Backwards compatibility considered
  • Type hints added for new functions
  • Pre-commit hooks pass

Agent Prompt Guidelines

When modifying agent prompts in .claude/agents/*.md:

  1. Be Specific - Clear role and expertise
  2. Structured Output - Define exact format expected
  3. Examples - Show good vs bad outputs
  4. Constraints - Specify limits (token count, format rules)
  5. Quality Standards - Define what "good" looks like
  6. Test Changes - Verify with mock tests first

Getting Help

  • Questions? Open a Discussion on GitHub
  • Stuck? Check existing Issues
  • Want to chat? Start a Discussion
  • Security Issue? See SECURITY.md

Recognition

Contributors will be acknowledged in:

  • Release notes
  • Contributors section (planned)
  • Git commit history
  • Pull request comments

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on the code, not the person
  • Help others learn and grow
  • Follow GitHub's Community Guidelines

Thank you for helping make Agentic Proposal Generator better! 🎉