PlimverAI JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for PlimverAI - Advanced AI API with Hybrid Memory, RAG, and Grounding.

Features

• ✅ Chat Completions - OpenAI-compatible chat API
• ✅ Streaming Support - Real-time response streaming
• ✅ Hybrid Memory - Redis + Pinecone vector memory
• ✅ RAG (Retrieval Augmented Generation) - Query your documents
• ✅ Grounding - Web search integration via Jina AI
• ✅ File Upload - PDF, TXT, DOCX support
• ✅ Code Execution - Safe Python code execution
• ✅ Weather Tool - Real-time weather information
• ✅ TypeScript Support - Full type definitions included
• ✅ ESM & CommonJS - Works in both module systems

Installation

npm

npm install plimverai

yarn

yarn add plimverai

pnpm

pnpm add plimverai

Quick Start

ES Modules (TypeScript/Modern JavaScript)

import { PlimverClient } from 'plimverai';

const client = new PlimverClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.zenuxai.tech' // Optional, this is default
});

// Simple chat
const response = await client.chat('Hello, PlimverAI!');
console.log(response.choices[0].message.content);

CommonJS (Node.js)

const { PlimverClient } = require('plimverai');

const client = new PlimverClient({
  apiKey: 'your-api-key'
});

// Async example
(async () => {
  const response = await client.chat('Hello!');
  console.log(response.choices[0].message.content);
})();

Usage Examples

Chat with Options

const response = await client.chat('Explain quantum computing', {
  model: 'gpt-4o-mini',
  temperature: 0.7,
  maxTokens: 1000,
  useGrounding: true  // Enable web search
});

console.log(response.choices[0].message.content);
console.log('Tokens used:', response.usage.total_tokens);

Chat with Conversation History

// First message
const response1 = await client.chatWithHistory(
  'My name is Alice',
  'user-session-123'
);

// Follow-up message - AI remembers context
const response2 = await client.chatWithHistory(
  'What is my name?',
  'user-session-123'
);

console.log(response2.choices[0].message.content); // "Your name is Alice"

Streaming Responses

await client.chatStream(
  'Write a short story',
  { model: 'gpt-4o-mini' },
  (chunk) => {
    // Called for each chunk received
    process.stdout.write(chunk);
  }
);

RAG (Document Querying)

// First, upload a document
await client.uploadFile({
  file: fileBuffer, // or File object in browser
  filename: 'document.pdf',
  sessionId: 'session-123'
});

// Query the document
const response = await client.ragQuery(
  'What are the main points in the document?',
  'session-123',
  { topK: 5 }
);

console.log(response.choices[0].message.content);
console.log('Citations:', response.citations);

File Management

// List files in session
const files = await client.listFiles('session-123');
console.log('Files:', files);

// Delete a file
await client.deleteFile('document.pdf', 'session-123');

Weather Tool

const weather = await client.getWeather('New York');
console.log(`Temperature: ${weather.temperature}°C`);
console.log(`Condition: ${weather.condition}`);

Code Execution

const result = await client.executeCode(`
print("Hello from Python!")
x = 2 + 2
print(f"2 + 2 = {x}")
`);

console.log(result.output);
console.log('Execution time:', result.execution_time);

Usage Statistics

const stats = await client.getUsageStats();
console.log(`Total requests: ${stats.total_requests}`);
console.log(`Remaining: ${stats.remaining}/${stats.limit}`);

Health Check

const health = await client.healthCheck();
console.log('API Status:', health.status);

API Reference

Constructor

new PlimverClient(config)

Creates a new PlimverAI client instance.

Parameters:

• config.apiKey (string, required) - Your PlimverAI API key
• config.baseUrl (string, optional) - API base URL (default: https://api.zenuxai.tech)

Methods

chat(message, options?)

Send a chat message.

Parameters:

• message (string) - The message to send
• options (object, optional):
  • model (string) - Model to use (default: gpt-4o-mini)
  • temperature (number) - Sampling temperature 0-1 (default: 0.7)
  • maxTokens (number) - Maximum tokens in response (default: 2000)
  • useGrounding (boolean) - Enable web search (default: false)
  • customK (number) - Custom RAG retrieval count

Returns: Promise<ChatResponse>

chatWithHistory(message, sessionId, options?)

Send a chat message with conversation history.

Parameters:

• message (string) - The message to send
• sessionId (string) - Session ID for memory context
• options (object, optional) - Same as chat()

Returns: Promise<ChatResponse>

chatStream(message, options?, onChunk)

Stream chat responses in real-time.

Parameters:

• message (string) - The message to send
• options (object, optional) - Same as chat()
• onChunk (function) - Callback for each chunk: (chunk: string) => void

Returns: Promise<void>

ragQuery(query, sessionId, options?)

Query uploaded documents using RAG.

Parameters:

• query (string) - The query string
• sessionId (string) - Session ID with uploaded documents
• options (object, optional):
  • topK (number) - Number of relevant chunks to retrieve (default: 5)
  • model (string) - Model to use (default: gpt-4o-mini)
  • temperature (number) - Sampling temperature (default: 0.7)

Returns: Promise<RAGQueryResponse> - Includes citations array

uploadFile(options)

Upload a file for RAG processing.

Parameters:

• options.file (File | Buffer) - File to upload
• options.filename (string) - Filename
• options.sessionId (string) - Session ID

Returns: Promise<FileUploadResponse>

listFiles(sessionId)

List all uploaded files in a session.

Parameters:

• sessionId (string) - Session ID

Returns: Promise<string[]> - Array of filenames

deleteFile(filename, sessionId)

Delete an uploaded file.

Parameters:

• filename (string) - Filename to delete
• sessionId (string) - Session ID

Returns: Promise<{success: boolean, message: string}>

getWeather(location)

Get weather information for a location.

Parameters:

• location (string) - City name or coordinates

Returns: Promise<WeatherResponse>

executeCode(code)

Execute Python code safely.

Parameters:

• code (string) - Python code to execute

Returns: Promise<CodeExecutionResponse>

getUsageStats()

Get API usage statistics.

Returns: Promise<UsageStats>

healthCheck()

Check API health status.

Returns: Promise<{status: string, timestamp: string}>

TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

import {
  PlimverClient,
  ChatResponse,
  RAGQueryResponse,
  ChatOptions,
  UsageStats
} from 'plimverai';

const client = new PlimverClient({ apiKey: 'your-key' });

// Full type inference
const response: ChatResponse = await client.chat('Hello!');
const content: string = response.choices[0].message.content;
const tokens: number = response.usage.total_tokens;

Error Handling

try {
  const response = await client.chat('Hello!');
  console.log(response.choices[0].message.content);
} catch (error) {
  if (error.response) {
    // API returned an error
    console.error('API Error:', error.response.status);
    console.error('Message:', error.response.data);
  } else if (error.request) {
    // Request was made but no response received
    console.error('Network Error:', error.message);
  } else {
    // Other errors
    console.error('Error:', error.message);
  }
}

Advanced Usage

Custom Axios Instance

import axios from 'axios';
import { PlimverClient } from 'plimverai';

const client = new PlimverClient({
  apiKey: 'your-key',
  baseUrl: 'https://api.zenuxai.tech'
});

// The client uses axios internally with:
// - 60s timeout
// - Bearer token authentication
// - Automatic retry on network errors

Parallel Requests

// Send multiple requests in parallel
const [response1, response2, response3] = await Promise.all([
  client.chat('What is AI?'),
  client.chat('What is ML?'),
  client.chat('What is DL?')
]);

Browser Usage

The SDK works in browsers with bundlers like Webpack, Vite, or Rollup:

import { PlimverClient } from 'plimverai';

const client = new PlimverClient({
  apiKey: import.meta.env.VITE_PLIMVERAI_KEY // or process.env.REACT_APP_KEY
});

async function handleChat() {
  const response = await client.chat(userMessage);
  displayMessage(response.choices[0].message.content);
}

Examples

Complete Chat Application

import { PlimverClient } from 'plimverai';

class ChatApp {
  private client: PlimverClient;
  private sessionId: string;

  constructor(apiKey: string) {
    this.client = new PlimverClient({ apiKey });
    this.sessionId = `session-${Date.now()}`;
  }

  async sendMessage(message: string): Promise<string> {
    const response = await this.client.chatWithHistory(
      message,
      this.sessionId,
      { temperature: 0.8 }
    );
    
    return response.choices[0].message.content;
  }

  async sendWithStreaming(message: string, onUpdate: (text: string) => void) {
    let fullText = '';
    
    await this.client.chatStream(
      message,
      { temperature: 0.8 },
      (chunk) => {
        fullText += chunk;
        onUpdate(fullText);
      }
    );
    
    return fullText;
  }
}

// Usage
const app = new ChatApp('your-api-key');
const response = await app.sendMessage('Hello!');
console.log(response);

Document Q&A System

import { PlimverClient } from 'plimverai';
import * as fs from 'fs';

class DocumentQA {
  private client: PlimverClient;
  private sessionId: string;

  constructor(apiKey: string) {
    this.client = new PlimverClient({ apiKey });
    this.sessionId = `doc-${Date.now()}`;
  }

  async uploadDocument(filePath: string): Promise<void> {
    const file = fs.readFileSync(filePath);
    const filename = filePath.split('/').pop() || 'document.pdf';
    
    await this.client.uploadFile({
      file,
      filename,
      sessionId: this.sessionId
    });
    
    console.log(`Uploaded: ${filename}`);
  }

  async ask(question: string): Promise<{answer: string, citations: any[]}> {
    const response = await this.client.ragQuery(
      question,
      this.sessionId,
      { topK: 5 }
    );
    
    return {
      answer: response.choices[0].message.content,
      citations: response.citations
    };
  }
}

// Usage
const qa = new DocumentQA('your-api-key');
await qa.uploadDocument('./document.pdf');
const result = await qa.ask('What is the main topic?');
console.log('Answer:', result.answer);
console.log('Sources:', result.citations);

Requirements

• Node.js >= 16.0.0
• TypeScript >= 5.0 (for TypeScript projects)

Dependencies

• axios ^1.6.0

Development

Build from Source

git clone https://github.com/Elliot-Elikplim/Zenux-Api.git
cd Zenux-Api/sdk-js
npm install
npm run build

Run Tests

npm test

Lint Code

npm run lint

Format Code

npm run format

License

MIT License - see LICENSE file for details.

Support

• Documentation: GitHub Repository
• Issues: GitHub Issues
• Email: [email protected]

Links

• npm Package: https://www.npmjs.com/package/plimverai
• GitHub: https://github.com/Elliot-Elikplim/Zenux-Api
• API Base URL: https://api.zenuxai.tech
• Python SDK: https://pypi.org/project/plimverai-sdk/

Made with ❤️ by PlimverAI Team