Skip to content

DEVELOPER_GUIDE.md

Latest commit

 

History

History
357 lines (281 loc) · 7.71 KB

DEVELOPER_GUIDE.md

File metadata and controls

357 lines (281 loc) · 7.71 KB
Raw

Developer Quick Start - Groq LLM Test Generation

🚀 Quick Start (5 minutes)

1. Verify Services Are Running

# Check backend
curl http://localhost:8000/health
# Expected: {"status": "healthy"}

# Check Celery worker is active
ps aux | grep celery

2. Submit Your First Analysis

# Using curl
curl -X POST http://localhost:8000/api/v1/analysis/start \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "user_story",
    "source_data": "def add(a, b):\n    return a + b"
  }'

# Response:
# {"job_id": "xxxxx", "status": "PENDING", "created_at": "..."}

3. Check Results

curl http://localhost:8000/api/v1/analysis/xxxxx

# Wait a few seconds, then:
# Returns full analysis with generated tests

📝 API Examples

Python - Using requests

import requests
import time

# Submit analysis
response = requests.post(
    'http://localhost:8000/api/v1/analysis/start',
    json={
        'source_type': 'user_story',
        'source_data': '''
def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b
'''
    }
)

job_id = response.json()['job_id']

# Wait for completion
time.sleep(10)

# Get results
result = requests.get(f'http://localhost:8000/api/v1/analysis/{job_id}').json()

# View tests
for test in result['tests']:
    print(f"Function: {test['target_function']}")
    print(f"Test Type: {test['test_type']}")
    print(f"Generated by: {test['generated_by']}")
    print(f"Code:\n{test['content']}")

JavaScript - Using fetch

// Submit analysis
const jobResponse = await fetch('http://localhost:8000/api/v1/analysis/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source_type: 'user_story',
    source_data: `
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}
    `
  })
});

const { job_id } = await jobResponse.json();

// Wait and get results
await new Promise(resolve => setTimeout(resolve, 10000));

const resultResponse = await fetch(
  `http://localhost:8000/api/v1/analysis/${job_id}`
);
const result = await resultResponse.json();

// Display tests
result.tests.forEach(test => {
  console.log(`Function: ${test.target_function}`);
  console.log(`Generated by: ${test.generated_by}`);
  console.log(`Code:\n${test.content}`);
});

🔍 Understanding Responses

Analysis Response Structure

{
  "job_id": "8dd6c98f-9691-47e7-91c1-dde5890bbf02",
  "status": "COMPLETED",
  "structure": {
    "languages": { "python": 2 },
    "files": ["code.python"],
    "functions": [
      { "name": "add", "file": "code.python" },
      { "name": "divide", "file": "code.python" }
    ]
  },
  "edge_cases": [...],
  "tests": [
    {
      "id": "llm_test_add",
      "test_type": "comprehensive",
      "target_function": "add",
      "language": "python",
      "content": "import pytest...",
      "file_path": "tests/test_add.py",
      "generated_by": "demo"  // "groq" when API key configured
    }
  ],
  "llm_provider": "groq",
  "api_calls_made": 2
}

Test Object Fields

Field Meaning
id Unique test identifier
test_type "comprehensive" or "edge_cases"
target_function Which function this tests
language "python" or "javascript"
content The actual test code
generated_by "demo" or "groq"

🛠️ Troubleshooting

"Analysis failed" Error

Check:

# 1. Backend is running
curl http://localhost:8000/health

# 2. Celery worker is running
ps aux | grep celery

# 3. Redis is running
redis-cli ping  # Should return PONG

Tests Show "demo" Instead of "groq"

Reason: Groq API key not configured

Fix:

  1. Get API key from https://console.groq.com
  2. Update backend/.env with your key
  3. Restart backend and Celery worker

Job Hangs on "PENDING"

Reason: Celery worker not processing tasks

Fix:

# Check worker status
ps aux | grep celery

# If not running, start it
cd backend
celery -A app.workers.celery_app worker --loglevel=info

📊 Monitoring

View Generated Tests Database

# Connect to SQLite
sqlite3 test.db

# List all analyses
SELECT id, status, json_array_length(results->'tests') as test_count 
FROM analysis_jobs;

# View provider usage
SELECT 
  json_each.value->>'generated_by' as provider,
  COUNT(*) as count
FROM analysis_jobs, json_each(analysis_jobs.results, '$.tests')
GROUP BY provider;

# Exit
.exit

Monitor API Calls

Check Groq dashboard at https://console.groq.com/usage for:

  • API calls count
  • Token usage
  • Rate limit status

🎯 Production Deployment

Enable Real Groq API

  1. Get Production API Key

    # From https://console.groq.com
# Create new key with name like "production-atcg"

  2. Update Environment

    # backend/.env
GROQ_API_KEY=gsk_YOUR_PRODUCTION_KEY_HERE
LLM_PROVIDER=groq
GROQ_MODEL=llama-3.1-8b-instant

  3. Restart Services

    # Restart backend
pkill -f "uvicorn"
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 &

# Restart Celery
pkill -f "celery"
celery -A app.workers.celery_app worker --loglevel=info &

  4. Verify Integration

    # Submit test analysis and check that generated_by = "groq"
requests.get('...').json()['tests'][0]['generated_by']
# Should return: "groq"

Handle Rate Limits

Free tier limits: 30 requests/minute

For production:

  • Upgrade Groq account for higher limits
  • Implement queuing/batching
  • Add retry logic (already built-in)

📚 Integration with Your App

In Your Frontend

// In React/Next.js component
import { useState } from 'react';

export default function CodeAnalyzer() {
  const [code, setCode] = useState('');
  const [results, setResults] = useState(null);
  const [loading, setLoading] = useState(false);

  const analyzeCode = async () => {
    setLoading(true);
    
    // Submit analysis
    const jobRes = await fetch('/api/v1/analysis/start', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        source_type: 'user_story',
        source_data: code
      })
    });
    
    const { job_id } = await jobRes.json();
    
    // Poll for results
    let result = null;
    for (let i = 0; i < 60; i++) {
      const res = await fetch(`/api/v1/analysis/${job_id}`);
      if (res.status === 200) {
        result = await res.json();
        break;
      }
      await new Promise(r => setTimeout(r, 1000));
    }
    
    setResults(result);
    setLoading(false);
  };

  return (
    <div>
      <textarea 
        value={code} 
        onChange={(e) => setCode(e.target.value)}
        placeholder="Paste your code here..."
      />
      <button onClick={analyzeCode} disabled={loading}>
        {loading ? 'Analyzing...' : 'Generate Tests'}
      </button>
      
      {results && (
        <div>
          <h2>Generated Tests ({results.tests.length})</h2>
          {results.tests.map(test => (
            <div key={test.id}>
              <h3>{test.target_function}</h3>
              <p>Type: {test.test_type}</p>
              <pre>{test.content}</pre>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

📖 More Information

🆘 Need Help?

  1. Check GROQ_SETUP.md for configuration issues
  2. Review Celery logs: tail -f /tmp/celery_worker.log
  3. Check database: sqlite3 test.db
  4. Enable debug logging in orchestrator

Happy testing! 🎉