pareng-boyong

Name	pareng-boyong JSON
Version	1.0.0 JSON
	download
home_page	https://github.com/innovatehub-ph/pareng-boyong
Summary	Pareng Boyong - Your Intelligent Filipino AI Agent and Coding Assistant
upload_time	2025-08-05 12:34:40
maintainer	None
docs_url	None
author	InnovateHub PH
requires_python	>=3.8
license	MIT
keywords	ai agent filipino coding-assistant multimodal cost-optimization agent-zero pinoy-ai tts cli
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 🇵🇭 Pareng Boyong - Your Intelligent Filipino AI Agent

[![PyPI version](https://badge.fury.io/py/pareng-boyong.svg)](https://badge.fury.io/py/pareng-boyong)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Filipino AI](https://img.shields.io/badge/Filipino-AI-red.svg)](https://github.com/innovatehub-ph/pareng-boyong)

**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

```bash
# 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

```bash
# Run the setup wizard
boyong setup

# Start chatting
boyong chat

# Launch web interface
boyong web
```

### Python API

```python
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

```python
# 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
```bash
pip install pareng-boyong
```
**Includes:** Core agent, CLI, basic tools

### Feature-Specific Installations
```bash
# 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
```bash
# Initial setup wizard
boyong setup

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

# Force reconfiguration
boyong setup --force
```

### Interactive Chat
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Check system health and status
boyong status
```

## 🐍 Python API

### Quick Setup
```python
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
```python
# 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
```python
# 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
```python
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
```bash
# 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`:

```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
```python
# 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
```python
# 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
```python
# 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
```python
# 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:

```bash
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

```python
# 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:

```python
# 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

```python
# 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
```bash
# 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](docs/installation.md)**: Detailed setup instructions
- **[API Reference](docs/api.md)**: Complete Python API documentation
- **[CLI Guide](docs/cli.md)**: Command-line interface reference
- **[Cultural Features](docs/cultural.md)**: Filipino integration details
- **[Tool Development](docs/tools.md)**: Creating custom tools
- **[Cost Optimization](docs/costs.md)**: Understanding cost management
- **[Troubleshooting](docs/troubleshooting.md)**: Common issues and solutions

## 🆘 Support

Need help? We're here with **malasakit**!

- **📖 Documentation**: [https://pareng-boyong.readthedocs.io](https://pareng-boyong.readthedocs.io)
- **🐛 Issues**: [GitHub Issues](https://github.com/innovatehub-ph/pareng-boyong/issues)
- **💬 Discussions**: [GitHub Discussions](https://github.com/innovatehub-ph/pareng-boyong/discussions)  
- **🇵🇭 Community**: [Filipino AI Discord](https://discord.gg/filipino-ai)
- **📧 Email**: support@innovatehub.ph

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

**Salamat** to these amazing projects and communities:

- **[Agent Zero](https://github.com/agent0ai/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

---

<div align="center">

**🇵🇭 Built with Filipino pride, powered by AI excellence**

*Pareng Boyong - Your kaibigan in the age of artificial intelligence*

[![Made in Philippines](https://img.shields.io/badge/Made%20in-Philippines-red.svg)](https://github.com/innovatehub-ph)
[![Powered by AI](https://img.shields.io/badge/Powered%20by-AI-blue.svg)](https://pareng-boyong.ai)
[![Bayanihan Spirit](https://img.shields.io/badge/Bayanihan-Spirit-yellow.svg)](https://github.com/innovatehub-ph/pareng-boyong)

</div>

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/innovatehub-ph/pareng-boyong",
    "name": "pareng-boyong",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "Pareng Boyong Development Team <dev@innovatehub.ph>",
    "keywords": "ai, agent, filipino, coding-assistant, multimodal, cost-optimization, agent-zero, pinoy-ai, tts, cli",
    "author": "InnovateHub PH",
    "author_email": "InnovateHub PH <info@innovatehub.ph>",
    "download_url": "https://files.pythonhosted.org/packages/5c/15/79a06476b9fd1a8b0c8c1b761e3043aee6241e27efe98338a5474d013854/pareng_boyong-1.0.0.tar.gz",
    "platform": null,
    "description": "# \ud83c\uddf5\ud83c\udded Pareng Boyong - Your Intelligent Filipino AI Agent\n\n[![PyPI version](https://badge.fury.io/py/pareng-boyong.svg)](https://badge.fury.io/py/pareng-boyong)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Filipino AI](https://img.shields.io/badge/Filipino-AI-red.svg)](https://github.com/innovatehub-ph/pareng-boyong)\n\n**Kumusta!** Meet **Pareng Boyong**, your intelligent Filipino AI agent and coding assistant with cost optimization, cultural awareness, and multimodal capabilities.\n\n> *\"Bayanihan spirit meets AI excellence\"* - Built with Filipino values, world-class technology\n\n## \u2728 What Makes Pareng Boyong Special\n\n\ud83c\uddf5\ud83c\udded **Filipino Cultural Integration**\n- Natural Filipino/Tagalog communication\n- Cultural values: Bayanihan, Kapamilya, Utang na loob\n- Respectful communication patterns (po/opo)\n- Philippine time zone and local context awareness\n\n\ud83d\udcb0 **Cost-Optimized Excellence** \n- **FREE-first approach** - prioritizes free services before paid alternatives\n- 90-95% of requests use FREE services\n- Intelligent cost tracking and budget management\n- Average cost per video: < $0.005, per image: < $0.003\n\n\ud83e\udd16 **44+ Specialized AI Tools**\n- Multimodal generation (text, images, video, audio)\n- Code execution across multiple environments\n- System monitoring and self-healing\n- Multi-agent architecture\n\n\ud83c\udf10 **Complete Solution**\n- Command-line interface (`boyong` command)\n- Web interface with real-time chat\n- Python API for integration\n- Extensive documentation\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Basic installation\npip install pareng-boyong\n\n# Full installation with all features\npip install pareng-boyong[full]\n\n# Specific feature sets\npip install pareng-boyong[ai,multimedia,filipino]\n```\n\n### Setup\n\n```bash\n# Run the setup wizard\nboyong setup\n\n# Start chatting\nboyong chat\n\n# Launch web interface\nboyong web\n```\n\n### Python API\n\n```python\nfrom pareng_boyong import setup_pareng_boyong\n\n# Quick setup\nagent = setup_pareng_boyong(\n    api_keys={\"openai\": \"sk-xxx\", \"google\": \"xxx\"},\n    cultural_mode=True\n)\n\n# Start chatting\nresponse = agent.chat(\"Kumusta! Create a video of Manila sunset\")\nprint(response)\n```\n\n## \ud83c\udfaf Key Features\n\n### \ud83d\udd27 Cost-Optimized Tool Ecosystem\n\n**Primary Tools (Always Try First):**\n- `cost_optimized_video_generator` - FREE \u2192 $0.01 video generation\n- `imagen4_generator` - Google Imagen 4 Fast for images  \n- `multimodal_coordinator` - Intelligent request routing\n- `system_self_awareness` - Health monitoring and risk assessment\n\n**Decision Tree Example:**\n```\nVideo Request \u2192 cost_optimized (FREE ComfyUI) \u2192 trending (CogVideoX-2B) \u2192 advanced (premium)\nImage Request \u2192 imagen4 (Google Fast) \u2192 multimedia (ComfyUI) \u2192 SVG fallback\n```\n\n### \ud83c\uddf5\ud83c\udded Cultural Intelligence\n\n```python\n# Automatic cultural context\nagent.chat(\"Hello\")\n# Response: \"\ud83c\uddf5\ud83c\udded Magandang araw po! I'm Pareng Boyong, your kaibigan na AI assistant!\"\n\n# Cost-conscious recommendations\nagent.chat(\"Create a professional video\")  \n# Response: \"I can generate this video for you! \n#          \ud83c\udd93 FREE Option: ComfyUI (5-10 min)\n#          \ud83d\udcb8 Paid Option: Replicate ($0.008, premium quality)\n#          Which would you prefer? I always recommend trying FREE first!\"\n```\n\n### \ud83c\udfa8 Multimodal Generation\n\n**Video Generation:**\n- **FREE**: ComfyUI AnimateDiff, HuggingFace Spaces\n- **Paid**: CogVideoX-2B, Stable Video Diffusion, Open-Sora\n\n**Image Generation:**\n- **Primary**: Google Imagen 4 Fast (2K resolution)\n- **Fallback**: ComfyUI FLUX.1, SVG placeholders\n\n**Audio Generation:**\n- **Filipino TTS**: Toucan TTS for Filipino/Tagalog\n- **Music**: Bark, AudioCraft with cost optimization\n- **Voiceovers**: Multiple languages with quality tiers\n\n## \ud83d\udce6 Installation Options\n\n### Basic Installation\n```bash\npip install pareng-boyong\n```\n**Includes:** Core agent, CLI, basic tools\n\n### Feature-Specific Installations\n```bash\n# AI and LLM features\npip install pareng-boyong[ai]\n\n# Multimedia generation\npip install pareng-boyong[multimedia]\n\n# Filipino TTS and cultural features  \npip install pareng-boyong[filipino]\n\n# Web interface\npip install pareng-boyong[web]\n\n# Development tools\npip install pareng-boyong[dev]\n\n# Everything included\npip install pareng-boyong[full]\n```\n\n## \ud83d\udda5\ufe0f Command Line Interface\n\n### Setup and Configuration\n```bash\n# Initial setup wizard\nboyong setup\n\n# Minimal setup (essential features only)\nboyong setup --minimal\n\n# Force reconfiguration\nboyong setup --force\n```\n\n### Interactive Chat\n```bash\n# Basic chat mode\nboyong chat\n\n# Chat with specific model\nboyong chat --model \"openai/gpt-4\"\n\n# Disable cultural mode\nboyong chat --no-cultural\n\n# Debug mode\nboyong chat --debug\n```\n\n### Web Interface\n```bash\n# Start web server (default: http://localhost:8080)\nboyong web\n\n# Custom host and port\nboyong web --host 0.0.0.0 --port 3000\n\n# Development mode\nboyong web --debug\n```\n\n### Tool Management\n```bash\n# List all tools\nboyong tools --list\n\n# Show enabled tools only\nboyong tools --enabled\n\n# Filter by category\nboyong tools --category multimodal\n\n# Enable/disable tools\nboyong tools --enable imagen4_generator\nboyong tools --disable advanced_video_generator\n```\n\n### Configuration Management\n```bash\n# Show current config\nboyong config --show\n\n# Edit configuration interactively\nboyong config --edit\n\n# Set specific values\nboyong config --key cultural_mode --value true\nboyong config --key max_daily_cost --value 10.0\n\n# Reset to defaults\nboyong config --reset\n```\n\n### System Status\n```bash\n# Check system health and status\nboyong status\n```\n\n## \ud83d\udc0d Python API\n\n### Quick Setup\n```python\nfrom pareng_boyong import ParengBoyong, ParengBoyongConfig\n\n# Using default configuration\nagent = ParengBoyong()\n\n# Custom configuration\nconfig = ParengBoyongConfig(\n    api_keys={\n        \"openai\": \"sk-xxx\",\n        \"google\": \"xxx\", \n        \"replicate\": \"r8-xxx\"\n    },\n    cultural_mode=True,\n    cost_optimization=True,\n    max_daily_cost=5.0\n)\nagent = ParengBoyong(config)\n```\n\n### Basic Usage\n```python\n# Simple chat\nresponse = agent.chat(\"Create an image of Mayon Volcano\")\nprint(response)\n\n# Streaming chat\nfor chunk in agent.chat(\"Tell me about Filipino culture\", stream=True):\n    print(chunk, end='')\n\n# With additional context\nresponse = agent.chat(\n    \"Generate a professional presentation video\",\n    context={\"quality\": \"high\", \"budget\": 0.05}\n)\n```\n\n### Advanced Features\n```python\n# Create subordinate agents for complex tasks\nsubordinate = agent.create_subordinate(\n    task=\"Handle video generation subtasks\",\n    context={\"specialization\": \"multimedia\"}\n)\n\n# Get capabilities and status\ncapabilities = agent.get_capabilities()\nprint(f\"Available tools: {len(capabilities['tools'])}\")\nprint(f\"Cultural features: {capabilities['cultural_features']}\")\n\n# Reset session\nagent.reset_session()\n```\n\n### Error Handling\n```python\nfrom pareng_boyong import ParengBoyongError, ConfigurationError, CostLimitError\n\ntry:\n    response = agent.chat(\"Create expensive content\")\nexcept CostLimitError as e:\n    print(f\"Cost limit reached: {e.get_filipino_message()}\")\n    # \"Pasensya na po, naabot na natin ang cost limit...\"\n    \nexcept ConfigurationError as e:\n    print(f\"Config issue: {e.get_filipino_message()}\")\n    # \"Pasensya na po, kulang pa ang API keys...\"\n```\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n```bash\n# API Keys\nexport OPENAI_API_KEY=\"sk-xxx\"\nexport GOOGLE_API_KEY=\"xxx\"\nexport REPLICATE_API_TOKEN=\"r8-xxx\"\nexport ELEVENLABS_API_KEY=\"xxx\"\n\n# Pareng Boyong Settings\nexport PARENG_BOYONG_CULTURAL_MODE=\"true\"\nexport PARENG_BOYONG_MAX_DAILY_COST=\"5.0\"\nexport PARENG_BOYONG_DEBUG=\"false\"\n```\n\n### Configuration File\nConfig is automatically saved to `~/.pareng-boyong/config.yaml`:\n\n```yaml\n# Core settings\ncultural_mode: true\ncost_optimization: true\nmax_daily_cost: 5.0\nmax_history_size: 100\n\n# Model settings\ndefault_llm: \"openai/gpt-4\"\ntemperature: 0.7\nmax_tokens: 4000\n\n# Tool preferences\nenabled_tools:\n  - cost_optimized_video_generator\n  - imagen4_generator\n  - multimodal_coordinator\n  - system_self_awareness\n\n# Cultural settings\nprimary_language: \"mixed\"  # english, filipino, mixed\ncultural_context_level: \"moderate\"  # minimal, moderate, full\nuse_filipino_greetings: true\nuse_po_opo: true\n\n# Cost optimization\nprefer_free_services: true\ncost_warning_threshold: 1.0\nauto_escalate_quality: false\n```\n\n## \ud83c\udfa8 Usage Examples\n\n### Multimedia Generation\n```python\n# Cost-optimized video (tries FREE first)\nresponse = agent.chat(\"Create a 5-second video of Philippine flag waving\")\n# Uses FREE ComfyUI or HuggingFace before paid services\n\n# High-quality image with Google Imagen 4\nresponse = agent.chat(\"Professional photo of Banaue Rice Terraces, golden hour\")\n# Uses Google Imagen 4 Fast for best quality/cost ratio\n\n# Filipino TTS\nresponse = agent.chat(\"Convert this to Filipino speech: 'Magandang umaga sa lahat'\")\n# Uses Toucan TTS for authentic Filipino pronunciation\n```\n\n### Code and Development\n```python\n# Code execution with cultural context\nresponse = agent.chat(\"\"\"\nCreate a Python script that greets users in Filipino,\nthen deploy it to a web server\n\"\"\")\n\n# System analysis\nresponse = agent.chat(\"Check system health and recommend optimizations\")\n# Uses system_self_awareness tool for comprehensive analysis\n```\n\n### Cultural Integration\n```python\n# Cultural responses automatically\nagent.chat(\"Hello!\")\n# \"\ud83c\uddf5\ud83c\udded Magandang araw po! I'm Pareng Boyong...\"\n\nagent.chat(\"Can you help me?\")  \n# \"Oo naman! Walang problema! What do you need help with?\"\n\n# Cost consciousness\nagent.chat(\"I need a video but I'm on a tight budget\")\n# \"No worries! Let's use FREE services muna. ComfyUI is perfect for this!\"\n```\n\n## \ud83d\udd27 Tool Categories\n\n### Multimodal Generation (11 tools)\n- **Video**: cost_optimized, trending, advanced, simple generators\n- **Image**: imagen4, multimedia generators\n- **Audio**: studio, voiceover, music, cost-optimized generators\n- **Coordination**: multimodal_coordinator for intelligent routing\n\n### Development & Code (7 tools)\n- **Execution**: enhanced_code_execution (RFC HTTP\u2192Daytona\u2192SSH\u2192Local)\n- **Version Control**: github_tool with full API integration\n- **Deployment**: automatic_deployment_tool, context7_tool\n- **Configuration**: enhanced_model_configuration, model_discovery\n\n### Intelligence & Memory (7 tools)\n- **Memory**: save, load, forget, delete operations\n- **Search**: engine, searxng, document_query capabilities\n\n### System Management (11 tools)\n- **Monitoring**: system_self_awareness, comprehensive_system_test\n- **Recovery**: self_healing_tool, error_analysis_tool\n- **UI**: enhanced_ui_renderer with React-style components\n- **Infrastructure**: env_loader, browser, email, MCP tools\n\n### Utility (8 tools)\n- Input handling, vision processing, legacy support tools\n\n## \ud83d\udcca Cost Optimization Features\n\n### Intelligent Cost Management\n```python\n# Automatic cost tracking\ndaily_usage = agent.cost_optimizer.get_daily_usage()\nmonthly_usage = agent.cost_optimizer.get_monthly_usage()\n\n# Cost report with Filipino context\nreport = agent.cost_optimizer.get_cost_report()\nprint(f\"Today's usage: ${report['daily_usage']:.3f}\")\nprint(f\"Estimated monthly savings: ${report['estimated_savings']:.2f}\")\n\n# Budget checking\nif agent.cost_optimizer.can_afford(0.05):\n    print(\"\u2705 Within budget!\")\nelse:\n    print(\"\u26a0\ufe0f Budget limit reached - try FREE alternatives!\")\n```\n\n### Cost Optimization Strategies\n1. **FREE-First Approach**: Always try free services before paid\n2. **Budget Monitoring**: Track daily/monthly spending with alerts\n3. **Quality vs Cost**: Auto-select appropriate quality tier\n4. **Alternative Suggestions**: Recommend cheaper options when budget is tight\n5. **Cultural Cost Messaging**: Filipino-friendly budget notifications\n\n## \ud83c\udf10 Web Interface\n\nLaunch the web interface for a complete graphical experience:\n\n```bash\nboyong web\n```\n\nFeatures:\n- **Interactive Chat**: Real-time conversation with Pareng Boyong\n- **Tool Dashboard**: Visual tool management and status\n- **Cost Monitor**: Live cost tracking and optimization insights\n- **Cultural Settings**: Adjust Filipino integration preferences\n- **Multimedia Gallery**: View generated images, videos, and audio\n- **System Health**: Monitor performance and resource usage\n\n## \ud83e\udd1d Multi-Agent Architecture\n\n```python\n# Create specialized subordinate agents\nvideo_agent = agent.create_subordinate(\n    task=\"Handle all video generation requests\",\n    context={\"specialization\": \"video\", \"budget\": 0.02}\n)\n\ncode_agent = agent.create_subordinate(\n    task=\"Execute code and development tasks\", \n    context={\"specialization\": \"development\"}\n)\n\n# Agents collaborate automatically\nresponse = agent.chat(\"\"\"\nCreate a video showcasing a Python web app,\nthen deploy the app to production\n\"\"\")\n# Automatically delegates to video_agent and code_agent\n```\n\n## \ud83d\udee1\ufe0f System Self-Awareness\n\nPareng Boyong includes intelligent system monitoring:\n\n```python\n# Health check before major operations\nhealth = agent.system_monitor.health_check()\nif not health['healthy']:\n    print(f\"\u26a0\ufe0f System issues: {health['issues']}\")\n\n# Risk assessment for operations\nrisk = agent.system_monitor.assess_risk(\"generate_large_video\")\nif risk['high_risk']:\n    print(f\"\ud83d\udea8 High risk operation: {risk['warnings']}\")\n\n# Automatic self-healing\nagent.system_monitor.enable_self_healing()\n```\n\n## \ud83d\udd12 Security and Privacy\n\n- **API Key Management**: Secure storage and validation\n- **Container Isolation**: Sandboxed execution environments\n- **Cost Protection**: Automatic budget limits and alerts\n- **Cultural Sensitivity**: Respectful AI behavior with Filipino values\n- **Data Privacy**: Local storage with optional cloud integration\n\n## \ud83d\ude97 Migration from Agent Zero\n\nIf you're coming from Agent Zero, Pareng Boyong provides:\n\n- **Enhanced Cost Optimization**: FREE-first approach vs default paid services\n- **Filipino Cultural Integration**: Natural cultural context and language\n- **Improved Tool Selection**: Intelligent routing based on cost and quality\n- **Better Error Handling**: Culturally-sensitive error messages\n- **Comprehensive CLI**: Full command-line interface with setup wizard\n\n```python\n# Agent Zero style (still works)\nfrom pareng_boyong import ParengBoyong\nagent = ParengBoyong()\nresponse = agent.chat(\"Create content\")\n\n# Enhanced Pareng Boyong style\nfrom pareng_boyong import setup_pareng_boyong\nagent = setup_pareng_boyong(cultural_mode=True, cost_optimization=True)\nresponse = agent.chat(\"Gumawa ng content para sa presentation\")\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions with **bayanihan spirit**! Here's how to help:\n\n### Development Setup\n```bash\n# Clone repository\ngit clone https://github.com/innovatehub-ph/pareng-boyong.git\ncd pareng-boyong\n\n# Install development dependencies\npip install -e .[dev]\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n\n# Code formatting\nblack pareng_boyong/\nflake8 pareng_boyong/\n```\n\n### Ways to Contribute\n- \ud83d\udc1b **Bug Reports**: Help us improve reliability\n- \u2728 **Features**: Suggest new tools and capabilities  \n- \ud83c\uddf5\ud83c\udded **Cultural Enhancement**: Improve Filipino integration\n- \ud83d\udcda **Documentation**: Help others understand and use Pareng Boyong\n- \ud83c\udf10 **Translations**: Support more Filipino languages and dialects\n- \ud83d\udd27 **Tools**: Develop new specialized AI tools\n\n### Community Guidelines\n- **Respectful**: Maintain Filipino values of respect and courtesy\n- **Collaborative**: Embrace bayanihan spirit in all interactions\n- **Inclusive**: Welcome all backgrounds and skill levels\n- **Cost-Conscious**: Consider cost optimization in all features\n\n## \ud83d\udcda Documentation\n\n- **[Installation Guide](docs/installation.md)**: Detailed setup instructions\n- **[API Reference](docs/api.md)**: Complete Python API documentation\n- **[CLI Guide](docs/cli.md)**: Command-line interface reference\n- **[Cultural Features](docs/cultural.md)**: Filipino integration details\n- **[Tool Development](docs/tools.md)**: Creating custom tools\n- **[Cost Optimization](docs/costs.md)**: Understanding cost management\n- **[Troubleshooting](docs/troubleshooting.md)**: Common issues and solutions\n\n## \ud83c\udd98 Support\n\nNeed help? We're here with **malasakit**!\n\n- **\ud83d\udcd6 Documentation**: [https://pareng-boyong.readthedocs.io](https://pareng-boyong.readthedocs.io)\n- **\ud83d\udc1b Issues**: [GitHub Issues](https://github.com/innovatehub-ph/pareng-boyong/issues)\n- **\ud83d\udcac Discussions**: [GitHub Discussions](https://github.com/innovatehub-ph/pareng-boyong/discussions)  \n- **\ud83c\uddf5\ud83c\udded Community**: [Filipino AI Discord](https://discord.gg/filipino-ai)\n- **\ud83d\udce7 Email**: support@innovatehub.ph\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n**Salamat** to these amazing projects and communities:\n\n- **[Agent Zero](https://github.com/agent0ai/agent-zero)**: Foundation AI agent framework\n- **Filipino AI Community**: Cultural guidance and feedback\n- **Open Source Contributors**: Tools, libraries, and inspiration\n- **InnovateHub PH**: Development and maintenance\n\n## \ud83c\udfaf Roadmap\n\n### Short Term (Q1 2025)\n- \u2705 PyPI package release\n- \u2705 Comprehensive CLI interface\n- \u2705 Cost optimization system\n- \ud83d\udd04 Enhanced web interface\n- \ud83d\udd04 More Filipino TTS voices\n\n### Medium Term (Q2-Q3 2025)\n- \ud83d\udcf1 Mobile app integration\n- \ud83c\udf10 Multi-language support (Cebuano, Ilocano, etc.)\n- \ud83e\udd16 Advanced multi-agent workflows\n- \u2601\ufe0f Cloud deployment options\n- \ud83d\udcca Enhanced analytics and reporting\n\n### Long Term (Q4 2025+)\n- \ud83e\udde0 Fine-tuned Filipino language models\n- \ud83c\udfe2 Enterprise features and support\n- \ud83c\udf0f Southeast Asian cultural expansion\n- \ud83d\udd2c Research collaborations\n- \ud83c\udf93 Educational partnerships\n\n---\n\n<div align=\"center\">\n\n**\ud83c\uddf5\ud83c\udded Built with Filipino pride, powered by AI excellence**\n\n*Pareng Boyong - Your kaibigan in the age of artificial intelligence*\n\n[![Made in Philippines](https://img.shields.io/badge/Made%20in-Philippines-red.svg)](https://github.com/innovatehub-ph)\n[![Powered by AI](https://img.shields.io/badge/Powered%20by-AI-blue.svg)](https://pareng-boyong.ai)\n[![Bayanihan Spirit](https://img.shields.io/badge/Bayanihan-Spirit-yellow.svg)](https://github.com/innovatehub-ph/pareng-boyong)\n\n</div>\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Pareng Boyong - Your Intelligent Filipino AI Agent and Coding Assistant",
    "version": "1.0.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/innovatehub-ph/pareng-boyong/issues",
        "Changelog": "https://github.com/innovatehub-ph/pareng-boyong/blob/main/CHANGELOG.md",
        "Documentation": "https://pareng-boyong.readthedocs.io",
        "Homepage": "https://github.com/innovatehub-ph/pareng-boyong",
        "Repository": "https://github.com/innovatehub-ph/pareng-boyong.git"
    },
    "split_keywords": [
        "ai",
        " agent",
        " filipino",
        " coding-assistant",
        " multimodal",
        " cost-optimization",
        " agent-zero",
        " pinoy-ai",
        " tts",
        " cli"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ded868c69ed07248d1077c4acbbb64edf7ccbf9df44135e7f2ea30c67c0e7b16",
                "md5": "c26b876808e9395fb526c6ade1e89baa",
                "sha256": "cc01ca1fba1574d241152014b88c3763bf311e5ac2c5691b56c3380ce1af2c03"
            },
            "downloads": -1,
            "filename": "pareng_boyong-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c26b876808e9395fb526c6ade1e89baa",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 59985,
            "upload_time": "2025-08-05T12:34:38",
            "upload_time_iso_8601": "2025-08-05T12:34:38.951950Z",
            "url": "https://files.pythonhosted.org/packages/de/d8/68c69ed07248d1077c4acbbb64edf7ccbf9df44135e7f2ea30c67c0e7b16/pareng_boyong-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5c1579a06476b9fd1a8b0c8c1b761e3043aee6241e27efe98338a5474d013854",
                "md5": "234f257e9bde9df80b587c79acca96ee",
                "sha256": "28c0a144f0a27c59c91de7f732f90436d3f494787eccf528e9325fa57293339e"
            },
            "downloads": -1,
            "filename": "pareng_boyong-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "234f257e9bde9df80b587c79acca96ee",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 60991,
            "upload_time": "2025-08-05T12:34:40",
            "upload_time_iso_8601": "2025-08-05T12:34:40.989504Z",
            "url": "https://files.pythonhosted.org/packages/5c/15/79a06476b9fd1a8b0c8c1b761e3043aee6241e27efe98338a5474d013854/pareng_boyong-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-05 12:34:40",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "innovatehub-ph",
    "github_project": "pareng-boyong",
    "github_not_found": true,
    "lcname": "pareng-boyong"
}