Only the delta.

1
2
3
4
5
6
7

<Project>
  <!-- V3 development. V2 is preserved by v2.0.0 and release/v2. -->
  <PropertyGroup>
    <VersionPrefix>3.0.0</VersionPrefix>
    <VersionSuffix>alpha.2</VersionSuffix>
  </PropertyGroup>
</Project>

1
2
3
4
5
6
7

<Project>
  <!-- Shared V2 release version. V1 remains on release/v1 and v1.0.0. -->
  <PropertyGroup>
    <VersionPrefix>2.0.1</VersionPrefix>
    <VersionSuffix></VersionSuffix>
  </PropertyGroup>
</Project>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

using Lilith.Core.Logging;
using Lilith.Core.Ollama;

namespace Lilith.Agent;

public partial class Lilith
{
    public bool IsBooted { get; private set; }

    public async Task BootAsync(bool startServerIfNotRunning = true)
    {
        using var operation = EnterOperation();
        try
        {
            if (IsBooted) return;
            if (string.IsNullOrWhiteSpace(Credentials.Model) || string.IsNullOrWhiteSpace(Credentials.SystemPrompt) ||
                string.IsNullOrWhiteSpace(Credentials.AgentName)) throw new ArgumentException("Model, system prompt, and agent name are required.");
            await Logger.TimeStageAsync("Total agent boot", () => BootCoreAsync(startServerIfNotRunning));
        }
        catch
        {
            _llmclient?.Dispose();
            _llmclient = null!;
            IsBooted = false;
            throw;
        }
    }

    private async Task BootCoreAsync(bool startServerIfNotRunning)
    {
        IsBooted = false;
        await Logger.TimeStageAsync("Client initialization", () => InitializeProviderAsync(startServerIfNotRunning));
        await Logger.TimeStageAsync("Chat readiness validation", () => { EnsureChatReadiness(); return Task.CompletedTask; });
        if (Credentials.Tts is { Enabled: true } options && _tts is null)
        {
            try
            {
                _tts = await Logger.TimeStageAsync("Kokoro initialization", () =>
                    global::Lilith.Core.Kokoro.KokoroTts.CreateAsync(Logger, options));
            }
            catch (Exception ex) { Logger.SystemWriteLine($"Speech unavailable: {ex.Message}. Text chat remains available.", LogColors.Orange); }
        }
        Logger.SystemWriteLine($"=== {Credentials.AgentName} AI Chat ({Credentials.Model} via {Credentials.Provider}) ===");
        Logger.SystemWriteLine("Type your message and press Enter. Type 'exit' to quit.\n");
        Logger.SystemPromptWriteLine($"SYSTEM: {Credentials.SystemPrompt}");
        await Logger.TimeStageAsync("Greeting generation", GreetingCoreAsync);
        Logger.SystemWriteLine("", LogColors.White);
        IsBooted = true;
    }

    public async Task GreetAsync()
    {
        using var operation = EnterOperation("Boot the agent before greeting.");
        await GreetingCoreAsync();
    }

    private async Task GreetingCoreAsync()
    {
        if (!EnableScenarios)
        {
            await ChatCoreAsync("Please greet the user.");
            return;
        }
        string greeting = await Client.RunScenarioAsync("greeting", new Dictionary<string, string>
        {
            ["agent_name"] = Credentials.AgentName
        });
        if (_tts is not null) await _tts.SpeakAsync(greeting);
    }

    private void EnsureChatReadiness()
    {
        _llmclient.IsNull();
        this.EnsureSystemPromptContent();
        this.EnsureContextInitialized();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

using Lilith.Core.Logging;
using Lilith.Core.Ollama;

namespace Lilith.Agent;

public partial class Lilith
{
    public bool IsBooted { get; private set; }

    public async Task BootAsync(bool startServerIfNotRunning = true)
    {
        using var operation = EnterOperation();
        try
        {
            if (IsBooted) return;
            if (string.IsNullOrWhiteSpace(Credentials.Model) || string.IsNullOrWhiteSpace(Credentials.SystemPrompt) ||
                string.IsNullOrWhiteSpace(Credentials.AgentName)) throw new ArgumentException("Model, system prompt, and agent name are required.");
            await Logger.TimeStageAsync("Total agent boot", () => BootCoreAsync(startServerIfNotRunning));
        }
        catch
        {
            _llmclient?.Dispose();
            _llmclient = null!;
            IsBooted = false;
            throw;
        }
    }

    private async Task BootCoreAsync(bool startServerIfNotRunning)
    {
        IsBooted = false;
        await Logger.TimeStageAsync("Client initialization", () => InitializeProviderAsync(startServerIfNotRunning));
        await Logger.TimeStageAsync("Chat readiness validation", () => { EnsureChatReadiness(); return Task.CompletedTask; });
        if (Credentials.Tts is { Enabled: true } options && _tts is null)
        {
            try
            {
                _tts = await Logger.TimeStageAsync("Kokoro initialization", () =>
                    global::Lilith.Core.Kokoro.KokoroTts.CreateAsync(Logger, options));
            }
            catch (Exception ex) { Logger.SystemWriteLine($"Speech unavailable: {ex.Message}. Text chat remains available.", LogColors.Orange); }
        }
        Logger.SystemWriteLine($"=== {Credentials.AgentName} AI Chat ({Credentials.Model} via {Credentials.Provider}) ===");
        Logger.SystemWriteLine("Type your message and press Enter. Type 'exit' to quit.\n");
        Logger.SystemPromptWriteLine($"SYSTEM: {Credentials.SystemPrompt}");
        await Logger.TimeStageAsync("Greeting generation", () => ChatCoreAsync("Please greet the user."));
        Logger.SystemWriteLine("", LogColors.White);
        IsBooted = true;
    }

    public async Task GreetAsync() => await ChatAsync("Please greet the user.");

    private void EnsureChatReadiness()
    {
        _llmclient.IsNull();
        this.EnsureSystemPromptContent();
        this.EnsureContextInitialized();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using System.Diagnostics;

namespace Lilith.Agent;

public partial class Lilith
{
    public async Task ChatAsync(string input, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation("Boot the agent before chatting.");
        await ChatCoreAsync(input, images, cancellationToken);
    }

    private async Task ChatCoreAsync(string input, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        var timer = Stopwatch.StartNew();
        string reply;
        try { reply = await Client.StreamReply(input, images, cancellationToken); }
        finally { timer.Stop(); }
        this.LogTokenCounts(timer.Elapsed);
        if (_tts is not null) await _tts.SpeakAsync(reply, cancellationToken);
    }

    private T WithConversation<T>(Func<ProviderClient, T> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        return action(Client);
    }

    private void WithConversation(Action<ProviderClient> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        action(Client);
    }

    public void NewConversation() => WithConversation(client => client.NewConversation());

    public void SaveConversation() => WithConversation(client => client.SaveConversation());

    public IReadOnlyList<ChatSessionSummary> ListConversations() => WithConversation(client => client.ListConversations());

    public bool LoadConversation(int displayIndex) => WithConversation(client => client.LoadConversation(displayIndex));

    public bool LoadConversation(string id) => WithConversation(client => client.LoadConversation(id));

    public void HandleHistoryCommand(string input)
    {
        var parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        if (parts.Length == 1)
        {
            var sessions = ListConversations();
            if (sessions.Count == 0)
            {
                Logger.HistoryWriteLine("No saved chats found.");
                return;
            }

            Logger.HistoryWriteLine("Saved chats:", LogColors.Cyan);
            for (int i = 0; i < sessions.Count; i++)
            {
                var session = sessions[i];
                Logger.HistoryWriteLine($"{i + 1}. {session.Title} ({session.UpdatedAt.LocalDateTime:g}, {session.MessageCount} messages)");
            }

            Logger.HistoryWriteLine("Use /history <number> to load a chat.");
            return;
        }

        if (!int.TryParse(parts[1], out int index))
        {
            Logger.HistoryWriteLine("Usage: /history or /history <number>", LogColors.Orange);
            return;
        }

        if (LoadConversation(index))
        {
            Logger.HistoryWriteLine($"Loaded saved chat #{index}.", LogColors.Cyan);
        }
        else
        {
            Logger.HistoryWriteLine($"Saved chat #{index} was not found.", LogColors.Orange);
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using System.Diagnostics;

namespace Lilith.Agent;

public partial class Lilith
{
    public async Task ChatAsync(string input, List<string>? images = null)
    {
        using var operation = EnterOperation("Boot the agent before chatting.");
        await ChatCoreAsync(input, images);
    }

    private async Task ChatCoreAsync(string input, List<string>? images = null)
    {
        var timer = Stopwatch.StartNew();
        string reply;
        try { reply = await Client.StreamReply(input, images); }
        finally { timer.Stop(); }
        this.LogTokenCounts(timer.Elapsed);
        if (_tts is not null) await _tts.SpeakAsync(reply);
    }

    private T WithConversation<T>(Func<ProviderClient, T> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        return action(Client);
    }

    private void WithConversation(Action<ProviderClient> action)
    {
        using var operation = EnterOperation("Boot the agent before using its conversation.");
        action(Client);
    }

    public void NewConversation() => WithConversation(client => client.NewConversation());

    public void SaveConversation() => WithConversation(client => client.SaveConversation());

    public IReadOnlyList<ChatSessionSummary> ListConversations() => WithConversation(client => client.ListConversations());

    public bool LoadConversation(int displayIndex) => WithConversation(client => client.LoadConversation(displayIndex));

    public bool LoadConversation(string id) => WithConversation(client => client.LoadConversation(id));

    public void HandleHistoryCommand(string input)
    {
        var parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        if (parts.Length == 1)
        {
            var sessions = ListConversations();
            if (sessions.Count == 0)
            {
                Logger.HistoryWriteLine("No saved chats found.");
                return;
            }

            Logger.HistoryWriteLine("Saved chats:", LogColors.Cyan);
            for (int i = 0; i < sessions.Count; i++)
            {
                var session = sessions[i];
                Logger.HistoryWriteLine($"{i + 1}. {session.Title} ({session.UpdatedAt.LocalDateTime:g}, {session.MessageCount} messages)");
            }

            Logger.HistoryWriteLine("Use /history <number> to load a chat.");
            return;
        }

        if (!int.TryParse(parts[1], out int index))
        {
            Logger.HistoryWriteLine("Usage: /history or /history <number>", LogColors.Orange);
            return;
        }

        if (LoadConversation(index))
        {
            Logger.HistoryWriteLine($"Loaded saved chat #{index}.", LogColors.Cyan);
        }
        else
        {
            Logger.HistoryWriteLine($"Saved chat #{index} was not found.", LogColors.Orange);
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

using Lilith.Core.Scenarios;

namespace Lilith.Agent;

public partial class Lilith
{
    partial void RegisterScenarioCommands(global::Lilith.Core.Commands.ChatCommandRegistry commands) =>
        commands.Register("subagents", "List agents; show or hide their detailed output.", context => SubagentCommands.Execute(Client, context.Arguments));
    private bool _showSubagentOutput;
    public bool ShowSubagentOutput
    {
        get => _llmclient?.ShowSubagentOutput ?? _showSubagentOutput;
        set { _showSubagentOutput = value; if (_llmclient is not null) _llmclient.ShowSubagentOutput = value; }
    }
    public SubagentSnapshot Subagents => Client.Subagents.Snapshot();

    public string HandleSubagentCommand(string command) => SubagentCommands.Execute(Client, command.Trim()[Math.Min(command.Trim().Length, "/subagents".Length)..]);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using Lilith.Core.Kokoro;

namespace Lilith.Agent;

public partial class Lilith(Action<LogEntry> onLog, LilithCredentials? credentials = null) : IAsyncDisposable
{
    private KokoroTts? _tts;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private ProviderClient _llmclient = null!;
    private readonly LilithCredentials _credentials = credentials ?? new();

    public LilithCredentials Credentials => _credentials;
    public Logger Logger { get; } = new(onLog);
    internal Func<bool, Task<ProviderClient>>? ProviderFactory { get; set; }

    private ProviderClient Client
    {
        get
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            return _llmclient ?? throw new InvalidOperationException("Boot the agent before using its conversation.");
        }
    }
    public ChatHistory History => Client.History;
    public int ContextMax => Client.ContextMax;
    public int CurrentContextTokens => Client.CurrentContextTokens;

    private async Task InitializeProviderAsync(bool startServerIfNotRunning)
    {
        _llmclient = ProviderFactory is { } factory ? await factory(startServerIfNotRunning) : await this.CreateClient(startServerIfNotRunning);
        _llmclient.ShowSubagentOutput = _showSubagentOutput;
        foreach (var tool in Tools) _llmclient.RegisterTool(tool);
        if (EnableScenarios) global::Lilith.Core.Scenarios.ScenarioTools.Register(_llmclient, ScenarioRoot);
    }

    public bool EnableScenarios { get; set; } = true;
    public string? ScenarioRoot { get; set; }

    /// <summary>Configure before boot. The template is deliberately not enabled.</summary>
    public List<global::Lilith.Core.Tools.ILilithTool> Tools { get; } = [new global::Lilith.Core.Tools.CurrentTimeTool()];

    private IDisposable EnterOperation(string? bootRequiredMessage = null)
    {
        var operation = _operation.EnterOrThrow("An agent operation is already in progress.");
        try
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            if (bootRequiredMessage is not null && !IsBooted) throw new InvalidOperationException(bootRequiredMessage);
            return operation;
        }
        catch { operation.Dispose(); throw; }
    }

    public async ValueTask DisposeAsync()
    {
        using var operation = await _operation.EnterAsync();
        if (_disposed) return;
        _disposed = true;
        try { if (_tts is not null) await _tts.DisposeAsync(); }
        finally { _llmclient?.Dispose(); IsBooted = false; }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

using Lilith.Core.Logging;
using Lilith.Core.Ollama;
using Lilith.Core.Providers;
using Lilith.Core.Kokoro;

namespace Lilith.Agent;

public partial class Lilith(Action<LogEntry> onLog, LilithCredentials? credentials = null) : IAsyncDisposable
{
    private KokoroTts? _tts;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private ProviderClient _llmclient = null!;
    private readonly LilithCredentials _credentials = credentials ?? new();

    public LilithCredentials Credentials => _credentials;
    public Logger Logger { get; } = new(onLog);
    internal Func<bool, Task<ProviderClient>>? ProviderFactory { get; set; }

    private ProviderClient Client
    {
        get
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            return _llmclient ?? throw new InvalidOperationException("Boot the agent before using its conversation.");
        }
    }
    public ChatHistory History => Client.History;
    public int ContextMax => Client.ContextMax;
    public int CurrentContextTokens => Client.CurrentContextTokens;

    private async Task InitializeProviderAsync(bool startServerIfNotRunning)
    {
        _llmclient = ProviderFactory is { } factory ? await factory(startServerIfNotRunning) : await this.CreateClient(startServerIfNotRunning);
        foreach (var tool in Tools) _llmclient.RegisterTool(tool);
    }

    /// <summary>Configure before boot. The template is deliberately not enabled.</summary>
    public List<global::Lilith.Core.Tools.ILilithTool> Tools { get; } = [new global::Lilith.Core.Tools.CurrentTimeTool()];

    private IDisposable EnterOperation(string? bootRequiredMessage = null)
    {
        var operation = _operation.EnterOrThrow("An agent operation is already in progress.");
        try
        {
            ObjectDisposedException.ThrowIf(_disposed, this);
            if (bootRequiredMessage is not null && !IsBooted) throw new InvalidOperationException(bootRequiredMessage);
            return operation;
        }
        catch { operation.Dispose(); throw; }
    }

    public async ValueTask DisposeAsync()
    {
        using var operation = await _operation.EnterAsync();
        if (_disposed) return;
        _disposed = true;
        try { if (_tts is not null) await _tts.DisposeAsync(); }
        finally { _llmclient?.Dispose(); IsBooted = false; }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>Lilith.Core</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="KokoroSharp.CPU" Version="0.8.4" />
    <Content Include="Scenarios/Definitions/*.xml" Link="Scenarios/%(Filename)%(Extension)"
             CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
  </ItemGroup>
</Project>

1
2
3
4
5
6
7
8
9
10
11
12
13

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>Lilith.Core</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="KokoroSharp.CPU" Version="0.8.4" />
  </ItemGroup>
</Project>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

using System.Net.Http.Headers;
using System.Text.Json;
using Lilith.Core.Tools;

namespace Lilith.Core.LMStudio;

public sealed class LMStudioClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null)
    : ProviderClient(logger, historyStore, httpClient)
{
    public string BaseUrl { get; init; } = LMStudioSetup.BaseUrl;

    protected override async Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages)
        => await GenerateReplyAsync(messages, CancellationToken.None);

    protected override async Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages, CancellationToken cancellationToken)
    {
        if (messages.Any(m => m.Images?.Count > 0))
            throw new NotSupportedException("LM Studio image input is not implemented in this interface.");
        using var request = HttpExtensions.JsonRequest(BaseUrl + "/v1/chat/completions", new
        {
            model = Model,
            stream = false,
            messages = messages.Select(ToWireMessage),
            tools = ToolDefinitions
        });
        LMStudioSetup.Authorize(request);
        using var json = await Http.SendJsonDocumentAsync(request, cancellationToken);
        var choice = json.RootElement.GetProperty("choices")[0];
        string? finish = choice.GetProperty("finish_reason").GetString();
        if (finish is not ("stop" or "tool_calls"))
            throw new InvalidDataException("LM Studio did not return a complete text reply.");
        var message = choice.GetProperty("message");
        if (message.GetProperty("role").GetString() != "assistant")
            throw new InvalidDataException("LM Studio returned an invalid assistant message.");
        List<ToolCall>? calls = null;
        if (message.TryGetProperty("tool_calls", out var toolCalls) && toolCalls.ValueKind != JsonValueKind.Null)
        {
            calls = [];
            foreach (var call in toolCalls.EnumerateArray())
            {
                if (call.GetProperty("type").GetString() != "function" ||
                    string.IsNullOrWhiteSpace(call.GetProperty("id").GetString()))
                    throw new InvalidDataException("Invalid LM Studio function call.");
                var function = call.GetProperty("function");
                using var arguments = JsonDocument.Parse(function.GetProperty("arguments").GetString()!);
                calls.Add(new ToolCall(new ToolFunction(function.GetProperty("name").GetString()!, arguments.RootElement.Clone()),
                    call.GetProperty("id").GetString()));
            }
            if (calls.Select(c => c.Id).Distinct().Count() != calls.Count)
                throw new InvalidDataException("Duplicate LM Studio tool call IDs.");
        }
        if ((finish == "tool_calls") != (calls is { Count: > 0 }))
            throw new InvalidDataException("LM Studio tool calls do not match the finish reason.");
        string? content = message.TryGetProperty("content", out var text) && text.ValueKind == JsonValueKind.String ? text.GetString() : null;
        if (calls is not { Count: > 0 } && content is null)
            throw new InvalidDataException("LM Studio returned no assistant content.");
        int? prompt = null, completion = null;
        if (json.RootElement.TryGetProperty("usage", out var usage))
        {
            if (usage.TryGetProperty("prompt_tokens", out var p)) prompt = p.GetInt32();
            if (usage.TryGetProperty("completion_tokens", out var c)) completion = c.GetInt32();
        }
        return new ChatChunk(new ChatMessage("assistant", content ?? string.Empty, ToolCalls: calls), true, prompt, completion);
    }

    private static object ToWireMessage(ChatMessage message)
    {
        var wire = new Dictionary<string, object?> { ["role"] = message.Role, ["content"] = message.Content };
        if (message.ToolCallId is { } id) wire["tool_call_id"] = id;
        if (message.ToolCalls is { Count: > 0 } calls)
            wire["tool_calls"] = calls.Select(c => new
            {
                id = c.Id, type = "function",
                function = new { name = c.Function.Name, arguments = c.Function.Arguments.GetRawText() }
            }).ToArray();
        return wire;
    }

    public override ProviderClient CreateScenarioBranch(string prompt, Logger branchLogger, ChatHistoryStore store)
    {
        var child = new LMStudioClient(branchLogger, store, Http)
        {
            Model = Model, BaseUrl = BaseUrl, SystemPrompt = prompt, NumCtx = NumCtx, AgentName = "Scenario"
        };
        child.InitializeConversation();
        return child;
    }

    public static async Task<LMStudioClient> CreateClient(string model, string systemPrompt, Logger logger,
        bool startServerIfNotRunning, string agentName = "Lilith", ChatHistoryStore? historyStore = null)
    {
        await LMStudioSetup.EnsureServerAsync(logger, startServerIfNotRunning);
        var client = new LMStudioClient(logger, historyStore) { Model = model, SystemPrompt = systemPrompt, AgentName = agentName };
        try
        {
            var models = await LMStudioSetup.ListModelsAsync();
            var selected = models.FirstOrDefault(m => m.Id == model)
                ?? throw new InvalidOperationException($"LM Studio model '{model}' is not downloaded. Run setup first.");
            if (selected.InstanceId is not null && selected.ContextLength is > 0)
            {
                client.Model = selected.InstanceId;
                client.NumCtx = selected.ContextLength.Value;
            }
            else
            {
                using var request = HttpExtensions.JsonRequest(client.BaseUrl + "/api/v1/models/load", new { model, echo_load_config = true });
                LMStudioSetup.Authorize(request);
                using var json = await client.Http.SendJsonDocumentAsync(request);
                client.Model = json.RootElement.GetProperty("instance_id").GetString()!;
                client.NumCtx = json.RootElement.GetProperty("load_config").GetProperty("context_length").GetInt32();
            }
            if (client.NumCtx <= 0) throw new InvalidDataException("LM Studio reported an invalid context window.");
            client.InitializeConversation();
            return client;
        }
        catch { client.Dispose(); throw; }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

using System.Net.Http.Headers;
using System.Text.Json;
using Lilith.Core.Tools;

namespace Lilith.Core.LMStudio;

public sealed class LMStudioClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null)
    : ProviderClient(logger, historyStore, httpClient)
{
    public string BaseUrl { get; init; } = LMStudioSetup.BaseUrl;

    protected override async Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages)
    {
        if (messages.Any(m => m.Images?.Count > 0))
            throw new NotSupportedException("LM Studio image input is not implemented in this interface.");
        using var request = HttpExtensions.JsonRequest(BaseUrl + "/v1/chat/completions", new
        {
            model = Model,
            stream = false,
            messages = messages.Select(ToWireMessage),
            tools = ToolDefinitions
        });
        LMStudioSetup.Authorize(request);
        using var json = await Http.SendJsonDocumentAsync(request);
        var choice = json.RootElement.GetProperty("choices")[0];
        string? finish = choice.GetProperty("finish_reason").GetString();
        if (finish is not ("stop" or "tool_calls"))
            throw new InvalidDataException("LM Studio did not return a complete text reply.");
        var message = choice.GetProperty("message");
        if (message.GetProperty("role").GetString() != "assistant")
            throw new InvalidDataException("LM Studio returned an invalid assistant message.");
        List<ToolCall>? calls = null;
        if (message.TryGetProperty("tool_calls", out var toolCalls) && toolCalls.ValueKind != JsonValueKind.Null)
        {
            calls = [];
            foreach (var call in toolCalls.EnumerateArray())
            {
                if (call.GetProperty("type").GetString() != "function" ||
                    string.IsNullOrWhiteSpace(call.GetProperty("id").GetString()))
                    throw new InvalidDataException("Invalid LM Studio function call.");
                var function = call.GetProperty("function");
                using var arguments = JsonDocument.Parse(function.GetProperty("arguments").GetString()!);
                calls.Add(new ToolCall(new ToolFunction(function.GetProperty("name").GetString()!, arguments.RootElement.Clone()),
                    call.GetProperty("id").GetString()));
            }
            if (calls.Select(c => c.Id).Distinct().Count() != calls.Count)
                throw new InvalidDataException("Duplicate LM Studio tool call IDs.");
        }
        if ((finish == "tool_calls") != (calls is { Count: > 0 }))
            throw new InvalidDataException("LM Studio tool calls do not match the finish reason.");
        string? content = message.TryGetProperty("content", out var text) && text.ValueKind == JsonValueKind.String ? text.GetString() : null;
        if (calls is not { Count: > 0 } && content is null)
            throw new InvalidDataException("LM Studio returned no assistant content.");
        int? prompt = null, completion = null;
        if (json.RootElement.TryGetProperty("usage", out var usage))
        {
            if (usage.TryGetProperty("prompt_tokens", out var p)) prompt = p.GetInt32();
            if (usage.TryGetProperty("completion_tokens", out var c)) completion = c.GetInt32();
        }
        return new ChatChunk(new ChatMessage("assistant", content ?? string.Empty, ToolCalls: calls), true, prompt, completion);
    }

    private static object ToWireMessage(ChatMessage message)
    {
        var wire = new Dictionary<string, object?> { ["role"] = message.Role, ["content"] = message.Content };
        if (message.ToolCallId is { } id) wire["tool_call_id"] = id;
        if (message.ToolCalls is { Count: > 0 } calls)
            wire["tool_calls"] = calls.Select(c => new
            {
                id = c.Id, type = "function",
                function = new { name = c.Function.Name, arguments = c.Function.Arguments.GetRawText() }
            }).ToArray();
        return wire;
    }

    public static async Task<LMStudioClient> CreateClient(string model, string systemPrompt, Logger logger,
        bool startServerIfNotRunning, string agentName = "Lilith", ChatHistoryStore? historyStore = null)
    {
        await LMStudioSetup.EnsureServerAsync(logger, startServerIfNotRunning);
        var client = new LMStudioClient(logger, historyStore) { Model = model, SystemPrompt = systemPrompt, AgentName = agentName };
        try
        {
            var models = await LMStudioSetup.ListModelsAsync();
            var selected = models.FirstOrDefault(m => m.Id == model)
                ?? throw new InvalidOperationException($"LM Studio model '{model}' is not downloaded. Run setup first.");
            if (selected.InstanceId is not null && selected.ContextLength is > 0)
            {
                client.Model = selected.InstanceId;
                client.NumCtx = selected.ContextLength.Value;
            }
            else
            {
                using var request = HttpExtensions.JsonRequest(client.BaseUrl + "/api/v1/models/load", new { model, echo_load_config = true });
                LMStudioSetup.Authorize(request);
                using var json = await client.Http.SendJsonDocumentAsync(request);
                client.Model = json.RootElement.GetProperty("instance_id").GetString()!;
                client.NumCtx = json.RootElement.GetProperty("load_config").GetProperty("context_length").GetInt32();
            }
            if (client.NumCtx <= 0) throw new InvalidDataException("LM Studio reported an invalid context window.");
            client.InitializeConversation();
            return client;
        }
        catch { client.Dispose(); throw; }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339

using System.Diagnostics;

namespace Lilith.Core.Ollama;

public class OllamaClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null) : ProviderClient(logger, historyStore, httpClient)
{
    private const string StatusBlue = "#AAAAFF";
    private const string StatusGray = "#AAAAAA";
    private bool _contextKnown;

    public string BaseUrl { get; } = "http://localhost:11434";
    public string ChatApiUrl => $"{BaseUrl}/api/chat";
    public string ShowApiUrl => $"{BaseUrl}/api/show";
    protected override async Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages)
        => await GenerateReplyAsync(messages, CancellationToken.None);

    protected override async Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages, CancellationToken cancellationToken)
    {
        var request = new ChatRequest(Model, messages, Stream: false, Options: _contextKnown ? new ChatOptions(NumCtx) : null,
            Tools: ToolDefinitions);
        using HttpRequestMessage httpReq = HttpExtensions.JsonRequest(ChatApiUrl, request);
        return await Http.SendJsonAsync<ChatChunk>(httpReq, cancellationToken);
    }

    public override ProviderClient CreateScenarioBranch(string prompt, Logger branchLogger, ChatHistoryStore store)
    {
        var child = new OllamaClient(branchLogger, store, Http)
        {
            Model = Model, SystemPrompt = prompt, NumCtx = NumCtx, _contextKnown = _contextKnown,
            AgentName = "Scenario"
        };
        child.InitializeConversation();
        return child;
    }
    /// <summary>Connects to a prepared model; never installs Ollama or downloads a model.</summary>
    public static async Task<OllamaClient> CreateClient(
        string model,
        string systemPrompt,
        Logger logger,
        bool startOllamaIfNotRunning,
        string agentName = "Lilith", ChatHistoryStore? historyStore = null)
    {
        var client = new OllamaClient(logger, historyStore)
        {
            Model = model,
            SystemPrompt = systemPrompt,
            AgentName = agentName
        };
        client.InitializeConversation();

        client.PrintStatus($"Initializing client for model '{model}'...", StatusBlue);

        try
        {
            await logger.TimeStageAsync("Server readiness", () => EnsureServerAsync(logger, startOllamaIfNotRunning));
            bool available = await logger.TimeStageAsync("Model readiness", () => IsModelAvailableAsync(model));
            if (!available) throw new InvalidOperationException($"Model '{model}' is not installed. Run console setup to choose and download a model.");
            client.NumCtx = await logger.TimeStageAsync("Model specifications", client.GetModelContextSizeAsync);
            client.PrintStatus(client._contextKnown ? $"Context window: {client.NumCtx:N0} tokens." :
                $"Context size is unknown; usage uses a {client.NumCtx:N0}-token estimate and Ollama selects its own request default.",
                client._contextKnown ? LogColors.Green : LogColors.Orange);
            return client;
        }
        catch
        {
            client.Http.Dispose();
            throw;
        }
    }

    internal async Task<int> GetModelContextSizeAsync()
    {
        _contextKnown = false;
        try
        {
            var request = new ShowModelRequest(Model);
            using HttpRequestMessage httpReq = HttpExtensions.JsonRequest(ShowApiUrl, request);
            using HttpResponseMessage httpResp = await Http.SendAsync(httpReq);
            if (!httpResp.IsSuccessStatusCode)
            {
                PrintStatus("Could not retrieve model specs; retaining Ollama defaults (context estimate: 4,096 tokens).", LogColors.Orange);
                return 4096;
            }

            string json = await httpResp.Content.ReadAsStringAsync();
            ShowModelResponse? response = json.Deserialize<ShowModelResponse>();
            if (response?.ModelInfo is { } info)
            {
                foreach (var kv in info)
                {
                    if (kv.Key.EndsWith(".context_length", StringComparison.Ordinal) && kv.Value.TryGetInt32(out int ctx) && ctx > 0)
                    {
                        _contextKnown = true;
                        return ctx;
                    }
                }
            }
        }
        catch (Exception ex)
        {
            PrintStatus($"Model spec query failed ({ex.Message}); retaining Ollama defaults (context estimate: 4,096 tokens).", LogColors.Orange);
        }

        PrintStatus("Valid model context metadata is unavailable; retaining Ollama defaults (context estimate: 4,096 tokens).", LogColors.Orange);
        return 4096;
    }

    public static async Task EnsureServerAsync(Logger logger, bool startIfMissing = true)
    {
        using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(2) };
        if (await http.IsReachableAsync("http://localhost:11434/")) { logger.WriteInfo("Ollama", "Ollama server already running; skipping server start."); return; }
        if (!startIfMissing) throw new InvalidOperationException("Ollama server is not running.");
        var psi = new ProcessStartInfo(ResolveExecutable()) { UseShellExecute = false, CreateNoWindow = true };
        psi.ArgumentList.Add("serve");
        using var server = Process.Start(psi) ?? throw new InvalidOperationException("Could not start Ollama server.");
        var timer = Stopwatch.StartNew();
        while (timer.Elapsed < TimeSpan.FromSeconds(60))
        {
            if (await http.IsReachableAsync("http://localhost:11434/")) return;
            // The installer/app may already own the port while still discovering GPUs.
            // An exited second serve process does not prove that the API cannot become ready.
            await Task.Delay(500);
        }
        if (!server.HasExited) server.Kill(entireProcessTree: true);
        throw new TimeoutException(server.HasExited
            ? $"Ollama API did not become ready within 60 seconds (startup process exit {server.ExitCode})."
            : "Ollama server did not become ready within 60 seconds.");
    }

    private static string ResolveExecutable()
    {
        string installed = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "Programs", "Ollama", "ollama.exe");
        return File.Exists(installed) ? installed : "ollama";
    }

    public static bool IsOllamaInstalled()
    {
        try
        {
            var psi = new ProcessStartInfo(ResolveExecutable(), "--version")
            {
                CreateNoWindow = true,
                UseShellExecute = false,
                RedirectStandardOutput = true,
                RedirectStandardError = true,
            };
            using var proc = Process.Start(psi);
            if (proc == null)
            {
                return false;
            }

            Task stdout = proc.StandardOutput.ReadToEndAsync();
            Task stderr = proc.StandardError.ReadToEndAsync();

            if (!proc.WaitForExit(5000))
            {
                try
                {
                    proc.Kill();
                }
                catch
                {
                    // ignore
                }

                return false;
            }

            Task.WaitAll(stdout, stderr);
            return proc.ExitCode == 0;
        }
        catch
        {
            return false;
        }
    }

    private static async Task<bool> PullModelAsync(OllamaClient client)
    {
        try
        {
            client.PrintStatus($"Pulling model '{client.Model}'…", StatusBlue);

            var psi = new ProcessStartInfo
            {
                FileName = ResolveExecutable(),
                CreateNoWindow = true,
                UseShellExecute = false,
                RedirectStandardOutput = true,
                RedirectStandardError = true,
            };
            psi.ArgumentList.Add("pull");
            psi.ArgumentList.Add(client.Model);

            using var proc = Process.Start(psi);
            if (proc is null)
            {
                client.PrintStatus("Could not start ollama pull process.", LogColors.Red);
                return false;
            }

            var tracker = new OllamaCliProgressTracker(client.Model);
            Task stdoutTask = OllamaCliStreamReader.PumpAsync(proc.StandardOutput, tracker);
            Task stderrTask = OllamaCliStreamReader.PumpAsync(proc.StandardError, tracker);

            DateTime started = DateTime.UtcNow;
            DateTime deadline = started.AddMinutes(30);
            while (!proc.HasExited && DateTime.UtcNow < deadline)
            {
                TimeSpan elapsed = DateTime.UtcNow - started;
                TimeSpan remaining = deadline - DateTime.UtcNow;
                client.PrintProgress(tracker.GetDisplayMessage(elapsed, remaining), StatusGray);
                await Task.Delay(250);
            }

            if (!proc.HasExited)
            {
                proc.Kill(entireProcessTree: true);
                await proc.WaitForExitAsync();
                await Task.WhenAll(stdoutTask, stderrTask);
                throw new TimeoutException("Model download exceeded 30 minutes.");
            }
            await proc.WaitForExitAsync();
            await Task.WhenAll(stdoutTask, stderrTask);

            if (proc.ExitCode != 0 && !await IsModelAvailableAsync(client.Model))
            {
                client.PrintStatus($"ollama pull failed (exit {proc.ExitCode}).", LogColors.Red);
                return false;
            }

            if (await IsModelAvailableAsync(client.Model))
            {
                client.PrintStatus(
                    $"Model '{client.Model}' ready ({(DateTime.UtcNow - started):mm\\:ss}).",
                    LogColors.Green);
                return true;
            }

            client.PrintStatus($"Timed out waiting for model '{client.Model}' to become available.", LogColors.Orange);
            if (!proc.HasExited)
            {
                proc.Kill(entireProcessTree: true);
            }

            return false;
        }
        catch (Exception ex)
        {
            client.PrintStatus($"Model pull error: {ex.Message}", LogColors.Red);
            return false;
        }
    }

    public static async Task<bool> IsModelAvailableAsync(string model)
    {
        using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
        using var request = HttpExtensions.JsonRequest("http://localhost:11434/api/show", new ShowModelRequest(model));
        using var response = await http.SendAsync(request);
        if (response.StatusCode == System.Net.HttpStatusCode.NotFound) return false;
        response.EnsureSuccessStatusCode();
        return true;
    }

    public static async Task InstallAsync(Logger logger)
    {
        using var client = new OllamaClient(logger);
        if (!await InstallOllamaAsync(client)) throw new InvalidOperationException("Ollama installation failed. Relaunch setup to retry.");
    }

    public static async Task DownloadModelAsync(string model, Logger logger)
    {
        using var client = new OllamaClient(logger) { Model = model };
        if (!await PullModelAsync(client)) throw new InvalidOperationException($"Model '{model}' download failed. Relaunch setup to retry.");
    }

    private static async Task<bool> InstallOllamaAsync(OllamaClient client)
    {
        try
        {
            var psi = new ProcessStartInfo
            {
                FileName = "powershell",
                Arguments = "-NoProfile -ExecutionPolicy Bypass -Command " +
                            "\"irm https://ollama.com/install.ps1 | iex\"",
                CreateNoWindow = true,
                UseShellExecute = false,
                RedirectStandardOutput = true,
                RedirectStandardError = true,
            };

            using var proc = Process.Start(psi);
            if (proc == null)
            {
                return false;
            }

            proc.OutputDataReceived += (_, e) =>
            {
                if (!string.IsNullOrEmpty(e.Data))
                {
                    client.PrintInstallerOutput(e.Data, StatusGray);
                }
            };
            proc.ErrorDataReceived += (_, e) =>
            {
                if (!string.IsNullOrEmpty(e.Data))
                {
                    client.PrintInstallerOutput(e.Data, LogColors.Orange);
                }
            };
            proc.BeginOutputReadLine();
            proc.BeginErrorReadLine();

            await proc.WaitForExitOrKillAsync(TimeSpan.FromMinutes(10), "Ollama installation timed out.");
            return proc.ExitCode == 0 && IsOllamaInstalled();
        }
        catch (Exception ex)
        {
            client.PrintStatus($"Installer error: {ex.Message}", LogColors.Red);
            return false;
        }
    }

    private void PrintStatus(string message, string color) =>
        Logger.WriteLine("Ollama", message, color);

    internal void PrintInstallerOutput(string message, string color)
    {
        if (RegexPatterns.InstallerProgress().IsMatch(message))
            PrintProgress(message.Trim(), color);
        else
            PrintStatus(message, color);
    }

    private void PrintProgress(string message, string color) =>
        Logger.WriteProgress("Ollama", message, color);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325

using System.Diagnostics;

namespace Lilith.Core.Ollama;

public class OllamaClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null) : ProviderClient(logger, historyStore, httpClient)
{
    private const string StatusBlue = "#AAAAFF";
    private const string StatusGray = "#AAAAAA";
    private bool _contextKnown;

    public string BaseUrl { get; } = "http://localhost:11434";
    public string ChatApiUrl => $"{BaseUrl}/api/chat";
    public string ShowApiUrl => $"{BaseUrl}/api/show";
    protected override async Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages)
    {
        var request = new ChatRequest(Model, messages, Stream: false, Options: _contextKnown ? new ChatOptions(NumCtx) : null,
            Tools: ToolDefinitions);
        using HttpRequestMessage httpReq = HttpExtensions.JsonRequest(ChatApiUrl, request);
        return await Http.SendJsonAsync<ChatChunk>(httpReq);
    }
    /// <summary>Connects to a prepared model; never installs Ollama or downloads a model.</summary>
    public static async Task<OllamaClient> CreateClient(
        string model,
        string systemPrompt,
        Logger logger,
        bool startOllamaIfNotRunning,
        string agentName = "Lilith", ChatHistoryStore? historyStore = null)
    {
        var client = new OllamaClient(logger, historyStore)
        {
            Model = model,
            SystemPrompt = systemPrompt,
            AgentName = agentName
        };
        client.InitializeConversation();

        client.PrintStatus($"Initializing client for model '{model}'...", StatusBlue);

        try
        {
            await logger.TimeStageAsync("Server readiness", () => EnsureServerAsync(logger, startOllamaIfNotRunning));
            bool available = await logger.TimeStageAsync("Model readiness", () => IsModelAvailableAsync(model));
            if (!available) throw new InvalidOperationException($"Model '{model}' is not installed. Run console setup to choose and download a model.");
            client.NumCtx = await logger.TimeStageAsync("Model specifications", client.GetModelContextSizeAsync);
            client.PrintStatus(client._contextKnown ? $"Context window: {client.NumCtx:N0} tokens." :
                $"Context size is unknown; usage uses a {client.NumCtx:N0}-token estimate and Ollama selects its own request default.",
                client._contextKnown ? LogColors.Green : LogColors.Orange);
            return client;
        }
        catch
        {
            client.Http.Dispose();
            throw;
        }
    }

    internal async Task<int> GetModelContextSizeAsync()
    {
        _contextKnown = false;
        try
        {
            var request = new ShowModelRequest(Model);
            using HttpRequestMessage httpReq = HttpExtensions.JsonRequest(ShowApiUrl, request);
            using HttpResponseMessage httpResp = await Http.SendAsync(httpReq);
            if (!httpResp.IsSuccessStatusCode)
            {
                PrintStatus("Could not retrieve model specs; retaining Ollama defaults (context estimate: 4,096 tokens).", LogColors.Orange);
                return 4096;
            }

            string json = await httpResp.Content.ReadAsStringAsync();
            ShowModelResponse? response = json.Deserialize<ShowModelResponse>();
            if (response?.ModelInfo is { } info)
            {
                foreach (var kv in info)
                {
                    if (kv.Key.EndsWith(".context_length", StringComparison.Ordinal) && kv.Value.TryGetInt32(out int ctx) && ctx > 0)
                    {
                        _contextKnown = true;
                        return ctx;
                    }
                }
            }
        }
        catch (Exception ex)
        {
            PrintStatus($"Model spec query failed ({ex.Message}); retaining Ollama defaults (context estimate: 4,096 tokens).", LogColors.Orange);
        }

        PrintStatus("Valid model context metadata is unavailable; retaining Ollama defaults (context estimate: 4,096 tokens).", LogColors.Orange);
        return 4096;
    }

    public static async Task EnsureServerAsync(Logger logger, bool startIfMissing = true)
    {
        using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(2) };
        if (await http.IsReachableAsync("http://localhost:11434/")) { logger.WriteInfo("Ollama", "Ollama server already running; skipping server start."); return; }
        if (!startIfMissing) throw new InvalidOperationException("Ollama server is not running.");
        var psi = new ProcessStartInfo(ResolveExecutable()) { UseShellExecute = false, CreateNoWindow = true };
        psi.ArgumentList.Add("serve");
        using var server = Process.Start(psi) ?? throw new InvalidOperationException("Could not start Ollama server.");
        var timer = Stopwatch.StartNew();
        while (timer.Elapsed < TimeSpan.FromSeconds(60))
        {
            if (await http.IsReachableAsync("http://localhost:11434/")) return;
            // The installer/app may already own the port while still discovering GPUs.
            // An exited second serve process does not prove that the API cannot become ready.
            await Task.Delay(500);
        }
        if (!server.HasExited) server.Kill(entireProcessTree: true);
        throw new TimeoutException(server.HasExited
            ? $"Ollama API did not become ready within 60 seconds (startup process exit {server.ExitCode})."
            : "Ollama server did not become ready within 60 seconds.");
    }

    private static string ResolveExecutable()
    {
        string installed = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "Programs", "Ollama", "ollama.exe");
        return File.Exists(installed) ? installed : "ollama";
    }

    public static bool IsOllamaInstalled()
    {
        try
        {
            var psi = new ProcessStartInfo(ResolveExecutable(), "--version")
            {
                CreateNoWindow = true,
                UseShellExecute = false,
                RedirectStandardOutput = true,
                RedirectStandardError = true,
            };
            using var proc = Process.Start(psi);
            if (proc == null)
            {
                return false;
            }

            Task stdout = proc.StandardOutput.ReadToEndAsync();
            Task stderr = proc.StandardError.ReadToEndAsync();

            if (!proc.WaitForExit(5000))
            {
                try
                {
                    proc.Kill();
                }
                catch
                {
                    // ignore
                }

                return false;
            }

            Task.WaitAll(stdout, stderr);
            return proc.ExitCode == 0;
        }
        catch
        {
            return false;
        }
    }

    private static async Task<bool> PullModelAsync(OllamaClient client)
    {
        try
        {
            client.PrintStatus($"Pulling model '{client.Model}'…", StatusBlue);

            var psi = new ProcessStartInfo
            {
                FileName = ResolveExecutable(),
                CreateNoWindow = true,
                UseShellExecute = false,
                RedirectStandardOutput = true,
                RedirectStandardError = true,
            };
            psi.ArgumentList.Add("pull");
            psi.ArgumentList.Add(client.Model);

            using var proc = Process.Start(psi);
            if (proc is null)
            {
                client.PrintStatus("Could not start ollama pull process.", LogColors.Red);
                return false;
            }

            var tracker = new OllamaCliProgressTracker(client.Model);
            Task stdoutTask = OllamaCliStreamReader.PumpAsync(proc.StandardOutput, tracker);
            Task stderrTask = OllamaCliStreamReader.PumpAsync(proc.StandardError, tracker);

            DateTime started = DateTime.UtcNow;
            DateTime deadline = started.AddMinutes(30);
            while (!proc.HasExited && DateTime.UtcNow < deadline)
            {
                TimeSpan elapsed = DateTime.UtcNow - started;
                TimeSpan remaining = deadline - DateTime.UtcNow;
                client.PrintProgress(tracker.GetDisplayMessage(elapsed, remaining), StatusGray);
                await Task.Delay(250);
            }

            if (!proc.HasExited)
            {
                proc.Kill(entireProcessTree: true);
                await proc.WaitForExitAsync();
                await Task.WhenAll(stdoutTask, stderrTask);
                throw new TimeoutException("Model download exceeded 30 minutes.");
            }
            await proc.WaitForExitAsync();
            await Task.WhenAll(stdoutTask, stderrTask);

            if (proc.ExitCode != 0 && !await IsModelAvailableAsync(client.Model))
            {
                client.PrintStatus($"ollama pull failed (exit {proc.ExitCode}).", LogColors.Red);
                return false;
            }

            if (await IsModelAvailableAsync(client.Model))
            {
                client.PrintStatus(
                    $"Model '{client.Model}' ready ({(DateTime.UtcNow - started):mm\\:ss}).",
                    LogColors.Green);
                return true;
            }

            client.PrintStatus($"Timed out waiting for model '{client.Model}' to become available.", LogColors.Orange);
            if (!proc.HasExited)
            {
                proc.Kill(entireProcessTree: true);
            }

            return false;
        }
        catch (Exception ex)
        {
            client.PrintStatus($"Model pull error: {ex.Message}", LogColors.Red);
            return false;
        }
    }

    public static async Task<bool> IsModelAvailableAsync(string model)
    {
        using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
        using var request = HttpExtensions.JsonRequest("http://localhost:11434/api/show", new ShowModelRequest(model));
        using var response = await http.SendAsync(request);
        if (response.StatusCode == System.Net.HttpStatusCode.NotFound) return false;
        response.EnsureSuccessStatusCode();
        return true;
    }

    public static async Task InstallAsync(Logger logger)
    {
        using var client = new OllamaClient(logger);
        if (!await InstallOllamaAsync(client)) throw new InvalidOperationException("Ollama installation failed. Relaunch setup to retry.");
    }

    public static async Task DownloadModelAsync(string model, Logger logger)
    {
        using var client = new OllamaClient(logger) { Model = model };
        if (!await PullModelAsync(client)) throw new InvalidOperationException($"Model '{model}' download failed. Relaunch setup to retry.");
    }

    private static async Task<bool> InstallOllamaAsync(OllamaClient client)
    {
        try
        {
            var psi = new ProcessStartInfo
            {
                FileName = "powershell",
                Arguments = "-NoProfile -ExecutionPolicy Bypass -Command " +
                            "\"irm https://ollama.com/install.ps1 | iex\"",
                CreateNoWindow = true,
                UseShellExecute = false,
                RedirectStandardOutput = true,
                RedirectStandardError = true,
            };

            using var proc = Process.Start(psi);
            if (proc == null)
            {
                return false;
            }

            proc.OutputDataReceived += (_, e) =>
            {
                if (!string.IsNullOrEmpty(e.Data))
                {
                    client.PrintInstallerOutput(e.Data, StatusGray);
                }
            };
            proc.ErrorDataReceived += (_, e) =>
            {
                if (!string.IsNullOrEmpty(e.Data))
                {
                    client.PrintInstallerOutput(e.Data, LogColors.Orange);
                }
            };
            proc.BeginOutputReadLine();
            proc.BeginErrorReadLine();

            await proc.WaitForExitOrKillAsync(TimeSpan.FromMinutes(10), "Ollama installation timed out.");
            return proc.ExitCode == 0 && IsOllamaInstalled();
        }
        catch (Exception ex)
        {
            client.PrintStatus($"Installer error: {ex.Message}", LogColors.Red);
            return false;
        }
    }

    private void PrintStatus(string message, string color) =>
        Logger.WriteLine("Ollama", message, color);

    internal void PrintInstallerOutput(string message, string color)
    {
        if (RegexPatterns.InstallerProgress().IsMatch(message))
            PrintProgress(message.Trim(), color);
        else
            PrintStatus(message, color);
    }

    private void PrintProgress(string message, string color) =>
        Logger.WriteProgress("Ollama", message, color);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

using Lilith.Core.Scenarios;

namespace Lilith.Core.Providers;

public abstract partial class ProviderClient
{
    public SubagentRegistry Subagents { get; } = new();
    private volatile bool _showSubagentOutput;
    public bool ShowSubagentOutput { get => _showSubagentOutput; set => _showSubagentOutput = value; }
    public event Action<SubagentOutput>? SubagentOutput;

    private void ReportSubagent(ScenarioProgress progress)
    {
        var output = SubagentRegistry.Present(progress, Subagents.Observe(progress), ShowSubagentOutput);
        if (output is null) return;
        Logger.WriteLine("Subagent " + output.AgentId, output.IsSummary ? output.Text : output.Kind + ": " + output.Text, LogColors.Cyan);
        if (SubagentOutput is not { } handlers) return;
        foreach (var handler in handlers.GetInvocationList().Cast<Action<SubagentOutput>>())
            try { handler(output); }
            catch (Exception ex) { Logger.WriteWarning("Subagent", "Output observer failed: " + ex.Message); }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287

namespace Lilith.Core.Providers;

using System.Text.Json;
using Lilith.Core.Tools;

/// <summary>Conversation operations reject overlap rather than mixing sessions or snapshots.</summary>
public abstract partial class ProviderClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null) : IDisposable
{
    private readonly bool _ownsHttp = httpClient is null;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private readonly Dictionary<string, ILilithTool> _tools = new(StringComparer.Ordinal);
    internal IReadOnlyDictionary<string, ILilithTool> RegisteredTools => _tools;
    public event Action<Lilith.Core.Scenarios.ScenarioProgress>? ScenarioProgress;
    internal void ReportScenario(Lilith.Core.Scenarios.ScenarioProgress progress)
    {
        ReportSubagent(progress);
        if (ScenarioProgress is not { } handlers) return;
        foreach (var handler in handlers.GetInvocationList().Cast<Action<Lilith.Core.Scenarios.ScenarioProgress>>())
            try { handler(progress); }
            catch (Exception ex) { Logger.WriteWarning("Scenario", "Progress observer failed: " + ex.Message); }
    }

    /// <summary>Fresh context with borrowed transport; never boots or reenters the parent.</summary>
    public virtual ProviderClient CreateScenarioBranch(string prompt, Logger branchLogger, ChatHistoryStore store) =>
        throw new NotSupportedException("This provider does not support scenario branches.");
    protected object[]? ToolDefinitions => _tools.Count == 0 ? null : _tools.Values.Select(t => (object)new
    {
        type = "function", function = new { name = t.Name, description = t.Description, parameters = t.Parameters }
    }).ToArray();

    public void RegisterTool(ILilithTool tool)
    {
        using var operation = EnterOperation();
        ArgumentNullException.ThrowIfNull(tool);
        if (string.IsNullOrWhiteSpace(tool.Name) || tool.Name.Length > 64 ||
            tool.Name.Any(c => !(char.IsAsciiLetterOrDigit(c) || c is '_' or '-')) ||
            tool.Parameters.ValueKind != JsonValueKind.Object)
            throw new ArgumentException("A tool requires a valid function name and JSON parameter schema.", nameof(tool));
        if (!_tools.TryAdd(tool.Name, tool)) throw new ArgumentException($"Tool '{tool.Name}' is already registered.", nameof(tool));
    }
    public HttpClient Http { get; } = httpClient ?? new() { Timeout = TimeSpan.FromMinutes(20) };
    public string Model { get; set; } = "gemma4";
    protected int NumCtx { get; set; } = 131072;
    public int ContextMax => NumCtx;
    public string SystemPrompt { get; protected set; } = string.Empty;
    /// <summary>Inspect only while idle. Use conversation methods to change an active session.</summary>
    public ChatHistory History { get; } = [];
    public ChatHistoryStore HistoryStore { get; } = historyStore ?? new ChatHistoryStore();
    public Logger Logger { get; } = logger;
    public string AgentName { get; set; } = "Lilith";
    public int ContextUsagePercent { get; private set; }
    public int CurrentContextTokens { get; private set; }
    public int ContextWarningThreshold { get; set; } = 60;
    public event Action<int>? OnContextHighUsage;

    public void ContextHighUsage(Func<int, string> message, string color = LogColors.Orange) =>
        OnContextHighUsage += pct => Logger.WriteLine("System", message(pct), color);

    protected void InitializeConversation()
    {
        History.Add("system", SystemPrompt);
        ContextHighUsage(pct => $"\u26a0 Context window is {pct}% full — history is getting long.");
    }

    private IDisposable EnterOperation()
    {
        var operation = _operation.EnterOrThrow("A conversation operation is already in progress.");
        if (_disposed) { operation.Dispose(); throw new ObjectDisposedException(GetType().Name); }
        return operation;
    }

    public void NewConversation()
    {
        using var operation = EnterOperation();
        SaveCore();
        HistoryStore.StartNewSession();
        ClearCore();
        Logger.WriteLine("System", "New conversation started.", LogColors.Cyan);
    }

    public void SaveConversation() => SaveCurrentConversation();
    public IReadOnlyList<ChatSessionSummary> ListConversations() => ListSavedConversations();
    public bool LoadConversation(int displayIndex) => LoadSavedConversation(displayIndex);
    public bool LoadConversation(string id) => LoadSavedConversation(id);
    public void ClearHistory() { using var operation = EnterOperation(); ClearCore(); }

    private void ClearCore()
    {
        History.Clear();
        ResetUsage();
        if (!string.IsNullOrWhiteSpace(SystemPrompt)) History.Add("system", SystemPrompt);
    }

    private void ResetUsage() { CurrentContextTokens = 0; ContextUsagePercent = 0; }
    public void StartNewSession() { using var operation = EnterOperation(); HistoryStore.StartNewSession(); }
    public void SaveCurrentConversation() { using var operation = EnterOperation(); SaveCore(); }

    private void SaveCore()
    {
        try
        {
            if (History.Any(m => !m.Role.Equals("system", StringComparison.OrdinalIgnoreCase) && !string.IsNullOrWhiteSpace(m.Content)))
                HistoryStore.SaveSession(Model, History);
        }
        catch (Exception ex) { Logger.WriteWarning("History", $"Could not save chat history: {ex.Message}"); }
    }

    public IReadOnlyList<ChatSessionSummary> ListSavedConversations()
    {
        using var operation = EnterOperation();
        return HistoryStore.ListSessions();
    }

    public bool LoadSavedConversation(int displayIndex)
    {
        using var operation = EnterOperation();
        var sessions = HistoryStore.ListSessions();
        return displayIndex >= 1 && displayIndex <= sessions.Count && LoadCore(sessions[displayIndex - 1].Id);
    }

    public bool LoadSavedConversation(string id) { using var operation = EnterOperation(); return LoadCore(id); }

    private bool LoadCore(string id)
    {
        string previousId = HistoryStore.CurrentSessionId;
        try
        {
            var session = HistoryStore.LoadSession(id);
            if (session is null) return false;
            var messages = session.Messages.Select(m => m.ToChatMessage()).ToList();
            if (messages[0].Role != "system")
            {
                if (string.IsNullOrWhiteSpace(SystemPrompt)) throw new InvalidDataException("System prompt content is missing.");
                messages.Insert(0, new ChatMessage("system", SystemPrompt));
            }
            History.Clear();
            History.AddRange(messages);
            ResetUsage();
            return true;
        }
        catch (Exception ex)
        {
            HistoryStore.UseSession(previousId);
            Logger.WriteWarning("History", $"Could not load chat history: {ex.Message}");
            return false;
        }
    }

    protected abstract Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages);
    protected virtual Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages, CancellationToken cancellationToken) =>
        GenerateReplyAsync(messages);

    public async Task<string> StreamReply(string userInput, List<string>? images = null, CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        return await StreamReplyCoreAsync(userInput, images, cancellationToken);
    }

    /// <summary>Application-requested scenario dispatch; no model decision is needed to start it.</summary>
    public async Task<string> RunScenarioAsync(string scenarioName, IReadOnlyDictionary<string, string>? inputs = null,
        CancellationToken cancellationToken = default)
    {
        using var operation = EnterOperation();
        if (!_tools.TryGetValue("run_scenario", out var tool) || tool is not Lilith.Core.Scenarios.RunScenarioTool)
            throw new InvalidOperationException("Register scenario support before running a scenario.");
        var arguments = JsonSerializer.SerializeToElement(new { scenario_name = scenarioName, inputs = inputs ?? new Dictionary<string, string>() });
        var call = new ToolCall(new ToolFunction("run_scenario", arguments), "application-" + Guid.NewGuid().ToString("N"));
        var dispatch = new ChatChunk(new ChatMessage("assistant", "", ToolCalls: [call]), true, null, null);
        Logger.WriteLine("System", "Application requested scenario: " + scenarioName, LogColors.Cyan);
        return await StreamReplyCoreAsync(scenarioName == "greeting" ? "Please greet the user using the greeting scenario." : "Run " + scenarioName + " scenario.",
            null, cancellationToken, dispatch);
    }

    private async Task<string> StreamReplyCoreAsync(string userInput, List<string>? images, CancellationToken cancellationToken,
        ChatChunk? applicationDispatch = null)
    {
        bool requireScenarioSuccess = applicationDispatch is not null;
        if (string.IsNullOrWhiteSpace(userInput)) throw new ArgumentException("User input cannot be blank.", nameof(userInput));
        var userMessage = new ChatMessage("user", userInput, Images: images is null ? null : [.. images]);
        var requestHistory = History.Select(m => m.Snapshot()).ToList();
        requestHistory.Add(userMessage);
        Logger.WriteLine("User", $"User: {userInput}", LogColors.Green);
        ChatChunk? chunk;
        int originalCount = requestHistory.Count - 1;
        int rounds = 0;
        while (true)
        {
            cancellationToken.ThrowIfCancellationRequested();
            chunk = applicationDispatch ?? await GenerateReplyAsync(requestHistory, cancellationToken);
            applicationDispatch = null;
            cancellationToken.ThrowIfCancellationRequested();
            if (chunk is not { Done: true, Message.Role: "assistant" } ||
                chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
                throw new InvalidDataException("The model provider returned an invalid assistant response.");
            if (chunk.Message.ToolCalls is not { Count: > 0 } calls) break;
            if (++rounds > 8 || calls.Count > 16)
                throw new InvalidDataException("The model exceeded the tool execution limit.");
            foreach (var call in calls)
                if (call?.Function is null || string.IsNullOrWhiteSpace(call.Function.Name) ||
                    call.Function.Arguments.ValueKind != JsonValueKind.Object)
                    throw new InvalidDataException("The model returned a malformed tool call.");
            if (calls.Count != 1 && calls.Any(c => _tools.TryGetValue(c.Function.Name, out var candidate) && candidate is ITurnResultTool))
                throw new InvalidDataException("Run a scenario in its own tool batch so its final output is unambiguous.");
            requestHistory.Add(chunk.Message with { Content = chunk.Message.Content ?? string.Empty });
            string? exactReply = null;
            foreach (var call in calls)
            {
                cancellationToken.ThrowIfCancellationRequested();
                string result;
                if (!_tools.TryGetValue(call.Function.Name, out var tool))
                    result = JsonSerializer.Serialize(new { error = "Unknown tool: " + call.Function.Name });
                else
                {
                    using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
                    deadline.CancelAfter(tool is ITurnResultTool timed ? timed.ExecutionTimeout : TimeSpan.FromSeconds(30));
                    try
                    {
                        // Await actual completion: custom tools must cooperate with cancellation.
                        if (tool is ITurnResultTool turnTool)
                        {
                            var outcome = await turnTool.ExecuteResultAsync(call.Function.Arguments, deadline.Token);
                            deadline.Token.ThrowIfCancellationRequested();
                            if (requireScenarioSuccess && call.Function.Name == "run_scenario")
                            {
                                using var status = JsonDocument.Parse(outcome.Content);
                                if (status.RootElement.GetProperty("status").GetString() != "completed")
                                    throw new InvalidDataException("Configured scenario did not complete: " + outcome.Content);
                            }
                            result = outcome.Content;
                            if (outcome.ExactReply is { } exact)
                            {
                                if (exactReply is not null) throw new InvalidDataException("Only one exact scenario output is allowed per tool batch.");
                                exactReply = exact;
                            }
                        }
                        else result = await tool.ExecuteAsync(call.Function.Arguments, deadline.Token);
                        deadline.Token.ThrowIfCancellationRequested();
                    }
                    catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
                    catch (Exception ex) when (!requireScenarioSuccess && ex is not OutOfMemoryException)
                    {
                        result = JsonSerializer.Serialize(new { error = ex is OperationCanceledException ? "Tool execution canceled or timed out." : ex.Message });
                    }
                }
                requestHistory.Add(new ChatMessage("tool", result ?? string.Empty, ToolName: call.Function.Name, ToolCallId: call.Id));
            }
            if (exactReply is not null)
            {
                chunk = new ChatChunk(new ChatMessage("assistant", exactReply), true, null, null);
                break;
            }
        }
        cancellationToken.ThrowIfCancellationRequested();
        if (chunk is not { Done: true, Message: { Role: "assistant", Content: not null } } ||
            string.IsNullOrWhiteSpace(chunk.Message.Content) || chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
            throw new InvalidDataException("The model provider did not return a complete nonempty assistant reply with valid token counts.");
        string reply = chunk.Message.Content;
        // Commit only after a successful final answer.
        requestHistory[originalCount] = userMessage with { Tokens = chunk.PromptTokens };
        History.AddRange(requestHistory.Skip(originalCount).Select(m => m.Snapshot()));
        History.Add("assistant", reply, chunk.CompletionTokens);
        SaveCore();
        Logger.WriteLine(AgentName, $"{AgentName}: {reply}", LogColors.Yellow);
        ResetUsage();
        if (chunk.PromptTokens is { } prompt && chunk.CompletionTokens is { } completion && NumCtx > 0)
        {
            CurrentContextTokens = (int)Math.Min(int.MaxValue, (long)prompt + completion);
            ContextUsagePercent = (int)Math.Min(int.MaxValue, (long)CurrentContextTokens * 100 / NumCtx);
            if (ContextUsagePercent >= ContextWarningThreshold && OnContextHighUsage is { } handlers)
                foreach (var handler in handlers.GetInvocationList().Cast<Action<int>>())
                    try { handler(ContextUsagePercent); }
                    catch (Exception ex) { Logger.WriteWarning("System", $"Context warning callback failed: {ex.Message}"); }
        }
        return reply;
    }

    public void Dispose()
    {
        using var operation = _operation.EnterOrThrow("Cannot dispose a provider during a conversation operation.");
        if (_disposed) return;
        _disposed = true;
        if (_ownsHttp) Http.Dispose();
        GC.SuppressFinalize(this);
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217

namespace Lilith.Core.Providers;

using System.Text.Json;
using Lilith.Core.Tools;

/// <summary>Conversation operations reject overlap rather than mixing sessions or snapshots.</summary>
public abstract class ProviderClient(Logger logger, ChatHistoryStore? historyStore = null, HttpClient? httpClient = null) : IDisposable
{
    private readonly bool _ownsHttp = httpClient is null;
    private readonly SemaphoreSlim _operation = new(1, 1);
    private bool _disposed;
    private readonly Dictionary<string, ILilithTool> _tools = new(StringComparer.Ordinal);
    protected object[]? ToolDefinitions => _tools.Count == 0 ? null : _tools.Values.Select(t => (object)new
    {
        type = "function", function = new { name = t.Name, description = t.Description, parameters = t.Parameters }
    }).ToArray();

    public void RegisterTool(ILilithTool tool)
    {
        using var operation = EnterOperation();
        ArgumentNullException.ThrowIfNull(tool);
        if (string.IsNullOrWhiteSpace(tool.Name) || tool.Name.Length > 64 ||
            tool.Name.Any(c => !(char.IsAsciiLetterOrDigit(c) || c is '_' or '-')) ||
            tool.Parameters.ValueKind != JsonValueKind.Object)
            throw new ArgumentException("A tool requires a valid function name and JSON parameter schema.", nameof(tool));
        if (!_tools.TryAdd(tool.Name, tool)) throw new ArgumentException($"Tool '{tool.Name}' is already registered.", nameof(tool));
    }
    public HttpClient Http { get; } = httpClient ?? new() { Timeout = TimeSpan.FromMinutes(20) };
    public string Model { get; set; } = "gemma4";
    protected int NumCtx { get; set; } = 131072;
    public int ContextMax => NumCtx;
    public string SystemPrompt { get; protected set; } = string.Empty;
    /// <summary>Inspect only while idle. Use conversation methods to change an active session.</summary>
    public ChatHistory History { get; } = [];
    public ChatHistoryStore HistoryStore { get; } = historyStore ?? new ChatHistoryStore();
    public Logger Logger { get; } = logger;
    public string AgentName { get; set; } = "Lilith";
    public int ContextUsagePercent { get; private set; }
    public int CurrentContextTokens { get; private set; }
    public int ContextWarningThreshold { get; set; } = 60;
    public event Action<int>? OnContextHighUsage;

    public void ContextHighUsage(Func<int, string> message, string color = LogColors.Orange) =>
        OnContextHighUsage += pct => Logger.WriteLine("System", message(pct), color);

    protected void InitializeConversation()
    {
        History.Add("system", SystemPrompt);
        ContextHighUsage(pct => $"\u26a0 Context window is {pct}% full — history is getting long.");
    }

    private IDisposable EnterOperation()
    {
        var operation = _operation.EnterOrThrow("A conversation operation is already in progress.");
        if (_disposed) { operation.Dispose(); throw new ObjectDisposedException(GetType().Name); }
        return operation;
    }

    public void NewConversation()
    {
        using var operation = EnterOperation();
        SaveCore();
        HistoryStore.StartNewSession();
        ClearCore();
        Logger.WriteLine("System", "New conversation started.", LogColors.Cyan);
    }

    public void SaveConversation() => SaveCurrentConversation();
    public IReadOnlyList<ChatSessionSummary> ListConversations() => ListSavedConversations();
    public bool LoadConversation(int displayIndex) => LoadSavedConversation(displayIndex);
    public bool LoadConversation(string id) => LoadSavedConversation(id);
    public void ClearHistory() { using var operation = EnterOperation(); ClearCore(); }

    private void ClearCore()
    {
        History.Clear();
        ResetUsage();
        if (!string.IsNullOrWhiteSpace(SystemPrompt)) History.Add("system", SystemPrompt);
    }

    private void ResetUsage() { CurrentContextTokens = 0; ContextUsagePercent = 0; }
    public void StartNewSession() { using var operation = EnterOperation(); HistoryStore.StartNewSession(); }
    public void SaveCurrentConversation() { using var operation = EnterOperation(); SaveCore(); }

    private void SaveCore()
    {
        try
        {
            if (History.Any(m => !m.Role.Equals("system", StringComparison.OrdinalIgnoreCase) && !string.IsNullOrWhiteSpace(m.Content)))
                HistoryStore.SaveSession(Model, History);
        }
        catch (Exception ex) { Logger.WriteWarning("History", $"Could not save chat history: {ex.Message}"); }
    }

    public IReadOnlyList<ChatSessionSummary> ListSavedConversations()
    {
        using var operation = EnterOperation();
        return HistoryStore.ListSessions();
    }

    public bool LoadSavedConversation(int displayIndex)
    {
        using var operation = EnterOperation();
        var sessions = HistoryStore.ListSessions();
        return displayIndex >= 1 && displayIndex <= sessions.Count && LoadCore(sessions[displayIndex - 1].Id);
    }

    public bool LoadSavedConversation(string id) { using var operation = EnterOperation(); return LoadCore(id); }

    private bool LoadCore(string id)
    {
        string previousId = HistoryStore.CurrentSessionId;
        try
        {
            var session = HistoryStore.LoadSession(id);
            if (session is null) return false;
            var messages = session.Messages.Select(m => m.ToChatMessage()).ToList();
            if (messages[0].Role != "system")
            {
                if (string.IsNullOrWhiteSpace(SystemPrompt)) throw new InvalidDataException("System prompt content is missing.");
                messages.Insert(0, new ChatMessage("system", SystemPrompt));
            }
            History.Clear();
            History.AddRange(messages);
            ResetUsage();
            return true;
        }
        catch (Exception ex)
        {
            HistoryStore.UseSession(previousId);
            Logger.WriteWarning("History", $"Could not load chat history: {ex.Message}");
            return false;
        }
    }

    protected abstract Task<ChatChunk?> GenerateReplyAsync(List<ChatMessage> messages);

    public async Task<string> StreamReply(string userInput, List<string>? images = null)
    {
        using var operation = EnterOperation();
        if (string.IsNullOrWhiteSpace(userInput)) throw new ArgumentException("User input cannot be blank.", nameof(userInput));
        var userMessage = new ChatMessage("user", userInput, Images: images is null ? null : [.. images]);
        var requestHistory = History.Select(m => m.Snapshot()).ToList();
        requestHistory.Add(userMessage);
        Logger.WriteLine("User", $"User: {userInput}", LogColors.Green);
        ChatChunk? chunk;
        int originalCount = requestHistory.Count - 1;
        int rounds = 0;
        while (true)
        {
            chunk = await GenerateReplyAsync(requestHistory);
            if (chunk is not { Done: true, Message.Role: "assistant" } ||
                chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
                throw new InvalidDataException("The model provider returned an invalid assistant response.");
            if (chunk.Message.ToolCalls is not { Count: > 0 } calls) break;
            if (++rounds > 8 || calls.Count > 16)
                throw new InvalidDataException("The model exceeded the tool execution limit.");
            foreach (var call in calls)
                if (call?.Function is null || string.IsNullOrWhiteSpace(call.Function.Name) ||
                    call.Function.Arguments.ValueKind != JsonValueKind.Object)
                    throw new InvalidDataException("The model returned a malformed tool call.");
            requestHistory.Add(chunk.Message with { Content = chunk.Message.Content ?? string.Empty });
            foreach (var call in calls)
            {
                string result;
                if (!_tools.TryGetValue(call.Function.Name, out var tool))
                    result = JsonSerializer.Serialize(new { error = "Unknown tool: " + call.Function.Name });
                else
                {
                    using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(30));
                    try
                    {
                        // Await actual completion: custom tools must cooperate with cancellation.
                        result = await tool.ExecuteAsync(call.Function.Arguments, deadline.Token);
                        deadline.Token.ThrowIfCancellationRequested();
                    }
                    catch (Exception ex) when (ex is not OutOfMemoryException)
                    {
                        result = JsonSerializer.Serialize(new { error = ex is OperationCanceledException ? "Tool execution canceled or timed out." : ex.Message });
                    }
                }
                requestHistory.Add(new ChatMessage("tool", result ?? string.Empty, ToolName: call.Function.Name, ToolCallId: call.Id));
            }
        }
        if (chunk is not { Done: true, Message: { Role: "assistant", Content: not null } } ||
            string.IsNullOrWhiteSpace(chunk.Message.Content) || chunk.PromptTokens is < 0 || chunk.CompletionTokens is < 0)
            throw new InvalidDataException("The model provider did not return a complete nonempty assistant reply with valid token counts.");
        string reply = chunk.Message.Content;
        // Commit only after a successful final answer.
        requestHistory[originalCount] = userMessage with { Tokens = chunk.PromptTokens };
        History.AddRange(requestHistory.Skip(originalCount).Select(m => m.Snapshot()));
        History.Add("assistant", reply, chunk.CompletionTokens);
        SaveCore();
        Logger.WriteLine(AgentName, $"{AgentName}: {reply}", LogColors.Yellow);
        ResetUsage();
        if (chunk.PromptTokens is { } prompt && chunk.CompletionTokens is { } completion && NumCtx > 0)
        {
            CurrentContextTokens = (int)Math.Min(int.MaxValue, (long)prompt + completion);
            ContextUsagePercent = (int)Math.Min(int.MaxValue, (long)CurrentContextTokens * 100 / NumCtx);
            if (ContextUsagePercent >= ContextWarningThreshold && OnContextHighUsage is { } handlers)
                foreach (var handler in handlers.GetInvocationList().Cast<Action<int>>())
                    try { handler(ContextUsagePercent); }
                    catch (Exception ex) { Logger.WriteWarning("System", $"Context warning callback failed: {ex.Message}"); }
        }
        return reply;
    }

    public void Dispose()
    {
        using var operation = _operation.EnterOrThrow("Cannot dispose a provider during a conversation operation.");
        if (_disposed) return;
        _disposed = true;
        if (_ownsHttp) Http.Dispose();
        GC.SuppressFinalize(this);
    }

}