diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index dc5a26a8c..b2681b4bf 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -142,7 +142,7 @@ export default defineConfig({ { text: 'Quick Start', items: [ - { text: 'Desktop Version', link: withBase('/en/docs/manual/tamagotchi/') }, + { text: 'Desktop ver.', link: withBase('/en/docs/manual/tamagotchi/') }, { text: 'Web Version', link: withBase('/en/docs/manual/web/') }, ], }, @@ -151,30 +151,131 @@ export default defineConfig({ text: 'Configuration', items: [ { text: 'Configuration Guide', link: withBase('/en/docs/manual/config/') }, + { text: 'Common Setup', link: withBase('/en/docs/manual/config/common') }, + { text: 'Feature Configuration', collapsed: true, items: [ + { text: 'Chat Models', link: withBase('/en/docs/manual/config/llm') }, + { text: 'Audio Input and Output', link: withBase('/en/docs/manual/config/audio') }, + { text: 'Vision', link: withBase('/en/docs/manual/config/vision') }, + { text: 'Web Search', link: withBase('/en/docs/manual/config/web-search') }, + ] }, + { text: 'Service Providers', collapsed: true, items: [ + { text: 'Chat', collapsed: true, items: [ + { text: 'AIRI Official Provider', link: withBase('/en/docs/manual/config/providers/consciousness/official') }, + { text: 'AIHubMix', link: withBase('/en/docs/manual/config/providers/consciousness/aihubmix') }, + { text: 'Amazon Bedrock', link: withBase('/en/docs/manual/config/providers/consciousness/amazon-bedrock') }, + { text: 'Anthropic', link: withBase('/en/docs/manual/config/providers/consciousness/anthropic') }, + { text: 'Atlas Cloud', link: withBase('/en/docs/manual/config/providers/consciousness/atlascloud') }, + { text: 'Azure AI Foundry', link: withBase('/en/docs/manual/config/providers/consciousness/azure-ai-foundry') }, + { text: 'Azure OpenAI', link: withBase('/en/docs/manual/config/providers/consciousness/azure-openai') }, + { text: 'BytePlus', link: withBase('/en/docs/manual/config/providers/consciousness/byteplus') }, + { text: 'BytePlus Coding Plan', link: withBase('/en/docs/manual/config/providers/consciousness/byteplus-coding-plan') }, + { text: 'Cerebras', link: withBase('/en/docs/manual/config/providers/consciousness/cerebras') }, + { text: 'Comet API', link: withBase('/en/docs/manual/config/providers/consciousness/comet-api') }, + { text: 'Google Gemini', link: withBase('/en/docs/manual/config/providers/consciousness/google-gemini') }, + { text: 'xAI', link: withBase('/en/docs/manual/config/providers/consciousness/xai') }, + { text: 'Cloudflare Workers AI', link: withBase('/en/docs/manual/config/providers/consciousness/cloudflare-workers-ai') }, + { text: 'LM Studio (Local Model)', link: withBase('/en/docs/manual/config/providers/consciousness/lm-studio') }, + { text: 'OpenPaths', link: withBase('/en/docs/manual/config/providers/consciousness/openpaths') }, + { text: 'OpenRouter', link: withBase('/en/docs/manual/config/providers/consciousness/openrouter') }, + { text: 'Ollama', link: withBase('/en/docs/manual/config/providers/consciousness/ollama') }, + { text: 'DeepSeek', link: withBase('/en/docs/manual/config/providers/consciousness/deepseek') }, + { text: 'OpenAI & Compatible APIs', link: withBase('/en/docs/manual/config/providers/consciousness/openai') }, + { text: '302.AI', link: withBase('/en/docs/manual/config/providers/consciousness/302ai') }, + { text: 'Fireworks.ai', link: withBase('/en/docs/manual/config/providers/consciousness/fireworks') }, + { text: 'Featherless AI', link: withBase('/en/docs/manual/config/providers/consciousness/featherless') }, + { text: 'Groq', link: withBase('/en/docs/manual/config/providers/consciousness/groq') }, + { text: 'MiniMax', link: withBase('/en/docs/manual/config/providers/consciousness/minimax') }, + { text: 'MiniMax Global', link: withBase('/en/docs/manual/config/providers/consciousness/minimax-global') }, + { text: 'Mistral', link: withBase('/en/docs/manual/config/providers/consciousness/mistral') }, + { text: 'Xiaomi MiMo', link: withBase('/en/docs/manual/config/providers/consciousness/mimo') }, + { text: 'ModelScope', link: withBase('/en/docs/manual/config/providers/consciousness/modelscope') }, + { text: 'Moonshot AI', link: withBase('/en/docs/manual/config/providers/consciousness/moonshot') }, + { text: 'NVIDIA NIM', link: withBase('/en/docs/manual/config/providers/consciousness/nvidia') }, + { text: 'n1n', link: withBase('/en/docs/manual/config/providers/consciousness/n1n') }, + { text: 'Novita', link: withBase('/en/docs/manual/config/providers/consciousness/novita') }, + { text: 'Perplexity', link: withBase('/en/docs/manual/config/providers/consciousness/perplexity') }, + { text: 'Together.ai', link: withBase('/en/docs/manual/config/providers/consciousness/together') }, + { text: 'Z.ai', link: withBase('/en/docs/manual/config/providers/consciousness/zhipu') }, + { text: 'Volcengine Coding Plan', link: withBase('/en/docs/manual/config/providers/consciousness/volcengine-coding-plan') }, + ] }, + { text: 'Speech', collapsed: true, items: [ + { text: 'Official Speech Provider', link: withBase('/en/docs/manual/config/providers/speech/official') }, + { text: 'Alibaba Cloud Model Studio', link: withBase('/en/docs/manual/config/providers/speech/alibaba-cloud-model-studio') }, + { text: 'Browser (Local)', link: withBase('/en/docs/manual/config/providers/speech/browser-local') }, + { text: 'Comet API', link: withBase('/en/docs/manual/config/providers/speech/comet-api') }, + { text: 'Deepgram', link: withBase('/en/docs/manual/config/providers/speech/deepgram') }, + { text: 'Desktop (Local)', link: withBase('/en/docs/manual/config/providers/speech/desktop-local') }, + { text: 'ElevenLabs', link: withBase('/en/docs/manual/config/providers/speech/elevenlabs') }, + { text: 'Google Gemini', link: withBase('/en/docs/manual/config/providers/speech/google-gemini') }, + { text: 'Bilibili / IndexTTS', link: withBase('/en/docs/manual/config/providers/speech/index-tts') }, + { text: 'Kokoro TTS (Local)', link: withBase('/en/docs/manual/config/providers/speech/kokoro') }, + { text: 'Microsoft Azure Speech', link: withBase('/en/docs/manual/config/providers/speech/azure-speech') }, + { text: 'MiniMax Speech (Unavailable)', link: withBase('/en/docs/manual/config/providers/speech/minimax') }, + { text: 'Xiaomi MiMo', link: withBase('/en/docs/manual/config/providers/speech/mimo') }, + { text: 'OpenAI & Compatible APIs', link: withBase('/en/docs/manual/config/providers/speech/openai') }, + { text: 'OpenRouter', link: withBase('/en/docs/manual/config/providers/speech/openrouter') }, + { text: 'Player2', link: withBase('/en/docs/manual/config/providers/speech/player2') }, + { text: 'Volcano Engine', link: withBase('/en/docs/manual/config/providers/speech/volcengine') }, + ] }, + { text: 'Transcription', collapsed: true, items: [ + { text: 'Official Transcription Provider', link: withBase('/en/docs/manual/config/providers/transcription/official') }, + { text: 'Aliyun NLS', link: withBase('/en/docs/manual/config/providers/transcription/aliyun') }, + { text: 'Browser (Local)', link: withBase('/en/docs/manual/config/providers/transcription/browser-local') }, + { text: 'Browser Web Speech API', link: withBase('/en/docs/manual/config/providers/transcription/web-speech-api') }, + { text: 'Comet API', link: withBase('/en/docs/manual/config/providers/transcription/comet-api') }, + { text: 'Desktop (Local)', link: withBase('/en/docs/manual/config/providers/transcription/desktop-local') }, + { text: 'Xiaomi MiMo', link: withBase('/en/docs/manual/config/providers/transcription/mimo') }, + { text: 'OpenAI & Compatible APIs', link: withBase('/en/docs/manual/config/providers/transcription/openai') }, + ] }, + { text: 'Artistry', collapsed: true, items: [ + { text: 'ComfyUI (Local Workflow)', link: withBase('/en/docs/manual/config/providers/artistry/comfyui') }, + { text: 'Nano Banana', link: withBase('/en/docs/manual/config/providers/artistry/nanobanana') }, + { text: 'Replicate', link: withBase('/en/docs/manual/config/providers/artistry/replicate') }, + ] }, + ] }, ], }, ], }, { - text: 'Contributing', - icon: 'lucide:users', + text: 'Integration Services', + icon: 'lucide:plug', items: [ { - text: 'Basic Setup', + text: 'Games', items: [ - { text: 'Environment Setup & Prerequisites', link: withBase('/en/docs/contributing/') }, + { text: 'Minecraft Agent', link: withBase('/en/docs/integrations/minecraft') }, + { text: 'Factorio', link: withBase('/en/docs/integrations/factorio') }, + ], + }, + { + text: 'Messaging Platforms', + items: [ + { text: 'Satori Bot', link: withBase('/en/docs/integrations/satori') }, + { text: 'Telegram Bot', link: withBase('/en/docs/integrations/telegram') }, + { text: 'Discord Bot', link: withBase('/en/docs/integrations/discord') }, + { text: 'X / Twitter (Unavailable)', link: withBase('/en/docs/integrations/x') }, + ], + }, + ], + }, + { + text: 'Developer Guide', + icon: 'lucide:code-2', + items: [ + { + text: 'Contributing', + items: [ + { text: 'Development Setup & First Contribution', link: withBase('/en/docs/contributing/') }, { text: 'Desktop App', link: withBase('/en/docs/contributing/tamagotchi') }, - { text: 'Web UI', link: withBase('/en/docs/contributing/webui') }, + { text: 'Web App', link: withBase('/en/docs/contributing/webui') }, { text: 'Documentation Site', link: withBase('/en/docs/contributing/docs') }, ], }, { - text: 'Games & Social Platforms', + text: 'Desktop Debugging', items: [ - { text: 'Minecraft', link: withBase('/en/docs/contributing/services/minecraft') }, - { text: 'Satori Bot', link: withBase('/en/docs/contributing/services/satori') }, - { text: 'Telegram Bot', link: withBase('/en/docs/contributing/services/telegram') }, - { text: 'Discord Bot', link: withBase('/en/docs/contributing/services/discord') }, + { text: 'Developer Tools', link: withBase('/en/docs/contributing/desktop-developer-tools') }, ], }, { diff --git a/docs/.vitepress/theme/theme-markdown.css b/docs/.vitepress/theme/theme-markdown.css index cc0bd2436..93618888d 100644 --- a/docs/.vitepress/theme/theme-markdown.css +++ b/docs/.vitepress/theme/theme-markdown.css @@ -24,6 +24,10 @@ details::details-content { overflow: clip; } +details[open]::details-content { + height: auto; +} + summary { cursor: pointer; transition: transform 200ms ease-in-out; diff --git a/docs/content/en/docs/contributing/design-guidelines/index.md b/docs/content/en/docs/contributing/design-guidelines/index.md index 0b2012be4..c96f72a75 100644 --- a/docs/content/en/docs/contributing/design-guidelines/index.md +++ b/docs/content/en/docs/contributing/design-guidelines/index.md @@ -3,3 +3,11 @@ title: Design Guidelines description: How to contribute design to Project AIRI --- +::: warning Work in progress +This section is still under construction. +::: + +See the pages in the sidebar for more information: + +- [Resources](./resources) +- [Tools](./tools) diff --git a/docs/content/en/docs/contributing/desktop-developer-tools.md b/docs/content/en/docs/contributing/desktop-developer-tools.md new file mode 100644 index 000000000..1949b8efe --- /dev/null +++ b/docs/content/en/docs/contributing/desktop-developer-tools.md @@ -0,0 +1,142 @@ +--- +title: Desktop Developer Tools +description: Use the diagnostic and validation tools under Settings → System → Developer in the Desktop ver. +--- + +The **System → Developer** page in the Desktop ver. contains tools for development, troubleshooting, and validation of experimental features. These tools do not improve everyday chat or character interactions. You do not need to configure them after installation. Use them only to reproduce a problem, develop a feature, or collect diagnostics for a maintainer. + +This page covers the desktop app only. The web app also has development pages, but its available features and runtime environment differ. + +::: warning Know what you are testing +Some tools capture the screen, use the microphone, register global shortcuts, open additional windows, or display raw network and plugin data. Stop capture streams and close unused windows after testing. Do not publicly share screenshots containing API keys, conversations, screen contents, or WebSocket data. +::: + +## Open the page and choose a tool + +In the desktop app, open **Settings → System → Developer**. Quick actions and rendering switches appear at the top; links to individual diagnostic pages appear below. + +Choose a tool based on what you need to investigate: + +| What you need to check | Start with | +| --- | --- | +| Page errors, element styles, or network requests | Open Developer Tools | +| Three.js or VRM rendering diagnostics | Lag Visualizer | +| Broken transition animations | the animation switches | +| Keyboard, mouse, display, or global-shortcut behavior | useMagicKeys, mouse/display tools, or Global Shortcut | +| Chat context, WebSockets, or real-time transcription | Context Flow, WebSocket Inspector, or Aliyun Real-time Transcriber | +| Plugin discovery, loading, or unloading | Plugin Host Debug | +| Failed updates or an unexpected update source | Updater | +| Screen sharing, vision input, or capture permissions | Screen Capture or Vision Capture | + +## Quick actions and rendering diagnostics + +### Open Developer Tools + +Select **Open** to launch Electron's built-in browser developer tools. Use them to inspect console errors, network requests, the DOM, and performance recordings. This is usually the best starting point for an interface problem. + +For a reproducible issue, clear the console, repeat the action once, and save only the relevant errors. Remove sensitive information before attaching diagnostics to an issue or pull request. + +### Markdown Stress + +This tool renders high-volume Markdown in a separate window to test long passages, code blocks, tables, scrolling, and theme styles. It does not modify your documents or conversations. + +### IO Tracer + +IO Tracer shows the timing spans for interaction turns across ASR, LLM, Streaming Control, TTS, and Playback. Use it to locate delays or missing stages in the voice-and-chat pipeline. Trace data can contain contextual information, so open it only when needed and avoid sharing complete traces. + +### Lag Visualizer + +Lag Visualizer traces the Stage Three runtime. It reports the window lifecycle, Three.js render counts and resources, VRM frame-update timing, fade-on-hover hit tests, VRM load and disposal timing, and renderer/resource snapshots. Use it for Three.js or VRM rendering problems; it is not a general page-transition, long-task, or FPS profiler. + +### Stage and page transition animations + +**Disable Stage Transitions** removes the overall animation used when switching stages. Turn it on to remove stage transitions as a variable during testing. **Use Page Specific Transitions** controls each page's own transition and is unavailable while **Disable Stage Transitions** is on. + +When investigating flickering, pages that do not unload, or slow transitions, test each state separately. Restore your normal settings after testing. + +## Keyboard, mouse, and displays + +### useMagicKeys + +This page shows keyboard shortcut and modifier-key state so you can confirm that the app receives key events correctly. It has no regular user settings. To change AIRI's Spotlight shortcut, use **Settings → System → Window Shortcuts** instead. + +### useElectronWindowMouse, Displays, and Relative Mouse + +These tools show pointer positions in different coordinate systems: + +- **useElectronWindowMouse** shows the pointer in the desktop coordinate space formed by all displays. +- **Displays** shows connected displays and the pointer's current location. Use it for multi-display, scaling, or external-monitor problems. +- **Relative Mouse** shows the pointer relative to the AIRI window. Use it to test hit areas and dragging inside the window. + +When reporting window-following, click-offset, or multi-display positioning problems, include the display arrangement, scale factors, primary display, and reproduction steps. + +### Widgets Calling + +Widgets Calling creates overlay widgets and validates the component props passed to them. It is intended for desktop-overlay and component-call development; regular AIRI use does not require it. + +### Beat Sync Visualizer + +Beat Sync Visualizer plots beat-synchronized V-motion targets, paths, and Y/Z scalar changes. Use **Hit beat** or **Hit V sequence** to inject test beats and inspect the resulting motion. This page has no audio input or automatic beat-detection path. + +## Chat, real-time services, and networking + +### Context Flow + +Context Flow shows context updates entering the chat pipeline and chat-stream events sent to services. It is useful for confirming that context from plugins, VS Code, and other external sources reaches AIRI. + +Open the tool first, perform the smallest reproduction, and then compare the input context and output events in chronological order. Context can contain filenames, conversations, or other private information; redact logs before sharing them. + +### WebSocket Inspector + +WebSocket Inspector displays raw WebSocket traffic. Use it for failed connections, missing events, or messages with an unexpected format. Share only the few frames relevant to the problem, and remove tokens, user content, and address information. + +### Aliyun Real-time Transcriber + +This page sends audio from the system's default microphone to Alibaba Cloud NLS and displays the transcription as it arrives. It validates the real-time speech-recognition path: default microphone input, credentials, network connectivity, and transcription output. The page does not provide an input-device selector, so choose the desired default microphone in the operating system before opening it. Record only where you have permission. + +## Plugins, updates, and system features + +### Plugin Host Debug + +Plugin Host Debug shows whether plugins are discovered, enabled, and loaded, and lets developers control their load and unload lifecycle. For a plugin that does not work, check discovery, enabled state, load errors, and whether events or interface state remain after unloading. + +Record the current state and errors before changing anything. Repeatedly loading and unloading a plugin without a minimal reproduction can make the original problem harder to diagnose. + +### Updater + +Updater shows the current version, platform, architecture, update channel, update source, log location, and update state. It can also check for, download, and install updates manually. Use it to investigate failed updates, unexpected update sources, or platform-specific installation problems. + +For routine updates, prefer the **About** window. Do not override the update source unless you understand and trust it. + +## Screen and vision capture + +### Screen Capture + +Screen Capture can capture an application window or an entire display and create a video or audio stream. It is primarily a test page for screen-sharing and capture behavior. + +The operating system may request screen-recording permission on first use. On macOS, if AIRI is not listed, enable or add it under **System Settings → Privacy & Security → Screen & System Audio Recording**, restart AIRI, and try again. Permission prompts on Windows and Linux depend on the operating system, desktop environment, and Electron version. + +In the tool, **Applications** lists application windows and **Displays** lists entire screens. The current implementation does not supply external sources to the **Devices** tab, so that tab remains empty. Use **Refetch** after connecting or disconnecting a display, opening a window, or changing permissions. After stopping, confirm that the preview has closed so the stream no longer uses system resources or permissions. + +### Vision Capture + +Vision Capture captures screen frames and shows the payload sent through the vision pipeline. Use it to verify that vision input is captured correctly and reaches downstream features. It is a diagnostic workflow, not a global switch that must remain open after configuring a vision provider. + +To test screen vision: + +1. Configure a vision provider's credentials under **Settings → Providers → Vision**. +2. Open **Settings → Modules → Vision**, then select the configured provider and an image-capable model. +3. Open **Settings → System → Developer → Vision Capture** and grant the operating system's screen-recording permission. +4. Choose a window or display, then select **Start ticker** to begin capturing and analyzing frames. +5. Enable **Publish to character** only when you want recognition results added to AIRI's conversation context. +6. Select **Stop ticker** when finished. Leaving the page also stops the capture loop. + +If the page remains on a permission prompt, grant permission in the operating system, fully quit AIRI, restart it, and reopen the tool. Never publish captures that show a personal desktop, notifications, or content from other applications. + +## Global shortcuts + +### Global Shortcut + +Global Shortcut registers, unregisters, and observes system-wide shortcut events. It differs from the Spotlight shortcut configured for everyday use under **Settings → System → Window Shortcuts**: this page exists for development and validation. + +Choose a key combination that does not conflict with the operating system or another application. If registration fails, check whether that combination is already in use. Unregister the shortcut after testing so it does not continue intercepting keys. diff --git a/docs/content/en/docs/contributing/docs.md b/docs/content/en/docs/contributing/docs.md index a8e0fea68..2d433958f 100644 --- a/docs/content/en/docs/contributing/docs.md +++ b/docs/content/en/docs/contributing/docs.md @@ -1,20 +1,27 @@ --- -title: Documentation Site -description: Contribute to Project AIRI +title: Documentation Site Development +description: Write, preview, and validate the VitePress documentation locally --- -### Documentation site +The documentation site is in `docs`, with content organized by locale under `docs/content/`. From the repository root, run: ```shell pnpm dev:docs ``` -::: tip +To validate only the documentation site, run: -For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +```shell +pnpm -F @proj-airi/docs typecheck +pnpm -F @proj-airi/docs build +``` + +When adding an English page, also add it to the `en` sidebar in `docs/.vitepress/config.ts`. Otherwise, the page will be available by URL but will not appear in the navigation. + +::: tip +If you use [@antfu/ni](https://github.com/antfu-collective/ni), run: ```shell nr dev:docs ``` - ::: diff --git a/docs/content/en/docs/contributing/index.md b/docs/content/en/docs/contributing/index.md index cf3d6f278..c3588c004 100644 --- a/docs/content/en/docs/contributing/index.md +++ b/docs/content/en/docs/contributing/index.md @@ -1,50 +1,37 @@ --- -title: Contributing -description: Contributing to Project AIRI +title: Development Setup and Your First Contribution +description: Run Project AIRI locally and submit your first pull request --- -Hello! Thank you for your interest in contributing to this project. This guide will help you get started. +Hello! Thank you for your interest in contributing to Project AIRI. This guide explains how to set up a local development environment, create a branch, and submit your first pull request. + +::: info Scope +This section is for contributors who want to change source code, documentation, or design resources. If you only want to use AIRI, start with the user manual. For the debugging tools built into the app, see [Developer Tools](./desktop-developer-tools). +::: ## Prerequisites - [Git](https://git-scm.com/downloads) -- [Node.js 23+](https://nodejs.org/en/download/) -- [corepack](https://github.com/nodejs/corepack) -- [pnpm](https://pnpm.io/installation) +- [mise](https://mise.jdx.dev/installing-mise.html), or another version manager that reads `.tool-versions` +- [Corepack](https://github.com/nodejs/corepack), which is included with recent Node.js releases + +The repository pins Node.js in [`.tool-versions`](https://github.com/moeru-ai/airi/blob/main/.tool-versions) (currently 24.13.0). Install that pinned version after cloning instead of relying on the version supplied by a system package manager.
Windows setup -0. Download [Visual Studio](https://visualstudio.microsoft.com/downloads/), and follow the instructions here: https://rust-lang.github.io/rustup/installation/windows-msvc.html#walkthrough-installing-visual-studio-2022 - - > Make sure to install Windows SDK and C++ build tools when installing Visual Studio. - -1. Open PowerShell -2. Install [`scoop`](https://scoop.sh/) +1. Open PowerShell. +2. Install [`scoop`](https://scoop.sh/). ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression ``` -3. Install `git`, Node.js, `rustup`, `msvc` through `scoop` +3. Install Git and mise with Scoop. ```powershell - scoop install git nodejs rustup - - # For Rust dependencies - # Not required if you are not going to develop on either crates or apps/tamagotchi - scoop install main/rust-msvc - # Rust & Windows specific - rustup toolchain install stable-x86_64-pc-windows-msvc - rustup default stable-x86_64-pc-windows-msvc - ``` - -4. Install `pnpm` through `corepack` - - ```powershell - corepack enable - corepack prepare pnpm@latest --activate + scoop install git mise ```
@@ -52,18 +39,11 @@ Hello! Thank you for your interest in contributing to this project. This guide w
macOS setup -0. Open Terminal, (or iTerm2, Ghostty, Kitty, etc.) -1. Install `git`, `node` through `brew` +1. Open Terminal, iTerm2, Ghostty, Kitty, or another terminal. +2. Install Git and mise with Homebrew. ```shell - brew install git node - ``` - -2. Install `pnpm` through `corepack` - - ```shell - corepack enable - corepack prepare pnpm@latest --activate + brew install git mise ```
@@ -71,152 +51,130 @@ Hello! Thank you for your interest in contributing to this project. This guide w
Linux setup -0. Open Terminal -1. Follow [nodesource/distributions: NodeSource Node.js Binary Distributions](https://github.com/nodesource/distributions?tab=readme-ov-file#table-of-contents) to install `node` -2. Follow [Git](https://git-scm.com/downloads/linux) to install `git` -3. Install `pnpm` through `corepack` - - ```shell - corepack enable - corepack prepare pnpm@latest --activate - ``` -4. If you would love to help to develop the desktop version, you will need those dependencies: - ```shell - sudo apt install \ - libssl-dev \ - libglib2.0-dev \ - libgtk-3-dev \ - libjavascriptcoregtk-4.1-dev \ - libwebkit2gtk-4.1-dev - ``` +1. Open a terminal. +2. Follow the [Git installation instructions for Linux](https://git-scm.com/downloads/linux). +3. Install mise using the [package or installation method for your distribution](https://mise.jdx.dev/installing-mise.html).
-## If you have already contributed to this project before - -::: warning - -If you haven't clone this repository, skip this section. +## If you have contributed before +::: tip +Skip this section if you have not cloned the repository yet. ::: -Make sure your local repository is up to date with the upstream repository: +Fetch upstream changes and rebase your local `main` branch: ```shell git fetch --all -git checkout main +git switch main git pull upstream main --rebase ``` -If you have a working branch, to make your branch up to date with the upstream repository: +If you already have a working branch, update it from `main`: ```shell -git checkout +git switch git rebase main ``` -## Fork this project +## Fork the project -Click on the **Fork** button on the top right corner of the [moeru-ai/airi](https://github.com/moeru-ai/airi) page. +Click **Fork** in the upper-right corner of the [moeru-ai/airi](https://github.com/moeru-ai/airi) repository page to create a copy under your account. -## Clone +## Clone your fork ```shell git clone https://github.com//airi.git cd airi ``` -## Create your working branch +## Create a working branch ```shell -git checkout -b +git switch -c ``` ## Install dependencies -```shell -corepack enable -pnpm install +From the repository root, install the Node.js version recorded in `.tool-versions`, verify it, enable Corepack, and install dependencies: -# For Rust dependencies -# Not required if you are not going to develop on either crates or apps/tamagotchi -cargo fetch +```shell +mise install +mise exec -- node --version +mise exec -- corepack enable +mise exec -- pnpm install +``` + +The reported Node.js version must match `.tool-versions`. The remaining examples assume that [mise is activated for your shell](https://mise.jdx.dev/dev-tools/shims.html); otherwise, run package-manager commands through `mise exec --`, for example `mise exec -- pnpm typecheck`. + +::: tip +You can optionally install [@antfu/ni](https://github.com/antfu-collective/ni) to simplify package-manager commands: + +```shell +mise exec -- npm install --global @antfu/ni +``` + +After installation: + +- Use `ni` instead of `pnpm install`, `npm install`, or `yarn install`. +- Use `nr` instead of `pnpm run`, `npm run`, or `yarn run`. + +`ni` detects the package manager used by the repository. +::: + +## Commit your changes + +### Validate before committing + +Make sure the code passes linting and type checking: + +```shell +pnpm lint +pnpm typecheck ``` ::: tip - -We would recommend to install [@antfu/ni](https://github.com/antfu-collective/ni) to make your script simpler. - -```shell -corepack enable -npm i -g @antfu/ni -``` - -Once installed, you can - -- use `ni` for `pnpm install`, `npm install` and `yarn install`. -- use `nr` for `pnpm run`, `npm run` and `yarn run`. - -You don't need to care about the package manager, `ni` will help you choose the right one. -::: - -## Choose the application you want to develop on - -## Commit - -### Before commit - -::: warning - -Please make sure lint (static checkers) and TypeScript compilers are satisfied: - -```shell -pnpm lint && pnpm typecheck -``` - -::: - -::: tip - -If you have [@antfu/ni](https://github.com/antfu-collective/ni) installed, you can use `nr` to run the commands: +If you installed [@antfu/ni](https://github.com/antfu-collective/ni), run: ```shell nr lint && nr typecheck ``` - ::: -### Commit +### Create the commit ```shell -git add . +git add git commit -m "" ``` -### Push to your fork repository +### Push your branch ```shell -git push origin -u +git push -u origin ``` -You should be able to browse the branch on your fork repository. +Your branch should now be available on GitHub. ::: tip - -If this is your first time contributing with this project, you need to add the upstream repository too: +If this is your first contribution, add the Project AIRI repository as the `upstream` remote: ```shell git remote add upstream https://github.com/moeru-ai/airi.git ``` - ::: -## Creating Pull Request +## Create a pull request -Navigate to [moeru-ai/airi](https://github.com/moeru-ai/airi) page, click on the **Pull requests** tab, and click on the **New pull request** button, click on the **Compare across forks** link, and select your fork repository. +Open the [moeru-ai/airi](https://github.com/moeru-ai/airi) repository page: -Review the changes, and click on the **Create pull request** button. +1. Click **Pull requests**. +2. Click **New pull request**. +3. Click **Compare across forks**. +4. Select your fork and working branch. +5. Review the changes, then click **Create pull request**. -## Whooo-ya! You made it! +## You made it! -Congratulations! You made your first contribution to this project. You can now wait for the maintainers to review your pull request. +Congratulations on submitting your first contribution. The project maintainers can now review your pull request. diff --git a/docs/content/en/docs/contributing/services/discord.md b/docs/content/en/docs/contributing/services/discord.md deleted file mode 100644 index 18b8b0bef..000000000 --- a/docs/content/en/docs/contributing/services/discord.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Discord Bot -description: Contribute to Project AIRI ---- - -### Discord bot integration - -```shell -cd integrations/discord-bot -``` - -Configure `.env` - -```shell -cp .env .env.local -``` - -Edit the credentials in `.env.local`. - -Run the bot - -```shell -pnpm -F @proj-airi/discord-bot start -``` - -::: tip - -For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can - -```shell -nr -F @proj-airi/discord-bot dev -``` - -::: diff --git a/docs/content/en/docs/contributing/services/minecraft.md b/docs/content/en/docs/contributing/services/minecraft.md deleted file mode 100644 index 82533cb7e..000000000 --- a/docs/content/en/docs/contributing/services/minecraft.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Minecraft -description: Contribute to Project AIRI ---- - -### Minecraft agent - -```shell -cd integrations/minecraft -``` - -Start a Minecraft client, export your world with desired port, and fill-in the port number in `.env.local`. - -Configure `.env` - -```shell -cp .env .env.local -``` - -Edit the credentials in `.env.local`. - -Run the bot - -```shell -pnpm -F @proj-airi/minecraft-bot start -``` - -::: tip - -For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can - -```shell -nr -F @proj-airi/minecraft-bot dev -``` - -::: diff --git a/docs/content/en/docs/contributing/services/satori.md b/docs/content/en/docs/contributing/services/satori.md deleted file mode 100644 index 484b73c12..000000000 --- a/docs/content/en/docs/contributing/services/satori.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Satori Bot -description: Contribute to Project AIRI ---- - -### Satori Bot - -```shell -cd integrations/satori-bot -``` - -Configure the `.env` file: - -```shell -cp .env .env.local -``` - -Edit various keys and configuration information in `.env.local`. - -Start the bot: - -```shell -pnpm -F @proj-airi/satori-bot dev -``` - -::: tip - -If you use [@antfu/ni](https://github.com/antfu-collective/ni), you can: - -```shell -nr -F @proj-airi/satori-bot dev -``` - -::: diff --git a/docs/content/en/docs/contributing/services/telegram.md b/docs/content/en/docs/contributing/services/telegram.md deleted file mode 100644 index 62df7507e..000000000 --- a/docs/content/en/docs/contributing/services/telegram.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Telegram Bot -description: Contribute to Project AIRI ---- - -### Telegram bot integration - -A Postgres database is required. - -```shell -cd integrations/telegram-bot -docker compose up -d -``` - -Configure `.env` - -```shell -cp .env .env.local -``` - -Edit the credentials in `.env.local`. - -Migrate the database - -```shell -pnpm -F @proj-airi/telegram-bot db:generate -pnpm -F @proj-airi/telegram-bot db:push -``` - -Run the bot - -```shell -pnpm -F @proj-airi/telegram-bot start -``` - -::: tip - -For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can - -```shell -nr -F @proj-airi/telegram-bot dev -``` - -::: diff --git a/docs/content/en/docs/contributing/tamagotchi.md b/docs/content/en/docs/contributing/tamagotchi.md index 78c7bed19..8335d31b7 100644 --- a/docs/content/en/docs/contributing/tamagotchi.md +++ b/docs/content/en/docs/contributing/tamagotchi.md @@ -1,20 +1,29 @@ --- -title: Desktop -description: Contribute to Project AIRI +title: Desktop Development +description: Run, check, and build the Electron desktop app --- -### Stage Tamagotchi (Desktop version) +The desktop app is in `apps/stage-tamagotchi`. From the repository root, run: ```shell pnpm dev:tamagotchi ``` -::: tip +This starts the Electron development environment. Before changing desktop pages, check whether the relevant shared component or state already exists in `packages/stage-ui`. Logic used by both the web and desktop apps should normally live in a shared package. -For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +## Validation + +```shell +pnpm -F @proj-airi/stage-tamagotchi typecheck +pnpm -F @proj-airi/stage-tamagotchi build +``` + +For the **System → Developer** menu and the purpose of each debugging tool, see [Developer Tools](./desktop-developer-tools). + +::: tip +If you use [@antfu/ni](https://github.com/antfu-collective/ni), run: ```shell nr dev:tamagotchi ``` - ::: diff --git a/docs/content/en/docs/contributing/webui.md b/docs/content/en/docs/contributing/webui.md index 5c1bd4d57..6cd56f8a8 100644 --- a/docs/content/en/docs/contributing/webui.md +++ b/docs/content/en/docs/contributing/webui.md @@ -1,20 +1,31 @@ --- -title: Web UI -description: Contribute to Project AIRI +title: Web App Development +description: Run, check, and build the AIRI web app --- -### Stage Web (Browser version for [airi.moeru.ai](https://airi.moeru.ai)) +The web app is in `apps/stage-web` and powers [airi.moeru.ai](https://airi.moeru.ai). From the repository root, run: ```shell pnpm dev ``` -::: tip +You can also use the more explicit command: -For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +```shell +pnpm dev:web +``` + +## Validation + +```shell +pnpm -F @proj-airi/stage-web typecheck +pnpm -F @proj-airi/stage-web build +``` + +::: tip +If you use [@antfu/ni](https://github.com/antfu-collective/ni), run: ```shell nr dev ``` - ::: diff --git a/docs/content/en/docs/integrations/discord.md b/docs/content/en/docs/integrations/discord.md new file mode 100644 index 000000000..7a9bfc57f --- /dev/null +++ b/docs/content/en/docs/integrations/discord.md @@ -0,0 +1,64 @@ +--- +title: Discord Bot +description: Run AIRI as a voice and messaging bot using a Discord application +--- + +The Discord bot connects to text and voice channels in a Discord server. Text replies come from the chat provider and model selected in AIRI. + +## Prerequisites + +- Install dependencies from the repository root with **pnpm i**. +- Create an application and bot in the [Discord Developer Portal](https://discord.com/developers/home). +- Enable **Message Content Intent** in the bot settings. +- Configure a working chat provider and model in AIRI. + +::: warning Credential security +Keep the Bot Token and AIRI Auth Token only in AIRI's local settings or the bot service's local **.env.local** file. Do not commit, screenshot, or share these credentials. +::: + +## Configure the bot service + +```bash +cp integrations/discord-bot/.env integrations/discord-bot/.env.local +``` + +In the Desktop ver., open **Settings → Connection**. Show and copy the **Auth Token**. Then add these values to **integrations/discord-bot/.env.local**: + +```env +AIRI_URL=ws://localhost:6121/ws +AIRI_TOKEN= +``` + +`DISCORD_TOKEN` is an optional startup fallback. You can leave it empty and send the Bot Token from AIRI after the service connects. The service does not use `DISCORD_BOT_CLIENT_ID`, `OPENAI_MODEL`, `OPENAI_API_*`, or `ELEVENLABS_*`; Discord text replies use AIRI's active chat configuration. + +For Discord voice input, configure an OpenAI-compatible transcription endpoint with `OPENAI_STT_API_BASE_URL`, `OPENAI_STT_API_KEY`, and `OPENAI_STT_MODEL`. These values are not required for text channels, but voice transcription cannot complete without them. + +## Start the service + +```bash +pnpm -F @proj-airi/discord-bot start +``` + +## Configure Discord in AIRI + +1. Open **Settings → Modules → Discord**. +2. Paste the bot token into **Bot Token**. +3. Turn on **Enable Discord Integration**. +4. Click **Save**. + +The authenticated bot service receives the enabled state and token through AIRI's configuration channel. If the service is not running or its AIRI Auth Token is missing or incorrect, saving these fields alone does not start the Discord bot. + +## Install and use the bot in Discord + +1. In the Discord Developer Portal, configure a **Guild Install** with the `bot` scope and install the bot in your server. The `bot` scope includes `applications.commands` by default. Grant only the permissions required by the features you use: + - Text replies: **View Channels** and **Send Messages**. + - Voice input: **View Channels** and **Connect**. + - Voice playback: **Speak**. +2. For text chat, send the bot a direct message or mention it in a server channel. The bot does not respond to every server message. +3. For voice input, join a voice channel and run `/summon`. The service registers `/ping` and `/summon` after the bot logs in. + +If the bot works in some channels but not others, check the channel-level permission overrides. + +## Security notes + +Limit the bot's access to the channels and capabilities it needs. If the Bot Token is lost or exposed, reset it immediately in the Discord Developer Portal. diff --git a/docs/content/en/docs/integrations/factorio.md b/docs/content/en/docs/integrations/factorio.md new file mode 100644 index 000000000..ff1e266d6 --- /dev/null +++ b/docs/content/en/docs/integrations/factorio.md @@ -0,0 +1,30 @@ +--- +title: Factorio +description: Connect AIRI to a trusted Factorio server +--- + +The Factorio integration connects AIRI to an external game service. The Desktop ver. provides settings for the server address, port, and player name. You must supply a reachable Factorio server and a compatible server-side integration. + +## Prerequisites + +- A reachable Factorio server. +- Permission from the server administrator for your account and server-side integration to connect. +- The server address, port, and your in-game username. + +::: warning Connect only to trusted servers +This integration exchanges context and action requests with the game server. Do not use it with an untrusted public server, and do not expose server addresses, tokens, or account information in public chats, screenshots, or issues. +::: + +## Configure in AIRI + +1. Open **Settings → Modules → Factorio**. +2. Enable **Factorio Integration**. +3. Enter the server address, port, and your in-game username. The default port is `34197`. +4. Click **Save**. A **configured** status only means that all three fields have values; an actual connection still depends on the server and its server-side integration. + +## Troubleshooting + +- Check that the device running AIRI can reach the server address and port. +- Confirm that no firewall, VPN, or server allowlist blocks the connection. +- Confirm that the username matches the player name on the server. +- If the settings are saved but AIRI still cannot interact, inspect the server-side integration logs. The Desktop ver. does not include a ready-to-deploy Factorio bot service. diff --git a/docs/content/en/docs/integrations/minecraft.md b/docs/content/en/docs/integrations/minecraft.md new file mode 100644 index 000000000..2a55c2836 --- /dev/null +++ b/docs/content/en/docs/integrations/minecraft.md @@ -0,0 +1,46 @@ +--- +title: Minecraft Agent +description: Run AIRI's local game agent on a trusted Minecraft server +--- + +The Minecraft integration uses Mineflayer to connect AIRI to a Minecraft server so the agent can receive context, perform in-game actions, and report state. It is intended for local development and maintenance. The current implementation is planned to migrate to a Fabric runtime, so avoid building new long-term features around it. + +## Prerequisites + +- Install dependencies from the repository root with **pnpm i**. +- Provide a reachable local or trusted Minecraft server. The connection address and port come from the environment configuration. +- Configure a working chat provider and model in AIRI, and prepare the OpenAI-compatible model settings used by the Minecraft agent. + +::: warning Credential security +Keep API keys, service addresses, and Minecraft server credentials only in the local **.env.local** file. Do not commit, screenshot, or share these values. +::: + +## Configure + +```bash +cp integrations/minecraft/.env integrations/minecraft/.env.local +``` + +Edit **integrations/minecraft/.env.local** and provide the required Minecraft server, AIRI, and model-service settings. + +In the Desktop ver., open **Settings → Connection**. Show and copy the **Auth Token**. Then add these AIRI channel settings: + +```env +AIRI_WS_BASEURL=ws://localhost:6121/ws +AIRI_CLIENT_NAME=minecraft-bot +AIRI_WS_TOKEN= +``` + +Also configure `BOT_HOSTNAME`, `BOT_PORT`, and the `OPENAI_API_BASEURL`, `OPENAI_API_KEY`, `OPENAI_MODEL`, and `OPENAI_REASONING_MODEL` values required by your server and model service. Keep the defaults only when they match your local setup. + +## Start + +```bash +pnpm -F @proj-airi/minecraft-bot dev +``` + +After startup, use the terminal output to verify that authentication to AIRI succeeds and that the agent connects to the Minecraft server. A missing or incorrect `AIRI_WS_TOKEN` prevents the module from registering with AIRI. + +## Security and limitations + +Do not connect the agent to an untrusted public server. It controls a local Minecraft session and network connection. Even when action planning runs in an isolated environment, a malicious server may still cause unexpected behavior. diff --git a/docs/content/en/docs/integrations/satori.md b/docs/content/en/docs/integrations/satori.md new file mode 100644 index 000000000..84f5fe34f --- /dev/null +++ b/docs/content/en/docs/integrations/satori.md @@ -0,0 +1,34 @@ +--- +title: Satori Bot +description: Bridge AIRI to multiple messaging platforms through Koishi and the Satori protocol +--- + +The Satori bot connects to messaging platforms such as QQ, Telegram, Discord, and Lark through Koishi's Satori service. The current standalone core is transitional and is suitable for experiments and maintenance; it should not be treated as a stable AIRI Core integration. + +## Prerequisites + +- Install dependencies from the repository root with **pnpm i**. +- Run a Koishi instance with the **server-satori** plugin enabled. +- Provide a model service with an OpenAI-compatible API. + +::: warning Credential security +Keep the Satori token, messaging-platform credentials, and model API keys only in the local **.env.local** file. Do not commit, screenshot, or share these values. +::: + +## Configure + +```bash +cp integrations/satori-bot/.env integrations/satori-bot/.env.local +``` + +Edit **integrations/satori-bot/.env.local** and provide **SATORI_WS_URL**, **SATORI_API_BASE_URL**, the optional **SATORI_TOKEN**, and the LLM address, key, and model. + +## Start + +```bash +pnpm -F @proj-airi/satori-bot dev +``` + +## Notes + +Messaging-platform addresses, tokens, and model credentials are sensitive. Do not commit **.env.local** or send its contents to anyone. diff --git a/docs/content/en/docs/integrations/telegram.md b/docs/content/en/docs/integrations/telegram.md new file mode 100644 index 000000000..8ec447e96 --- /dev/null +++ b/docs/content/en/docs/integrations/telegram.md @@ -0,0 +1,52 @@ +--- +title: Telegram Bot +description: Run AIRI as a Telegram bot using PostgreSQL and model services +--- + +The Telegram bot requires a Telegram Bot Token, a PostgreSQL vector database, and model services. The repository Compose service runs PostgreSQL with pgvecto.rs 0.4.0 in pgvector compatibility mode. The bot is intended to be run from source. + +## Prerequisites + +- Install dependencies from the repository root with **pnpm i**. +- Create a Telegram bot with [@BotFather](https://t.me/BotFather) and obtain its token. +- Make Docker available to start the repository's PostgreSQL vector service. +- Prepare chat-model and embedding-model services. + +::: warning Credential security +Keep the Telegram Bot Token, database connection, and model API keys only in the local **.env.local** file. Do not commit, screenshot, or share these values. +::: + +## Configure + +```bash +cp integrations/telegram-bot/.env integrations/telegram-bot/.env.local +``` + +Edit **integrations/telegram-bot/.env.local** and provide **TELEGRAM_BOT_TOKEN**, the database connection, and the chat-model and embedding-model settings. The embedding service's output size must match `EMBEDDING_DIMENSION`; supported values are `768`, `1024`, and `1536`. + +## Initialize the database + +```bash +cd integrations/telegram-bot +docker compose up -d --wait pgvector +cd ../.. +pnpm -F @proj-airi/telegram-bot db:push +``` + +The repository Compose file exposes PostgreSQL on host port `5433`. When using that service, set: + +```env +DATABASE_URL=postgres://postgres:123456@localhost:5433/postgres +``` + +Starting only `pgvector` avoids launching the optional Grafana, Tempo, Prometheus, and OpenTelemetry services. + +## Start + +```bash +pnpm -F @proj-airi/telegram-bot start +``` + +## Notes + +The database, Telegram token, and model credentials are sensitive. Do not commit **.env.local**. Before the first deployment, also confirm the database backup and access-control arrangements. diff --git a/docs/content/en/docs/integrations/x.md b/docs/content/en/docs/integrations/x.md new file mode 100644 index 000000000..ec2b53ca5 --- /dev/null +++ b/docs/content/en/docs/integrations/x.md @@ -0,0 +1,26 @@ +--- +title: X / Twitter (unavailable) +description: Current implementation status of AIRI's X / Twitter integration +--- + +The X / Twitter integration is not functional in AIRI 0.11.3. Although **Settings → Modules → X / Twitter** displays credential fields and can show **configured**, the app cannot currently deliver that configuration to the separate X service. + +::: warning Do not enter X credentials + +Do not enter an API Key, API Secret, Access Token, or Access Token Secret in the current version. The **configured** state means only that all four fields contain values; it does not confirm a working service connection. +::: + +## Current limitation + +Before investigating the protocol mismatch, contributors must start the external process with `ENABLE_AIRI=true`, `AIRI_URL=ws://localhost:6121/ws`, and an `AIRI_TOKEN` that matches **Settings → Connection → Auth Token**. The checked-in defaults disable the AIRI adapter, point it to `http://localhost:3000`, and provide no token. Correcting these settings only allows the service to connect; it does not repair the incompatible configuration flow described below. + +The AIRI module publishes configuration under the module name `twitter`, while the external service expects `x`. The channel protocols also disagree: the server forwards configuration as `module:configure` with a `{ config }` payload, but the service listens for `ui:configure` and expects a `moduleName` field. The external service also runs as a separate process and is not started by AIRI. Fixing only the module name or starting the service manually is therefore not enough to make the form work. + +There is no supported end-user workaround. Contributors investigating the implementation can compare: + +- `packages/stage-ui/src/stores/modules/twitter.ts` +- `integrations/twitter-services/src/adapters/airi-adapter.ts` + +## Credential security + +If you previously entered credentials, remove them from AIRI and rotate them in the [X Developer Portal](https://developer.x.com/en/portal/dashboard) if they may have been exposed. Never commit, screenshot, or share X credentials. diff --git a/docs/content/en/docs/manual/config/audio.md b/docs/content/en/docs/manual/config/audio.md new file mode 100644 index 000000000..ab8ace327 --- /dev/null +++ b/docs/content/en/docs/manual/config/audio.md @@ -0,0 +1,41 @@ +--- +title: Configure voice input and output +description: Configuring AIRI for speech synthesis (TTS) and speech recognition (ASR/STT) +--- + +Speech synthesis (TTS) reads AIRI's text responses aloud; speech recognition (ASR/STT) converts microphone audio into text. You can configure either capability independently. + +## Configure speech synthesis (TTS) + +1. Open **Settings → Providers → Speech**, select a provider, and enter its credentials. +2. Use the provider playground, when available, to synthesize a short test sentence. +3. Open **Settings → Modules → Speech** and select the configured provider, model, and voice. + +See **Service Providers → Speech** in the sidebar for provider-specific instructions. If your provider implements the OpenAI speech interface, see [OpenAI Compatible API (TTS)](./providers/speech/openai.md). + +## Configure speech recognition (ASR/STT) + +1. Open **Settings → Providers → Transcription**, select a provider, and enter its credentials. +2. Open **Settings → Modules → Hearing** and select the configured provider and model. +3. Select the correct microphone, click **Start Monitoring**, and say a brief sentence. +4. Confirm that the text appears correctly in the recognition result area. + +See **Service Providers → Transcription** in the sidebar for provider-specific instructions. If your provider supports the OpenAI-compatible transcription interface, see [OpenAI Compatible API (ASR/STT)](./providers/transcription/openai.md). + +## FAQ + +### TTS no sound + +Confirm that the Speech provider, model, and voice are selected, and check the system output device and volume. If the playground reports an error, check the API key, account credit, and model capabilities. + +### ASR produces no text + +Confirm that AIRI has permission to the microphone and that the correct input device is selected on the Hearing page. For real-time recognition services, network outages or browser/system microphone permissions being revoked can also result in empty results. + +### Incorrect language or voice + +Select a model and voice that the provider supports for the target language. Transcription language, region, and model settings must match the capabilities enabled for the provider account. + +## Next step + +For field and validation details, read [Common Configuration Instructions](./common.md). Provider-specific guides are under **Providers → Speech** and **Providers → Transcription**. diff --git a/docs/content/en/docs/manual/config/common.md b/docs/content/en/docs/manual/config/common.md new file mode 100644 index 000000000..b1aaa248e --- /dev/null +++ b/docs/content/en/docs/manual/config/common.md @@ -0,0 +1,45 @@ +--- +title: General configuration instructions +description: Understand AIRI's provider configuration flow, fields, and verification methods +--- + +This page explains how AIRI's provider configuration works. For a provider's API endpoint, account setup, and model selection, see its provider-specific guide. + +## Configuration process + +1. Open **Settings → Providers** and select **Chat**, **Vision**, **Speech**, **Transcription**, or **Artistry**. +2. Select a provider and enter the credentials required by its settings page. +3. If necessary, expand the advanced settings and enter the Base URL or other parameters from the provider's documentation. +4. Wait for automatic validation. Where available, use **Ping API** or the provider playground for a live test. +5. Select the provider and model or voice on the corresponding page under **Settings → Modules**. + +::: warning Credential security +Credentials and provider settings are saved in the current device's local settings. Never disclose credentials such as API keys or AccessKey Secrets in screenshots, logs, issues, or chat messages. +::: + +## Common fields + +| Field | Meaning | Guidance | +| --- | --- | --- | +| API Key | Access token issued by the provider | Paste the complete key without adding quotes or spaces. | +| Base URL | Root URL of the provider API | Change it only when the provider's documentation requires another URL. Include the complete `https://` or `http://` address. | +| Model | Model ID used for chat, speech, or recognition | Prefer a model from AIRI's list. If the list cannot be loaded and the field accepts custom input, enter the exact ID from the provider's documentation. | +| Voice | Voice ID used for speech synthesis | Select the model first, then select a voice supported by that model. | +| Region | Deployment region used by some cloud services | Match the project or resource region shown in the provider console. | + +## Verification results + +Chat-provider forms validate required fields automatically; providers that expose **Ping API** can also send a live request, which may consume a small amount of credit. Speech-provider playgrounds test synthesis and playback when available. Test transcription from **Settings → Modules → Hearing** with the selected microphone. + +When verification fails, troubleshoot in this order: + +1. Confirm that the account has access to the service and available credit or quota. +2. Copy the API Key again and make sure you did not include leading or trailing spaces or line breaks. +3. Restore the default Base URL, or compare it exactly with the provider's official documentation. +4. Confirm that the network, proxy, and firewall allow access to the provider. +5. Choose a model that is explicitly supported by the provider; do not use the display name as a model ID. + +## Next + +- To configure text replies, read [Configure a chat model](./llm.md). +- To configure speech output or microphone input, read [Configure voice input and output](./audio.md). diff --git a/docs/content/en/docs/manual/config/index.md b/docs/content/en/docs/manual/config/index.md index db76e4c2c..7de90ae8c 100644 --- a/docs/content/en/docs/manual/config/index.md +++ b/docs/content/en/docs/manual/config/index.md @@ -1,48 +1,56 @@ --- -title: Configuration Guide -description: How to use Project AIRI +title: Provider configuration guide +description: Configure Chat, Vision, Speech, Transcription, and Artistry providers for Project AIRI --- -## Settings +To chat with AIRI, configure at least one Chat provider and chat model. Speech synthesis (TTS) adds voice output, while automatic speech recognition (ASR/STT) adds microphone input. Voice input and output are optional and can be configured independently. -You can open settings in the system tray for further customization, for example, -changing the theme color of AIRI, or switching to another model, either -Live2D (2D) or VRM (3D, like Grok Companion). +## Configure the minimum required setup -