docs/api_spec.md

Moodrae - API Specification

1. Core Endpoints

POST /api/v1/analyze/text

Analyzes a pasted string of WhatsApp chat text.

• Request Body: AnalysisRequest (JSON)
• Response Body: AnalysisSuccessResponse (JSON)

POST /api/v1/analyze/file

Analyzes an uploaded WhatsApp export (.txt).

• Format: multipart/form-data
• Field: file (UploadFile)
• Response Body: AnalysisSuccessResponse (JSON)

GET /health

Health check for the backend service.

---

2. Request Schemas

AnalysisRequest

{
  "text": "The raw chat export string...",
  "options": {
    "anonymize": true
  }
}

---

3. Response Schemas (Recursive)

AnalysisSuccessResponse

{
  "status": "success",
  "data": ScoringResponse,
  "metadata": {
    "timestamp": "2024-04-02T10:00:00Z",
    "processing_time": 1.25
  }
}

ScoringResponse

{
  "overall_summary": "string",
  "overall_mood": "string",
  "participants": [ParticipantScoring],
  "segments": [SegmentScoring],
  "timeline": [{"time": "...", "sentiment": 0.5, "volume": 10, "tension": 0.2}],
  "standout_cards": [StandoutCard],
  "global_metrics": {
    "conversation_health": 0.85,
    "total_messages": 100
  }
}

ParticipantScoring

{
  "name": "Alice",
  "dominance": ScoreMetadata,
  "dry_texting": ScoreMetadata,
  "passive_aggression": ScoreMetadata,
  "main_character_energy": ScoreMetadata,
  "badges": ["string"]
}

ScoreMetadata

{
  "value": 0.7,
  "label": "High",
  "explanation": "...",
  "confidence": 0.9
}

ErrorResponse

{
  "status": "error",
  "code": "ANALYSIS_FAILED",
  "message": "Human-readable error message",
  "details": {}
}

---

4. Privacy & Cleanup Strategy

1. No Disk Storage: All uploaded content is processed in memory via byte-streams.
2. Ephemeral Lifecycle: No database persistence. Objects are garbage collected after response delivery.
3. Local-First: 100% of NLP processing occurs within the local CPU/memory space using spaCy and Transformers.
4. No External Calls: The backend is prohibited from contacting any cloud API or LLM provider.

5. Deployment / Test Plan

• Run uvicorn main:app --port 8000 --reload
• Integration tests in backend/tests/test_api_integration.py
• Benchmarking with sample WhatsApp exports (>10,000 messages) recommended.