Future Explorer Lib

Shared utilities and clients for Future Explorer projects.

Installation

npm install @future-explorer/lib

GrokAiClient

AI client for interacting with Grok (xAI) models with structured output support.

Basic Usage

import { GrokAiClient } from '@future-explorer/lib';

const client = new GrokAiClient({
  apiKey: 'your-api-key', // or set XAI_API_KEY env var
  temperature: 0.1,
  maxTokens: 4096,
  logger: console, // optional
});

interface PersonInfo {
  name: string;
  age: number;
}

const response = await client.getGenericStructuredResponse<PersonInfo>({
  model: 'grok-2-latest',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Extract data from this text...' },
  ],
  tools: [
    {
      type: 'function',
      name: 'extract_info',
      description: 'Extract structured information',
      parameters: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          age: { type: 'number' },
        },
        required: ['name', 'age'],
      },
    },
  ],
});

if (response) {
  console.log(response.args); // { name: '...', age: ... }
  console.log(response.functionName); // 'extract_info'
}

Constructor Options

• apiKey (optional): xAI API key. Falls back to XAI_API_KEY env var
• temperature (optional): Default temperature for requests (default: 0.1)
• maxTokens (optional): Default max tokens (default: 4096)
• logger (optional): Logger instance with warn and error methods

UnifiedAiClient

Multi-provider AI client supporting OpenAI, XAI (Grok), and Google Gemini with Zod schema-based structured outputs.

Basic Usage

import { UnifiedAiClient, Provider } from '@future-explorer/lib';
import { z } from 'zod';

// Create client with desired provider
const client = new UnifiedAiClient(Provider.OpenAI);
// or Provider.XAI, Provider.Gemini

// Define a Zod schema for the response
const SentimentSchema = z.object({
  sentiment: z.enum(['positive', 'negative', 'neutral']),
  confidence: z.number().min(0).max(1),
  summary: z.string(),
});

// Generate structured response
const result = await client.generateStructuredResponse(
  SentimentSchema,
  'I absolutely love this product!',
  'You are a sentiment analysis expert.'
);

console.log(result.sentiment); // 'positive'
console.log(result.confidence); // 0.95
console.log(result.summary); // '...'

Providers

| Provider | Enum Value | Required Environment Variables | | ------------- | ----------------- | ---------------------------------------------- | | OpenAI | Provider.OpenAI | OPENAI_API_KEY, MODEL_OPEN_AI | | XAI (Grok) | Provider.XAI | XAI_API_KEY, MODEL_XAI | | Google Gemini | Provider.Gemini | GOOGLE_GENERATIVE_AI_API_KEY, MODEL_GEMINI |

Methods

• generateStructuredResponse<T>(schema, userPrompt, systemMessage?): Generates a structured response matching the Zod schema
• getModel(): Returns the underlying LanguageModel instance

Development

Build

npm run build

Watch Mode

npm run watch

Lint

npm run lint
npm run lint:fix

Local Development

Link the package locally for testing in other projects:

./scripts/link-local.sh

Then in your project:

npm link @future-explorer/lib

Publishing

Manual Publish

npm run build
npm publish

Using Script

./scripts/publish.sh [patch|minor|major]

Changelog

1.0.7

• Updated peer dependency to zod 4.2.x

1.0.6

• Added UnifiedAiClient with multi-provider support (OpenAI, XAI, Gemini)

License

ISC