@plasius/ai-speech 0.1.1 → 0.1.3

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n  readonly packageName: string;\n  readonly featureFlagId: string;\n  readonly envPrefix: string;\n  readonly summary: string;\n}\n\nexport const AI_SPEECH_PACKAGE = \"@plasius/ai-speech\";\nexport const AI_SPEECH_FEATURE_FLAG_ID = \"ai.speech.enabled\";\nexport const AI_SPEECH_ENV_PREFIX = \"AI_SPEECH\";\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n  packageName: AI_SPEECH_PACKAGE,\n  featureFlagId: AI_SPEECH_FEATURE_FLAG_ID,\n  envPrefix: AI_SPEECH_ENV_PREFIX,\n  summary: \"Speech orchestration, TTS cache contracts, STT/TTS routing, and voice tier policy for Plasius AI.\",\n});\n"],"mappings":";AAOO,IAAM,oBAAoB;AAC1B,IAAM,4BAA4B;AAClC,IAAM,uBAAuB;AAE7B,IAAM,oBAAyC,OAAO,OAAO;AAAA,EAClE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SAAS;AACX,CAAC;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n  readonly packageName: string;\n  readonly featureFlagId: string;\n  readonly envPrefix: string;\n  readonly summary: string;\n}\n\nfunction requireNonEmptyString(value: string, label: string): string {\n  const trimmed = value.trim();\n  if (trimmed.length === 0) {\n    throw new Error(`${label} must be a non-empty string.`);\n  }\n\n  return trimmed;\n}\n\nfunction normalizeWhitespace(value: string): string {\n  return value.replace(/\\s+/gu, \" \").trim();\n}\n\nexport const AI_SPEECH_PACKAGE = \"@plasius/ai-speech\";\nexport const AI_SPEECH_ENV_PREFIX = \"AI_SPEECH\";\n\nexport const AI_SPEECH_FEATURE_FLAGS = {\n  ttsCache: \"ai.tts.cache.enabled\",\n  ttsNearReuse: \"ai.tts.near-reuse.enabled\",\n  premiumCharacters: \"ai.tts.premium-characters.enabled\",\n} as const;\n\nexport type AiSpeechFeatureFlagKey =\n  (typeof AI_SPEECH_FEATURE_FLAGS)[keyof typeof AI_SPEECH_FEATURE_FLAGS];\n\nexport type AiSpeechFeatureFlagSnapshot = Readonly<\n  Record<string, boolean | undefined>\n>;\n\nexport const AI_SPEECH_FEATURE_FLAG_ID = AI_SPEECH_FEATURE_FLAGS.ttsCache;\n\nexport const AI_SPEECH_ROLLOUT_EVALUATORS = [\n  \"remote-flag-service\",\n  \"host-application\",\n  \"break-glass-env\",\n] as const;\n\nexport type AiSpeechRolloutEvaluator =\n  (typeof AI_SPEECH_ROLLOUT_EVALUATORS)[number];\n\nexport const AI_SPEECH_ROLLOUT_FALLBACK_MODES = [\n  \"fail-closed\",\n  \"fail-open\",\n] as const;\n\nexport type AiSpeechRolloutFallbackMode =\n  (typeof AI_SPEECH_ROLLOUT_FALLBACK_MODES)[number];\n\nexport interface AiSpeechRolloutControl {\n  readonly featureFlag: AiSpeechFeatureFlagKey;\n  readonly evaluator: AiSpeechRolloutEvaluator;\n  readonly defaultEnabled: boolean;\n  readonly fallbackMode: AiSpeechRolloutFallbackMode;\n}\n\nexport interface AiSpeechRolloutDecision extends AiSpeechRolloutControl {\n  readonly enabled: boolean;\n  readonly source: \"snapshot\" | \"default\";\n}\n\nexport const AI_SPEECH_ROLLOUTS = Object.freeze({\n  ttsCache: Object.freeze<AiSpeechRolloutControl>({\n    featureFlag: AI_SPEECH_FEATURE_FLAGS.ttsCache,\n    evaluator: \"remote-flag-service\",\n    defaultEnabled: false,\n    fallbackMode: \"fail-closed\",\n  }),\n  ttsNearReuse: Object.freeze<AiSpeechRolloutControl>({\n    featureFlag: AI_SPEECH_FEATURE_FLAGS.ttsNearReuse,\n    evaluator: \"remote-flag-service\",\n    defaultEnabled: false,\n    fallbackMode: \"fail-closed\",\n  }),\n  premiumCharacters: Object.freeze<AiSpeechRolloutControl>({\n    featureFlag: AI_SPEECH_FEATURE_FLAGS.premiumCharacters,\n    evaluator: \"remote-flag-service\",\n    defaultEnabled: false,\n    fallbackMode: \"fail-closed\",\n  }),\n});\n\nexport function resolveAiSpeechRolloutDecision(\n  control: AiSpeechRolloutControl,\n  snapshot: AiSpeechFeatureFlagSnapshot = {}\n): AiSpeechRolloutDecision {\n  const resolved = snapshot[control.featureFlag];\n  if (typeof resolved === \"boolean\") {\n    return {\n      ...control,\n      enabled: resolved,\n      source: \"snapshot\",\n    };\n  }\n\n  return {\n    ...control,\n    enabled: control.defaultEnabled,\n    source: \"default\",\n  };\n}\n\nexport function isAiSpeechFeatureEnabled(\n  featureFlag: AiSpeechFeatureFlagKey,\n  snapshot: AiSpeechFeatureFlagSnapshot = {}\n): boolean {\n  const control = Object.values(AI_SPEECH_ROLLOUTS).find(\n    (candidate) => candidate.featureFlag === featureFlag\n  );\n\n  if (!control) {\n    return false;\n  }\n\n  return resolveAiSpeechRolloutDecision(control, snapshot).enabled;\n}\n\nexport const AI_SPEECH_VOICE_TIERS = [\n  \"development\",\n  \"standard\",\n  \"premium-character\",\n] as const;\n\nexport type AiSpeechVoiceTier = (typeof AI_SPEECH_VOICE_TIERS)[number];\n\nexport const AI_SPEECH_ENVIRONMENTS = [\n  \"development\",\n  \"preview\",\n  \"production\",\n] as const;\n\nexport type AiSpeechEnvironment = (typeof AI_SPEECH_ENVIRONMENTS)[number];\n\nexport interface AiSpeechVoiceTierDecision {\n  readonly requestedTier: AiSpeechVoiceTier;\n  readonly resolvedTier: AiSpeechVoiceTier;\n  readonly fallbackTier?: AiSpeechVoiceTier;\n  readonly reasonCodes: readonly string[];\n}\n\nexport interface ResolveAiSpeechVoiceTierInput {\n  readonly environment: AiSpeechEnvironment;\n  readonly requestedTier?: AiSpeechVoiceTier;\n  readonly featureFlags?: AiSpeechFeatureFlagSnapshot;\n}\n\nexport function resolveAiSpeechVoiceTier(\n  input: ResolveAiSpeechVoiceTierInput\n): AiSpeechVoiceTierDecision {\n  const requestedTier =\n    input.requestedTier ??\n    (input.environment === \"development\" ? \"development\" : \"standard\");\n\n  if (\n    requestedTier === \"premium-character\" &&\n    !isAiSpeechFeatureEnabled(\n      AI_SPEECH_FEATURE_FLAGS.premiumCharacters,\n      input.featureFlags\n    )\n  ) {\n    return {\n      requestedTier,\n      resolvedTier: \"standard\",\n      fallbackTier: \"standard\",\n      reasonCodes: [\"premium-character-rollout-disabled\"],\n    };\n  }\n\n  if (\n    requestedTier === \"development\" &&\n    input.environment !== \"development\"\n  ) {\n    return {\n      requestedTier,\n      resolvedTier: \"standard\",\n      fallbackTier: \"standard\",\n      reasonCodes: [\"development-voices-limited-to-development-environments\"],\n    };\n  }\n\n  return {\n    requestedTier,\n    resolvedTier: requestedTier,\n    reasonCodes: [],\n  };\n}\n\nexport const AI_SPEECH_PLAYER_ADDRESS_SOURCES = [\n  \"generic-player\",\n  \"class-title\",\n  \"faction-title\",\n  \"authored-character\",\n  \"user-name\",\n  \"account-handle\",\n  \"user-renamed-character\",\n] as const;\n\nexport type AiSpeechPlayerAddressSource =\n  (typeof AI_SPEECH_PLAYER_ADDRESS_SOURCES)[number];\n\nexport const AI_SPEECH_DEFAULT_PLAYER_LABEL = \"Player\";\n\nexport interface AiSpeechPlayerAddressInput {\n  readonly source: AiSpeechPlayerAddressSource;\n  readonly rawValue?: string;\n  readonly fallbackLabel?: string;\n}\n\nexport interface AiSpeechPlayerAddressDecision {\n  readonly source: AiSpeechPlayerAddressSource;\n  readonly renderText: string;\n  readonly exactReuseAllowed: boolean;\n  readonly nearReuseAllowed: boolean;\n  readonly redacted: boolean;\n  readonly reasonCodes: readonly string[];\n}\n\nexport function resolveAiSpeechPlayerAddress(\n  input: AiSpeechPlayerAddressInput\n): AiSpeechPlayerAddressDecision {\n  const fallbackLabel =\n    normalizeWhitespace(input.fallbackLabel ?? \"\") ||\n    AI_SPEECH_DEFAULT_PLAYER_LABEL;\n  const rawValue = normalizeWhitespace(input.rawValue ?? \"\");\n\n  switch (input.source) {\n    case \"generic-player\":\n      return {\n        source: input.source,\n        renderText: fallbackLabel,\n        exactReuseAllowed: true,\n        nearReuseAllowed: true,\n        redacted: false,\n        reasonCodes: [\"generic-player-address\"],\n      };\n    case \"class-title\":\n    case \"faction-title\":\n      return {\n        source: input.source,\n        renderText: rawValue || fallbackLabel,\n        exactReuseAllowed: true,\n        nearReuseAllowed: true,\n        redacted: false,\n        reasonCodes: rawValue ? [] : [\"player-address-fell-back-to-generic-label\"],\n      };\n    case \"authored-character\":\n      return {\n        source: input.source,\n        renderText: rawValue || fallbackLabel,\n        exactReuseAllowed: true,\n        nearReuseAllowed: true,\n        redacted: false,\n        reasonCodes: rawValue ? [] : [\"player-address-fell-back-to-generic-label\"],\n      };\n    case \"user-name\":\n    case \"account-handle\":\n    case \"user-renamed-character\":\n      return {\n        source: input.source,\n        renderText: fallbackLabel,\n        exactReuseAllowed: true,\n        nearReuseAllowed: false,\n        redacted: true,\n        reasonCodes: [\"player-identifier-redacted-from-render-text\"],\n      };\n  }\n}\n\nexport interface AiSpeechRenderTextInput {\n  readonly textTemplate: string;\n  readonly playerAddress?: AiSpeechPlayerAddressInput;\n}\n\nexport interface AiSpeechRenderTextResult {\n  readonly renderText: string;\n  readonly normalizedRenderText: string;\n  readonly playerAddress?: AiSpeechPlayerAddressDecision;\n}\n\nexport function renderAiSpeechText(\n  input: AiSpeechRenderTextInput\n): AiSpeechRenderTextResult {\n  const textTemplate = requireNonEmptyString(\n    input.textTemplate,\n    \"Speech text template\"\n  );\n  const hasPlayerPlaceholder = textTemplate.includes(\"{playerAddress}\");\n\n  if (hasPlayerPlaceholder && !input.playerAddress) {\n    throw new Error(\n      \"Speech text template requires playerAddress when using the {playerAddress} placeholder.\"\n    );\n  }\n\n  const playerAddress = input.playerAddress\n    ? resolveAiSpeechPlayerAddress(input.playerAddress)\n    : undefined;\n  const renderText = normalizeWhitespace(\n    hasPlayerPlaceholder && playerAddress\n      ? textTemplate.replace(/\\{playerAddress\\}/gu, playerAddress.renderText)\n      : textTemplate\n  );\n\n  return {\n    renderText,\n    normalizedRenderText: normalizeAiSpeechText(renderText),\n    playerAddress,\n  };\n}\n\nexport function normalizeAiSpeechText(value: string): string {\n  return requireNonEmptyString(\n    normalizeWhitespace(value).toLocaleLowerCase(\"en-GB\"),\n    \"Speech text\"\n  );\n}\n\nexport const AI_SPEECH_PROVIDER_CACHE_PERMISSIONS = [\n  \"forbidden\",\n  \"exact-only\",\n  \"exact-and-near\",\n] as const;\n\nexport type AiSpeechProviderCachePermission =\n  (typeof AI_SPEECH_PROVIDER_CACHE_PERMISSIONS)[number];\n\nexport const AI_SPEECH_CACHE_MODES = [\n  \"disabled\",\n  \"no-cache\",\n  \"exact\",\n  \"near\",\n] as const;\n\nexport type AiSpeechCacheMode = (typeof AI_SPEECH_CACHE_MODES)[number];\n\nexport const AI_SPEECH_CACHE_SCOPES = [\"none\", \"actor\", \"global\"] as const;\n\nexport type AiSpeechCacheScope = (typeof AI_SPEECH_CACHE_SCOPES)[number];\n\nexport const AI_SPEECH_UTTERANCE_CLASSES = [\n  \"system-generic\",\n  \"game-npc-dialogue\",\n  \"game-bark\",\n  \"player-address\",\n  \"moderation-notice\",\n  \"private-response\",\n] as const;\n\nexport type AiSpeechUtteranceClass =\n  (typeof AI_SPEECH_UTTERANCE_CLASSES)[number];\n\nexport const AI_SPEECH_NEAR_REUSE_SAFE_CLASSES = [\n  \"system-generic\",\n  \"game-npc-dialogue\",\n  \"game-bark\",\n  \"player-address\",\n] as const satisfies readonly AiSpeechUtteranceClass[];\n\nconst AI_SPEECH_NEAR_REUSE_SAFE_CLASS_SET: ReadonlySet<AiSpeechUtteranceClass> =\n  new Set(AI_SPEECH_NEAR_REUSE_SAFE_CLASSES);\n\nexport interface AiSpeechCacheKeyInput {\n  readonly providerId: string;\n  readonly modelId: string;\n  readonly voiceId: string;\n  readonly locale: string;\n  readonly format: string;\n  readonly pronunciationVersion: string;\n  readonly normalizedRenderText: string;\n  readonly styleId?: string;\n  readonly scopeDiscriminator?: string;\n}\n\nexport interface AiSpeechVoiceProfileRef {\n  readonly providerId: string;\n  readonly modelId: string;\n  readonly voiceId: string;\n  readonly locale: string;\n  readonly format: string;\n  readonly pronunciationVersion: string;\n  readonly styleId?: string;\n  readonly cachePermission: AiSpeechProviderCachePermission;\n  readonly tier?: AiSpeechVoiceTier;\n  readonly profileId?: string;\n}\n\nexport interface AiSpeechCacheTelemetry {\n  readonly cacheHits: number;\n  readonly nearCacheHits: number;\n  readonly cacheMisses: number;\n  readonly charactersSaved: number;\n  readonly estimatedCostSavedUsd?: number;\n  readonly voiceProfileIds?: readonly string[];\n}\n\nexport interface PlanAiSpeechCacheInput {\n  readonly utteranceClass: AiSpeechUtteranceClass;\n  readonly textTemplate: string;\n  readonly playerAddress?: AiSpeechPlayerAddressInput;\n  readonly voice: AiSpeechVoiceProfileRef;\n  readonly featureFlags?: AiSpeechFeatureFlagSnapshot;\n  readonly actorScopeKey?: string;\n  readonly containsPersonalData?: boolean;\n  readonly containsPrivateContext?: boolean;\n  readonly containsModerationNotice?: boolean;\n}\n\nexport interface AiSpeechCachePlan {\n  readonly mode: AiSpeechCacheMode;\n  readonly sharingScope: AiSpeechCacheScope;\n  readonly renderText: string;\n  readonly normalizedRenderText: string;\n  readonly exactKey?: string;\n  readonly nearKey?: string;\n  readonly enabledFeatureFlags: readonly AiSpeechFeatureFlagKey[];\n  readonly playerAddress?: AiSpeechPlayerAddressDecision;\n  readonly reasonCodes: readonly string[];\n}\n\nexport function createAiSpeechCacheKey(input: AiSpeechCacheKeyInput): string {\n  const scopeDiscriminator = normalizeWhitespace(input.scopeDiscriminator ?? \"\");\n  return [\n    requireNonEmptyString(input.providerId, \"Provider id\"),\n    requireNonEmptyString(input.modelId, \"Model id\"),\n    requireNonEmptyString(input.voiceId, \"Voice id\"),\n    requireNonEmptyString(input.locale, \"Locale\"),\n    normalizeWhitespace(input.styleId ?? \"\") || \"_\",\n    requireNonEmptyString(input.format, \"Format\"),\n    requireNonEmptyString(\n      input.pronunciationVersion,\n      \"Pronunciation version\"\n    ),\n    scopeDiscriminator || \"global\",\n    normalizeAiSpeechText(input.normalizedRenderText),\n  ]\n    .map((segment) => encodeURIComponent(segment))\n    .join(\"::\");\n}\n\nexport function createAiSpeechNearReuseFingerprint(value: string): string {\n  const normalized = normalizeAiSpeechText(value)\n    .replace(/[^a-z0-9\\s]/gu, \" \")\n    .replace(/\\s+/gu, \" \")\n    .trim();\n\n  return requireNonEmptyString(normalized, \"Near-reuse fingerprint\");\n}\n\nexport function isAiSpeechNearReuseSafeClass(\n  utteranceClass: AiSpeechUtteranceClass\n): boolean {\n  return AI_SPEECH_NEAR_REUSE_SAFE_CLASS_SET.has(utteranceClass);\n}\n\nexport function planAiSpeechCache(\n  input: PlanAiSpeechCacheInput\n): AiSpeechCachePlan {\n  const rendered = renderAiSpeechText({\n    textTemplate: input.textTemplate,\n    playerAddress: input.playerAddress,\n  });\n  const enabledFeatureFlags: AiSpeechFeatureFlagKey[] = [];\n  const cacheEnabled = isAiSpeechFeatureEnabled(\n    AI_SPEECH_FEATURE_FLAGS.ttsCache,\n    input.featureFlags\n  );\n\n  if (!cacheEnabled) {\n    return {\n      mode: \"disabled\",\n      sharingScope: \"none\",\n      renderText: rendered.renderText,\n      normalizedRenderText: rendered.normalizedRenderText,\n      enabledFeatureFlags,\n      playerAddress: rendered.playerAddress,\n      reasonCodes: [\"tts-cache-rollout-disabled\"],\n    };\n  }\n\n  enabledFeatureFlags.push(AI_SPEECH_FEATURE_FLAGS.ttsCache);\n\n  if (input.voice.cachePermission === \"forbidden\") {\n    return {\n      mode: \"no-cache\",\n      sharingScope: \"none\",\n      renderText: rendered.renderText,\n      normalizedRenderText: rendered.normalizedRenderText,\n      enabledFeatureFlags,\n      playerAddress: rendered.playerAddress,\n      reasonCodes: [\"provider-forbids-tts-caching\"],\n    };\n  }\n\n  const containsSensitiveContent =\n    Boolean(input.containsPersonalData) ||\n    Boolean(input.containsPrivateContext) ||\n    Boolean(input.containsModerationNotice) ||\n    Boolean(rendered.playerAddress?.redacted);\n  const actorScopeKey = normalizeWhitespace(input.actorScopeKey ?? \"\");\n\n  const actorScopeRequired =\n    containsSensitiveContent || input.utteranceClass === \"private-response\";\n\n  if (actorScopeRequired && !actorScopeKey) {\n    return {\n      mode: \"no-cache\",\n      sharingScope: \"none\",\n      renderText: rendered.renderText,\n      normalizedRenderText: rendered.normalizedRenderText,\n      enabledFeatureFlags,\n      playerAddress: rendered.playerAddress,\n      reasonCodes: [\"actor-scope-key-required-for-sensitive-cache-entry\"],\n    };\n  }\n\n  const exactKey = createAiSpeechCacheKey({\n    ...input.voice,\n    normalizedRenderText: rendered.normalizedRenderText,\n    scopeDiscriminator: actorScopeRequired ? actorScopeKey : undefined,\n  });\n\n  const nearReuseEnabled =\n    input.voice.cachePermission === \"exact-and-near\" &&\n    isAiSpeechFeatureEnabled(\n      AI_SPEECH_FEATURE_FLAGS.ttsNearReuse,\n      input.featureFlags\n    ) &&\n    isAiSpeechNearReuseSafeClass(input.utteranceClass) &&\n    !containsSensitiveContent &&\n    (rendered.playerAddress?.nearReuseAllowed ?? true);\n\n  if (!nearReuseEnabled) {\n    return {\n      mode: \"exact\",\n      sharingScope: actorScopeRequired ? \"actor\" : \"global\",\n      renderText: rendered.renderText,\n      normalizedRenderText: rendered.normalizedRenderText,\n      exactKey,\n      enabledFeatureFlags,\n      playerAddress: rendered.playerAddress,\n      reasonCodes: containsSensitiveContent\n        ? [\"exact-cache-only-for-sensitive-or-redacted-content\"]\n        : [\"near-reuse-disabled-or-ineligible\"],\n    };\n  }\n\n  enabledFeatureFlags.push(AI_SPEECH_FEATURE_FLAGS.ttsNearReuse);\n\n  const nearKey = createAiSpeechCacheKey({\n    ...input.voice,\n    normalizedRenderText: createAiSpeechNearReuseFingerprint(\n      rendered.normalizedRenderText\n    ),\n  });\n\n  return {\n    mode: \"near\",\n    sharingScope: \"global\",\n    renderText: rendered.renderText,\n    normalizedRenderText: rendered.normalizedRenderText,\n    exactKey,\n    nearKey,\n    enabledFeatureFlags,\n    playerAddress: rendered.playerAddress,\n    reasonCodes: [\"near-reuse-eligible\"],\n  };\n}\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n  packageName: AI_SPEECH_PACKAGE,\n  featureFlagId: AI_SPEECH_FEATURE_FLAG_ID,\n  envPrefix: AI_SPEECH_ENV_PREFIX,\n  summary:\n    \"Speech orchestration, TTS cache contracts, STT/TTS routing, and voice tier policy for Plasius AI.\",\n});\n"],"mappings":"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","names":[]}

package/docs/adrs/adr-0002-tts-cache-and-address-policy-contracts.md

@@ -0,0 +1,34 @@
+# ADR-0002: TTS Cache, Player Address, and Voice Tier Contracts
+
+- Date: 2026-05-13
+- Status: Accepted
+
+## Context
+
+`@plasius/ai-speech` was bootstrapped as a publishable package but only exposed a descriptor constant. Feature `Plasius-LTD/plasius-ltd-site#263` and task `Plasius-LTD/ai-speech#1` require a public contract surface for:
+
+- exact and near-text TTS cache planning
+- cache-safe player address rendering
+- development, standard, and premium-character voice tier routing
+- rollout controls tied to remotely managed feature flags
+
+The package must stay free of secrets, product-only runtime state, and provider credentials while still giving downstream applications enough structure to apply consistent cache and routing decisions.
+
+## Decision
+
+Expose deterministic, package-level contract helpers that operate on caller-supplied metadata only:
+
+- rollout control constants for `ai.tts.cache.enabled`, `ai.tts.near-reuse.enabled`, and `ai.tts.premium-characters.enabled`
+- player-address policy helpers that redact user/account identifiers to generic labels by default
+- cache-planning helpers that distinguish disabled, no-cache, exact-cache, and near-cache modes
+- voice-tier routing helpers that separate development voices from standard and premium-character production tiers
+- telemetry shape definitions for cache hit/miss and cost-saved reporting
+
+The package does not fetch feature flags, store cache entries, or talk to speech providers directly. Those concerns remain with host applications and provider adapters.
+
+## Consequences
+
+- Consumers can centralize speech cache policy without embedding product-specific secrets.
+- Sensitive player identifiers and private response content are rejected or narrowed to actor-scoped exact cache entries.
+- Near-text reuse remains opt-in, rollout-gated, and limited to explicitly safe utterance classes.
+- Future provider adapters can depend on this package for contracts without inheriting provider implementation code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/ai-speech",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Speech orchestration, TTS cache contracts, STT/TTS routing, and voice tier policy for Plasius AI.",
   "type": "module",
   "sideEffects": false,