basic-usage.md

Updated basic usage docs

Author: atvonsc

docs/docs/guides/basic-usage.md

@@ -6,97 +6,201 @@ sidebar_position: 5
 
 This guide covers the fundamental concepts and patterns for using Eliza in your applications.
 
+## Prerequisites
+
+- Node.js 20+ required
+- PNPM for package management
+
+## Installation
+
+```bash
+pnpm install eliza
+
+# Database adapters
+pnpm install sqlite-vss better-sqlite3 # for SQLite (local development)
+pnpm install @supabase/supabase-js # for Supabase (production)
+
+# Optional - for Linux
+pnpm install --include=optional sharp
+```
+
+## Environment Setup
+
+Copy .env.example to .env and configure:
+
+```bash
+# Required
+OPENAI_API_KEY="sk-*" # OpenAI API key, starting with sk-
+XAI_MODEL="gpt-4o-mini" # Model selection (see below)
+
+# Model Selection Options
+XAI_MODEL=gpt-4o-mini                                   # OpenAI GPT-4
+XAI_MODEL=meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo # Llama 70B
+XAI_MODEL=meta-llama/Meta-Llama-3.1-405B-Instruct      # Llama 405B
+XAI_MODEL=grok-beta                                     # Grok  
+
+# Optional - Model Configuration
+LOCALAI_URL="http://localhost:8080"
+LOCALAI_TOKEN="your-token"
+ANTHROPIC_API_KEY="your-claude-api-key"
+
+# Optional - Database (for production)
+POSTGRES_URL="postgres://user:pass@host:5432/db"  # Add this line
+SUPABASE_URL="https://your-supabase-url.supabase.co"
+SUPABASE_SERVICE_API_KEY="your-supabase-service-api-key"
+
+# Optional - Platform Integration
+DISCORD_TOKEN="your-discord-token"
+TELEGRAM_BOT_TOKEN="your-telegram-token"
+TWITTER_USERNAME="your-twitter-username"
+TWITTER_PASSWORD="your-twitter-password"
+
+# Optional - Voice Support
+ELEVENLABS_XI_API_KEY="your-elevenlabs-key"
+ELEVENLABS_MODEL_ID="eleven_multilingual_v2"
+ELEVENLABS_VOICE_ID="21m00Tcm4TlvDq8ikWAM"
+ELEVENLABS_VOICE_STABILITY=0.5
+ELEVENLABS_VOICE_SIMILARITY_BOOST=0.9
+ELEVENLABS_VOICE_STYLE=0.66
+ELEVENLABS_VOICE_USE_SPEAKER_BOOST=false
+ELEVENLABS_OPTIMIZE_STREAMING_LATENCY=4
+ELEVENLABS_OUTPUT_FORMAT=pcm_16000
+```
+
 ## Creating an Agent Runtime
 
-The first step is to initialize an agent runtime with your desired configuration:
+Initialize with SQLite (local development):
+
+```typescript
+import { createAgentRuntime, Database } from "eliza";
+import { initializeDatabase, ModelProvider } from "eliza";
+
+// Initialize database (SQLite locally, Postgres in production)
+const db = initializeDatabase();
+
+// Get token for model provider (supports character-specific keys)
+const token = getTokenForProvider(ModelProvider.OPENAI, character);
+
+// Create runtime with default configuration
+const runtime = await createAgentRuntime(
+  character,
+  db,
+  token,
+  "./elizaConfig.yaml"
+);
 ```
-import { AgentRuntime, SqliteDatabaseAdapter } from "eliza";
-import { Database } from "sqlite3";
-const sqliteDatabaseAdapter = new SqliteDatabaseAdapter(new Database(":memory:"));
-const runtime = new AgentRuntime({
-serverUrl: "https://api.openai.com/v1",
-token: process.env.OPENAI_API_KEY,
-databaseAdapter: sqliteDatabaseAdapter,
-model: "gpt-3.5-turbo",
-embeddingModel: "text-embedding-3-small"
-});
+
+For production with Supabase:
+
+```typescript
+import { SupabaseDatabaseAdapter } from "eliza";
+
+const db = new SupabaseDatabaseAdapter(
+  process.env.SUPABASE_URL,
+  process.env.SUPABASE_SERVICE_API_KEY
+);
 ```
 
-## Loading Characters
+## Working with Characters
+
+You can either:
+- Modify the default character in `src/core/defaultCharacter.ts`
+- Create a custom character file:
 
-Characters can be loaded from JSON files:
 ```json
 {
-"name": "character_name",
-"bio": [],
-"lore": [],
-"knowledge": [],
-"style": {}
+  "name": "character_name",
+  "settings": {
+    "secrets": {
+      "OPENAI_API_KEY": "optional-character-specific-key",
+      "CLAUDE_API_KEY": "optional-character-specific-key"
+    }
+  },
+  "bio": [],
+  "lore": [],
+  "knowledge": [],
+  "messageExamples": [],
+  "postExamples": [],
+  "topics": [],
+  "style": {},
+  "adjectives": [],
+  "clients": ["discord", "telegram", "twitter"]
 }
 ```
 
-Load the character:
-```
+Load characters:
+
+```bash
 node --loader ts-node/esm src/index.ts --characters="path/to/your/character.json"
 ```
 
-## Working with Memory
+## Basic Memory Management
 
-Process different types of content:
-```
-// Process documents
+Process documents and text:
+
+```typescript
+// Basic document processing
 await runtime.processDocument("path/to/document.pdf");
 await runtime.processUrl("https://example.com");
 await runtime.processText("Important information");
 ```
 
-Use the knowledge management tools:
+Use built-in knowledge tools:
+
 ```bash
-npx folder2knowledge ./docs
-npx knowledge2character my-character.json knowledge.json
+npx folder2knowledge <path/to/folder>
+npx knowledge2character <character-file> <knowledge-file>
 ```
 
 ## Platform Integration
 
-Set up Discord integration:
-```
-import { DiscordConnector } from "eliza";
-const discord = new DiscordConnector({
-token: process.env.DISCORD_TOKEN,
-runtime: runtime
-});
-await discord.start();
-```
+Before initializing clients, ensure:
+1. The desired clients are configured in your character file's `clients` array
+2. Required environment variables are set for each platform:
+   - Discord: DISCORD_TOKEN
+   - Telegram: TELEGRAM_BOT_TOKEN
+   - Twitter: TWITTER_USERNAME and TWITTER_PASSWORD
 
-Set up Twitter integration:
-```
-import { TwitterConnector } from "eliza";
-const twitter = new TwitterConnector({
-username: process.env.TWITTER_USERNAME,
-password: process.env.TWITTER_PASSWORD,
-runtime: runtime
-});
-await twitter.start();
-```
+For help with setting up your Discord Bot, check out: https://discordjs.guide/preparations/setting-up-a-bot-application.html
 
+Initialize all configured clients:
 
-## Development Commands
+```typescript
+import { initializeClients } from "eliza";
 
-Start the server:
-```bash
-pnpm run dev
+// Initialize all configured clients
+const clients = await initializeClients(character, runtime);
 ```
 
+## Development Commands
 
-Start the interactive shell:
 ```bash
-pnpm run shell
+pnpm run dev    # Start the server
+pnpm run shell  # Start interactive shell
 ```
+## Runtime Components
+
+The runtime includes these built-in components:
+
+### Actions
+- Default actions from defaultActions
+- followRoom/unfollowRoom
+- muteRoom/unmuteRoom
+- imageGeneration
+- Custom actions from elizaConfig.yaml
+
+### Providers
+- timeProvider
+- boredomProvider
 
+See [Advanced Features](./advanced) for adding custom actions and providers.
 ## Next Steps
 
 - Learn about [Configuration](./configuration) options
-- Explore [Advanced Features](./advanced)
+- Explore [Advanced Features](./advanced) including:
+  - Audio/video processing
+  - Advanced memory management
+  - Custom actions and evaluators
 - Read about [Character Files](./characterfile)
 
 For API details, see the [API Reference](../api).