AI-Powered Intelligent Commit-Task Linking

🤖 Overview

Upgrade from TF-IDF keyword matching to AI semantic understanding using LLM APIs (Anthropic Claude, OpenAI GPT-4).

Why AI is Better

TF-IDF (Current):

Commit: "Add JWT auth system"
Task: "Implement user authentication with JWT"
Match: 72% (keyword overlap)

AI-Powered (Enhanced):

Commit: "Add JWT auth system"
Task: "Implement user authentication with JWT"
Match: 95% ✅
Reasoning: "Commit implements JWT authentication mentioned in task.
            Code changes show token generation and validation middleware."

Key Improvements

Semantic Understanding
- Understands "Add JWT" = "Implement authentication"
- Not just keyword matching
Context Awareness
- Reads code diffs to determine intent
- Understands multi-file changes
Synonym Handling
- "Fix bug" = "Resolve issue" = "Debug problem"
- "Add feature" = "Implement functionality"
Multi-Language
- Works with any programming language
- Understands technical jargon
Explanation
- AI explains WHY commit matches task
- Helps verify correctness

🚀 Setup

1. Install Dependencies

cd docs/dashboard-2.0/poc/backend

# Install AI SDK
pip install anthropic  # For Claude
# OR
pip install openai     # For GPT-4

2. Set API Key

Option A: Environment Variable

# Anthropic Claude (recommended)
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"

# OR OpenAI GPT-4
export OPENAI_API_KEY="sk-xxx"
export AI_PROVIDER="openai"

Option B: .env File

# Create .env file
cat > backend/.env << EOF
ANTHROPIC_API_KEY=sk-ant-api03-xxx
AI_PROVIDER=anthropic
AI_CONFIDENCE_THRESHOLD=0.3
EOF

# Load in Python
pip install python-dotenv

3. Update API to Use AI Linker

Edit backend/api_v2.py:

# Add at top of file
from ai_linker import AITaskLinker

# Replace this line (around line 600):
from linkers import CommitTaskLinker

# With:
try:
    from ai_linker import AITaskLinker as CommitTaskLinker
    print("✅ AI-powered linking enabled")
except ImportError:
    from linkers import CommitTaskLinker
    print("⚠️  Using TF-IDF fallback (no AI)")

That's it! Restart API and AI linking is active.

🧪 Test AI Linking

CLI Test

cd backend

# Set API key
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"

# Test commit matching
python ai_linker.py "feat: Implement JWT authentication with RS256 signing"

Output:

🤖 Analyzing commit: feat: Implement JWT authentication with RS256 signing

✅ Found 2 matching tasks:
  Task #1091: 95.0% confidence
    Reasoning: Commit directly implements JWT authentication system mentioned in task title.
               The RS256 signing detail indicates production-ready implementation.

  Task #1093: 78.0% confidence
    Reasoning: JWT authentication is part of the security infrastructure setup mentioned in this task.

API Test

# Send commit with AI linking
curl -X POST http://localhost:5001/api/v1/git/commits \
  -H "Content-Type: application/json" \
  -d '{
    "sha": "ai-test-001",
    "message": "feat: Add JWT authentication system\n\nImplemented token generation with RS256 signing and validation middleware.",
    "author": "Hal Casteel",
    "timestamp": "2025-11-28T01:00:00Z",
    "repo_name": "dashboard-2.0-poc"
  }' | jq '.'

Response:

{
  "commit_sha": "ai-test-001",
  "links_created": 2,
  "links": [
    {
      "task_id": 1091,
      "task_title": "Implement user authentication system with JWT",
      "confidence": 0.95,
      "link_type": "ai_inferred",
      "evidence": "Commit implements JWT authentication mentioned in task",
      "ai_provider": "anthropic"
    },
    {
      "task_id": 1093,
      "task_title": "Configure security infrastructure",
      "confidence": 0.78,
      "link_type": "ai_inferred",
      "evidence": "JWT is part of security setup",
      "ai_provider": "anthropic"
    }
  ]
}

🎯 Advanced Features

1. Code Diff Analysis

AI can read code diffs to better understand commits:

from ai_linker import AITaskLinker

linker = AITaskLinker()

# Get git diff
diff = """
diff --git a/auth.py b/auth.py
+import jwt
+def generate_token(user_id):
+    return jwt.encode({'user_id': user_id}, secret, algorithm='RS256')
"""

links = linker.link_commit_to_tasks(
    commit_sha="abc123",
    commit_message="feat: Add authentication",
    commit_diff=diff  # AI analyzes code changes!
)

AI sees actual code and understands:

JWT library imported
Token generation implemented
RS256 algorithm used
Matches task more accurately

2. AI-Generated Commit Messages

Let AI write commit messages for you:

from ai_linker import AITaskLinker

linker = AITaskLinker()

# Generate commit message from task
message = linker.generate_commit_message(
    task_id=1091,
    code_diff=git_diff  # Optional: AI reads your changes
)

print(message)

Output:

feat(auth): Implement JWT authentication #1091

Added RS256 token signing and validation middleware for secure user authentication.

Features:
- Token generation with configurable expiry (default 24h)
- Validation middleware for protected routes
- Refresh token support for extended sessions
- Proper error handling for invalid/expired tokens

Closes #1091

Use in git hook:

# .git/hooks/prepare-commit-msg
TASK_ID=$(git branch --show-current | grep -oE '[0-9]+')
if [ -n "$TASK_ID" ]; then
  # Let AI generate message
  AI_MESSAGE=$(python backend/ai_linker.py --generate $TASK_ID)
  echo "$AI_MESSAGE" > "$1"
fi

3. AI Task Suggestions

AI suggests creating tasks for commits without references:

suggestion = linker.suggest_task_from_commit(
    commit_message="fix: Resolve database timeout issues",
    commit_diff=diff
)

if suggestion['should_create_task']:
    task = suggestion['suggested_task']
    print(f"Suggested task: {task['title']}")
    print(f"Description: {task['description']}")
    print(f"Complexity: {task['complexity']}")
    print(f"Priority: {task['priority']}")

Output:

{
  "should_create_task": true,
  "suggested_task": {
    "title": "Fix database connection pool timeout",
    "description": "Connection pool exhaustion causing timeouts under load. Need to increase pool size and add connection recycling.",
    "complexity": "M",
    "priority": "P1",
    "reasoning": "This is a production bug affecting system reliability"
  }
}

⚙️ Configuration

Environment Variables

# AI Provider (anthropic or openai)
AI_PROVIDER=anthropic

# API Keys
ANTHROPIC_API_KEY=sk-ant-api03-xxx
OPENAI_API_KEY=sk-xxx

# Confidence threshold (0.0-1.0)
# Lower = more matches, Higher = stricter
AI_CONFIDENCE_THRESHOLD=0.3

# Model selection
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
OPENAI_MODEL=gpt-4-turbo-preview

# Enable/disable diff analysis (costs more tokens)
AI_ANALYZE_DIFFS=true

# Max tasks to analyze per commit
AI_MAX_CANDIDATE_TASKS=100

Cost Optimization

Token Usage:

Without diff: ~~500-1000 tokens per commit (~~$0.003-$0.006)
With diff: ~~2000-4000 tokens per commit (~~$0.012-$0.024)

Best practices:

Only analyze diffs for important commits (main branch)
Cache AI results to avoid re-analyzing same commit
Use cheaper models for simple matches (claude-3-haiku)
Batch commits to reduce API calls

Example cost:

100 commits/day × $0.006 = $0.60/day = $18/month

Much cheaper than manual task linking!

📊 Comparison: TF-IDF vs AI

Example 1: Synonyms

Commit: "Refactor authentication logic" Task: "Implement user login system"

Method	Match	Confidence
TF-IDF	❌ No match	0% (no keyword overlap)
AI	✅ Matched	82% (understands synonyms)

AI Reasoning: "Refactoring authentication logic is part of implementing the login system"

Example 2: Context

Commit: "Add RS256 key generation" Task: "Secure JWT implementation"

Method	Match	Confidence
TF-IDF	❌ No match	15% (weak keyword match)
AI	✅ Matched	88% (understands context)

AI Reasoning: "RS256 is the secure algorithm for JWT token signing mentioned in task requirements"

Example 3: Multi-Task

Commit: "Update authentication and add rate limiting" Tasks:

#1091: "Implement authentication"
#1095: "Add API rate limiting"

Method	Matches	Confidence
TF-IDF	1 task	#1091: 65%
AI	2 tasks	#1091: 92%, #1095: 87%

AI Reasoning: "Commit addresses both authentication (primary) and rate limiting (secondary) tasks"

🔧 Troubleshooting

AI Not Working

Problem: API using TF-IDF fallback

Solutions:

Check API key: echo $ANTHROPIC_API_KEY
Verify SDK installed: pip show anthropic
Check API logs for errors
Test CLI: python ai_linker.py "test message"

Low Confidence Scores

Problem: AI giving low confidence (<0.5) for obvious matches

Solutions:

Lower threshold: AI_CONFIDENCE_THRESHOLD=0.2
Improve task descriptions (more detail = better matching)
Include code diffs for better context
Use more specific commit messages

High API Costs

Problem: Token usage too high

Solutions:

Disable diff analysis: AI_ANALYZE_DIFFS=false
Use cheaper model: ANTHROPIC_MODEL=claude-3-haiku-20240307
Reduce candidates: AI_MAX_CANDIDATE_TASKS=50
Only use AI for main branch commits

🚀 Next Steps

Set API key - Get Anthropic or OpenAI key
Install dependencies - pip install anthropic
Update api_v2.py - Import AITaskLinker
Restart API - API will use AI automatically
Test it - Make a commit and watch AI link it!

💡 Pro Tips

1. Branch-Based AI Strategy

# .git/hooks/post-commit
BRANCH=$(git branch --show-current)

if [[ "$BRANCH" == "main" ]]; then
  # Use AI for main branch (important commits)
  curl -X POST "$API_URL/api/v1/git/commits?use_ai=true" ...
else
  # Use TF-IDF for feature branches (cheaper)
  curl -X POST "$API_URL/api/v1/git/commits?use_ai=false" ...
fi

2. Commit Message Templates

Train your team to write AI-friendly commits:

# Good for AI
feat(auth): Implement JWT token validation middleware

Added middleware to validate JWT tokens on protected routes.
Uses RS256 algorithm with public key verification.

# Bad for AI
fix stuff

updated files

3. Review AI Links

Dashboard shows AI reasoning - review periodically:

Click task → see linked commits
Check "AI Reasoning" for each link
Unlink if AI was wrong
Improves over time with feedback

API Key: Add to .env file Cost: ~$18/month for 100 commits/day Accuracy: 85-95% vs 60-70% with TF-IDF

Ready to make your dashboard intelligently track progress! 🧠✨

🤖 Overview​

Why AI is Better​

Key Improvements​

🚀 Setup​

1. Install Dependencies​

2. Set API Key​

3. Update API to Use AI Linker​

🧪 Test AI Linking​

CLI Test​

API Test​

🎯 Advanced Features​

1. Code Diff Analysis​

2. AI-Generated Commit Messages​

3. AI Task Suggestions​

⚙️ Configuration​

Environment Variables​

Cost Optimization​

📊 Comparison: TF-IDF vs AI​

Example 1: Synonyms​

Example 2: Context​

Example 3: Multi-Task​

🔧 Troubleshooting​

AI Not Working​

Low Confidence Scores​

High API Costs​

🚀 Next Steps​

💡 Pro Tips​

1. Branch-Based AI Strategy​

2. Commit Message Templates​

3. Review AI Links​

🤖 Overview

Why AI is Better

Key Improvements

🚀 Setup

1. Install Dependencies

2. Set API Key

3. Update API to Use AI Linker

🧪 Test AI Linking

CLI Test

API Test

🎯 Advanced Features

1. Code Diff Analysis

2. AI-Generated Commit Messages

3. AI Task Suggestions

⚙️ Configuration

Environment Variables

Cost Optimization

📊 Comparison: TF-IDF vs AI

Example 1: Synonyms

Example 2: Context

Example 3: Multi-Task

🔧 Troubleshooting

AI Not Working

Low Confidence Scores

High API Costs

🚀 Next Steps

💡 Pro Tips

1. Branch-Based AI Strategy

2. Commit Message Templates

3. Review AI Links