Luna/Documentation/Luna AI Assistant/Core.md

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.

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.

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.

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.

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:

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