Examples

This page provides complete, runnable examples for integrating with the Blue Oyster Personal Companion API.

Basic Chat Application

HTML Structure

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Blue Oyster Chat</title>
  <style>
    body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; margin: 0; padding: 20px; }
    .chat-container { max-width: 800px; margin: 0 auto; }
    .messages { height: 400px; overflow-y: auto; border: 1px solid #ddd; padding: 10px; margin-bottom: 10px; }
    .message { margin-bottom: 10px; padding: 8px; border-radius: 8px; }
    .user-message { background: #007bff; color: white; margin-left: 100px; }
    .assistant-message { background: #f8f9fa; margin-right: 100px; }
    .input-area { display: flex; gap: 10px; }
    input { flex: 1; padding: 8px; border: 1px solid #ddd; border-radius: 4px; }
    button { padding: 8px 16px; background: #28a745; color: white; border: none; border-radius: 4px; cursor: pointer; }
    .loading { opacity: 0.6; }
    .personality-selector { margin-bottom: 10px; }
    .personality-btn { padding: 5px 10px; margin: 0 5px; border: 1px solid #ddd; background: white; cursor: pointer; }
    .personality-btn.active { background: #007bff; color: white; }
  </style>
</head>
<body>
  <div class="chat-container">
    <h1>Blue Oyster Personal Companion</h1>

    <div class="personality-selector">
      <button class="personality-btn active" data-personality="friend">🤝 Friend</button>
      <button class="personality-btn" data-personality="guru">🧘 Guru</button>
      <button class="personality-btn" data-personality="wanderer">🗺️ Wanderer</button>
      <button class="personality-btn" data-personality="philosopher">🤔 Philosopher</button>
    </div>

    <div id="messages" class="messages"></div>

    <div class="input-area">
      <input type="text" id="messageInput" placeholder="Ask me anything about spirituality..." />
      <button onclick="sendMessage()">Send</button>
    </div>
  </div>

  <script src="chat.js"></script>
</body>
</html>

JavaScript Implementation

// chat.js
class BlueOysterChat {
  constructor() {
    this.baseUrl = 'https://oyester.metaphy.live';
    this.currentPersonality = 'friend';
    this.threadId = null;
    this.isLoading = false;

    this.initializeUI();
  }

  initializeUI() {
    // Personality selector
    document.querySelectorAll('.personality-btn').forEach(btn => {
      btn.addEventListener('click', () => {
        this.setPersonality(btn.dataset.personality);
      });
    });

    // Message input
    document.getElementById('messageInput').addEventListener('keypress', (e) => {
      if (e.key === 'Enter') {
        this.sendMessage();
      }
    });
  }

  setPersonality(personality) {
    this.currentPersonality = personality;

    // Update UI
    document.querySelectorAll('.personality-btn').forEach(btn => {
      btn.classList.toggle('active', btn.dataset.personality === personality);
    });

    this.addMessage(`Switched to ${personality} personality`, 'system');
  }

  async sendMessage() {
    if (this.isLoading) return;

    const input = document.getElementById('messageInput');
    const message = input.value.trim();
    if (!message) return;

    input.value = '';
    this.addMessage(message, 'user');
    await this.processMessage(message);
  }

  async processMessage(message) {
    this.isLoading = true;
    this.showTypingIndicator();

    try {
      const response = await this.callAPI(message);
      this.hideTypingIndicator();
      this.addMessage(response.text, 'assistant');

      // Store thread ID for continuity
      if (response.threadId) {
        this.threadId = response.threadId;
      }
    } catch (error) {
      this.hideTypingIndicator();
      this.addMessage(`Error: ${error.message}`, 'error');
    } finally {
      this.isLoading = false;
    }
  }

  async callAPI(message) {
    const response = await fetch(`${this.baseUrl}/api/agents/companionAgent/generate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messages: [{ role: 'user', content: message }],
        runtimeContext: {
          metadata: {
            personality: this.currentPersonality
          }
        },
        threadId: this.threadId,
        resourceId: 'demo-user'
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || `HTTP ${response.status}`);
    }

    return await response.json();
  }

  addMessage(text, type) {
    const messages = document.getElementById('messages');
    const messageDiv = document.createElement('div');
    messageDiv.className = `message ${type}-message`;

    if (type === 'system') {
      messageDiv.style.fontStyle = 'italic';
      messageDiv.style.color = '#666';
    } else if (type === 'error') {
      messageDiv.style.color = '#dc3545';
    }

    messageDiv.textContent = text;
    messages.appendChild(messageDiv);
    messages.scrollTop = messages.scrollHeight;
  }

  showTypingIndicator() {
    const messages = document.getElementById('messages');
    const indicator = document.createElement('div');
    indicator.className = 'message assistant-message typing-indicator';
    indicator.innerHTML = '<em>Thinking...</em>';
    indicator.id = 'typing-indicator';
    messages.appendChild(indicator);
    messages.scrollTop = messages.scrollHeight;
  }

  hideTypingIndicator() {
    const indicator = document.getElementById('typing-indicator');
    if (indicator) {
      indicator.remove();
    }
  }
}

// Initialize chat when page loads
const chat = new BlueOysterChat();

// Global function for button
function sendMessage() {
  chat.sendMessage();
}

Streaming Chat Application

Enhanced Streaming Implementation

class StreamingChat extends BlueOysterChat {
  constructor() {
    super();
    this.useStreaming = true;
  }

  async processMessage(message) {
    this.isLoading = true;
    this.showTypingIndicator();

    try {
      const fullResponse = await this.callStreamingAPI(message);
      this.hideTypingIndicator();
      // Response is built progressively, so just finalize
    } catch (error) {
      this.hideTypingIndicator();
      this.addMessage(`Error: ${error.message}`, 'error');
    } finally {
      this.isLoading = false;
    }
  }

  async callStreamingAPI(message) {
    const response = await fetch(`${this.baseUrl}/api/agents/companionAgent/stream`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messages: [{ role: 'user', content: message }],
        runtimeContext: {
          metadata: {
            personality: this.currentPersonality
          }
        },
        threadId: this.threadId,
        resourceId: 'demo-user'
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || `HTTP ${response.status}`);
    }

    return await this.processStream(response);
  }

  async processStream(response) {
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let fullText = '';
    let currentMessageDiv = null;

    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        const lines = chunk.split('\n');

        for (const line of lines) {
          if (line.startsWith('data: ')) {
            try {
              const data = JSON.parse(line.slice(6));
              await this.handleStreamEvent(data, fullText, currentMessageDiv);
            } catch (e) {
              console.warn('Failed to parse stream event:', e);
            }
          }
        }
      }

      return fullText;
    } catch (error) {
      throw error;
    } finally {
      reader.releaseLock();
    }
  }

  async handleStreamEvent(event, fullText, currentMessageDiv) {
    switch (event.type) {
      case 'text':
        if (!currentMessageDiv) {
          this.hideTypingIndicator();
          currentMessageDiv = this.createStreamingMessage();
        }
        currentMessageDiv.textContent += event.text;
        document.getElementById('messages').scrollTop = document.getElementById('messages').scrollHeight;
        break;

      case 'tool-call':
        this.addMessage(`🔧 Using ${event.payload.toolName}...`, 'system');
        break;

      case 'tool-result':
        const toolName = event.payload.toolName;
        const result = event.payload.result;

        if (toolName === 'weatherTool') {
          this.addMessage(`🌤️ Weather: ${result.temperature}°C, ${result.conditions}`, 'system');
        } else if (toolName === 'search-destinations') {
          this.addMessage(`📍 Found ${result.totalFound} spiritual destinations`, 'system');
        }
        break;

      case 'error':
        this.addMessage(`❌ Error: ${event.error.message}`, 'error');
        break;
    }
  }

  createStreamingMessage() {
    const messages = document.getElementById('messages');
    const messageDiv = document.createElement('div');
    messageDiv.className = 'message assistant-message';
    messages.appendChild(messageDiv);
    return messageDiv;
  }
}

// Use streaming version
const chat = new StreamingChat();

Meditation Timer with Audio

Complete Meditation App

// meditation-app.js
class MeditationApp {
  constructor() {
    this.chat = new BlueOysterChat();
    this.audioPlayer = new MeditationAudioPlayer();
    this.timer = new MeditationTimer();
    this.currentSession = null;

    this.initializeUI();
  }

  initializeUI() {
    // Timer controls
    document.getElementById('start-timer').addEventListener('click', () => {
      this.startMeditationSession();
    });

    document.getElementById('stop-timer').addEventListener('click', () => {
      this.stopMeditationSession();
    });

    // Duration selector
    document.getElementById('duration').addEventListener('change', (e) => {
      this.timer.setDuration(parseInt(e.target.value));
    });
  }

  async startMeditationSession() {
    const mood = document.getElementById('meditation-mood').value;
    const duration = parseInt(document.getElementById('duration').value);

    // Get guidance for the session
    const guidance = await this.getMeditationGuidance(mood, duration);

    // Find and play appropriate audio
    await this.loadMeditationAudio(mood);

    // Start the timer
    this.timer.start(duration * 60, (remaining) => {
      this.updateTimerDisplay(remaining);
    }, () => {
      this.onSessionComplete();
    });

    this.currentSession = { mood, duration, guidance };
    this.updateUI('active');
  }

  async getMeditationGuidance(mood, duration) {
    const prompt = `Guide me through a ${duration}-minute ${mood} meditation session. Provide step-by-step instructions.`;

    const response = await this.chat.callAPI(prompt);
    return response.text;
  }

  async loadMeditationAudio(mood) {
    // Search for appropriate meditation audio
    const searchResponse = await this.chat.callAPI(
      `Find ${mood} meditation audio tracks for a ${duration}-minute session`
    );

    // Extract audio URLs from tool results
    const audioResults = searchResponse.toolResults?.find(
      r => r.toolName === 'search-meditation-audio'
    );

    if (audioResults?.result?.tracks?.length > 0) {
      const track = audioResults.result.tracks[0];
      this.audioPlayer.playTrack(track);
    }
  }

  stopMeditationSession() {
    this.timer.stop();
    this.audioPlayer.pause();
    this.updateUI('stopped');
  }

  onSessionComplete() {
    this.audioPlayer.fadeOut();
    this.updateUI('completed');

    // Get completion message
    setTimeout(async () => {
      const completionMessage = await this.getCompletionMessage();
      this.chat.addMessage(completionMessage, 'assistant');
    }, 2000);
  }

  async getCompletionMessage() {
    const response = await this.chat.callAPI(
      'I just completed my meditation session. What are your thoughts?'
    );
    return response.text;
  }

  updateTimerDisplay(seconds) {
    const minutes = Math.floor(seconds / 60);
    const remainingSeconds = seconds % 60;
    document.getElementById('timer-display').textContent =
      `${minutes}:${remainingSeconds.toString().padStart(2, '0')}`;
  }

  updateUI(state) {
    const startBtn = document.getElementById('start-timer');
    const stopBtn = document.getElementById('stop-timer');

    switch (state) {
      case 'active':
        startBtn.disabled = true;
        stopBtn.disabled = false;
        break;
      case 'stopped':
      case 'completed':
        startBtn.disabled = false;
        stopBtn.disabled = true;
        break;
    }
  }
}

class MeditationTimer {
  constructor() {
    this.interval = null;
    this.duration = 5; // minutes
    this.remaining = 0;
  }

  setDuration(minutes) {
    this.duration = minutes;
  }

  start(durationSeconds, onTick, onComplete) {
    this.remaining = durationSeconds;
    this.interval = setInterval(() => {
      this.remaining--;

      if (this.remaining <= 0) {
        this.stop();
        onComplete();
      } else {
        onTick(this.remaining);
      }
    }, 1000);
  }

  stop() {
    if (this.interval) {
      clearInterval(this.interval);
      this.interval = null;
    }
  }
}

class MeditationAudioPlayer {
  constructor() {
    this.audio = new Audio();
    this.currentTrack = null;
  }

  async playTrack(track) {
    this.currentTrack = track;
    this.audio.src = track.audioUrl;
    this.audio.volume = 0.3; // Gentle volume

    try {
      await this.audio.play();
    } catch (error) {
      console.warn('Audio playback failed:', error);
    }
  }

  pause() {
    this.audio.pause();
  }

  fadeOut() {
    const fadeStep = 0.05;
    const fadeInterval = setInterval(() => {
      if (this.audio.volume > fadeStep) {
        this.audio.volume -= fadeStep;
      } else {
        this.audio.volume = 0;
        this.audio.pause();
        clearInterval(fadeInterval);
      }
    }, 100);
  }
}

// HTML for meditation app
const meditationHTML = `
  <div class="meditation-app">
    <h2>Meditation Session</h2>

    <div class="session-controls">
      <select id="meditation-mood">
        <option value="calm">Calm</option>
        <option value="peaceful">Peaceful</option>
        <option value="focused">Focused</option>
        <option value="relaxing">Relaxing</option>
      </select>

      <select id="duration">
        <option value="5">5 minutes</option>
        <option value="10">10 minutes</option>
        <option value="15">15 minutes</option>
        <option value="20">20 minutes</option>
      </select>

      <button id="start-timer">Start Session</button>
      <button id="stop-timer" disabled>Stop</button>
    </div>

    <div id="timer-display" class="timer">5:00</div>

    <div id="guidance" class="guidance-area"></div>
  </div>
`;

// Initialize the app
const meditationApp = new MeditationApp();

Weather-Aware Spiritual Planning

Travel Planning Integration

class SpiritualTravelPlanner {
  constructor(chat) {
    this.chat = chat;
    this.weatherCache = new Map();
  }

  async planSpiritualTrip(destination, interests) {
    // Get weather for the destination
    const weather = await this.getWeather(destination);

    // Find spiritual destinations
    const destinations = await this.findDestinations(destination, interests);

    // Create personalized itinerary
    const itinerary = await this.createItinerary(destinations, weather, interests);

    return {
      destination,
      weather,
      destinations,
      itinerary,
      recommendations: this.generateRecommendations(weather, destinations)
    };
  }

  async getWeather(location) {
    if (this.weatherCache.has(location)) {
      return this.weatherCache.get(location);
    }

    const response = await this.chat.callAPI(`What's the weather like in ${location}?`);
    const weatherData = this.extractWeatherFromResponse(response);

    if (weatherData) {
      this.weatherCache.set(location, weatherData);
    }

    return weatherData;
  }

  async findDestinations(location, interests) {
    const query = `Find spiritual destinations in ${location} related to ${interests.join(', ')}`;

    const response = await this.chat.callAPI(query);
    const toolResults = response.toolResults || [];
    const destinationResult = toolResults.find(r => r.toolName === 'search-destinations');

    return destinationResult?.result?.destinations || [];
  }

  async createItinerary(destinations, weather, interests) {
    const destinationNames = destinations.slice(0, 3).map(d => d.name).join(', ');
    const query = `Create a spiritual itinerary for ${destinationNames} considering ${weather.conditions} weather. Focus on ${interests.join(', ')} activities.`;

    const response = await this.chat.callAPI(query);
    return response.text;
  }

  generateRecommendations(weather, destinations) {
    const recommendations = [];

    if (weather.temperature < 15) {
      recommendations.push('Bring warm clothing for outdoor activities');
    }

    if (weather.humidity > 70) {
      recommendations.push('Stay hydrated, especially during meditation');
    }

    if (destinations.some(d => d.category === 'temple')) {
      recommendations.push('Visit temples early morning for peaceful atmosphere');
    }

    return recommendations;
  }

  extractWeatherFromResponse(response) {
    const toolResults = response.toolResults || [];
    const weatherResult = toolResults.find(r => r.toolName === 'weatherTool');
    return weatherResult?.result || null;
  }
}

// Usage
const travelPlanner = new SpiritualTravelPlanner(chat);

async function planTrip() {
  const trip = await travelPlanner.planSpiritualTrip('Kyoto, Japan', [
    'Zen meditation',
    'temple visits',
    'traditional tea ceremony'
  ]);

  console.log('Spiritual Trip Plan:', trip);
}

Voice Integration with Speech-to-Text

Voice-Enabled Chat

class VoiceEnabledChat extends StreamingChat {
  constructor() {
    super();
    this.recognition = null;
    this.synthesis = new SpeechSynthesisUtterance();
    this.isListening = false;

    this.initializeVoice();
  }

  initializeVoice() {
    // Check for Web Speech API support
    if ('webkitSpeechRecognition' in window || 'SpeechRecognition' in window) {
      const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;
      this.recognition = new SpeechRecognition();
      this.recognition.continuous = false;
      this.recognition.interimResults = false;
      this.recognition.lang = 'en-US';

      this.recognition.onresult = (event) => {
        const transcript = event.results[0][0].transcript;
        document.getElementById('messageInput').value = transcript;
        this.sendMessage();
      };

      this.recognition.onerror = (event) => {
        console.error('Speech recognition error:', event.error);
        this.stopListening();
      };

      this.recognition.onend = () => {
        this.stopListening();
      };
    }

    // Voice synthesis
    this.synthesis.rate = 0.9;
    this.synthesis.pitch = 1;
  }

  startListening() {
    if (!this.recognition) {
      alert('Speech recognition not supported in this browser');
      return;
    }

    if (this.isListening) return;

    this.isListening = true;
    this.recognition.start();

    // Update UI
    document.getElementById('voice-btn').classList.add('listening');
    document.getElementById('voice-btn').textContent = '🎤 Listening...';
  }

  stopListening() {
    if (this.recognition && this.isListening) {
      this.recognition.stop();
    }

    this.isListening = false;

    // Update UI
    document.getElementById('voice-btn').classList.remove('listening');
    document.getElementById('voice-btn').textContent = '🎤';
  }

  speakText(text) {
    if ('speechSynthesis' in window) {
      this.synthesis.text = text;
      window.speechSynthesis.speak(this.synthesis);
    }
  }

  async processVoiceMessage(audioBlob) {
    try {
      // Convert blob to base64
      const base64Audio = await this.blobToBase64(audioBlob);

      // Send to speech-to-text endpoint
      const transcript = await this.transcribeAudio(base64Audio);

      // Process the transcribed text
      document.getElementById('messageInput').value = transcript;
      await this.sendMessage();

    } catch (error) {
      console.error('Voice processing error:', error);
      this.addMessage('Sorry, I couldn\'t understand that audio. Please try again.', 'error');
    }
  }

  async transcribeAudio(base64Audio) {
    const formData = new FormData();
    // Convert base64 back to blob for upload
    const audioBlob = this.base64ToBlob(base64Audio);
    formData.append('audio', audioBlob);

    const response = await fetch(`${this.baseUrl}/stt`, {
      method: 'POST',
      body: formData
    });

    if (!response.ok) {
      throw new Error('Speech-to-text failed');
    }

    const result = await response.json();
    return result.transcript;
  }

  blobToBase64(blob) {
    return new Promise((resolve, reject) => {
      const reader = new FileReader();
      reader.onload = () => resolve(reader.result.split(',')[1]);
      reader.onerror = reject;
      reader.readAsDataURL(blob);
    });
  }

  base64ToBlob(base64) {
    const byteCharacters = atob(base64);
    const byteNumbers = new Array(byteCharacters.length);
    for (let i = 0; i < byteCharacters.length; i++) {
      byteNumbers[i] = byteCharacters.charCodeAt(i);
    }
    const byteArray = new Uint8Array(byteNumbers);
    return new Blob([byteArray], { type: 'audio/wav' });
  }

  async handleStreamEvent(event, fullText, currentMessageDiv) {
    // Call parent method
    await super.handleStreamEvent(event, fullText, currentMessageDiv);

    // Auto-speak completed responses
    if (event.type === 'run-finish' && fullText) {
      setTimeout(() => this.speakText(fullText), 500);
    }
  }
}

// Enhanced HTML with voice controls
const voiceChatHTML = `
  <div class="voice-controls">
    <button id="voice-btn" onclick="toggleVoice()">🎤</button>
    <button onclick="speakLastResponse()">🔊</button>
  </div>
`;

// Global functions
function toggleVoice() {
  if (chat.isListening) {
    chat.stopListening();
  } else {
    chat.startListening();
  }
}

function speakLastResponse() {
  const messages = document.querySelectorAll('.assistant-message');
  const lastMessage = messages[messages.length - 1];
  if (lastMessage) {
    chat.speakText(lastMessage.textContent);
  }
}

These examples provide complete, runnable code for various integration scenarios with the Blue Oyster Personal Companion API.

Getting Started

Core API

Tools

Personalities

Reference

Examples

Examples

Basic Chat Application

HTML Structure

JavaScript Implementation

Streaming Chat Application

Enhanced Streaming Implementation

Meditation Timer with Audio

Complete Meditation App

Weather-Aware Spiritual Planning

Travel Planning Integration

Voice Integration with Speech-to-Text

Voice-Enabled Chat

Getting Started

Core API

Tools

Personalities

Reference

​Examples

​Basic Chat Application

​HTML Structure

​JavaScript Implementation

​Streaming Chat Application

​Enhanced Streaming Implementation

​Meditation Timer with Audio

​Complete Meditation App

​Weather-Aware Spiritual Planning

​Travel Planning Integration

​Voice Integration with Speech-to-Text

​Voice-Enabled Chat

Examples

Basic Chat Application

HTML Structure

JavaScript Implementation

Streaming Chat Application

Enhanced Streaming Implementation

Meditation Timer with Audio

Complete Meditation App

Weather-Aware Spiritual Planning

Travel Planning Integration

Voice Integration with Speech-to-Text

Voice-Enabled Chat