@torqlab/get-activity-image-generation-prompt

Generate image generation prompts from activity signals for AI-powered fitness visualization.

This package takes activity signals (semantic labels about intensity, mood, terrain, etc.) and produces optimized prompts suitable for AI image generation models like DALL·E, Midjourney, or Stable Diffusion. The prompts are crafted to create compelling fitness-themed artwork that reflects the activity's characteristics.

Install

Published to NPM.

npm i @torqlab/get-activity-image-generation-prompt

Or with Bun:

bun add @torqlab/get-activity-image-generation-prompt

Quick start

import getActivityImageGenerationPrompt from '@torqlab/get-activity-image-generation-prompt';
import type { ActivitySignals } from '@torqlab/get-activity-image-generation-prompt';

const signals: ActivitySignals = {
  core: {
    activityType: 'Run',
    intensity: 'medium',
    elevation: 'rolling',
    timeOfDay: 'morning',
    tags: ['recovery'],
    semanticContext: ['park', 'peaceful'],
  },
  derived: {
    mood: 'calm',
    style: 'minimal',
    subject: 'runner',
    terrain: 'rolling hills',
    environment: 'outdoor training space',
    atmosphere: 'soft morning light',
  },
};

const prompt: string = getActivityImageGenerationPrompt(
  signals,
  // Your moderation/guardrails callback for prompt content.
  // Return true if content should be rejected.
  (input) => input.toLowerCase().includes('forbidden'),
);

console.log(prompt);
// Output: "minimal style, runner in rolling hills, calm mood, soft morning light, outdoor training space"

API

getActivityImageGenerationPrompt(signals, checkForbiddenContent)

Parameters

• signals: ActivitySignals - Activity signals object containing core and derived properties
• checkForbiddenContent: (input: string) => boolean - Function to detect forbidden/unsafe content in the generated prompt

Returns

• string - Generated and validated image generation prompt

Behavior

• Assembles a structured prompt from activity signals
• Validates prompt length and content safety
• Falls back to safe default prompt if validation fails
• Truncates intelligently while preserving key components

Types

ActivitySignals

export interface ActivitySignals {
  core: {
    activityType: string;
    intensity: string;
    elevation: string;
    timeOfDay: string;
    tags?: string[];
    brands?: string[];
    semanticContext?: string[];
  };
  derived: {
    mood: string;
    style: string;
    subject: string;
    terrain: string;
    environment: string;
    atmosphere: string;
  };
}

PromptValidationResult

export interface PromptValidationResult {
  valid: boolean;
  errors: string[];
}

Exports

• getActivityImageGenerationPrompt (default) - Main prompt generation function
• ACTIVITY_IMAGE_GENERATION_PROMPT_DEFAULT - Safe fallback prompt: "minimal style, athlete, neutral mood, simple outdoor setting"
• ActivitySignals - TypeScript interface for input signals
• PromptValidationResult - TypeScript interface for validation results

How it works

1. Assemble prompt from activity signals using priority-based component selection
2. Apply quality keywords and style-specific enhancements based on derived signals
3. Truncate intelligently if needed, preserving high-priority components (style, subject, mood)
4. Validate prompt length (≤1000 chars) and content safety
5. Fallback to safe default if validation fails

Modules

The package is organized into focused modules:

• assemble-prompt/ - Core prompt assembly and truncation logic
• validate-prompt/ - Prompt validation and content safety checks
• truncate-prompt/ - Intelligent truncation preserving priority components

Priority System

Components are prioritized during truncation:

1. High priority: style, subject, mood (always preserved)
2. Medium priority: terrain, atmosphere, environment
3. Low priority: semantic context, tags, brands

Configuration

Max Prompt Length

Prompts are limited to 1000 characters by default:

import { MAX_PROMPT_LENGTH } from '@torqlab/get-activity-image-generation-prompt/constants';
console.log(MAX_PROMPT_LENGTH); // 1000

Default Fallback

If validation fails, the system falls back to a safe default:

import { ACTIVITY_IMAGE_GENERATION_PROMPT_DEFAULT } from '@torqlab/get-activity-image-generation-prompt';
console.log(ACTIVITY_IMAGE_GENERATION_PROMPT_DEFAULT);
// "minimal style, athlete, neutral mood, simple outdoor setting"

Development

This package has no runtime dependencies. Tooling uses Bun + TypeScript.

# Install dependencies
bun install

# Run tests
bun test

# Lint code
bun run lint

# Format code
bun run format

# Build for publishing
bun run build

License

MIT