Skip to main content

Quick Start: Hybrid AI + TF-IDF Commit-Task Linking

✅ Setup Complete!​

Your Dashboard 2.0 is now configured with hybrid intelligent commit-task linking:

  • ✅ AI Linking - Semantic understanding using Claude 3.5 Sonnet
  • ✅ TF-IDF Fallback - Keyword matching when AI unavailable
  • ✅ Automatic Hooks - Universal git hook for all repos
  • ✅ API Key - Using your existing ~/.hal-mac-os-anthropic.key

🎯 How It Works​

Hybrid Strategy​

  1. AI First - Uses Claude to semantically match commits to tasks
  2. TF-IDF Fallback - If AI fails, uses keyword matching
  3. Result Merging - Combines both methods (70% AI + 30% TF-IDF)
  4. Transparent Tracking - Each link shows which method was used

Confidence Scores​

  • 1.0 (100%) - Explicit reference (e.g., #TASK-123)
  • 0.7-0.95 - AI semantic match with high confidence
  • 0.5-0.7 - AI semantic match with medium confidence
  • 0.3-0.5 - TF-IDF keyword match or AI low confidence
  • 0.0-0.3 - Not stored (below threshold)

🚀 Next Steps​

1. Install Hooks in Your Repositories​

Run the automatic installer:

cd /Users/halcasteel/PROJECTS/coditect-rollout-master/docs/dashboard-2.0/poc
./install-hooks.sh

Interactive Menu Options:

  • Option 1: Install in all repos (search from directory)
  • Option 2: Install in current repo only
  • Option 3: Setup global template (auto-install in new repos)
  • Option 4: Configure settings
  • Option 5: Uninstall hooks
  • Option 6: Test hook in current repo

Command-Line Mode:

# Install in all repos under ~/Projects
./install-hooks.sh --install ~/Projects

# Install in current repo
./install-hooks.sh --install-current

# Setup global template
./install-hooks.sh --setup-template

# Uninstall all hooks
./install-hooks.sh --uninstall ~/Projects

2. Test the System​

Make a test commit:

cd /path/to/your/repo

# Make a change
echo "test" >> README.md

# Commit with task reference
git add .
git commit -m "feat: Add hybrid linking system #TASK-1091"

# Hook will automatically:
# 1. Extract commit metadata
# 2. Send to Dashboard API
# 3. AI will analyze and link to tasks
# 4. Show confirmation: "✅ Dashboard: Linked to 1 task(s)"

3. View Results in Dashboard​

Open Dashboard: http://localhost:8082

You'll see:

  • Task cards show linked commits
  • Commit cards show which tasks they affect
  • Confidence scores and linking method (AI/TF-IDF/hybrid)
  • AI reasoning for each link (if verbose mode enabled)

📊 Configuration Files​

Backend Configuration (.env)​

/Users/halcasteel/PROJECTS/coditect-rollout-master/docs/dashboard-2.0/poc/backend/.env

Key settings:

ANTHROPIC_API_KEY=sk-ant-api03-xxx  # Your API key
AI_PROVIDER=anthropic
AI_MODEL=claude-3-5-sonnet-20241022
AI_CONFIDENCE_THRESHOLD=0.3          # Lower = more matches
MERGE_AI_TFIDF=true                  # Combine both methods

Hook Configuration (~/.dashboard-hooks.conf)​

DASHBOARD_API_URL="http://localhost:5001/api/v1/git/commits"
DASHBOARD_LINK_METHOD="hybrid"
DASHBOARD_HOOK_ENABLED="true"
DASHBOARD_HOOK_VERBOSE="false"      # Set to "true" for debug info

🔧 Advanced Usage​

Test Linking Without Committing​

cd backend
source venv/bin/activate

# Test AI linking
python3 hybrid_linker.py "feat: Implement JWT authentication with RS256 signing"

Change Linking Strategy​

Edit .env:

# Use only AI (no TF-IDF fallback)
MERGE_AI_TFIDF=false

# Use only TF-IDF (no AI)
AI_ENABLED=false

# Adjust sensitivity
AI_CONFIDENCE_THRESHOLD=0.5  # Stricter (fewer matches)
AI_CONFIDENCE_THRESHOLD=0.2  # Looser (more matches)

Per-Repo Configuration​

Override global settings in specific repos:

cd /path/to/repo

# Set custom API URL
git config --local dashboard.apiUrl "https://dashboard.example.com/api/v1/git/commits"

# Use only AI (no fallback)
git config --local dashboard.linkMethod "ai"

# Use only TF-IDF (no AI)
git config --local dashboard.linkMethod "tfidf"

# Disable hook temporarily
git config --local dashboard.enabled "false"

💰 Cost Monitoring​

Expected Costs:

  • ~$0.003-0.006 per commit (without code diff)
  • ~$0.012-0.024 per commit (with code diff analysis)
  • ~$18/month for 100 commits/day (reasonable development pace)

Monitor Usage:

  • View token usage in Anthropic Console: https://console.anthropic.com
  • Set up billing alerts to avoid surprises
  • Use MERGE_AI_TFIDF=false to reduce costs (AI only, no extra TF-IDF processing)

🐛 Troubleshooting​

Hook Not Triggering​

# Verify hook is installed
ls -la .git/hooks/post-commit

# Test hook manually
.git/hooks/post-commit

# Check hook is executable
chmod +x .git/hooks/post-commit

AI Not Working​

# Check API key
cat ~/.hal-mac-os-anthropic.key

# Verify backend configuration
cat backend/.env | grep ANTHROPIC

# Test AI directly
cd backend
source venv/bin/activate
python3 ai_linker.py "test commit message"

Common causes:

  1. No matching tasks - Create tasks in Dashboard first
  2. Below confidence threshold - Lower AI_CONFIDENCE_THRESHOLD in .env
  3. AI API issue - Check Anthropic Console for errors
  4. TF-IDF fallback used - Check task titles match commit keywords

Debug:

# Enable verbose mode
export DASHBOARD_HOOK_VERBOSE=true
git commit -m "test message"
# Shows detailed AI reasoning

API Server Not Running​

# Start API server
cd backend
source venv/bin/activate
python3 api_v2.py

# Verify running
curl http://localhost:5001/api/v1/health

📚 Documentation​

🎉 You're Ready!​

Your hybrid intelligent linking system is fully operational:

  1. ✅ Backend configured with your API key
  2. ✅ Hybrid linker tested and working
  3. ✅ Universal git hook ready to deploy
  4. ✅ Automatic installer available

Next: Install hooks in your repos and start committing with intelligent task linking!

cd /Users/halcasteel/PROJECTS/coditect-rollout-master/docs/dashboard-2.0/poc
./install-hooks.sh

Happy coding! 🚀