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

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

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

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

### Verify Device

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

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

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

### List Devices

```http
GET /api/devices
Authorization: Bearer <token>
```

### Deactivate Device

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

---

## Sync Endpoints

### Sync Messages

```http
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

```http
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

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

**Response:**
```json
{
  "conversations": [...],
  "total": 100,
  "page": 1,
  "pageSize": 20
}
```

### Get Conversation Messages

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

---

## Response Generation Endpoints

### Generate Response

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

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

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

### Response Action (Accept/Reject/Edit)

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

{
  "action": "accept"
}
```

Or with edit:

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

Or with rejection:

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

---

## Training Endpoints

### List Training Samples

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

### Start Training Job

```http
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

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

**Response:**
```json
{
  "job": {
    "id": "uuid",
    "status": "training",
    "progress": 45.0,
    "error": null
  }
}
```

### Cancel Training Job

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

---

## ML Service API (FastAPI - Port 8100)

### Health Check

```http
GET /health
```

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

### Synchronous Generation

```http
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:**
```json
{
  "response": "I'm doing great, thanks for asking!",
  "confidence": 0.82,
  "model_version": "ministral-3b-instruct",
  "tokens_used": 12,
  "cached": false
}
```

### Asynchronous Generation

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

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

**Response:**
```json
{
  "job_id": "uuid",
  "status": "queued"
}
```

### Check Async Job Status

```http
GET /generate/status/:job_id
```

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

```http
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

```http
GET /training/status/:job_id
```

### Cancel Training

```http
POST /training/cancel/:job_id
```

### Reload Model

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

### Clear Cache

```http
DELETE /cache?pattern=*
```

**Response:**
```json
{
  "invalidated": 42
}
```

---

## Error Responses

All endpoints return errors in this format:

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