Mythosia.AI.Abstractions 3.1.0

Mythosia.AI.Abstractions

Core contracts and shared models for the Mythosia.AI ecosystem. Defines IAIService, the optional IAIRunService, IAIRequestFeatureService and IImageGenerationService capabilities, provider-neutral model types, and streaming primitives. Consumed by Mythosia.AI.Rag and any library that needs the AI service contract without pulling in heavy provider implementations.

Upgrading to v3? This is the abstractions release paired with Mythosia.AI v7. See the v3.0 release notes and migration guide.

Current release: 3.1.0

The Run and request-feature capabilities, GPT-6 Astra contracts, common reasoning/search options, citations, and AllowAsync metadata require Mythosia.AI.Abstractions 3.1.0 or later. Use Mythosia.AI 7.1.0 or later for the supplied provider implementations. The new capabilities are optional; existing IAIService implementations gain no required members. See the v3.1.0 release notes.

Installation

dotnet add package Mythosia.AI.Abstractions

Install this package directly only when writing a library that depends on the AI service contract (e.g., RAG orchestration, custom middleware). Applications normally take a transitive dependency through Mythosia.AI.

Core Interface

IAIService

The central abstraction for AI completion and streaming.

public interface IAIService
{
    string Model { get; }
    string Provider { get; }
    string SystemMessage { get; set; }
    bool StatelessMode { get; set; }
    ChatBlock ActivateChat { get; }

    Task<string> GetCompletionAsync(
        string prompt,
        AIRequestProfile? profile = null,
        AIRequestContext? context = null);

    Task<string> GetCompletionAsync(
        Message message,
        AIRequestProfile? profile = null,
        AIRequestContext? context = null);

    IAsyncEnumerable<string> StreamAsync(string prompt, CancellationToken ct = default);
    IAsyncEnumerable<string> StreamAsync(
        Message message,
        AIRequestContext? context = null,
        CancellationToken ct = default);

    IAsyncEnumerable<StreamingContent> StreamAsync(
        string prompt,
        StreamOptions options,
        CancellationToken ct = default);

    IAsyncEnumerable<StreamingContent> StreamAsync(
        Message message,
        StreamOptions options,
        AIRequestContext? context = null,
        CancellationToken ct = default);
}

All concrete providers (OpenAIService, AnthropicService, GoogleAIService, etc.) in Mythosia.AI implement this interface.

IAIRunService and AIRun

Libraries that need to display or cancel ongoing work can depend on IAIRunService without referencing a concrete provider. See the Run guide for application examples.

To adjust effort for a task or ground an answer in hosted sources without coupling middleware to a provider, use optional IAIRequestFeatureService. Its WithReasoning, WithWebSearch and WithFileSearch extensions retain the concrete service type, copy settings for the next logical request, and reject unsupported capabilities explicitly. AICitation, StreamingContent.Citation and AIRun.Citations carry provider source references independently of text observation. Existing IAIService implementations need no new required members. See reasoning and search for scope, provider support and citation indexing.

Run startup is an optional capability, so existing custom IAIService implementations gain no mandatory members. It exposes StartRunAsync overloads for string and Message input with onText, streaming options, request context, and cancellation.

using Mythosia.AI.Services;

if (service is IAIRunService runService)
{
    await using var run = await runService.StartRunAsync(
        "Summarize the documents.",
        onText: text => Console.Write(text),
        cancellationToken: cancellationToken);
    string answer = await run.Result;
}

AIRun is in Mythosia.AI.Models.Runs. It exposes Result, output-only StreamAsync, CanSteer, SteerAsync, Cancel, and DisposeAsync. A single event reader may accompany the text callback. Execution and result collection continue without an event reader; see the run guide for buffering and lifetime contracts.

IImageGenerationService

Image generation is an optional provider capability rather than part of the LLM-focused IAIService contract. Consumers can depend on the abstraction without assuming that every chat provider can generate images.

using Mythosia.AI.Models.Images;
using Mythosia.AI.Services;

if (service is IImageGenerationService imageService)
{
    ImageGenerationResult result = await imageService.GenerateImagesAsync(
        new ImageGenerationRequest
        {
            Prompt = "A glass pavilion at sunrise",
            Count = 1,
            Size = "1024x1024"
        });

    IReadOnlyList<GeneratedImage> images = result.Images;
}

DefaultImageModel is independent from IAIService.Model. ImageEditRequest adds ordered InputImages and an optional Mask; provider support varies. OpenAI supports mask editing, while Gemini accepts reference images but rejects a separate mask and requires Count = 1.

Models

Streaming

Functions

When a slow lookup leaves room for independent model work, such as giving general advice while waiting for a forecast, AllowAsync permits the two to overlap on a supporting provider, model, and API. The implementation currently enables it for GPT-6 Astra through Responses; other connections omit the API option and wait for the same handler's result. The permission is preserved when switching models. FunctionCall.IsAsync records the provider's actual call status, so enabling the permission does not guarantee async execution. In Mythosia.AI, FunctionBuilder.WithAsync() is the fluent equivalent of AllowAsync = true.

This is separate from Task-returning handlers and FunctionExecutionMode.Parallel. Pending function jobs belong to the existing completion or streaming request; they are completed and cleaned up before that request ends. Handlers do not receive cancellation tokens, so cancelling or disposing the request does not interrupt an already-started handler.

Exceptions

Relationship to Microsoft.Extensions.AI

IAIService is Mythosia.AI's provider-neutral contract and is independent from Microsoft.Extensions.AI.IChatClient. It exposes Mythosia-specific stateful sessions (ChatBlock), request profiles and contexts, typed streaming events, and the built-in multi-round function loop. This package does not implement or reference IChatClient, and the two interfaces are not implicitly interchangeable.

Applications that use both ecosystems should put an explicit adapter at their integration boundary and decide how message history, tool execution, streaming metadata, and usage are mapped. Keeping that conversion explicit avoids silently losing semantics when either abstraction evolves.

Why This Package?

Mythosia.AI.Rag  →  Mythosia.AI.Abstractions  (no provider SDK dependencies)
                     instead of
                     Mythosia.AI  (Azure.AI.OpenAI, NJsonSchema, TiktokenSharp, ...)

By depending on abstractions rather than the full implementation package, libraries like Mythosia.AI.Rag avoid pulling in provider-specific dependencies. The concrete provider is chosen by the final application.

Links

• Mythosia.AI (implementation)
• GitHub
• Documentation
• v3.1.0 Release Notes