# 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