Add project documentation and reference materials

Include Luna AI Assistant design docs covering channels, configuration, core architecture, memory, scheduler, and skills. Add reference docs from OpenClaw and ZeroClaw projects, plus Mistral and OpenAI API specs.
2026-04-04 04:14:06 +02:00
parent 969e4d6e37
commit 9929941748
39 changed files with 55467 additions and 0 deletions
@@ -0,0 +1,137 @@
+# Core Module
+
+The Core module serves as the central orchestration engine for Luna, managing sessions, message routing, context compaction, and tool integration. It is split into `Luna.Core.Abstractions` for interfaces and `Luna.Core` for the primary implementation.
+
+## Luna.Core.Abstractions
+
+This project defines the contracts used by the Core and other modules.
+
+### ISessionManager
+The primary interface for managing chat sessions and routing messages.
+```csharp
+public interface ISessionManager
+{
+    IAsyncEnumerable<ChatStreamUpdate> RouteMessagesAsync(string content, string conversationId, string connectionId, CancellationToken ct);
+    Task ClientDisconnectedAsync(string connectionId);
+}
+```
+
+### IChatHubContext
+Interface for sending responses back to clients via SignalR.
+```csharp
+public interface IChatHubContext
+{
+    Task SendResponseAsync(string connectionId, ChannelMessage message, CancellationToken ct);
+    Task SendStreamingResponseAsync(string connectionId, IAsyncEnumerable<ChatStreamUpdate> messageStream, CancellationToken ct);
+}
+```
+
+## Luna.Core
+
+The main implementation project containing the session logic and SignalR hubs.
+
+### Session
+The `Session` class manages the state of an active conversation.
+```csharp
+public class Session
+{
+    public string SessionId { get; set; }
+    public List<ChatMessage> Messages { get; } = new();
+    public int TokenAmount => TokenEstimator.EstimateTokens(Messages);
+}
+```
+
+### SessionManager
+Implements `ISessionManager`. It coordinates between agents, memory, and the core LLM processing.
+- **Injected Services**:
+    - `[FromKeyedServices("Core")] IAgent coreAgent`
+    - `[FromKeyedServices("Librarian")] IAgent librarianAgent`
+    - `IOptions<SessionOptions> options`
+    - `IChatStreamUpdateBuilder streamUpdateBuilder`
+    - `IMemoryStore memoryStore`
+- **State Management**: Maintains an in-memory `Dictionary<string, Session>` for sessions and a `ConcurrentDictionary<string, string>` for mapping connection IDs to session IDs.
+
+#### Message Routing Flow
+1. **Session Initialization**: Creates a new session if one does not exist and loads existing [[Memory]] via `memoryStore.GetMemoriesAsync()`.
+2. **Token Check**: Evaluates current token usage against `MaxContextTokens * ContextTokenThreshold`.
+3. **Compaction**: If the threshold is exceeded, triggers `CompactSessionAsync`.
+4. **Processing**: Appends the user message, streams the response from the `coreAgent` via `ProcessStreamingAsync`, and converts AI content to `ChatStreamUpdate` using the `IChatStreamUpdateBuilder`.
+5. **Persistence**: Appends the assistant response to the session history.
+
+#### Compaction Strategy
+When a session exceeds the token threshold, the system:
+1. Retains the last $N$ messages (defined by `SessionOptions.RetainedMessagesAfterCompacting`).
+2. Sends all older messages to the `librarianAgent` for summarization.
+3. Wraps the resulting summary in `<---- MEMORY BEGIN ---->` and `<---- MEMORY END ---->` markers and inserts it at the beginning of the message list.
+
+#### Disconnect Flow
+When `ClientDisconnectedAsync` is called:
+1. The conversation log is saved to the `IMemoryStore`.
+2. The session and connection mappings are cleaned up.
+
+### Hubs and Contexts
+
+#### ChatHub
+A SignalR hub that serves as the entry point for real-time communication.
+- **OnConnected**: Creates a `CliChannel` and registers it with the `IChannelManager`.
+- **OnDisconnected**: Unregisters the channel.
+- **OnMessageReceived**: Delegates message handling to the `CliChannel.RaiseMessageReceived`.
+
+#### ChatHubContext
+Implements `IChatHubContext` using `IHubContext<ChatHub>`. It handles the actual transmission of data to SignalR clients, supporting both discrete and streaming responses.
+
+### Tools System
+
+#### IToolbox
+Provides a mechanism for discovering and exposing tools to the AI.
+- **Implementation**: Uses reflection to find methods decorated with `[ToolAttribute]`.
+- **Function Creation**: Generates `AITool` instances using `AIFunctionFactory.Create`.
+
+#### IToolsProvider
+Exposes the collection of discovered tools.
+```csharp
+public interface IToolsProvider
+{
+    IEnumerable<AITool> GetTools();
+}
+```
+
+### Token Estimation
+The `TokenEstimator` provides a heuristic-based token count:
+- **Calculation**: Number of characters divided by 4.
+
+## Architecture Flow
+
+The following flow describes how a message moves through the Core module:
+
+```text
+Channel.MessageReceived → ChannelManager → SessionManager.RouteMessagesAsync
+  → Token Check → Compaction if needed (LibrarianAgent)
+  → CoreAgent.ProcessStreamingAsync → IChatClient Streaming
+  → ChatStreamUpdateBuilder → IAsyncEnumerable<ChatStreamUpdate>
+  → Channel.SendStreamingMessageAsync → Client
+```
+
+## Cross-References
+- [[Channels]]: Management of communication pathways.
+- [[Memory]]: Long-term and short-term state persistence.
+- [[Configuration]]: `SessionOptions` and system settings.
+- [[Skills]]: Integration of specialized capabilities.
+- [[Scheduler]]: Task timing and execution.
+
+## Dependencies
+
+### Project References
+- Luna.Agents.Abstractions
+- Luna.Channels
+- Luna.Channels.Abstractions
+- [[Configuration]] (Luna.Configuration)
+- Luna.Core.Abstractions
+- [[Memory]] (Luna.Memory)
+- Luna.Providers
+- Luna.Providers.Abstractions
+- Luna.Shared
+
+### NuGet Packages
+- Microsoft.AspNetCore.OpenApi
+- Microsoft.Extensions.AI