# @sdkrouter/aisphere

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

## Install

```bash
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.

```tsx
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`.

```tsx
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`.

```tsx
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.

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

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

## License

MIT