UAIX.LmRuntime.LocalEndpoint

using UAIX.LmRuntime.LocalEndpoint;

public static class LocalGgufQuickStart
{
    /// <summary>
    /// Loads a verified local GGUF model and performs deterministic greedy generation.
    /// </summary>
    /// <param name="modelPath">The local path to the GGUF model.</param>
    /// <param name="trustedModelRoot">The canonical root under which the model must reside.</param>
    /// <param name="expectedSha256">The expected SHA-256 digest.</param>
    /// <param name="expectedByteCount">The exact expected model byte count.</param>
    /// <param name="appInstanceId">The host application's stable instance identifier.</param>
    /// <param name="importedPackageCorrelationId">A legacy UAIX package correlation identifier; it grants no authority.</param>
    /// <param name="profileId">The already validated UAIX profile identifier.</param>
    /// <param name="profileDisplayName">The display-safe profile name.</param>
    /// <param name="loadSessionId">The host-owned profile load-session identifier.</param>
    /// <param name="wikiRootId">The host-owned long-term-memory root identifier.</param>
    /// <param name="workerSessionId">The host-owned inference session identifier.</param>
    /// <param name="prompt">The already prepared prompt; the runtime does not assemble it.</param>
    /// <param name="cancellationToken">A token used to cancel between committed inference steps.</param>
    /// <returns>The deterministic generation result.</returns>
    public static LocalGgufGenerationResult Generate(
        string modelPath,
        string trustedModelRoot,
        string expectedSha256,
        long expectedByteCount,
        string appInstanceId,
        string importedPackageCorrelationId,
        string profileId,
        string profileDisplayName,
        string loadSessionId,
        string wikiRootId,
        string workerSessionId,
        string prompt,
        CancellationToken cancellationToken)
    {
        var runtime = new LocalGgufRuntime(
            new LocalGgufRuntimeScope
            {
                ApplicationInstanceId = appInstanceId,
                UaixPackageId = importedPackageCorrelationId
            });

        var uaixContext = new LocalUaixRuntimeContext
        {
            LoadedUaixProfilePresent = true,
            LoadedUaixProfileId = profileId,
            LoadedUaixProfileDisplayName = profileDisplayName,
            LoadedUaixLoadSessionId = loadSessionId,
            LoadedUaixUaiRelativePath = $"Memories/Profiles/{profileId}/.uai",
            LoadedUaixSessionRelativePath = $"Memories/Sessions/{loadSessionId}.json",
            LongTermMemoryRootId = wikiRootId,
            LongTermMemoryRootRelativePath = $"Profiles/{profileId}",
            LongTermMemoryMode = LocalUaixLongTermMemoryMode.Isolated,
            RuntimeExecutionAllowed = false,
            MemoryCanOverridePolicy = false,
            CommandExecutionAllowed = false,
            NetworkAccessAllowed = false,
            ProviderApisAllowed = false,
            WebsitePromptIntakeAllowed = false,
            TelemetryEnabled = false,
            AutoExportAllowed = false
        };

        LocalUaixRuntimeContextEvidence contextEvidence =
            LocalGgufRuntime.VerifyUaixRuntimeContext(uaixContext);

        using LocalGgufModel model = runtime.LoadVerifiedModel(
            modelPath,
            new LocalGgufFileExpectation
            {
                ModelSha256 = expectedSha256,
                ModelByteCount = expectedByteCount
            },
            new LocalGgufModelLoadOptions
            {
                AllowedRootDirectory = trustedModelRoot,
                RejectReparsePoints = true,
                MaximumModelBytes = expectedByteCount,
                ExecutionLimits = new LocalGgufExecutionLimits
                {
                    MaximumPromptCharacters = 32_768,
                    MaximumGeneratedTokens = 256,
                    MaximumStopTokenCount = 32
                }
            });

        using LocalGgufSession session = model.CreateSession(
            new LocalGgufSessionContext
            {
                SessionId = workerSessionId,
                UaixRuntimeContext = uaixContext
            });

        return session.GenerateGreedy(
            new LocalGgufGenerationRequest
            {
                Prompt = prompt,
                MaximumTokens = 128,
                ResetSession = true,
                AddSpecialTokens = false,
                ParseSpecialTokens = false,
                EmitTokenizerTrace = false,
                RemoveSpecialTokens = false,
                UnparseSpecialTokens = true,
                CleanSpaces = false
            },
            cancellationToken);
    }
}

using UAIX.LmRuntime.LocalEndpoint;

public static class TokenObservationExample
{
    /// <summary>
    /// Generates a bounded response and observes each selected token synchronously.
    /// </summary>
    /// <param name="session">The isolated local GGUF session.</param>
    /// <param name="preparedPrompt">The host-prepared prompt.</param>
    /// <param name="cancellationToken">A token observed between committed model steps.</param>
    /// <returns>The complete deterministic generation result.</returns>
    public static LocalGgufGenerationResult Generate(
        LocalGgufSession session,
        string preparedPrompt,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(session);
        ArgumentException.ThrowIfNullOrWhiteSpace(preparedPrompt);

        return session.GenerateGreedy(
            new LocalGgufGenerationRequest
            {
                Prompt = preparedPrompt,
                MaximumTokens = 64,
                ResetSession = true,
                AddSpecialTokens = true,
                ParseSpecialTokens = false,
                RemoveSpecialTokens = true
            },
            token => Console.WriteLine(
                $"{session.SessionId}:{token.Sequence}:{token.TokenId}:{token.SelectedLogit}"),
            cancellationToken);
    }
}

using UAIX.LmRuntime.LocalEndpoint;

public static class AssociatedArtifactExample
{
    /// <summary>
    /// Verifies a LocalEndpoint-reviewed associated artifact without granting execution authority.
    /// </summary>
    /// <param name="runtime">The local runtime facade performing byte verification.</param>
    /// <param name="artifactPath">The local associated-artifact path.</param>
    /// <param name="trustedModelRoot">The canonical root that must contain the artifact.</param>
    /// <param name="expectedSha256">The expected SHA-256 digest.</param>
    /// <param name="expectedByteCount">The exact expected byte count.</param>
    /// <returns>Path-free immutable artifact identity evidence.</returns>
    public static IReadOnlyList<LocalGgufAssociatedArtifactIdentity> Verify(
        LocalGgufRuntime runtime,
        string artifactPath,
        string trustedModelRoot,
        string expectedSha256,
        long expectedByteCount)
    {
        ArgumentNullException.ThrowIfNull(runtime);

        string fileName = Path.GetFileName(artifactPath);

        return runtime.VerifyAssociatedArtifacts(
            [
                new LocalGgufAssociatedArtifactLoadInput
                {
                    ArtifactPath = artifactPath,
                    Role = "projector",
                    FileName = fileName,
                    ArtifactSha256 = expectedSha256,
                    ArtifactByteCount = expectedByteCount
                }
            ],
            new LocalGgufModelLoadOptions
            {
                AllowedRootDirectory = trustedModelRoot,
                RejectReparsePoints = true
            });
    }
}

using UAIX.LmRuntime.LocalEndpoint;

var runtime = new LocalGgufRuntime();
LocalGgufRuntimeCapabilities capabilities = runtime.Capabilities;

Console.WriteLine($"Managed execution: {capabilities.IsManagedExecution}");
Console.WriteLine($"Explicit verification: {capabilities.SupportsExplicitFileVerification}");
Console.WriteLine($"Network access: {capabilities.UsesNetworkAccess}");
Console.WriteLine($"Subprocesses: {capabilities.UsesSubprocesses}");
Console.WriteLine($"Telemetry: {capabilities.UsesTelemetry}");
Console.WriteLine($"Server: {capabilities.HostsServer}");
Console.WriteLine($"Global UAIX profile: {capabilities.UsesGlobalUaixProfile}");
Console.WriteLine($"Memory grants authority: {capabilities.UaixMemoryGrantsAuthority}");

using UAIX.LmRuntime.LocalEndpoint;

public static class SessionReuseExample
{
    /// <summary>
    /// Executes an initial prepared prompt, then continues the same isolated model session.
    /// </summary>
    /// <param name="session">The isolated local GGUF session.</param>
    /// <param name="firstPreparedPrompt">The complete first-turn prompt prepared by the host.</param>
    /// <param name="continuationPreparedPrompt">The continuation prompt prepared by the host.</param>
    /// <param name="cancellationToken">A token observed between committed model steps.</param>
    /// <returns>The first and continuation generation results.</returns>
    public static (
        LocalGgufGenerationResult First,
        LocalGgufGenerationResult Continuation) GenerateTwoTurns(
        LocalGgufSession session,
        string firstPreparedPrompt,
        string continuationPreparedPrompt,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(session);

        LocalGgufGenerationResult first = session.GenerateGreedy(
            new LocalGgufGenerationRequest
            {
                Prompt = firstPreparedPrompt,
                MaximumTokens = 64,
                ResetSession = true,
                AddSpecialTokens = true
            },
            cancellationToken);

        LocalGgufGenerationResult continuation = session.GenerateGreedy(
            new LocalGgufGenerationRequest
            {
                Prompt = continuationPreparedPrompt,
                MaximumTokens = 64,
                ResetSession = false,
                AddSpecialTokens = false
            },
            cancellationToken);

        return (first, continuation);
    }
}

using UAIX.LmRuntime.LocalEndpoint;

var runtime = new LocalGgufRuntime();
LocalGgufRuntimeCapabilities capabilities = runtime.Capabilities;

Console.WriteLine($"Managed execution: {capabilities.IsManagedExecution}");
Console.WriteLine($"Native inference: {capabilities.UsesNativeInference}");
Console.WriteLine($"GPU acceleration: {capabilities.UsesGpuAcceleration}");
Console.WriteLine($"Network access: {capabilities.UsesNetworkAccess}");
Console.WriteLine($"Telemetry: {capabilities.UsesTelemetry}");

if (!capabilities.IsManagedExecution ||
    capabilities.UsesNativeInference ||
    capabilities.UsesGpuAcceleration ||
    capabilities.UsesNetworkAccess ||
    capabilities.UsesTelemetry)
{
    throw new InvalidOperationException("The active facade does not match the required local managed boundary.");
}