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.
This commit is contained in:
@@ -0,0 +1,23 @@
|
||||
# CLI Channel
|
||||
|
||||
The CLI connects to Luna via SignalR. `CliChannel` is a server-side adapter that bridges the SignalR hub to the `IChannel` interface defined in [[Channels]].
|
||||
|
||||
## How It Works
|
||||
|
||||
`CliChannel` wraps `IChatHubContext` from [[Core]] to send streaming responses back to the connected SignalR client. The flow:
|
||||
|
||||
1. The `ChatHub` receives a message from the CLI client over SignalR.
|
||||
2. `ChatHub` calls `RaiseMessageReceived` on the `CliChannel` instance.
|
||||
3. The [[Channels|ChannelManager]] picks up the event and routes it through `SessionManager.RouteMessagesAsync`.
|
||||
4. The resulting `IAsyncEnumerable<ChatStreamUpdate>` is passed back to `CliChannel.SendStreamingMessageAsync`.
|
||||
5. `CliChannel` forwards the stream to the SignalR client via `IChatHubContext`.
|
||||
|
||||
## Key Characteristics
|
||||
|
||||
- **Server-side adapter**: `CliChannel` lives on the server; the actual CLI is a separate SignalR client.
|
||||
- **Single connection**: One `CliChannel` instance maps to the SignalR hub connection.
|
||||
- **No polling**: Unlike [[Telegram Channel]], the CLI uses persistent WebSocket connections via SignalR.
|
||||
|
||||
## Namespace
|
||||
|
||||
`Luna.Channels.Cli`
|
||||
@@ -0,0 +1,101 @@
|
||||
# Channels
|
||||
|
||||
The Channels module provides a unified abstraction for communication platforms like the CLI and Telegram. It handles message transport, while [[Core]] manages AI context and session state.
|
||||
|
||||
## Luna.Channels.Abstractions
|
||||
|
||||
This project defines the contracts and event models for all channel implementations.
|
||||
|
||||
### IChannel
|
||||
The primary interface for any communication transport. There is no abstract base class; `IChannel` is the complete contract.
|
||||
|
||||
```csharp
|
||||
public interface IChannel : IDisposable
|
||||
{
|
||||
string ChannelId { get; }
|
||||
string ChannelType { get; }
|
||||
string DisplayName { get; }
|
||||
bool IsConnected { get; }
|
||||
|
||||
event ChannelMessageReceivedEventHandler? MessageReceived;
|
||||
event EventHandler<ChannelConnectionEventArgs>? ConnectionStateChanged;
|
||||
|
||||
Task SendMessageAsync(ChannelMessage message, CancellationToken ct = default);
|
||||
Task SendStreamingMessageAsync(IAsyncEnumerable<ChatStreamUpdate> messageStream, CancellationToken ct = default);
|
||||
}
|
||||
```
|
||||
|
||||
### IChannelManager
|
||||
Coordinates registered channels and handles message routing.
|
||||
|
||||
```csharp
|
||||
public interface IChannelManager
|
||||
{
|
||||
void RegisterChannel(IChannel channel);
|
||||
void UnregisterChannel(string channelId);
|
||||
IChannel? GetChannel(string channelId);
|
||||
IReadOnlyList<IChannel> GetAllChannels();
|
||||
event EventHandler<ChannelMessageReceivedEventArgs>? MessageRouted;
|
||||
}
|
||||
```
|
||||
|
||||
### Supporting Types
|
||||
- **ChannelType**: A static class providing constants like `cli` and `telegram`.
|
||||
- **ChannelMessageReceivedEventHandler**: Delegate for handling incoming messages.
|
||||
`Task ChannelMessageReceivedEventHandler(object? sender, ChannelMessageReceivedEventArgs e)`
|
||||
- **ChannelMessageReceivedEventArgs**: Contains the `Channel`, `Message`, and an `IsHandled` flag.
|
||||
- **ChannelConnectionEventArgs**: Contains the `Channel` and `IsConnected` status.
|
||||
|
||||
## Luna.Channels
|
||||
|
||||
This project contains the concrete management logic and specific channel implementations.
|
||||
|
||||
### ChannelManager
|
||||
The `ChannelManager` implements `IChannelManager` and acts as the central hub for message traffic. It injects `ISessionManager` from [[Core]] and `ILogger<ChannelManager>`.
|
||||
|
||||
When a channel is registered via `RegisterChannel`, the manager subscribes to its `MessageReceived` event. The `OnMessageReceivedAsync` handler performs the following:
|
||||
1. Calls `sessionManager.RouteMessagesAsync(message.Content, message.ConversationId, channel.ChannelId)`.
|
||||
2. Pipes the resulting `IAsyncEnumerable<ChatStreamUpdate>` back to the channel via `channel.SendStreamingMessageAsync`.
|
||||
|
||||
### Channel Implementations
|
||||
- [[CLI Channel]] — SignalR-based adapter for the command-line interface.
|
||||
- [[Telegram Channel]] — Telegram Bot API adapter with message splitting and streaming.
|
||||
- [[Web Interface Channel]] — Browser-based chat UI (not yet implemented).
|
||||
|
||||
## Routing Flow
|
||||
|
||||
1. `Channel.MessageReceived` event triggers.
|
||||
2. `ChannelManager` catches the event and identifies the sender.
|
||||
3. Manager calls `SessionManager.RouteMessagesAsync`.
|
||||
4. `SessionManager` returns an `IAsyncEnumerable<ChatStreamUpdate>`.
|
||||
5. `ChannelManager` passes this stream to `Channel.SendStreamingMessageAsync`.
|
||||
6. The channel implementation handles the physical transport of the stream.
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
- **Separation of Concerns**: `ChannelManager` handles transport and routing. `SessionManager` handles AI context and conversation logic.
|
||||
- **Conversation Scoping**: Sessions are scoped to conversations, not specific channels. This allows for potential cross-channel persistence.
|
||||
- **Unified DTOs**: All message data uses the `ChannelMessage` DTO from `Luna.Shared`.
|
||||
- **Registration**: Channels are registered via the `AddChannels()` DI extension method, following the [[Configuration]] patterns.
|
||||
- **Options Pattern**: Implementations use `IOptions<TOptions>` (e.g., `TelegramOptions`) for configuration.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Project References
|
||||
- `Luna.Channels.Abstractions`
|
||||
- `Luna.Configuration`
|
||||
- `Luna.Core.Abstractions`
|
||||
- `Luna.Shared`
|
||||
|
||||
### NuGet Packages
|
||||
- `Telegram.Bot`
|
||||
- `Microsoft.Extensions.Hosting.Abstractions`
|
||||
- `Microsoft.Extensions.Logging.Abstractions`
|
||||
|
||||
## Adding a New Channel
|
||||
|
||||
To implement a new channel:
|
||||
1. Create a class implementing `IChannel`.
|
||||
2. Ensure it handles both `SendMessageAsync` and `SendStreamingMessageAsync`.
|
||||
3. Raise `MessageReceived` when the external platform sends a message.
|
||||
4. Register the channel with `IChannelManager` during startup or via a background adapter (like `TelegramAdapter`).
|
||||
@@ -0,0 +1,39 @@
|
||||
# Telegram Channel
|
||||
|
||||
The Telegram integration consists of two classes: `TelegramChannel` (the `IChannel` implementation) and `TelegramAdapter` (the hosted service that manages channel lifecycles). Both live in the `Luna.Channels.Telegram` namespace.
|
||||
|
||||
## TelegramChannel
|
||||
|
||||
Handles interaction with the Telegram Bot API, implementing the `IChannel` interface defined in [[Channels]].
|
||||
|
||||
### Message Splitting
|
||||
Telegram enforces a 4096-character limit per message. `TelegramChannel` automatically splits long responses into sequential chunks that respect this limit.
|
||||
|
||||
### Streaming
|
||||
Rather than forwarding every `ChatStreamUpdate` individually (which would hit Telegram's rate limits), the channel accumulates streaming updates and sends them in periodic batches.
|
||||
|
||||
### Typing Indicators
|
||||
Uses `KeepTypingAsync` to maintain a "typing..." indicator in the Telegram chat while the AI generates a response. This runs as a background loop until the response completes.
|
||||
|
||||
### User Filtering
|
||||
`RaiseMessageReceived` filters incoming updates by `AllowedUserIds` (configured via `TelegramOptions` in [[Configuration]]). Messages from unauthorized users or with empty content are silently dropped.
|
||||
|
||||
## TelegramAdapter
|
||||
|
||||
An `IHostedService` and `IUpdateHandler` that polls Telegram for updates using long polling.
|
||||
|
||||
### Lifecycle
|
||||
1. On startup, begins polling the Telegram Bot API.
|
||||
2. For each incoming update, identifies the chat ID.
|
||||
3. Creates a new `TelegramChannel` instance for each unique chat (if one doesn't already exist).
|
||||
4. Registers the channel with `IChannelManager` from [[Channels]].
|
||||
5. Routes the update to the appropriate `TelegramChannel`.
|
||||
|
||||
### Configuration
|
||||
Configured via `TelegramOptions` (see [[Configuration]]), which includes:
|
||||
- `BotToken` — Telegram Bot API token.
|
||||
- `AllowedUserIds` — Whitelist of Telegram user IDs permitted to interact with Luna.
|
||||
|
||||
## Namespace
|
||||
|
||||
`Luna.Channels.Telegram`
|
||||
@@ -0,0 +1,41 @@
|
||||
# Web Interface Channel
|
||||
|
||||
> [!info] Status: Not Yet Implemented
|
||||
|
||||
The Web Interface channel will provide a browser-based chat UI for interacting with Luna directly, without requiring the CLI or Telegram. It implements the `IChannel` interface defined in [[Channels]].
|
||||
|
||||
## Planned Approach
|
||||
|
||||
### WebInterfaceChannel
|
||||
|
||||
A server-side `IChannel` implementation that bridges the web frontend to Luna's channel system. Similar to [[CLI Channel]], it will likely use SignalR for real-time bidirectional communication.
|
||||
|
||||
**Key responsibilities:**
|
||||
- Accept messages from authenticated browser sessions.
|
||||
- Stream `ChatStreamUpdate` responses back to the frontend in real time.
|
||||
- Manage connection lifecycle (connect, disconnect, reconnect).
|
||||
|
||||
### WebInterfaceAdapter
|
||||
|
||||
An `IHostedService` (similar to `TelegramAdapter` in [[Telegram Channel]]) responsible for:
|
||||
- Registering `WebInterfaceChannel` instances with `IChannelManager` from [[Channels]].
|
||||
- Managing per-user or per-session channel lifecycle.
|
||||
|
||||
## Configuration
|
||||
|
||||
Will follow the existing [[Configuration]] options pattern with a `WebInterfaceOptions` class containing settings such as:
|
||||
- Authentication / authorization settings.
|
||||
- CORS policy.
|
||||
- Session timeout.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Expected Project References
|
||||
- `Luna.Channels.Abstractions`
|
||||
- `Luna.Configuration`
|
||||
- `Luna.Core.Abstractions`
|
||||
- `Luna.Shared`
|
||||
|
||||
## Namespace
|
||||
|
||||
`Luna.Channels.Web`
|
||||
Reference in New Issue
Block a user