VOIX

https://github.com/svenschultze/voix
Admin
VOIX is a lightweight browser framework that enables adding AI assistants to any website using...
Tokens:74,202
Snippets:180
Trust Score:5.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Project Setup Commands

Source: https://github.com/svenschultze/voix/blob/master/examples/vue-example/README.md

Provides essential command-line instructions for setting up the project, including installing dependencies using npm and starting the development server.

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build
```

--------------------------------

### Project Setup and Dependencies

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Provides essential commands for setting up a Svelte project with VOIX, including installing dependencies, starting the development server, and building for production. It also lists key dependencies.

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build
```

```json
{
  "svelte": "^5.0.0",
  "@sveltejs/vite-plugin-svelte": "^4.0.0",
  "vite": "^5.0.0"
}
```

--------------------------------

### Installation and Setup Commands

Source: https://github.com/svenschultze/voix/blob/master/examples/react-example/README.md

A sequence of bash commands to set up and run the React task manager application. This includes navigating to the project directory, installing necessary Node.js dependencies, and starting the development server.

```bash
cd examples/react-example
npm install
npm start
```

--------------------------------

### OpenAI Provider Configuration

Source: https://github.com/svenschultze/voix/blob/master/docs/getting-started.md

Configuration details for using OpenAI as the AI provider for VOIX. This includes the base URL, API key, and model selection.

```APIDOC
OpenAI Provider Configuration:
  Base URL: https://api.openai.com/v1
  API Key: Your OpenAI API key (starts with sk-)
  Model: gpt-4 or gpt-3.5-turbo
```

--------------------------------

### VOIX Website Interaction with Tools and Context

Source: https://github.com/svenschultze/voix/blob/master/docs/getting-started.md

Details on how VOIX interacts with compatible websites using custom HTML elements. It explains the functionality of `<tool>` elements for executing actions and `<context>` elements for providing page state information.

```APIDOC
VOIX Website Interaction:

Tools:
  Element: <tool>
  Functionality: Allows VOIX to execute actions on the page, fill forms, click buttons, and extract data.

Context:
  Element: <context>
  Functionality: Provides VOIX with information about the current page state, user details, and application data.
```

--------------------------------

### Best Practices: Helpful Descriptions Examples

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Highlights the need for clear and informative descriptions for tools, showing examples of good versus insufficient descriptions.

```html
<!-- Gut -->
<tool name="filter_products" description="Produkte nach Kategorie und Preis filtern">

<!-- Vermeiden -->
<tool name="filter_products" description="Filtern">
```

--------------------------------

### OpenAI-Compatible Provider Configuration

Source: https://github.com/svenschultze/voix/blob/master/docs/getting-started.md

Configuration details for using OpenAI-compatible AI providers, such as Azure OpenAI. This requires specifying the custom base URL, API key, and model name.

```APIDOC
OpenAI-Compatible Provider Configuration:
  Base URL: Your OpenAI-compatible endpoint (e.g. https://api.example.org/v1)
  API Key: Your API key
  Model: Your model name
```

--------------------------------

### VOIX Chrome Extension Setup

Source: https://github.com/svenschultze/voix/blob/master/README.md

This section outlines the steps to install and configure the VOIX Chrome extension. It covers finding the extension on the Chrome Web Store, adding it to the browser, and configuring AI provider settings like API keys and base URLs through the extension's options page.

```APIDOC
VOIX Chrome Extension Setup Guide:

1. Installation:
   - Navigate to the VOIX Chrome Extension page on the Chrome Web Store.
   - Click 'Add to Chrome' and confirm the installation.

2. Configuration:
   - Access Extension Options: Click the VOIX extension icon in the Chrome toolbar and select 'Options'.
   - AI Provider Setup:
     - Choose an AI provider (e.g., OpenAI, Azure OpenAI, Anthropic, Ollama).
     - Enter necessary credentials:
       - API Key: Your authentication key for the chosen provider.
       - Base URL: The endpoint for the AI service (e.g., for Azure OpenAI or local Ollama).
       - Model Name: The specific AI model to use.
   - Voice Input Configuration (Optional):
     - Configure settings for voice transcription, typically using OpenAI's Whisper API.
   - Testing and Saving:
     - Use the 'Test Connection' button to verify your configuration.
     - Click 'Save' to apply your settings.
```

--------------------------------

### Local (Ollama) Provider Configuration

Source: https://github.com/svenschultze/voix/blob/master/docs/getting-started.md

Configuration details for using a local AI provider via Ollama. This specifies the local base URL and the model name, with no API key required.

```APIDOC
Local (Ollama) Provider Configuration:
  Base URL: http://localhost:11434/v1
  API Key: Not required (leave empty)
  Model: qwen3, mistral, or your installed model
```

--------------------------------

### Vue Navigation Helper Script Setup

Source: https://github.com/svenschultze/voix/blob/master/docs/demo-navigation.md

This script setup block defines the logic for the Navigation Demo component in Vue.js. It imports necessary components and sets up the application's navigation features, leveraging the VOIX framework.

```vue
<script setup>
import NavigationDemo from './components/NavigationDemo.vue'
</script>
```

--------------------------------

### Best Practices: Focused Tools Examples

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Emphasizes the principle of keeping tools focused on a single task, showing examples of separate tools for distinct actions versus a single tool for multiple actions.

```html
<!-- Gut: Separate Werkzeuge für verschiedene Aktionen -->
<tool name="add_to_cart" description="Artikel zum Warenkorb hinzufügen">
<tool name="remove_from_cart" description="Artikel aus dem Warenkorb entfernen">

<!-- Vermeiden: Ein Werkzeug, das mehrere Dinge tut -->
<tool name="manage_cart" description="Warenkorb hinzufügen, entfernen oder aktualisieren">
```

--------------------------------

### Best Practices: Clear Naming Examples

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Illustrates the importance of using descriptive, action-oriented names for tools, contrasting good and bad naming conventions.

```html
<!-- Gut -->
<tool name="create_task" description="Eine neue Aufgabe erstellen">
<tool name="delete_item" description="Einen Artikel löschen">

<!-- Vermeiden -->
<tool name="do_thing" description="Etwas tun">
<tool name="action1" description="Aktion">
```

--------------------------------

### Whisper API Voice Input Configuration

Source: https://github.com/svenschultze/voix/blob/master/docs/getting-started.md

Configuration for VOIX's voice transcription using OpenAI's Whisper API. This includes language selection, model choice, and optional base URL/API key for custom endpoints.

```APIDOC
Whisper API Voice Input Configuration:
  Language: Select your preferred language or use "Auto-detect"
  Model: whisper-1 (default)
  Base URL: Leave empty to use the same as your AI provider, otherwise specify another OpenAI-compatible endpoint
  API Key: Your API key (if using a separate endpoint)
```

--------------------------------

### Tool Testing Example

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Provides a complete HTML page example for testing VOIX tools, including a simple tool definition and a JavaScript listener to log and display tool call details.

```html
<!DOCTYPE html>
<html>
<body>
  <tool name="test_tool" description="Testwerkzeug zum Debuggen">
    <prop name="message" type="string" required></prop>
  </tool>
  
  <script>
  document.querySelector('[name=test_tool]').addEventListener('call', (e) => {
    console.log('Werkzeug aufgerufen mit:', e.detail);
    alert(`Werkzeug empfangen: ${e.detail.message}`);
  });
  </script>
</body>
</html>
```

--------------------------------

### Vue Script Setup for Form Assistant Demo

Source: https://github.com/svenschultze/voix/blob/master/docs/demo-form-assistant.md

The script setup block for the Form Assistant Demo page, importing the necessary Vue component for displaying the demo. This setup is part of a Vue Single File Component (SFC).

```vue
<script setup>
import FormAssistantDemo from './components/FormAssistantDemo.vue'
</script>
```

--------------------------------

### Project Key Dependencies

Source: https://github.com/svenschultze/voix/blob/master/examples/vue-example/README.md

Lists the core dependencies required for the project, specifying versions for Vue, Vite plugin for Vue, and Vite itself.

```json
{
  "vue": "^3.4.0",
  "@vitejs/plugin-vue": "^5.0.0",
  "vite": "^5.0.0"
}
```

--------------------------------

### Vue.js Script Setup for Context Loading

Source: https://github.com/svenschultze/voix/blob/master/docs/de/voix_context.md

This Vue.js script setup block handles navigation logic and imports data for context loading. It defines a `navigateTo` function that opens a new URL in the current tab.

```vue
import { ref, onMounted } from 'vue';

import { data } from "../load_context.data.js";

function navigateTo(e) {
    const { section } = e.detail
    const url = `${section}`;
    // go to that url in this tab
    window.open(url, '_self');
}
```

--------------------------------

### Product Search Demo Component Setup

Source: https://github.com/svenschultze/voix/blob/master/docs/demo-product-search.md

Imports the main ProductSearchDemo component, which is the entry point for the searchable product catalog functionality. This setup enables features like searching, filtering by category and price, and sorting results using natural language.

```vue
<script setup>
import ProductSearchDemo from './components/ProductSearchDemo.vue'
</script>
```

--------------------------------

### Implement Simple Tool Action (HTML/JS)

Source: https://github.com/svenschultze/voix/blob/master/docs/tools.md

A basic example of a tool that performs a simple action, like toggling a theme, without returning data to the AI. It demonstrates the minimal structure for a tool with no parameters.

```html
<tool name="toggle_theme" description="Switch between light and dark theme">
</tool>

<script>
document.querySelector('[name=toggle_theme]').addEventListener('call', (e) => {
  document.body.classList.toggle('dark-theme');
});
</script>
```

--------------------------------

### Best Practices: Error Handling Example

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Provides a JavaScript code snippet demonstrating how to implement robust error handling for tool execution using a try-catch block.

```javascript
tool.addEventListener('call', async (e) => {
  try {
    // Ihre Logik hier
    await performAction(e.detail);
  } catch (err) {
    console.error('Werkzeugausführung fehlgeschlagen:', err);
    showErrorMessage('Aktion fehlgeschlagen. Bitte versuchen Sie es erneut.');
  }
});
```

--------------------------------

### Vue Component Setup

Source: https://github.com/svenschultze/voix/blob/master/docs/demo-data-table.md

Demonstrates the setup of the DataTableDemo Vue component, importing it for use within the application. This component facilitates interaction with data tables using natural language.

```vue
<script setup>
import DataTableDemo from './components/DataTableDemo.vue'
</script>
```

--------------------------------

### Example React App Using VOIX Tool Component

Source: https://github.com/svenschultze/voix/blob/master/docs/react-integration.md

Demonstrates how to use the custom React 'Tool' component to define and interact with VOIX tools within a React application. It includes a 'context' element for state display and a 'Tool' component for an 'increment_counter' function.

```tsx
import { useState } from 'react'
import './App.css'
import { Tool } from './Tool'

function App() {
  const [count, setCount] = useState(0)

  function handleIncrement(event: Event) {
    const details = (event as CustomEvent).detail;
    console.log('Incrementing counter:', details);
    setCount((prevCount) => prevCount + details.n);
  }

  return (
    <>
      <context name="counter">
        The current count is {count}
      </context>
      <Tool name="increment_counter" description="Increments the counter by n" onCall={(event) => handleIncrement(event)}>
        <prop name="n" type="number" required description="The number to increment the counter by" ></prop>
      </Tool>
      <button onClick={() => setCount((count) => count + 1)}>
        count is {count}
      </button>
    </>
  )
}

export default App
```

--------------------------------

### Basic robots.txt Configuration

Source: https://github.com/svenschultze/voix/blob/master/examples/react-example/public/robots.txt

This snippet defines rules for web crawlers. The 'User-agent: *' directive applies to all crawlers, and 'Disallow:' indicates that no paths are disallowed, meaning all content is crawlable.

```robots.txt
User-agent: *
Disallow:
```

--------------------------------

### VOIX Tool for Fetching Data (Weather)

Source: https://github.com/svenschultze/voix/blob/master/docs/angular-integration.md

An example of a VOIX tool designed to fetch external data, specifically weather information for a given location. It uses Angular's event binding to trigger an asynchronous function.

```html
<tool name="get_weather" description="Fetch weather for a city" (call)="getWeather($event)">
  <prop name="location" type="string" description="City name" ></prop>
</tool>
```

--------------------------------

### Svelte Tool for Asynchronous Data Fetching

Source: https://github.com/svenschultze/voix/blob/master/docs/svelte-integration.md

Creates a VOIX tool that fetches data from external APIs using asynchronous JavaScript. This example fetches weather data based on a provided location, handling potential errors and returning structured results.

```svelte
<script lang="ts">
  const getWeather = async (location: string) => {
    try {
      const geoRes = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(location)}`);
      const geoData = await geoRes.json();

      if (!geoData.results?.length) {
        throw new Error('Location not found');
      }

      const { latitude, longitude, name, country } = geoData.results[0];

      const wxRes = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,weather_code&daily=weather_code,temperature_2m_max,temperature_2m_min&timezone=auto`);
      const wxData = await wxRes.json();

      return { ...wxData, city: name, country };
    } catch (e: any) {
      return { error: e.message };
    }
  };
</script>

<tool
  name="get_weather"
  description="Fetch weather by city name. For example: 'Berlin' or 'New York'."
  return
  oncall={async (event: CustomEvent) => {
    const { location } = event.detail;
    const data = await getWeather(location);
    event.target?.dispatchEvent(new CustomEvent('return', { detail: data }));
  }}>
  <prop name="location" type="string" description="City name to fetch weather for"></prop>
</tool>
```

--------------------------------

### Framework Example: Svelte Add Item

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Illustrates the integration of a VOIX tool for adding items in a Svelte component, utilizing event listeners for tool calls.

```svelte
<script>
  async function handleAdd(e) {
    const { item } = e.detail;
    await addItem(item);
    showMessage(`${item} hinzugefügt`);
  }
</script>

<tool name="add_item" on:call={handleAdd} description="Einen Artikel hinzufügen">
  <prop name="item" type="string" required></prop>
</tool>
```

--------------------------------

### Framework Example: React Task Manager

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Demonstrates how to integrate a VOIX tool for creating tasks within a React component using `useRef` and `useEffect` for event handling.

```jsx
function TaskManager() {
  const toolRef = useRef();
  
  useEffect(() => {
    const handleCall = async (e) => {
      const { title } = e.detail;
      await createTask(title);
      refreshTaskList();
    };
    
    toolRef.current?.addEventListener('call', handleCall);
    return () => toolRef.current?.removeEventListener('call', handleCall);
  }, []);
  
  return (
    <tool ref={toolRef} name="create_task" description="Eine neue Aufgabe erstellen">
      <prop name="title" type="string" required></prop>
    </tool>
  );
}
```

--------------------------------

### Context Examples: User, Page, App State

Source: https://github.com/svenschultze/voix/blob/master/docs/contexts.md

Illustrates how to use context elements to convey specific application states like user information, page details, and application status using simple key-value pairs.

```html
<context name="current_user">
  Name: John Doe
  Role: Administrator
  Last login: 2025-01-30 10:00
</context>
```

```html
<context name="page_info">
  Page: Dashboard
  User role: Admin
  Total items: 42
  Filter: Active only
</context>
```

```html
<context name="app_state">
  Mode: Edit
  Unsaved changes: Yes
  Auto-save: Enabled
  Last saved: 5 minutes ago
</context>
```

--------------------------------

### Tool Naming Best Practice

Source: https://github.com/svenschultze/voix/blob/master/docs/tools.md

Illustrates the best practice for naming VOIX tools, emphasizing descriptive and action-oriented names for clarity and usability. Contrasts good examples like 'create_task' with less informative ones like 'do_thing'.

```html
<!-- Good -->
<tool name="create_task" description="Create a new task">
<tool name="delete_item" description="Delete an item">

<!-- Avoid -->
<tool name="do_thing" description="Do something">
<tool name="action1" description="Action">
```

--------------------------------

### VOIX Test Tool Example

Source: https://github.com/svenschultze/voix/blob/master/docs/tools.md

Provides a simple HTML page with a 'test_tool' for debugging VOIX integrations. It includes a message property and a JavaScript listener that logs the received details to the console and displays an alert.

```html
<!DOCTYPE html>
<html>
<body>
  <tool name="test_tool" description="Test tool for debugging">
    <prop name="message" type="string" required></prop>
  </tool>
  
  <script>
  document.querySelector('[name=test_tool]').addEventListener('call', (e) => {
    console.log('Tool called with:', e.detail);
    alert(`Tool received: ${e.detail.message}`);
  });
  </script>
</body>
</html>
```

--------------------------------

### WeatherDemo Component Setup

Source: https://github.com/svenschultze/voix/blob/master/docs/de/demo-weather.md

This snippet demonstrates the setup for the WeatherDemo component in a Vue.js application. It imports the WeatherDemo component itself, which is likely where the main logic and UI for the weather tool reside. This is a common pattern for organizing Vue.js components.

```Vue.js
<script setup>
import WeatherDemo from "../components/WeatherDemo.vue";
</script>
```

--------------------------------

### React Tool Integration Example

Source: https://github.com/svenschultze/voix/blob/master/docs/tools.md

Demonstrates how to integrate VOIX tools within a React component using `useRef` and `useEffect`. It shows setting up an event listener for a 'create_task' tool and handling its execution within the React lifecycle.

```jsx
function TaskManager() {
  const toolRef = useRef();
  
  useEffect(() => {
    const handleCall = async (e) => {
      const { title } = e.detail;
      await createTask(title);
      refreshTaskList();
    };
    
    toolRef.current?.addEventListener('call', handleCall);
    return () => toolRef.current?.removeEventListener('call', handleCall);
  }, []);
  
  return (
    <tool ref={toolRef} name="create_task" description="Create a new task">
      <prop name="title" type="string" required></prop>
    </tool>
  );
}
```

--------------------------------

### Define and Handle VOIX Tools in Vue.js

Source: https://github.com/svenschultze/voix/blob/master/examples/vue-example/README.md

Shows how to define VOIX `<tool>` elements within a Vue.js template, specifying properties and using the `@call` directive to bind to JavaScript event handlers. Includes examples for adding tasks and updating task status, demonstrating how to pass data and receive results/errors.

```vue
<template>
  <!-- Tool that AI can call to add tasks -->
  <tool 
    name="add_task" 
    description="Add a new task to the list"
    @call="handleAddTaskTool"
  >
    <prop name="text" type="string" description="Text of the task to add" required>
      Buy groceries
    </prop>
  </tool>

  <!-- Tool with dynamic context from Vue data -->
  <tool 
    name="update_task_status" 
    description="Update the status of a specific task"
    @call="handleUpdateStatus"
  >
    <prop name="task_id" type="string" description="ID of task to update" required>
      {{ tasks[0]?.id || 'task-123' }}
    </prop>
    <prop name="completed" type="boolean" description="Mark as completed" required>
      false
    </prop>
  </tool>
</template>

<script setup>
// Tool event handlers
function handleAddTaskTool(event) {
  const { text } = event.detail || {};
  if (text) {
    addTask(text);
    
    // Set success response directly on event detail
    event.detail.success = true;
    event.detail.result = { task_added: text };
    event.detail.message = `Task "${text}" added successfully`;
  } else {
    event.detail.success = false;
    event.detail.error = "Task text is required";
  }
}

function handleUpdateStatus(event) {
  const { task_id, completed } = event.detail;
  
  try {
    setTaskComplete(parseInt(task_id), completed);
    
    event.detail.success = true;
    event.detail.result = { task_id, completed };
    event.detail.message = `Task ${task_id} marked as ${completed ? 'completed' : 'incomplete'}`;
  } catch (error) {
    event.detail.success = false;
    event.detail.error = error.message;
  }
}
</script>
```

--------------------------------

### Leveraging Svelte Reactivity with VOIX Context

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Demonstrates how Svelte's built-in reactivity system seamlessly updates VOIX context when application data changes. This ensures that context consumers always receive the latest state.

```svelte
<script>
  let appData = $state({ users: [], tasks: [] });
  
  // Context automatically updates when appData changes
  let contextString = $derived(`
    Users: ${appData.users.length}
    Tasks: ${appData.tasks.length}
    Updated: ${new Date().toISOString()}
  `);
</script>

<context name="app_state">{contextString}</context>
```

--------------------------------

### Voix Component API Reference

Source: https://github.com/svenschultze/voix/blob/master/docs/vue-integration.md

Documentation for core Voix components used in Vue.js applications, including <tool> for defining AI-executable actions and <context> for displaying dynamic information.

```APIDOC
Tool Component:
  Represents an action or function that the AI can call.

  Attributes:
    name (string, required): A unique identifier for the tool.
    description (string, required): A human-readable description of what the tool does, used by the AI for understanding.
    @call (event handler): Emitted when the tool is invoked by the AI. The event detail contains parameters passed to the tool.

  Child Elements:
    <prop>: Defines parameters for the tool.

  Example:
    <tool name="send_email" description="Send an email to a recipient">
      <prop name="to" type="string" required></prop>
      <prop name="subject" type="string" required></prop>
      <prop name="body" type="string"></prop>
    </tool>

Context Component:
  Displays dynamic information or state within the AI's environment.

  Attributes:
    name (string, required): A unique identifier for the context block.

  Content:
    Can contain text, variables, and expressions that Vue.js will render reactively.

  Example:
    <context name="user_status">
      User: {{ userName }}
      Status: {{ userStatus }}
    </context>

Prop Component:
  Defines a parameter for a <tool> component.

  Attributes:
    name (string, required): The name of the parameter.
    type (string, required): The expected data type of the parameter (e.g., 'string', 'number', 'array', 'boolean', 'object').
    required (boolean, optional): If true, this parameter must be provided when the tool is called.
    description (string, optional): A description of the parameter for AI understanding.

  Example:
    <prop name="userIds" type="array" required description="List of user IDs to process"></prop>
```

--------------------------------

### Svelte Tool Integration Example

Source: https://github.com/svenschultze/voix/blob/master/docs/tools.md

Illustrates integrating VOIX tools within a Svelte component. It sets up an `on:call` event listener for an 'add_item' tool, defining a handler function to process the item and display a confirmation message.

```svelte
<script>
  async function handleAdd(e) {
    const { item } = e.detail;
    await addItem(item);
    showMessage(`${item} added`);
  }
</script>

<tool name="add_item" on:call={handleAdd} description="Add an item">
  <prop name="item" type="string" required></prop>
</tool>
```

--------------------------------

### Svelte Reactive Tool Parameters

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Shows how to dynamically define and render Svelte components, specifically a 'tool' component, whose parameters are derived from the application's reactive state. This allows tools to adapt to changing data.

```svelte
<script>
  let selectedProject = $state(null);
  let availableStatuses = $state(['todo', 'in-progress', 'done']);
  
  // Dynamic tool based on current state
  let currentTaskId = $derived(selectedProject?.tasks?.[0]?.id || null);
</script>

{#if currentTaskId}
<tool 
  name="update_current_task" 
  description="Update the currently selected task"
  oncall={handleUpdateTask}
>
  <prop name="task_id" type="string" description="Task ID" required>
    {currentTaskId}
  </prop>
  <prop name="status" type="string" description="New status" required>
    {availableStatuses[0]}
  </prop>
</tool>
{/if}
```

--------------------------------

### Real-Time Data Updates with Vue.js Reactivity

Source: https://github.com/svenschultze/voix/blob/master/docs/vue-integration.md

Illustrates how to leverage Vue's reactivity system to display and update data in real-time within <context> elements. It uses ref for reactive state and onMounted with setInterval to simulate live data feeds.

```vue
<template>
  <div class="dashboard">
    <!-- This context automatically updates when its content changes -->
    <context name="metrics">
      Users online: {{ onlineUsers }}
      Last update: {{ lastUpdate }}
    </context>

    <tool
      name="refresh_data"
      description="Manually refresh dashboard data"
      @call="refreshData"
    >
    </tool>

    <h3>Dashboard</h3>
    <p>Users Online: {{ onlineUsers }}</p>
    <p>Last Update: {{ lastUpdate }}</p>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'

const onlineUsers = ref(0)
const lastUpdate = ref(new Date().toLocaleTimeString())

function refreshData(event) {
  onlineUsers.value = Math.floor(Math.random() * 100)
  lastUpdate.value = new Date().toLocaleTimeString()
  if (event) {
    event.detail.success = true;
    event.detail.message = "Dashboard data has been refreshed.";
  }
}

// Simulate real-time updates from a server
onMounted(() => {
  setInterval(refreshData, 5000)
})
</script>
```

--------------------------------

### Basic VOIX Tool and Context in Angular

Source: https://github.com/svenschultze/voix/blob/master/docs/angular-integration.md

Demonstrates defining a VOIX context and a tool with a property in an Angular template. It shows how to bind a tool's call event to a component method and display context values.

```html
<!-- app.html -->
<context name="secret_number">
  the secret number is {{ secretNumber() }}
</context>

<tool name="change_number" description="Change the secret number" (call)="changeNumber($event)">
  <prop name="number" type="number" ></prop>
</tool>

<div>
  <p>The secret number is: {{ secretNumber() }}</p>
  <p>Use the tool to change it!</p>
</div>
```

--------------------------------

### Tool Focus Best Practice

Source: https://github.com/svenschultze/voix/blob/master/docs/tools.md

Illustrates the principle of keeping VOIX tools focused on a single responsibility. It shows examples of separate tools for distinct actions like 'add_to_cart' and 'remove_from_cart', contrasting with a single tool attempting to manage multiple operations.

```html
<!-- Good: Separate tools for different actions -->
<tool name="add_to_cart" description="Add item to shopping cart">
<tool name="remove_from_cart" description="Remove item from cart">

<!-- Avoid: One tool doing multiple things -->
<tool name="manage_cart" description="Add, remove, or update cart">
```

--------------------------------

### Log Available VOIX Tools in Browser Console

Source: https://github.com/svenschultze/voix/blob/master/examples/vue-example/README.md

A simple JavaScript snippet to log the discovered VOIX tools to the browser's console, useful for debugging tool discovery issues.

```javascript
// In browser console
console.log('Available tools:', window.mcpServer?.tools);
```

--------------------------------

### Svelte Custom Elements Configuration

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Shows how Svelte treats VOIX custom elements like `<tool>` and `<prop>` as regular HTML elements without special configuration. This snippet illustrates the basic structure for defining a tool with properties.

```Svelte
<!-- No special configuration needed in Svelte! -->
<tool name="add_task" description="Add a new task">
  <prop name="text" type="string" description="Task text" required>
    New task
  </prop>
</tool>
```

--------------------------------

### Debugging Tool Discovery in Browser Console

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Offers a simple debugging technique to inspect available 'tool' elements directly in the browser's developer console, helping to verify if tools are correctly registered and discoverable by the system.

```javascript
// In browser console
console.log('Available tools:', document.querySelectorAll('tool'));
```

--------------------------------

### Svelte 5 Runes for Reactivity

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Illustrates the core concepts of Svelte 5 Runes, including state runes for mutable data, derived runes for computed values, and effect runes for handling side effects, showcasing reactive programming patterns.

```javascript
// State runes for reactive data
let tasks = $state([]);
let filter = $state('all');

// Derived runes for computed values
let filteredTasks = $derived(tasks.filter(/* filter logic */));

// Effect runes for side effects
$effect(() => {
  console.log('Tasks updated:', tasks.length);
});
```

--------------------------------

### AI Interaction Tools for Task Editing

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Defines custom tool elements for interacting with AI to modify specific fields of a task. Each tool specifies its name, a description, the function to call (`oncall`), and properties with their types and descriptions.

```APIDOC
context name="current_task"
  Provides context about the task being edited.
  - task.id: Identifier of the task.
  - task.text: Current text of the task.
  - task.dueDate: Current due date of the task (YYYY-MM-DD or null).
  - task.priority: Current priority of the task (low, medium, high, or null).
  - task.notes: Current notes for the task (or null).

tool name="set_text"
  description: Set the task text.
  oncall: setText (function)
  Parameters:
    text (string): New text for the task. Cannot be empty.
  Returns:
    success (boolean): True if the text was updated successfully.
    message (string): Confirmation message.
    error (string): Error message if update failed.

tool name="set_due_date"
  description: Set the due date.
  oncall: setDueDate (function)
  Parameters:
    dueDate (string): Due date in YYYY-MM-DD format. Can be empty to clear.
  Returns:
    success (boolean): True if the due date was updated successfully.
    message (string): Confirmation message.
    error (string): Error message if update failed.

tool name="set_priority"
  description: Set the priority.
  oncall: setPriority (function)
  Parameters:
    priority (string): Priority level. Must be one of 'low', 'medium', or 'high'.
  Returns:
    success (boolean): True if the priority was updated successfully.
    message (string): Confirmation message.
    error (string): Error message if update failed.
```

--------------------------------

### Svelte Derived State for App Context

Source: https://github.com/svenschultze/voix/blob/master/examples/svelte-example/README.md

Demonstrates using Svelte 5 derived state to create a complex application context object from multiple state variables. This context can be passed down through components or exposed via a context API.

```svelte
<script>
  let tasks = $state([]);
  let users = $state([]);
  let currentFilter = $state('all');
  
  // Complex derived context
  let appContext = $derived(() => {
    const completedTasks = tasks.filter(t => t.completed);
    const overdueTasks = tasks.filter(t => 
      t.dueDate && new Date(t.dueDate) < new Date() && !t.completed
    );
    
    return {
      totalTasks: tasks.length,
      completedTasks: completedTasks.length,
      overdueTasks: overdueTasks.length,
      activeUsers: users.filter(u => u.isActive).length,
      currentFilter,
      lastUpdate: new Date().toISOString()
    };
  });
</script>

<context name="app_state">
  {JSON.stringify(appContext, null, 2)}
</context>
```

--------------------------------

### Vue Composition API for Tool Logic

Source: https://github.com/svenschultze/voix/blob/master/examples/vue-example/README.md

Illustrates using the Vue Composition API, specifically composables, to organize and manage VOIX tool handling logic within a Vue application, promoting better code structure and TypeScript support.

```javascript
// Use composables for tool logic
const { handleTaskTools } = useTaskTools(tasks);
```

--------------------------------

### Conditional VOIX Tools and Context in Svelte

Source: https://github.com/svenschultze/voix/blob/master/docs/svelte-integration.md

Shows how to conditionally render VOIX tools and context based on application state, such as user roles. This example uses a boolean flag to toggle the visibility of an admin tool and context.

```svelte
<script lang="ts">
  let isAdmin = false;

  const secretAdminAction = () => {
    console.log('Admin action performed');
  };
</script>

{#if isAdmin}
  <tool name="secret_admin_action" description="Perform admin action" oncall={secretAdminAction}>
    <prop name="secret_prop" type="string" required></prop>
  </tool>

  <context name="admin_info">
    Admin tools are available.
  </context>
{/if}

<div>
  <button onclick={() => isAdmin = !isAdmin}>
    Toggle Admin Mode: {isAdmin ? 'On' : 'Off'}
  </button>
</div>
```

--------------------------------

### string

Source: https://github.com/svenschultze/voix/blob/master/docs/de/demo-navigation.md

string

```string
string
```

--------------------------------

### Core UI Styling and Layout

Source: https://github.com/svenschultze/voix/blob/master/docs/demo-navigation.md

Provides essential CSS for the application's layout, including container sizing, navigation bar styling, menu toggling, breadcrumbs, content area, and page sections. Includes responsive adjustments for smaller screens.

```css
#app-container {
  max-width: 800px;
  margin: 0 auto;
}

#main-nav {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 1rem;
  background: #333;
  color: white;
}

.nav-brand {
  font-size: 1.25rem;
  font-weight: bold;
}

.nav-menu {
  display: flex;
  list-style: none;
  margin: 0;
  padding: 0;
  gap: 1rem;
}

.nav-menu a {
  color: white;
  text-decoration: none;
  padding: 0.5rem 1rem;
  border-radius: 4px;
}

.nav-menu a:hover,
.nav-menu a.active {
  background: #555;
}

#menu-toggle {
  display: none;
  background: none;
  border: none;
  color: white;
  font-size: 1.5rem;
  cursor: pointer;
}

.breadcrumb {
  padding: 0.5rem 1rem;
  background: #f0f0f0;
  font-size: 0.875rem;
  color: #666;
}

#content-area {
  padding: 2rem 1rem;
}

.page-section {
  margin: 2rem 0;
  padding: 1rem;
  border-radius: 8px;
  transition: background 0.3s;
}

.page-section.highlight {
  background: #ffffcc;
}

#search-results {
  position: fixed;
  top: 20%;
  left: 50%;
  transform: translateX(-50%);
  background: white;
  border: 2px solid #333;
  border-radius: 8px;
  padding: 1.5rem;
  max-width: 500px;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);
}

@media (max-width: 768px) {
  .nav-menu {
    display: none;
    position: absolute;
    top: 100%;
    left: 0;
    right: 0;
    background: #333;
    flex-direction: column;
    padding: 1rem;
  }
  
  .nav-menu.open {
    display: flex;
  }
  
  #menu-toggle {
    display: block;
  }
}
```

--------------------------------

### HTML Structure for Product Display

Source: https://github.com/svenschultze/voix/blob/master/docs/demo-product-search.md

Provides the HTML structure for displaying search information and a grid of product cards. This includes placeholders for dynamic content updates.

```html
<!-- Context showing search state -->
<context name="search_state" id="search-context">
  Current search: none
  Category filter: all
  Price range: all prices
  Sort: default
  Results: 6 products
</context>

<!-- Product display -->
<div id="product-container">
  <div id="search-info"></div>
  <div id="product-grid"></div>
</div>
```

--------------------------------

### Context Update Function

Source: https://github.com/svenschultze/voix/blob/master/docs/contexts.md

Provides a JavaScript example of a function to update context content dynamically based on application data.

```javascript
// Simple context update
function updateUserContext(user) {
  document.querySelector('context[name="user"]').textContent = 
    `Name: ${user.name}\nRole: ${user.role}`;
}
```

--------------------------------

### navigateTo Function

Source: https://github.com/svenschultze/voix/blob/master/docs/voix_context.md

A Vue.js script setup function that handles navigation to a specified section. It constructs a URL based on the section name and opens it in the current tab.

```javascript
import { ref, onMounted } from 'vue';

import { data } from "./load_context.data.js";

function navigateTo(e) {
    const { section } = e.detail
    const url = `${section}`;
    // go to that url in this tab
    window.open(url, '_self');
}
```

--------------------------------

### Dynamic Context Updates

Source: https://github.com/svenschultze/voix/blob/master/docs/contexts.md

Demonstrates how to dynamically update context content using JavaScript, showing an example of a session state that updates periodically.

```html
<context name="session_state" id="session-context">
  Loading...
</context>
```

```javascript
setInterval(() => {
  document.getElementById('session-context').textContent = 
    `Time: ${new Date().toLocaleTimeString()}`;
}, 10000);
```

--------------------------------

### Parameterdefinition mit Typen und Anforderungen (HTML)

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Zeigt, wie Parameter für ein KI-Werkzeug mit spezifischen Datentypen, Beschreibungen und Pflichtfeldern definiert werden. Dies hilft der KI, die erwarteten Eingaben zu verstehen.

```html
<tool name="create_meeting" description="Ein neues Meeting planen">
  <prop name="title" type="string" required></prop>
  <prop name="date" type="string" description="Datum im YYYY-MM-DD-Format" required></prop>
  <prop name="duration" type="number" description="Dauer in Minuten"></prop>
</tool>
```

--------------------------------

### Common Context Patterns

Source: https://github.com/svenschultze/voix/blob/master/docs/contexts.md

Showcases common patterns for using context elements, including general page descriptions, lists of actions, and system status information.

```html
<context name="page_description">
  This is the user dashboard showing their recent activity and pending tasks. The user has been inactive for the past week but has several overdue items that need attention.
</context>
```

```html
<context name="recent_actions">
  Recent actions:
  - Created document "Q4 Report"
  - Shared with team@example.com
  - Updated project timeline
  - Completed task #42
</context>
```

```html
<context name="system_status">
  Server: Connected
  Sync: Up to date
  Version: 2.1.0
  Environment: Production
</context>
```

--------------------------------

### Context Best Practices: Simplicity and Conciseness

Source: https://github.com/svenschultze/voix/blob/master/docs/contexts.md

Highlights best practices for context content, emphasizing the use of clear, simple plain text and avoiding complex formats like HTML or JSON. It also shows how to be concise by including only relevant information.

```html
<!-- Good: Clear and simple -->
<context name="order_status">
  Order ID: ORD-12345
  Status: Processing
  Items: 3
  Total: $99.99
</context>

<!-- Avoid: Don't use HTML or JSON -->
<context name="order_status">
  {"orderId": "ORD-12345", "status": "processing", "items": 3}
</context>
```

```html
<!-- Good: Relevant information only -->
<context name="search_filters">
  Category: Electronics
  Price range: $100-$500
  In stock only: Yes
</context>

<!-- Avoid: Unnecessary internal details -->
<context name="search_filters">
  Category: Electronics
  Category ID: 123
  Category parent: Technology
  Category created: 2020-01-01
  Price range: $100-$500
  Price currency: USD
  Price includes tax: No
  ...
</context>
```

--------------------------------

### Framework Example: Vue Status Update

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Shows how to use a VOIX tool for updating status within a Vue.js application using the Composition API and event handling.

```vue
<template>
  <tool name="update_status" @call="handleUpdate" description="Status aktualisieren">
    <prop name="status" type="string" required></prop>
  </tool>
</template>

<script setup>
async function handleUpdate(e) {
  const { status } = e.detail;
  await updateStatus(status);
  refreshUI();
}
</script>
```

--------------------------------

### Definition komplexer Parameterstrukturen (HTML)

Source: https://github.com/svenschultze/voix/blob/master/docs/de/tools.md

Veranschaulicht die Definition von Arrays und Objekten als Parameter für KI-Werkzeuge. Dies ermöglicht die Übergabe strukturierter Daten wie Listen von Benutzern mit Rollen.

```html
<tool name="invite_users" description="Benutzer zum Projekt einladen">
  <array name="users" required>
    <dict>
      <prop name="email" type="string" description="Gültige E-Mail-Adresse" required></prop>
      <prop name="role" type="string" description="Entweder 'viewer', 'editor' oder 'admin'"></prop>
    </dict>
  </array>
</tool>
```

--------------------------------

### Angular Component for VOIX Integration

Source: https://github.com/svenschultze/voix/blob/master/docs/angular-integration.md

An Angular component that manages a signal for a secret number and handles the 'change_number' tool call. It updates the secret number based on the event data received from the tool.

```typescript
import { Component, NO_ERRORS_SCHEMA, signal } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styleUrl: './app.css',
  schemas: [NO_ERRORS_SCHEMA],
})
export class App {
  protected readonly secretNumber = signal(42);

  protected changeNumber = (event: Event) => {
    const number = (event as CustomEvent<{ number: number }>).detail.number;
    console.log('changeNumber called with value:', number);
    this.secretNumber.set(number);
  }
}
```
Tokens:
Raw