@charivo/core 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,15 +1,15 @@
1
1
  # @charivo/core
2
2
 
3
- Core types, interfaces, and event bus for the Charivo framework.
3
+ `@charivo/core` is the contract layer for the Charivo workspace.
4
4
 
5
- ## Features
5
+ It exports:
6
6
 
7
- - 🎯 **Core Types** - Shared types for messages, characters, and configuration
8
- - 🔌 **Interface Definitions** - Standard interfaces for LLM, TTS, and Renderer
9
- - 📡 **Event Bus** - Type-safe event system for component communication
10
- - 🎨 **Extensible** - Build custom clients, players, and providers
7
+ - `Charivo`: the top-level orchestrator
8
+ - shared domain types such as `Character`, `Message`, and `Emotion`
9
+ - interface contracts for LLM, render, TTS, STT, and realtime managers
10
+ - the typed `EventBus`
11
11
 
12
- ## Installation
12
+ ## Install
13
13
 
14
14
  ```bash
15
15
  pnpm add @charivo/core
@@ -17,275 +17,65 @@ pnpm add @charivo/core
17
17
 
18
18
  ## Usage
19
19
 
20
- ### Basic Setup
20
+ ```ts
21
+ import { Charivo, Emotion } from "@charivo/core";
21
22
 
22
- ```typescript
23
- import { Charivo } from "@charivo/core";
24
- import { createLLMManager } from "@charivo/llm-core";
25
- import { createTTSManager } from "@charivo/tts-core";
26
- import { createRenderManager } from "@charivo/render-core";
27
- import { OpenAILLMClient } from "@charivo/llm-client-openai";
28
- import { OpenAITTSPlayer } from "@charivo/tts-player-openai";
29
- import { Live2DRenderer } from "@charivo/render-live2d";
30
-
31
- // Initialize Charivo
32
23
  const charivo = new Charivo();
33
24
 
34
- // Setup LLM
35
- const llmClient = new OpenAILLMClient({ apiKey: "your-api-key" });
36
- const llmManager = createLLMManager(llmClient);
37
- charivo.attachLLM(llmManager);
38
-
39
- // Setup TTS
40
- const ttsPlayer = new OpenAITTSPlayer({ apiKey: "your-api-key" });
41
- const ttsManager = createTTSManager(ttsPlayer);
42
- charivo.attachTTS(ttsManager);
43
-
44
- // Disable TTS (optional)
45
- // charivo.detachTTS();
46
-
47
- // Setup Renderer
48
- const renderer = new Live2DRenderer({ canvas });
49
- await renderer.initialize();
50
- await renderer.loadModel("/live2d/model.model3.json");
51
- const renderManager = createRenderManager(renderer);
52
- charivo.attachRenderer(renderManager);
53
-
54
- // Set character
55
25
  charivo.setCharacter({
56
26
  id: "hiyori",
57
27
  name: "Hiyori",
58
- personality: "Cheerful and helpful AI assistant"
28
+ personality: "Cheerful and helpful assistant",
29
+ emotionMappings: [
30
+ {
31
+ emotion: Emotion.HAPPY,
32
+ expression: "f02",
33
+ motion: { group: "TapBody", index: 0 },
34
+ },
35
+ ],
59
36
  });
60
37
 
61
- // Start chatting
62
- await charivo.userSay("Hello!");
63
- ```
64
-
65
- ### API Reference
66
-
67
- #### Charivo Methods
68
-
69
- - `attachLLM(manager: LLMManager): void` - Attach an LLM manager for conversation
70
- - `attachTTS(manager: TTSManager): void` - Attach a TTS manager for voice synthesis
71
- - `detachTTS(): void` - Detach the TTS manager to disable voice synthesis
72
- - `attachRenderer(manager: RenderManager): void` - Attach a renderer for visual output
73
- - `setCharacter(character: Character): void` - Set the character configuration
74
- - `userSay(message: string): Promise<void>` - Send a user message and get a response
75
-
76
- ### Event Bus
77
-
78
- ```typescript
79
- import { EventBus } from "@charivo/core";
80
-
81
- const eventBus = new EventBus();
82
-
83
- // Subscribe to events
84
- eventBus.on("tts:audio:start", (data) => {
85
- console.log("TTS started", data.audioElement);
38
+ charivo.on("message:received", ({ message }) => {
39
+ console.log(message.content);
86
40
  });
87
-
88
- eventBus.on("tts:audio:end", () => {
89
- console.log("TTS ended");
90
- });
91
-
92
- // Emit events
93
- eventBus.emit("tts:audio:start", { audioElement });
94
- eventBus.emit("tts:audio:end", {});
95
- ```
96
-
97
- ## Core Types
98
-
99
- ### Character
100
-
101
- ```typescript
102
- interface Character {
103
- id: string;
104
- name: string;
105
- personality: string;
106
- traits?: string[];
107
- background?: string;
108
- instructions?: string[];
109
- }
110
- ```
111
-
112
- ### Message
113
-
114
- ```typescript
115
- interface Message {
116
- id: string;
117
- content: string;
118
- timestamp: Date;
119
- type: "user" | "character" | "system";
120
- }
121
- ```
122
-
123
- ### MotionType
124
-
125
- ```typescript
126
- type MotionType = "greeting" | "happy" | "thinking" | "talk";
127
- ```
128
-
129
- ## Core Interfaces
130
-
131
- ### LLMManager
132
-
133
- ```typescript
134
- interface LLMManager {
135
- setCharacter(character: Character): void;
136
- getCharacter(): Character | null;
137
- clearHistory(): void;
138
- getHistory(): Message[];
139
- generateResponse(message: Message): Promise<string>;
140
- }
141
- ```
142
-
143
- ### TTSManager
144
-
145
- ```typescript
146
- interface TTSManager {
147
- speak(text: string, options?: TTSOptions): Promise<void>;
148
- stop(): Promise<void>;
149
- setVoice(voice: string): void;
150
- isSupported(): boolean;
151
- setEventEmitter?(eventEmitter: {
152
- emit: (event: string, data: any) => void;
153
- }): void;
154
- }
155
41
  ```
156
42
 
157
- ### RenderManager
43
+ ## `Charivo`
158
44
 
159
- ```typescript
160
- interface RenderManager {
161
- initialize(): Promise<void>;
162
- render(message: Message, character?: Character): Promise<void>;
163
- setCharacter(character: Character): void;
164
- destroy(): Promise<void>;
165
- loadModel?(modelPath: string): Promise<void>;
166
- setMessageCallback?(callback: MessageCallback): void;
167
- }
168
- ```
169
-
170
- ### Renderer
171
-
172
- ```typescript
173
- interface Renderer {
174
- initialize(): Promise<void>;
175
- render(message: Message, character?: Character): Promise<void>;
176
- destroy(): Promise<void>;
177
- loadModel?(modelPath: string): Promise<void>;
178
- playMotion?(motionType: MotionType): void;
179
- animateExpression?(motionType: MotionType): void;
180
- setRealtimeLipSync?(enabled: boolean): void;
181
- updateRealtimeLipSyncRms?(rms: number): void;
182
- }
183
- ```
184
-
185
- ## Architecture
186
-
187
- The Charivo framework follows a modular architecture:
188
-
189
- ```
190
- Charivo (orchestrator)
191
- ├─ LLMManager (stateful)
192
- │ └─ LLMClient (stateless)
193
- │
194
- ├─ TTSManager (stateful)
195
- │ └─ TTSPlayer (stateless)
196
- │
197
- └─ RenderManager (stateful)
198
- └─ Renderer (stateless)
199
- ```
200
-
201
- ### Manager Pattern
202
-
203
- - **Managers**: Stateful components that handle business logic, state management, and coordination
204
- - **Clients/Players/Renderers**: Stateless components that handle pure operations (API calls, audio playback, rendering)
205
-
206
- This separation allows:
207
- - Easy testing (mock the stateless components)
208
- - Flexibility (swap implementations without changing business logic)
209
- - Reusability (use clients independently or with managers)
210
-
211
- ## Creating Custom Implementations
212
-
213
- ### Custom LLM Client
214
-
215
- ```typescript
216
- import { LLMClient } from "@charivo/core";
217
-
218
- class MyLLMClient implements LLMClient {
219
- async call(messages: Array<{role: string, content: string}>): Promise<string> {
220
- // Call your LLM API
221
- return "Response from my LLM";
222
- }
223
- }
224
- ```
45
+ The `Charivo` instance wires managers together:
225
46
 
226
- ### Custom TTS Player
47
+ - `attachRenderer(renderManager)`
48
+ - `attachLLM(llmManager)`
49
+ - `attachTTS(ttsManager)`
50
+ - `attachSTT(sttManager)`
51
+ - `attachRealtime(realtimeManager)`
52
+ - `setCharacter(character)`
53
+ - `userSay(text)`
54
+ - `clearHistory()`
55
+ - `getHistory()`
56
+ - `on(event, listener)`
57
+ - `off(event, listener)`
227
58
 
228
- ```typescript
229
- import { TTSPlayer, TTSOptions } from "@charivo/core";
230
-
231
- class MyTTSPlayer implements TTSPlayer {
232
- async speak(text: string, options?: TTSOptions): Promise<void> {
233
- // Play audio
234
- }
235
-
236
- async stop(): Promise<void> {
237
- // Stop playback
238
- }
239
-
240
- setVoice(voice: string): void {
241
- // Set voice
242
- }
243
-
244
- isSupported(): boolean {
245
- return true;
246
- }
247
- }
248
- ```
249
-
250
- ### Custom Renderer
251
-
252
- ```typescript
253
- import { Renderer, Message, Character, MotionType } from "@charivo/core";
254
-
255
- class MyRenderer implements Renderer {
256
- async initialize(): Promise<void> {
257
- // Setup renderer
258
- }
259
-
260
- async render(message: Message, character?: Character): Promise<void> {
261
- // Render the message
262
- }
263
-
264
- async destroy(): Promise<void> {
265
- // Cleanup
266
- }
267
-
268
- // Optional methods
269
- playMotion?(motionType: MotionType): void {
270
- // Play motion
271
- }
272
- }
273
- ```
59
+ The current render-manager contract is explicit: a `RenderManager` must expose
60
+ `setEventBus(eventBus)` so the core can connect typed character, TTS, and
61
+ realtime events without duck typing.
274
62
 
275
63
  ## Events
276
64
 
277
- ### TTS Events
278
-
279
- - `tts:audio:start` - Emitted when TTS starts playing
280
- ```typescript
281
- { audioElement: HTMLAudioElement }
282
- ```
283
-
284
- - `tts:audio:end` - Emitted when TTS stops playing
285
- ```typescript
286
- {}
287
- ```
288
-
289
- ## License
290
-
291
- MIT
65
+ Important event names include:
66
+
67
+ - `message:sent`
68
+ - `message:received`
69
+ - `character:speak`
70
+ - `tts:start`
71
+ - `tts:end`
72
+ - `tts:error`
73
+ - `tts:audio:start`
74
+ - `tts:audio:end`
75
+ - `tts:lipsync:update`
76
+ - `stt:start`
77
+ - `stt:stop`
78
+ - `stt:error`
79
+ - `realtime:emotion`
80
+ - `realtime:text:delta`
81
+ - `realtime:error`
package/dist/index.cjs CHANGED
@@ -2,30 +2,29 @@
2
2
 
3
3
  // src/bus.ts
4
4
  var EventBus = class {
5
- listeners = /* @__PURE__ */ new Map();
5
+ listeners = {};
6
6
  on(event, listener) {
7
- if (!this.listeners.has(event)) {
8
- this.listeners.set(event, []);
9
- }
10
- this.listeners.get(event).push(listener);
7
+ this.listeners[event] ??= [];
8
+ this.listeners[event].push(listener);
11
9
  }
12
10
  emit(event, data) {
13
- const eventListeners = this.listeners.get(event);
14
- if (eventListeners) {
15
- eventListeners.forEach((listener) => listener(data));
16
- }
11
+ this.listeners[event]?.forEach((listener) => listener(data));
17
12
  }
18
13
  off(event, listener) {
19
- const eventListeners = this.listeners.get(event);
20
- if (eventListeners) {
21
- const index = eventListeners.indexOf(listener);
22
- if (index > -1) {
23
- eventListeners.splice(index, 1);
24
- }
14
+ const eventListeners = this.listeners[event];
15
+ if (!eventListeners) {
16
+ return;
17
+ }
18
+ const index = eventListeners.indexOf(listener);
19
+ if (index > -1) {
20
+ eventListeners.splice(index, 1);
21
+ }
22
+ if (eventListeners.length === 0) {
23
+ delete this.listeners[event];
25
24
  }
26
25
  }
27
26
  clear() {
28
- this.listeners.clear();
27
+ this.listeners = {};
29
28
  }
30
29
  };
31
30
 
@@ -44,6 +43,7 @@ var Emotion = /* @__PURE__ */ ((Emotion2) => {
44
43
 
45
44
  // src/emotion-parser.ts
46
45
  var EMOTION_TAG_REGEX = /\[([a-zA-Z]+)\]/g;
46
+ var EMOTION_TAG_TEST_REGEX = /\[([a-zA-Z]+)\]/;
47
47
  var EMOTION_KEYWORD_MAP = {
48
48
  // Neutral
49
49
  neutral: "neutral" /* NEUTRAL */,
@@ -97,22 +97,17 @@ function parseEmotion(text) {
97
97
  const emotion = EMOTION_KEYWORD_MAP[keyword];
98
98
  if (emotion) {
99
99
  detectedEmotion = emotion;
100
- } else {
101
- console.warn(`\u26A0\uFE0F [Emotion] Unknown keyword: [${match[1]}]`);
102
100
  }
103
101
  cleanedText = cleanedText.replace(match[0], "");
104
102
  }
105
103
  cleanedText = cleanedText.replace(/\s+/g, " ").trim();
106
- if (detectedEmotion) {
107
- console.log(`\u{1F3AD} [Emotion] ${detectedEmotion} \u2192 "${cleanedText}"`);
108
- }
109
104
  return {
110
105
  text: cleanedText,
111
106
  emotion: detectedEmotion
112
107
  };
113
108
  }
114
109
  function hasEmotionTag(text) {
115
- return EMOTION_TAG_REGEX.test(text);
110
+ return EMOTION_TAG_TEST_REGEX.test(text);
116
111
  }
117
112
  function getSupportedEmotionKeywords() {
118
113
  return Object.keys(EMOTION_KEYWORD_MAP);
@@ -124,7 +119,10 @@ var Charivo = class {
124
119
  llmManager;
125
120
  renderManager;
126
121
  ttsManager;
122
+ sttManager;
123
+ realtimeManager;
127
124
  character;
125
+ isRealtimeMode = false;
128
126
  constructor() {
129
127
  this.eventBus = new EventBus();
130
128
  }
@@ -133,10 +131,6 @@ var Charivo = class {
133
131
  * Automatically connects the event bus and sets the current character if available.
134
132
  */
135
133
  attachRenderer(renderManager) {
136
- console.log(
137
- "\u{1F3AD} Charivo: Attaching render manager",
138
- renderManager.constructor.name
139
- );
140
134
  this.renderManager = renderManager;
141
135
  this.connectRenderManagerEventBus(renderManager);
142
136
  if (this.character) {
@@ -147,35 +141,7 @@ var Charivo = class {
147
141
  * Connects the render manager to the event bus for bidirectional communication.
148
142
  */
149
143
  connectRenderManagerEventBus(renderManager) {
150
- if ("setEventBus" in renderManager && typeof renderManager.setEventBus === "function") {
151
- console.log(
152
- "\u{1F517} Charivo: \u2705 Render manager supports event bus - connecting"
153
- );
154
- renderManager.setEventBus({
155
- on: (event, callback) => {
156
- console.log(
157
- `\u{1F517} Charivo: Render manager subscribing to event: ${event}`
158
- );
159
- this.eventBus.on(event, callback);
160
- },
161
- emit: (event, data) => {
162
- console.log(
163
- `\u{1F517} Charivo: Render manager emitting event: ${event}`,
164
- data
165
- );
166
- this.eventBus.emit(event, data);
167
- }
168
- });
169
- console.log("\u{1F517} Charivo: Event bus connection completed");
170
- } else {
171
- console.warn(
172
- "\u26A0\uFE0F Charivo: Render manager doesn't support event bus connection",
173
- {
174
- hasSetEventBus: "setEventBus" in renderManager,
175
- setEventBusType: typeof renderManager.setEventBus
176
- }
177
- );
178
- }
144
+ renderManager.setEventBus(this.eventBus);
179
145
  }
180
146
  /**
181
147
  * Attach an LLM manager to handle conversation generation.
@@ -192,7 +158,6 @@ var Charivo = class {
192
158
  * Automatically connects the event emitter for audio events.
193
159
  */
194
160
  attachTTS(manager) {
195
- console.log("\u{1F50A} Charivo: Attaching TTS manager", manager.constructor.name);
196
161
  this.ttsManager = manager;
197
162
  this.connectTTSManagerEventEmitter(manager);
198
163
  }
@@ -200,29 +165,36 @@ var Charivo = class {
200
165
  * Detach the TTS manager to disable voice synthesis.
201
166
  */
202
167
  detachTTS() {
203
- console.log("\u{1F507} Charivo: Detaching TTS manager");
204
168
  this.ttsManager = void 0;
205
169
  }
170
+ /**
171
+ * Attach an STT manager to handle speech recognition.
172
+ * Automatically connects the event emitter for STT events.
173
+ */
174
+ attachSTT(manager) {
175
+ this.sttManager = manager;
176
+ this.connectSTTManagerEventEmitter(manager);
177
+ }
178
+ /**
179
+ * Detach the STT manager to disable speech recognition.
180
+ */
181
+ detachSTT() {
182
+ this.sttManager = void 0;
183
+ }
206
184
  /**
207
185
  * Connects the TTS manager to the event bus for audio event emission.
208
186
  */
209
187
  connectTTSManagerEventEmitter(manager) {
210
188
  if (manager.setEventEmitter) {
211
- console.log(
212
- "\u{1F517} Charivo: \u2705 TTS manager supports event emitter - connecting"
213
- );
214
- manager.setEventEmitter({
215
- emit: (event, data) => {
216
- console.log(`\u{1F3B5} Charivo: \u2705 TTS EMITTING EVENT: ${event}`, data);
217
- this.eventBus.emit(event, data);
218
- console.log(`\u{1F3B5} Charivo: \u2705 Event ${event} emitted to event bus`);
219
- }
220
- });
221
- console.log("\u{1F517} Charivo: TTS Manager connection completed");
222
- } else {
223
- console.warn("\u26A0\uFE0F Charivo: TTS manager doesn't support event emitter", {
224
- managerType: manager.constructor.name
225
- });
189
+ manager.setEventEmitter(this.eventBus);
190
+ }
191
+ }
192
+ /**
193
+ * Connects the STT manager to the event bus for speech recognition event emission.
194
+ */
195
+ connectSTTManagerEventEmitter(manager) {
196
+ if (manager.setEventEmitter) {
197
+ manager.setEventEmitter(this.eventBus);
226
198
  }
227
199
  }
228
200
  /**
@@ -314,12 +286,60 @@ var Charivo = class {
314
286
  getCurrentCharacter() {
315
287
  return this.character ?? null;
316
288
  }
289
+ /**
290
+ * Get the current STT manager instance.
291
+ */
292
+ getSTTManager() {
293
+ return this.sttManager;
294
+ }
295
+ /**
296
+ * Attach a Realtime manager to handle real-time conversation.
297
+ * Automatically connects the event emitter and enables Realtime mode.
298
+ */
299
+ attachRealtime(manager) {
300
+ this.realtimeManager = manager;
301
+ this.isRealtimeMode = true;
302
+ this.connectRealtimeManagerEventEmitter(manager);
303
+ }
304
+ /**
305
+ * Detach the Realtime manager and disable Realtime mode.
306
+ */
307
+ detachRealtime() {
308
+ this.realtimeManager = void 0;
309
+ this.isRealtimeMode = false;
310
+ }
311
+ /**
312
+ * Check if Realtime mode is enabled.
313
+ */
314
+ isRealtimeModeEnabled() {
315
+ return this.isRealtimeMode;
316
+ }
317
+ /**
318
+ * Connects the Realtime manager to the event bus.
319
+ */
320
+ connectRealtimeManagerEventEmitter(manager) {
321
+ if (manager.setEventEmitter) {
322
+ manager.setEventEmitter(this.eventBus);
323
+ }
324
+ }
325
+ /**
326
+ * Get the current Realtime manager instance.
327
+ */
328
+ getRealtimeManager() {
329
+ return this.realtimeManager;
330
+ }
317
331
  /**
318
332
  * Subscribe to events from the event bus.
319
333
  */
320
334
  on(event, listener) {
321
335
  this.eventBus.on(event, listener);
322
336
  }
337
+ /**
338
+ * Unsubscribe from events from the event bus.
339
+ */
340
+ off(event, listener) {
341
+ this.eventBus.off(event, listener);
342
+ }
323
343
  /**
324
344
  * Emit events to the event bus.
325
345
  */