@charivo/avatar 0.3.4 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -49,6 +49,7 @@ const catalog = {
49
49
  expressions: ["Smile", "Sad"],
50
50
  motions: { Idle: 2, TapBody: 3 },
51
51
  expressionDescriptions: { Smile: "happy or amused", Sad: "downcast or disappointed" },
52
+ motionDescriptions: { Idle: ["resting", "shifting weight"], TapBody: ["waves", "folds her arms"] },
52
53
  };
53
54
 
54
55
  const manager = createRealtimeManager(client, {
@@ -93,7 +94,9 @@ shape and the round cap.
93
94
  `createAvatarResultProjector()` emits, on successful tool execution:
94
95
 
95
96
  - `avatar:expression` — `{ expressionId }`
96
- - `avatar:motion` — `{ group, index }`
97
+ - `avatar:motion` — `{ group, index, muteSound: true }` — the result projector
98
+ asks for muting because the motion came from a tool call, so a sample clip
99
+ baked into the motion does not talk over the character's own voice
97
100
  - `avatar:gaze` — `{ x, y }`
98
101
 
99
102
  `@charivo/render`'s `RenderManager` already listens for these three events, so
@@ -113,15 +116,26 @@ const instructions = [
113
116
  ].join("\n");
114
117
  ```
115
118
 
116
- ## Expression Descriptions
119
+ ## Expression And Motion Descriptions
117
120
 
118
121
  `catalog.expressionDescriptions` is an optional `Record<string, string>` of
119
122
  expression IDs to short meanings. Keys are expression IDs from
120
123
  `catalog.expressions`; keys that don't match are ignored. When present,
121
124
  matching meanings are appended to the `setExpression` tool's `expressionId`
122
125
  parameter description and to `buildAvatarControlInstructions(...)` output.
123
- When absent, or when none of its keys match, both outputs are unchanged. The
124
- formatting is internal to this package — the Exports list above is unchanged.
126
+
127
+ `catalog.motionDescriptions` does the same for motions, as an optional
128
+ `Record<string, string[]>`. Keys are group names from `catalog.motions`, and
129
+ each array is positional — index 0 describes motion index 0 — because
130
+ `playMotion` takes a group AND an index, and a group-level sentence cannot tell
131
+ four different reactions apart. Groups absent from `catalog.motions`, and
132
+ entries past a group's motion count, are ignored. Matching meanings are
133
+ appended to the `playMotion` tool's `index` parameter description and to the
134
+ instructions.
135
+
136
+ When either is absent, or when none of its keys match, the outputs are
137
+ unchanged. The formatting is internal to this package — the Exports list above
138
+ is unchanged.
125
139
 
126
140
  ## Migrating From `@charivo/realtime-avatar`
127
141
 
package/dist/index.js CHANGED
@@ -25,6 +25,21 @@ function formatExpressionMeanings(catalog) {
25
25
  }
26
26
  return entries.join("; ");
27
27
  }
28
+ function formatMotionMeanings(catalog) {
29
+ const descriptions = catalog.motionDescriptions;
30
+ if (!descriptions) {
31
+ return null;
32
+ }
33
+ const entries = Object.entries(catalog.motions).filter(([group]) => Object.hasOwn(descriptions, group)).flatMap(
34
+ ([group, count]) => (descriptions[group] ?? []).slice(0, count).flatMap(
35
+ (text, index) => text ? [`${group} #${index} = ${text}`] : []
36
+ )
37
+ );
38
+ if (entries.length === 0) {
39
+ return null;
40
+ }
41
+ return entries.join("; ");
42
+ }
28
43
  function buildAvatarControlInstructions(catalog) {
29
44
  const hasExpressions = catalog.expressions.length > 0;
30
45
  const hasMotions = Object.keys(catalog.motions).length > 0;
@@ -45,6 +60,10 @@ function buildAvatarControlInstructions(catalog) {
45
60
  instructions.push(
46
61
  "Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply."
47
62
  );
63
+ const motionMeanings = formatMotionMeanings(catalog);
64
+ if (motionMeanings !== null) {
65
+ instructions.push(`Motion meanings: ${motionMeanings}`);
66
+ }
48
67
  }
49
68
  if (hasExpressions && hasMotions) {
50
69
  instructions.push(
@@ -92,6 +111,8 @@ function createAvatarControlTools(catalog) {
92
111
  }
93
112
  const motionGroups = Object.keys(catalog.motions);
94
113
  if (motionGroups.length > 0) {
114
+ const motionMeanings = formatMotionMeanings(catalog);
115
+ const motionIndexDescription = motionMeanings === null ? "Zero-based motion index within the selected motion group." : `Zero-based motion index within the selected motion group. Meanings: ${motionMeanings}`;
95
116
  tools.push({
96
117
  definition: {
97
118
  type: "function",
@@ -107,7 +128,7 @@ function createAvatarControlTools(catalog) {
107
128
  },
108
129
  index: {
109
130
  type: "number",
110
- description: "Zero-based motion index within the selected motion group."
131
+ description: motionIndexDescription
111
132
  }
112
133
  },
113
134
  required: ["group", "index"]
@@ -191,7 +212,11 @@ function createAvatarResultProjector() {
191
212
  const group = output.group;
192
213
  const index = output.index;
193
214
  if (typeof group === "string" && Number.isInteger(index)) {
194
- emit("avatar:motion", { group, index });
215
+ emit("avatar:motion", {
216
+ group,
217
+ index,
218
+ muteSound: true
219
+ });
195
220
  }
196
221
  return;
197
222
  }
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type {\n AvatarControlCatalog,\n GazeCoordinates,\n ToolRegistration,\n ToolResultProjector,\n} from \"@charivo/core\";\n\nconst MIN_GAZE = -1;\nconst MAX_GAZE = 1;\n\nconst SET_EXPRESSION_TOOL_DESCRIPTION =\n \"Change facial expression when emotion should show. Use proactively for greetings, gratitude, jokes, delight, surprise, concern, sympathy, embarrassment, frustration, tension, relief, or a warmer tone. Rich moments can pair setExpression with motion or gaze.\";\n\nconst PLAY_MOTION_TOOL_DESCRIPTION =\n \"Use a noticeable body motion for greetings, emphasis, or bigger reactions. Save this for moments that truly need body movement, and don't stack body motions in the same reply.\";\n\nconst LOOK_AT_TOOL_DESCRIPTION =\n 'Shift gaze for attention changes or focus. Trigger this on phrases like \"glance\", \"look over\", \"peek at\", or directional cues. A gaze shift can stand alone or pair with another avatar action when both fit.';\n\nexport const SET_EXPRESSION_TOOL_NAME = \"setExpression\";\nexport const PLAY_MOTION_TOOL_NAME = \"playMotion\";\nexport const LOOK_AT_TOOL_NAME = \"lookAt\";\n\nexport const AVATAR_CONTROL_TOOL_NAMES = [\n SET_EXPRESSION_TOOL_NAME,\n PLAY_MOTION_TOOL_NAME,\n LOOK_AT_TOOL_NAME,\n] as const;\n\n// Iterates `catalog.expressions` (not `Object.keys(descriptions)`) because this\n// function is the single enforcement point for the key-intersection contract:\n// output order must follow the catalog's own expression order, and description\n// keys with no matching expression must be silently dropped rather than\n// validated by callers.\nfunction formatExpressionMeanings(\n catalog: AvatarControlCatalog,\n): string | null {\n const descriptions = catalog.expressionDescriptions;\n if (!descriptions) {\n return null;\n }\n\n const entries = catalog.expressions\n .filter((expressionId) => Object.hasOwn(descriptions, expressionId))\n .map((expressionId) => `${expressionId} = ${descriptions[expressionId]}`);\n\n if (entries.length === 0) {\n return null;\n }\n\n return entries.join(\"; \");\n}\n\nexport function buildAvatarControlInstructions(\n catalog: AvatarControlCatalog,\n): string {\n const hasExpressions = catalog.expressions.length > 0;\n const hasMotions = Object.keys(catalog.motions).length > 0;\n const instructions = [\n \"Use avatar tools only when they make the moment feel present. Quiet exchanges can pass without an avatar action.\",\n \"Use lookAt when your attention shifts or a small gaze reaction is enough.\",\n ];\n\n if (hasExpressions) {\n instructions.push(\n \"React with your face when feelings come up: greetings, gratitude, jokes, teasing, concern, reassurance, surprise, or sympathy. Use setExpression with a fitting expression before you speak, even when the user did not ask for it.\",\n );\n\n const meanings = formatExpressionMeanings(catalog);\n if (meanings !== null) {\n instructions.push(`Expression meanings: ${meanings}`);\n }\n }\n\n if (hasMotions) {\n instructions.push(\n \"Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply.\",\n );\n }\n\n if (hasExpressions && hasMotions) {\n instructions.push(\n \"Richer beats can combine two avatar actions, such as setExpression plus playMotion, when both earn their place.\",\n );\n }\n\n return instructions.join(\"\\n\");\n}\n\nexport interface ExpressionArgs {\n expressionId: string;\n}\n\nexport interface MotionArgs {\n group: string;\n index: number;\n}\n\nexport type LookAtArgs = GazeCoordinates;\n\nexport function createAvatarControlTools(\n catalog: AvatarControlCatalog,\n): ToolRegistration[] {\n const tools: ToolRegistration[] = [];\n\n if (catalog.expressions.length > 0) {\n const expressionValues = [...catalog.expressions];\n const meanings = formatExpressionMeanings(catalog);\n const expressionIdDescription =\n meanings === null\n ? \"Expression ID available for your current model.\"\n : `Expression ID available for your current model. Meanings: ${meanings}`;\n tools.push({\n definition: {\n type: \"function\",\n name: SET_EXPRESSION_TOOL_NAME,\n description: SET_EXPRESSION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n expressionId: {\n type: \"string\",\n description: expressionIdDescription,\n enum: expressionValues,\n },\n },\n required: [\"expressionId\"],\n },\n },\n async handler(args) {\n const expressionId = args.expressionId;\n if (\n typeof expressionId !== \"string\" ||\n !expressionValues.includes(expressionId)\n ) {\n throw new Error(\n 'setExpression requires a valid \"expressionId\" from the model catalog',\n );\n }\n\n return {\n success: true,\n expressionId,\n };\n },\n });\n }\n\n const motionGroups = Object.keys(catalog.motions);\n if (motionGroups.length > 0) {\n tools.push({\n definition: {\n type: \"function\",\n name: PLAY_MOTION_TOOL_NAME,\n description: PLAY_MOTION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n group: {\n type: \"string\",\n description: \"Motion group available for your current model.\",\n enum: motionGroups,\n },\n index: {\n type: \"number\",\n description:\n \"Zero-based motion index within the selected motion group.\",\n },\n },\n required: [\"group\", \"index\"],\n },\n },\n async handler(args) {\n const group = args.group;\n const index = args.index;\n\n if (typeof group !== \"string\" || !motionGroups.includes(group)) {\n throw new Error(\n 'playMotion requires a valid \"group\" from the model catalog',\n );\n }\n\n if (!Number.isInteger(index)) {\n throw new Error('playMotion requires an integer \"index\"');\n }\n\n const count = catalog.motions[group] ?? 0;\n const motionIndex = index as number;\n\n if (motionIndex < 0 || motionIndex >= count) {\n throw new Error(\n `playMotion index ${String(motionIndex)} is out of range for group \"${group}\"`,\n );\n }\n\n return {\n success: true,\n group,\n index: motionIndex,\n };\n },\n });\n }\n\n tools.push({\n definition: {\n type: \"function\",\n name: LOOK_AT_TOOL_NAME,\n description: LOOK_AT_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n x: {\n type: \"number\",\n description:\n \"Normalized horizontal gaze target. -1 looks left, 0 is center, 1 looks right.\",\n },\n y: {\n type: \"number\",\n description:\n \"Normalized vertical gaze target. -1 looks down, 0 is center, 1 looks up.\",\n },\n },\n required: [\"x\", \"y\"],\n },\n },\n async handler(args) {\n const x = args.x;\n const y = args.y;\n\n if (typeof x !== \"number\" || Number.isNaN(x)) {\n throw new Error('lookAt requires a numeric \"x\"');\n }\n\n if (typeof y !== \"number\" || Number.isNaN(y)) {\n throw new Error('lookAt requires a numeric \"y\"');\n }\n\n return {\n success: true,\n x: clamp(x, MIN_GAZE, MAX_GAZE),\n y: clamp(y, MIN_GAZE, MAX_GAZE),\n };\n },\n });\n\n return tools;\n}\n\nexport function createAvatarResultProjector(): ToolResultProjector {\n return ({ name, output, emit }) => {\n switch (name) {\n case SET_EXPRESSION_TOOL_NAME: {\n const expressionId = output.expressionId;\n if (typeof expressionId === \"string\") {\n emit(\"avatar:expression\", { expressionId });\n }\n return;\n }\n\n case PLAY_MOTION_TOOL_NAME: {\n const group = output.group;\n const index = output.index;\n if (typeof group === \"string\" && Number.isInteger(index)) {\n emit(\"avatar:motion\", { group, index: index as number });\n }\n return;\n }\n\n case LOOK_AT_TOOL_NAME: {\n const coords = readGazeCoordinates(output);\n if (coords) {\n emit(\"avatar:gaze\", coords);\n }\n }\n }\n };\n}\n\nfunction readGazeCoordinates(\n output: Record<string, unknown>,\n): GazeCoordinates | null {\n const x = output.x;\n const y = output.y;\n\n if (typeof x !== \"number\" || typeof y !== \"number\") {\n return null;\n }\n\n return { x, y };\n}\n\nfunction clamp(value: number, min: number, max: number): number {\n return Math.max(min, Math.min(max, value));\n}\n"]}
1
+ {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type {\n AvatarControlCatalog,\n GazeCoordinates,\n ToolRegistration,\n ToolResultProjector,\n} from \"@charivo/core\";\n\nconst MIN_GAZE = -1;\nconst MAX_GAZE = 1;\n\nconst SET_EXPRESSION_TOOL_DESCRIPTION =\n \"Change facial expression when emotion should show. Use proactively for greetings, gratitude, jokes, delight, surprise, concern, sympathy, embarrassment, frustration, tension, relief, or a warmer tone. Rich moments can pair setExpression with motion or gaze.\";\n\nconst PLAY_MOTION_TOOL_DESCRIPTION =\n \"Use a noticeable body motion for greetings, emphasis, or bigger reactions. Save this for moments that truly need body movement, and don't stack body motions in the same reply.\";\n\nconst LOOK_AT_TOOL_DESCRIPTION =\n 'Shift gaze for attention changes or focus. Trigger this on phrases like \"glance\", \"look over\", \"peek at\", or directional cues. A gaze shift can stand alone or pair with another avatar action when both fit.';\n\nexport const SET_EXPRESSION_TOOL_NAME = \"setExpression\";\nexport const PLAY_MOTION_TOOL_NAME = \"playMotion\";\nexport const LOOK_AT_TOOL_NAME = \"lookAt\";\n\nexport const AVATAR_CONTROL_TOOL_NAMES = [\n SET_EXPRESSION_TOOL_NAME,\n PLAY_MOTION_TOOL_NAME,\n LOOK_AT_TOOL_NAME,\n] as const;\n\n// Iterates `catalog.expressions` (not `Object.keys(descriptions)`) because this\n// function is the single enforcement point for the key-intersection contract:\n// output order must follow the catalog's own expression order, and description\n// keys with no matching expression must be silently dropped rather than\n// validated by callers.\nfunction formatExpressionMeanings(\n catalog: AvatarControlCatalog,\n): string | null {\n const descriptions = catalog.expressionDescriptions;\n if (!descriptions) {\n return null;\n }\n\n const entries = catalog.expressions\n .filter((expressionId) => Object.hasOwn(descriptions, expressionId))\n .map((expressionId) => `${expressionId} = ${descriptions[expressionId]}`);\n\n if (entries.length === 0) {\n return null;\n }\n\n return entries.join(\"; \");\n}\n\n// Same key-intersection contract as formatExpressionMeanings, extended one\n// dimension: a group's descriptions are positional, so an entry past the\n// group's real motion count describes a motion that does not exist and is\n// dropped rather than surfaced.\nfunction formatMotionMeanings(catalog: AvatarControlCatalog): string | null {\n const descriptions = catalog.motionDescriptions;\n if (!descriptions) {\n return null;\n }\n\n const entries = Object.entries(catalog.motions)\n .filter(([group]) => Object.hasOwn(descriptions, group))\n .flatMap(([group, count]) =>\n (descriptions[group] ?? [])\n .slice(0, count)\n .flatMap((text, index) =>\n text ? [`${group} #${index} = ${text}`] : [],\n ),\n );\n\n if (entries.length === 0) {\n return null;\n }\n\n return entries.join(\"; \");\n}\n\nexport function buildAvatarControlInstructions(\n catalog: AvatarControlCatalog,\n): string {\n const hasExpressions = catalog.expressions.length > 0;\n const hasMotions = Object.keys(catalog.motions).length > 0;\n const instructions = [\n \"Use avatar tools only when they make the moment feel present. Quiet exchanges can pass without an avatar action.\",\n \"Use lookAt when your attention shifts or a small gaze reaction is enough.\",\n ];\n\n if (hasExpressions) {\n instructions.push(\n \"React with your face when feelings come up: greetings, gratitude, jokes, teasing, concern, reassurance, surprise, or sympathy. Use setExpression with a fitting expression before you speak, even when the user did not ask for it.\",\n );\n\n const meanings = formatExpressionMeanings(catalog);\n if (meanings !== null) {\n instructions.push(`Expression meanings: ${meanings}`);\n }\n }\n\n if (hasMotions) {\n instructions.push(\n \"Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply.\",\n );\n\n const motionMeanings = formatMotionMeanings(catalog);\n if (motionMeanings !== null) {\n instructions.push(`Motion meanings: ${motionMeanings}`);\n }\n }\n\n if (hasExpressions && hasMotions) {\n instructions.push(\n \"Richer beats can combine two avatar actions, such as setExpression plus playMotion, when both earn their place.\",\n );\n }\n\n return instructions.join(\"\\n\");\n}\n\nexport interface ExpressionArgs {\n expressionId: string;\n}\n\nexport interface MotionArgs {\n group: string;\n index: number;\n}\n\nexport type LookAtArgs = GazeCoordinates;\n\nexport function createAvatarControlTools(\n catalog: AvatarControlCatalog,\n): ToolRegistration[] {\n const tools: ToolRegistration[] = [];\n\n if (catalog.expressions.length > 0) {\n const expressionValues = [...catalog.expressions];\n const meanings = formatExpressionMeanings(catalog);\n const expressionIdDescription =\n meanings === null\n ? \"Expression ID available for your current model.\"\n : `Expression ID available for your current model. Meanings: ${meanings}`;\n tools.push({\n definition: {\n type: \"function\",\n name: SET_EXPRESSION_TOOL_NAME,\n description: SET_EXPRESSION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n expressionId: {\n type: \"string\",\n description: expressionIdDescription,\n enum: expressionValues,\n },\n },\n required: [\"expressionId\"],\n },\n },\n async handler(args) {\n const expressionId = args.expressionId;\n if (\n typeof expressionId !== \"string\" ||\n !expressionValues.includes(expressionId)\n ) {\n throw new Error(\n 'setExpression requires a valid \"expressionId\" from the model catalog',\n );\n }\n\n return {\n success: true,\n expressionId,\n };\n },\n });\n }\n\n const motionGroups = Object.keys(catalog.motions);\n if (motionGroups.length > 0) {\n const motionMeanings = formatMotionMeanings(catalog);\n const motionIndexDescription =\n motionMeanings === null\n ? \"Zero-based motion index within the selected motion group.\"\n : `Zero-based motion index within the selected motion group. Meanings: ${motionMeanings}`;\n\n tools.push({\n definition: {\n type: \"function\",\n name: PLAY_MOTION_TOOL_NAME,\n description: PLAY_MOTION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n group: {\n type: \"string\",\n description: \"Motion group available for your current model.\",\n enum: motionGroups,\n },\n index: {\n type: \"number\",\n description: motionIndexDescription,\n },\n },\n required: [\"group\", \"index\"],\n },\n },\n async handler(args) {\n const group = args.group;\n const index = args.index;\n\n if (typeof group !== \"string\" || !motionGroups.includes(group)) {\n throw new Error(\n 'playMotion requires a valid \"group\" from the model catalog',\n );\n }\n\n if (!Number.isInteger(index)) {\n throw new Error('playMotion requires an integer \"index\"');\n }\n\n const count = catalog.motions[group] ?? 0;\n const motionIndex = index as number;\n\n if (motionIndex < 0 || motionIndex >= count) {\n throw new Error(\n `playMotion index ${String(motionIndex)} is out of range for group \"${group}\"`,\n );\n }\n\n return {\n success: true,\n group,\n index: motionIndex,\n };\n },\n });\n }\n\n tools.push({\n definition: {\n type: \"function\",\n name: LOOK_AT_TOOL_NAME,\n description: LOOK_AT_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n x: {\n type: \"number\",\n description:\n \"Normalized horizontal gaze target. -1 looks left, 0 is center, 1 looks right.\",\n },\n y: {\n type: \"number\",\n description:\n \"Normalized vertical gaze target. -1 looks down, 0 is center, 1 looks up.\",\n },\n },\n required: [\"x\", \"y\"],\n },\n },\n async handler(args) {\n const x = args.x;\n const y = args.y;\n\n if (typeof x !== \"number\" || Number.isNaN(x)) {\n throw new Error('lookAt requires a numeric \"x\"');\n }\n\n if (typeof y !== \"number\" || Number.isNaN(y)) {\n throw new Error('lookAt requires a numeric \"y\"');\n }\n\n return {\n success: true,\n x: clamp(x, MIN_GAZE, MAX_GAZE),\n y: clamp(y, MIN_GAZE, MAX_GAZE),\n };\n },\n });\n\n return tools;\n}\n\nexport function createAvatarResultProjector(): ToolResultProjector {\n return ({ name, output, emit }) => {\n switch (name) {\n case SET_EXPRESSION_TOOL_NAME: {\n const expressionId = output.expressionId;\n if (typeof expressionId === \"string\") {\n emit(\"avatar:expression\", { expressionId });\n }\n return;\n }\n\n case PLAY_MOTION_TOOL_NAME: {\n const group = output.group;\n const index = output.index;\n if (typeof group === \"string\" && Number.isInteger(index)) {\n // This projector runs only on a successful playMotion tool call, so\n // it is the one place that knows the AI asked. The baked-in sample\n // clip is a different voice in a different language and would talk\n // over the character's own; a human trigger reaches the renderer\n // directly and keeps it.\n emit(\"avatar:motion\", {\n group,\n index: index as number,\n muteSound: true,\n });\n }\n return;\n }\n\n case LOOK_AT_TOOL_NAME: {\n const coords = readGazeCoordinates(output);\n if (coords) {\n emit(\"avatar:gaze\", coords);\n }\n }\n }\n };\n}\n\nfunction readGazeCoordinates(\n output: Record<string, unknown>,\n): GazeCoordinates | null {\n const x = output.x;\n const y = output.y;\n\n if (typeof x !== \"number\" || typeof y !== \"number\") {\n return null;\n }\n\n return { x, y };\n}\n\nfunction clamp(value: number, min: number, max: number): number {\n return Math.max(min, Math.min(max, value));\n}\n"]}
package/dist/index.mjs CHANGED
@@ -23,6 +23,21 @@ function formatExpressionMeanings(catalog) {
23
23
  }
24
24
  return entries.join("; ");
25
25
  }
26
+ function formatMotionMeanings(catalog) {
27
+ const descriptions = catalog.motionDescriptions;
28
+ if (!descriptions) {
29
+ return null;
30
+ }
31
+ const entries = Object.entries(catalog.motions).filter(([group]) => Object.hasOwn(descriptions, group)).flatMap(
32
+ ([group, count]) => (descriptions[group] ?? []).slice(0, count).flatMap(
33
+ (text, index) => text ? [`${group} #${index} = ${text}`] : []
34
+ )
35
+ );
36
+ if (entries.length === 0) {
37
+ return null;
38
+ }
39
+ return entries.join("; ");
40
+ }
26
41
  function buildAvatarControlInstructions(catalog) {
27
42
  const hasExpressions = catalog.expressions.length > 0;
28
43
  const hasMotions = Object.keys(catalog.motions).length > 0;
@@ -43,6 +58,10 @@ function buildAvatarControlInstructions(catalog) {
43
58
  instructions.push(
44
59
  "Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply."
45
60
  );
61
+ const motionMeanings = formatMotionMeanings(catalog);
62
+ if (motionMeanings !== null) {
63
+ instructions.push(`Motion meanings: ${motionMeanings}`);
64
+ }
46
65
  }
47
66
  if (hasExpressions && hasMotions) {
48
67
  instructions.push(
@@ -90,6 +109,8 @@ function createAvatarControlTools(catalog) {
90
109
  }
91
110
  const motionGroups = Object.keys(catalog.motions);
92
111
  if (motionGroups.length > 0) {
112
+ const motionMeanings = formatMotionMeanings(catalog);
113
+ const motionIndexDescription = motionMeanings === null ? "Zero-based motion index within the selected motion group." : `Zero-based motion index within the selected motion group. Meanings: ${motionMeanings}`;
93
114
  tools.push({
94
115
  definition: {
95
116
  type: "function",
@@ -105,7 +126,7 @@ function createAvatarControlTools(catalog) {
105
126
  },
106
127
  index: {
107
128
  type: "number",
108
- description: "Zero-based motion index within the selected motion group."
129
+ description: motionIndexDescription
109
130
  }
110
131
  },
111
132
  required: ["group", "index"]
@@ -189,7 +210,11 @@ function createAvatarResultProjector() {
189
210
  const group = output.group;
190
211
  const index = output.index;
191
212
  if (typeof group === "string" && Number.isInteger(index)) {
192
- emit("avatar:motion", { group, index });
213
+ emit("avatar:motion", {
214
+ group,
215
+ index,
216
+ muteSound: true
217
+ });
193
218
  }
194
219
  return;
195
220
  }
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type {\n AvatarControlCatalog,\n GazeCoordinates,\n ToolRegistration,\n ToolResultProjector,\n} from \"@charivo/core\";\n\nconst MIN_GAZE = -1;\nconst MAX_GAZE = 1;\n\nconst SET_EXPRESSION_TOOL_DESCRIPTION =\n \"Change facial expression when emotion should show. Use proactively for greetings, gratitude, jokes, delight, surprise, concern, sympathy, embarrassment, frustration, tension, relief, or a warmer tone. Rich moments can pair setExpression with motion or gaze.\";\n\nconst PLAY_MOTION_TOOL_DESCRIPTION =\n \"Use a noticeable body motion for greetings, emphasis, or bigger reactions. Save this for moments that truly need body movement, and don't stack body motions in the same reply.\";\n\nconst LOOK_AT_TOOL_DESCRIPTION =\n 'Shift gaze for attention changes or focus. Trigger this on phrases like \"glance\", \"look over\", \"peek at\", or directional cues. A gaze shift can stand alone or pair with another avatar action when both fit.';\n\nexport const SET_EXPRESSION_TOOL_NAME = \"setExpression\";\nexport const PLAY_MOTION_TOOL_NAME = \"playMotion\";\nexport const LOOK_AT_TOOL_NAME = \"lookAt\";\n\nexport const AVATAR_CONTROL_TOOL_NAMES = [\n SET_EXPRESSION_TOOL_NAME,\n PLAY_MOTION_TOOL_NAME,\n LOOK_AT_TOOL_NAME,\n] as const;\n\n// Iterates `catalog.expressions` (not `Object.keys(descriptions)`) because this\n// function is the single enforcement point for the key-intersection contract:\n// output order must follow the catalog's own expression order, and description\n// keys with no matching expression must be silently dropped rather than\n// validated by callers.\nfunction formatExpressionMeanings(\n catalog: AvatarControlCatalog,\n): string | null {\n const descriptions = catalog.expressionDescriptions;\n if (!descriptions) {\n return null;\n }\n\n const entries = catalog.expressions\n .filter((expressionId) => Object.hasOwn(descriptions, expressionId))\n .map((expressionId) => `${expressionId} = ${descriptions[expressionId]}`);\n\n if (entries.length === 0) {\n return null;\n }\n\n return entries.join(\"; \");\n}\n\nexport function buildAvatarControlInstructions(\n catalog: AvatarControlCatalog,\n): string {\n const hasExpressions = catalog.expressions.length > 0;\n const hasMotions = Object.keys(catalog.motions).length > 0;\n const instructions = [\n \"Use avatar tools only when they make the moment feel present. Quiet exchanges can pass without an avatar action.\",\n \"Use lookAt when your attention shifts or a small gaze reaction is enough.\",\n ];\n\n if (hasExpressions) {\n instructions.push(\n \"React with your face when feelings come up: greetings, gratitude, jokes, teasing, concern, reassurance, surprise, or sympathy. Use setExpression with a fitting expression before you speak, even when the user did not ask for it.\",\n );\n\n const meanings = formatExpressionMeanings(catalog);\n if (meanings !== null) {\n instructions.push(`Expression meanings: ${meanings}`);\n }\n }\n\n if (hasMotions) {\n instructions.push(\n \"Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply.\",\n );\n }\n\n if (hasExpressions && hasMotions) {\n instructions.push(\n \"Richer beats can combine two avatar actions, such as setExpression plus playMotion, when both earn their place.\",\n );\n }\n\n return instructions.join(\"\\n\");\n}\n\nexport interface ExpressionArgs {\n expressionId: string;\n}\n\nexport interface MotionArgs {\n group: string;\n index: number;\n}\n\nexport type LookAtArgs = GazeCoordinates;\n\nexport function createAvatarControlTools(\n catalog: AvatarControlCatalog,\n): ToolRegistration[] {\n const tools: ToolRegistration[] = [];\n\n if (catalog.expressions.length > 0) {\n const expressionValues = [...catalog.expressions];\n const meanings = formatExpressionMeanings(catalog);\n const expressionIdDescription =\n meanings === null\n ? \"Expression ID available for your current model.\"\n : `Expression ID available for your current model. Meanings: ${meanings}`;\n tools.push({\n definition: {\n type: \"function\",\n name: SET_EXPRESSION_TOOL_NAME,\n description: SET_EXPRESSION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n expressionId: {\n type: \"string\",\n description: expressionIdDescription,\n enum: expressionValues,\n },\n },\n required: [\"expressionId\"],\n },\n },\n async handler(args) {\n const expressionId = args.expressionId;\n if (\n typeof expressionId !== \"string\" ||\n !expressionValues.includes(expressionId)\n ) {\n throw new Error(\n 'setExpression requires a valid \"expressionId\" from the model catalog',\n );\n }\n\n return {\n success: true,\n expressionId,\n };\n },\n });\n }\n\n const motionGroups = Object.keys(catalog.motions);\n if (motionGroups.length > 0) {\n tools.push({\n definition: {\n type: \"function\",\n name: PLAY_MOTION_TOOL_NAME,\n description: PLAY_MOTION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n group: {\n type: \"string\",\n description: \"Motion group available for your current model.\",\n enum: motionGroups,\n },\n index: {\n type: \"number\",\n description:\n \"Zero-based motion index within the selected motion group.\",\n },\n },\n required: [\"group\", \"index\"],\n },\n },\n async handler(args) {\n const group = args.group;\n const index = args.index;\n\n if (typeof group !== \"string\" || !motionGroups.includes(group)) {\n throw new Error(\n 'playMotion requires a valid \"group\" from the model catalog',\n );\n }\n\n if (!Number.isInteger(index)) {\n throw new Error('playMotion requires an integer \"index\"');\n }\n\n const count = catalog.motions[group] ?? 0;\n const motionIndex = index as number;\n\n if (motionIndex < 0 || motionIndex >= count) {\n throw new Error(\n `playMotion index ${String(motionIndex)} is out of range for group \"${group}\"`,\n );\n }\n\n return {\n success: true,\n group,\n index: motionIndex,\n };\n },\n });\n }\n\n tools.push({\n definition: {\n type: \"function\",\n name: LOOK_AT_TOOL_NAME,\n description: LOOK_AT_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n x: {\n type: \"number\",\n description:\n \"Normalized horizontal gaze target. -1 looks left, 0 is center, 1 looks right.\",\n },\n y: {\n type: \"number\",\n description:\n \"Normalized vertical gaze target. -1 looks down, 0 is center, 1 looks up.\",\n },\n },\n required: [\"x\", \"y\"],\n },\n },\n async handler(args) {\n const x = args.x;\n const y = args.y;\n\n if (typeof x !== \"number\" || Number.isNaN(x)) {\n throw new Error('lookAt requires a numeric \"x\"');\n }\n\n if (typeof y !== \"number\" || Number.isNaN(y)) {\n throw new Error('lookAt requires a numeric \"y\"');\n }\n\n return {\n success: true,\n x: clamp(x, MIN_GAZE, MAX_GAZE),\n y: clamp(y, MIN_GAZE, MAX_GAZE),\n };\n },\n });\n\n return tools;\n}\n\nexport function createAvatarResultProjector(): ToolResultProjector {\n return ({ name, output, emit }) => {\n switch (name) {\n case SET_EXPRESSION_TOOL_NAME: {\n const expressionId = output.expressionId;\n if (typeof expressionId === \"string\") {\n emit(\"avatar:expression\", { expressionId });\n }\n return;\n }\n\n case PLAY_MOTION_TOOL_NAME: {\n const group = output.group;\n const index = output.index;\n if (typeof group === \"string\" && Number.isInteger(index)) {\n emit(\"avatar:motion\", { group, index: index as number });\n }\n return;\n }\n\n case LOOK_AT_TOOL_NAME: {\n const coords = readGazeCoordinates(output);\n if (coords) {\n emit(\"avatar:gaze\", coords);\n }\n }\n }\n };\n}\n\nfunction readGazeCoordinates(\n output: Record<string, unknown>,\n): GazeCoordinates | null {\n const x = output.x;\n const y = output.y;\n\n if (typeof x !== \"number\" || typeof y !== \"number\") {\n return null;\n }\n\n return { x, y };\n}\n\nfunction clamp(value: number, min: number, max: number): number {\n return Math.max(min, Math.min(max, value));\n}\n"]}
1
+ {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type {\n AvatarControlCatalog,\n GazeCoordinates,\n ToolRegistration,\n ToolResultProjector,\n} from \"@charivo/core\";\n\nconst MIN_GAZE = -1;\nconst MAX_GAZE = 1;\n\nconst SET_EXPRESSION_TOOL_DESCRIPTION =\n \"Change facial expression when emotion should show. Use proactively for greetings, gratitude, jokes, delight, surprise, concern, sympathy, embarrassment, frustration, tension, relief, or a warmer tone. Rich moments can pair setExpression with motion or gaze.\";\n\nconst PLAY_MOTION_TOOL_DESCRIPTION =\n \"Use a noticeable body motion for greetings, emphasis, or bigger reactions. Save this for moments that truly need body movement, and don't stack body motions in the same reply.\";\n\nconst LOOK_AT_TOOL_DESCRIPTION =\n 'Shift gaze for attention changes or focus. Trigger this on phrases like \"glance\", \"look over\", \"peek at\", or directional cues. A gaze shift can stand alone or pair with another avatar action when both fit.';\n\nexport const SET_EXPRESSION_TOOL_NAME = \"setExpression\";\nexport const PLAY_MOTION_TOOL_NAME = \"playMotion\";\nexport const LOOK_AT_TOOL_NAME = \"lookAt\";\n\nexport const AVATAR_CONTROL_TOOL_NAMES = [\n SET_EXPRESSION_TOOL_NAME,\n PLAY_MOTION_TOOL_NAME,\n LOOK_AT_TOOL_NAME,\n] as const;\n\n// Iterates `catalog.expressions` (not `Object.keys(descriptions)`) because this\n// function is the single enforcement point for the key-intersection contract:\n// output order must follow the catalog's own expression order, and description\n// keys with no matching expression must be silently dropped rather than\n// validated by callers.\nfunction formatExpressionMeanings(\n catalog: AvatarControlCatalog,\n): string | null {\n const descriptions = catalog.expressionDescriptions;\n if (!descriptions) {\n return null;\n }\n\n const entries = catalog.expressions\n .filter((expressionId) => Object.hasOwn(descriptions, expressionId))\n .map((expressionId) => `${expressionId} = ${descriptions[expressionId]}`);\n\n if (entries.length === 0) {\n return null;\n }\n\n return entries.join(\"; \");\n}\n\n// Same key-intersection contract as formatExpressionMeanings, extended one\n// dimension: a group's descriptions are positional, so an entry past the\n// group's real motion count describes a motion that does not exist and is\n// dropped rather than surfaced.\nfunction formatMotionMeanings(catalog: AvatarControlCatalog): string | null {\n const descriptions = catalog.motionDescriptions;\n if (!descriptions) {\n return null;\n }\n\n const entries = Object.entries(catalog.motions)\n .filter(([group]) => Object.hasOwn(descriptions, group))\n .flatMap(([group, count]) =>\n (descriptions[group] ?? [])\n .slice(0, count)\n .flatMap((text, index) =>\n text ? [`${group} #${index} = ${text}`] : [],\n ),\n );\n\n if (entries.length === 0) {\n return null;\n }\n\n return entries.join(\"; \");\n}\n\nexport function buildAvatarControlInstructions(\n catalog: AvatarControlCatalog,\n): string {\n const hasExpressions = catalog.expressions.length > 0;\n const hasMotions = Object.keys(catalog.motions).length > 0;\n const instructions = [\n \"Use avatar tools only when they make the moment feel present. Quiet exchanges can pass without an avatar action.\",\n \"Use lookAt when your attention shifts or a small gaze reaction is enough.\",\n ];\n\n if (hasExpressions) {\n instructions.push(\n \"React with your face when feelings come up: greetings, gratitude, jokes, teasing, concern, reassurance, surprise, or sympathy. Use setExpression with a fitting expression before you speak, even when the user did not ask for it.\",\n );\n\n const meanings = formatExpressionMeanings(catalog);\n if (meanings !== null) {\n instructions.push(`Expression meanings: ${meanings}`);\n }\n }\n\n if (hasMotions) {\n instructions.push(\n \"Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply.\",\n );\n\n const motionMeanings = formatMotionMeanings(catalog);\n if (motionMeanings !== null) {\n instructions.push(`Motion meanings: ${motionMeanings}`);\n }\n }\n\n if (hasExpressions && hasMotions) {\n instructions.push(\n \"Richer beats can combine two avatar actions, such as setExpression plus playMotion, when both earn their place.\",\n );\n }\n\n return instructions.join(\"\\n\");\n}\n\nexport interface ExpressionArgs {\n expressionId: string;\n}\n\nexport interface MotionArgs {\n group: string;\n index: number;\n}\n\nexport type LookAtArgs = GazeCoordinates;\n\nexport function createAvatarControlTools(\n catalog: AvatarControlCatalog,\n): ToolRegistration[] {\n const tools: ToolRegistration[] = [];\n\n if (catalog.expressions.length > 0) {\n const expressionValues = [...catalog.expressions];\n const meanings = formatExpressionMeanings(catalog);\n const expressionIdDescription =\n meanings === null\n ? \"Expression ID available for your current model.\"\n : `Expression ID available for your current model. Meanings: ${meanings}`;\n tools.push({\n definition: {\n type: \"function\",\n name: SET_EXPRESSION_TOOL_NAME,\n description: SET_EXPRESSION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n expressionId: {\n type: \"string\",\n description: expressionIdDescription,\n enum: expressionValues,\n },\n },\n required: [\"expressionId\"],\n },\n },\n async handler(args) {\n const expressionId = args.expressionId;\n if (\n typeof expressionId !== \"string\" ||\n !expressionValues.includes(expressionId)\n ) {\n throw new Error(\n 'setExpression requires a valid \"expressionId\" from the model catalog',\n );\n }\n\n return {\n success: true,\n expressionId,\n };\n },\n });\n }\n\n const motionGroups = Object.keys(catalog.motions);\n if (motionGroups.length > 0) {\n const motionMeanings = formatMotionMeanings(catalog);\n const motionIndexDescription =\n motionMeanings === null\n ? \"Zero-based motion index within the selected motion group.\"\n : `Zero-based motion index within the selected motion group. Meanings: ${motionMeanings}`;\n\n tools.push({\n definition: {\n type: \"function\",\n name: PLAY_MOTION_TOOL_NAME,\n description: PLAY_MOTION_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n group: {\n type: \"string\",\n description: \"Motion group available for your current model.\",\n enum: motionGroups,\n },\n index: {\n type: \"number\",\n description: motionIndexDescription,\n },\n },\n required: [\"group\", \"index\"],\n },\n },\n async handler(args) {\n const group = args.group;\n const index = args.index;\n\n if (typeof group !== \"string\" || !motionGroups.includes(group)) {\n throw new Error(\n 'playMotion requires a valid \"group\" from the model catalog',\n );\n }\n\n if (!Number.isInteger(index)) {\n throw new Error('playMotion requires an integer \"index\"');\n }\n\n const count = catalog.motions[group] ?? 0;\n const motionIndex = index as number;\n\n if (motionIndex < 0 || motionIndex >= count) {\n throw new Error(\n `playMotion index ${String(motionIndex)} is out of range for group \"${group}\"`,\n );\n }\n\n return {\n success: true,\n group,\n index: motionIndex,\n };\n },\n });\n }\n\n tools.push({\n definition: {\n type: \"function\",\n name: LOOK_AT_TOOL_NAME,\n description: LOOK_AT_TOOL_DESCRIPTION,\n parameters: {\n type: \"object\",\n properties: {\n x: {\n type: \"number\",\n description:\n \"Normalized horizontal gaze target. -1 looks left, 0 is center, 1 looks right.\",\n },\n y: {\n type: \"number\",\n description:\n \"Normalized vertical gaze target. -1 looks down, 0 is center, 1 looks up.\",\n },\n },\n required: [\"x\", \"y\"],\n },\n },\n async handler(args) {\n const x = args.x;\n const y = args.y;\n\n if (typeof x !== \"number\" || Number.isNaN(x)) {\n throw new Error('lookAt requires a numeric \"x\"');\n }\n\n if (typeof y !== \"number\" || Number.isNaN(y)) {\n throw new Error('lookAt requires a numeric \"y\"');\n }\n\n return {\n success: true,\n x: clamp(x, MIN_GAZE, MAX_GAZE),\n y: clamp(y, MIN_GAZE, MAX_GAZE),\n };\n },\n });\n\n return tools;\n}\n\nexport function createAvatarResultProjector(): ToolResultProjector {\n return ({ name, output, emit }) => {\n switch (name) {\n case SET_EXPRESSION_TOOL_NAME: {\n const expressionId = output.expressionId;\n if (typeof expressionId === \"string\") {\n emit(\"avatar:expression\", { expressionId });\n }\n return;\n }\n\n case PLAY_MOTION_TOOL_NAME: {\n const group = output.group;\n const index = output.index;\n if (typeof group === \"string\" && Number.isInteger(index)) {\n // This projector runs only on a successful playMotion tool call, so\n // it is the one place that knows the AI asked. The baked-in sample\n // clip is a different voice in a different language and would talk\n // over the character's own; a human trigger reaches the renderer\n // directly and keeps it.\n emit(\"avatar:motion\", {\n group,\n index: index as number,\n muteSound: true,\n });\n }\n return;\n }\n\n case LOOK_AT_TOOL_NAME: {\n const coords = readGazeCoordinates(output);\n if (coords) {\n emit(\"avatar:gaze\", coords);\n }\n }\n }\n };\n}\n\nfunction readGazeCoordinates(\n output: Record<string, unknown>,\n): GazeCoordinates | null {\n const x = output.x;\n const y = output.y;\n\n if (typeof x !== \"number\" || typeof y !== \"number\") {\n return null;\n }\n\n return { x, y };\n}\n\nfunction clamp(value: number, min: number, max: number): number {\n return Math.max(min, Math.min(max, value));\n}\n"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@charivo/avatar",
3
- "version": "0.3.4",
3
+ "version": "0.4.0",
4
4
  "description": "Avatar control tools for Charivo LLM and realtime sessions",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -12,8 +12,15 @@
12
12
  "require": "./dist/index.js"
13
13
  }
14
14
  },
15
+ "keywords": [
16
+ "charivo",
17
+ "avatar",
18
+ "expression",
19
+ "motion",
20
+ "tool-calling"
21
+ ],
15
22
  "dependencies": {
16
- "@charivo/core": "^0.29.0"
23
+ "@charivo/core": "^0.31.0"
17
24
  },
18
25
  "devDependencies": {
19
26
  "tsup": "^8.5.0",