@charivo/avatar 0.3.5 → 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 +18 -4
- package/dist/index.js +27 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +27 -2
- package/dist/index.mjs.map +1 -1
- package/package.json +9 -2
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
|
-
|
|
124
|
-
|
|
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:
|
|
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", {
|
|
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:
|
|
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", {
|
|
213
|
+
emit("avatar:motion", {
|
|
214
|
+
group,
|
|
215
|
+
index,
|
|
216
|
+
muteSound: true
|
|
217
|
+
});
|
|
193
218
|
}
|
|
194
219
|
return;
|
|
195
220
|
}
|
package/dist/index.mjs.map
CHANGED
|
@@ -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
|
+
"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.
|
|
23
|
+
"@charivo/core": "^0.31.0"
|
|
17
24
|
},
|
|
18
25
|
"devDependencies": {
|
|
19
26
|
"tsup": "^8.5.0",
|