Resource Allocation Guide

This guide explains how to use the enhanced Resource Allocator Agent to automatically assign tasks to available developers and create GitHub issues using MongoDB as the data source.

Features

• Smart Task Assignment: Automatically assigns tasks to the best available developers based on:

  • Skill matching with task requirements
  • Developer availability (from MongoDB)
  • Performance metrics (success rate, completion time)
  • Current workload

• GitHub Integration: Automatically creates GitHub issues for assigned tasks with:

  • Detailed task descriptions
  • Acceptance criteria
  • Developer assignment
  • Proper labels and formatting

• MongoDB Integration: All data is stored and retrieved from MongoDB:

  • Project analyses
  • Tasks and assignments
  • Developer information and workload
  • Real-time updates

• Complete Workflow: End-to-end automation from project description to task assignment

Quick Start

1. Environment Setup

Make sure you have the required environment variables in your .env file:

GITHUB_TOKEN=your_github_personal_access_token
MONGO_URI=your_mongodb_connection_string
GEMINI_API_KEY=your_gemini_api_key

2. Add Developers to Database

First, add developers to your MongoDB database:

POST /developers/batch

With developer data in the request body.

3. Complete Workflow (Recommended)

Use the complete workflow endpoint for end-to-end automation:

POST /complete_workflow

This will:

• Analyze your project description using Gemini AI
• Generate tasks automatically
• Store everything in MongoDB
• Assign tasks to available developers
• Optionally create GitHub issues

API Usage

Complete Workflow (Recommended)

POST /complete_workflow

Request Body:

{
  "project_description": "Build a web application for task management with user authentication, real-time notifications, and analytics dashboard. Users should be able to create projects, assign tasks, track progress, and generate reports.",
  "repo_name": "your-username/your-repo",
  "create_github_issues": true
}

Response:

{
  "status": "success",
  "workflow_summary": {
    "analysis_id": "507f1f77bcf86cd799439011",
    "project_id": "PROJECT-12345",
    "total_tasks_created": 8,
    "tasks_assigned": 7,
    "github_issues_created": 7
  },
  "project_analysis": { ... },
  "tasks": [ ... ],
  "assignment_results": [ ... ]
}

Step-by-Step Workflow

1. Analyze Project

POST /analyze_project_gemini

Request Body:

{
  "description": "Build a web application for task management..."
}

2. Create Tasks from Analysis

POST /create_tasks_from_analysis_id

Request Body:

"507f1f77bcf86cd799439011"

3. Allocate Tasks by Project

POST /allocate_tasks_by_project

Query Parameters:

• project_id: The project ID from the analysis
• repo_name: GitHub repository (optional)
• create_github_issues: Boolean flag

Response:

{
  "assignment_results": [
    {
      "task_id": "TASK-001",
      "task_title": "Implement user authentication",
      "assigned_to": "Alice Thompson",
      "developer_id": "A193014",
      "github_username": "jayypatel18",
      "assignment_score": 0.85,
      "github_issue": {
        "status": "created",
        "issue_number": 42,
        "issue_url": "https://github.com/your-username/your-repo/issues/42"
      }
    }
  ]
}

Get Available Developers

GET /developers/available

Response:

{
  "available_developers": [
    {
      "id": "A193014",
      "name": "Alice Thompson",
      "skills": ["Python", "Django", "PostgreSQL"],
      "github_username": "jayypatel18",
      "current_tasks_count": 0,
      "performance_metrics": {
        "success_rate": 0.95,
        "avg_completion_time": 7.5
      }
    }
  ],
  "total_available": 15
}

Find Developers by Skills

POST /developers/by_skills

Request Body:

{
  "required_skills": ["Python", "React", "PostgreSQL"]
}

Get Developer Workload

GET /developers/workload

Returns detailed workload information for all developers.

How the Assignment Algorithm Works

The resource allocator uses a scoring system to find the best developer for each task:

Scoring Factors

1. Skill Match (40%): How well the developer's skills match the task requirements
2. Availability (20%): Whether the developer is currently available
3. Performance (30%): Developer's historical success rate
4. Workload (10%): Current number of assigned tasks

Assignment Process

1. Load Developers: Queries MongoDB for available developers (availability: true)
2. Calculate Scores: Computes assignment score for each developer-task pair
3. Best Match: Assigns task to developer with highest score
4. Update Database: Updates task assignment and developer workload in MongoDB
5. Create GitHub Issue: If enabled, creates issue and assigns to developer
6. Real-time Updates: All changes are immediately reflected in the database

GitHub Issue Format

When creating GitHub issues, the system generates:

## Task Description
[Task description from the task object]

## Assigned Developer
- **Name**: Alice Thompson
- **GitHub**: @jayypatel18
- **Skills**: Python, Django, PostgreSQL

## Acceptance Criteria
- JWT token implementation
- Login/register endpoints
- Unit tests with 90% coverage

## Estimated Time
16.0 hours

## Dependencies
- TASK-000: Setup project structure

---
*This issue was automatically created by the Resource Allocator Agent*

Developer Data Structure

Developers are stored in MongoDB with the following structure:

{
  "id": "A193014",
  "name": "Alice Thompson",
  "skills": ["Python", "Django", "PostgreSQL"],
  "github_username": "jayypatel18",
  "current_tasks": [],
  "availability": true,
  "performance_metrics": {
    "success_rate": 0.95,
    "avg_completion_time": 7.5
  }
}

Adding Developers to Database

POST /developers/batch

Request Body:

[
  {
    "id": "A193014",
    "name": "Alice Thompson",
    "skills": ["Python", "Django", "PostgreSQL"],
    "github_username": "alice_dev",
    "current_tasks": [],
    "availability": true,
    "performance_metrics": {
      "success_rate": 0.95,
      "avg_completion_time": 7.5
    }
  }
]

Best Practices

Task Definition

• Include clear acceptance criteria
• Use descriptive titles and descriptions
• Mention specific technologies in requirements
• Set realistic time estimates

Skill Matching

• Keep developer skills updated
• Use consistent skill naming (e.g., "JavaScript" not "JS")
• Include both technologies and methodologies

GitHub Integration

• Ensure developers have GitHub accounts
• Use consistent GitHub usernames
• Set up proper repository permissions
• Consider using labels for better organization

Troubleshooting

Common Issues

1. No developers assigned

   • Check if developers are available (availability: true) in MongoDB
   • Verify skill matching between tasks and developers
   • Ensure developers exist in the MongoDB database

2. GitHub issue creation fails

   • Verify GITHUB_TOKEN is valid and has repo permissions
   • Check repository name format (owner/repo)
   • Ensure developer GitHub usernames are correct

3. Low assignment scores

   • Review task descriptions for skill keywords
   • Update developer skill lists
   • Check performance metrics are realistic

Debugging

Enable logging to see detailed assignment information:

import logging
logging.basicConfig(level=logging.INFO)

Extending the System

Custom Scoring Algorithm

Override the calculate_assignment_score method:

class CustomResourceAllocator(ResourceAllocatorAgent):
    def calculate_assignment_score(self, task: Task, developer: Developer) -> float:
        # Your custom scoring logic here
        return custom_score

Additional Integrations

The system is designed to be extensible. You can add:

• Slack notifications
• Jira integration
• Time tracking systems
• Custom analytics

Performance Considerations

• Developer data is cached after first load
• GitHub API has rate limits (5000 requests/hour)
• Consider batching operations for large task sets
• Monitor memory usage with large developer pools

Security Notes

• Store GitHub tokens securely
• Use environment variables for sensitive data
• Implement proper access controls
• Audit assignment decisions regularly