✨ Thinking

2025-10-25 23:32:51 +08:00
parent 93f7dfd379
commit 609b130b4e
19 changed files with 829 additions and 80 deletions
--- a/DysonNetwork.Insight/Thought/README.md
+++ b/DysonNetwork.Insight/Thought/README.md
@@ -0,0 +1,137 @@
+# DysonNetwork Insight Thought API
+
+The Thought API provides conversational AI capabilities for users of the Solar Network. It allows users to engage in chat-like conversations with an AI assistant powered by semantic kernel and connected to various tools.
+
+This service is handled by the Insight, when using with the Gateway, the `/api` should be replaced with `/insight`
+
+## Features
+
+- Streaming chat responses using Server-Sent Events (SSE)
+- Conversation context management with sequences
+- Caching for improved performance
+- Authentication required for all operations
+
+## Endpoints
+
+### POST /api/thought
+
+Initiates or continues a chat conversation.
+
+#### Parameters
+- `UserMessage` (string, required): The message from the user
+- `SequenceId` (Guid, optional): ID of existing conversation sequence. If not provided, a new sequence is created.
+
+#### Response
+- Content-Type: `text/event-stream`
+- Streaming response with assistant messages
+- Status: 401 if not authenticated
+- Status: 403 if sequence doesn't belong to user
+
+#### Example Usage
+```bash
+curl -X POST "http://localhost:5000/api/thought" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "UserMessage": "Hello, how can I help with the Solar Network?",
+    "SequenceId": null
+  }'
+```
+
+### GET /api/thought/sequences
+
+Lists all thinking sequences for the authenticated user.
+
+#### Parameters
+- `offset` (int, default 0): Number of sequences to skip for pagination
+- `take` (int, default 20): Maximum number of sequences to return
+
+#### Response
+- `200 OK`: Array of `SnThinkingSequence`
+- `401 Unauthorized`: If not authenticated
+- Headers:
+  - `X-Total`: Total number of sequences before pagination
+
+#### Example Usage
+```bash
+curl -X GET "http://localhost:5000/api/thought/sequences?take=10"
+```
+
+### GET /api/thought/sequences/{sequenceId}
+
+Retrieves all thoughts (messages) in a specific conversation sequence.
+
+#### Parameters
+- `sequenceId` (Guid, path): ID of the sequence to retrieve
+
+#### Response
+- `200 OK`: Array of `SnThinkingThought` ordered by creation date
+- `401 Unauthorized`: If not authenticated
+- `404 Not Found`: If sequence doesn't exist or doesn't belong to user
+
+#### Example Usage
+```bash
+curl -X GET "http://localhost:5000/api/thought/sequences/12345678-1234-1234-1234-123456789abc"
+```
+
+## Data Models
+
+### StreamThinkingRequest
+```csharp
+{
+  string UserMessage, // Required
+  Guid? SequenceId    // Optional
+}
+```
+
+### SnThinkingSequence
+```csharp
+{
+  Guid Id,
+  string? Topic,
+  Guid AccountId
+}
+```
+
+### SnThinkingThought
+```csharp
+{
+  Guid Id,
+  string? Content,
+  List<SnCloudFileReferenceObject> Files,
+  ThinkingThoughtRole Role,
+  Guid SequenceId,
+  SnThinkingSequence Sequence
+}
+```
+
+### ThinkingThoughtRole (enum)
+- `Assistant`
+- `User`
+
+## Caching
+
+The API uses Redis-based caching for conversation thoughts:
+- Thoughts are cached for 10 minutes with group-based invalidation
+- Cache is invalidated when new thoughts are added to a sequence
+- Improves performance for accessing conversation history
+
+## Authentication
+
+All endpoints require authentication through the current user session. Sequence access is validated against the authenticated user's account ID.
+
+## Error Responses
+
+- `401 Unauthorized`: Authentication required
+- `403 Forbidden`: Access denied (sequence ownership)
+- `404 Not Found`: Resource not found
+
+## Streaming Details
+
+The POST endpoint returns a stream of assistant responses using Server-Sent Events format. Clients should handle the streaming response and display messages incrementally.
+
+## Implementation Notes
+
+- Built with ASP.NET Core and Semantic Kernel
+- Uses PostgreSQL via Entity Framework Core
+- Integrated with Ollama for AI completion
+- Caching via Redis