Skip to main content

Quick Start Guide

Prerequisites​

  • Python 3.8+
  • MongoDB instance
  • Environment variables configured
  • JWT authentication service

Setup​

  1. Clone and navigate to the evaluate service:

    cd /Users/ericngo/Desktop/projects/dudu/evaluate

  2. Install dependencies:

    pip install -r requirements.txt
    # or using uv
    uv sync

  3. Configure environment variables:

    cp .env.example .env
    # Edit .env with your configuration

  4. Start the server:

    python server.py

The API will be available at http://localhost:5049

First API Call​

  1. Get a JWT token from your authentication service:

    # Use your auth service or shared auth module
    python get_jwt_token.py

  2. Test the health endpoint:

    curl http://localhost:5049/health

  3. Create an outcome:

    curl -X POST "http://localhost:5049/api/outcomes/upload" \
      -H "Authorization: Bearer <your-jwt-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "decision_id": "test_decision_123",
        "customer_id": "test_user",
        "outcome": "success - test outcome"
      }'

  4. Get statistics:

    curl -X GET "http://localhost:5049/api/stats/overall" \
      -H "Authorization: Bearer <your-jwt-token>"

Workflow Example​

1. Create Decision Outcome​

curl -X POST "http://localhost:5049/api/outcomes/upload" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "decision_456",
    "customer_id": "customer_123",
    "outcome": "success - customer satisfied with recommendation"
  }'

2. Get Decision Statistics​

curl -X GET "http://localhost:5049/api/stats/decision/decision_456" \
  -H "Authorization: Bearer <jwt-token>"
curl -X GET "http://localhost:5049/api/stats/trends?days=7" \
  -H "Authorization: Bearer <jwt-token>"

4. Compare Performance​

curl -X GET "http://localhost:5049/api/stats/comparison?limit=5" \
  -H "Authorization: Bearer <jwt-token>"

Common Use Cases​

Monitoring Recommendation Performance​

  1. Log outcomes from recommendation decisions
  2. Track success rates over time
  3. Compare different recommendation strategies
  4. Identify top-performing decision types

Quality Assurance​

  1. Monitor data completeness and consistency
  2. Track error rates and response times
  3. Analyze outcome patterns
  4. Generate performance reports

Business Intelligence​

  1. Analyze customer satisfaction trends
  2. Track decision effectiveness
  3. Monitor system performance metrics
  4. Generate executive summaries

Integration Examples​

With Recommend Service​

# After getting recommendations
recommendation_response = requests.post(
    "http://localhost:5051/api/recommend/recommend",
    headers={"Authorization": f"Bearer {token}"},
    json=request_data
)

# Log the outcome
outcome_response = requests.post(
    "http://localhost:5049/api/outcomes/upload",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "decision_id": recommendation_response.json()["decision_id"],
        "customer_id": customer_id,
        "outcome": "success" if customer_purchased else "no_purchase"
    }
)

Batch Processing​

# Process multiple outcomes
outcomes = [
    {
        "decision_id": f"decision_{i}",
        "customer_id": customer_id,
        "outcome": f"outcome_{i}"
    }
    for i in range(10)
]

for outcome in outcomes:
    response = requests.post(
        "http://localhost:5049/api/outcomes/upload",
        headers={"Authorization": f"Bearer {token}"},
        json=outcome
    )

Next Steps​

Troubleshooting​

Common Issues​

401 Unauthorized

  • Check your JWT token is valid and not expired
  • Ensure token is properly formatted in Authorization header

404 Not Found

  • Verify the endpoint URL is correct
  • Check that decision_id or outcome_id exists

500 Internal Server Error

  • Check MongoDB connection
  • Verify environment variables are set correctly
  • Check server logs for detailed error information

Debug Mode​

Enable debug logging by setting:

DEBUG=true
LOG_LEVEL=DEBUG

Health Checks​

Monitor service health:

curl http://localhost:5049/health