From f397690b22a9e0bcf6def070590377ece99f351d Mon Sep 17 00:00:00 2001 From: Shakker Nerd Date: Tue, 31 Dec 2024 12:55:25 +0000 Subject: [PATCH] chore: README files --- packages/plugin-image-generation/README.MD | 155 ++++++++++++++ packages/plugin-web-search/src/README.MD | 225 +++++++++++++++++++++ 2 files changed, 380 insertions(+) create mode 100644 packages/plugin-image-generation/README.MD create mode 100644 packages/plugin-web-search/src/README.MD diff --git a/packages/plugin-image-generation/README.MD b/packages/plugin-image-generation/README.MD new file mode 100644 index 0000000000..f3488fe44f --- /dev/null +++ b/packages/plugin-image-generation/README.MD @@ -0,0 +1,155 @@ +# Plugin Image Generation + +A plugin designed for generating and managing images, providing features like image manipulation, storage integration, and optimized handling for various use cases. + +## Overview + +The Plugin Image Generation offers developers tools to handle image-related operations seamlessly. It supports image creation, manipulation, and integration with storage solutions, making it ideal for applications requiring dynamic image generation. + +### Features + +- Dynamic image generation +- Integration with storage solutions +- Optimized handling for high-resolution images + +## Installation Instructions + +To install the plugin, use the following command: + +```bash +pnpm install plugin-image-generation +``` + +## Configuration Requirements + +### Environment Variables + +Ensure the following environment variables are set: + +| Variable Name | Description | +| ---------------------- | ----------------------------------- | +| `IMAGE_STORAGE_BUCKET` | Name of the storage bucket. | +| `STORAGE_ACCESS_KEY` | Access key for storage integration. | +| `STORAGE_SECRET_KEY` | Secret key for storage integration. | + +### TypeScript Configuration + +The plugin assumes a TypeScript environment. Ensure your `tsconfig.json` includes the necessary compiler options: + +```json +{ + "compilerOptions": { + "module": "ESNext", + "target": "ES6", + "moduleResolution": "node", + "strict": true + } +} +``` + +## Usage Examples + +### Generate an Image + +The main functionality allows generating an image dynamically. + +```typescript +import { generateImage } from "plugin-image-generation"; + +const image = await generateImage({ + width: 800, + height: 600, + backgroundColor: "#ffffff", + text: "Hello World", + font: "Arial", +}); + +console.log("Generated Image:", image); +``` + +### Upload to Storage + +The plugin supports direct integration with storage solutions for uploading images. + +```typescript +import { uploadImage } from "plugin-image-generation"; + +const uploadResult = await uploadImage({ + imagePath: "path/to/image.png", + bucketName: "my-storage-bucket", +}); + +console.log("Image uploaded successfully:", uploadResult); +``` + +## API Reference + +### generateImage + +#### Parameters + +- `width`: Width of the image. +- `height`: Height of the image. +- `backgroundColor`: Background color of the image. +- `text`: Text to be displayed on the image. +- `font`: Font style for the text. + +#### Returns + +A promise that resolves with the generated image. + +### uploadImage + +#### Parameters + +- `imagePath`: Path to the image file. +- `bucketName`: Name of the storage bucket. + +#### Returns + +A promise that resolves with the upload result. + +## Common Issues/Troubleshooting + +### Issue: Image Not Generated + +**Solution**: Ensure the input parameters for `generateImage` are valid and properly formatted. + +### Issue: Upload Fails + +**Solution**: Verify that the storage credentials and bucket name are correctly configured. + +### Issue: Poor Image Quality + +**Solution**: Check the resolution and ensure that high-quality settings are applied during generation. + +## Additional Documentation + +### Examples Folder + +Include sample projects in the `examples/` directory for users to reference. + +### Testing Guide + +- Run tests using `pnpm test`. +- Ensure integration tests cover all major functionalities. + +### Plugin Development Guide + +To extend this plugin, add new image generation or manipulation features in the `src/` directory. + +### Security Best Practices + +- Store access keys securely. +- Use environment variables for sensitive information. +- Regularly update dependencies. + +### Performance Optimization Guide + +- Optimize image generation by reducing redundant processing. +- Use efficient algorithms for image manipulation. +- Cache frequently used assets. + +## License + +MIT diff --git a/packages/plugin-web-search/src/README.MD b/packages/plugin-web-search/src/README.MD new file mode 100644 index 0000000000..4fbd27dad0 --- /dev/null +++ b/packages/plugin-web-search/src/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; + handler: ( + runtime: IAgentRuntime, + message: Memory, + state: State, + options: any, + callback: HandlerCallback + ) => Promise; + examples: Array>; +} + +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.