Level 1: SVK Primitives

Mosaic Service

Mosaic is the structure-and-seeding service in the stack. Use it when you need to initialize taste from captures, derive clusters, or fetch domain-targeted product seeds that you will later hand off to Prism.

When to Use Mosaic

  • • Initialize a user taste profile from captures
  • • Generate cluster-driven seeds for downstream windows
  • • Fetch retailer-targeted product seeds for domain-specific flows
  • • Build onboarding and curation pipelines that feed Prism

Configuration

Base URL: https://api-mosaic.bestomer.io/

Authentication: HTTP Bearer token

Authorization: Bearer $MOSAIC_TOKEN

Core Pattern

Mosaic is usually upstream of Prism. A common sequence is: gather captures, ask Mosaic to initialize taste or produce targeted seeds, then use those outputs to drive personalized product retrieval in Prism.

  1. Collect captures or identify a target domain
  2. Call Mosaic to derive structure or targeted seeds
  3. Persist the resulting cluster or seed metadata in your app
  4. Use Prism to turn those seeds into products, windows, or feeds

TypeScript Example: Initialize Taste

For onboarding, the most common Mosaic call is taste initialization from a set of captures.

type InitializeTasteRequest = {
  user_id: string;
  capture_ids: string[];
  force_rebuild?: boolean;
  debug?: boolean;
};

async function initializeTaste(
  body: InitializeTasteRequest,
  mosaicToken: string
) {
  const response = await fetch("https://api-mosaic.bestomer.io/onboarding/initialize_taste", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${mosaicToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) {
    throw new Error(`Mosaic initialize_taste failed: ${response.status}`);
  }

  return response.json();
}

const result = await initializeTaste(
  {
    user_id: "user-123",
    capture_ids: ["capture-1", "capture-2", "capture-3"],
    force_rebuild: false
  },
  process.env.MOSAIC_TOKEN!
);

TypeScript Example: Domain-Targeted Seeds

For retailer-specific flows, use Mosaic to fetch targeted products and domain-level clustering metadata, then pass the selected handles to Prism or your own window layer.

async function getTargetedProducts(domain: string, mosaicToken: string) {
  const [productsResponse, clustersResponse] = await Promise.all([
    fetch(`https://api-mosaic.bestomer.io/domains/${domain}/targeted-products`, {
      headers: { Authorization: `Bearer ${mosaicToken}` }
    }),
    fetch(`https://api-mosaic.bestomer.io/domains/${domain}/clusters`, {
      headers: { Authorization: `Bearer ${mosaicToken}` }
    })
  ]);

  if (!productsResponse.ok) {
    throw new Error(`Mosaic targeted-products failed: ${productsResponse.status}`);
  }

  const products = await productsResponse.json();
  const clusters = clustersResponse.ok ? await clustersResponse.json() : null;

  return {
    products: products.products,
    cover_image_url: clusters?.cover_image_url ?? null
  };
}

Practical Notes

  • Mosaic structures taste; Prism turns that structure into personalized retrieval
  • Initialize once, refresh selectively when a user adds enough new capture signal to justify rebuilding
  • Persist Mosaic outputs in your own app layer so you can explain or replay downstream curation
  • Handle partial failures gracefully when optional metadata like domain clusters is unavailable

More Detail

For implementation help inside Claude Code, see the /calling-mosaic skill for more detailed usage patterns and prompts.

Related Resources