algochat-ai 1.0.0

package/src/index.js

@@ -0,0 +1,254 @@
+'use strict';
+
+/**
+ * algochat-ai — Public API
+ *
+ * This is the main entry point for the algochat-ai npm package.
+ * It exposes a clean, high-level API on top of the AlgoChatClient.
+ *
+ * Usage:
+ *   const algochat = require('algochat-ai');
+ *
+ *   // Simple one-shot chat (string input)
+ *   const reply = await algochat.chat('What is 2+2?');
+ *
+ *   // Full messages array (OpenAI style)
+ *   const reply = await algochat.chat([
+ *     { role: 'system', content: 'You are a helpful assistant.' },
+ *     { role: 'user',   content: 'What is 2+2?' },
+ *   ]);
+ *
+ *   // Streaming
+ *   await algochat.chatStream('Tell me a joke', (chunk) => process.stdout.write(chunk));
+ *
+ *   // Custom instance with options
+ *   const client = new algochat.AlgoChatClient({ debug: true, timeout: 60000 });
+ */
+
+const AlgoChatClient = require('./client');
+const { resolveModel, getModelList, ALGOCHAT_MODELS, DEFAULT_MODEL } = require('./models');
+const { v4: uuidv4 } = require('uuid');
+
+// ─── Singleton client (shared across simple helper calls) ─────────────────────
+let _defaultClient = null;
+function _getDefaultClient(options) {
+  if (!_defaultClient) _defaultClient = new AlgoChatClient(options || {});
+  return _defaultClient;
+}
+
+// ─── High-level helpers ───────────────────────────────────────────────────────
+
+/**
+ * Send a message and get the full AI response as a string.
+ *
+ * @param {string|Array} input
+ *   - string: a single user message
+ *   - Array: full OpenAI-style messages array [{role, content}, ...]
+ * @param {object} [options]
+ * @param {string} [options.model]        - Model ID (default: gemini-3-flash-preview)
+ * @param {string} [options.systemPrompt] - Override the default system prompt
+ * @param {boolean} [options.debug]       - Enable verbose logging
+ * @param {number} [options.timeout]      - Request timeout in ms (default: 90000)
+ * @returns {Promise<string>} - The AI's response text
+ *
+ * @example
+ * const reply = await algochat.chat('Hello!');
+ * console.log(reply);
+ */
+async function chat(input, options = {}) {
+  const client = _getDefaultClient(options);
+  const { model: requestedModel, systemPrompt } = options;
+
+  let messages;
+  let extractedSystemPrompt = systemPrompt;
+
+  if (typeof input === 'string') {
+    messages = [{ role: 'user', content: input }];
+  } else if (Array.isArray(input)) {
+    // Extract system message(s) from the array
+    messages = input.filter((m) => {
+      if (m.role === 'system') {
+        extractedSystemPrompt = extractedSystemPrompt || m.content;
+        return false;
+      }
+      return true;
+    });
+  } else {
+    throw new TypeError('input must be a string or an array of messages');
+  }
+
+  if (messages.length === 0) {
+    throw new Error('No user messages provided');
+  }
+
+  const resolvedModel = resolveModel(requestedModel);
+  const { stream } = await client.createChatStream({
+    model: resolvedModel,
+    messages,
+    systemPrompt: extractedSystemPrompt,
+  });
+
+  return client.streamToText(stream);
+}
+
+/**
+ * Stream the AI response chunk by chunk.
+ *
+ * @param {string|Array} input - Same as `chat()`
+ * @param {Function} onChunk  - Called with each text delta (string)
+ * @param {object} [options]  - Same as `chat()`
+ * @returns {Promise<string>} - The full accumulated response text
+ *
+ * @example
+ * await algochat.chatStream('Tell me a story', (chunk) => {
+ *   process.stdout.write(chunk);
+ * });
+ */
+async function chatStream(input, onChunk, options = {}) {
+  if (typeof onChunk !== 'function') throw new TypeError('onChunk must be a function');
+
+  const client = _getDefaultClient(options);
+  const { model: requestedModel, systemPrompt } = options;
+
+  let messages;
+  let extractedSystemPrompt = systemPrompt;
+
+  if (typeof input === 'string') {
+    messages = [{ role: 'user', content: input }];
+  } else if (Array.isArray(input)) {
+    messages = input.filter((m) => {
+      if (m.role === 'system') {
+        extractedSystemPrompt = extractedSystemPrompt || m.content;
+        return false;
+      }
+      return true;
+    });
+  } else {
+    throw new TypeError('input must be a string or an array of messages');
+  }
+
+  const resolvedModel = resolveModel(requestedModel);
+  const { stream } = await client.createChatStream({
+    model: resolvedModel,
+    messages,
+    systemPrompt: extractedSystemPrompt,
+  });
+
+  return new Promise((resolve, reject) => {
+    let fullText = '';
+    let buffer = '';
+
+    stream.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split('\n');
+      buffer = lines.pop();
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('data:')) continue;
+        const jsonStr = trimmed.slice(5).trim();
+        if (!jsonStr || jsonStr === '[DONE]') continue;
+        try {
+          const parsed = JSON.parse(jsonStr);
+          if (parsed.type === 'text-delta' && parsed.delta) {
+            fullText += parsed.delta;
+            onChunk(parsed.delta);
+          }
+        } catch {
+          // skip
+        }
+      }
+    });
+
+    stream.on('end', () => resolve(fullText));
+    stream.on('error', reject);
+  });
+}
+
+/**
+ * Create an OpenAI-compatible chat completion object (non-streaming).
+ * Useful when you need the same response shape as openai's SDK.
+ *
+ * @param {Array} messages    - OpenAI-style messages
+ * @param {object} [options]
+ * @param {string} [options.model]
+ * @param {string} [options.systemPrompt]
+ * @returns {Promise<object>}  - OpenAI-compatible completion object
+ */
+async function createCompletion(messages, options = {}) {
+  const text = await chat(messages, options);
+  const resolvedModel = resolveModel(options.model);
+  const now = Math.floor(Date.now() / 1000);
+  const id = `chatcmpl-${uuidv4().replace(/-/g, '').slice(0, 24)}`;
+  const promptTokens = Math.ceil(JSON.stringify(messages).length / 4);
+  const completionTokens = Math.ceil(text.length / 4);
+
+  return {
+    id,
+    object: 'chat.completion',
+    created: now,
+    model: resolvedModel,
+    choices: [
+      {
+        index: 0,
+        message: { role: 'assistant', content: text },
+        finish_reason: 'stop',
+        logprobs: null,
+      },
+    ],
+    usage: {
+      prompt_tokens: promptTokens,
+      completion_tokens: completionTokens,
+      total_tokens: promptTokens + completionTokens,
+    },
+    system_fingerprint: null,
+  };
+}
+
+/**
+ * Send a message with an image (multimodal).
+ *
+ * @param {string} text       - The text question about the image
+ * @param {string} imageUrl   - An https URL or base64 data URI (data:image/...)
+ * @param {object} [options]
+ * @returns {Promise<string>} - The AI response
+ *
+ * @example
+ * const desc = await algochat.chatWithImage(
+ *   'What is in this image?',
+ *   'https://example.com/photo.jpg'
+ * );
+ */
+async function chatWithImage(text, imageUrl, options = {}) {
+  return chat(
+    [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text },
+          { type: 'image_url', image_url: { url: imageUrl } },
+        ],
+      },
+    ],
+    options
+  );
+}
+
+// ─── Module exports ───────────────────────────────────────────────────────────
+
+module.exports = {
+  // High-level helpers
+  chat,
+  chatStream,
+  chatWithImage,
+  createCompletion,
+
+  // Factory for custom instances
+  AlgoChatClient,
+
+  // Model helpers
+  resolveModel,
+  getModelList,
+  ALGOCHAT_MODELS,
+  DEFAULT_MODEL,
+};

package/src/models.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * Model definitions and resolution helpers.
+ */
+
+const ALGOCHAT_MODELS = {
+  'gemini-3-flash-preview': {
+    id: 'gemini-3-flash-preview',
+    displayName: 'Gemini 3 Flash Preview',
+    contextWindow: 128000,
+    maxOutputTokens: 8192,
+    requiresAuth: false,  // Free — works without an AlgoChat account
+  },
+  'gemini-2.5-pro': {
+    id: 'gemini-2.5-pro',
+    displayName: 'Gemini 2.5 Pro',
+    contextWindow: 200000,
+    maxOutputTokens: 8192,
+    requiresAuth: true,   // Needs a logged-in AlgoChat session
+  },
+  'gemini-2.0-flash': {
+    id: 'gemini-2.0-flash',
+    displayName: 'Gemini 2.0 Flash',
+    contextWindow: 128000,
+    maxOutputTokens: 8192,
+    requiresAuth: true,
+  },
+};
+
+/** OpenAI model aliases → AlgoChat model IDs */
+const MODEL_ALIAS_MAP = {
+  'gpt-4o':        'gemini-3-flash-preview',
+  'gpt-4':         'gemini-3-flash-preview',
+  'gpt-3.5-turbo': 'gemini-3-flash-preview',
+  'gpt-4-turbo':   'gemini-3-flash-preview',
+  'gpt-4o-mini':   'gemini-3-flash-preview',
+};
+
+const DEFAULT_MODEL = 'gemini-3-flash-preview';
+
+/**
+ * Resolve any model name (OpenAI alias or AlgoChat native) to an AlgoChat model ID.
+ * Falls back to the default free model if unrecognised.
+ * @param {string} requestedModel
+ * @returns {string}
+ */
+function resolveModel(requestedModel) {
+  if (!requestedModel) return DEFAULT_MODEL;
+  if (ALGOCHAT_MODELS[requestedModel]) return requestedModel;
+  if (MODEL_ALIAS_MAP[requestedModel]) return MODEL_ALIAS_MAP[requestedModel];
+  return DEFAULT_MODEL;
+}
+
+/**
+ * Return all available models (native + aliases) in OpenAI /v1/models format.
+ * @returns {Array}
+ */
+function getModelList() {
+  const now = Math.floor(Date.now() / 1000);
+
+  const models = Object.values(ALGOCHAT_MODELS).map((m) => ({
+    id: m.id,
+    object: 'model',
+    created: now,
+    owned_by: 'algochat',
+    permission: [],
+    root: m.id,
+    parent: null,
+    requiresAuth: m.requiresAuth,
+  }));
+
+  const aliases = Object.entries(MODEL_ALIAS_MAP).map(([alias, target]) => ({
+    id: alias,
+    object: 'model',
+    created: now,
+    owned_by: 'algochat-alias',
+    permission: [],
+    root: target,
+    parent: null,
+    requiresAuth: false,
+  }));
+
+  return [...models, ...aliases];
+}
+
+module.exports = { ALGOCHAT_MODELS, MODEL_ALIAS_MAP, DEFAULT_MODEL, resolveModel, getModelList };