@vargai/sdk 0.1.1

package/lib/groq.ts

@@ -0,0 +1,246 @@
+#!/usr/bin/env bun
+
+/**
+ * groq api wrapper for ultra-fast llm inference
+ * supports llama, mixtral, gemma models with blazing fast speeds
+ */
+
+import Groq from "groq-sdk";
+import type { Uploadable } from "groq-sdk/uploads";
+
+const groq = new Groq({
+  apiKey: process.env.GROQ_API_KEY || "",
+});
+
+// types
+export interface ChatCompletionOptions {
+  model?: string;
+  messages: Array<{
+    role: "system" | "user" | "assistant";
+    content: string;
+  }>;
+  temperature?: number;
+  maxTokens?: number;
+  stream?: boolean;
+}
+
+export interface TranscriptionOptions {
+  file: Uploadable;
+  model?: string;
+  language?: string;
+  prompt?: string;
+  temperature?: number;
+}
+
+// popular models
+export const GROQ_MODELS = {
+  // llama models (meta)
+  LLAMA_90B: "llama-3.3-70b-versatile",
+  LLAMA_8B: "llama-3.1-8b-instant",
+  LLAMA_70B: "llama-3.1-70b-versatile",
+
+  // mixtral models (mistral)
+  MIXTRAL_8X7B: "mixtral-8x7b-32768",
+
+  // gemma models (google)
+  GEMMA_7B: "gemma-7b-it",
+  GEMMA_2_9B: "gemma2-9b-it",
+
+  // whisper for audio transcription
+  WHISPER_LARGE: "whisper-large-v3",
+};
+
+// core functions
+export async function chatCompletion(options: ChatCompletionOptions) {
+  const {
+    model = GROQ_MODELS.LLAMA_90B,
+    messages,
+    temperature = 1,
+    maxTokens = 1024,
+    stream = false,
+  } = options;
+
+  if (!messages || messages.length === 0) {
+    throw new Error("messages array is required");
+  }
+
+  console.log(`[groq] chat completion with ${model}...`);
+
+  try {
+    if (stream) {
+      const streamResponse = await groq.chat.completions.create({
+        model,
+        messages,
+        temperature,
+        max_tokens: maxTokens,
+        stream: true,
+      });
+      console.log(`[groq] streaming response...`);
+      return streamResponse;
+    }
+
+    const response = await groq.chat.completions.create({
+      model,
+      messages,
+      temperature,
+      max_tokens: maxTokens,
+      stream: false,
+    });
+
+    const content = response.choices[0]?.message?.content || "";
+    console.log(`[groq] completed (${response.usage?.total_tokens} tokens)`);
+    return content;
+  } catch (error) {
+    console.error(`[groq] error:`, error);
+    throw error;
+  }
+}
+
+export async function transcribeAudio(options: TranscriptionOptions) {
+  const {
+    file,
+    model = GROQ_MODELS.WHISPER_LARGE,
+    language,
+    prompt,
+    temperature,
+  } = options;
+
+  if (!file) {
+    throw new Error("file is required");
+  }
+
+  console.log(`[groq] transcribing audio with ${model}...`);
+
+  try {
+    const response = await groq.audio.transcriptions.create({
+      file,
+      model,
+      language,
+      prompt,
+      temperature,
+    });
+
+    console.log(`[groq] transcription completed`);
+    return response.text;
+  } catch (error) {
+    console.error(`[groq] error:`, error);
+    throw error;
+  }
+}
+
+export async function listModels() {
+  console.log(`[groq] fetching available models...`);
+
+  try {
+    const response = await groq.models.list();
+    const models = Array.from(response.data);
+    console.log(`[groq] found ${models.length} models`);
+    return models;
+  } catch (error) {
+    console.error(`[groq] error:`, error);
+    throw error;
+  }
+}
+
+// cli
+async function cli() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "help") {
+    console.log(`
+usage:
+  bun run lib/groq.ts <command> [args]
+
+commands:
+  chat <prompt> [model]              chat completion
+  stream <prompt> [model]            streaming chat completion
+  models                             list available models
+  help                               show this help
+
+examples:
+  bun run lib/groq.ts chat "explain quantum computing"
+  bun run lib/groq.ts chat "write a haiku about cats" llama-3.1-8b-instant
+  bun run lib/groq.ts stream "tell me a story"
+  bun run lib/groq.ts models
+
+popular models:
+  llama-3.3-70b-versatile    - meta llama 3.3 70b (best quality)
+  llama-3.1-8b-instant       - meta llama 3.1 8b (fastest)
+  llama-3.1-70b-versatile    - meta llama 3.1 70b
+  mixtral-8x7b-32768         - mistral mixtral 8x7b
+  gemma2-9b-it               - google gemma 2 9b
+  whisper-large-v3           - openai whisper (audio transcription)
+
+environment:
+  GROQ_API_KEY - your groq api key
+    `);
+    process.exit(0);
+  }
+
+  try {
+    switch (command) {
+      case "chat": {
+        const prompt = args[1];
+        const model = args[2];
+
+        if (!prompt) {
+          throw new Error("prompt is required");
+        }
+
+        const response = await chatCompletion({
+          model: model || GROQ_MODELS.LLAMA_90B,
+          messages: [{ role: "user", content: prompt }],
+        });
+
+        console.log(`\n${response}\n`);
+        break;
+      }
+
+      case "stream": {
+        const prompt = args[1];
+        const model = args[2];
+
+        if (!prompt) {
+          throw new Error("prompt is required");
+        }
+
+        const stream = await chatCompletion({
+          model: model || GROQ_MODELS.LLAMA_90B,
+          messages: [{ role: "user", content: prompt }],
+          stream: true,
+        });
+
+        console.log("");
+        for await (const chunk of stream as AsyncIterable<{
+          choices: Array<{ delta: { content?: string } }>;
+        }>) {
+          const content = chunk.choices[0]?.delta?.content || "";
+          process.stdout.write(content);
+        }
+        console.log("\n");
+        break;
+      }
+
+      case "models": {
+        const models = await listModels();
+        console.log(
+          `\navailable models:\n${models.map((m) => `  ${m.id} - ${m.owned_by}`).join("\n")}\n`,
+        );
+        break;
+      }
+
+      default:
+        console.error(`unknown command: ${command}`);
+        console.log(`run 'bun run lib/groq.ts help' for usage`);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`[groq] error:`, error);
+    process.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  cli();
+}

package/lib/higgsfield/MIGRATION.md

@@ -0,0 +1,308 @@
+# Migration Guide: @higgsfield/client to HTTP API
+
+This guide helps you migrate from the old `@higgsfield/client` library to the new HTTP-based implementation.
+
+## Summary of Changes
+
+### What Changed
+
+1. **No external client library** - Now uses native `fetch()` for HTTP requests
+2. **Response structure** - New structure matching the official API
+3. **Parameter naming** - Uses snake_case (API convention) instead of camelCase
+4. **Queue management** - Direct access to status checking and cancellation
+5. **Webhook support** - Built-in webhook functionality
+
+### What Stayed the Same
+
+- Authentication via environment variables
+- Core functionality (generate, list styles)
+- CLI commands (backward compatible)
+- Async/await patterns
+
+## API Changes
+
+### Before (Old Client)
+
+```typescript
+import { HiggsfieldClient, SoulSize, SoulQuality } from "@higgsfield/client";
+
+const client = new HiggsfieldClient({
+  apiKey: process.env.HF_API_KEY,
+  apiSecret: process.env.HF_API_SECRET,
+});
+
+const jobSet = await client.generate("/v1/text2image/soul", {
+  prompt: "beautiful sunset",
+  width_and_height: SoulSize.PORTRAIT_1152x2048,
+  quality: SoulQuality.HD,
+  style_id: "some-style-id",
+  batch_size: 1,
+  enhance_prompt: false,
+});
+
+// Access results
+const imageUrl = jobSet.jobs[0].results.raw.url;
+console.log(jobSet.id);
+console.log(jobSet.isCompleted);
+```
+
+### After (New HTTP API)
+
+```typescript
+import { generateSoul, SoulSize, SoulQuality } from "./lib/higgsfield/soul";
+
+const result = await generateSoul({
+  prompt: "beautiful sunset",
+  width_and_height: SoulSize.PORTRAIT_1152x2048,
+  quality: SoulQuality.HD,
+  style_id: "some-style-id",
+  batch_size: 1,
+  enhance_prompt: false,
+});
+
+// Access results
+const imageUrl = result.images[0].url;
+console.log(result.request_id);
+console.log(result.status === "completed");
+```
+
+## Response Structure Changes
+
+### Old Structure
+
+```typescript
+{
+  id: string;
+  isCompleted: boolean;
+  isFailed: boolean;
+  jobs: Array<{
+    results: {
+      raw: { url: string };
+    };
+  }>;
+}
+```
+
+### New Structure
+
+```typescript
+{
+  status: "queued" | "in_progress" | "completed" | "failed" | "nsfw" | "canceled";
+  request_id: string;
+  status_url: string;
+  cancel_url: string;
+  images?: Array<{ url: string }>;
+  video?: { url: string };
+  error?: string;
+}
+```
+
+## Common Migration Patterns
+
+### Pattern 1: Simple Generation
+
+**Before:**
+```typescript
+const jobSet = await client.generate("/v1/text2image/soul", {
+  prompt: "test",
+  width_and_height: SoulSize.PORTRAIT_1152x2048,
+});
+
+if (jobSet.isCompleted && jobSet.jobs.length > 0) {
+  const url = jobSet.jobs[0].results.raw.url;
+}
+```
+
+**After:**
+```typescript
+const result = await generateSoul({
+  prompt: "test",
+  width_and_height: SoulSize.PORTRAIT_1152x2048,
+});
+
+if (result.status === "completed" && result.images) {
+  const url = result.images[0].url;
+}
+```
+
+### Pattern 2: Error Handling
+
+**Before:**
+```typescript
+if (jobSet.isFailed) {
+  console.error("Generation failed");
+}
+```
+
+**After:**
+```typescript
+if (result.status === "failed") {
+  console.error(`Generation failed: ${result.error}`);
+} else if (result.status === "nsfw") {
+  console.error("Content flagged as NSFW");
+}
+```
+
+### Pattern 3: List Styles
+
+**Before:**
+```typescript
+const styles = await client.getSoulStyles();
+```
+
+**After:**
+```typescript
+import { listSoulStyles } from "./lib/higgsfield/soul";
+
+const styles = await listSoulStyles();
+```
+
+## New Features
+
+### 1. Manual Queue Management
+
+```typescript
+import { SoulClient } from "./lib/higgsfield/soul";
+
+const client = new SoulClient();
+
+// Submit request
+const request = await client.submitRequest("soul", {
+  prompt: "test",
+});
+
+// Check status later
+const status = await client.getStatus(request.request_id);
+
+// Cancel if needed
+if (status.status === "queued") {
+  await client.cancelRequest(request.request_id);
+}
+```
+
+### 2. Webhook Support
+
+```typescript
+const result = await generateSoul(
+  {
+    prompt: "test",
+  },
+  {
+    webhook: "https://your-webhook.url/endpoint",
+  },
+);
+
+// Returns immediately with request info
+// Your webhook receives the result when ready
+```
+
+### 3. Status Updates During Generation
+
+```typescript
+const result = await generateSoul(
+  {
+    prompt: "test",
+  },
+  {
+    onUpdate: (status) => {
+      console.log(`Current status: ${status.status}`);
+    },
+  },
+);
+```
+
+## Breaking Changes Checklist
+
+- [ ] Update imports from `@higgsfield/client` to `./lib/higgsfield/soul`
+- [ ] Change `jobSet.jobs[0].results.raw.url` to `result.images[0].url`
+- [ ] Change `jobSet.id` to `result.request_id`
+- [ ] Change `jobSet.isCompleted` to `result.status === "completed"`
+- [ ] Change `jobSet.isFailed` to `result.status === "failed"`
+- [ ] Remove `@higgsfield/client` from package.json
+- [ ] Run `bun install` to clean up dependencies
+- [ ] Update parameter names to snake_case if using object literals
+
+## Environment Variables
+
+No changes needed - same variables work:
+
+```bash
+export HIGGSFIELD_API_KEY="your-key"
+export HIGGSFIELD_SECRET="your-secret"
+
+# or
+
+export HF_API_KEY="your-key"
+export HF_API_SECRET="your-secret"
+```
+
+## CLI Commands
+
+### Backward Compatible
+
+```bash
+# Old commands still work
+bun run lib/higgsfield.ts generate_soul "prompt"
+bun run lib/higgsfield.ts list_styles
+```
+
+### New Commands (More Features)
+
+```bash
+# Generate
+bun run lib/higgsfield/soul.ts generate "prompt" "style-id"
+
+# List styles
+bun run lib/higgsfield/soul.ts list_styles
+
+# Check status
+bun run lib/higgsfield/soul.ts status "request-id"
+
+# Cancel request
+bun run lib/higgsfield/soul.ts cancel "request-id"
+```
+
+## Testing Your Migration
+
+```bash
+# Run examples to verify everything works
+bun run lib/higgsfield/example.ts simple
+bun run lib/higgsfield/example.ts style
+bun run lib/higgsfield/example.ts all
+```
+
+## Rollback Plan
+
+If you need to temporarily rollback:
+
+1. Reinstall the old client:
+   ```bash
+   bun add @higgsfield/client@^0.1.2
+   ```
+
+2. Restore old imports in your code
+
+3. The old implementation is still available in git history if needed
+
+## Getting Help
+
+- See `lib/higgsfield/README.md` for full documentation
+- See `lib/higgsfield/example.ts` for usage examples
+- Check the official API docs at https://platform.higgsfield.ai
+
+## Benefits of Migration
+
+✅ No external client library dependency  
+✅ Full control over HTTP requests  
+✅ Webhook support for production workflows  
+✅ Better error messages  
+✅ Cancel pending requests  
+✅ Direct API compatibility  
+✅ Smaller bundle size  
+✅ More TypeScript types  
+
+## Questions?
+
+Open an issue or check the examples in `lib/higgsfield/example.ts` for common use cases.
+
+