EvaluatedApplications.EvalApp.Neural 2.0.4

EvalApp.Neural

A neural concurrency tuner for EvalApp. It replaces the built-in heuristic on your app's resource gates with a small holographic policy model (HoloFormer, from AlgFormer). The model reads each gate's recent trajectory and predicts the next concurrency level. It keeps training from its own decisions, so it re-converges when the best concurrency moves.

Install: dotnet add package EvaluatedApplications.EvalApp.Neural

Quick start

using EvalApp;
using EvalApp.Neural;

Eval.App("orders")
    .WithResource(ResourceKind.Cpu, Tunable.Between(1, 32, 4))
    .WithResource(ResourceKind.Of("db"), Tunable.Between(1, 24, 4))
    .WithNeuralTuning()
    .DefineDomain("orders")
        .DefineTask<Batch>("process")
            .ForEach(select: b => b.Items, merge: (b, r) => b with { Items = r.ToList() }, collectionName: "Items",
                configure: sub => sub.AddStep("Score", (Item i) => i with { Score = i.Id * 2 }))
        .Run(out var pipeline)
    .Build();

var result = await pipeline.RunAsync(new Batch(Enumerable.Range(1, 100).Select(i => new Item(i)).ToList()));
Console.WriteLine($"scored {result.GetData().Items.Count} items, first = {result.GetData().Items[0].Score}");

public sealed record Item(int Id, int Score = 0);
public sealed record Batch(IReadOnlyList<Item> Items);

WithNeuralTuning() turns tuning on for the app and attaches the neural tuner. Call it before DefineDomain.

Features

• Per-app tuner: WithNeuralTuning() on any Eval.App(...) builder. Each app gets its own tuner and its own model.
• A model you own, shared across apps: WithNeuralTuning(model) trains the model you pass in, in place.
• Process-wide install: NeuralTuning.UseGlobally(model) makes every app that calls WithTuning() use one model.
• Persistence: NeuralTuning.UseGloballyPersisted(path) loads a model file, trains it, and saves it on dispose.
• Save and restore: model.Serialize() and HoloFormer.Deserialize(bytes) round-trip the model exactly.
• Warm-start: a starting model ships inside the DLL. Nothing to configure.
• Coordinate descent: with more than one gate, each decision credits the gate moved last and moves the gate with the highest contention. A small exploration rate runs alongside it.
• Time-paced decisions: at most one decision per 25 ms of wall time, so cost does not grow with drain rate.
• No licence key: nothing in the package is gated by tier.

Shared model across apps

using EvalApp;
using EvalApp.Neural;
using PrismFormer;

var model = NeuralTuning.NewModel(seed: 1);
byte[] before = model.Serialize();
var path = Path.Combine(Path.GetTempPath(), "neural-e-shared.tuning.json");
Eval.App("svc-e")
    .WithResource(ResourceKind.Cpu, Tunable.Between(1, 32, 4))
    .WithTuning(path)
    .WithNeuralTuning(model)
    .DefineDomain("work")
        .DefineTask<Batch>("process")
            .ForEach(select: b => b.Items, merge: (b, r) => b with { Items = r.ToList() }, collectionName: "Items",
                configure: sub => sub.AddStep("Score", (int i) => i * 2))
        .Run(out var pipe)
    .Build();
for (int i = 0; i < 40; i++)
{
    var r = await pipe.RunAsync(new Batch(Enumerable.Range(1, 50).ToList()));
    if (i == 0) Console.WriteLine($"items = {r.GetData().Items.Count}");
    await Task.Delay(30);   // tuner decisions are paced to 25 ms of wall time
}
Console.WriteLine($"shared model trained in place = {!model.Serialize().AsSpan().SequenceEqual(before)}");

public sealed record Batch(IReadOnlyList<int> Items);

Pass the same model to each app that should learn together. Drive those apps one after another: the model is not thread-safe.

Process-wide install and persistence

using EvalApp;
using EvalApp.Neural;

var path = Path.Combine(Path.GetTempPath(), "neural-d-persisted.bin");
using (NeuralTuning.UseGloballyPersisted(path))
{
    Eval.App("svc-d")
        .WithResource(ResourceKind.Cpu, Tunable.Between(1, 32, 4))
        .WithTuning(Path.Combine(Path.GetTempPath(), "neural-d-persisted.tuning.json"))
        .DefineDomain("work")
            .DefineTask<Batch>("process")
                .AddStep("Score", (Batch b) => b with { Total = b.Items.Sum(i => i * 2) })
            .Run(out var pipe)
        .Build();
    var r = await pipe.RunAsync(new Batch(Enumerable.Range(1, 10).ToList()));
    Console.WriteLine($"total = {r.GetData().Total}");
}
Console.WriteLine($"model file written = {File.Exists(path)}");

public sealed record Batch(IReadOnlyList<int> Items, int Total = 0);

UseGlobally(model) is the same without the file: it installs the model for the duration of the using block and restores the previous default on dispose. Both mutate a process-wide setting, so run one workload at a time under them.

Environment install: if EVALAPP_NEURAL_MODEL is set, any process that loads this DLL trains the model at that path and saves it on exit. Unset (the default) means nothing happens. Every process that loads the DLL while the variable is set is affected, including test runs.

Saving a model

using EvalApp.Neural;
using PrismFormer;

var model = NeuralTuning.NewModel(seed: 1);
byte[] bytes = model.Serialize();
HoloFormer restored = HoloFormer.Deserialize(bytes);
Console.WriteLine($"bytes = {bytes.Length}, same bytes after round trip = {restored.Serialize().AsSpan().SequenceEqual(bytes)}");

WithNeuralTuning does not write the model anywhere. Save it yourself if you want it to survive the process.

Things to know

• The tuner learns only from gated work. A pipeline whose steps acquire no gate (a plain AddStep) gives the tuner nothing to tune, and the model does not change. The check above (a gated ForEach) is what trains it.
• Tuning store: WithNeuralTuning() enables tuning, so the app has a tuning store. Pass WithTuning(path) to choose its file; without it the default is a per-application folder under the local application data directory.
• Models are fixed-shape. Shape and vocabulary are fixed (16 concurrency buckets, 8-step trajectory, d48/L2/K2/shifts8). A persisted file that does not match is ignored: the warm-start or a cold model is used, and UseGloballyPersisted overwrites the file on dispose. No exception is thrown.
• A new tuner starts its layer ramp again. The second layer's contribution ramps from zero over 50 training steps for each new tuner instance, including one built on a model you already trained. The ramp is not saved with the model.
• learn: false on UseGlobally exists for controlled comparisons only. Production paths always learn.
• Overhead: about 2 ms of tuner work per decision (package hot-path benchmark, Windows 11, Release, 2026-10-03). Decisions run at most once per 25 ms.
• Warm-start: the shipped model is a starting point. Its value is the continued learning from the first decision.
• Maturity: the shape and vocabulary are fixed for the 2.x line.
• Where it helps: multi-gate workloads whose best concurrency is not obvious, and workloads whose optimum moves at runtime. A single pipeline whose best concurrency is about the core count is simpler on the built-in tuner.
• Shifting optimum (tested): on a synthetic workload whose optimum moves between regimes, the always-learning tuner re-converges after each shift. The package test suite asserts it.

Dependencies

• EvaluatedApplications.EvalApp (ITuner, tuning state, the tuner factory hook).
• EvaluatedApplications.AlgFormer (HoloFormer, shipped inside the DLL; no separate install).
• Targets .NET 8 and .NET 10.

License

Proprietary. This package ships the compiled library only; see LICENSE for the full terms. Installing and using unmodified copies for internal evaluation and non-commercial development or testing is licensed; commercial, production, or revenue-generating use requires a separate commercial licence from the owner. No feature on this page is gated behind a tier or a licence key — every capability described works identically with or without one. Copyright (c) 2026 Dongyang Stephen Chen, trading as Evaluated Applications. All rights reserved.