novixo-ai 0.1.1

package/README.md

@@ -0,0 +1,172 @@
+# novixo-ai
+
+Unified AI client for Node.js and the browser. One API for **15 AI providers** — with automatic fallback, rate-limit detection, and response caching built in.
+
+```bash
+npm install novixo-ai
+```
+
+---
+
+## Quick start
+
+```ts
+import { NovixoAI } from "novixo-ai";
+
+const ai = new NovixoAI({
+  keys: {
+    groq: process.env.GROQ_API_KEY,
+    gemini: process.env.GEMINI_API_KEY,
+    openai: process.env.OPENAI_API_KEY,
+  },
+});
+
+// Single prompt
+const text = await ai.ask("Explain recursion in simple terms");
+
+// Multi-turn chat
+const response = await ai.chat([
+  { role: "user", content: "What is a binary tree?" },
+  { role: "assistant", content: "A binary tree is..." },
+  { role: "user", content: "Give me an example in JavaScript" },
+]);
+
+console.log(response.text);
+console.log(response.provider); // which provider answered
+```
+
+---
+
+## Supported providers
+
+| Provider       | Key name        | Default model                              |
+|----------------|-----------------|---------------------------------------------|
+| Groq           | `groq`          | llama3-8b-8192                              |
+| Google Gemini  | `gemini`        | gemini-1.5-flash                            |
+| Anthropic      | `anthropic`     | claude-haiku-4-5-20251001                   |
+| OpenAI         | `openai`        | gpt-4o-mini                                 |
+| Cohere         | `cohere`        | command-r-plus                              |
+| Mistral        | `mistral`       | mistral-small-latest                        |
+| Together AI    | `together`      | meta-llama/Llama-3-8b-chat-hf               |
+| Perplexity     | `perplexity`    | llama-3-sonar-small-32k-chat                |
+| Hugging Face   | `huggingface`   | mistralai/Mistral-7B-Instruct-v0.2          |
+| OpenRouter     | `openrouter`    | openai/gpt-4o-mini (access to 100+ models) |
+| Fireworks AI   | `fireworks`     | llama-v3-8b-instruct                        |
+| DeepSeek       | `deepseek`      | deepseek-chat                               |
+| xAI (Grok)     | `xai`           | grok-beta                                   |
+| AI21           | `ai21`          | jamba-instruct                              |
+| NLP Cloud      | `nlpcloud`      | finetuned-llama-3-70b                       |
+
+---
+
+## How fallback works
+
+novixo-ai tries providers **left to right** in your priority order:
+
+1. If a provider is **rate limited**, it's skipped and retried after cooldown.
+2. If a provider **fails**, the next one is tried automatically.
+3. If **all providers fail**, an error is thrown with details from each attempt.
+
+Default order: `groq → gemini → openai → mistral → anthropic → ...`
+
+---
+
+## Configuration
+
+```ts
+const ai = new NovixoAI({
+  // Only add keys for providers you have access to
+  keys: {
+    groq:        "gsk_...",
+    gemini:      "AIza...",
+    openai:      "sk-...",
+    cohere:      "...",
+    mistral:     "...",
+    together:    "...",
+    perplexity:  "pplx-...",
+    huggingface: "hf_...",
+    openrouter:  "sk-or-...",
+    fireworks:   "fw-...",
+    deepseek:    "...",
+    xai:         "xai-...",
+    ai21:        "...",
+    nlpcloud:    "...",
+    anthropic:   "sk-ant-...",
+  },
+
+  // Custom priority order
+  providers: ["groq", "gemini", "mistral", "openai"],
+
+  // Override models per provider
+  models: {
+    openai:  "gpt-4o",
+    mistral: "mistral-large-latest",
+    groq:    "llama3-70b-8192",
+  },
+
+  maxTokens:   1024,     // default: 1024
+  temperature: 0.7,      // default: 0.7
+  cache:       true,     // default: true
+  cacheTTL:    300_000,  // default: 5 minutes
+});
+```
+
+---
+
+## API
+
+### `ai.ask(prompt, systemPrompt?)`
+Single-turn shorthand. Returns response text as a string.
+
+### `ai.chat(messages, options?)`
+Multi-turn chat. Returns an `AIResponse`:
+
+```ts
+{
+  text:       string   // The model's response
+  provider:   string   // Which provider answered
+  model:      string   // Which model was used
+  cached:     boolean  // Whether this came from cache
+  durationMs: number   // Time taken in milliseconds
+}
+```
+
+### `ai.clearCache()`
+Clears the in-memory response cache.
+
+### `ai.cacheSize`
+Number of cached entries.
+
+---
+
+## With system prompts
+
+```ts
+const res = await ai.chat(
+  [{ role: "user", content: "Summarise this for me: ..." }],
+  { systemPrompt: "You are a concise academic writing assistant." }
+);
+```
+
+## Force a specific provider for one call
+
+```ts
+const res = await ai.chat(messages, {
+  providers: ["openai"], // only use OpenAI for this call
+});
+```
+
+---
+
+## Part of the NovixoTech ecosystem
+
+- [novixo-engine](https://npmjs.com/package/novixo-engine) — Offline-first network SDK
+- [novixo-agent-logger](https://npmjs.com/package/novixo-agent-logger) — AI agent audit trail
+- **novixo-ai** — Multi-provider AI client ← you are here
+
+---
+
+## License
+
+MIT © [NovixoTech](https://github.com/NovixoTech)
+

package/dist/index.cjs

@@ -0,0 +1,501 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  NovixoAI: () => NovixoAI
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/cache.ts
+var ResponseCache = class {
+  constructor(ttlMs = 5 * 60 * 1e3) {
+    this.store = /* @__PURE__ */ new Map();
+    this.ttl = ttlMs;
+  }
+  key(messages, systemPrompt) {
+    return JSON.stringify({ messages, systemPrompt });
+  }
+  get(messages, systemPrompt) {
+    const k = this.key(messages, systemPrompt);
+    const entry = this.store.get(k);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(k);
+      return null;
+    }
+    return entry.value;
+  }
+  set(messages, value, systemPrompt) {
+    const k = this.key(messages, systemPrompt);
+    this.store.set(k, { value, expiresAt: Date.now() + this.ttl });
+  }
+  clear() {
+    this.store.clear();
+  }
+  get size() {
+    return this.store.size;
+  }
+};
+
+// src/providers.ts
+var DEFAULT_MODELS = {
+  groq: "llama3-8b-8192",
+  gemini: "gemini-1.5-flash",
+  anthropic: "claude-haiku-4-5-20251001",
+  openai: "gpt-4o-mini",
+  cohere: "command-r-plus",
+  mistral: "mistral-small-latest",
+  together: "meta-llama/Llama-3-8b-chat-hf",
+  perplexity: "llama-3-sonar-small-32k-chat",
+  huggingface: "mistralai/Mistral-7B-Instruct-v0.2",
+  openrouter: "openai/gpt-4o-mini",
+  fireworks: "accounts/fireworks/models/llama-v3-8b-instruct",
+  deepseek: "deepseek-chat",
+  xai: "grok-beta",
+  ai21: "jamba-instruct",
+  nlpcloud: "finetuned-llama-3-70b"
+};
+var rateLimitedUntil = {};
+function isRateLimited(provider) {
+  const until = rateLimitedUntil[provider];
+  if (!until) return false;
+  if (Date.now() > until) {
+    delete rateLimitedUntil[provider];
+    return false;
+  }
+  return true;
+}
+function markRateLimited(provider, retryAfterMs = 6e4) {
+  rateLimitedUntil[provider] = Date.now() + retryAfterMs;
+}
+function getRetryAfter(headers, fallback = 6e4) {
+  const val = headers.get("retry-after");
+  if (!val) return fallback;
+  const secs = parseFloat(val);
+  return isNaN(secs) ? fallback : secs * 1e3;
+}
+async function callOpenAICompat(url, authHeader, model, messages, systemPrompt, maxTokens, temperature, provider, extraBody = {}) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...authHeader },
+    body: JSON.stringify({
+      model,
+      messages: [
+        ...systemPrompt ? [{ role: "system", content: systemPrompt }] : [],
+        ...messages
+      ],
+      max_tokens: maxTokens,
+      temperature,
+      ...extraBody
+    })
+  });
+  if (res.status === 429) {
+    markRateLimited(provider, getRetryAfter(res.headers));
+    throw Object.assign(new Error(`${provider} rate limited`), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.error?.message || `${provider} ${res.status}`);
+  }
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+async function callGroq(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.groq.com/openai/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "groq"
+  );
+}
+async function callOpenAI(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.openai.com/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "openai"
+  );
+}
+async function callMistral(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.mistral.ai/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "mistral"
+  );
+}
+async function callTogether(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.together.xyz/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "together"
+  );
+}
+async function callPerplexity(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.perplexity.ai/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "perplexity"
+  );
+}
+async function callOpenRouter(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://openrouter.ai/api/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}`, "HTTP-Referer": "https://github.com/NovixoTech/novixo-ai" },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "openrouter"
+  );
+}
+async function callFireworks(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.fireworks.ai/inference/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "fireworks"
+  );
+}
+async function callDeepSeek(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.deepseek.com/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "deepseek"
+  );
+}
+async function callXAI(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.x.ai/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "xai"
+  );
+}
+async function callGemini(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`;
+  const contents = messages.map((m) => ({
+    role: m.role === "assistant" ? "model" : "user",
+    parts: [{ text: m.content }]
+  }));
+  const body = {
+    contents,
+    generationConfig: { maxOutputTokens: maxTokens, temperature }
+  };
+  if (systemPrompt) body.system_instruction = { parts: [{ text: systemPrompt }] };
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (res.status === 429) {
+    markRateLimited("gemini", getRetryAfter(res.headers));
+    throw Object.assign(new Error("Gemini rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.error?.message || `Gemini ${res.status}`);
+  }
+  const data = await res.json();
+  return data.candidates[0].content.parts[0].text;
+}
+async function callAnthropic(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const body = {
+    model,
+    max_tokens: maxTokens,
+    temperature,
+    messages: messages.filter((m) => m.role !== "system")
+  };
+  if (systemPrompt) body.system = systemPrompt;
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01"
+    },
+    body: JSON.stringify(body)
+  });
+  if (res.status === 429) {
+    markRateLimited("anthropic", getRetryAfter(res.headers));
+    throw Object.assign(new Error("Anthropic rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.error?.message || `Anthropic ${res.status}`);
+  }
+  const data = await res.json();
+  return data.content[0].text;
+}
+async function callCohere(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const history = messages.slice(0, -1).map((m) => ({
+    role: m.role === "assistant" ? "CHATBOT" : "USER",
+    message: m.content
+  }));
+  const lastMessage = messages[messages.length - 1]?.content ?? "";
+  const res = await fetch("https://api.cohere.com/v1/chat", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model,
+      message: lastMessage,
+      chat_history: history,
+      preamble: systemPrompt,
+      max_tokens: maxTokens,
+      temperature
+    })
+  });
+  if (res.status === 429) {
+    markRateLimited("cohere", getRetryAfter(res.headers));
+    throw Object.assign(new Error("Cohere rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.message || `Cohere ${res.status}`);
+  }
+  const data = await res.json();
+  return data.text;
+}
+async function callHuggingFace(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    `https://api-inference.huggingface.co/models/${model}/v1/chat/completions`,
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "huggingface"
+  );
+}
+async function callAI21(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.ai21.com/studio/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "ai21"
+  );
+}
+async function callNLPCloud(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const allMessages = [
+    ...systemPrompt ? [{ role: "system", content: systemPrompt }] : [],
+    ...messages
+  ];
+  const res = await fetch(`https://api.nlpcloud.io/v1/gpu/${model}/chatbot`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Token ${apiKey}`
+    },
+    body: JSON.stringify({
+      input: allMessages[allMessages.length - 1]?.content ?? "",
+      history: allMessages.slice(0, -1).map((m) => ({
+        input: m.role === "user" ? m.content : void 0,
+        response: m.role === "assistant" ? m.content : void 0
+      })),
+      max_length: maxTokens,
+      temperature
+    })
+  });
+  if (res.status === 429) {
+    markRateLimited("nlpcloud", getRetryAfter(res.headers));
+    throw Object.assign(new Error("NLPCloud rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.detail || `NLPCloud ${res.status}`);
+  }
+  const data = await res.json();
+  return data.response;
+}
+async function callProvider(provider, messages, systemPrompt, apiKey, modelOverride, maxTokens, temperature) {
+  const model = modelOverride ?? DEFAULT_MODELS[provider];
+  const map = {
+    groq: callGroq,
+    openai: callOpenAI,
+    mistral: callMistral,
+    together: callTogether,
+    perplexity: callPerplexity,
+    openrouter: callOpenRouter,
+    fireworks: callFireworks,
+    deepseek: callDeepSeek,
+    xai: callXAI,
+    gemini: callGemini,
+    anthropic: callAnthropic,
+    cohere: callCohere,
+    huggingface: callHuggingFace,
+    ai21: callAI21,
+    nlpcloud: callNLPCloud
+  };
+  const fn = map[provider];
+  if (!fn) throw new Error(`Unknown provider: ${provider}`);
+  return fn(messages, systemPrompt, apiKey, model, maxTokens, temperature);
+}
+
+// src/client.ts
+var DEFAULT_PROVIDERS = ["groq", "gemini", "anthropic"];
+var NovixoAI = class {
+  constructor(config) {
+    this.config = {
+      keys: config.keys,
+      providers: config.providers ?? DEFAULT_PROVIDERS,
+      models: config.models ?? {},
+      maxTokens: config.maxTokens ?? 1024,
+      temperature: config.temperature ?? 0.7,
+      cache: config.cache ?? true,
+      cacheTTL: config.cacheTTL ?? 5 * 60 * 1e3
+    };
+    this.cache = this.config.cache ? new ResponseCache(this.config.cacheTTL) : null;
+  }
+  /**
+   * Send a message and get a response.
+   * Tries providers in order, skipping rate-limited ones.
+   * Falls back automatically on failure.
+   *
+   * @example
+   * const res = await ai.chat([{ role: "user", content: "Explain recursion" }])
+   * console.log(res.text)
+   */
+  async chat(messages, options = {}) {
+    const systemPrompt = options.systemPrompt;
+    const providers = options.providers ?? this.config.providers;
+    const errors = [];
+    if (this.cache) {
+      const cached = this.cache.get(messages, systemPrompt);
+      if (cached) {
+        return {
+          text: cached,
+          provider: "groq",
+          // placeholder; cached means we don't know original
+          model: "cached",
+          cached: true,
+          durationMs: 0
+        };
+      }
+    }
+    for (const provider of providers) {
+      const apiKey = this.config.keys[provider];
+      if (!apiKey) continue;
+      if (isRateLimited(provider)) {
+        errors.push({ provider, message: "Rate limited, skipping", rateLimited: true });
+        continue;
+      }
+      const start = Date.now();
+      try {
+        const text = await callProvider(
+          provider,
+          messages,
+          systemPrompt,
+          apiKey,
+          this.config.models[provider],
+          this.config.maxTokens,
+          this.config.temperature
+        );
+        const response = {
+          text,
+          provider,
+          model: this.config.models[provider] ?? DEFAULT_MODELS[provider],
+          cached: false,
+          durationMs: Date.now() - start
+        };
+        if (this.cache) {
+          this.cache.set(messages, text, systemPrompt);
+        }
+        return response;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const rateLimited = err?.rateLimited === true;
+        errors.push({ provider, message, rateLimited });
+        console.warn(`[novixo-ai] ${provider} failed: ${message}`);
+      }
+    }
+    const summary = errors.map((e) => `${e.provider}: ${e.message}`).join(" | ");
+    throw new Error(`All AI providers failed. ${summary}`);
+  }
+  /**
+   * Convenience: single-turn prompt → response string.
+   *
+   * @example
+   * const text = await ai.ask("What is photosynthesis?")
+   */
+  async ask(prompt, systemPrompt) {
+    const res = await this.chat(
+      [{ role: "user", content: prompt }],
+      { systemPrompt }
+    );
+    return res.text;
+  }
+  /** Clear the response cache */
+  clearCache() {
+    this.cache?.clear();
+  }
+  /** How many entries are in the cache */
+  get cacheSize() {
+    return this.cache?.size ?? 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NovixoAI
+});

package/dist/index.d.cts

@@ -0,0 +1,69 @@
+type Provider = "groq" | "gemini" | "anthropic" | "openai" | "cohere" | "mistral" | "together" | "perplexity" | "huggingface" | "openrouter" | "fireworks" | "deepseek" | "xai" | "ai21" | "nlpcloud";
+interface Message {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+interface NovixoAIConfig {
+    /** API keys for each provider */
+    keys: Partial<Record<Provider, string>>;
+    /**
+     * Provider priority order. novixo-ai tries them left to right.
+     * Defaults to ["groq", "gemini", "openai", "mistral", "anthropic", ...]
+     */
+    providers?: Provider[];
+    /** Default model per provider. Override if needed. */
+    models?: Partial<Record<Provider, string>>;
+    /** Max tokens to generate (default: 1024) */
+    maxTokens?: number;
+    /** Temperature 0–1 (default: 0.7) */
+    temperature?: number;
+    /** Enable response caching (default: true) */
+    cache?: boolean;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTTL?: number;
+}
+interface AIResponse {
+    text: string;
+    provider: Provider;
+    model: string;
+    cached: boolean;
+    durationMs: number;
+}
+interface AIError {
+    provider: Provider;
+    message: string;
+    rateLimited: boolean;
+}
+
+declare class NovixoAI {
+    private config;
+    private cache;
+    constructor(config: NovixoAIConfig);
+    /**
+     * Send a message and get a response.
+     * Tries providers in order, skipping rate-limited ones.
+     * Falls back automatically on failure.
+     *
+     * @example
+     * const res = await ai.chat([{ role: "user", content: "Explain recursion" }])
+     * console.log(res.text)
+     */
+    chat(messages: Message[], options?: {
+        systemPrompt?: string;
+        /** Override provider order for this call only */
+        providers?: Provider[];
+    }): Promise<AIResponse>;
+    /**
+     * Convenience: single-turn prompt → response string.
+     *
+     * @example
+     * const text = await ai.ask("What is photosynthesis?")
+     */
+    ask(prompt: string, systemPrompt?: string): Promise<string>;
+    /** Clear the response cache */
+    clearCache(): void;
+    /** How many entries are in the cache */
+    get cacheSize(): number;
+}
+
+export { type AIError, type AIResponse, type Message, NovixoAI, type NovixoAIConfig, type Provider };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+type Provider = "groq" | "gemini" | "anthropic" | "openai" | "cohere" | "mistral" | "together" | "perplexity" | "huggingface" | "openrouter" | "fireworks" | "deepseek" | "xai" | "ai21" | "nlpcloud";
+interface Message {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+interface NovixoAIConfig {
+    /** API keys for each provider */
+    keys: Partial<Record<Provider, string>>;
+    /**
+     * Provider priority order. novixo-ai tries them left to right.
+     * Defaults to ["groq", "gemini", "openai", "mistral", "anthropic", ...]
+     */
+    providers?: Provider[];
+    /** Default model per provider. Override if needed. */
+    models?: Partial<Record<Provider, string>>;
+    /** Max tokens to generate (default: 1024) */
+    maxTokens?: number;
+    /** Temperature 0–1 (default: 0.7) */
+    temperature?: number;
+    /** Enable response caching (default: true) */
+    cache?: boolean;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTTL?: number;
+}
+interface AIResponse {
+    text: string;
+    provider: Provider;
+    model: string;
+    cached: boolean;
+    durationMs: number;
+}
+interface AIError {
+    provider: Provider;
+    message: string;
+    rateLimited: boolean;
+}
+
+declare class NovixoAI {
+    private config;
+    private cache;
+    constructor(config: NovixoAIConfig);
+    /**
+     * Send a message and get a response.
+     * Tries providers in order, skipping rate-limited ones.
+     * Falls back automatically on failure.
+     *
+     * @example
+     * const res = await ai.chat([{ role: "user", content: "Explain recursion" }])
+     * console.log(res.text)
+     */
+    chat(messages: Message[], options?: {
+        systemPrompt?: string;
+        /** Override provider order for this call only */
+        providers?: Provider[];
+    }): Promise<AIResponse>;
+    /**
+     * Convenience: single-turn prompt → response string.
+     *
+     * @example
+     * const text = await ai.ask("What is photosynthesis?")
+     */
+    ask(prompt: string, systemPrompt?: string): Promise<string>;
+    /** Clear the response cache */
+    clearCache(): void;
+    /** How many entries are in the cache */
+    get cacheSize(): number;
+}
+
+export { type AIError, type AIResponse, type Message, NovixoAI, type NovixoAIConfig, type Provider };

package/dist/index.js

@@ -0,0 +1,474 @@
+// src/cache.ts
+var ResponseCache = class {
+  constructor(ttlMs = 5 * 60 * 1e3) {
+    this.store = /* @__PURE__ */ new Map();
+    this.ttl = ttlMs;
+  }
+  key(messages, systemPrompt) {
+    return JSON.stringify({ messages, systemPrompt });
+  }
+  get(messages, systemPrompt) {
+    const k = this.key(messages, systemPrompt);
+    const entry = this.store.get(k);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(k);
+      return null;
+    }
+    return entry.value;
+  }
+  set(messages, value, systemPrompt) {
+    const k = this.key(messages, systemPrompt);
+    this.store.set(k, { value, expiresAt: Date.now() + this.ttl });
+  }
+  clear() {
+    this.store.clear();
+  }
+  get size() {
+    return this.store.size;
+  }
+};
+
+// src/providers.ts
+var DEFAULT_MODELS = {
+  groq: "llama3-8b-8192",
+  gemini: "gemini-1.5-flash",
+  anthropic: "claude-haiku-4-5-20251001",
+  openai: "gpt-4o-mini",
+  cohere: "command-r-plus",
+  mistral: "mistral-small-latest",
+  together: "meta-llama/Llama-3-8b-chat-hf",
+  perplexity: "llama-3-sonar-small-32k-chat",
+  huggingface: "mistralai/Mistral-7B-Instruct-v0.2",
+  openrouter: "openai/gpt-4o-mini",
+  fireworks: "accounts/fireworks/models/llama-v3-8b-instruct",
+  deepseek: "deepseek-chat",
+  xai: "grok-beta",
+  ai21: "jamba-instruct",
+  nlpcloud: "finetuned-llama-3-70b"
+};
+var rateLimitedUntil = {};
+function isRateLimited(provider) {
+  const until = rateLimitedUntil[provider];
+  if (!until) return false;
+  if (Date.now() > until) {
+    delete rateLimitedUntil[provider];
+    return false;
+  }
+  return true;
+}
+function markRateLimited(provider, retryAfterMs = 6e4) {
+  rateLimitedUntil[provider] = Date.now() + retryAfterMs;
+}
+function getRetryAfter(headers, fallback = 6e4) {
+  const val = headers.get("retry-after");
+  if (!val) return fallback;
+  const secs = parseFloat(val);
+  return isNaN(secs) ? fallback : secs * 1e3;
+}
+async function callOpenAICompat(url, authHeader, model, messages, systemPrompt, maxTokens, temperature, provider, extraBody = {}) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...authHeader },
+    body: JSON.stringify({
+      model,
+      messages: [
+        ...systemPrompt ? [{ role: "system", content: systemPrompt }] : [],
+        ...messages
+      ],
+      max_tokens: maxTokens,
+      temperature,
+      ...extraBody
+    })
+  });
+  if (res.status === 429) {
+    markRateLimited(provider, getRetryAfter(res.headers));
+    throw Object.assign(new Error(`${provider} rate limited`), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.error?.message || `${provider} ${res.status}`);
+  }
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+async function callGroq(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.groq.com/openai/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "groq"
+  );
+}
+async function callOpenAI(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.openai.com/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "openai"
+  );
+}
+async function callMistral(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.mistral.ai/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "mistral"
+  );
+}
+async function callTogether(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.together.xyz/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "together"
+  );
+}
+async function callPerplexity(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.perplexity.ai/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "perplexity"
+  );
+}
+async function callOpenRouter(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://openrouter.ai/api/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}`, "HTTP-Referer": "https://github.com/NovixoTech/novixo-ai" },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "openrouter"
+  );
+}
+async function callFireworks(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.fireworks.ai/inference/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "fireworks"
+  );
+}
+async function callDeepSeek(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.deepseek.com/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "deepseek"
+  );
+}
+async function callXAI(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.x.ai/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "xai"
+  );
+}
+async function callGemini(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`;
+  const contents = messages.map((m) => ({
+    role: m.role === "assistant" ? "model" : "user",
+    parts: [{ text: m.content }]
+  }));
+  const body = {
+    contents,
+    generationConfig: { maxOutputTokens: maxTokens, temperature }
+  };
+  if (systemPrompt) body.system_instruction = { parts: [{ text: systemPrompt }] };
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (res.status === 429) {
+    markRateLimited("gemini", getRetryAfter(res.headers));
+    throw Object.assign(new Error("Gemini rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.error?.message || `Gemini ${res.status}`);
+  }
+  const data = await res.json();
+  return data.candidates[0].content.parts[0].text;
+}
+async function callAnthropic(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const body = {
+    model,
+    max_tokens: maxTokens,
+    temperature,
+    messages: messages.filter((m) => m.role !== "system")
+  };
+  if (systemPrompt) body.system = systemPrompt;
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01"
+    },
+    body: JSON.stringify(body)
+  });
+  if (res.status === 429) {
+    markRateLimited("anthropic", getRetryAfter(res.headers));
+    throw Object.assign(new Error("Anthropic rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.error?.message || `Anthropic ${res.status}`);
+  }
+  const data = await res.json();
+  return data.content[0].text;
+}
+async function callCohere(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const history = messages.slice(0, -1).map((m) => ({
+    role: m.role === "assistant" ? "CHATBOT" : "USER",
+    message: m.content
+  }));
+  const lastMessage = messages[messages.length - 1]?.content ?? "";
+  const res = await fetch("https://api.cohere.com/v1/chat", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model,
+      message: lastMessage,
+      chat_history: history,
+      preamble: systemPrompt,
+      max_tokens: maxTokens,
+      temperature
+    })
+  });
+  if (res.status === 429) {
+    markRateLimited("cohere", getRetryAfter(res.headers));
+    throw Object.assign(new Error("Cohere rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.message || `Cohere ${res.status}`);
+  }
+  const data = await res.json();
+  return data.text;
+}
+async function callHuggingFace(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    `https://api-inference.huggingface.co/models/${model}/v1/chat/completions`,
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "huggingface"
+  );
+}
+async function callAI21(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  return callOpenAICompat(
+    "https://api.ai21.com/studio/v1/chat/completions",
+    { Authorization: `Bearer ${apiKey}` },
+    model,
+    messages,
+    systemPrompt,
+    maxTokens,
+    temperature,
+    "ai21"
+  );
+}
+async function callNLPCloud(messages, systemPrompt, apiKey, model, maxTokens, temperature) {
+  const allMessages = [
+    ...systemPrompt ? [{ role: "system", content: systemPrompt }] : [],
+    ...messages
+  ];
+  const res = await fetch(`https://api.nlpcloud.io/v1/gpu/${model}/chatbot`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Token ${apiKey}`
+    },
+    body: JSON.stringify({
+      input: allMessages[allMessages.length - 1]?.content ?? "",
+      history: allMessages.slice(0, -1).map((m) => ({
+        input: m.role === "user" ? m.content : void 0,
+        response: m.role === "assistant" ? m.content : void 0
+      })),
+      max_length: maxTokens,
+      temperature
+    })
+  });
+  if (res.status === 429) {
+    markRateLimited("nlpcloud", getRetryAfter(res.headers));
+    throw Object.assign(new Error("NLPCloud rate limited"), { rateLimited: true });
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.detail || `NLPCloud ${res.status}`);
+  }
+  const data = await res.json();
+  return data.response;
+}
+async function callProvider(provider, messages, systemPrompt, apiKey, modelOverride, maxTokens, temperature) {
+  const model = modelOverride ?? DEFAULT_MODELS[provider];
+  const map = {
+    groq: callGroq,
+    openai: callOpenAI,
+    mistral: callMistral,
+    together: callTogether,
+    perplexity: callPerplexity,
+    openrouter: callOpenRouter,
+    fireworks: callFireworks,
+    deepseek: callDeepSeek,
+    xai: callXAI,
+    gemini: callGemini,
+    anthropic: callAnthropic,
+    cohere: callCohere,
+    huggingface: callHuggingFace,
+    ai21: callAI21,
+    nlpcloud: callNLPCloud
+  };
+  const fn = map[provider];
+  if (!fn) throw new Error(`Unknown provider: ${provider}`);
+  return fn(messages, systemPrompt, apiKey, model, maxTokens, temperature);
+}
+
+// src/client.ts
+var DEFAULT_PROVIDERS = ["groq", "gemini", "anthropic"];
+var NovixoAI = class {
+  constructor(config) {
+    this.config = {
+      keys: config.keys,
+      providers: config.providers ?? DEFAULT_PROVIDERS,
+      models: config.models ?? {},
+      maxTokens: config.maxTokens ?? 1024,
+      temperature: config.temperature ?? 0.7,
+      cache: config.cache ?? true,
+      cacheTTL: config.cacheTTL ?? 5 * 60 * 1e3
+    };
+    this.cache = this.config.cache ? new ResponseCache(this.config.cacheTTL) : null;
+  }
+  /**
+   * Send a message and get a response.
+   * Tries providers in order, skipping rate-limited ones.
+   * Falls back automatically on failure.
+   *
+   * @example
+   * const res = await ai.chat([{ role: "user", content: "Explain recursion" }])
+   * console.log(res.text)
+   */
+  async chat(messages, options = {}) {
+    const systemPrompt = options.systemPrompt;
+    const providers = options.providers ?? this.config.providers;
+    const errors = [];
+    if (this.cache) {
+      const cached = this.cache.get(messages, systemPrompt);
+      if (cached) {
+        return {
+          text: cached,
+          provider: "groq",
+          // placeholder; cached means we don't know original
+          model: "cached",
+          cached: true,
+          durationMs: 0
+        };
+      }
+    }
+    for (const provider of providers) {
+      const apiKey = this.config.keys[provider];
+      if (!apiKey) continue;
+      if (isRateLimited(provider)) {
+        errors.push({ provider, message: "Rate limited, skipping", rateLimited: true });
+        continue;
+      }
+      const start = Date.now();
+      try {
+        const text = await callProvider(
+          provider,
+          messages,
+          systemPrompt,
+          apiKey,
+          this.config.models[provider],
+          this.config.maxTokens,
+          this.config.temperature
+        );
+        const response = {
+          text,
+          provider,
+          model: this.config.models[provider] ?? DEFAULT_MODELS[provider],
+          cached: false,
+          durationMs: Date.now() - start
+        };
+        if (this.cache) {
+          this.cache.set(messages, text, systemPrompt);
+        }
+        return response;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const rateLimited = err?.rateLimited === true;
+        errors.push({ provider, message, rateLimited });
+        console.warn(`[novixo-ai] ${provider} failed: ${message}`);
+      }
+    }
+    const summary = errors.map((e) => `${e.provider}: ${e.message}`).join(" | ");
+    throw new Error(`All AI providers failed. ${summary}`);
+  }
+  /**
+   * Convenience: single-turn prompt → response string.
+   *
+   * @example
+   * const text = await ai.ask("What is photosynthesis?")
+   */
+  async ask(prompt, systemPrompt) {
+    const res = await this.chat(
+      [{ role: "user", content: prompt }],
+      { systemPrompt }
+    );
+    return res.text;
+  }
+  /** Clear the response cache */
+  clearCache() {
+    this.cache?.clear();
+  }
+  /** How many entries are in the cache */
+  get cacheSize() {
+    return this.cache?.size ?? 0;
+  }
+};
+export {
+  NovixoAI
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "novixo-ai",
+  "version": "0.1.1",
+  "description": "Unified AI provider client with auto-fallback, rate-limit detection, and response caching. Works with Groq, Gemini, and Anthropic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "keywords": [
+    "ai",
+    "groq",
+    "gemini",
+    "anthropic",
+    "llm",
+    "fallback",
+    "multi-provider",
+    "novixo"
+  ],
+  "author": "NovixoTech",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}