@charivo/avatar 0.2.7 → 0.3.1

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
@@ -45,7 +45,11 @@ import {
45
45
  createAvatarResultProjector,
46
46
  } from "@charivo/avatar";
47
47
 
48
- const catalog = { expressions: ["Smile", "Sad"], motions: { Idle: 2, TapBody: 3 } };
48
+ const catalog = {
49
+ expressions: ["Smile", "Sad"],
50
+ motions: { Idle: 2, TapBody: 3 },
51
+ expressionDescriptions: { Smile: "happy or amused", Sad: "downcast or disappointed" },
52
+ };
49
53
 
50
54
  const manager = createRealtimeManager(client, {
51
55
  tools: createAvatarControlTools(catalog),
@@ -109,6 +113,16 @@ const instructions = [
109
113
  ].join("\n");
110
114
  ```
111
115
 
116
+ ## Expression Descriptions
117
+
118
+ `catalog.expressionDescriptions` is an optional `Record<string, string>` of
119
+ expression IDs to short meanings. Keys are expression IDs from
120
+ `catalog.expressions`; keys that don't match are ignored. When present,
121
+ matching meanings are appended to the `setExpression` tool's `expressionId`
122
+ 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.
125
+
112
126
  ## Migrating From `@charivo/realtime-avatar`
113
127
 
114
128
  `@charivo/realtime-avatar` is deprecated; its published versions re-export
package/dist/index.js CHANGED
@@ -14,6 +14,17 @@ var AVATAR_CONTROL_TOOL_NAMES = [
14
14
  PLAY_MOTION_TOOL_NAME,
15
15
  LOOK_AT_TOOL_NAME
16
16
  ];
17
+ function formatExpressionMeanings(catalog) {
18
+ const descriptions = catalog.expressionDescriptions;
19
+ if (!descriptions) {
20
+ return null;
21
+ }
22
+ const entries = catalog.expressions.filter((expressionId) => Object.hasOwn(descriptions, expressionId)).map((expressionId) => `${expressionId} = ${descriptions[expressionId]}`);
23
+ if (entries.length === 0) {
24
+ return null;
25
+ }
26
+ return entries.join("; ");
27
+ }
17
28
  function buildAvatarControlInstructions(catalog) {
18
29
  const hasExpressions = catalog.expressions.length > 0;
19
30
  const hasMotions = Object.keys(catalog.motions).length > 0;
@@ -25,6 +36,10 @@ function buildAvatarControlInstructions(catalog) {
25
36
  instructions.push(
26
37
  "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."
27
38
  );
39
+ const meanings = formatExpressionMeanings(catalog);
40
+ if (meanings !== null) {
41
+ instructions.push(`Expression meanings: ${meanings}`);
42
+ }
28
43
  }
29
44
  if (hasMotions) {
30
45
  instructions.push(
@@ -42,6 +57,8 @@ function createAvatarControlTools(catalog) {
42
57
  const tools = [];
43
58
  if (catalog.expressions.length > 0) {
44
59
  const expressionValues = [...catalog.expressions];
60
+ const meanings = formatExpressionMeanings(catalog);
61
+ const expressionIdDescription = meanings === null ? "Expression ID available for your current model." : `Expression ID available for your current model. Meanings: ${meanings}`;
45
62
  tools.push({
46
63
  definition: {
47
64
  type: "function",
@@ -52,7 +69,7 @@ function createAvatarControlTools(catalog) {
52
69
  properties: {
53
70
  expressionId: {
54
71
  type: "string",
55
- description: "Expression ID available for your current model.",
72
+ description: expressionIdDescription,
56
73
  enum: expressionValues
57
74
  }
58
75
  },
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\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\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 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: \"Expression ID available for your current model.\",\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\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"]}
package/dist/index.mjs CHANGED
@@ -12,6 +12,17 @@ var AVATAR_CONTROL_TOOL_NAMES = [
12
12
  PLAY_MOTION_TOOL_NAME,
13
13
  LOOK_AT_TOOL_NAME
14
14
  ];
15
+ function formatExpressionMeanings(catalog) {
16
+ const descriptions = catalog.expressionDescriptions;
17
+ if (!descriptions) {
18
+ return null;
19
+ }
20
+ const entries = catalog.expressions.filter((expressionId) => Object.hasOwn(descriptions, expressionId)).map((expressionId) => `${expressionId} = ${descriptions[expressionId]}`);
21
+ if (entries.length === 0) {
22
+ return null;
23
+ }
24
+ return entries.join("; ");
25
+ }
15
26
  function buildAvatarControlInstructions(catalog) {
16
27
  const hasExpressions = catalog.expressions.length > 0;
17
28
  const hasMotions = Object.keys(catalog.motions).length > 0;
@@ -23,6 +34,10 @@ function buildAvatarControlInstructions(catalog) {
23
34
  instructions.push(
24
35
  "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."
25
36
  );
37
+ const meanings = formatExpressionMeanings(catalog);
38
+ if (meanings !== null) {
39
+ instructions.push(`Expression meanings: ${meanings}`);
40
+ }
26
41
  }
27
42
  if (hasMotions) {
28
43
  instructions.push(
@@ -40,6 +55,8 @@ function createAvatarControlTools(catalog) {
40
55
  const tools = [];
41
56
  if (catalog.expressions.length > 0) {
42
57
  const expressionValues = [...catalog.expressions];
58
+ const meanings = formatExpressionMeanings(catalog);
59
+ const expressionIdDescription = meanings === null ? "Expression ID available for your current model." : `Expression ID available for your current model. Meanings: ${meanings}`;
43
60
  tools.push({
44
61
  definition: {
45
62
  type: "function",
@@ -50,7 +67,7 @@ function createAvatarControlTools(catalog) {
50
67
  properties: {
51
68
  expressionId: {
52
69
  type: "string",
53
- description: "Expression ID available for your current model.",
70
+ description: expressionIdDescription,
54
71
  enum: expressionValues
55
72
  }
56
73
  },
@@ -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\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\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 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: \"Expression ID available for your current model.\",\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\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"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@charivo/avatar",
3
- "version": "0.2.7",
3
+ "version": "0.3.1",
4
4
  "description": "Avatar control tools for Charivo LLM and realtime sessions",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -13,7 +13,7 @@
13
13
  }
14
14
  },
15
15
  "dependencies": {
16
- "@charivo/core": "^0.24.0"
16
+ "@charivo/core": "^0.26.0"
17
17
  },
18
18
  "devDependencies": {
19
19
  "tsup": "^8.5.0",