adopt-a-street/backend/AI_SERVICE.md

AI Service Documentation

Overview

The AI Service provides intelligent task suggestions for street maintenance using OpenAI's GPT models. It analyzes street conditions, historical data, weather patterns, and community priorities to generate contextually relevant and actionable maintenance tasks.

Features

• Context-Aware Suggestions: Generates tasks based on street name, location, and past maintenance history
• Weather Integration: Considers current weather conditions for appropriate task suggestions
• Community Priorities: Aligns suggestions with community goals and priorities
• Fallback Mode: Automatically falls back to high-quality mock suggestions if OpenAI API is unavailable
• Graceful Degradation: Works without API key configuration, providing mock data with warnings

Configuration

Environment Variables

# Required for AI features
OPENAI_API_KEY=sk-your-api-key-here

# Optional - defaults to gpt-3.5-turbo
OPENAI_MODEL=gpt-3.5-turbo

Available Models:

• gpt-3.5-turbo (default) - Fast, cost-effective, good for most use cases
• gpt-4 - More advanced reasoning, higher quality suggestions
• gpt-4-turbo-preview - Latest GPT-4 with improved performance

Cost Considerations

• gpt-3.5-turbo: ~$0.001-0.002 per request (typical task suggestion)
• gpt-4: ~$0.03-0.06 per request
• Each task suggestion request typically uses 500-1000 tokens

API Endpoints

Check AI Service Status

GET /api/ai/status

Returns the current status of the AI service.

Headers:

x-auth-token: <jwt-token>

Response:

{
  "success": true,
  "data": {
    "configured": true,
    "model": "gpt-3.5-turbo",
    "status": "active"
  }
}

Get Task Suggestions

GET /api/ai/task-suggestions

Generate AI-powered task suggestions for street maintenance.

Headers:

x-auth-token: <jwt-token>

Query Parameters:

• streetId (optional, string): ID of the specific street to get suggestions for
• count (optional, integer): Number of suggestions to generate (1-10, default: 5)

Response:

{
  "success": true,
  "data": [
    {
      "street": "Main Street",
      "description": "Remove litter from sidewalk",
      "details": "Improves neighborhood appearance and prevents storm drain blockage.",
      "estimatedTime": 30,
      "difficulty": "easy",
      "priority": "medium",
      "source": "ai"
    }
  ],
  "meta": {
    "source": "ai",
    "count": 5,
    "aiConfigured": true
  }
}

Response (without API key):

{
  "success": true,
  "data": [...],
  "meta": {
    "source": "mock",
    "count": 5,
    "aiConfigured": false
  },
  "warning": "OpenAI API not configured. Returning mock suggestions. Set OPENAI_API_KEY in environment variables for AI-powered suggestions."
}

Service Usage

Import the Service

const aiService = require('./services/aiService');

Generate Task Suggestions

const suggestions = await aiService.generateTaskSuggestions({
  streetName: "Main Street",
  location: {
    type: "Point",
    coordinates: [-122.4194, 37.7749]
  },
  pastTasks: [
    "Remove graffiti from wall",
    "Clear storm drains"
  ],
  weather: {
    condition: "Partly cloudy",
    description: "Clear with mild temperatures",
    temperature: 72
  },
  communityPriorities: [
    "Safety improvements",
    "Environmental sustainability"
  ],
  numberOfSuggestions: 5
});

Check Service Availability

if (aiService.isAvailable()) {
  // Use AI-powered suggestions
} else {
  // Use mock suggestions or alternative logic
}

Get Service Status

const status = aiService.getStatus();
// Returns: { configured: boolean, model: string, status: string }

Suggestion Structure

Each task suggestion includes:

• street (string): Name of the street
• description (string): Brief, actionable task description (2-8 words)
• details (string): Explanation of why the task is important (1 sentence)
• estimatedTime (number): Estimated completion time in minutes
• difficulty (string): Task difficulty - "easy", "moderate", or "hard"
• priority (string): Task priority - "low", "medium", or "high"
• source (string): Source of suggestion - "ai" or "mock"

Prompt Engineering

The AI service uses carefully crafted prompts to generate high-quality suggestions:

1. Context Building: Includes street name, location, and relevant historical data
2. Past Tasks Analysis: Avoids suggesting recently completed tasks
3. Weather Awareness: Suggests weather-appropriate activities
4. Community Alignment: Prioritizes tasks aligned with community goals
5. Safety Focus: Emphasizes tasks safe for volunteers without specialized equipment
6. Structured Output: Requests JSON format with specific fields

Error Handling

The service implements comprehensive error handling:

1. API Failures: Automatically falls back to mock suggestions
2. Timeout Protection: 10-second timeout on API requests
3. Response Parsing: Handles various response formats (including markdown code blocks)
4. Validation: Ensures all suggestions have required fields
5. Logging: Detailed error logging for debugging

Testing

Run the AI service tests:

npm test -- __tests__/routes/ai.test.js

Test coverage includes:

• Service status endpoint
• Task suggestion generation (with and without street ID)
• Input validation
• Mock mode functionality
• Error handling and fallbacks
• Service integration tests

Best Practices

1. Cache Suggestions: Consider caching suggestions for frequently requested streets
2. Rate Limiting: Implement rate limiting to control API costs
3. Batch Processing: Generate suggestions for multiple streets in batches when possible
4. Monitor Usage: Track OpenAI API usage and costs
5. Fallback Strategy: Always have mock suggestions available as fallback
6. User Feedback: Collect feedback on suggestion quality to improve prompts

Troubleshooting

Issue: "OpenAI API not configured" warning

Solution: Set OPENAI_API_KEY environment variable with your OpenAI API key.

Issue: Suggestions are not contextual

Solution: Ensure you're passing street details, location, and past tasks to the service.

Issue: API timeout errors

Solution: Check network connectivity to OpenAI API. The service will automatically fall back to mock suggestions.

Issue: High API costs

Solution:

• Use gpt-3.5-turbo instead of gpt-4
• Implement caching for frequently requested streets
• Add rate limiting to the endpoint
• Reduce numberOfSuggestions parameter

Future Enhancements

Potential improvements to the AI service:

• Integration with real-time weather APIs
• Machine learning on task completion rates
• Seasonal task suggestions
• User preference learning
• Image analysis for street condition assessment
• Multi-language support
• Integration with city planning APIs
• Automated task prioritization based on urgency

Support

For issues or questions:

• Check logs at backend/server.log
• Review error messages in the response
• Ensure environment variables are correctly set
• Verify OpenAI API key is valid and has sufficient credits