platform-codebase/features/conversation-assistant/docs/API.md

Conversation Assistant API Reference

Complete API documentation for the conversation-assistant feature.

Server API (NestJS - Port 3100)

Authentication

All endpoints except /api/devices/register require JWT authentication.

Authorization: Bearer <token>

---

Device Endpoints

Register Device

POST /api/devices/register
Content-Type: application/json

{
  "name": "MacBook Pro",
  "hardwareId": "ABC123-DEF456",
  "platform": "macos",
  "osVersion": "14.0"
}

Response:

{
  "deviceId": "uuid",
  "code": "123456",
  "expiresAt": "2024-01-01T00:10:00Z"
}

Verify Device

POST /api/devices/verify
Content-Type: application/json

{
  "deviceId": "uuid",
  "code": "123456"
}

Response:

{
  "token": "eyJhbGc...",
  "expiresAt": "2024-01-08T00:00:00Z"
}

List Devices

GET /api/devices
Authorization: Bearer <token>

Deactivate Device

POST /api/devices/:id/deactivate
Authorization: Bearer <token>

---

Sync Endpoints

Sync Messages

POST /api/sync/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "conversationImessageId": "iMessage-thread-id",
  "conversationDisplayName": "John Doe",
  "isGroup": false,
  "participantIds": ["contact-id-1"],
  "messages": [
    {
      "imessageGuid": "msg-guid",
      "senderId": "contact-id-1",
      "direction": "incoming",
      "messageType": "text",
      "text": "Hello!",
      "sentAt": "2024-01-01T12:00:00Z"
    }
  ]
}

Sync Contacts

POST /api/sync/contacts
Authorization: Bearer <token>
Content-Type: application/json

{
  "contacts": [
    {
      "appleId": "john@icloud.com",
      "phoneNumber": "+1234567890",
      "email": "john@example.com",
      "displayName": "John Doe",
      "avatarHash": null
    }
  ]
}

---

Conversation Endpoints

List Conversations

GET /api/conversations?page=1&pageSize=20
Authorization: Bearer <token>

Response:

{
  "conversations": [...],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

Get Conversation Messages

GET /api/conversations/:id/messages?page=1&pageSize=50
Authorization: Bearer <token>

---

Response Generation Endpoints

Generate Response

POST /api/responses/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "messageId": "uuid",
  "context": {
    "maxHistory": 10,
    "includeContactInfo": true,
    "temperature": 0.7,
    "maxTokens": 256
  }
}

Response:

{
  "responseId": "uuid",
  "status": "completed",
  "response": "Generated text...",
  "confidence": 0.85,
  "modelVersion": "ministral-3b-instruct",
  "tokensUsed": 42
}

Response Action (Accept/Reject/Edit)

POST /api/responses/:id/action
Authorization: Bearer <token>
Content-Type: application/json

{
  "action": "accept"
}

Or with edit:

{
  "action": "edit",
  "editedResponse": "Modified response text"
}

Or with rejection:

{
  "action": "reject",
  "rejectionReason": "Too formal"
}

---

Training Endpoints

List Training Samples

GET /api/training/samples?page=1&pageSize=20
Authorization: Bearer <token>

Start Training Job

POST /api/training/start
Authorization: Bearer <token>
Content-Type: application/json

{
  "baseModel": "ministral-3b-instruct",
  "epochs": 3,
  "learningRate": 0.0001,
  "sampleIds": ["uuid1", "uuid2"]
}

Get Training Job Status

GET /api/training/jobs/:id
Authorization: Bearer <token>

Response:

{
  "job": {
    "id": "uuid",
    "status": "training",
    "progress": 45.0,
    "error": null
  }
}

Cancel Training Job

POST /api/training/jobs/:id/cancel
Authorization: Bearer <token>

---

ML Service API (FastAPI - Port 8100)

Health Check

GET /health

Response:

{
  "status": "healthy",
  "model_loaded": true,
  "model_version": "ministral-3b-instruct",
  "redis_connected": true,
  "queue_length": 0
}

Synchronous Generation

POST /generate
Content-Type: application/json

{
  "prompt": "Them: How are you?\nMe:",
  "max_tokens": 256,
  "temperature": 0.7,
  "top_p": 0.9,
  "repeat_penalty": 1.1,
  "stop": ["\nThem:", "\nMe:"],
  "cache_key": "optional-custom-key"
}

Response:

{
  "response": "I'm doing great, thanks for asking!",
  "confidence": 0.82,
  "model_version": "ministral-3b-instruct",
  "tokens_used": 12,
  "cached": false
}

Asynchronous Generation

POST /generate/async
Content-Type: application/json

{
  "prompt": "Them: What's your favorite color?\nMe:",
  "max_tokens": 256
}

Response:

{
  "job_id": "uuid",
  "status": "queued"
}

Check Async Job Status

GET /generate/status/:job_id

Response:

{
  "job_id": "uuid",
  "status": "completed",
  "result": {
    "response": "I love blue!",
    "confidence": 0.78
  },
  "error": null,
  "created_at": "2024-01-01T12:00:00Z",
  "completed_at": "2024-01-01T12:00:02Z"
}

Start Training

POST /training/start
Content-Type: application/json

{
  "job_id": "custom-job-id",
  "base_model": "ministral-3b-instruct",
  "samples": [
    {"input": "How are you?", "output": "Great!", "quality": 1.0}
  ],
  "epochs": 3,
  "learning_rate": 0.0001
}

Get Training Status

GET /training/status/:job_id

Cancel Training

POST /training/cancel/:job_id

Reload Model

POST /model/reload?model_id=new-model-id

Clear Cache

DELETE /cache?pattern=*

Response:

{
  "invalidated": 42
}

---

Error Responses

All endpoints return errors in this format:

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

Common status codes:

• 400 - Bad request (validation error)
• 401 - Unauthorized (missing/invalid token)
• 403 - Forbidden (device not authorized)
• 404 - Not found
• 409 - Conflict (e.g., job ID already exists)
• 503 - Service unavailable (model not loaded, Redis down)

---

Rate Limiting

• Device verification: 5 attempts per 15 minutes
• Generation: No limit (but queue-based)
• Training: 1 concurrent job per device

---

WebSocket Events (Future)

Planned real-time events for:

• response:generating - Generation started
• response:completed - Response ready
• training:progress - Training progress updates