🇵🇭 Pareng Boyong - Your Intelligent Filipino AI Agent

Kumusta! Meet Pareng Boyong, your intelligent Filipino AI agent and coding assistant with cost optimization, cultural awareness, and multimodal capabilities.

"Bayanihan spirit meets AI excellence" - Built with Filipino values, world-class technology

✨ What Makes Pareng Boyong Special

🇵🇭 Filipino Cultural Integration

• Natural Filipino/Tagalog communication
• Cultural values: Bayanihan, Kapamilya, Utang na loob
• Respectful communication patterns (po/opo)
• Philippine time zone and local context awareness

💰 Cost-Optimized Excellence

• FREE-first approach - prioritizes free services before paid alternatives
• 90-95% of requests use FREE services
• Intelligent cost tracking and budget management
• Average cost per video: < $0.005, per image: < $0.003

🤖 44+ Specialized AI Tools

• Multimodal generation (text, images, video, audio)
• Code execution across multiple environments
• System monitoring and self-healing
• Multi-agent architecture

🌐 Complete Solution

• Command-line interface (boyong command)
• Web interface with real-time chat
• Python API for integration
• Extensive documentation

🚀 Quick Start

Installation

# Basic installation
pip install pareng-boyong

# Full installation with all features
pip install pareng-boyong[full]

# Specific feature sets
pip install pareng-boyong[ai,multimedia,filipino]

Setup

# Run the setup wizard
boyong setup

# Start chatting
boyong chat

# Launch web interface
boyong web

Python API

from pareng_boyong import setup_pareng_boyong

# Quick setup
agent = setup_pareng_boyong(
    api_keys={"openai": "sk-xxx", "google": "xxx"},
    cultural_mode=True
)

# Start chatting
response = agent.chat("Kumusta! Create a video of Manila sunset")
print(response)

🎯 Key Features

🔧 Cost-Optimized Tool Ecosystem

Primary Tools (Always Try First):

• cost_optimized_video_generator - FREE → $0.01 video generation
• imagen4_generator - Google Imagen 4 Fast for images
• multimodal_coordinator - Intelligent request routing
• system_self_awareness - Health monitoring and risk assessment

Decision Tree Example:

Video Request → cost_optimized (FREE ComfyUI) → trending (CogVideoX-2B) → advanced (premium)
Image Request → imagen4 (Google Fast) → multimedia (ComfyUI) → SVG fallback

🇵🇭 Cultural Intelligence

# Automatic cultural context
agent.chat("Hello")
# Response: "🇵🇭 Magandang araw po! I'm Pareng Boyong, your kaibigan na AI assistant!"

# Cost-conscious recommendations
agent.chat("Create a professional video")  
# Response: "I can generate this video for you! 
#          🆓 FREE Option: ComfyUI (5-10 min)
#          💸 Paid Option: Replicate ($0.008, premium quality)
#          Which would you prefer? I always recommend trying FREE first!"

🎨 Multimodal Generation

Video Generation:

• FREE: ComfyUI AnimateDiff, HuggingFace Spaces
• Paid: CogVideoX-2B, Stable Video Diffusion, Open-Sora

Image Generation:

• Primary: Google Imagen 4 Fast (2K resolution)
• Fallback: ComfyUI FLUX.1, SVG placeholders

Audio Generation:

• Filipino TTS: Toucan TTS for Filipino/Tagalog
• Music: Bark, AudioCraft with cost optimization
• Voiceovers: Multiple languages with quality tiers

📦 Installation Options

Basic Installation

pip install pareng-boyong

Includes: Core agent, CLI, basic tools

Feature-Specific Installations

# AI and LLM features
pip install pareng-boyong[ai]

# Multimedia generation
pip install pareng-boyong[multimedia]

# Filipino TTS and cultural features  
pip install pareng-boyong[filipino]

# Web interface
pip install pareng-boyong[web]

# Development tools
pip install pareng-boyong[dev]

# Everything included
pip install pareng-boyong[full]

🖥️ Command Line Interface

Setup and Configuration

# Initial setup wizard
boyong setup

# Minimal setup (essential features only)
boyong setup --minimal

# Force reconfiguration
boyong setup --force

Interactive Chat

# Basic chat mode
boyong chat

# Chat with specific model
boyong chat --model "openai/gpt-4"

# Disable cultural mode
boyong chat --no-cultural

# Debug mode
boyong chat --debug

Web Interface

# Start web server (default: http://localhost:8080)
boyong web

# Custom host and port
boyong web --host 0.0.0.0 --port 3000

# Development mode
boyong web --debug

Tool Management

# List all tools
boyong tools --list

# Show enabled tools only
boyong tools --enabled

# Filter by category
boyong tools --category multimodal

# Enable/disable tools
boyong tools --enable imagen4_generator
boyong tools --disable advanced_video_generator

Configuration Management

# Show current config
boyong config --show

# Edit configuration interactively
boyong config --edit

# Set specific values
boyong config --key cultural_mode --value true
boyong config --key max_daily_cost --value 10.0

# Reset to defaults
boyong config --reset

System Status

# Check system health and status
boyong status

🐍 Python API

Quick Setup

from pareng_boyong import ParengBoyong, ParengBoyongConfig

# Using default configuration
agent = ParengBoyong()

# Custom configuration
config = ParengBoyongConfig(
    api_keys={
        "openai": "sk-xxx",
        "google": "xxx", 
        "replicate": "r8-xxx"
    },
    cultural_mode=True,
    cost_optimization=True,
    max_daily_cost=5.0
)
agent = ParengBoyong(config)

Basic Usage

# Simple chat
response = agent.chat("Create an image of Mayon Volcano")
print(response)

# Streaming chat
for chunk in agent.chat("Tell me about Filipino culture", stream=True):
    print(chunk, end='')

# With additional context
response = agent.chat(
    "Generate a professional presentation video",
    context={"quality": "high", "budget": 0.05}
)

Advanced Features

# Create subordinate agents for complex tasks
subordinate = agent.create_subordinate(
    task="Handle video generation subtasks",
    context={"specialization": "multimedia"}
)

# Get capabilities and status
capabilities = agent.get_capabilities()
print(f"Available tools: {len(capabilities['tools'])}")
print(f"Cultural features: {capabilities['cultural_features']}")

# Reset session
agent.reset_session()

Error Handling

from pareng_boyong import ParengBoyongError, ConfigurationError, CostLimitError

try:
    response = agent.chat("Create expensive content")
except CostLimitError as e:
    print(f"Cost limit reached: {e.get_filipino_message()}")
    # "Pasensya na po, naabot na natin ang cost limit..."
    
except ConfigurationError as e:
    print(f"Config issue: {e.get_filipino_message()}")
    # "Pasensya na po, kulang pa ang API keys..."

⚙️ Configuration

Environment Variables

# API Keys
export OPENAI_API_KEY="sk-xxx"
export GOOGLE_API_KEY="xxx"
export REPLICATE_API_TOKEN="r8-xxx"
export ELEVENLABS_API_KEY="xxx"

# Pareng Boyong Settings
export PARENG_BOYONG_CULTURAL_MODE="true"
export PARENG_BOYONG_MAX_DAILY_COST="5.0"
export PARENG_BOYONG_DEBUG="false"

Configuration File

Config is automatically saved to ~/.pareng-boyong/config.yaml:

# Core settings
cultural_mode: true
cost_optimization: true
max_daily_cost: 5.0
max_history_size: 100

# Model settings
default_llm: "openai/gpt-4"
temperature: 0.7
max_tokens: 4000

# Tool preferences
enabled_tools:
  - cost_optimized_video_generator
  - imagen4_generator
  - multimodal_coordinator
  - system_self_awareness

# Cultural settings
primary_language: "mixed"  # english, filipino, mixed
cultural_context_level: "moderate"  # minimal, moderate, full
use_filipino_greetings: true
use_po_opo: true

# Cost optimization
prefer_free_services: true
cost_warning_threshold: 1.0
auto_escalate_quality: false

🎨 Usage Examples

Multimedia Generation

# Cost-optimized video (tries FREE first)
response = agent.chat("Create a 5-second video of Philippine flag waving")
# Uses FREE ComfyUI or HuggingFace before paid services

# High-quality image with Google Imagen 4
response = agent.chat("Professional photo of Banaue Rice Terraces, golden hour")
# Uses Google Imagen 4 Fast for best quality/cost ratio

# Filipino TTS
response = agent.chat("Convert this to Filipino speech: 'Magandang umaga sa lahat'")
# Uses Toucan TTS for authentic Filipino pronunciation

Code and Development

# Code execution with cultural context
response = agent.chat("""
Create a Python script that greets users in Filipino,
then deploy it to a web server
""")

# System analysis
response = agent.chat("Check system health and recommend optimizations")
# Uses system_self_awareness tool for comprehensive analysis

Cultural Integration

# Cultural responses automatically
agent.chat("Hello!")
# "🇵🇭 Magandang araw po! I'm Pareng Boyong..."

agent.chat("Can you help me?")  
# "Oo naman! Walang problema! What do you need help with?"

# Cost consciousness
agent.chat("I need a video but I'm on a tight budget")
# "No worries! Let's use FREE services muna. ComfyUI is perfect for this!"

🔧 Tool Categories

Multimodal Generation (11 tools)

• Video: cost_optimized, trending, advanced, simple generators
• Image: imagen4, multimedia generators
• Audio: studio, voiceover, music, cost-optimized generators
• Coordination: multimodal_coordinator for intelligent routing

Development & Code (7 tools)

• Execution: enhanced_code_execution (RFC HTTP→Daytona→SSH→Local)
• Version Control: github_tool with full API integration
• Deployment: automatic_deployment_tool, context7_tool
• Configuration: enhanced_model_configuration, model_discovery

Intelligence & Memory (7 tools)

• Memory: save, load, forget, delete operations
• Search: engine, searxng, document_query capabilities

System Management (11 tools)

• Monitoring: system_self_awareness, comprehensive_system_test
• Recovery: self_healing_tool, error_analysis_tool
• UI: enhanced_ui_renderer with React-style components
• Infrastructure: env_loader, browser, email, MCP tools

Utility (8 tools)

• Input handling, vision processing, legacy support tools

📊 Cost Optimization Features

Intelligent Cost Management

# Automatic cost tracking
daily_usage = agent.cost_optimizer.get_daily_usage()
monthly_usage = agent.cost_optimizer.get_monthly_usage()

# Cost report with Filipino context
report = agent.cost_optimizer.get_cost_report()
print(f"Today's usage: ${report['daily_usage']:.3f}")
print(f"Estimated monthly savings: ${report['estimated_savings']:.2f}")

# Budget checking
if agent.cost_optimizer.can_afford(0.05):
    print("✅ Within budget!")
else:
    print("⚠️ Budget limit reached - try FREE alternatives!")

Cost Optimization Strategies

1. FREE-First Approach: Always try free services before paid
2. Budget Monitoring: Track daily/monthly spending with alerts
3. Quality vs Cost: Auto-select appropriate quality tier
4. Alternative Suggestions: Recommend cheaper options when budget is tight
5. Cultural Cost Messaging: Filipino-friendly budget notifications

🌐 Web Interface

Launch the web interface for a complete graphical experience:

boyong web

Features:

• Interactive Chat: Real-time conversation with Pareng Boyong
• Tool Dashboard: Visual tool management and status
• Cost Monitor: Live cost tracking and optimization insights
• Cultural Settings: Adjust Filipino integration preferences
• Multimedia Gallery: View generated images, videos, and audio
• System Health: Monitor performance and resource usage

🤝 Multi-Agent Architecture

# Create specialized subordinate agents
video_agent = agent.create_subordinate(
    task="Handle all video generation requests",
    context={"specialization": "video", "budget": 0.02}
)

code_agent = agent.create_subordinate(
    task="Execute code and development tasks", 
    context={"specialization": "development"}
)

# Agents collaborate automatically
response = agent.chat("""
Create a video showcasing a Python web app,
then deploy the app to production
""")
# Automatically delegates to video_agent and code_agent

🛡️ System Self-Awareness

Pareng Boyong includes intelligent system monitoring:

# Health check before major operations
health = agent.system_monitor.health_check()
if not health['healthy']:
    print(f"⚠️ System issues: {health['issues']}")

# Risk assessment for operations
risk = agent.system_monitor.assess_risk("generate_large_video")
if risk['high_risk']:
    print(f"🚨 High risk operation: {risk['warnings']}")

# Automatic self-healing
agent.system_monitor.enable_self_healing()

🔒 Security and Privacy

• API Key Management: Secure storage and validation
• Container Isolation: Sandboxed execution environments
• Cost Protection: Automatic budget limits and alerts
• Cultural Sensitivity: Respectful AI behavior with Filipino values
• Data Privacy: Local storage with optional cloud integration

🚗 Migration from Agent Zero

If you're coming from Agent Zero, Pareng Boyong provides:

• Enhanced Cost Optimization: FREE-first approach vs default paid services
• Filipino Cultural Integration: Natural cultural context and language
• Improved Tool Selection: Intelligent routing based on cost and quality
• Better Error Handling: Culturally-sensitive error messages
• Comprehensive CLI: Full command-line interface with setup wizard

# Agent Zero style (still works)
from pareng_boyong import ParengBoyong
agent = ParengBoyong()
response = agent.chat("Create content")

# Enhanced Pareng Boyong style
from pareng_boyong import setup_pareng_boyong
agent = setup_pareng_boyong(cultural_mode=True, cost_optimization=True)
response = agent.chat("Gumawa ng content para sa presentation")

🤝 Contributing

We welcome contributions with bayanihan spirit! Here's how to help:

Development Setup

# Clone repository
git clone https://github.com/innovatehub-ph/pareng-boyong.git
cd pareng-boyong

# Install development dependencies
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Code formatting
black pareng_boyong/
flake8 pareng_boyong/

Ways to Contribute

• 🐛 Bug Reports: Help us improve reliability
• ✨ Features: Suggest new tools and capabilities
• 🇵🇭 Cultural Enhancement: Improve Filipino integration
• 📚 Documentation: Help others understand and use Pareng Boyong
• 🌐 Translations: Support more Filipino languages and dialects
• 🔧 Tools: Develop new specialized AI tools

Community Guidelines

• Respectful: Maintain Filipino values of respect and courtesy
• Collaborative: Embrace bayanihan spirit in all interactions
• Inclusive: Welcome all backgrounds and skill levels
• Cost-Conscious: Consider cost optimization in all features

📚 Documentation

• Installation Guide: Detailed setup instructions
• API Reference: Complete Python API documentation
• CLI Guide: Command-line interface reference
• Cultural Features: Filipino integration details
• Tool Development: Creating custom tools
• Cost Optimization: Understanding cost management
• Troubleshooting: Common issues and solutions

🆘 Support

Need help? We're here with malasakit!

• 📖 Documentation: https://pareng-boyong.readthedocs.io
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🇵🇭 Community: Filipino AI Discord
• 📧 Email: support@innovatehub.ph

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Salamat to these amazing projects and communities:

• Agent Zero: Foundation AI agent framework
• Filipino AI Community: Cultural guidance and feedback
• Open Source Contributors: Tools, libraries, and inspiration
• InnovateHub PH: Development and maintenance

🎯 Roadmap

Short Term (Q1 2025)

• ✅ PyPI package release
• ✅ Comprehensive CLI interface
• ✅ Cost optimization system
• 🔄 Enhanced web interface
• 🔄 More Filipino TTS voices

Medium Term (Q2-Q3 2025)

• 📱 Mobile app integration
• 🌐 Multi-language support (Cebuano, Ilocano, etc.)
• 🤖 Advanced multi-agent workflows
• ☁️ Cloud deployment options
• 📊 Enhanced analytics and reporting

Long Term (Q4 2025+)

• 🧠 Fine-tuned Filipino language models
• 🏢 Enterprise features and support
• 🌏 Southeast Asian cultural expansion
• 🔬 Research collaborations
• 🎓 Educational partnerships

---