🤖 Elvic ASCII Agent

AI-powered ASCII art generator with GPT-4o Vision and OpenAI Web Search capabilities.

✨ Features

• 🖼️ Image Analysis - Analyze images using GPT-4o Vision
• 🎨 Image to ASCII - Convert images to ASCII art with AI
• ✍️ Text to ASCII - Generate artistic ASCII text
• 🔍 Web Search - Search for ASCII art trends and styles
• 🤖 Interactive Mode - Chat with the AI agent
• 📚 Font Library - Access to multiple font categories

🚀 Installation

Global Installation (Recommended)

npm install -g elvic-ascii-agent

Local Installation

npm install elvic-ascii-agent

📋 Prerequisites

• Node.js >= 18.0.0
• OpenAI API Key - Get one at platform.openai.com

⚙️ Configuration

Create a .env file in your project root or home directory:

OPENAI_API_KEY=your_api_key_here

Or set the environment variable:

export OPENAI_API_KEY=your_api_key_here

📖 Usage

Command Line Interface

1. Analyze an Image

elvic-ascii-agent analyze-image path/to/image.jpg
elvic-ascii-agent analyze-image path/to/image.jpg --detailed

2. Convert Image to ASCII Art

elvic-ascii-agent image-to-ascii path/to/image.jpg
elvic-ascii-agent image-to-ascii path/to/image.jpg --width 80 --style artistic

Styles: detailed, simple, artistic, blocky

3. Generate Text ASCII Art

elvic-ascii-agent text-to-ascii "Hello World"
elvic-ascii-agent text-to-ascii "AWESOME" --style 3d

Styles: banner, block, graffiti, 3d, bubble

4. Interactive Mode

elvic-ascii-agent interactive
# or
elvic-ascii-agent i

In interactive mode, you can:

• Ask questions about ASCII art
• Request image analysis
• Generate ASCII art
• Search for trends and styles
• Get font recommendations

5. List Available Fonts

elvic-ascii-agent list-fonts
elvic-ascii-agent list-fonts banner

Help

elvic-ascii-agent --help
elvic-ascii-agent --version

🎯 Examples

Example 1: Analyze a Logo

elvic-ascii-agent analyze-image logo.png --detailed

Example 2: Create ASCII Art from Photo

elvic-ascii-agent image-to-ascii photo.jpg --width 60 --style artistic

Example 3: Generate Banner Text

elvic-ascii-agent text-to-ascii "WELCOME" --style banner

Example 4: Interactive Session

$ elvic-ascii-agent interactive

🤖 Elvic ASCII Agent - Interactive Mode

Powered by GPT-4o Vision + OpenAI Web Search
Type your request or "exit" to quit

You: analyze this image: /path/to/image.jpg
Agent: [AI provides detailed analysis]

You: convert it to ASCII art
Agent: [AI generates ASCII art]

You: search for trending ASCII art styles
Agent: [AI searches web and provides results]

You: exit
Goodbye! 👋

🛠️ API Usage

You can also use the package programmatically:

import { analyzeImageTool, convertImageToAsciiTool } from 'elvic-ascii-agent';

// Analyze an image
const analysis = await analyzeImageTool.execute({
  imagePath: '/path/to/image.jpg'
});

// Convert to ASCII
const ascii = await convertImageToAsciiTool.execute({
  imagePath: '/path/to/image.jpg',
  width: 60,
  style: 'detailed'
});

console.log(ascii.asciiArt);

🎨 ASCII Art Styles

Image Styles

• detailed - Rich shading with many characters
• simple - Clean lines and basic shapes
• artistic - Creative interpretation
• blocky - Solid block characters

Text Styles

• banner - Large, bold letters
• block - Blocky, solid style
• graffiti - Street art style
• 3d - Three-dimensional effect
• bubble - Rounded, bubbly letters

🔧 Troubleshooting

"OPENAI_API_KEY not found"

Make sure you've set your OpenAI API key:

export OPENAI_API_KEY=your_key_here

Or create a .env file with:

OPENAI_API_KEY=your_key_here

"Command not found: elvic-ascii-agent"

If installed globally, make sure npm global bin is in your PATH:

npm config get prefix

Add the bin directory to your PATH in ~/.bashrc or ~/.zshrc:

export PATH="$PATH:$(npm config get prefix)/bin"

Image file not found

Use absolute paths or paths relative to your current directory:

elvic-ascii-agent image-to-ascii ./images/photo.jpg
elvic-ascii-agent image-to-ascii /Users/username/Pictures/photo.jpg

📦 What's Included

• GPT-4o Vision - Advanced image understanding
• OpenAI Web Search - Real-time web search capabilities
• AI-Powered Generation - Creative ASCII art generation
• Multiple Styles - Various artistic styles
• Interactive Mode - Conversational interface

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Elvic Kongolo

🔗 Links

• GitHub Repository
• npm Package
• Report Issues

🌟 Powered By

• OpenAI GPT-4o - Vision and language model
• OpenAI Agents SDK - Agent framework
• Commander.js - CLI framework
• Chalk - Terminal styling
• Ora - Elegant terminal spinners

Made with ❤️ by Elvic Kongolo