@happyvertical/smrt-images

pnpm add @happyvertical/smrt-images

npm install @happyvertical/smrt-images

import {
  Image, ImageCollection,
  ImageCategorizer, ImageEditor, ImageDeriver,
  ImageMetadataExtractor, ImageSearch, UpstreamManager,
} from '@happyvertical/smrt-images';
import { createAssetRuntime, ASSET_ROLES } from '@happyvertical/smrt-assets';

// Recommended: share an AssetRuntime across image + content + agents
const runtime = await createAssetRuntime({ db, storage });

// Create and query images
const images = new ImageCollection(db);
const image = await images.create({
  name: 'hero.jpg',
  sourceUri: 'https://cdn.example.com/hero.jpg',
  mimeType: 'image/jpeg',
  width: 1920,
  height: 1080,
});
await image.save();

// Computed properties from dimensions
image.isLandscape;       // true
image.aspectRatio;       // 1.778
image.isHighResolution();// false (below 4K)

// AI categorization
const categorizer = new ImageCategorizer({ ai });
const result = await categorizer.categorize(image);
await categorizer.autoTag(image, assetCollection);

// AI alt-text (via smrt-prompts)
const altText = await image.generateAltText();

// Editing -- each call creates a derivative Image linked via parentId.
// ImageEditor takes (store, collection, { ai? }); use runtime.store.
const editor = new ImageEditor(runtime.store, images, { ai });
const thumb   = await editor.thumbnail(image, 256);
const resized = await editor.resize(image, 800, 600);
const webp    = await editor.convert(image, 'webp');
const edited  = await editor.edit(image, 'add warm sunset tones');
const variations = await editor.generateVariation(image, 'winter theme', { count: 3 });

class Image extends Asset {
  width: number
  height: number
  alt?: string

  // Computed properties
  get isLandscape(): boolean
  get isPortrait(): boolean
  get isSquare(): boolean
  get aspectRatio(): number
  isHighResolution(): boolean

  // AI via smrt-prompts (see Prompt Registry below)
  generateAltText(): Promise<string>
}

class ImageCollection extends SmrtCollection<Image> {
  getByMinDimensions(width: number, height: number): Promise<Image[]>
  getByMaxDimensions(width: number, height: number): Promise<Image[]>
  getByAspectRatio(minRatio: number, maxRatio: number): Promise<Image[]>
  getLandscape(): Promise<Image[]>
  getPortrait(): Promise<Image[]>
  getSquare(): Promise<Image[]>
  getHighResolution(): Promise<Image[]>
  getMissingAltText(): Promise<Image[]>
}

// ImageCategorizer: AI vision analysis (tags, description, confidence, subjects)
const categorizer = new ImageCategorizer({ ai });
const result = await categorizer.categorize(image);

// ImageEditor: resize/crop/convert/thumbnail + AI edits, all create new Image
// records linked via parentId. Constructor: (store, collection, { ai? })
const editor = new ImageEditor(runtime.store, images, { ai });

// ImageDeriver: AI-generated derivations -- records provenance via AssetAssociation.
// Constructor: (store, collection, { ai }); derive() takes source images + a prompt.
const deriver = new ImageDeriver(runtime.store, images, { ai });
const derived = await deriver.derive([image], 'storybook style', { count: 1 });
// To also link sources via AssetAssociation, use deriveWithAssociations():
// await deriver.deriveWithAssociations([image], 'storybook style', associations);

// ImageMetadataExtractor: dimensions, format, EXIF
const extractor = new ImageMetadataExtractor();
const meta = await extractor.extract(imageBuffer);

// ImageSearch: text search with orientation filters.
// Constructor: (collection); search(query, options) — also findSimilar() / findByPrompt()
const search = new ImageSearch(images);
const results = await search.search('sunset', { orientation: 'landscape' });

// UpstreamManager: import from external providers.
// Constructor: (sources[], store, collection)
const upstream = new UpstreamManager([sourceAdapter], runtime.store, images);
const found = await upstream.search('mountains', { limit: 20 });
const imported = await upstream.import(found[0]);

import { smrtImagesGenerateAltTextPrompt } from '@happyvertical/smrt-images';
// key: 'smrtImages.image.generateAltText'

import '@happyvertical/smrt-images/svelte'; // side-effect: ModuleUIRegistry.register(...)
import { ModuleUIRegistry } from '@happyvertical/smrt-svelte/registry';

const Gallery = ModuleUIRegistry.get('@happyvertical/smrt-images', 'assets-gallery');