Universal.Operative.Sdk.Discrete 3.1.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.

Host multiple sessions

Session is the durable host-level unit around one discrete Conversation. It is independent of authentication, tenancy, UI selection, and transport. ISessionStore is the persistence boundary: implement it over a database or remote service, or start with the included InMemorySessionStore and FileSystemSessionStore.

ISessionStore store = new FileSystemSessionStore(new()
{
    Directory = sessionDirectory,
});

var sessions = new SessionManager(store, () => new Conversation
{
    System = [new TextBlock("You are a helpful operative.")],
});

Session session = await sessions.CreateAsync();
IOperative operative = operativeFactory.Create(session.Conversation);
// Run turns, then persist the mutated conversation with optimistic concurrency.
session = await sessions.SaveAsync(session with { Conversation = operative.Conversation });

Store-issued Session.Version values are opaque optimistic-concurrency tokens. Reads are detached, creates reject duplicate identifiers, stale saves fail with SessionConflictException, and deletes may be conditional. A store instance defines its own isolation boundary; the host decides whether that means one user, tenant, application, connection, or a deliberately shared consciousness.

SessionManager supplies storage-neutral create, rename, fork, truncate, and title inference operations. It intentionally does not track an active session or perform authorization. Those are adapter responsibilities.

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.
• Session and SessionManager model host-level conversation lifecycle.
• ISessionStore persists sessions independently of transport and identity.
• 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.