version 2

src/GreenHome.AI.DeepSeek/README.md

@@ -0,0 +1,399 @@
+# GreenHome.AI.DeepSeek
+
+سرویس هوش مصنوعی DeepSeek برای پروژه GreenHome
+
+## درباره DeepSeek
+
+DeepSeek یک مدل هوش مصنوعی پیشرفته است که می‌توانید از آن برای:
+- پاسخ به سوالات کاربران
+- تحلیل داده‌های خانه هوشمند
+- ارائه پیشنهادات بهینه‌سازی
+- تولید محتوای هوشمند
+
+## نصب و راه‌اندازی
+
+### 1. اضافه کردن Reference به پروژه
+
+در فایل `.csproj` پروژه خود:
+
+```xml
+<ItemGroup>
+  <ProjectReference Include="..\GreenHome.AI.DeepSeek\GreenHome.AI.DeepSeek.csproj" />
+</ItemGroup>
+```
+
+### 2. دریافت API Key
+
+1. به وب‌سایت [DeepSeek](https://platform.deepseek.com/) بروید
+2. ثبت‌نام کنید یا وارد حساب کاربری خود شوید
+3. از بخش API Keys، یک کلید API جدید بسازید
+4. کلید را کپی کنید (فقط یک بار نمایش داده می‌شود!)
+
+### 3. ثبت سرویس در Program.cs
+
+```csharp
+using GreenHome.AI.DeepSeek;
+
+// روش 1: استفاده از Configuration (پیشنهادی)
+builder.Services.AddDeepSeek(builder.Configuration);
+
+// روش 2: استفاده از Configuration Section
+builder.Services.AddDeepSeek(builder.Configuration.GetSection("DeepSeek"));
+
+// روش 3: تنظیم دستی
+builder.Services.AddDeepSeek(options =>
+{
+    options.ApiKey = "YOUR_API_KEY_HERE";
+    options.BaseUrl = "https://api.deepseek.com";
+    options.DefaultModel = "deepseek-chat";
+    options.DefaultTemperature = 1.0;
+});
+```
+
+### 4. تنظیمات در appsettings.json
+
+```json
+{
+  "DeepSeek": {
+    "BaseUrl": "https://api.deepseek.com",
+    "ApiKey": "YOUR_DEEPSEEK_API_KEY_HERE",
+    "DefaultModel": "deepseek-chat",
+    "DefaultTemperature": 1.0,
+    "DefaultMaxTokens": 2000
+  }
+}
+```
+
+**نکته امنیتی:** هرگز API Key خود را در کد یا repository قرار ندهید! از Environment Variables یا User Secrets استفاده کنید.
+
+#### استفاده از User Secrets (Development)
+
+```bash
+dotnet user-secrets init
+dotnet user-secrets set "DeepSeek:ApiKey" "YOUR_API_KEY_HERE"
+```
+
+#### استفاده از Environment Variables (Production)
+
+```bash
+export DeepSeek__ApiKey="YOUR_API_KEY_HERE"
+```
+
+## استفاده در کنترلرها
+
+### تزریق سرویس
+
+```csharp
+public class AIController : ControllerBase
+{
+    private readonly IDeepSeekService deepSeekService;
+
+    public AIController(IDeepSeekService deepSeekService)
+    {
+        this.deepSeekService = deepSeekService;
+    }
+}
+```
+
+### سوال ساده
+
+```csharp
+var response = await deepSeekService.AskSimpleAsync(
+    "چگونه می‌توانم مصرف انرژی خانه را کاهش دهم؟"
+);
+
+Console.WriteLine(response);
+```
+
+### سوال با System Prompt
+
+```csharp
+var systemPrompt = "شما یک مشاور خانه هوشمند هستید.";
+var question = "بهترین دمای کولر برای صرفه‌جویی انرژی چقدر است؟";
+
+var response = await deepSeekService.AskSimpleAsync(question, systemPrompt);
+```
+
+### چت پیشرفته با تاریخچه
+
+```csharp
+var request = new ChatRequest
+{
+    Model = "deepseek-chat",
+    Messages = new List<ChatMessage>
+    {
+        new ChatMessage 
+        { 
+            Role = "system", 
+            Content = "شما یک دستیار هوشمند خانه هوشمند هستید." 
+        },
+        new ChatMessage 
+        { 
+            Role = "user", 
+            Content = "دمای فعلی 28 درجه است" 
+        },
+        new ChatMessage 
+        { 
+            Role = "assistant", 
+            Content = "باشه، دمای فعلی خانه را دریافت کردم." 
+        },
+        new ChatMessage 
+        { 
+            Role = "user", 
+            Content = "آیا باید کولر را روشن کنم؟" 
+        }
+    },
+    Temperature = 0.7,
+    MaxTokens = 1000
+};
+
+var response = await deepSeekService.AskAsync(request);
+var answer = response?.Choices?.FirstOrDefault()?.Message?.Content;
+```
+
+## API Endpoints
+
+سرویس شامل 3 endpoint اصلی است:
+
+### 1. POST /api/ai/ask
+پرسیدن یک سوال ساده
+
+**Request Body:**
+```json
+{
+  "question": "چگونه می‌توانم دمای خانه را کنترل کنم؟",
+  "systemPrompt": "شما یک مشاور خانه هوشمند هستید."
+}
+```
+
+**Response:**
+```json
+{
+  "question": "چگونه می‌توانم دمای خانه را کنترل کنم؟",
+  "answer": "برای کنترل دمای خانه می‌توانید از ترموستات هوشمند استفاده کنید...",
+  "timestamp": "2025-12-16T10:30:00Z"
+}
+```
+
+### 2. POST /api/ai/chat
+چت پیشرفته با تاریخچه
+
+**Request Body:**
+```json
+{
+  "model": "deepseek-chat",
+  "messages": [
+    {
+      "role": "system",
+      "content": "شما یک دستیار هوشمند هستید."
+    },
+    {
+      "role": "user",
+      "content": "سلام"
+    }
+  ],
+  "temperature": 0.7,
+  "maxTokens": 2000
+}
+```
+
+**Response:**
+```json
+{
+  "id": "chatcmpl-xxx",
+  "object": "chat.completion",
+  "created": 1702735200,
+  "model": "deepseek-chat",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "سلام! چطور می‌تونم کمکتون کنم؟"
+      },
+      "finishReason": "stop"
+    }
+  ],
+  "usage": {
+    "promptTokens": 20,
+    "completionTokens": 15,
+    "totalTokens": 35
+  }
+}
+```
+
+### 3. POST /api/ai/suggest
+دریافت پیشنهادات برای بهینه‌سازی خانه هوشمند
+
+**Request Body:**
+```json
+{
+  "deviceContext": "دمای اتاق: 28°C، رطوبت: 65%، ساعت: 14:00"
+}
+```
+
+**Response:**
+```json
+{
+  "suggestions": "با توجه به دمای بالای 28 درجه، توصیه می‌شود کولر را روشن کنید...",
+  "timestamp": "2025-12-16T10:30:00Z"
+}
+```
+
+## مثال‌های کاربردی
+
+### 1. تحلیل داده‌های سنسور
+
+```csharp
+var deviceData = $@"
+دمای اتاق خواب: {temperature}°C
+رطوبت: {humidity}%
+کیفیت هوا: {airQuality}
+ساعت: {DateTime.Now:HH:mm}
+";
+
+var systemPrompt = "شما یک مشاور خانه هوشمند هستید که بر اساس داده‌های سنسورها پیشنهاد می‌دهید.";
+
+var response = await deepSeekService.AskSimpleAsync(
+    $"وضعیت خانه: {deviceData}\nچه کاری باید انجام دهم؟",
+    systemPrompt
+);
+```
+
+### 2. پاسخ به سوالات کاربر
+
+```csharp
+[HttpPost("ask")]
+public async Task<IActionResult> Ask([FromBody] string question)
+{
+    var answer = await deepSeekService.AskSimpleAsync(question);
+    return Ok(new { question, answer });
+}
+```
+
+### 3. دستیار هوشمند با حافظه
+
+```csharp
+// ذخیره تاریخچه در session یا database
+var conversationHistory = GetConversationHistory(userId);
+
+var request = new ChatRequest
+{
+    Messages = conversationHistory.Select(m => new ChatMessage
+    {
+        Role = m.Role,
+        Content = m.Content
+    }).ToList()
+};
+
+// اضافه کردن پیام جدید کاربر
+request.Messages.Add(new ChatMessage
+{
+    Role = "user",
+    Content = userMessage
+});
+
+var response = await deepSeekService.AskAsync(request);
+
+// ذخیره پاسخ در تاریخچه
+SaveToHistory(userId, response);
+```
+
+## پارامترها
+
+### Temperature
+- **مقدار:** 0 تا 2
+- **پیش‌فرض:** 1.0
+- **توضیح:** هر چه عدد بالاتر باشد، پاسخ‌ها خلاقانه‌تر و تصادفی‌تر هستند
+
+### MaxTokens
+- **توضیح:** حداکثر تعداد توکن در پاسخ
+- **توصیه:** برای پاسخ‌های کوتاه: 500، برای پاسخ‌های بلند: 2000
+
+### Model
+- **مقدار:** `deepseek-chat` (پیش‌فرض)
+- **توضیح:** مدل مورد استفاده برای تولید پاسخ
+
+## نکات مهم
+
+1. **هزینه:** هر درخواست به DeepSeek بر اساس تعداد توکن‌های استفاده شده هزینه دارد
+2. **Rate Limiting:** محدودیت تعداد درخواست در واحد زمان را رعایت کنید
+3. **Timeout:** درخواست‌های AI ممکن است طولانی باشند (پیش‌فرض: 60 ثانیه)
+4. **خطاها:** همیشه خطاها را مدیریت کنید و پیام مناسب به کاربر نمایش دهید
+5. **امنیت:** API Key را محرمانه نگه دارید
+
+## عیب‌یابی
+
+### خطای 401 Unauthorized
+- بررسی کنید که API Key صحیح است
+- مطمئن شوید که در configuration به درستی تنظیم شده است
+
+### خطای 429 Too Many Requests
+- به محدودیت rate limit رسیده‌اید
+- کمی صبر کنید و دوباره تلاش کنید
+
+### خطای Timeout
+- درخواست خیلی طولانی است
+- MaxTokens را کاهش دهید یا Timeout را افزایش دهید
+
+## مثال کامل
+
+```csharp
+using GreenHome.AI.DeepSeek;
+using Microsoft.AspNetCore.Mvc;
+
+[ApiController]
+[Route("api/[controller]")]
+public class SmartHomeAIController : ControllerBase
+{
+    private readonly IDeepSeekService _ai;
+    private readonly ILogger<SmartHomeAIController> _logger;
+
+    public SmartHomeAIController(
+        IDeepSeekService ai,
+        ILogger<SmartHomeAIController> logger)
+    {
+        _ai = ai;
+        _logger = logger;
+    }
+
+    [HttpPost("analyze")]
+    public async Task<IActionResult> AnalyzeHome([FromBody] HomeData data)
+    {
+        try
+        {
+            var prompt = $@"
+داده‌های خانه هوشمند:
+- دمای داخل: {data.Temperature}°C
+- رطوبت: {data.Humidity}%
+- مصرف برق: {data.PowerUsage}W
+- تعداد افراد: {data.OccupancyCount}
+
+لطفاً تحلیل کامل ارائه دهید و پیشنهادات بهینه‌سازی بدهید.
+            ";
+
+            var systemPrompt = "شما یک متخصص خانه هوشمند هستید.";
+            
+            var analysis = await _ai.AskSimpleAsync(prompt, systemPrompt);
+            
+            return Ok(new { analysis, timestamp = DateTime.UtcNow });
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Error analyzing home data");
+            return StatusCode(500, "خطا در تحلیل داده‌ها");
+        }
+    }
+}
+```
+
+## منابع
+
+- [DeepSeek Documentation](https://platform.deepseek.com/docs)
+- [API Reference](https://platform.deepseek.com/api-docs)
+- [Pricing](https://platform.deepseek.com/pricing)
+
+## پشتیبانی
+
+در صورت بروز مشکل، لطفاً یک Issue در GitHub ایجاد کنید.
+