Alephbasys.Mana.Gateway.Client 2.0.1

Mana Gateway SDK

A multi-language SDK (C# implemented, TypeScript & Python planned) 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 (preview)
5. Handling Rate Limits & Retries
6. Listing Models with Pagination
7. Error Handling
8. Migration (1.x → 2.0)
9. FAQ
10. Contributing / License

1. Quickstart (5 minutes)

C#

using Alephbasys.Mana.Gateway.Client;
using Alephbasys.Mana.Gateway.Client.Models; // legacy (will move to domain soon)

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

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

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

TypeScript (planned)

import { ManaClient } from '@mana-gateway/sdk';
const client = new ManaClient({ apiKey: process.env.MANA_KEY || 'free' });
const catalog = await client.models.list();
console.log('Models', catalog.models.length);
const result = await client.chat.complete({
  modelId: 'gpt-3.5-turbo',
  messages: [{ role: 'user', content: 'Say hello in Persian' }]
});
console.log(result.choices[0].message.content);

Python (planned)

from mana_gateway import ManaClient
client = ManaClient(api_key=os.getenv("MANA_KEY", "free"))
cat = client.models.list()
print("Models", len(cat.models))
resp = client.chat.complete(model_id="gpt-3.5-turbo", messages=[{"role":"user","content":"Say hello in Persian"}])
print(resp.choices[0].message.content)

2. Installation

C#

dotnet add package Alephbasys.Mana.Gateway.Client

TypeScript & Python packages will be published after domain API stabilization.

3. Sending a Prompt (Chat Completion)

Current C# surface (will migrate to domain names):

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);

Future domain API (preview intent):

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

4. Streaming (preview)

Streaming helpers (StreamingExtensions) provide an adapter pattern. A full streaming chat endpoint will surface as an IAsyncEnumerable<ChatStreamEvent> when the API supports SSE / chunked responses.

Conceptual usage:

await foreach (var delta in stream.ToAsyncEnumerable(ct))
{
    Console.Write(delta.Token);
}

5. Handling Rate Limits & Retries

The builder adds retry with exponential backoff + jitter for transient 5xx/408.

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

Explicit handling (typed errors):

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

Pagination helper is generic; once list endpoints accept page params you can do:

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

Where fetchPageFunc matches (pageIndex, pageSize, ct) => Task<IReadOnlyList<T>>.

7. Error Handling

All failures throw ManaGatewayException with Code, StatusCode, RequestId, Hint and optional RetryAfter. See: docs/errors.md.

8. Migration (1.x → 2.0)

Legacy wire types (ModelsResponse, ChatCompletionResponse, etc.) are marked [Obsolete]. Use domain models (e.g. ModelCatalog, ChatCompletionResult) as they land. Full rename map: docs/model-rename-map.md. Guide: docs/migration-1.x-to-2.0.md.

9. FAQ

Why new names? Improve clarity & future-proofing.

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

When will streaming be available? After server exposes SSE/chunk streaming; client scaffolding is ready.

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

10. Contributing / License

PRs welcome for mappings, mappers, analyzers, and language ports. See LICENSE.

Roadmap Snapshot

• Builder & retry
• Typed errors
• Domain model spec & initial models
• Full mappers (chat, embeddings, health)
• Streaming chat events
• TypeScript & Python ports
• Analyzer & codemod