felona-voice 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,36 @@
+MIT License with Attribution Requirement
+
+Copyright (c) 2026 Mohit & Felona Voice Contributors (https://github.com/felona-voice/felona-voice)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+2. ATTRIBUTION REQUIREMENT:
+   Any product, application, service, website, software, documentation, or marketing
+   material that uses, incorporates, embeds, or is derived from this Software must
+   prominently display visible attribution to the author.
+   
+   The attribution must clearly display:
+   "Powered by Felona Voice" or "Built with Felona Voice"
+   accompanied by an active, clickable hyperlink back to the official repository:
+   https://github.com/felona-voice/felona-voice
+   
+   This credit must be visible in at least one of the following locations:
+   - The user interface of the product/application (e.g., footer, about dialog, or settings screen)
+   - The official public documentation or README of the product/service
+   - The marketing website or public landing page of the offering
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/felona-voice/felona-voice/main/public/logo.png" alt="Felona Voice" width="280" />
+</p>
+
+<p align="center">
+  <strong>Sub-10ms Voice Agent Framework powered by Joint Embedding Vectors (JEV)</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/felona-voice"><img src="https://img.shields.io/npm/v/felona-voice.svg?style=flat-square&color=3b82f6" alt="npm version" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-emerald.svg?style=flat-square" alt="License: MIT" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.5-blue.svg?style=flat-square" alt="TypeScript" /></a>
+</p>
+
+**Open-source, ultra-low-latency voice agent framework powered by JEV (Joint Embedding Vectors) with stateful conversational graphs.**
+
+## Installation
+
+```bash
+npm install felona-voice
+```
+
+## Quick Start
+
+```typescript
+import { createAgent } from "felona-voice";
+
+const agent = createAgent("Concierge")
+  .system("You are a friendly concierge.")
+  .action("book_table", "Book a dining table or restaurant reservation", async () => "Table booked for 7 PM!")
+  .action("room_service", "Order food or fresh towels", async () => "Room service is on its way.")
+  .fallback("Sorry, I am not able to understand that. How can I assist you?");
+
+// Test instantly without spinning up a server (zero external API keys required!):
+const reply = await agent.interact("can I get clean towels?");
+console.log(reply.text); // "Room service is on its way."
+console.log(reply.action.id); // "room_service"
+```
+
+## Features
+
+- **JEV Routing**: Sub-10ms neural intent routing via local fast semantic embeddings or OpenAI embeddings.
+- **Pure JavaScript Execution**: Deterministic responses without LLM latency, token cost, or hallucinations.
+- **Pluggable Audio Stack**:
+  - **STT**: Deepgram Nova-2, OpenAI Whisper, AssemblyAI, Azure Speech, Google Cloud Speech.
+  - **TTS**: Cartesia Sonic (<100ms), Deepgram Aura, ElevenLabs, OpenAI Speech, Azure Speech, Amazon Polly, LMNT.
+  - **VAD**: Zero-dependency energy-based speech boundary detection.
+- **Stateful Conversational Graphs**: `VoiceGraph` with `.addNode()`, `.addEdge()`, `.compile()`, and `.invoke()`.
+- **Markdown & Mermaid Visualization**: Automatic generation of architectural diagrams and transition tables.
+
+## Documentation & Repository
+
+For complete documentation, guides, and architectural overviews:
+👉 [https://github.com/felona-voice/felona-voice](https://github.com/felona-voice/felona-voice#readme)
+
+## License & Attribution
+
+MIT License with Attribution Requirement. See [LICENSE](./LICENSE) for details.
+Any product or service powered by Felona Voice must display "Powered by Felona Voice" linking to https://github.com/felona-voice/felona-voice.
+
+© 2026 Mohit & Felona Voice Contributors

package/dist/agent.d.ts

@@ -1,6 +1,8 @@
 import { EventEmitter } from "node:events";
-import type { FelAgentConfig, AgentAction } from "./types.js";
+import type { FelAgentConfig, AgentAction, InteractOptions, InteractResult } from "./types.js";
 import { JEVEngine } from "./jev/engine.js";
+import { ConversationMemory } from "./memory/context.js";
+import { type GraphData, type VisualizeOptions, type VisualizeResult } from "./graph/visualize.js";
 /**
  * FelAgent — The main entry point for building a voice agent with Felona Voice.
  *
@@ -9,20 +11,15 @@ import { JEVEngine } from "./jev/engine.js";
  * const agent = new FelAgent({
  *   name: "Support Bot",
  *   systemPrompt: "You are a helpful support agent.",
- *   stt: { provider: "deepgram", apiKey: "..." },
- *   tts: { provider: "elevenlabs", apiKey: "..." },
- *   llm: { provider: "openai", apiKey: "...", model: "gpt-4o-mini" },
  *   actions: [ ... ],
  * });
  *
+ * // Directly interact (text/simulation):
+ * const reply = await agent.interact("where is my order?");
+ *
+ * // Or listen on WebSocket for live audio calls:
  * agent.listen({ port: 8080 });
  * ```
- *
- * FelAgent wires together:
- * - Transport (WebSocket server for audio I/O)
- * - Voice Pipeline (STT → JEV → LLM → TTS per session)
- * - JEV Engine (action prediction)
- * - Memory, Tools, Analytics
  */
 export declare class FelAgent extends EventEmitter {
     private readonly config;
@@ -34,9 +31,8 @@ export declare class FelAgent extends EventEmitter {
     private readonly sttProvider;
     private readonly ttsProvider;
     private readonly vadProvider;
-    private readonly llmProvider;
-    private readonly llmInterface;
     private pipelines;
+    private sessionMap;
     private initialized;
     constructor(config: FelAgentConfig);
     /**
@@ -66,8 +62,26 @@ export declare class FelAgent extends EventEmitter {
     private createSTTProvider;
     /** Create TTS provider based on config */
     private createTTSProvider;
-    /** Create LLM provider based on config */
-    private createLLMProvider;
+    /**
+     * Directly interact with the agent (simulate a single turn without WebSocket audio).
+     *
+     * Perfect for unit testing, HTTP/REST API endpoints, Next.js server actions,
+     * CLI tools, or text-based debugging.
+     *
+     * @example
+     * ```typescript
+     * const reply = await agent.interact("where is my order?");
+     * console.log(reply.text);
+     * console.log(reply.action.id);
+     * ```
+     */
+    interact(input: string | InteractOptions): Promise<InteractResult>;
+    /**
+     * Run a multi-turn conversation simulation.
+     */
+    simulate(turns: string[], sessionId?: string): Promise<InteractResult[]>;
+    /** Access default conversation memory manager */
+    get memory(): ConversationMemory;
     /** Get the number of active calls */
     get activeCallCount(): number;
     /** Check if the agent is running */
@@ -76,6 +90,34 @@ export declare class FelAgent extends EventEmitter {
     get name(): string;
     /** Get the JEV engine (for inspection/testing) */
     get jevEngine(): JEVEngine;
+    /**
+     * Get graph data representing the agent's action space.
+     */
+    getGraph(): GraphData;
+    /**
+     * Render an ASCII diagram of the agent's actions in the terminal.
+     */
+    drawAscii(options?: {
+        title?: string;
+    }): string;
+    /**
+     * Export the agent's action space as a Mermaid flowchart.
+     */
+    drawMermaid(): string;
+    /**
+     * Export the agent's action space as Markdown documentation.
+     */
+    drawMarkdown(options?: {
+        title?: string;
+    }): string;
+    /**
+     * Get a direct link to view the diagram in Mermaid Live Editor.
+     */
+    toMermaidLiveUrl(): string;
+    /**
+     * Visualize the agent in terminal (ASCII), Mermaid, or launch the interactive HTML visualizer.
+     */
+    visualize(options?: VisualizeOptions): Promise<VisualizeResult>;
 }
 /**
  * Helper to define an action with type safety.
@@ -83,23 +125,19 @@ export declare class FelAgent extends EventEmitter {
 export declare function defineAction(action: AgentAction): AgentAction;
 /**
  * Quick-start factory — creates a minimal agent with sensible defaults.
- * Automatically creates a default "respond" action that uses the LLM directly.
  */
-export declare function quickStart(config: {
-    llm: {
-        provider: string;
-        apiKey: string;
-        model?: string;
-    };
-    stt: {
+export declare function quickStart(config?: {
+    name?: string;
+    stt?: {
         provider: string;
         apiKey: string;
     };
-    tts: {
+    tts?: {
         provider: string;
         apiKey: string;
         voice?: string;
     };
     systemPrompt?: string;
+    onRespond?: (utterance: string) => Promise<string> | string;
 }): FelAgent;
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,cAAc,EAGd,WAAW,EAGZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAa5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAY;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAY;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAG5C,OAAO,CAAC,SAAS,CAAyC;IAE1D,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,cAAc;IA4ClC;;OAEG;IACG,MAAM,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CvE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B;;OAEG;YACW,aAAa;IA2C3B;;OAEG;YACW,gBAAgB;IAY9B;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB,0CAA0C;IAC1C,OAAO,CAAC,iBAAiB;IAiBzB,0CAA0C;IAC1C,OAAO,CAAC,iBAAiB;IAkBzB,0CAA0C;IAC1C,OAAO,CAAC,iBAAiB;IAiBzB,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,oCAAoC;IACpC,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,yBAAyB;IACzB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,kDAAkD;IAClD,IAAI,SAAS,IAAI,SAAS,CAEzB;CACF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAE7D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE;IACjC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,QAAQ,CAgCX"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}