groq-module 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+groq-module
+
+A lightweight Node.js module for interacting with the Groq API. Easily send messages to AI models, manage conversation history, configure response formats, and process structured JSON responses with a simple interface.
+
+Features
+Simple integration with the Groq API
+Support for multiple Groq models
+Automatic language detection
+Configurable response language
+Optional plain-text response mode
+JSON and JSON Schema response support
+Conversation history management
+Custom API key support
+Environment variable support
+Installation
+bash
+npm install groq-module
+
+
+For environment variable management, you can optionally install dotenv:
+
+bash
+npm install dotenv
+
+Configuration
+
+Create a .env file in your project root:
+
+env
+GROQ_API_KEY=your_groq_api_key
+
+
+You can obtain an API key from the Groq Console.
+
+Usage
+
+Import the askGroq function:
+
+javascript
+import { askGroq } from "groq-module";
+
+Basic Example
+javascript
+const response = await askGroq("Hello, how are you?");
+
+console.log(response);
+
+
+The module automatically detects the language of the user's message and responds in the same language.
+
+Custom Model
+javascript
+const response = await askGroq(
+    "Explain how APIs work.",
+    {
+        model: "openai/gpt-oss-120b"
+    }
+);
+
+console.log(response);
+
+Custom Response Language
+javascript
+const response = await askGroq(
+    "Hello!",
+    {
+        lang: "German"
+    }
+);
+
+Plain Text Mode
+
+Plain-text responses are enabled by default when no response format is specified.
+
+javascript
+const response = await askGroq(
+    "Explain JavaScript.",
+    {
+        plainText: true
+    }
+);
+
+JSON Responses
+
+Request structured JSON responses using the responseFormat option:
+
+javascript
+const response = await askGroq(
+    "Generate information about a fictional user.",
+    {
+        plainText: false,
+        responseFormat: {
+            type: "json_object"
+        }
+    }
+);
+
+console.log(response);
+
+
+JSON responses are automatically parsed into JavaScript objects.
+
+Conversation History
+
+Maintain conversations by passing previous messages through the chat option.
+
+javascript
+const [answer, chat] = await askGroq(
+    "My name is John.",
+    {
+        returnGroqChat: true
+    }
+);
+
+console.log(answer);
+
+const [nextAnswer, updatedChat] = await askGroq(
+    "What is my name?",
+    {
+        chat,
+        returnGroqChat: true
+    }
+);
+
+console.log(nextAnswer);
+
+Custom API Key
+
+You can provide a custom API key instead of using the environment variable:
+
+javascript
+const response = await askGroq(
+    "Hello!",
+    {
+        apiKey: "your_groq_api_key"
+    }
+);
+
+API Reference
+askGroq(messages, options)
+
+Sends a request to the Groq Chat Completions API.
+
+Parameter	Type	Default	Description
+messages	string | Array	Required	User message or array of messages
+apiKey	string | null	null	Custom Groq API key
+model	string	"openai/gpt-oss-120b"	Groq model identifier
+responseFormat	object | null	null	Requested response format
+lang	string | null	null	Preferred response language
+plainText	boolean	true	Requests plain-text responses
+returnGroqChat	boolean	false	Returns the updated conversation history
+chat	Array	[]	Previous conversation messages
+Return Values
+
+By default, askGroq() returns the assistant response.
+
+When returnGroqChat is enabled, it returns:
+
+javascript
+[
+    answer,
+    updatedChat
+]
+
+
+When JSON response formatting is enabled, the answer is automatically parsed into a JavaScript object.
+
+Error Handling
+
+The module throws errors when requests fail or invalid parameters are provided.
+
+javascript
+try {
+    const response = await askGroq("Hello!");
+
+    console.log(response);
+
+} catch (error) {
+    console.error("Groq API Error:", error.message);
+}
+
+Requirements
+Node.js 18 or newer
+A valid Groq API key
+Internet connection
+License
+
+MIT License

package/groqModule.js

@@ -0,0 +1,146 @@
+import "dotenv/config";
+
+async function modelExists(modelName) {
+    const response = await fetch(
+        "https://api.groq.com/openai/v1/models",
+        {
+            headers: {
+                Authorization: `Bearer ${process.env.GROQ_API_KEY}`
+            }
+        }
+    );
+
+    if (!response.ok) {
+        throw new Error("Modelle konnten nicht abgerufen werden: " + response.status);
+    }
+
+    const data = await response.json();
+
+    return data.data.some(model => model.id === modelName);
+}
+
+export async function askGroq(
+    messages,
+    {
+        apiKey = null,
+        model = "openai/gpt-oss-120b",
+        responseFormat = null,
+        lang = null,
+        plainText = true,
+        returnGroqChat = false,
+        chat = []
+    } = {}
+) {
+    try {
+        const key = apiKey || process.env.GROQ_API_KEY;
+
+        if (!key) {
+            throw new Error("GROQ_API_KEY wurde nicht angegeben!");
+        }
+
+        // String in Array umwandeln
+        if (typeof messages === "string") {
+            messages = [
+                { role: "user", content: messages }
+            ];
+        }
+
+        if (!Array.isArray(messages) || messages.length === 0) {
+            throw new Error("Ungültige Nachrichten!");
+        }
+
+        // Chatverlauf überprüfen
+        if (!Array.isArray(chat)) {
+            throw new Error("Chat muss ein Array sein!");
+        }
+
+        // System-Anweisungen erstellen
+        const instructions = [
+            lang
+                ? `Always respond in ${lang}.`
+                : "Detect the language of the user's message and respond in that same language.",
+
+            plainText && !responseFormat
+                ? "Use plain text only. Never use Markdown or LaTeX."
+                : "",
+
+            responseFormat
+                ? "Return the response as valid JSON matching the requested format."
+                : "",
+
+            "Always prioritize the most recent information available to you.",
+            "Keep answers concise. Avoid unnecessarily long sentences for simple questions."
+        ].filter(Boolean).join(" ");
+
+        // Gesamte Nachrichten zusammenstellen
+        const apiMessages = [
+            {
+                role: "system",
+                content: instructions
+            },
+            ...chat,
+            ...messages
+        ];
+
+        // API-Anfrage erstellen
+        const body = {
+            model,
+            messages: apiMessages
+        };
+
+        if (responseFormat) {
+            body.response_format = responseFormat;
+        }
+
+        // Anfrage senden
+        const response = await fetch(
+            "https://api.groq.com/openai/v1/chat/completions",
+            {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${key}`
+                },
+                body: JSON.stringify(body)
+            }
+        );
+
+        const data = await response.json();
+
+        if (!response.ok) {
+            throw new Error(
+                data.error?.message || "Groq API Fehler"
+            );
+        }
+
+        const content = data.choices[0].message.content;
+
+        // Antwort verarbeiten
+        const answer = (
+            responseFormat?.type === "json_schema" ||
+            responseFormat?.type === "json_object"
+        )
+            ? JSON.parse(content)
+            : content;
+
+        // Antwort und Chatverlauf zurückgeben
+        if (returnGroqChat) {
+            const updatedChat = [
+                ...chat,
+                ...messages,
+                data.choices[0].message
+            ];
+
+            return [
+                answer,
+                updatedChat
+            ];
+        }
+
+        return answer;
+
+    } catch (error) {
+        throw error;
+    }
+}
+

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "groq-module",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Ein einfaches Groq Node.js Modul",
+  "type": "module",
+  "main": "groqModule.js",
+  "dependencies": {
+    "dotenv": "^16.4.5"
+  },
+  "exports": "./groqModule.js"
+}