levrops-contracts 1.3.1 → 1.3.2

package/creative/creative_signal_profile.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.levrops.com/creative/creative_signal_profile.schema.json",
+  "title": "CreativeSignalProfile",
+  "description": "Extracted creative signal profile from a single asset. Captures emotional, thematic, and narrative dimensions for Creative Whisperer synthesis.",
+  "type": "object",
+  "required": ["asset_id", "asset_type", "energy"],
+  "properties": {
+    "asset_id": {
+      "type": "string",
+      "description": "Unique identifier of the source asset",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "asset_type": {
+      "type": "string",
+      "description": "Type of creative asset",
+      "enum": ["note", "audio", "url", "lyric", "image", "other"]
+    },
+    "energy": {
+      "type": "string",
+      "description": "Perceived energy level of the creative content",
+      "enum": ["low", "mid", "high"]
+    },
+    "emotions": {
+      "type": "array",
+      "description": "Detected emotional tones",
+      "items": { "type": "string", "maxLength": 100 },
+      "maxItems": 20,
+      "default": []
+    },
+    "themes": {
+      "type": "array",
+      "description": "Recurring themes or topics",
+      "items": { "type": "string", "maxLength": 100 },
+      "maxItems": 20,
+      "default": []
+    },
+    "narrative_posture": {
+      "type": "string",
+      "description": "Stance or posture of the narrative voice",
+      "maxLength": 200
+    },
+    "intensity": {
+      "type": "number",
+      "description": "Intensity score (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "vulnerability": {
+      "type": "number",
+      "description": "Vulnerability/openness score (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "certainty": {
+      "type": "number",
+      "description": "Certainty/conviction score (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "imagery": {
+      "type": "array",
+      "description": "Evocative imagery or visual motifs",
+      "items": { "type": "string", "maxLength": 200 },
+      "maxItems": 30,
+      "default": []
+    }
+  },
+  "additionalProperties": false
+}

package/creative/creative_whisper.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.levrops.com/creative/creative_whisper.schema.json",
+  "title": "CreativeWhisper",
+  "description": "Synthesis output from Creative Whisperer. Summarizes clusters, patterns, tensions, and suggests follow-up exploration with citations.",
+  "type": "object",
+  "required": ["cluster_summary", "confidence"],
+  "properties": {
+    "cluster_summary": {
+      "type": "string",
+      "description": "Summary of the creative cluster(s) analyzed",
+      "minLength": 1,
+      "maxLength": 2000
+    },
+    "detected_pattern": {
+      "type": "string",
+      "description": "Detected creative pattern or recurring motif",
+      "maxLength": 500
+    },
+    "creative_tension": {
+      "type": "string",
+      "description": "Identified creative tension or dialectic",
+      "maxLength": 500
+    },
+    "suggested_exploration": {
+      "type": "string",
+      "description": "Suggested direction for further creative exploration",
+      "maxLength": 1000
+    },
+    "confidence": {
+      "type": "number",
+      "description": "Confidence in the synthesis (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "followup_questions": {
+      "type": "array",
+      "description": "Suggested follow-up questions to deepen exploration",
+      "items": { "type": "string", "maxLength": 300 },
+      "maxItems": 10,
+      "default": []
+    },
+    "citations": {
+      "type": "array",
+      "description": "Citations referencing asset IDs with short quotes",
+      "items": {
+        "type": "object",
+        "required": ["asset_id", "quote"],
+        "properties": {
+          "asset_id": {
+            "type": "string",
+            "description": "ID of the cited asset",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "quote": {
+            "type": "string",
+            "description": "Short excerpt (≤140 chars)",
+            "minLength": 1,
+            "maxLength": 140
+          }
+        },
+        "additionalProperties": false
+      },
+      "maxItems": 20,
+      "default": []
+    }
+  },
+  "additionalProperties": false
+}

package/creative/models.py

@@ -0,0 +1,86 @@
+"""
+Pydantic models for Creative Whisperer synthesis contracts.
+
+Mirrors the JSON schemas in creative/*.schema.json.
+Install: pip install pydantic
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from pydantic import BaseModel, Field
+
+
+class AssetType(str, Enum):
+    """Creative asset type."""
+
+    NOTE = "note"
+    AUDIO = "audio"
+    URL = "url"
+    LYRIC = "lyric"
+    IMAGE = "image"
+    OTHER = "other"
+
+
+class Energy(str, Enum):
+    """Perceived energy level."""
+
+    LOW = "low"
+    MID = "mid"
+    HIGH = "high"
+
+
+class CreativeSignalProfile(BaseModel):
+    """Extracted creative signal profile from a single asset."""
+
+    asset_id: str = Field(..., min_length=1, max_length=255)
+    asset_type: AssetType
+    energy: Energy
+    emotions: list[str] = Field(default_factory=list, max_length=20)
+    themes: list[str] = Field(default_factory=list, max_length=20)
+    narrative_posture: str | None = Field(None, max_length=200)
+    intensity: float | None = Field(None, ge=0.0, le=1.0)
+    vulnerability: float | None = Field(None, ge=0.0, le=1.0)
+    certainty: float | None = Field(None, ge=0.0, le=1.0)
+    imagery: list[str] = Field(default_factory=list, max_length=30)
+
+
+class CreativeEdgeAlignment(BaseModel):
+    """Alignment metrics between two creative signal profiles."""
+
+    source_asset_id: str = Field(..., min_length=1, max_length=255)
+    target_asset_id: str = Field(..., min_length=1, max_length=255)
+    semantic_score: float = Field(..., ge=0.0, le=1.0)
+    emotional_score: float = Field(..., ge=0.0, le=1.0)
+    theme_overlap_count: int = Field(..., ge=0)
+    motif_overlap_count: int = Field(..., ge=0)
+    resonance_score: float = Field(..., ge=0.0, le=1.0)
+
+
+class CreativeCluster(BaseModel):
+    """Cluster of related creative signal profiles."""
+
+    cluster_id: str = Field(..., min_length=1, max_length=255)
+    asset_ids: list[str] = Field(..., min_length=1, max_length=100)
+    dominant_emotions: list[str] = Field(default_factory=list, max_length=10)
+    dominant_themes: list[str] = Field(default_factory=list, max_length=10)
+    cohesion_score: float | None = Field(None, ge=0.0, le=1.0)
+
+
+class CreativeWhisperCitation(BaseModel):
+    """Citation referencing an asset with a short quote."""
+
+    asset_id: str = Field(..., min_length=1, max_length=255)
+    quote: str = Field(..., min_length=1, max_length=140)
+
+
+class CreativeWhisper(BaseModel):
+    """Synthesis output from Creative Whisperer."""
+
+    cluster_summary: str = Field(..., min_length=1, max_length=2000)
+    detected_pattern: str | None = Field(None, max_length=500)
+    creative_tension: str | None = Field(None, max_length=500)
+    suggested_exploration: str | None = Field(None, max_length=1000)
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    followup_questions: list[str] = Field(default_factory=list, max_length=10)
+    citations: list[CreativeWhisperCitation] = Field(default_factory=list, max_length=20)

package/creative/requirements.txt

@@ -0,0 +1,2 @@
+# Optional: for Pydantic models (creative/models.py)
+pydantic>=2.0.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "levrops-contracts",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "LevrOps API contracts, schemas, code generators, and Sanity content contracts",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jackmckracken/levrops-contracts.git"
+    "url": "git+https://github.com/jackmckracken/levrops-contracts.git"
   },
   "homepage": "https://github.com/jackmckracken/levrops-contracts#readme",
   "type": "module",
@@ -23,6 +23,7 @@
   },
   "files": [
     "contracts/",
+    "creative/",
     "sanity/",
     "index.ts",
     "README.md",
@@ -31,13 +32,15 @@
   ],
   "scripts": {
     "sanity:codegen": "tsx tools/levrops-sanity-codegen.ts",
-    "sanity:check": "tsx tools/sanity-check.ts"
+    "sanity:check": "tsx tools/sanity-check.ts",
+    "test:creative": "node --test tests/creative/validation.test.mjs"
   },
   "dependencies": {
     "sanity": "^3.56.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.24",
+    "ajv": "^8.12.0",
     "tsx": "^4.7.0",
     "typescript": "^5.4.0"
   },
@@ -48,4 +51,3 @@
     "access": "public"
   }
 }
-

package/sanity/schema/generated/blocks/cta.ts

@@ -0,0 +1,68 @@
+import { defineType, defineField, string, text, url, image, boolean, number, array, reference } from "sanity";
+
+/**
+ * CTA
+ * 
+ * Generated from Structure DSL block: "cta"
+ * Sanity type: "block.cta"
+ * Call to action block
+ */
+export const blockCTA = defineType({
+  name: "block.cta",
+  title: "CTA",
+  type: "object",
+  description: "Call to action block",
+  fields: [
+    defineField({
+      name: "_key",
+      type: "string",
+      title: "Key",
+      description: "Unique key for array item (auto-generated)",
+      readOnly: true,
+    }),
+    defineField({
+      name: "headline",
+      type: string(),
+      title: "Headline",
+      description: "Constraints: Max 100 characters",
+      validation: (Rule) => Rule.required().max(100),
+    }),
+    defineField({
+      name: "description",
+      type: string(),
+      title: "Description",
+      description: "Constraints: Max 300 characters",
+      validation: (Rule) => Rule.max(300),
+    }),
+    defineField({
+      name: "buttonText",
+      type: string(),
+      title: "Button Text",
+      description: "Constraints: Max 50 characters",
+      validation: (Rule) => Rule.required().max(50),
+    }),
+    defineField({
+      name: "buttonLink",
+      type: url(),
+      title: "Button Link",
+      validation: (Rule) => Rule.required(),
+    }),
+    defineField({
+      name: "variant",
+      type: string(),
+      title: "Variant",
+      initialValue: "primary",
+    }),
+  ],
+  preview: {
+    select: {
+      headline: "headline",
+    },
+    prepare({ headline }) {
+      return {
+        title: headline || "CTA",
+        subtitle: "Call to action block",
+      };
+    },
+  },
+});

package/sanity/schema/generated/blocks/editorial_grid.ts

@@ -0,0 +1,58 @@
+import { defineType, defineField, string, text, url, image, boolean, number, array, reference } from "sanity";
+
+/**
+ * Editorial Grid
+ * 
+ * Generated from Structure DSL block: "editorial_grid"
+ * Sanity type: "block.editorial_grid"
+ * Grid of editorial content
+ */
+export const blockEditorialGrid = defineType({
+  name: "block.editorial_grid",
+  title: "Editorial Grid",
+  type: "object",
+  description: "Grid of editorial content",
+  fields: [
+    defineField({
+      name: "_key",
+      type: "string",
+      title: "Key",
+      description: "Unique key for array item (auto-generated)",
+      readOnly: true,
+    }),
+    defineField({
+      name: "title",
+      type: string(),
+      title: "Title",
+      description: "Constraints: Max 200 characters",
+      validation: (Rule) => Rule.required().max(200),
+    }),
+    defineField({
+      name: "items",
+      type: array({
+    of: [{ type: "reference", to: [{ type: "blog-post" }] }],
+  }),
+      title: "Items",
+      validation: (Rule) => Rule.required().min(1),
+    }),
+    defineField({
+      name: "columns",
+      type: number(),
+      title: "Columns",
+      description: "Constraints: Min value: 1, Max value: 4",
+      validation: (Rule) => Rule.min(1).max(4),
+      initialValue: 3,
+    }),
+  ],
+  preview: {
+    select: {
+      title: "title",
+    },
+    prepare({ title }) {
+      return {
+        title: title || "Editorial Grid",
+        subtitle: "Grid of editorial content",
+      };
+    },
+  },
+});

package/sanity/schema/generated/blocks/hero.ts

@@ -0,0 +1,72 @@
+import { defineType, defineField, string, text, url, image, boolean, number, array, reference } from "sanity";
+
+/**
+ * Hero
+ * 
+ * Generated from Structure DSL block: "hero"
+ * Sanity type: "block.hero"
+ * Large headline with supporting text and CTA
+ */
+export const blockHero = defineType({
+  name: "block.hero",
+  title: "Hero",
+  type: "object",
+  description: "Large headline with supporting text and CTA",
+  fields: [
+    defineField({
+      name: "_key",
+      type: "string",
+      title: "Key",
+      description: "Unique key for array item (auto-generated)",
+      readOnly: true,
+    }),
+    defineField({
+      name: "headline",
+      type: string(),
+      title: "Headline",
+      description: "Constraints: Max 100 characters",
+      validation: (Rule) => Rule.required().max(100),
+    }),
+    defineField({
+      name: "subheadline",
+      type: string(),
+      title: "Subheadline",
+      description: "Constraints: Max 200 characters",
+      validation: (Rule) => Rule.max(200),
+    }),
+    defineField({
+      name: "backgroundImage",
+      type: image({
+    options: {
+      hotspot: true,
+    },
+  }),
+      title: "Background Image",
+      description: "Constraints: Allowed formats: jpg, png, webp, Max size: 5.0MB",
+      validation: (Rule) => Rule.required(),
+    }),
+    defineField({
+      name: "ctaText",
+      type: string(),
+      title: "CTA Button Text",
+      description: "Constraints: Max 50 characters",
+      validation: (Rule) => Rule.max(50),
+    }),
+    defineField({
+      name: "ctaLink",
+      type: url(),
+      title: "CTA Link",
+    }),
+  ],
+  preview: {
+    select: {
+      headline: "headline",
+    },
+    prepare({ headline }) {
+      return {
+        title: headline || "Hero",
+        subtitle: "Large headline with supporting text and CTA",
+      };
+    },
+  },
+});

package/sanity/schema/generated/blocks/product.ts

@@ -0,0 +1,66 @@
+import { defineType, defineField, string, text, url, image, boolean, number, array, reference } from "sanity";
+
+/**
+ * Product Block
+ * 
+ * Generated from Structure DSL block: "product"
+ * Sanity type: "block.product"
+ * Product showcase block
+ */
+export const blockProductBlock = defineType({
+  name: "block.product",
+  title: "Product Block",
+  type: "object",
+  description: "Product showcase block",
+  fields: [
+    defineField({
+      name: "_key",
+      type: "string",
+      title: "Key",
+      description: "Unique key for array item (auto-generated)",
+      readOnly: true,
+    }),
+    defineField({
+      name: "title",
+      type: string(),
+      title: "Title",
+      description: "Constraints: Max 200 characters",
+      validation: (Rule) => Rule.required().max(200),
+    }),
+    defineField({
+      name: "description",
+      type: string(),
+      title: "Description",
+      description: "Constraints: Max 500 characters",
+      validation: (Rule) => Rule.max(500),
+    }),
+    defineField({
+      name: "products",
+      type: array({
+    of: [{ type: "reference", to: [{ type: "product" }] }],
+  }),
+      title: "Products",
+      validation: (Rule) => Rule.required().min(1).max(10),
+    }),
+    defineField({
+      name: "image",
+      type: image({
+    options: {
+      hotspot: true,
+    },
+  }),
+      title: "Image",
+    }),
+  ],
+  preview: {
+    select: {
+      title: "title",
+    },
+    prepare({ title }) {
+      return {
+        title: title || "Product Block",
+        subtitle: "Product showcase block",
+      };
+    },
+  },
+});

package/sanity/schema/generated/blocks/story.ts

@@ -0,0 +1,59 @@
+import { defineType, defineField, string, text, url, image, boolean, number, array, reference } from "sanity";
+
+/**
+ * Story Section
+ * 
+ * Generated from Structure DSL block: "story"
+ * Sanity type: "block.story"
+ * Narrative content block
+ */
+export const blockStorySection = defineType({
+  name: "block.story",
+  title: "Story Section",
+  type: "object",
+  description: "Narrative content block",
+  fields: [
+    defineField({
+      name: "_key",
+      type: "string",
+      title: "Key",
+      description: "Unique key for array item (auto-generated)",
+      readOnly: true,
+    }),
+    defineField({
+      name: "title",
+      type: string(),
+      title: "Title",
+      description: "Constraints: Max 200 characters",
+      validation: (Rule) => Rule.required().max(200),
+    }),
+    defineField({
+      name: "content",
+      type: array({
+    of: [{ type: "block" }],
+  }),
+      title: "Content",
+      validation: (Rule) => Rule.required(),
+    }),
+    defineField({
+      name: "image",
+      type: image({
+    options: {
+      hotspot: true,
+    },
+  }),
+      title: "Image",
+    }),
+  ],
+  preview: {
+    select: {
+      title: "title",
+    },
+    prepare({ title }) {
+      return {
+        title: title || "Story Section",
+        subtitle: "Narrative content block",
+      };
+    },
+  },
+});

package/sanity/schema/generated/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Generated Sanity Schema Index
+ * 
+ * This file is auto-generated from Structure DSL.
+ * DO NOT EDIT THIS FILE DIRECTLY.
+ * 
+ * To regenerate:
+ *   node tools/codegen/structure-to-sanity/index.js --input <path> --out <dir>
+ */
+
+export { page } from './page';
+export { blockHero } from './blocks/hero';
+export { blockStorySection } from './blocks/story';
+export { blockProductBlock } from './blocks/product';
+export { blockEditorialGrid } from './blocks/editorial_grid';
+export { blockCTA } from './blocks/cta';

package/sanity/schema/generated/page.ts

@@ -0,0 +1,74 @@
+import { defineType, defineField, string, slug, array } from "sanity";
+
+/**
+ * Page Document
+ * 
+ * Generated from Structure DSL page templates.
+ * Single document type with pageType discriminant.
+ */
+export const page = defineType({
+  name: "page",
+  title: "Page",
+  type: "document",
+  description: "A page composed of ordered blocks, discriminated by pageType",
+  fields: [
+    defineField({
+      name: "title",
+      type: string(),
+      title: "Title",
+      validation: (Rule) => Rule.required().max(200),
+      description: "Page title",
+    }),
+    defineField({
+      name: "slug",
+      type: slug({
+        source: "title",
+      }),
+      title: "Slug",
+      validation: (Rule) => Rule.required(),
+      description: "URL-friendly identifier",
+    }),
+    defineField({
+      name: "pageType",
+      type: string(),
+      title: "Page Type",
+      validation: (Rule) => Rule.required(),
+      description: "Template type (maps to Structure DSL page template ID)",
+      options: {
+        list: [
+          { title: "Homepage", value: "homepage" },
+          { title: "Product Page", value: "product_page" },
+          { title: "Editorial Page", value: "editorial_page" },
+        ],
+      },
+    }),
+    defineField({
+      name: "content",
+      type: array({
+        of: [
+          { type: "block.hero" },
+          { type: "block.story" },
+          { type: "block.product" },
+          { type: "block.editorial_grid" },
+          { type: "block.cta" },
+        ],
+      }),
+      title: "Content Blocks",
+      description: "Ordered composition of content blocks",
+      validation: (Rule) => Rule.required().min(1),
+    }),
+  ],
+  preview: {
+    select: {
+      title: "title",
+      pageType: "pageType",
+      slug: "slug.current",
+    },
+    prepare({ title, pageType, slug }) {
+      return {
+        title: title || "Untitled Page",
+        subtitle: `${pageType || "unknown"} • /${slug || ""}`,
+      };
+    },
+  },
+});