@elizaos/plugin-web-search 0.1.7-alpha.2 → 0.1.8-alpha.1

package/README.MD

@@ -0,0 +1,225 @@
+# @elizaos/plugin-web-search
+
+A plugin for powerful web search capabilities, providing efficient search query handling and result processing through a customizable API interface.
+
+## Overview
+
+This plugin provides functionality to:
+
+- Execute web search queries with customizable parameters
+- Process and format search results
+- Handle search API authentication
+- Manage token limits and response sizes
+- Optimize query performance
+
+## Installation
+
+```bash
+pnpm install @elizaos/plugin-web-search
+```
+
+## Configuration
+
+The plugin requires the following environment variables:
+
+```env
+TAVILY_API_KEY=your_api_key    # Required: API key for search service
+```
+
+## Usage
+
+Import and register the plugin in your Eliza configuration:
+
+```typescript
+import { webSearchPlugin } from "@elizaos/plugin-web-search";
+
+export default {
+    plugins: [webSearchPlugin],
+    // ... other configuration
+};
+```
+
+## Features
+
+### Web Search
+
+The plugin provides comprehensive web search capabilities:
+
+```typescript
+import { webSearch } from "@elizaos/plugin-web-search";
+
+// Execute a search query
+const result = await webSearch.handler(
+    runtime,
+    {
+        content: { text: "What is the latest news about AI?" },
+    },
+    state,
+    {},
+    callback
+);
+```
+
+### Token Management
+
+```typescript
+// The plugin automatically handles token limits
+const DEFAULT_MAX_WEB_SEARCH_TOKENS = 4000;
+
+// Example of token-limited response
+const response = MaxTokens(searchResult, DEFAULT_MAX_WEB_SEARCH_TOKENS);
+```
+
+## Development
+
+### Building
+
+```bash
+pnpm run build
+```
+
+### Testing
+
+```bash
+pnpm run test
+```
+
+### Development Mode
+
+```bash
+pnpm run dev
+```
+
+## Dependencies
+
+- `@elizaos/core`: Core Eliza functionality
+- `js-tiktoken`: Token counting and management
+- `tsup`: Build tool
+- Other standard dependencies listed in package.json
+
+## API Reference
+
+### Core Interfaces
+
+```typescript
+interface Action {
+    name: "WEB_SEARCH";
+    similes: string[];
+    description: string;
+    validate: (runtime: IAgentRuntime, message: Memory) => Promise<boolean>;
+    handler: (
+        runtime: IAgentRuntime,
+        message: Memory,
+        state: State,
+        options: any,
+        callback: HandlerCallback
+    ) => Promise<void>;
+    examples: Array<Array<any>>;
+}
+
+interface SearchResult {
+    title: string;
+    url: string;
+    answer?: string;
+    results?: Array<{
+        title: string;
+        url: string;
+    }>;
+}
+```
+
+### Plugin Methods
+
+- `webSearch.handler`: Main method for executing searches
+- `generateWebSearch`: Core search generation function
+- `MaxTokens`: Token limit management function
+- `getTotalTokensFromString`: Token counting utility
+
+## Common Issues/Troubleshooting
+
+### Issue: API Authentication Failures
+
+- **Cause**: Invalid or missing Tavily API key
+- **Solution**: Verify TAVILY_API_KEY environment variable
+
+### Issue: Token Limit Exceeded
+
+- **Cause**: Search results exceeding maximum token limit
+- **Solution**: Results are automatically truncated to fit within limits
+
+### Issue: Search Rate Limiting
+
+- **Cause**: Too many requests in short time
+- **Solution**: Implement proper request throttling
+
+## Security Best Practices
+
+- Store API keys securely using environment variables
+- Validate all search inputs
+- Implement proper error handling
+- Keep dependencies updated
+- Monitor API usage and rate limits
+- Use HTTPS for API communication
+
+## Example Usage
+
+```typescript
+// Basic search
+const searchQuery = "Latest developments in quantum computing";
+const results = await generateWebSearch(searchQuery, runtime);
+
+// With formatted response
+if (results && results.results.length) {
+    const formattedResponse = `${results.answer}\n\nFor more details, check out:\n${results.results
+        .map(
+            (result, index) => `${index + 1}. [${result.title}](${result.url})`
+        )
+        .join("\n")}`;
+}
+```
+
+## Configuration Options
+
+### Token Management
+
+```typescript
+const DEFAULT_MODEL_ENCODING = "gpt-3.5-turbo";
+const DEFAULT_MAX_WEB_SEARCH_TOKENS = 4000;
+```
+
+### Search Actions
+
+The plugin includes multiple search action similes:
+
+- SEARCH_WEB
+- INTERNET_SEARCH
+- LOOKUP
+- QUERY_WEB
+- FIND_ONLINE
+- And more...
+
+## Contributing
+
+Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
+
+## Credits
+
+This plugin integrates with and builds upon several key technologies:
+
+- [Tavily API](https://tavily.com/): Advanced search and content analysis API
+- [js-tiktoken](https://github.com/dqbd/tiktoken): Token counting for API responses
+- [Zod](https://github.com/colinhacks/zod): TypeScript-first schema validation
+
+Special thanks to:
+
+- The Eliza community for their contributions and feedback
+
+For more information about the search capabilities and tools:
+
+- [Tavily API Documentation](https://docs.tavily.com/)
+- [Token Management Guide](https://github.com/dqbd/tiktoken#readme)
+- [Search API Best Practices](https://docs.tavily.com/docs/guides/best-practices)
+
+## License
+
+This plugin is part of the Eliza project. See the main project repository for license information.

package/package.json

@@ -1,19 +1,33 @@
 {
-  "name": "@elizaos/plugin-web-search",
-  "version": "0.1.7-alpha.2",
-  "main": "dist/index.js",
-  "type": "module",
-  "types": "dist/index.d.ts",
-  "dependencies": {
-    "@elizaos/core": "0.1.7-alpha.2",
-    "tsup": "8.3.5"
-  },
-  "scripts": {
-    "build": "tsup --format esm --dts",
-    "dev": "tsup --format esm --dts --watch"
-  },
-  "peerDependencies": {
-    "whatwg-url": "7.1.0"
-  },
-  "gitHead": "256e6634696074cdb38f3f79bc383fed04376688"
+    "name": "@elizaos/plugin-web-search",
+    "version": "0.1.8-alpha.1",
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "import": {
+                "@elizaos/source": "./src/index.ts",
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@elizaos/core": "0.1.8-alpha.1",
+        "tsup": "8.3.5"
+    },
+    "scripts": {
+        "build": "tsup --format esm --dts",
+        "dev": "tsup --format esm --dts --watch"
+    },
+    "peerDependencies": {
+        "whatwg-url": "7.1.0"
+    },
+    "gitHead": "d5f2924d866c21b54543637b694695bd1f410621"
 }

package/Readme.md

@@ -1,180 +0,0 @@
-# Plugin Web Search
-
-## Overview
-
-The Web Search Plugin enables powerful and customizable web search capabilities, offering flexibility and ease of integration for modern applications.
-
-## Features
-
-- Efficient search query handling.
-- Configurable options for advanced customization.
-- Optimized for performance and scalability.
-
-## Handlers
-
-### `search`
-
-The `search` handler executes web search queries with specified parameters, returning results in a structured format.
-
-#### Usage
-
-```typescript
-import { WebSearch } from 'web-search-plugin';
-
-const search = new WebSearch({
-  apiEndpoint: 'https://api.example.com/search',
-  timeout: 5000,
-});
-
-try {
-  const results = await search.query('example query', {
-    limit: 10,
-    sortBy: 'relevance',
-  });
-  console.log('Search Results:', results);
-} catch (error) {
-  console.error('Search failed:', error);
-}
-```
-
-#### Features
-
-- **Query Customization**: Specify query parameters such as `limit` and `sortBy`.
-- **Error Handling**: Handles common search errors gracefully.
-
-## Configuration
-
-### Environment Variables
-
-Set the following environment variables for optimal performance:
-
-| Variable Name    | Description                       |
-| ---------------- | --------------------------------- |
-| `API_ENDPOINT`   | URL for the search API endpoint.  |
-| `SEARCH_TIMEOUT` | Timeout duration in milliseconds. |
-
-Example `.env` file:
-
-```env
-API_ENDPOINT=https://api.example.com/search
-SEARCH_TIMEOUT=5000
-```
-
-### TypeScript Configuration
-
-Ensure your `tsconfig.json` is properly configured:
-
-```json
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "CommonJS",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true
-  }
-}
-```
-
-## Example Workflow
-
-Streamline your search operations with the following example:
-
-```typescript
-import { WebSearch } from 'web-search-plugin';
-
-const search = new WebSearch({ apiEndpoint: 'https://api.example.com/search' });
-
-(async () => {
-  try {
-    // Execute a search query
-    const results = await search.query('example', { limit: 5 });
-    console.log('Search Results:', results);
-  } catch (error) {
-    console.error('Error executing search:', error);
-  }
-})();
-```
-
-## Local Testing
-
-To test locally, you can set up a mock server for the API endpoint:
-
-1. Install `json-server`:
-
-   ```bash
-   npm install -g json-server
-   ```
-
-2. Create a `db.json` file with mock search data.
-
-3. Start the mock server:
-
-   ```bash
-   json-server --watch db.json --port 3000
-   ```
-
-4. Update your `.env` file:
-   ```env
-   API_ENDPOINT=http://localhost:3000
-   ```
-
-## Common Issues
-
-### "API endpoint not defined"
-
-- Ensure the `API_ENDPOINT` is set in your environment variables.
-
-### "Search query timeout"
-
-- Increase the `SEARCH_TIMEOUT` value in the configuration.
-
-## Dependencies
-
-This plugin relies on the following:
-
-- `axios` for HTTP requests.
-- `dotenv` for managing environment variables.
-
-## Development Guide
-
-### Setup
-
-1. Clone the repository:
-
-   ```bash
-   git clone https://github.com/your-repo/web-search-plugin.git
-   ```
-
-2. Install dependencies:
-   ```bash
-   npm install
-   ```
-
-### Testing
-
-Run tests with:
-
-```bash
-npm test
-```
-
-### Contribution Guidelines
-
-- Fork the repository.
-- Create a feature branch.
-- Submit a pull request with a clear description.
-
-### Security Best Practices
-
-- Validate user inputs to prevent injection attacks.
-- Use HTTPS for secure API communication.
-
-## Performance Optimization
-
-- Use caching for frequently queried terms.
-- Optimize query parameters for faster responses.
-
----
-
-This documentation aims to streamline onboarding, reduce support queries, and enable faster adoption of the Web Search Plugin.

package/dist/index.d.ts

@@ -1,5 +0,0 @@
-import { Plugin } from '@elizaos/core';
-
-declare const webSearchPlugin: Plugin;
-
-export { webSearchPlugin };