📡 API Reference

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Training job queued successfully"
}

{
  "job_id": "job-12345-abcde",
  "metrics": [
    {
      "epoch": 1,
      "step": 100,
      "loss": 2.45,
      "learning_rate": 0.0001,
      "grad_norm": 1.23,
      "timestamp": "2025-01-15T10:30:00Z"
    },
    {
      "epoch": 1,
      "step": 200,
      "loss": 2.12,
      "learning_rate": 0.0001,
      "grad_norm": 1.18,
      "timestamp": "2025-01-15T10:35:00Z"
    }
  ],
  "total_points": 2
}

{
  "job_id": "job-12345-abcde",
  "logs": [
    "[2025-01-15 10:30:00] Loading model gpt2...",
    "[2025-01-15 10:30:05] Model loaded successfully",
    "[2025-01-15 10:30:10] Starting training...",
    "[2025-01-15 10:30:15] Epoch 1/3 - Step 100 - Loss: 2.45"
  ],
  "total_lines": 4
}

{
  "job_id": "job-12345-abcde",
  "checkpoints": [
    {
      "path": "checkpoint-1000",
      "epoch": 1,
      "step": 1000,
      "eval_loss": 1.85,
      "train_loss": 1.92,
      "size_mb": 245.7,
      "created_at": "2025-01-15T10:40:00Z"
    },
    {
      "path": "checkpoint-2000",
      "epoch": 2,
      "step": 2000,
      "eval_loss": 1.23,
      "train_loss": 1.45,
      "size_mb": 245.7,
      "created_at": "2025-01-15T11:10:00Z"
    }
  ],
  "best_checkpoint": "checkpoint-2000",
  "total": 2
}

{
  "job_id": "val-550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "metrics": {
    "perplexity": 15.23,
    "accuracy": 0.87,
    "bleu": 0.42
  },
  "message": "Validation completed successfully with 3 metrics"
}

ZIP file stream
Content-Type: application/zip
Content-Disposition: attachment; filename=job_12345-abcde_checkpoint-2000.zip

Contains:
- adapter_config.json
- adapter_model.bin
- tokenizer.json
- config.json
- ... (all model files)

ZIP file stream
Content-Type: application/zip
Content-Disposition: attachment; filename=job_12345-abcde_logs.zip

Contains:
- training.log (full console output)
- progress.json (metrics history)

{
  "job_id": "job-12345-abcde",
  "duration": {
    "total_seconds": 3600,
    "formatted": "1h 0m 0s"
  },
  "performance": {
    "avg_iteration_time": 2.5,
    "throughput": 400,
    "total_iterations": 1000
  },
  "resources": {
    "gpu_utilization": 0.85,
    "memory_used_gb": 8.2,
    "peak_temperature": 72
  },
  "loss_progression": {
    "initial_loss": 3.2,
    "final_loss": 1.1,
    "improvement": 2.1
  },
  "checkpoints": {
    "total": 3,
    "best_checkpoint": "checkpoint-2000"
  },
  "efficiency_score": 0.92
}

{
  "total_jobs": 42,
  "jobs_by_status": {
    "completed": 35,
    "running": 2,
    "failed": 3,
    "cancelled": 2
  },
  "avg_training_duration_seconds": 2400,
  "total_training_time_hours": 28.0,
  "avg_throughput": 450,
  "top_performing_jobs": [
    {
      "job_id": "job-12345-abcde",
      "efficiency_score": 0.95,
      "duration_seconds": 1800
    }
  ],
  "resource_utilization": {
    "avg_gpu_usage": 0.82,
    "avg_memory_gb": 7.5
  }
}

{
  "comparison": [
    {
      "job_id": "job-123",
      "duration_seconds": 1800,
      "throughput": 450,
      "loss_improvement": 2.1,
      "gpu_utilization": 0.85,
      "efficiency_score": 0.92
    },
    {
      "job_id": "job-456",
      "duration_seconds": 2100,
      "throughput": 380,
      "loss_improvement": 1.8,
      "gpu_utilization": 0.78,
      "efficiency_score": 0.85
    }
  ],
  "winner": {
    "best_duration": "job-123",
    "best_throughput": "job-123",
    "best_efficiency": "job-123"
  }
}

{
  "configs": [
    {
      "id": "config-123",
      "name": "My GPT-2 Fine-tune",
      "description": "Fine-tuning GPT-2 on custom dataset",
      "template_type": "sft",
      "is_validated": true,
      "created_at": "2025-01-15T10:00:00Z",
      "config_json": { ... }
    }
  ]
}

{
  "config": {
    "id": "config-456",
    "user_id": "user-789",
    "name": "My Training Config",
    "description": "Fine-tuning for customer support",
    "template_type": "sft",
    "is_validated": true,
    "validation_errors": null,
    "created_at": "2025-01-15T11:30:00Z",
    "config_json": { ... }
  }
}

{
  "config": {
    "id": "config-123",
    "name": "My GPT-2 Fine-tune",
    "description": "Fine-tuning GPT-2 on custom dataset",
    "template_type": "sft",
    "is_validated": true,
    "config_json": {
      "model": { ... },
      "training": { ... }
    }
  }
}

{
  "config": {
    "id": "config-123",
    "name": "Updated Config Name",
    "description": "Updated description",
    "is_validated": true,
    "updated_at": "2025-01-15T12:00:00Z",
    "config_json": { ... }
  }
}

{
  "success": true
}

{
  "success": true,
  "model": {
    "id": "model-789",
    "name": "My Custom GPT-4",
    "provider": "openai",
    "enabled": true
  },
  "message": "Model created successfully"
}

{
  "success": true,
  "message": "Model deleted successfully"
}

{
  "success": false,
  "error": "Cannot delete global models"
}

{
  "success": true,
  "document": {
    "id": "doc-abc-123",
    "filename": "document.pdf",
    "fileType": "pdf",
    "processed": false,
    "uploadPath": "documents/user-123/document.pdf",
    "metadata": {
      "title": "My Document",
      "source": "research"
    },
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "message": "Document uploaded successfully, processing started"
}

{
  "documents": [
    {
      "id": "doc-abc-123",
      "filename": "research.pdf",
      "fileType": "pdf",
      "processed": true,
      "neo4jEpisodeIds": ["ep-1", "ep-2"],
      "uploadPath": "documents/user-123/research.pdf",
      "metadata": { "title": "Research Paper" },
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

{
  "context": "Quantum computing has applications in...",
  "sources": [
    {
      "documentId": "doc-abc-123",
      "filename": "quantum-research.pdf",
      "relevanceScore": 0.92,
      "excerpt": "Quantum algorithms can solve..."
    }
  ],
  "metadata": {
    "searchMethod": "hybrid",
    "resultsFound": 5
  },
  "query": "quantum computing applications",
  "limit": 5
}

{
  "success": true,
  "id": "doc-abc-123",
  "message": "Document and knowledge graph entries deleted successfully"
}

startDate: ISO 8601 date (required) - Start of date range
endDate: ISO 8601 date (required) - End of date range
metrics: String (optional) - Comma-separated list or "all"
  Values: tokens, quality, tools, conversations, errors, latency
granularity: String (optional) - Data aggregation period
  Values: hour, day (default), week, month, all

{
  "success": true,
  "data": {
    "userId": "user-123",
    "timeRange": {
      "start": "2025-11-01T00:00:00.000Z",
      "end": "2025-11-12T23:59:59.000Z",
      "period": "day"
    },
    "metrics": {
      "tokenUsage": [
        {
          "timestamp": "2025-11-01T12:00:00.000Z",
          "messageId": "msg-abc",
          "conversationId": "conv-123",
          "modelId": "gpt-4o",
          "inputTokens": 1250,
          "outputTokens": 890,
          "totalTokens": 2140,
          "estimatedCost": 0.00321
        }
      ],
      "quality": [
        {
          "timestamp": "2025-11-01T12:05:00.000Z",
          "messageId": "msg-abc",
          "rating": 4,
          "successStatus": "success",
          "evaluationType": "user_feedback"
        }
      ],
      "tools": [
        {
          "timestamp": "2025-11-01T12:02:00.000Z",
          "toolName": "calculator",
          "executionTimeMs": 45,
          "success": true
        }
      ]
    },
    "aggregations": {
      "totals": {
        "messages": 156,
        "conversations": 23,
        "tokens": 334210,
        "cost": 0.501,
        "evaluations": 89,
        "errors": 3
      },
      "averages": {
        "tokensPerMessage": 2142,
        "costPerMessage": 0.00321,
        "rating": 4.2,
        "successRate": 94.3,
        "errorRate": 1.9,
        "latencyMs": 1834
      }
    }
  }
}

1. calculator - Exact mathematical calculations
2. evaluation_metrics - 13 operations:
   • get_metrics, quality_trends, success_analysis
   • compare_periods, model_comparison, tool_impact_analysis
   • error_analysis, temporal_analysis, textual_feedback_analysis
   • benchmark_analysis, advanced_sentiment_analysis
   • predictive_quality_modeling, anomaly_detection
3. datetime - Date/time operations and timezone conversions
4. system_monitor - System health and resource monitoring
5. get_session_evaluations - Ratings and feedback data
6. get_session_metrics - Token usage, costs, response times
7. get_session_conversations - Full message history
8. training_control - List configs, attach datasets, start training

data: {"type": "token_usage", "input_tokens": 1250, "output_tokens": 340}

data: {"type": "tools_metadata", "tools_called": [
  {"name": "get_session_metrics", "success": true},
  {"name": "calculator", "success": true}
]}

data: {"content": "I analyzed your session and found:"}
data: {"content": " The total cost was $0.0123"}
data: {"content": " across 3 conversations."}
data: {"content": " Average cost per conversation: $0.0041"}

data: [DONE]

Progress Tracking:
• current_step, current_epoch, total_steps, total_epochs, progress (%)
• elapsed_seconds, remaining_seconds

Loss Metrics:
• loss (current train loss), eval_loss (current eval loss)
• best_eval_loss, best_epoch, best_step
• loss_trend: "improving" | "degrading" | "stable"
• epochs_without_improvement (early stopping detection)
• train_perplexity, eval_perplexity (exp of loss)

GPU Metrics:
• gpu_memory_allocated_gb, gpu_memory_reserved_gb
• gpu_utilization_percent

Training Parameters:
• learning_rate (current), grad_norm (gradient norm)
• samples_per_second, tokens_per_second (throughput)

Status & Warnings:
• status: "pending" | "running" | "completed" | "failed" | "cancelled"
• warning: Stale job detection (no updates >5 minutes)
• error: Error message if failed

{
  "job_id": "job-abc-123",
  "status": "running",
  "model_name": "meta-llama/Llama-3.2-1B",
  
  "current_step": 450,
  "current_epoch": 2,
  "total_steps": 1000,
  "total_epochs": 3,
  "total_samples": 5000,
  "progress": 45,
  
  "loss": 1.89,
  "eval_loss": 1.82,
  "best_eval_loss": 1.75,
  "best_epoch": 1,
  "best_step": 350,
  "loss_trend": "improving",
  "epochs_without_improvement": 1,
  
  "train_perplexity": 6.62,
  "eval_perplexity": 6.17,
  
  "learning_rate": 0.00008,
  "grad_norm": 0.72,
  
  "gpu_memory_allocated_gb": 15.8,
  "gpu_memory_reserved_gb": 18.0,
  "gpu_utilization_percent": 92.3,
  
  "samples_per_second": 13.2,
  "tokens_per_second": 1689,
  
  "started_at": "2025-11-12T09:00:00.000Z",
  "elapsed_seconds": 3420,
  "remaining_seconds": 4180
}

{
  "job_id": "job-xyz-789",
  "status": "running",
  "current_step": 200,
  "progress": 20,
  "warning": "⚠️ No updates received in 8 minute(s). The training process may have terminated unexpectedly.",
  ...
}

• Loss Metrics: train_loss, eval_loss, train_perplexity, eval_perplexity
• Training Progress: step, epoch, learning_rate, grad_norm
• GPU Metrics: gpu_memory_allocated_gb, gpu_memory_reserved_gb, 
                gpu_utilization_percent
• Throughput: samples_per_second, tokens_per_second
• Timestamps: created_at (when metric was recorded)

{
  "job_id": "job-abc-123",
  "metrics": [
    {
      "id": "metric-001",
      "job_id": "job-abc-123",
      "step": 100,
      "epoch": 1,
      "train_loss": 2.45,
      "eval_loss": 2.38,
      "train_perplexity": 11.59,
      "perplexity": 10.80,
      "learning_rate": 0.0001,
      "grad_norm": 0.85,
      "gpu_memory_allocated_gb": 14.2,
      "gpu_memory_reserved_gb": 16.0,
      "gpu_utilization_percent": 89.5,
      "samples_per_second": 12.4,
      "tokens_per_second": 1586,
      "created_at": "2025-11-12T10:15:23.000Z"
    },
    {
      "id": "metric-002",
      "job_id": "job-abc-123",
      "step": 200,
      "epoch": 1,
      "train_loss": 2.12,
      "eval_loss": 2.05,
      "learning_rate": 0.00009,
      "samples_per_second": 12.8,
      "created_at": "2025-11-12T10:20:45.000Z"
    }
  ]
}

lookback_days: Number (optional, default: 30)
  - Number of days to analyze for insights
  - Example: lookback_days=7 for weekly insights

{
  "insights": [
    {
      "type": "anomaly",
      "severity": "high",
      "title": "Sudden Sentiment Drop Detected",
      "description": "Average sentiment decreased by 35% in the past 3 days",
      "affectedConversations": 12,
      "detectedAt": "2025-11-12T08:30:00.000Z",
      "recommendation": "Review recent model changes or data quality issues"
    },
    {
      "type": "trend",
      "severity": "medium",
      "title": "Increasing Negative Feedback",
      "description": "Negative ratings increased by 15% week-over-week",
      "affectedConversations": 8,
      "detectedAt": "2025-11-12T08:30:00.000Z",
      "recommendation": "Analyze error patterns in recent conversations"
    },
    {
      "type": "positive",
      "severity": "low",
      "title": "Quality Improvement Detected",
      "description": "Success rate improved from 82% to 94% this week",
      "affectedConversations": 45,
      "detectedAt": "2025-11-12T08:30:00.000Z",
      "recommendation": "Document successful strategies for future reference"
    }
  ]
}

• static: Fixed list of users (manual membership)
• dynamic: Auto-updates based on criteria (e.g., "active in last 7 days")
• behavioral: Action-based segmentation (e.g., "used calculator tool")
• subscription: Tier-based grouping (free, pro, enterprise)
• custom: Advanced custom criteria and rules

{
  "cohort": {
    "id": "cohort-abc-123",
    "name": "Power Users",
    "description": "Users with >50 conversations in last month",
    "cohort_type": "dynamic",
    "criteria": {
      "min_conversations": 50,
      "lookback_days": 30,
      "active_status": true
    },
    "member_count": 0,
    "is_active": true,
    "created_at": "2025-11-12T10:30:00.000Z",
    "updated_at": "2025-11-12T10:30:00.000Z"
  }
}