Universal.Operative.Sdk.Discrete 3.0.0

Universal.Operative.Sdk.Discrete

Provider-neutral conversations, model streams, tools, transforms, turn coordination, and durable conversation chronologies.

Install

dotnet add package Universal.Operative.Sdk.Discrete

Use a provider package such as Universal.Operative.Sdk.Discrete.OpenAI or Universal.Operative.Sdk.Discrete.Anthropic to supply an IModel.

Run a turn

using Universal.Operative.Sdk;
using Universal.Operative.Sdk.Discrete;

IEngine engine = EngineBuilder.FromDefaults(model)
    .AddBaselineToolSet()
    .Build();

var conversation = new Conversation
{
    Messages =
    {
        new Message
        {
            Role = MessageRoles.User,
            Content = { new TextBlock("Inspect this repository.") },
        },
    },
};

ConversationManager manager = await ConversationManager.CreateAsync(conversation);

await foreach (EngineEvent engineEvent in engine.ExecuteAsync(
    new ExecutionContext(new TurnContext()), manager))
{
    if (engineEvent is AssistantMessageEvent response)
        Console.WriteLine(response.Message);
}

Engine streams model output, dispatches tools, applies transforms, and records turn and model-call audit facts through the conversation manager.

Persist and resume

The host owns the repository and its lifetime. ConversationManager owns one mutable materialization and moves one named head.

var repositoryOptions = new FileSystemConversationRepositoryOptions
{
    Directory = conversationDirectory,
    ChronologyId = conversationId,
};

await using FileSystemConversationRepository repository =
    await FileSystemConversationRepository.OpenOrCreateAsync(repositoryOptions);

ConversationManager manager = await ConversationManager.OpenOrCreateAsync(
    repository,
    () => new Conversation { Id = conversationId });

IOperative operative = OperativeBuilder.Create(engine, manager)
    .WithChronologyCompactor(new SizeLimitedChronologyCompactor(new()
    {
        MaximumBytes = 256L * 1024 * 1024,
    }))
    .Build();

Use FileSystemConversationRepository.CreateAsync when the chronology must be new, OpenAsync when it must exist, and OpenOrCreateAsync for either state. A filesystem repository permits one open writer.

chronology.jsonl contains ordered audit facts. Immutable content-addressed objects store conversation snapshots and messages. Unchanged messages are shared across revisions.

Branch and restore

Every revision records its ordered parents and exact conversation snapshot. A named head may be reset or forked without changing earlier revisions.

ConversationManager alternative = await manager.ForkAsync(
    earlierRevisionId,
    headName: "alternative");

await alternative.ResetAsync(otherRevisionId);
Conversation restored = alternative.Current;

Use ReadChronologyAsync to inspect revisions, named heads, turn outcomes, model invocations, and host-defined CustomChronologyEvent values.

Bound storage

IChronologyCompactor defines lossy chronology compaction for repositories that implement ICompactableConversationRepository.

• SizeLimitedChronologyCompactor retains the largest recent reachable revision window within a byte limit.
• RevisionWindowChronologyCompactor retains a configured number of recent reachable revisions.
• CheckpointChronologyCompactor retains only revisions referenced by named heads.
• FileSystemConversationRepository.ApplyRetentionAsync deletes old payloads while retaining the audit graph.

Compactors preserve every named head. A result reports when the requested byte target cannot be met by the required heads alone.

Main abstractions

• Conversation is mutable state supplied to a model.
• ConversationManager materializes revisions and moves one named head.
• IConversationRepository stores immutable revisions and chronology events.
• Chronology is the audit read model.
• IModel maps a provider to provider-neutral stream events.
• Engine runs one turn.
• Operative coordinates concurrent submissions.
• ITransformer derives replacement conversation or turn-context state.

License

Free for noncommercial use under the Universal.Operative Noncommercial License. Commercial use requires a separate license from Andrew Ong.