Alephbasys.Mana.Gateway.Client 2.0.2

Mana Gateway SDK

A .NET (C#) SDK for the Mana Gateway API.

Evaluation key: free (3 req/min). Replace with your own X-Key for production.

Table of Contents

1. Quickstart (5 minutes)
2. Installation
3. Sending a Prompt (Chat Completion)
4. Streaming Chat
5. Handling Rate Limits & Retries
6. Listing Models with Pagination
7. Error Handling
8. Migration (1.x → 2.0)
9. Analyzer & Codemod
10. FAQ
11. Contributing / License
12. Roadmap Snapshot
13. In‑Depth Usage (Advanced)

For a full advanced guide see: docs/USAGE.md

1. Quickstart (5 minutes)

using Alephbasys.Mana.Gateway.Client;
using Alephbasys.Mana.Gateway.Client.Models; // legacy wire layer

var http = new HttpClient();
var client = new ManaGatewayClient(http, apiKey: Environment.GetEnvironmentVariable("MANA_KEY") ?? "free");

var models = await client.GetModelsAsync();
Console.WriteLine($"Models: {models.Data.Length}");

var chat = await client.CreateChatCompletionAsync(
    new ChatCompletionRequest(
        Model: "gpt-3.5-turbo",
        Messages: new [] { new ChatMessage(ChatRole.User, "Say hello in Persian") }
    )
);
Console.WriteLine(chat.Choices.Length > 0 ? chat.Choices[0].Message.Content : "<no output>");

2. Installation

dotnet add package Alephbasys.Mana.Gateway.Client

3. Sending a Prompt (Chat Completion)

var completion = await client.CreateChatCompletionAsync(
    new ChatCompletionRequest(
        Model: "gpt-3.5-turbo",
        Messages: new [] { new ChatMessage(ChatRole.User, "Explain embeddings in one sentence") },
        Temperature: 0.7));
Console.WriteLine(completion.Choices[0].Message.Content);

Upcoming domain abstraction:

// var result = await mana.Chat.CreateAsync(new Domain.Chat.ChatCompletionRequest { ... });

4. Streaming Chat

using Alephbasys.Mana.Gateway.Client.Domain.Client; // streaming helper
using Alephbasys.Mana.Gateway.Client.Models;

var http2 = new HttpClient { BaseAddress = new Uri("https://api.alephbasys.ir") };
http2.DefaultRequestHeaders.Add("X-Key", Environment.GetEnvironmentVariable("MANA_KEY") ?? "free");

var wireRequest = new ChatCompletionRequest(
    Model: "gpt-3.5-turbo",
    Messages: new [] { new ChatMessage(ChatRole.User, "Stream the alphabet slowly") },
    Stream: true
);

await foreach (var ev in http2.StreamChatCompletionAsync(wireRequest))
{
    if (ev.ContentDelta is not null) Console.Write(ev.ContentDelta);
    if (ev.IsFinal) Console.WriteLine($"\n[done reason={ev.FinishReason ?? "?"}]");
}

5. Handling Rate Limits & Retries

using Alephbasys.Mana.Gateway.Client.Domain.Client;
var mana = new ManaClientBuilder()
    .UseApiKey("free")
    .WithRetryPolicy(maxRetries: 3)
    .Build();

try { await client.GetModelsAsync(ct); }
catch (ManaGatewayException ex) when (ex.Code == ManaErrorCode.RateLimited)
{
    await Task.Delay(ex.RetryAfter ?? TimeSpan.FromSeconds(2), ct);
}

6. Listing Models with Pagination

await foreach (var page in fetchPageFunc.PaginateAsync(pageSize: 50, ct))
{
    foreach (var item in page) Console.WriteLine(item.ModelId);
}

7. Error Handling

All failures throw ManaGatewayException with Code, StatusCode, RequestId, Hint, optional RetryAfter.

8. Migration (1.x → 2.0)

Legacy wire types (ModelsResponse, ChatCompletionResponse, etc.) are being replaced by domain models (ChatCompletionResult, embedding domain types). See docs/model-rename-map.md and docs/migration-1.x-to-2.0.md.

9. Analyzer & Codemod

Project Alephbasys.Mana.Gateway.Client.Analyzers provides migration diagnostics:

• MIG001: Wire chat → domain chat
• MIG002: Wire embedding → domain embedding

Add as analyzer reference for hints / code fixes.

10. FAQ

Why new names? Clarity & future-proofing.

Is the free key production safe? No—evaluation only.

Streaming reliability? Depends on backend SSE; helper tolerates minor malformed chunks.

How to report issues? Open a GitHub issue with repro + RequestId.

11. Contributing / License

PRs welcome for mappers, analyzers, domain evolution, and tooling. See LICENSE.

12. Roadmap Snapshot

• Builder & retry
• Typed errors
• Domain model spec & initial models
• Full mappers (chat, embeddings, health)
• Streaming chat events
• Analyzer & codemod (initial)
• Additional domain facades (Chat, Embeddings, Health) public surface
• Advanced streaming (tool calls / function calling deltas)

13. In‑Depth Usage (Advanced)

See the full guide: docs/USAGE.md