Meilynx.Sdk 0.3.0

Meilynx .NET SDK

Meilynx is an AI governance and FinOps platform that gives enterprises visibility and control over LLM usage — from cost and compliance to business outcomes. This SDK lets you send structured telemetry and outcome events from your .NET applications.

Install

dotnet add package Meilynx.Sdk

Quickstart

Option 1: Tracked AI calls with context (recommended)

Wrap your AI calls for automatic telemetry — model, latency, and tokens are captured for you:

using Meilynx.Sdk;
using Meilynx.Sdk.Integrations;

var mx = new MeilynxClient(new MeilynxOptions
{
    ApiKey = "mx_live_...",  // BaseUrl defaults to https://api.meilynx.com
});

// Context propagation — all tracked calls inherit business metadata
await MeilynxContextScope.ObserveAsync(
    new ObserveOptions { FeatureKey = "search", CustomerId = "acme" },
    async () =>
    {
        // OpenAI
        var result = await OpenAiTracking.TrackAsync(mx, "gpt-4o", async () =>
        {
            return await chatClient.CompleteChatAsync(messages);
        });

        // Anthropic
        var response = await AnthropicTracking.TrackAsync(mx, "claude-sonnet-4-20250514", async () =>
        {
            return await anthropicClient.CreateMessageAsync(request);
        });
    });

await mx.ShutdownAsync();

Option 2: Explicit tracking

Full control over what you send:

using Meilynx.Sdk;

var mx = new MeilynxClient(new MeilynxOptions
{
    ApiKey = "mx_live_...",  // BaseUrl defaults to https://api.meilynx.com
});

mx.Track(new TelemetryEventInput
{
    EventType = "llm.response",
    CorrelationId = "run-123",
    CustomerId = "cust-acme",
    FeatureKey = "ask_docs",
    Model = "gpt-4o",
    Provider = "openai",
    PromptTokens = 1200,
    CompletionTokens = 220,
});

await mx.FlushAsync();
await mx.ShutdownAsync();

Which to choose? Use wrappers (Option 1) for most cases — they automatically capture model, latency, and agentic context with zero manual work. Use explicit tracking (Option 2) when you need custom event types, non-LLM operations, or providers without built-in integration.

Configuration

Environment variables (convention)

The SDK does not read environment variables directly. These are recommended names for your app configuration:

• MX_BASE_URL (optional) — Meilynx API URL
• MX_API_KEY — Project-scoped API key (mx_live_...)

Constructor options

Capturing outcomes

Outcomes are the business results your AI features produce:

using Meilynx.Sdk;

mx.CaptureOutcome(new OutcomeEventInput
{
    OutcomeType = "feature.result.accepted",
    IdempotencyKey = MeilynxIdempotency.MintIdempotencyKey("accepted", correlationId),
    CorrelationId = correlationId,
    CustomerId = "cust-acme",
    FeatureKey = "ask_docs",
    Attributes = new Dictionary<string, object?>
    {
        ["uiAction"] = "copy_clicked",
        ["timeToAcceptMs"] = 7000,
    },
});

Idempotency keys

Every outcome requires an IdempotencyKey to prevent duplicate processing. Use MeilynxIdempotency.MintIdempotencyKey() to generate a deterministic SHA-256 key from one or more fields:

using Meilynx.Sdk;

// Same inputs always produce the same key
MeilynxIdempotency.MintIdempotencyKey("accepted", "run-123");   // → "a1b2c3..."
MeilynxIdempotency.MintIdempotencyKey("accepted", "run-123");   // → "a1b2c3..." (same)
MeilynxIdempotency.MintIdempotencyKey("accepted", "run-456");   // → "d4e5f6..." (different)

Context propagation

The MeilynxContextScope.Observe / ObserveAsync methods propagate business context (correlation IDs, feature keys, customer IDs) through the async call stack using AsyncLocal<T>. All tracked AI calls inside inherit this context automatically:

MeilynxContextScope.Observe(
    new ObserveOptions { FeatureKey = "ask_docs", CustomerId = "acme" },
    () =>
    {
        // All tracked calls here are tagged with featureKey="ask_docs"
        var result = OpenAiTracking.Track(mx, "gpt-4o-mini", () =>
            chatClient.CompleteChat(messages));
    });

Nested scopes inherit the parent context and can override specific fields.

Agentic context

For agentic loops with multiple tool-call hops, set AgentName, ToolName, and StepIndex on each step:

for (int i = 0; i < steps.Count; i++)
{
    var step = steps[i];
    await MeilynxContextScope.ObserveAsync(
        new ObserveOptions { AgentName = "research-agent", ToolName = step.Name, StepIndex = i },
        async () =>
        {
            await OpenAiTracking.TrackAsync(mx, "gpt-4o", async () =>
                await chatClient.CompleteChatAsync(messages));
        });
}

The tracking helpers also capture ResponseToolCalls (tool names the model invoked) automatically from streaming and non-streaming responses.

Budget status

Check current budget utilization from your application. Results are cached for 60 seconds per query-parameter combination.

var status = await mx.GetBudgetStatusAsync(new BudgetStatusQuery { CustomerId = "acme" });

foreach (var budget in status.Budgets)
{
    if (budget.Action == "block")
        Console.WriteLine($"Budget {budget.Name} exceeded: {budget.UtilizationPct}%");
}

Failsafe behavior

The SDK is designed to never break your application. All tracking wrappers, context injection, and telemetry emission are wrapped in defensive error handling:

• If telemetry emission fails, the error is swallowed silently.
• Real LLM provider errors (rate limits, auth failures, invalid requests) always propagate normally.
• Your Func<Task<T>> callback always executes, regardless of any SDK-internal failure.

In other words: a bug in the Meilynx SDK will never cause your AI calls to fail.

Streaming

The tracking helpers handle streaming transparently. For both OpenAI and Anthropic:

• One telemetry event is emitted per completion (not per chunk)
• IsStreaming is set to true automatically
• LatencyMs measures time from request start to last token received
• Tool calls in the response are accumulated into ResponseToolCalls

await foreach (var chunk in OpenAiTracking.TrackStreamAsync(mx, "gpt-4o", stream))
{
    // process chunk as normal — telemetry is emitted when the stream completes
}

Error handling

• 429 and 5xx responses are retried with exponential backoff (max 4 seconds).
• 401/403 errors throw UnauthorizedAccessException immediately.
• Failed flushes re-enqueue events so they are not lost.

Batching and flushing

Events are buffered in memory and flushed automatically when the batch size (FlushAt) is reached or the flush interval elapses. Use FlushAsync() for deterministic delivery (e.g., before responding to an HTTP request) and ShutdownAsync() to drain queues before process exit.

Serverless and short-lived processes

In short-lived environments (Azure Functions, AWS Lambda via .NET), flush before the handler returns to avoid losing events:

// Azure Function / Minimal API endpoint
app.MapPost("/ask", async (AskRequest req) =>
{
    var result = await HandleRequest(req);
    await mx.FlushAsync();     // flush before returning
    return Results.Ok(result);
});

// Always call ShutdownAsync() when the host is stopping
lifetime.ApplicationStopping.Register(() => mx.ShutdownAsync().GetAwaiter().GetResult());

Set FlushIntervalMs = 0 to disable the background flush timer if the runtime does not support long-lived timers.

Compatibility

• .NET 10+ (targets net10.0)
• Thread-safe batching with background flush timer.
• Not intended for client-side use. API keys must stay server-side.

Docs

• Documentation: docs.meilynx.com
• JS/TS SDK: github.com/meilynx/meilynx-js
• Python SDK: github.com/meilynx/meilynx-python
• NuGet: nuget.org/packages/Meilynx.Sdk

License

MIT