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:**
```json
{
  "service": "Debatra AI Service",
  "status": "running",
  "version": "1.0.0"
}
```

### GET `/api/health`
Health check endpoint.

**Response:**
```json
{
  "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:**
```json
{
  "success": true,
  "transcript": "I believe that artificial intelligence will revolutionize...",
  "processingTime": 1.23,
  "debateId": "debate-id",
  "userId": "user-id"
}
```

**Example (curl):**
```bash
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:**
```json
{
  "transcript": "I believe that AI will create more jobs...",
  "topic": "AI and employment",
  "debateId": "debate-123"
}
```

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

**Example (curl):**
```bash
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:**
```json
{
  "transcript": "AI will replace all human jobs",
  "topic": "AI and employment",
  "opponentArgument": "AI creates new opportunities"
}
```

**Response:**
```json
{
  "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):**
```bash
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:**
```json
{
  "text": "This is the text to convert to speech.",
  "voice": "default"
}
```

**Response:**
```json
{
  "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):**
```bash
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:**
```json
{
  "transcript": "User's argument transcript...",
  "debateId": "debate-123",
  "userId": "user-456",
  "topic": "Debate topic"
}
```

**Response:**
```json
{
  "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):**
```bash
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:**
```json
{
  "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):**
```bash
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:**
```json
{
  "transcript": "User's argument...",
  "debateId": "debate-123",
  "userId": "user-456",
  "topic": "Debate topic"
}
```

**Response:**
```json
{
  "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:

```json
{
  "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
```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
```javascript
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
```javascript
// 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
});
```