Getting Started

Learn how to install and use @rankfor/dice-roller to analyze AI response stability for your brand.

Prerequisites

Node.js 18.0.0 or higher
API key for at least one LLM provider (Gemini, OpenAI, or Grok)
TypeScript 5.0+ (recommended, but not required)

Installation

Install the core package from npm:

npm install @rankfor/dice-roller

Then install the LLM SDK(s) you plan to use as peer dependencies:

# For Google Gemini
npm install @google/generative-ai

# For OpenAI or Grok/xAI (both use OpenAI SDK)
npm install openai

Note: Peer dependencies are optional. Only install the SDK for the provider(s) you plan to use.

Quick Start

Single Model Analysis

Analyze how consistently a single AI model responds to your prompt:

import { analyzeStability } from '@rankfor/dice-roller';

const result = await analyzeStability({
  prompt: 'What are the best CRM tools for small businesses?',
  iterations: 5,
  model: 'gemini',
  apiKey: process.env.GEMINI_API_KEY,
  brandName: 'Salesforce', // Optional: track your brand
});

console.log(`Consistency Score: ${result.consistencyScore}%`);
console.log('Core Messages:', result.analysis.coreStableMessages);
console.log('Brand Mentions:', result.brandMentions.average);

Cross-Model Experiment

Compare responses across multiple AI providers:

import { runExperiment } from '@rankfor/dice-roller';

const result = await runExperiment({
  prompt: 'What project management tools do you recommend?',
  apiKeys: {
    geminiApiKey: process.env.GEMINI_API_KEY,
    openaiApiKey: process.env.OPENAI_API_KEY,
    grokApiKey: process.env.GROK_API_KEY,
  },
  iterations: 5,
  brandName: 'Asana',
});

// Messages ALL models agree on
console.log('Universal Messages:', result.universalCoreMessages);

// Brands mentioned by ALL models
console.log('Universal Brands:', result.universalBrands);

// Statistical analysis
console.log('Shannon Entropy:', result.statistics.shannonEntropy);
console.log('Gini Coefficients:', result.statistics.giniCoefficients);

Getting API Keys

Google Gemini

Go to Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy the key and store it securely

OpenAI

Go to OpenAI Platform
Sign in or create an account
Navigate to API Keys in settings
Click "Create new secret key"

xAI Grok

Go to xAI Console
Sign in with your X account
Navigate to API section
Generate a new API key

Environment Setup

We recommend storing API keys in environment variables:

# .env file
GEMINI_API_KEY=your_gemini_key_here
OPENAI_API_KEY=your_openai_key_here
GROK_API_KEY=your_grok_key_here

Security: Never commit API keys to version control. Add .env to your .gitignore file.

Next Steps

Customisation Examples

Learn to configure stop words, synonyms, and sentiment indicators for your industry.

User Guide

Comprehensive guide to understanding results and best practices.