API_REFERENCE.md

Debatra AI Service - API Reference

Complete API reference for the AI/NLP microservice.

Base URL

http://localhost:8000

---

🏥 Health Check

GET /

Service information.

Response:

{
  "service": "Debatra AI Service",
  "status": "running",
  "version": "1.0.0"
}

GET /api/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "ai-nlp",
  "timestamp": 1234567890.123
}

---

🎤 Speech-to-Text

POST /api/speech-to-text

Convert audio file to text transcript.

Request:

• Content-Type: multipart/form-data
• Body:
  • file (required): Audio file (WAV, MP3, OGG)
  • debateId (optional): Debate ID
  • userId (optional): User ID

Response:

{
  "success": true,
  "transcript": "I believe that artificial intelligence will revolutionize...",
  "processingTime": 1.23,
  "debateId": "debate-id",
  "userId": "user-id"
}

Example (curl):

curl -X POST http://localhost:8000/api/speech-to-text \
  -F "file=@audio.wav" \
  -F "debateId=debate-123" \
  -F "userId=user-456"

---

📊 Argument Analysis

POST /api/analyze-argument

Analyze argument and provide scores.

Request Body:

{
  "transcript": "I believe that AI will create more jobs...",
  "topic": "AI and employment",
  "debateId": "debate-123"
}

Response:

{
  "success": true,
  "analysis": {
    "clarity": 88.5,
    "logic": 82.3,
    "evidence": 75.0,
    "persuasiveness": 90.2,
    "overallScore": 84.0
  },
  "processingTime": 1.15
}

Example (curl):

curl -X POST http://localhost:8000/api/analyze-argument \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "Your argument here...",
    "topic": "Debate topic"
  }'

---

💬 Rebuttal Generation

POST /api/generate-rebuttal

Generate AI rebuttal to opponent's argument.

Request Body:

{
  "transcript": "AI will replace all human jobs",
  "topic": "AI and employment",
  "opponentArgument": "AI creates new opportunities"
}

Response:

{
  "success": true,
  "rebuttal": "While automation does create new opportunities, we cannot ignore...",
  "reasoning": "Generated based on argument analysis and topic context",
  "confidence": 0.87,
  "processingTime": 1.45
}

Example (curl):

curl -X POST http://localhost:8000/api/generate-rebuttal \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "Opponent argument...",
    "topic": "Topic name"
  }'

---

🔊 Text-to-Speech

POST /api/text-to-speech

Convert text to speech audio.

Request Body:

{
  "text": "This is the text to convert to speech.",
  "voice": "default"
}

Response:

{
  "success": true,
  "audioUrl": "/api/audio/tts_1234567890_5678.wav",
  "audioBase64": "bW9ja19hdWRpb19kYXRh",
  "duration": 2.5,
  "processingTime": 1.02
}

Available Voices:

• default
• male
• female
• neutral

Example (curl):

curl -X POST http://localhost:8000/api/text-to-speech \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test.",
    "voice": "default"
  }'

---

📝 Comprehensive Feedback

POST /api/generate-feedback

Generate complete feedback including scores, strengths, improvements, and suggestions.

Request Body:

{
  "transcript": "User's argument transcript...",
  "debateId": "debate-123",
  "userId": "user-456",
  "topic": "Debate topic"
}

Response:

{
  "success": true,
  "scores": {
    "clarity": 88.5,
    "logic": 82.3,
    "evidence": 75.0,
    "persuasiveness": 90.2
  },
  "overallScore": 84.0,
  "feedback": {
    "strengths": [
      "Excellent clarity in your argument presentation",
      "Strong logical reasoning and structure"
    ],
    "improvements": [
      "Could use more statistical data to strengthen arguments",
      "Consider addressing counterarguments more directly"
    ]
  },
  "suggestions": [
    "Practice with more complex topics to improve logical reasoning",
    "Study successful debate techniques from professional debaters"
  ],
  "processingTime": 1.85
}

Example (curl):

curl -X POST http://localhost:8000/api/generate-feedback \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "User argument...",
    "debateId": "debate-123",
    "userId": "user-456",
    "topic": "Topic"
  }'

---

🔄 Combined Processing

POST /api/process-audio

Complete pipeline: STT → Analysis → Feedback.

Request:

• Content-Type: multipart/form-data
• Body:
  • file (required): Audio file
  • debateId (optional): Debate ID
  • userId (optional): User ID
  • topic (optional): Debate topic

Response:

{
  "success": true,
  "transcript": "User's speech transcript...",
  "analysis": {
    "clarity": 88.5,
    "logic": 82.3,
    "evidence": 75.0,
    "persuasiveness": 90.2,
    "overallScore": 84.0
  },
  "scores": {
    "clarity": 88.5,
    "logic": 82.3,
    "evidence": 75.0,
    "persuasiveness": 90.2
  },
  "feedback": {
    "strengths": [...],
    "improvements": [...]
  },
  "suggestions": [...],
  "processingTime": 2.45
}

Example (curl):

curl -X POST http://localhost:8000/api/process-audio \
  -F "file=@audio.wav" \
  -F "debateId=debate-123" \
  -F "userId=user-456" \
  -F "topic=AI and employment"

---

🔍 Analyze (Backend Integration)

POST /api/analyze

Analyze transcript and return scores/feedback. Used by backend.

Request Body:

{
  "transcript": "User's argument...",
  "debateId": "debate-123",
  "userId": "user-456",
  "topic": "Debate topic"
}

Response:

{
  "success": true,
  "scores": {
    "clarity": 88.5,
    "logic": 82.3,
    "evidence": 75.0,
    "persuasiveness": 90.2
  },
  "overallScore": 84.0,
  "feedback": {
    "strengths": [...],
    "improvements": [...]
  },
  "suggestions": [...],
  "processingTime": 1.65
}

---

📊 Scoring System

Clarity (0-100)

• Sentence structure and readability
• Average sentence length
• Clear organization
• Repetition penalty

Logic (0-100)

• Reasoning indicators
• Cause-effect relationships
• Counterargument consideration
• Logical flow

Evidence (0-100)

• Data and statistics usage
• Research citations
• Examples and case studies
• Supporting information

Persuasiveness (0-100)

• Persuasive language
• Emotional appeal
• Call to action
• Impact and engagement

Overall Score

Weighted average:

• Clarity: 25%
• Logic: 30%
• Evidence: 25%
• Persuasiveness: 20%

---

⚡ Performance

• Response Time: All endpoints respond in < 3 seconds
• Concurrent Requests: Handles multiple requests simultaneously
• Mock Implementation: Fast responses for development
• Production Ready: Easy to swap with real AI models

---

🚨 Error Responses

All errors follow this format:

{
  "detail": "Error message here"
}

Status Codes:

• 400 - Bad Request (validation errors)
• 422 - Unprocessable Entity (invalid data)
• 500 - Internal Server Error

---

📝 Notes

• All timestamps are Unix timestamps
• Processing times are in seconds
• Audio files are temporarily stored and cleaned up
• Mock implementations for fast development
• Easy to replace with real AI services

---

🔗 Integration Example

Python

import requests

response = requests.post('http://localhost:8000/api/analyze-argument', json={
    'transcript': 'Your argument here...',
    'topic': 'Debate topic'
})

data = response.json()
print(f"Clarity: {data['analysis']['clarity']}")

JavaScript/Node.js

const axios = require('axios');

const response = await axios.post('http://localhost:8000/api/analyze-argument', {
  transcript: 'Your argument here...',
  topic: 'Debate topic'
});

console.log(response.data.analysis);

Backend Integration

// In backend/services/aiService.js
const response = await axios.post(`${AI_SERVICE_URL}/api/analyze`, {
  transcript: user_transcript,
  debateId: debate_id,
  userId: user_id,
  topic: debate_topic
});