@myscheme/voice-navigation-sdk 0.1.0 → 0.1.3

package/README.md

@@ -2,32 +2,35 @@
 
 A TypeScript SDK for voice-controlled navigation using Azure Speech-to-Text and AWS Bedrock for intent understanding.
 
-## Features
+## 🚀 Features
 
-- 🎤 Real-time speech recognition using Azure Speech SDK
-- 🤖 Intent extraction using AWS Bedrock (Claude)
-- 🧭 Voice-controlled navigation actions
-- 🖱️ Rich browser and media controls
-- ♿ Accessibility-first design
-- 🎨 Customizable floating UI control
-- 📦 Full TypeScript support
+- 🎤 **Real-time speech recognition** using Azure Speech SDK
+- 🤖 **AI-powered intent extraction** using AWS Bedrock (Claude)
+- 🌐 **Dynamic page navigation** via XML configuration
+- 🧭 **Voice-controlled navigation** actions
+- 🖱️ **Rich browser and media controls**
+- ♿ **Accessibility-first design**
+- 🎨 **Customizable floating UI** control
+- 📦 **Full TypeScript support**
+- 🔄 **Reusable across multiple websites**
+- 🔍 **Vector search integration** with OpenSearch
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @myscheme/voice-navigation-sdk
 ```
 
-## Dependencies
+### Dependencies
 
-This SDK requires:
+The following packages are automatically installed:
 
-- `@aws-sdk/client-bedrock-runtime` - For AWS Bedrock integration
-- `microsoft-cognitiveservices-speech-sdk` - For Azure Speech-to-Text
+- `@aws-sdk/client-bedrock-runtime` - AWS Bedrock integration
+- `microsoft-cognitiveservices-speech-sdk` - Azure Speech-to-Text
 
-These are automatically installed as dependencies.
+## 🎯 Quick Start
 
-## Quick Start
+### Basic Setup
 
 ```typescript
 import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
@@ -36,7 +39,7 @@ const controller = initNavigationOnMicrophone({
   // Azure Speech configuration
   azure: {
     subscriptionKey: "your-azure-subscription-key",
-    region: "your-azure-region", // e.g., 'eastus'
+    region: "centralindia", // e.g., 'eastus', 'westus'
   },
 
   // AWS Bedrock configuration
@@ -44,7 +47,7 @@ const controller = initNavigationOnMicrophone({
     accessKeyId: "your-aws-access-key-id",
     secretAccessKey: "your-aws-secret-access-key",
     modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
-    region: "ap-south-1", // or your preferred region
+    region: "ap-south-1",
   },
 
   // Optional: Default language
@@ -55,9 +58,28 @@ const controller = initNavigationOnMicrophone({
 });
 ```
 
-## Configuration
+### With Dynamic Pages
 
-### NavigationConfig
+```typescript
+const controller = initNavigationOnMicrophone({
+  azure: {
+    /* ... */
+  },
+  aws: {
+    /* ... */
+  },
+
+  // Dynamic page navigation
+  pages: {
+    xml: "/navigation-pages.xml",
+    xmlType: "url", // or "string" for inline XML
+  },
+});
+```
+
+## ⚙️ Configuration
+
+### NavigationConfig Options
 
 | Property                | Type      | Required | Description                                    |
 | ----------------------- | --------- | -------- | ---------------------------------------------- |
@@ -69,64 +91,193 @@ const controller = initNavigationOnMicrophone({
 | `aws.region`            | `string`  | ❌       | AWS region (default: 'ap-south-1')             |
 | `language`              | `string`  | ❌       | Speech recognition language (default: 'en-IN') |
 | `autoStart`             | `boolean` | ❌       | Auto-start voice control (default: false)      |
-| `actionHandlers`        | `object`  | ❌       | Map of custom callbacks keyed by action        |
+| `actionHandlers`        | `object`  | ❌       | Custom action callbacks                        |
+| `pages`                 | `object`  | ❌       | Dynamic page navigation configuration          |
 | `opensearch`            | `object`  | ❌       | OpenSearch vector search configuration         |
 
-When you provide the optional `opensearch` block, include the following fields:
-
-| Property        | Type     | Required | Description                                                        |
-| --------------- | -------- | -------- | ------------------------------------------------------------------ |
-| `node`          | `string` | ✅       | OpenSearch cluster URL (e.g. `https://cluster.example.com`)        |
-| `username`      | `string` | ✅       | OpenSearch user name                                               |
-| `password`      | `string` | ✅       | OpenSearch password                                                |
-| `index`         | `string` | ✅       | Index name containing your embeddings                              |
-| `vectorField`   | `string` | ❌       | Embedding field (default: `embedding`)                             |
-| `size`          | `number` | ❌       | Result count returned to the browser (default: `5`)                |
-| `numCandidates` | `number` | ❌       | Candidate pool size for k-NN search (default: `Math.max(size*4,20)`)|
-| `minScore`      | `number` | ❌       | Minimum score to accept a hit (default: `0`)                       |
-| `sourceFields`  | `string[]` | ❌     | Source fields to request from OpenSearch                           |
-| `apiPath`       | `string` | ❌       | Browser endpoint that proxies vector search (default: `/api/voice-navigation/vector-search`) |
-
-## Supported Actions
-
-The SDK supports the following voice commands:
-
-### Navigation Actions
-
-- `navigate_home` - Navigate to home page
-- `navigate_search` - Navigate to search page
-- `navigate_faqs` - Navigate to FAQs
-- `navigate_help` - Navigate to help
-- `navigate_contact` - Navigate to contact
-- `navigate_about` - Navigate to about
-- `navigate_screen_reader` - Navigate to screen reader access
-- `navigate_accessibility` - Navigate to accessibility page
-- `navigate_disclaimer` - Navigate to disclaimer
-- `navigate_terms_conditions` - Navigate to terms and conditions
-
-### Page & UI Actions
-
-- `zoom_in` / `zoom_out` - Adjust page zoom
-- `scroll_up` / `scroll_down` / `scroll_left` / `scroll_right` - Scroll in any direction
-- `page_up` / `page_down` - Jump by one viewport height
-- `scroll_top` / `scroll_bottom` - Jump to page edges
-- `go_back` / `go_forward` - Navigate browser history
-- `reload_page` - Reload current page
-- `print_page` - Open print dialog
-- `copy_url` - Copy current page URL to clipboard
-- `open_menu` / `close_menu` - Toggle navigation menus
-- `focus_search` - Focus the primary search input
-- `toggle_fullscreen` / `exit_fullscreen` - Control fullscreen mode
-- `play_media` / `pause_media` - Control media playback
-- `mute_media` / `unmute_media` - Control media volume
+### OpenSearch Configuration
+
+When providing the optional `opensearch` block:
+
+| Property        | Type       | Required | Description                                                     |
+| --------------- | ---------- | -------- | --------------------------------------------------------------- |
+| `node`          | `string`   | ✅       | OpenSearch cluster URL                                          |
+| `username`      | `string`   | ✅       | OpenSearch username                                             |
+| `password`      | `string`   | ✅       | OpenSearch password                                             |
+| `index`         | `string`   | ✅       | Index name containing embeddings                                |
+| `vectorField`   | `string`   | ❌       | Embedding field (default: `embedding`)                          |
+| `size`          | `number`   | ❌       | Result count (default: `5`)                                     |
+| `numCandidates` | `number`   | ❌       | k-NN candidates (default: `Math.max(size*4,20)`)                |
+| `minScore`      | `number`   | ❌       | Minimum match score (default: `0`)                              |
+| `sourceFields`  | `string[]` | ❌       | Source fields to retrieve                                       |
+| `apiPath`       | `string`   | ❌       | Proxy endpoint (default: `/api/voice-navigation/vector-search`) |
+
+## 🌐 Dynamic Page Navigation
+
+Instead of hardcoding page navigation, configure pages dynamically using XML or direct configuration.
+
+### Method 1: XML File (Recommended)
+
+**Create XML file** (`public/navigation-pages.xml`):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<navigation>
+  <pages>
+    <page
+      id="home"
+      name="Home"
+      path="/"
+      keywords="main,homepage,start"
+      description="Main homepage"
+    />
+
+    <page
+      id="about"
+      name="About"
+      path="/about"
+      keywords="information,company"
+      description="About us page"
+    />
+
+    <page
+      id="contact"
+      name="Contact"
+      path="/contact"
+      keywords="reach,support,help"
+      description="Contact information"
+    />
+  </pages>
+</navigation>
+```
+
+**Configure SDK:**
+
+```typescript
+const controller = initNavigationOnMicrophone({
+  // ... azure & aws config ...
+  pages: {
+    xml: "/navigation-pages.xml",
+    xmlType: "url",
+  },
+});
+```
+
+### Method 2: Remote XML URL
+
+```typescript
+pages: {
+  xml: "https://yoursite.com/api/navigation-pages.xml",
+  xmlType: "url",
+}
+```
+
+### Method 3: Inline XML String
+
+```typescript
+const xmlConfig = `<?xml version="1.0" encoding="UTF-8"?>
+<navigation>
+  <pages>
+    <page id="home" name="Home" path="/" />
+    <page id="about" name="About" path="/about" />
+  </pages>
+</navigation>`;
+
+pages: {
+  xml: xmlConfig,
+  xmlType: "string",
+}
+```
+
+### Method 4: Direct Configuration
+
+```typescript
+pages: {
+  pages: [
+    {
+      id: "home",
+      name: "Home",
+      path: "/",
+      keywords: ["main", "start"]
+    },
+    {
+      id: "about",
+      name: "About",
+      path: "/about",
+      keywords: ["information", "company"]
+    },
+  ],
+}
+```
+
+### XML Schema Reference
+
+**Required attributes:**
+
+- `id` - Unique identifier (creates `navigate_<id>` action)
+- `name` - Display name for the page
+- `path` - URL path to navigate to
+
+**Optional attributes:**
+
+- `keywords` - Comma-separated keywords for voice matching
+- `description` - Page description
+
+### Voice Command Examples
+
+With the configuration above, users can say:
+
+- "Go to home" → navigates to `/`
+- "Open about page" → navigates to `/about`
+- "Show me contact" → navigates to `/contact`
+- "Take me to the team page" → navigates to `/team`
+
+## 🎬 Supported Actions
+
+### Dynamic Page Navigation
+
+Configure your own pages (see above). Each page automatically gets a `navigate_<id>` action.
+
+### Core Navigation Actions
+
+**Scrolling:**
+
+- `scroll_up` / `scroll_down`
+- `scroll_left` / `scroll_right`
+- `scroll_top` / `scroll_bottom`
+- `page_up` / `page_down`
+
+**Zoom:**
+
+- `zoom_in` / `zoom_out`
+
+**Browser:**
+
+- `go_back` / `go_forward`
+- `reload_page`
+- `print_page`
+- `copy_url`
+
+**UI Controls:**
+
+- `open_menu` / `close_menu`
+- `focus_search`
+- `toggle_fullscreen` / `exit_fullscreen`
+
+**Media:**
+
+- `play_media` / `pause_media`
+- `mute_media` / `unmute_media`
+
+**Other:**
+
+- `search_content` - Vector search (requires OpenSearch)
 - `stop` - Stop voice control
 
-## API Reference
+## 📚 API Reference
 
 ### VoiceNavigationController
 
-The main controller class for voice navigation.
-
 #### Methods
 
 ##### `start(): Promise<void>`
@@ -139,7 +290,7 @@ await controller.start();
 
 ##### `stop(): Promise<void>`
 
-Stop voice control and process any pending speech.
+Stop voice control and process pending speech.
 
 ```typescript
 await controller.stop();
@@ -171,64 +322,199 @@ controller.destroy();
 
 ### Events
 
-The SDK emits custom events that you can listen for:
+Listen for SDK events:
 
 ```typescript
-// Listen for state changes
+// State changes
 window.addEventListener("navigate:state-change", (event) => {
   console.log("State:", event.detail.state);
 });
 
-// Listen for action detection
+// Action detection
 window.addEventListener("navigate:action-detected", (event) => {
   console.log("Action:", event.detail.action);
 });
 
-// Listen for action performance
+// Action performance
 window.addEventListener("navigate:action-performed", (event) => {
   console.log("Performed:", event.detail.performed);
 });
 
-// Listen for errors
+// Errors
 window.addEventListener("navigate:error", (event) => {
   console.error("Error:", event.detail.error);
 });
 ```
 
-## Advanced Usage
+## 🔧 Framework Integration Examples
 
-### Vector Search with OpenSearch
+### React
+
+```typescript
+import { useEffect, useRef } from "react";
+import { VoiceNavigationController } from "@myscheme/voice-navigation-sdk";
+
+export function VoiceNavigation() {
+  const controllerRef = useRef<VoiceNavigationController | null>(null);
+
+  useEffect(() => {
+    controllerRef.current = new VoiceNavigationController({
+      azure: {
+        subscriptionKey: import.meta.env.VITE_AZURE_SPEECH_KEY,
+        region: import.meta.env.VITE_AZURE_SPEECH_REGION,
+      },
+      aws: {
+        accessKeyId: import.meta.env.VITE_AWS_ACCESS_KEY_ID,
+        secretAccessKey: import.meta.env.VITE_AWS_SECRET_ACCESS_KEY,
+        modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
+        region: "ap-south-1",
+      },
+      pages: {
+        xml: "/navigation-pages.xml",
+        xmlType: "url",
+      },
+      language: "en-US",
+      autoStart: false,
+    });
+
+    return () => {
+      controllerRef.current?.destroy();
+    };
+  }, []);
+
+  return null;
+}
+```
 
-1. Supply OpenSearch credentials to the client when you initialise the library:
+### Next.js (App Router)
 
 ```typescript
+// app/providers/voice-navigation-provider.tsx
+"use client";
+
+import { useEffect } from "react";
+import { VoiceNavigationController } from "@myscheme/voice-navigation-sdk";
+
+export function VoiceNavigationProvider() {
+  useEffect(() => {
+    const controller = new VoiceNavigationController({
+      azure: {
+        subscriptionKey: process.env.NEXT_PUBLIC_AZURE_SPEECH_KEY!,
+        region: process.env.NEXT_PUBLIC_AZURE_SPEECH_REGION!,
+      },
+      aws: {
+        accessKeyId: process.env.NEXT_PUBLIC_AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.NEXT_PUBLIC_AWS_SECRET_ACCESS_KEY!,
+        modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
+        region: "ap-south-1",
+      },
+      pages: {
+        xml: "/navigation-pages.xml",
+        xmlType: "url",
+      },
+    });
+
+    return () => controller.destroy();
+  }, []);
+
+  return null;
+}
+
+// app/layout.tsx
+import { VoiceNavigationProvider } from "./providers/voice-navigation-provider";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <VoiceNavigationProvider />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+### Next.js (Pages Router)
+
+```javascript
+// pages/_app.js
+import { useEffect, useRef } from "react";
 import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
 
+export default function App({ Component, pageProps }) {
+  const voiceControllerRef = useRef(null);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    try {
+      voiceControllerRef.current = initNavigationOnMicrophone({
+        azure: {
+          subscriptionKey: process.env.NEXT_PUBLIC_AZURE_SPEECH_KEY,
+          region: process.env.NEXT_PUBLIC_AZURE_SPEECH_REGION,
+        },
+        aws: {
+          accessKeyId: process.env.NEXT_PUBLIC_AWS_ACCESS_KEY_ID,
+          secretAccessKey: process.env.NEXT_PUBLIC_AWS_SECRET_ACCESS_KEY,
+          modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
+          region: "ap-south-1",
+        },
+        pages: {
+          xml: "/navigation-pages.xml",
+          xmlType: "url",
+        },
+        language: "en-IN",
+        autoStart: false,
+      });
+    } catch (error) {
+      console.error("Failed to initialize voice navigation:", error);
+    }
+
+    return () => {
+      voiceControllerRef.current?.destroy?.();
+      voiceControllerRef.current = null;
+    };
+  }, []);
+
+  return <Component {...pageProps} />;
+}
+```
+
+## 🚀 Advanced Usage
+
+### Vector Search with OpenSearch
+
+**1. Configure SDK with OpenSearch:**
+
+```typescript
 initNavigationOnMicrophone({
-  azure: { /* ... */ },
-  aws: { /* ... */ },
+  azure: {
+    /* ... */
+  },
+  aws: {
+    /* ... */
+  },
   opensearch: {
     node: process.env.NEXT_PUBLIC_OPENSEARCH_NODE!,
     username: process.env.NEXT_PUBLIC_OPENSEARCH_USERNAME!,
     password: process.env.NEXT_PUBLIC_OPENSEARCH_PASSWORD!,
     index: "my-embeddings-index",
-    // optional overrides:
-    // vectorField: "embedding",
-    // size: 5,
-    // apiPath: "/api/voice-navigation/vector-search",
+    vectorField: "embedding",
+    size: 5,
+    apiPath: "/api/voice-navigation/vector-search",
   },
 });
 ```
 
-2. Expose a server-side proxy so the browser never talks to OpenSearch directly. In a Next.js project, create a route such as `pages/api/voice-navigation/vector-search.ts`:
+**2. Create proxy endpoint** (`pages/api/voice-navigation/vector-search.ts`):
 
 ```typescript
 import type { NextApiRequest, NextApiResponse } from "next";
 import { createOpenSearchProxyHandler } from "@myscheme/voice-navigation-sdk/server";
 
 const handler = createOpenSearchProxyHandler({
-  // Optionally lock down allowed origins for CORS style checks.
-  allowedOrigins: process.env.OPENSEARCH_ALLOWED_ORIGINS?.split(",") ?? undefined,
+  allowedOrigins: process.env.OPENSEARCH_ALLOWED_ORIGINS?.split(","),
 });
 
 export default async function vectorSearchProxy(
@@ -238,7 +524,6 @@ export default async function vectorSearchProxy(
   await handler(req, res);
 }
 
-// Disable Next.js body parsing so the proxy can stream the incoming payload.
 export const config = {
   api: {
     bodyParser: false,
@@ -246,11 +531,9 @@ export const config = {
 };
 ```
 
-Mount the route at the same `apiPath` you configured on the client (defaults to `/api/voice-navigation/vector-search`). The handler lives in the `@myscheme/voice-navigation-sdk/server` export so it only runs on the server where the official OpenSearch client is available.
-
 ### Custom Service Initialization
 
-You can use the individual services separately:
+Use individual services separately:
 
 ```typescript
 import {
@@ -277,9 +560,30 @@ const bedrockService = new BedrockService({
 const action = await bedrockService.extractAction("zoom in");
 ```
 
-### Custom Action Handlers
+### Programmatic Page Management
+
+```typescript
+import { PageRegistry, setPageRegistry } from "@myscheme/voice-navigation-sdk";
+
+// Create custom registry
+const registry = new PageRegistry([
+  { id: "home", name: "Home", path: "/" },
+  { id: "about", name: "About", path: "/about" },
+]);
+
+// Add pages dynamically
+registry.addPage({
+  id: "blog",
+  name: "Blog",
+  path: "/blog",
+  keywords: ["articles", "posts"],
+});
+
+// Set as global registry
+setPageRegistry(registry);
+```
 
-You can perform actions programmatically:
+### Custom Action Handlers
 
 ```typescript
 import { performAgentAction } from "@myscheme/voice-navigation-sdk";
@@ -292,68 +596,217 @@ console.log("Action performed:", result.performed);
 console.log("New zoom:", result.info.newZoom);
 ```
 
-## Configuration Tips
+## 🐛 Troubleshooting
+
+### Pages Not Loading
+
+**Symptoms:**
+
+- Voice commands navigate to wrong page
+- `navigate_search` is triggered instead of page-specific actions
+- Console shows "Unknown action"
+
+**Solutions:**
+
+1. **Check XML file exists:**
+
+   - File should be in `public/` folder
+   - Verify URL: `http://localhost:3000/navigation-pages.xml`
+
+2. **Validate XML syntax:**
+
+   ```xml
+   <?xml version="1.0" encoding="UTF-8"?>
+   <navigation>
+     <pages>
+       <page id="unique_id" name="Display Name" path="/path" />
+     </pages>
+   </navigation>
+   ```
+
+3. **Check browser console:**
+
+   - Look for `[VoiceNavigation]` messages
+   - Should see: "✓ Page registry initialized with X pages"
+
+4. **Debug in console:**
+
+   ```javascript
+   console.log("Registry size:", window.__navigatePageRegistry?.size);
+   console.log("Pages:", window.__navigatePageRegistry?.getAllPages());
+   ```
+
+5. **Clear cache and hard refresh:**
+   - Clear Next.js cache: `rm -rf .next`
+   - Hard refresh browser: `Ctrl+Shift+R` / `Cmd+Shift+R`
+
+### Voice Not Recognized
+
+**Solutions:**
+
+- Check microphone permissions
+- Reduce background noise
+- Speak clearly at normal pace
+- Ensure microphone is working in other apps
 
-Because this SDK executes in the browser, protect your credentials:
+### Wrong Page Navigation
 
-- Use short-lived tokens (AWS Cognito, STS) instead of long-term keys.
-- Proxy Bedrock requests through a backend service when possible.
-- Keep Azure Speech keys in secured storage and rotate them regularly.
-- Provide configuration values via runtime injection, not hard-coded literals.
+**Solutions:**
 
-## Browser Support
+- Add more specific keywords to pages
+- Make page names more distinct
+- Remove overlapping keywords
+- Use exact page names in commands
 
-This SDK requires:
+### SDK Initialization Fails
 
-- Modern browser with ES2020 support
+**Solutions:**
+
+- Check all required config values are provided
+- Verify AWS credentials are valid
+- Confirm Azure subscription key is active
+- Check browser console for error messages
+
+### Testing Checklist
+
+- [ ] XML file accessible in browser
+- [ ] Pages config in SDK initialization
+- [ ] Browser console shows successful load
+- [ ] `window.__navigatePageRegistry.size > 0`
+- [ ] No 404 errors in Network tab
+- [ ] Hard refresh after changes
+
+## 💡 Best Practices
+
+### Security
+
+1. **Never expose credentials in client code:**
+
+   ```typescript
+   // ❌ BAD
+   aws: {
+     accessKeyId: "AKIAXXXXXXXX",
+     secretAccessKey: "xxxxxxxxxxxxx",
+   }
+
+   // ✅ GOOD
+   aws: {
+     accessKeyId: process.env.NEXT_PUBLIC_AWS_ACCESS_KEY_ID!,
+     secretAccessKey: process.env.NEXT_PUBLIC_AWS_SECRET_ACCESS_KEY!,
+   }
+   ```
+
+2. **Use temporary credentials:**
+
+   - AWS Cognito for user-specific tokens
+   - STS for temporary access keys
+   - API Gateway with authorization
+
+3. **Implement backend proxy:**
+   - Proxy Bedrock requests through your server
+   - Never expose AWS keys to the browser
+   - Use environment-specific configurations
+
+### Performance
+
+1. **Use XML files over direct config** for better caching
+2. **Add specific keywords** to reduce AI processing time
+3. **Limit the number of pages** to essential navigation
+4. **Enable auto-start carefully** (consider user experience)
+
+### User Experience
+
+1. **Clear page names:** Use descriptive, unique names
+2. **Relevant keywords:** Include synonyms and common phrases
+3. **Test voice commands:** Try different phrasings
+4. **Provide UI feedback:** Listen for SDK events
+5. **Handle errors gracefully:** Show helpful error messages
+
+### Page Configuration
+
+1. **Use descriptive IDs:** `privacy_policy` not `pp`
+2. **Add multiple keywords:** Cover variations and synonyms
+3. **Keep paths accurate:** Match your actual routes
+4. **Start small:** Begin with core pages, expand gradually
+5. **Test variations:** Try different voice commands
+
+## 🌐 Browser Support
+
+**Requirements:**
+
+- Modern browser with ES2020+ support
 - Microphone access
-- `MediaDevices` API support
-- `fetch` API support
+- `MediaDevices` API
+- `fetch` API
+- `DOMParser` (for XML)
 
-## Security Notes
+**Tested on:**
 
-⚠️ **Important**: Never expose your AWS credentials or API keys in client-side code in production. Consider using:
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
 
-- AWS Cognito for temporary credentials
-- API Gateway with authorization
-- Backend proxy for sensitive operations
+## 🔒 Security Considerations
 
-For development, you can use environment variables and a build tool to inject them securely.
+⚠️ **Important Security Notes:**
 
-## Migration from Script
+1. **Credential Protection:**
 
-If you're migrating from the previous script-based approach:
+   - Never hardcode AWS/Azure credentials
+   - Use environment variables
+   - Rotate keys regularly
+   - Use least-privilege IAM policies
 
-### Before (Script)
+2. **Production Setup:**
 
-```javascript
-// navigation_myscheme.js included in HTML
-// API routes in Next.js pages/api/
-```
+   - Implement AWS Cognito for temporary credentials
+   - Use API Gateway for request authorization
+   - Proxy sensitive operations through backend
+   - Enable CloudWatch logging for monitoring
 
-### After (Library)
+3. **Best Practices:**
+   - Validate all user inputs
+   - Sanitize XML content
+   - Implement rate limiting
+   - Monitor API usage
+   - Use HTTPS only
 
-```typescript
-import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
+## 📄 Environment Variables
 
-const controller = initNavigationOnMicrophone({
-  azure: {
-    /* config */
-  },
-  aws: {
-    /* config */
-  },
-});
+Create `.env.local` (Next.js) or `.env` file:
+
+```bash
+# AWS Bedrock
+NEXT_PUBLIC_AWS_REGION=ap-south-1
+NEXT_PUBLIC_AWS_ACCESS_KEY_ID=your_access_key_here
+NEXT_PUBLIC_AWS_SECRET_ACCESS_KEY=your_secret_key_here
+
+# Azure Speech
+NEXT_PUBLIC_AZURE_SPEECH_KEY=your_subscription_key_here
+NEXT_PUBLIC_AZURE_SPEECH_REGION=centralindia
+
+# OpenSearch (Optional)
+NEXT_PUBLIC_OPENSEARCH_NODE=https://your-cluster.example.com
+NEXT_PUBLIC_OPENSEARCH_USERNAME=your_username
+NEXT_PUBLIC_OPENSEARCH_PASSWORD=your_password
+NEXT_PUBLIC_OPENSEARCH_INDEX=your_index
 ```
 
-## License
+## 📝 License
 
 MIT
 
-## Contributing
+## 🤝 Contributing
+
+Contributions are welcome! This library is currently in beta phase.
+
+## 📧 Support
+
+For issues and questions, please open an issue on the repository.
 
-Contributions are welcome! Please open an issue or submit a pull request.
+## 🎯 Version
 
-## Support
+Current version: **0.1.0 (Beta)**
 
-For issues and questions, please open an issue on GitHub.
+This library is under active development. APIs may change between releases.