@sdkrouter/aisphere

Audio-reactive 3D liquid orb + voice conversation UI for AI interfaces.

Install

npm install @sdkrouter/aisphere

Peer dependencies: react, react-dom, three, @react-three/fiber, @react-three/drei

How it works

The package has two entry points:

• @sdkrouter/aisphere — core components: liquid orb, speech hooks, event system
• @sdkrouter/aisphere/dashboard — ready-to-use dashboard UI with orb, config panel, conversation controls

Core: Liquid Orb

A WebGL sphere with simplex noise displacement, matcap + Fresnel shading, and real-time audio reactivity via WebAudio API. Four visual modes — idle, listening, thinking, speaking — smoothly transition between preset configurations.

import { LiquidOrb } from '@sdkrouter/aisphere';

// Static
<LiquidOrb size={400} mode="idle" />

// Audio-reactive
<LiquidOrb size={400} mode="speaking" audioSource={audioElement} />

Core: Voice Conversation

useConversation manages the full voice pipeline: record user speech (STT) → send to LLM → play response (TTS). Phases cycle automatically: idle → listening → thinking → speaking → idle.

import { useConversation, LiquidOrbProvider, LiquidOrb, useLiquidOrb } from '@sdkrouter/aisphere';
import { SDKRouterClient } from '@sdkrouter/client';

const client = new SDKRouterClient({ apiKey: '...' });

function App() {
  const { setMode } = useLiquidOrb();
  const { phase, toggle, messages } = useConversation({
    client,
    voice: 'nova',
    llmModel: '@standard',
    systemPrompt: 'You are a helpful assistant.',
    onPhaseChange: (phase) => setMode(phase),
  });

  return (
    <>
      <LiquidOrb size={400} />
      <button onClick={toggle}>{phase}</button>
    </>
  );
}

Dashboard (separate entry point)

Pre-built dashboard with orb visualization, config panel, TTS/STT controls, and conversation UI. Requires @djangocfg/ui-core and lucide-react.

import { SDKRouterClient } from '@sdkrouter/client';
import { DashboardApp } from '@sdkrouter/aisphere/dashboard';

const client = new SDKRouterClient({ apiKey: '...' });

<DashboardApp client={client} />

Event System

Cross-component communication via typed event emitter. Wrap your app in AISphereEventsProvider and use useAISphereEvent / useAISphereEmitter to subscribe and emit.

import { AISphereEventsProvider, useAISphereEvent } from '@sdkrouter/aisphere';

function Listener() {
  useAISphereEvent('phaseChange', (phase) => console.log(phase));
  return null;
}

License

MIT