@lore-forge/ai-services

A centralized AI services library for the Lore Forge ecosystem, providing unified access to Google Cloud AI services including Vertex AI, Text-to-Speech, and Cloud Storage.

🎯 Purpose

This library consolidates all AI service interactions across the Lore Forge ecosystem (RPG, TCG, Map Editor, etc.) into a single, reusable NPM package. It eliminates code duplication, ensures consistency, and simplifies maintenance of AI-powered features.

🏗️ Architecture

The library is organized into focused service categories:

• Text Services: Character creation, scene generation, game master assistance
• Image Services: AI-powered image generation and enhancement
• Audio Services: Text-to-speech and voice character synthesis
• Core Services: Authentication, configuration, and shared utilities
• Prompt Templates: Reusable, optimized prompts for various AI tasks
• Types: Comprehensive TypeScript definitions

🚀 Quick Start

Installation

npm install @lore-forge/ai-services

Basic Setup

import { initializeAIServices, VertexAICharacterService } from '@lore-forge/ai-services';

// Initialize the library (validates environment variables)
await initializeAIServices();

// Use a service
const characterService = new VertexAICharacterService();
const character = await characterService.createCharacter({
  name: "Aragorn",
  race: "Human",
  class: "Ranger",
  background: "A skilled tracker and warrior from the North"
});

📚 Services Documentation

Text Services

VertexAICharacterService

Generate detailed RPG characters with personalities, backgrounds, and stats.

import { VertexAICharacterService } from '@lore-forge/ai-services';

const service = new VertexAICharacterService();

// Create a new character
const character = await service.createCharacter({
  name: "Gandalf",
  race: "Maia",
  class: "Wizard",
  background: "A wise wizard from the Undying Lands"
});

// Expand character personality
const personality = await service.expandPersonality(character);

VertexAIGamemasterService

AI-powered game master assistance for dynamic storytelling.

import { VertexAIGamemasterService } from '@lore-forge/ai-services';

const gmService = new VertexAIGamemasterService();

// Generate adventure hooks
const adventure = await gmService.generateAdventure({
  theme: "mystery",
  setting: "medieval fantasy",
  partyLevel: 5
});

VertexAISceneService

Create immersive scenes and locations.

import { VertexAISceneService } from '@lore-forge/ai-services';

const sceneService = new VertexAISceneService();

// Generate a scene description
const scene = await sceneService.generateScene({
  location: "ancient forest",
  mood: "mysterious",
  timeOfDay: "twilight"
});

Audio Services

VoiceCharactersService

Generate character voices with personality-matched audio profiles.

import { VoiceCharactersService } from '@lore-forge/ai-services';

const voiceService = new VoiceCharactersService();

// Create a voice profile for a character
const voiceProfile = await voiceService.createVoiceProfile({
  characterId: "char_123",
  personality: "wise and authoritative",
  age: "elderly",
  gender: "male"
});

// Generate speech
const audio = await voiceService.generateSpeech({
  text: "Welcome, adventurers, to my humble abode.",
  voiceProfile: voiceProfile
});

Image Services

Image Enhancement

Enhance and optimize image generation prompts.

import { enhanceCharacterImagePrompt } from '@lore-forge/ai-services';

const enhancedPrompt = await enhanceCharacterImagePrompt({
  character: character,
  style: "fantasy art",
  quality: "high"
});

🔧 Configuration

Environment Variables

Create a .env file with the required Google Cloud credentials:

# Google Cloud Configuration
GOOGLE_CLOUD_PROJECT_ID=your-project-id
GOOGLE_CLOUD_PRIVATE_KEY=your-private-key
GOOGLE_CLOUD_CLIENT_EMAIL=your-client-email

# Vertex AI Configuration
VERTEX_AI_LOCATION=us-central1
VERTEX_AI_MODEL=gemini-1.5-pro

# Text-to-Speech Configuration
TTS_LANGUAGE_CODE=en-US
TTS_SSML_GENDER=NEUTRAL

# Cloud Storage Configuration
CLOUD_STORAGE_BUCKET=your-bucket-name

Validation

The library automatically validates your configuration:

import { validateEnvironment } from '@lore-forge/ai-services';

try {
  await validateEnvironment();
  console.log("✅ Environment configuration is valid");
} catch (error) {
  console.error("❌ Configuration error:", error.message);
}

🎨 Prompt Templates

The library includes optimized prompt templates for various AI tasks:

import { 
  CHARACTER_PROMPTS, 
  SCENE_PROMPTS, 
  IMAGE_PROMPTS 
} from '@lore-forge/ai-services';

// Use character creation prompt
const prompt = CHARACTER_PROMPTS.CREATE_CHARACTER;

// Use scene description prompt
const scenePrompt = SCENE_PROMPTS.DESCRIBE_LOCATION;

// Use image generation prompt
const imagePrompt = IMAGE_PROMPTS.CHARACTER_IMAGE;

🔍 Type Definitions

The library provides comprehensive TypeScript support:

import type { 
  Character, 
  Adventure, 
  Scene, 
  VoiceProfile,
  AudioGenerationRequest,
  ImageGenerationRequest 
} from '@lore-forge/ai-services';

// All types are fully typed for better development experience
const character: Character = {
  id: "char_123",
  name: "Aragorn",
  race: "Human",
  class: "Ranger",
  // ... fully typed properties
};

🛠️ Core Utilities

Authentication

import { GoogleCloudAuthenticator } from '@lore-forge/ai-services';

const auth = GoogleCloudAuthenticator.getInstance();
const vertexClient = await auth.getVertexAIClient();
const ttsClient = await auth.getTTSClient();
const storageClient = await auth.getStorageClient();

Configuration Management

import { ConfigLoader } from '@lore-forge/ai-services';

const config = ConfigLoader.getInstance();
const projectId = config.getGoogleCloudProjectId();
const vertexLocation = config.getVertexAILocation();

Library Information

import { getLibraryInfo } from '@lore-forge/ai-services';

const info = getLibraryInfo();
console.log(`Library version: ${info.version}`);
console.log(`Services available: ${info.services.length}`);

🏗️ Development

Project Structure

src/
├── core/                    # Core services (auth, config)
├── services/
│   ├── text/               # Text generation services
│   ├── images/             # Image generation services
│   └── audio/              # Audio generation services
├── prompts/                # Reusable prompt templates
├── types/                  # TypeScript definitions
└── index.ts               # Main entry point

Adding New Services

1. Create your service class in the appropriate category folder
2. Add proper TypeScript types to src/types/index.ts
3. Export your service in src/index.ts
4. Add relevant prompt templates to src/prompts/
5. Update this README with usage examples

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

📦 Publishing

This library uses semantic versioning:

• MAJOR (e.g., 2.0.0): Breaking changes
• MINOR (e.g., 1.1.0): New features (backward compatible)
• PATCH (e.g., 1.0.1): Bug fixes (backward compatible)

# Publish new version
npm version patch  # or minor/major
npm publish

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-service
3. Make your changes and add tests
4. Ensure all tests pass: npm test
5. Submit a pull request

📋 Error Handling

The library provides consistent error handling:

import { AIServiceError, ErrorCodes } from '@lore-forge/ai-services';

try {
  const result = await service.someMethod();
} catch (error) {
  if (error instanceof AIServiceError) {
    switch (error.code) {
      case ErrorCodes.AUTHENTICATION_ERROR:
        // Handle auth errors
        break;
      case ErrorCodes.QUOTA_EXCEEDED:
        // Handle quota errors
        break;
      case ErrorCodes.INVALID_INPUT:
        // Handle validation errors
        break;
      default:
        // Handle other errors
        break;
    }
  }
}

🔐 Security

• All Google Cloud credentials are handled securely through environment variables
• The library never exposes API keys to client-side code
• Authentication tokens are managed automatically and refreshed as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔄 Changelog

v1.0.0 (Initial Release)

• Core authentication and configuration services
• Text generation services (Character, Scene, GameMaster)
• Audio services (TTS, Voice Characters)
• Image enhancement utilities
• Comprehensive TypeScript support
• Reusable prompt templates
• Complete documentation

Made with ❤️ for the Lore Forge ecosystem