162 lines
4.4 KiB
Markdown
162 lines
4.4 KiB
Markdown
# 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.
|
|
|
|
### Streaming Message Format
|
|
|
|
The streaming response sends several types of JSON messages:
|
|
|
|
- **Text messages**: `{"type": "text", "data": "..." }`
|
|
- **Function calls**: `{"type": "function_call", "data": {...} }` (when AI uses tools)
|
|
- **Topic updates**: `{"type": "topic", "data": "..." }` (sent at end if topic was generated)
|
|
- **Thought completion**: `{"type": "thought", "data": {...} }` (sent at end with saved thought details)
|
|
|
|
All streaming chunks during generation use the SSE event format:
|
|
```
|
|
data: {"type": "...", "data": ...}
|
|
|
|
```
|
|
|
|
Final messages (topic and thought) use custom event types:
|
|
```
|
|
topic: {"type": "topic", "data": "..."}
|
|
|
|
thought: {"type": "thought", "data": {...}}
|
|
```
|
|
|
|
Clients should parse these JSON messages and handle different types appropriately, such as displaying text in real-time and processing tool calls.
|
|
|
|
## 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
|