@happyvertical/smrt-images 0.30.0

package/dist/smrt-knowledge.json

@@ -0,0 +1,561 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-06-23T01:11:40.766Z",
+  "packageName": "@happyvertical/smrt-images",
+  "packageVersion": "0.30.0",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "71b096d51171295f4ef0a123bd4dd8f5c1758a9be84c9ccc9111d90ae1abaa87",
+    "packageJson": "0a220e4b64fd1e05dd36430b005c6bd8e09e854944bf35343ae4bedd57694a06",
+    "agents": "b0cf63bd78f00cc1729ea7f1425291f8e23ab5591161cbbf0d08f4b16ace07fd"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json",
+    "./playground",
+    "./svelte",
+    "./ui"
+  ],
+  "dependencies": {
+    "@happyvertical/ai": "catalog:",
+    "@happyvertical/images": "catalog:",
+    "@happyvertical/smrt-assets": "workspace:*",
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-prompts": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-types": "workspace:*",
+    "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/utils": "catalog:",
+    "jimp": "catalog:",
+    "sharp": "catalog:",
+    "@happyvertical/smrt-playground": "workspace:*",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@sveltejs/kit": "^2.5.7",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/node": "25.0.9",
+    "svelte": "^5.18.0",
+    "svelte-check": "^4.3.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-assets",
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-playground",
+    "@happyvertical/smrt-prompts",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-types",
+    "@happyvertical/smrt-ui",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/ai",
+    "@happyvertical/images",
+    "@happyvertical/sql",
+    "@happyvertical/utils"
+  ],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "Image",
+      "qualifiedName": "@happyvertical/smrt-images:Image",
+      "collection": "assets",
+      "tableName": "assets",
+      "packageName": "@happyvertical/smrt-images",
+      "extends": "Asset",
+      "fields": [
+        {
+          "name": "created_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "updated_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceUri",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "mimeType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "description",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "metadata",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "version",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "primaryVersionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "typeSlug",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "statusSlug",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "ownerProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceAssetId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "folderId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Folder",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "externalId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "externalRefs",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "createdAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "updatedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "width",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "height",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "alt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "primaryVersionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "ownerProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceAssetId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "folderId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Folder",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "associateWith",
+        "classifyConstraintError",
+        "clearEmbeddings",
+        "delete",
+        "describe",
+        "destroy",
+        "do",
+        "executeToolCall",
+        "forget",
+        "forgetScope",
+        "generateAltText",
+        "generateEmbeddings",
+        "getAiUsageSnapshot",
+        "getAssociations",
+        "getAvailableTools",
+        "getBySlug",
+        "getDerivatives",
+        "getEmbedding",
+        "getExternalRef",
+        "getExternalRefs",
+        "getFields",
+        "getId",
+        "getMetadata",
+        "getRelated",
+        "getSavedId",
+        "getSlug",
+        "getSource",
+        "getStatus",
+        "getTags",
+        "getType",
+        "hasStaleEmbeddings",
+        "hasTag",
+        "initialize",
+        "is",
+        "isHighResolution",
+        "isRelatedLoaded",
+        "isSaved",
+        "isValidImageFormat",
+        "listAiUsage",
+        "loadDataFromDb",
+        "loadFromId",
+        "loadFromSlug",
+        "loadRelated",
+        "loadRelatedMany",
+        "markAsPersisted",
+        "mergeMetadata",
+        "recall",
+        "recallAll",
+        "remember",
+        "resetAiUsage",
+        "save",
+        "setExternalRef",
+        "setMetadata",
+        "summarizeAiUsage",
+        "toJSON",
+        "toPlainObject",
+        "toPublicJSON"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "assets.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-images:Image",
+          "path": "/assets",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "assets.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-images:Image",
+          "path": "/assets/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "assets.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-images:Image",
+          "path": "/assets",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "assets.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-images:Image",
+          "path": "/assets/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "api",
+          "name": "assets.delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-images:Image",
+          "path": "/assets/[id]",
+          "method": "DELETE"
+        },
+        {
+          "kind": "cli",
+          "name": "image_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "cli",
+          "name": "image_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "cli",
+          "name": "image_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "cli",
+          "name": "image_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "cli",
+          "name": "image_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "mcp",
+          "name": "image_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "mcp",
+          "name": "image_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "mcp",
+          "name": "image_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "mcp",
+          "name": "image_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-images:Image"
+        },
+        {
+          "kind": "mcp",
+          "name": "image_generateAltText",
+          "operation": "generateAltText",
+          "objectName": "@happyvertical/smrt-images:Image"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ImageCollection",
+      "qualifiedName": "@happyvertical/smrt-images:ImageCollection",
+      "collection": "assets",
+      "tableName": "assets",
+      "packageName": "@happyvertical/smrt-images",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByTenant",
+        "findGlobal",
+        "findWithGlobals",
+        "getByAspectRatio",
+        "getByMaxDimensions",
+        "getByMinDimensions",
+        "getHighResolution",
+        "getLandscape",
+        "getMissingAltText",
+        "getPortrait",
+        "getSquare"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "assets.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-images:Image",
+      "path": "/assets",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "assets.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-images:Image",
+      "path": "/assets/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "assets.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-images:Image",
+      "path": "/assets",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "assets.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-images:Image",
+      "path": "/assets/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "api",
+      "name": "assets.delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-images:Image",
+      "path": "/assets/[id]",
+      "method": "DELETE"
+    },
+    {
+      "kind": "cli",
+      "name": "image_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "cli",
+      "name": "image_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "cli",
+      "name": "image_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "cli",
+      "name": "image_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "cli",
+      "name": "image_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "mcp",
+      "name": "image_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "mcp",
+      "name": "image_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "mcp",
+      "name": "image_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "mcp",
+      "name": "image_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-images:Image"
+    },
+    {
+      "kind": "mcp",
+      "name": "image_generateAltText",
+      "operation": "generateAltText",
+      "objectName": "@happyvertical/smrt-images:Image"
+    }
+  ],
+  "prompts": [
+    {
+      "filePath": "src/prompts.ts"
+    }
+  ],
+  "relationshipsV2": {
+    "foreignKeyFields": 3,
+    "crossPackageRefFields": 1,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 7
+  },
+  "agentDoc": "# @happyvertical/smrt-images\n\nImage management with AI categorization, editing, and metadata extraction. Extends Asset via cross-package STI.\n\n## Models\n\n- **Image**: STI subclass of Asset (from smrt-assets) — stored in same `assets` table with `_meta_type='Image'`. Adds `width`, `height`, `alt` text.\n\n## Key Services\n\n- **ImageCollection**: dimension/orientation filters — `getByMinDimensions()`, `getByAspectRatio()`, `getLandscape()`, `getPortrait()`, `getSquare()`, `getHighResolution()`, `getMissingAltText()`\n- **ImageMetadataExtractor**: dimensions, format, EXIF from buffers (via `@happyvertical/images`)\n- **ImageCategorizer**: AI vision analysis → tags, description, confidence, subjects (via `@happyvertical/ai`)\n- **ImageEditor**: resize/crop/convert/thumbnail + AI editing. Creates new Image records with `parentId` linking to source.\n- **ImageDeriver**: creates derived images and, when requested, records source provenance through generic `AssetAssociation` links\n- **ImageSearch**: text search across name/description/alt with orientation filters\n- **UpstreamManager**: import from external providers with provenance tracking\n\n## AI Operations\n\n`generateAltText()` uses the `smrtImages.image.generateAltText` prompt registered via `@happyvertical/smrt-prompts` (resolves tenant overrides via `resolvePrompt()` then dispatches through `getAiClient().message()`). Computed properties: `isLandscape`, `isPortrait`, `aspectRatio`.\n\n## Prompt Registry\n\n`Image.generateAltText()` is registered with `@happyvertical/smrt-prompts` so tenants can override template/model/params at runtime:\n\n```typescript\nimport { smrtImagesGenerateAltTextPrompt } from '@happyvertical/smrt-images';\n// key: 'smrtImages.image.generateAltText'\n```\n\nOnly non-PII metadata fields are passed to the AI provider: `name`, `description`. Source URIs, internal foreign-key fields (`parentId`, `tenantId`), and the extensible `metadata` blob are intentionally excluded — source URIs may embed signed/private bucket paths and `metadata` may contain EXIF GPS data or tenant-private configuration.\n\n## UI Registry\n\nSvelte components auto-register with `ModuleUIRegistry` on import of `@happyvertical/smrt-images/svelte`. UI slot declarations live in `src/ui.ts` and are exported via `@happyvertical/smrt-images/ui`:\n\n- `assets-gallery` — `AssetsGallery.svelte`\n- `image-editor` — `ImageEditor.svelte`\n- `image-uploader` — `ImageUploader.svelte`\n\n## Gotchas\n\n- **Cross-package STI**: Image extends Asset from different package — fragile if Asset schema changes\n- **AssetAssociation usage is intentional here**: image derivation uses it for provenance, not for base-model-owned asset storage\n- **Editor bypasses collection.create()**: creates Image instances directly (skips collection validation)\n- **Derivative creation**: 3 DB calls — `collection.create()` + `store.storeFile()` + `save()`\n- **Orientation filtering is in-memory**: queries all images, then filters by dimensions\n"
+}