@charivo/avatar 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Zeikar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,121 @@
1
+ # @charivo/avatar
2
+
3
+ Catalog-constrained avatar control tools for Charivo LLM and realtime sessions.
4
+
5
+ `@charivo/avatar` depends only on `@charivo/core`. It builds `setExpression`,
6
+ `playMotion`, and `lookAt` tool definitions/handlers from your model's
7
+ expression and motion catalog, plus a matching instruction string and a result
8
+ projector that turns successful tool calls into `avatar:*` events.
9
+
10
+ Pair `createAvatarControlTools(...)` with `buildAvatarControlInstructions(...)`
11
+ when you want the model to use avatar actions proactively. Keep those
12
+ instructions in the app/session layer rather than in `@charivo/llm` or
13
+ `@charivo/realtime` so non-avatar sessions in those packages stay generic.
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ pnpm add @charivo/avatar
19
+ ```
20
+
21
+ ## Exports
22
+
23
+ - `createAvatarControlTools(catalog)`
24
+ - `buildAvatarControlInstructions(catalog)`
25
+ - `createAvatarResultProjector()`
26
+ - `AVATAR_CONTROL_TOOL_NAMES`
27
+ - `SET_EXPRESSION_TOOL_NAME`
28
+ - `PLAY_MOTION_TOOL_NAME`
29
+ - `LOOK_AT_TOOL_NAME`
30
+ - `type ExpressionArgs`, `type MotionArgs`, `type LookAtArgs`
31
+
32
+ `createAvatarControlTools(catalog)` returns `ToolRegistration[]` from
33
+ `@charivo/core`, so it works with both `LLMManager` (`@charivo/llm`) and
34
+ `RealtimeManager` (`@charivo/realtime`) tool registries. `setExpression` and
35
+ `playMotion` are included only when `catalog.expressions` /
36
+ `catalog.motions` are non-empty; `lookAt` is always included.
37
+
38
+ ## Usage With `RealtimeManager`
39
+
40
+ ```ts
41
+ import { createRealtimeManager } from "@charivo/realtime";
42
+ import {
43
+ buildAvatarControlInstructions,
44
+ createAvatarControlTools,
45
+ createAvatarResultProjector,
46
+ } from "@charivo/avatar";
47
+
48
+ const catalog = { expressions: ["Smile", "Sad"], motions: { Idle: 2, TapBody: 3 } };
49
+
50
+ const manager = createRealtimeManager(client, {
51
+ tools: createAvatarControlTools(catalog),
52
+ resultProjectors: [createAvatarResultProjector()],
53
+ });
54
+
55
+ await manager.startSession({
56
+ provider: "openai",
57
+ instructions: buildAvatarControlInstructions(catalog),
58
+ });
59
+ ```
60
+
61
+ ## Usage With `LLMManager`
62
+
63
+ ```ts
64
+ import { createLLMManager } from "@charivo/llm";
65
+ import { createRemoteLLMClient } from "@charivo/llm/remote";
66
+ import {
67
+ buildAvatarControlInstructions,
68
+ createAvatarControlTools,
69
+ createAvatarResultProjector,
70
+ } from "@charivo/avatar";
71
+
72
+ const catalog = { expressions: ["Smile", "Sad"], motions: { Idle: 2, TapBody: 3 } };
73
+
74
+ const manager = createLLMManager(createRemoteLLMClient({ apiEndpoint: "/api/chat" }), {
75
+ tools: createAvatarControlTools(catalog),
76
+ resultProjectors: [createAvatarResultProjector()],
77
+ toolInstructions: buildAvatarControlInstructions(catalog),
78
+ });
79
+ ```
80
+
81
+ `LLMManager` only runs the tool loop when the underlying `LLMClient` also
82
+ implements `callWithTools` (e.g. `@charivo/llm/remote` talking to a route that
83
+ forwards tools to `generateResponseWithTools`). See the
84
+ [LLM package README](../llm/README.md#tool-calling) for the remote request/response
85
+ shape and the round cap.
86
+
87
+ ## Events
88
+
89
+ `createAvatarResultProjector()` emits, on successful tool execution:
90
+
91
+ - `avatar:expression` — `{ expressionId }`
92
+ - `avatar:motion` — `{ group, index }`
93
+ - `avatar:gaze` — `{ x, y }`
94
+
95
+ `@charivo/render`'s `RenderManager` already listens for these three events, so
96
+ wiring a `RenderManager` picks them up automatically.
97
+
98
+ ## Instruction Composition
99
+
100
+ `buildAvatarControlInstructions(catalog)` returns generic, catalog-aware
101
+ guidance (it adjusts wording based on which of expressions/motions are
102
+ available). If your app needs stronger product-specific acting guidance,
103
+ append it at the app layer instead of expanding this package's default text:
104
+
105
+ ```ts
106
+ const instructions = [
107
+ buildAvatarControlInstructions(catalog),
108
+ "Keep replies short and natural for this product.",
109
+ ].join("\n");
110
+ ```
111
+
112
+ ## Migrating From `@charivo/realtime-avatar`
113
+
114
+ `@charivo/realtime-avatar` is deprecated and now re-exports this package.
115
+ Replace the dependency and imports:
116
+
117
+ ```bash
118
+ s/@charivo\/realtime-avatar/@charivo\/avatar/
119
+ ```
120
+
121
+ All exports listed above are unchanged.
@@ -0,0 +1,19 @@
1
+ import { AvatarControlCatalog, GazeCoordinates, ToolRegistration, ToolResultProjector } from '@charivo/core';
2
+
3
+ declare const SET_EXPRESSION_TOOL_NAME = "setExpression";
4
+ declare const PLAY_MOTION_TOOL_NAME = "playMotion";
5
+ declare const LOOK_AT_TOOL_NAME = "lookAt";
6
+ declare const AVATAR_CONTROL_TOOL_NAMES: readonly ["setExpression", "playMotion", "lookAt"];
7
+ declare function buildAvatarControlInstructions(catalog: AvatarControlCatalog): string;
8
+ interface ExpressionArgs {
9
+ expressionId: string;
10
+ }
11
+ interface MotionArgs {
12
+ group: string;
13
+ index: number;
14
+ }
15
+ type LookAtArgs = GazeCoordinates;
16
+ declare function createAvatarControlTools(catalog: AvatarControlCatalog): ToolRegistration[];
17
+ declare function createAvatarResultProjector(): ToolResultProjector;
18
+
19
+ export { AVATAR_CONTROL_TOOL_NAMES, type ExpressionArgs, LOOK_AT_TOOL_NAME, type LookAtArgs, type MotionArgs, PLAY_MOTION_TOOL_NAME, SET_EXPRESSION_TOOL_NAME, buildAvatarControlInstructions, createAvatarControlTools, createAvatarResultProjector };
@@ -0,0 +1,19 @@
1
+ import { AvatarControlCatalog, GazeCoordinates, ToolRegistration, ToolResultProjector } from '@charivo/core';
2
+
3
+ declare const SET_EXPRESSION_TOOL_NAME = "setExpression";
4
+ declare const PLAY_MOTION_TOOL_NAME = "playMotion";
5
+ declare const LOOK_AT_TOOL_NAME = "lookAt";
6
+ declare const AVATAR_CONTROL_TOOL_NAMES: readonly ["setExpression", "playMotion", "lookAt"];
7
+ declare function buildAvatarControlInstructions(catalog: AvatarControlCatalog): string;
8
+ interface ExpressionArgs {
9
+ expressionId: string;
10
+ }
11
+ interface MotionArgs {
12
+ group: string;
13
+ index: number;
14
+ }
15
+ type LookAtArgs = GazeCoordinates;
16
+ declare function createAvatarControlTools(catalog: AvatarControlCatalog): ToolRegistration[];
17
+ declare function createAvatarResultProjector(): ToolResultProjector;
18
+
19
+ export { AVATAR_CONTROL_TOOL_NAMES, type ExpressionArgs, LOOK_AT_TOOL_NAME, type LookAtArgs, type MotionArgs, PLAY_MOTION_TOOL_NAME, SET_EXPRESSION_TOOL_NAME, buildAvatarControlInstructions, createAvatarControlTools, createAvatarResultProjector };
package/dist/index.js ADDED
@@ -0,0 +1,210 @@
1
+ 'use strict';
2
+
3
+ // src/index.ts
4
+ var MIN_GAZE = -1;
5
+ var MAX_GAZE = 1;
6
+ var SET_EXPRESSION_TOOL_DESCRIPTION = "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.";
7
+ var PLAY_MOTION_TOOL_DESCRIPTION = "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.";
8
+ var LOOK_AT_TOOL_DESCRIPTION = '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.';
9
+ var SET_EXPRESSION_TOOL_NAME = "setExpression";
10
+ var PLAY_MOTION_TOOL_NAME = "playMotion";
11
+ var LOOK_AT_TOOL_NAME = "lookAt";
12
+ var AVATAR_CONTROL_TOOL_NAMES = [
13
+ SET_EXPRESSION_TOOL_NAME,
14
+ PLAY_MOTION_TOOL_NAME,
15
+ LOOK_AT_TOOL_NAME
16
+ ];
17
+ function buildAvatarControlInstructions(catalog) {
18
+ const hasExpressions = catalog.expressions.length > 0;
19
+ const hasMotions = Object.keys(catalog.motions).length > 0;
20
+ const instructions = [
21
+ "Use avatar tools only when they make the moment feel present. Quiet exchanges can pass without an avatar action.",
22
+ "Use lookAt when your attention shifts or a small gaze reaction is enough."
23
+ ];
24
+ if (hasExpressions) {
25
+ instructions.push(
26
+ "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
+ );
28
+ }
29
+ if (hasMotions) {
30
+ instructions.push(
31
+ "Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply."
32
+ );
33
+ }
34
+ if (hasExpressions && hasMotions) {
35
+ instructions.push(
36
+ "Richer beats can combine two avatar actions, such as setExpression plus playMotion, when both earn their place."
37
+ );
38
+ }
39
+ return instructions.join("\n");
40
+ }
41
+ function createAvatarControlTools(catalog) {
42
+ const tools = [];
43
+ if (catalog.expressions.length > 0) {
44
+ const expressionValues = [...catalog.expressions];
45
+ tools.push({
46
+ definition: {
47
+ type: "function",
48
+ name: SET_EXPRESSION_TOOL_NAME,
49
+ description: SET_EXPRESSION_TOOL_DESCRIPTION,
50
+ parameters: {
51
+ type: "object",
52
+ properties: {
53
+ expressionId: {
54
+ type: "string",
55
+ description: "Expression ID available for your current model.",
56
+ enum: expressionValues
57
+ }
58
+ },
59
+ required: ["expressionId"]
60
+ }
61
+ },
62
+ async handler(args) {
63
+ const expressionId = args.expressionId;
64
+ if (typeof expressionId !== "string" || !expressionValues.includes(expressionId)) {
65
+ throw new Error(
66
+ 'setExpression requires a valid "expressionId" from the model catalog'
67
+ );
68
+ }
69
+ return {
70
+ success: true,
71
+ expressionId
72
+ };
73
+ }
74
+ });
75
+ }
76
+ const motionGroups = Object.keys(catalog.motions);
77
+ if (motionGroups.length > 0) {
78
+ tools.push({
79
+ definition: {
80
+ type: "function",
81
+ name: PLAY_MOTION_TOOL_NAME,
82
+ description: PLAY_MOTION_TOOL_DESCRIPTION,
83
+ parameters: {
84
+ type: "object",
85
+ properties: {
86
+ group: {
87
+ type: "string",
88
+ description: "Motion group available for your current model.",
89
+ enum: motionGroups
90
+ },
91
+ index: {
92
+ type: "number",
93
+ description: "Zero-based motion index within the selected motion group."
94
+ }
95
+ },
96
+ required: ["group", "index"]
97
+ }
98
+ },
99
+ async handler(args) {
100
+ const group = args.group;
101
+ const index = args.index;
102
+ if (typeof group !== "string" || !motionGroups.includes(group)) {
103
+ throw new Error(
104
+ 'playMotion requires a valid "group" from the model catalog'
105
+ );
106
+ }
107
+ if (!Number.isInteger(index)) {
108
+ throw new Error('playMotion requires an integer "index"');
109
+ }
110
+ const count = catalog.motions[group] ?? 0;
111
+ const motionIndex = index;
112
+ if (motionIndex < 0 || motionIndex >= count) {
113
+ throw new Error(
114
+ `playMotion index ${String(motionIndex)} is out of range for group "${group}"`
115
+ );
116
+ }
117
+ return {
118
+ success: true,
119
+ group,
120
+ index: motionIndex
121
+ };
122
+ }
123
+ });
124
+ }
125
+ tools.push({
126
+ definition: {
127
+ type: "function",
128
+ name: LOOK_AT_TOOL_NAME,
129
+ description: LOOK_AT_TOOL_DESCRIPTION,
130
+ parameters: {
131
+ type: "object",
132
+ properties: {
133
+ x: {
134
+ type: "number",
135
+ description: "Normalized horizontal gaze target. -1 looks left, 0 is center, 1 looks right."
136
+ },
137
+ y: {
138
+ type: "number",
139
+ description: "Normalized vertical gaze target. -1 looks down, 0 is center, 1 looks up."
140
+ }
141
+ },
142
+ required: ["x", "y"]
143
+ }
144
+ },
145
+ async handler(args) {
146
+ const x = args.x;
147
+ const y = args.y;
148
+ if (typeof x !== "number" || Number.isNaN(x)) {
149
+ throw new Error('lookAt requires a numeric "x"');
150
+ }
151
+ if (typeof y !== "number" || Number.isNaN(y)) {
152
+ throw new Error('lookAt requires a numeric "y"');
153
+ }
154
+ return {
155
+ success: true,
156
+ x: clamp(x, MIN_GAZE, MAX_GAZE),
157
+ y: clamp(y, MIN_GAZE, MAX_GAZE)
158
+ };
159
+ }
160
+ });
161
+ return tools;
162
+ }
163
+ function createAvatarResultProjector() {
164
+ return ({ name, output, emit }) => {
165
+ switch (name) {
166
+ case SET_EXPRESSION_TOOL_NAME: {
167
+ const expressionId = output.expressionId;
168
+ if (typeof expressionId === "string") {
169
+ emit("avatar:expression", { expressionId });
170
+ }
171
+ return;
172
+ }
173
+ case PLAY_MOTION_TOOL_NAME: {
174
+ const group = output.group;
175
+ const index = output.index;
176
+ if (typeof group === "string" && Number.isInteger(index)) {
177
+ emit("avatar:motion", { group, index });
178
+ }
179
+ return;
180
+ }
181
+ case LOOK_AT_TOOL_NAME: {
182
+ const coords = readGazeCoordinates(output);
183
+ if (coords) {
184
+ emit("avatar:gaze", coords);
185
+ }
186
+ }
187
+ }
188
+ };
189
+ }
190
+ function readGazeCoordinates(output) {
191
+ const x = output.x;
192
+ const y = output.y;
193
+ if (typeof x !== "number" || typeof y !== "number") {
194
+ return null;
195
+ }
196
+ return { x, y };
197
+ }
198
+ function clamp(value, min, max) {
199
+ return Math.max(min, Math.min(max, value));
200
+ }
201
+
202
+ exports.AVATAR_CONTROL_TOOL_NAMES = AVATAR_CONTROL_TOOL_NAMES;
203
+ exports.LOOK_AT_TOOL_NAME = LOOK_AT_TOOL_NAME;
204
+ exports.PLAY_MOTION_TOOL_NAME = PLAY_MOTION_TOOL_NAME;
205
+ exports.SET_EXPRESSION_TOOL_NAME = SET_EXPRESSION_TOOL_NAME;
206
+ exports.buildAvatarControlInstructions = buildAvatarControlInstructions;
207
+ exports.createAvatarControlTools = createAvatarControlTools;
208
+ exports.createAvatarResultProjector = createAvatarResultProjector;
209
+ //# sourceMappingURL=index.js.map
210
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAOA,IAAM,QAAA,GAAW,EAAA;AACjB,IAAM,QAAA,GAAW,CAAA;AAEjB,IAAM,+BAAA,GACJ,mQAAA;AAEF,IAAM,4BAAA,GACJ,iLAAA;AAEF,IAAM,wBAAA,GACJ,+MAAA;AAEK,IAAM,wBAAA,GAA2B;AACjC,IAAM,qBAAA,GAAwB;AAC9B,IAAM,iBAAA,GAAoB;AAE1B,IAAM,yBAAA,GAA4B;AAAA,EACvC,wBAAA;AAAA,EACA,qBAAA;AAAA,EACA;AACF;AAEO,SAAS,+BACd,OAAA,EACQ;AACR,EAAA,MAAM,cAAA,GAAiB,OAAA,CAAQ,WAAA,CAAY,MAAA,GAAS,CAAA;AACpD,EAAA,MAAM,aAAa,MAAA,CAAO,IAAA,CAAK,OAAA,CAAQ,OAAO,EAAE,MAAA,GAAS,CAAA;AACzD,EAAA,MAAM,YAAA,GAAe;AAAA,IACnB,kHAAA;AAAA,IACA;AAAA,GACF;AAEA,EAAA,IAAI,cAAA,EAAgB;AAClB,IAAA,YAAA,CAAa,IAAA;AAAA,MACX;AAAA,KACF;AAAA,EACF;AAEA,EAAA,IAAI,UAAA,EAAY;AACd,IAAA,YAAA,CAAa,IAAA;AAAA,MACX;AAAA,KACF;AAAA,EACF;AAEA,EAAA,IAAI,kBAAkB,UAAA,EAAY;AAChC,IAAA,YAAA,CAAa,IAAA;AAAA,MACX;AAAA,KACF;AAAA,EACF;AAEA,EAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAC/B;AAaO,SAAS,yBACd,OAAA,EACoB;AACpB,EAAA,MAAM,QAA4B,EAAC;AAEnC,EAAA,IAAI,OAAA,CAAQ,WAAA,CAAY,MAAA,GAAS,CAAA,EAAG;AAClC,IAAA,MAAM,gBAAA,GAAmB,CAAC,GAAG,OAAA,CAAQ,WAAW,CAAA;AAChD,IAAA,KAAA,CAAM,IAAA,CAAK;AAAA,MACT,UAAA,EAAY;AAAA,QACV,IAAA,EAAM,UAAA;AAAA,QACN,IAAA,EAAM,wBAAA;AAAA,QACN,WAAA,EAAa,+BAAA;AAAA,QACb,UAAA,EAAY;AAAA,UACV,IAAA,EAAM,QAAA;AAAA,UACN,UAAA,EAAY;AAAA,YACV,YAAA,EAAc;AAAA,cACZ,IAAA,EAAM,QAAA;AAAA,cACN,WAAA,EAAa,iDAAA;AAAA,cACb,IAAA,EAAM;AAAA;AACR,WACF;AAAA,UACA,QAAA,EAAU,CAAC,cAAc;AAAA;AAC3B,OACF;AAAA,MACA,MAAM,QAAQ,IAAA,EAAM;AAClB,QAAA,MAAM,eAAe,IAAA,CAAK,YAAA;AAC1B,QAAA,IACE,OAAO,YAAA,KAAiB,QAAA,IACxB,CAAC,gBAAA,CAAiB,QAAA,CAAS,YAAY,CAAA,EACvC;AACA,UAAA,MAAM,IAAI,KAAA;AAAA,YACR;AAAA,WACF;AAAA,QACF;AAEA,QAAA,OAAO;AAAA,UACL,OAAA,EAAS,IAAA;AAAA,UACT;AAAA,SACF;AAAA,MACF;AAAA,KACD,CAAA;AAAA,EACH;AAEA,EAAA,MAAM,YAAA,GAAe,MAAA,CAAO,IAAA,CAAK,OAAA,CAAQ,OAAO,CAAA;AAChD,EAAA,IAAI,YAAA,CAAa,SAAS,CAAA,EAAG;AAC3B,IAAA,KAAA,CAAM,IAAA,CAAK;AAAA,MACT,UAAA,EAAY;AAAA,QACV,IAAA,EAAM,UAAA;AAAA,QACN,IAAA,EAAM,qBAAA;AAAA,QACN,WAAA,EAAa,4BAAA;AAAA,QACb,UAAA,EAAY;AAAA,UACV,IAAA,EAAM,QAAA;AAAA,UACN,UAAA,EAAY;AAAA,YACV,KAAA,EAAO;AAAA,cACL,IAAA,EAAM,QAAA;AAAA,cACN,WAAA,EAAa,gDAAA;AAAA,cACb,IAAA,EAAM;AAAA,aACR;AAAA,YACA,KAAA,EAAO;AAAA,cACL,IAAA,EAAM,QAAA;AAAA,cACN,WAAA,EACE;AAAA;AACJ,WACF;AAAA,UACA,QAAA,EAAU,CAAC,OAAA,EAAS,OAAO;AAAA;AAC7B,OACF;AAAA,MACA,MAAM,QAAQ,IAAA,EAAM;AAClB,QAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AACnB,QAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AAEnB,QAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,CAAC,YAAA,CAAa,QAAA,CAAS,KAAK,CAAA,EAAG;AAC9D,UAAA,MAAM,IAAI,KAAA;AAAA,YACR;AAAA,WACF;AAAA,QACF;AAEA,QAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA,EAAG;AAC5B,UAAA,MAAM,IAAI,MAAM,wCAAwC,CAAA;AAAA,QAC1D;AAEA,QAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,OAAA,CAAQ,KAAK,CAAA,IAAK,CAAA;AACxC,QAAA,MAAM,WAAA,GAAc,KAAA;AAEpB,QAAA,IAAI,WAAA,GAAc,CAAA,IAAK,WAAA,IAAe,KAAA,EAAO;AAC3C,UAAA,MAAM,IAAI,KAAA;AAAA,YACR,CAAA,iBAAA,EAAoB,MAAA,CAAO,WAAW,CAAC,+BAA+B,KAAK,CAAA,CAAA;AAAA,WAC7E;AAAA,QACF;AAEA,QAAA,OAAO;AAAA,UACL,OAAA,EAAS,IAAA;AAAA,UACT,KAAA;AAAA,UACA,KAAA,EAAO;AAAA,SACT;AAAA,MACF;AAAA,KACD,CAAA;AAAA,EACH;AAEA,EAAA,KAAA,CAAM,IAAA,CAAK;AAAA,IACT,UAAA,EAAY;AAAA,MACV,IAAA,EAAM,UAAA;AAAA,MACN,IAAA,EAAM,iBAAA;AAAA,MACN,WAAA,EAAa,wBAAA;AAAA,MACb,UAAA,EAAY;AAAA,QACV,IAAA,EAAM,QAAA;AAAA,QACN,UAAA,EAAY;AAAA,UACV,CAAA,EAAG;AAAA,YACD,IAAA,EAAM,QAAA;AAAA,YACN,WAAA,EACE;AAAA,WACJ;AAAA,UACA,CAAA,EAAG;AAAA,YACD,IAAA,EAAM,QAAA;AAAA,YACN,WAAA,EACE;AAAA;AACJ,SACF;AAAA,QACA,QAAA,EAAU,CAAC,GAAA,EAAK,GAAG;AAAA;AACrB,KACF;AAAA,IACA,MAAM,QAAQ,IAAA,EAAM;AAClB,MAAA,MAAM,IAAI,IAAA,CAAK,CAAA;AACf,MAAA,MAAM,IAAI,IAAA,CAAK,CAAA;AAEf,MAAA,IAAI,OAAO,CAAA,KAAM,QAAA,IAAY,MAAA,CAAO,KAAA,CAAM,CAAC,CAAA,EAAG;AAC5C,QAAA,MAAM,IAAI,MAAM,+BAA+B,CAAA;AAAA,MACjD;AAEA,MAAA,IAAI,OAAO,CAAA,KAAM,QAAA,IAAY,MAAA,CAAO,KAAA,CAAM,CAAC,CAAA,EAAG;AAC5C,QAAA,MAAM,IAAI,MAAM,+BAA+B,CAAA;AAAA,MACjD;AAEA,MAAA,OAAO;AAAA,QACL,OAAA,EAAS,IAAA;AAAA,QACT,CAAA,EAAG,KAAA,CAAM,CAAA,EAAG,QAAA,EAAU,QAAQ,CAAA;AAAA,QAC9B,CAAA,EAAG,KAAA,CAAM,CAAA,EAAG,QAAA,EAAU,QAAQ;AAAA,OAChC;AAAA,IACF;AAAA,GACD,CAAA;AAED,EAAA,OAAO,KAAA;AACT;AAEO,SAAS,2BAAA,GAAmD;AACjE,EAAA,OAAO,CAAC,EAAE,IAAA,EAAM,MAAA,EAAQ,MAAK,KAAM;AACjC,IAAA,QAAQ,IAAA;AAAM,MACZ,KAAK,wBAAA,EAA0B;AAC7B,QAAA,MAAM,eAAe,MAAA,CAAO,YAAA;AAC5B,QAAA,IAAI,OAAO,iBAAiB,QAAA,EAAU;AACpC,UAAA,IAAA,CAAK,mBAAA,EAAqB,EAAE,YAAA,EAAc,CAAA;AAAA,QAC5C;AACA,QAAA;AAAA,MACF;AAAA,MAEA,KAAK,qBAAA,EAAuB;AAC1B,QAAA,MAAM,QAAQ,MAAA,CAAO,KAAA;AACrB,QAAA,MAAM,QAAQ,MAAA,CAAO,KAAA;AACrB,QAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA,EAAG;AACxD,UAAA,IAAA,CAAK,eAAA,EAAiB,EAAE,KAAA,EAAO,KAAA,EAAwB,CAAA;AAAA,QACzD;AACA,QAAA;AAAA,MACF;AAAA,MAEA,KAAK,iBAAA,EAAmB;AACtB,QAAA,MAAM,MAAA,GAAS,oBAAoB,MAAM,CAAA;AACzC,QAAA,IAAI,MAAA,EAAQ;AACV,UAAA,IAAA,CAAK,eAAe,MAAM,CAAA;AAAA,QAC5B;AAAA,MACF;AAAA;AACF,EACF,CAAA;AACF;AAEA,SAAS,oBACP,MAAA,EACwB;AACxB,EAAA,MAAM,IAAI,MAAA,CAAO,CAAA;AACjB,EAAA,MAAM,IAAI,MAAA,CAAO,CAAA;AAEjB,EAAA,IAAI,OAAO,CAAA,KAAM,QAAA,IAAY,OAAO,MAAM,QAAA,EAAU;AAClD,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,OAAO,EAAE,GAAG,CAAA,EAAE;AAChB;AAEA,SAAS,KAAA,CAAM,KAAA,EAAe,GAAA,EAAa,GAAA,EAAqB;AAC9D,EAAA,OAAO,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,CAAC,CAAA;AAC3C","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"]}
package/dist/index.mjs ADDED
@@ -0,0 +1,202 @@
1
+ // src/index.ts
2
+ var MIN_GAZE = -1;
3
+ var MAX_GAZE = 1;
4
+ var SET_EXPRESSION_TOOL_DESCRIPTION = "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.";
5
+ var PLAY_MOTION_TOOL_DESCRIPTION = "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.";
6
+ var LOOK_AT_TOOL_DESCRIPTION = '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.';
7
+ var SET_EXPRESSION_TOOL_NAME = "setExpression";
8
+ var PLAY_MOTION_TOOL_NAME = "playMotion";
9
+ var LOOK_AT_TOOL_NAME = "lookAt";
10
+ var AVATAR_CONTROL_TOOL_NAMES = [
11
+ SET_EXPRESSION_TOOL_NAME,
12
+ PLAY_MOTION_TOOL_NAME,
13
+ LOOK_AT_TOOL_NAME
14
+ ];
15
+ function buildAvatarControlInstructions(catalog) {
16
+ const hasExpressions = catalog.expressions.length > 0;
17
+ const hasMotions = Object.keys(catalog.motions).length > 0;
18
+ const instructions = [
19
+ "Use avatar tools only when they make the moment feel present. Quiet exchanges can pass without an avatar action.",
20
+ "Use lookAt when your attention shifts or a small gaze reaction is enough."
21
+ ];
22
+ if (hasExpressions) {
23
+ instructions.push(
24
+ "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
+ );
26
+ }
27
+ if (hasMotions) {
28
+ instructions.push(
29
+ "Use playMotion for bigger beats such as greetings, emphasis, or strong reactions. Don't stack body motions in one reply."
30
+ );
31
+ }
32
+ if (hasExpressions && hasMotions) {
33
+ instructions.push(
34
+ "Richer beats can combine two avatar actions, such as setExpression plus playMotion, when both earn their place."
35
+ );
36
+ }
37
+ return instructions.join("\n");
38
+ }
39
+ function createAvatarControlTools(catalog) {
40
+ const tools = [];
41
+ if (catalog.expressions.length > 0) {
42
+ const expressionValues = [...catalog.expressions];
43
+ tools.push({
44
+ definition: {
45
+ type: "function",
46
+ name: SET_EXPRESSION_TOOL_NAME,
47
+ description: SET_EXPRESSION_TOOL_DESCRIPTION,
48
+ parameters: {
49
+ type: "object",
50
+ properties: {
51
+ expressionId: {
52
+ type: "string",
53
+ description: "Expression ID available for your current model.",
54
+ enum: expressionValues
55
+ }
56
+ },
57
+ required: ["expressionId"]
58
+ }
59
+ },
60
+ async handler(args) {
61
+ const expressionId = args.expressionId;
62
+ if (typeof expressionId !== "string" || !expressionValues.includes(expressionId)) {
63
+ throw new Error(
64
+ 'setExpression requires a valid "expressionId" from the model catalog'
65
+ );
66
+ }
67
+ return {
68
+ success: true,
69
+ expressionId
70
+ };
71
+ }
72
+ });
73
+ }
74
+ const motionGroups = Object.keys(catalog.motions);
75
+ if (motionGroups.length > 0) {
76
+ tools.push({
77
+ definition: {
78
+ type: "function",
79
+ name: PLAY_MOTION_TOOL_NAME,
80
+ description: PLAY_MOTION_TOOL_DESCRIPTION,
81
+ parameters: {
82
+ type: "object",
83
+ properties: {
84
+ group: {
85
+ type: "string",
86
+ description: "Motion group available for your current model.",
87
+ enum: motionGroups
88
+ },
89
+ index: {
90
+ type: "number",
91
+ description: "Zero-based motion index within the selected motion group."
92
+ }
93
+ },
94
+ required: ["group", "index"]
95
+ }
96
+ },
97
+ async handler(args) {
98
+ const group = args.group;
99
+ const index = args.index;
100
+ if (typeof group !== "string" || !motionGroups.includes(group)) {
101
+ throw new Error(
102
+ 'playMotion requires a valid "group" from the model catalog'
103
+ );
104
+ }
105
+ if (!Number.isInteger(index)) {
106
+ throw new Error('playMotion requires an integer "index"');
107
+ }
108
+ const count = catalog.motions[group] ?? 0;
109
+ const motionIndex = index;
110
+ if (motionIndex < 0 || motionIndex >= count) {
111
+ throw new Error(
112
+ `playMotion index ${String(motionIndex)} is out of range for group "${group}"`
113
+ );
114
+ }
115
+ return {
116
+ success: true,
117
+ group,
118
+ index: motionIndex
119
+ };
120
+ }
121
+ });
122
+ }
123
+ tools.push({
124
+ definition: {
125
+ type: "function",
126
+ name: LOOK_AT_TOOL_NAME,
127
+ description: LOOK_AT_TOOL_DESCRIPTION,
128
+ parameters: {
129
+ type: "object",
130
+ properties: {
131
+ x: {
132
+ type: "number",
133
+ description: "Normalized horizontal gaze target. -1 looks left, 0 is center, 1 looks right."
134
+ },
135
+ y: {
136
+ type: "number",
137
+ description: "Normalized vertical gaze target. -1 looks down, 0 is center, 1 looks up."
138
+ }
139
+ },
140
+ required: ["x", "y"]
141
+ }
142
+ },
143
+ async handler(args) {
144
+ const x = args.x;
145
+ const y = args.y;
146
+ if (typeof x !== "number" || Number.isNaN(x)) {
147
+ throw new Error('lookAt requires a numeric "x"');
148
+ }
149
+ if (typeof y !== "number" || Number.isNaN(y)) {
150
+ throw new Error('lookAt requires a numeric "y"');
151
+ }
152
+ return {
153
+ success: true,
154
+ x: clamp(x, MIN_GAZE, MAX_GAZE),
155
+ y: clamp(y, MIN_GAZE, MAX_GAZE)
156
+ };
157
+ }
158
+ });
159
+ return tools;
160
+ }
161
+ function createAvatarResultProjector() {
162
+ return ({ name, output, emit }) => {
163
+ switch (name) {
164
+ case SET_EXPRESSION_TOOL_NAME: {
165
+ const expressionId = output.expressionId;
166
+ if (typeof expressionId === "string") {
167
+ emit("avatar:expression", { expressionId });
168
+ }
169
+ return;
170
+ }
171
+ case PLAY_MOTION_TOOL_NAME: {
172
+ const group = output.group;
173
+ const index = output.index;
174
+ if (typeof group === "string" && Number.isInteger(index)) {
175
+ emit("avatar:motion", { group, index });
176
+ }
177
+ return;
178
+ }
179
+ case LOOK_AT_TOOL_NAME: {
180
+ const coords = readGazeCoordinates(output);
181
+ if (coords) {
182
+ emit("avatar:gaze", coords);
183
+ }
184
+ }
185
+ }
186
+ };
187
+ }
188
+ function readGazeCoordinates(output) {
189
+ const x = output.x;
190
+ const y = output.y;
191
+ if (typeof x !== "number" || typeof y !== "number") {
192
+ return null;
193
+ }
194
+ return { x, y };
195
+ }
196
+ function clamp(value, min, max) {
197
+ return Math.max(min, Math.min(max, value));
198
+ }
199
+
200
+ export { AVATAR_CONTROL_TOOL_NAMES, LOOK_AT_TOOL_NAME, PLAY_MOTION_TOOL_NAME, SET_EXPRESSION_TOOL_NAME, buildAvatarControlInstructions, createAvatarControlTools, createAvatarResultProjector };
201
+ //# sourceMappingURL=index.mjs.map
202
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +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"]}
package/package.json ADDED
@@ -0,0 +1,48 @@
1
+ {
2
+ "name": "@charivo/avatar",
3
+ "version": "0.2.0",
4
+ "description": "Avatar control tools for Charivo LLM and realtime sessions",
5
+ "main": "dist/index.js",
6
+ "module": "dist/index.mjs",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.mjs",
12
+ "require": "./dist/index.js"
13
+ }
14
+ },
15
+ "dependencies": {
16
+ "@charivo/core": "0.17.0"
17
+ },
18
+ "devDependencies": {
19
+ "tsup": "^8.5.0",
20
+ "typescript": "^5.9.2"
21
+ },
22
+ "files": [
23
+ "dist"
24
+ ],
25
+ "publishConfig": {
26
+ "access": "public"
27
+ },
28
+ "license": "MIT",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "https://github.com/zeikar/charivo.git",
32
+ "directory": "packages/avatar"
33
+ },
34
+ "author": {
35
+ "name": "Zeikar",
36
+ "url": "https://github.com/zeikar"
37
+ },
38
+ "homepage": "https://github.com/zeikar/charivo#readme",
39
+ "bugs": {
40
+ "url": "https://github.com/zeikar/charivo/issues"
41
+ },
42
+ "scripts": {
43
+ "build": "tsup",
44
+ "dev": "tsup --watch",
45
+ "clean": "rm -rf dist",
46
+ "typecheck": "tsc --noEmit"
47
+ }
48
+ }