Apppublic

gaurangpatelahm/art-studio

sourceHugging Faceupdated 1y agoView on Hugging Face

0likes

App README

🎨 AI Visual Art Studio IDE

![Hugging Face Spaces](https://huggingface.co/spaces) ![Python](https://python.org) ![Gradio](https://gradio.app) ![OpenAI](https://openai.com)

A simplified creative IDE that uses OpenAI Agents SDK with intelligent delegation flow for multi-agent creative collaboration. Instead of rigid pipelines, agents naturally delegate to each other based on task requirements and expertise.

🚀 Ready for instant Docker deployment to Hugging Face Spaces!

🚀 Live Demo

Try the AI Visual Art Studio live on Hugging Face Spaces (Docker-based):

![Hugging Face Spaces](https://huggingface.co/spaces)

Deploy your own instance:

bash

# Quick deployment to Hugging Face Spaces
./deploy_to_hf.sh your-username

🌟 Key Features

🤖 Intelligent Agent Delegation

—Concept Artist: Creative director who can delegate specialized tasks
—Sketch Artist: Visual creator who can delegate refinement work
—Refinement Artist: Detail specialist who can delegate evaluation
—Curator: Final evaluator who can request improvements from any agent

🔄 Natural Delegation Flow

—No fixed order - agents decide when to delegate based on task needs
—Intelligent handoffs - each agent focuses on their expertise
—Collaborative creation - multiple agents work together naturally
—Flexible workflows - adapts to different creative requirements

🔧 OpenAI Agents SDK Integration

—Built-in tracing for all executions and delegations
—Decorator-based tools (@tool, @guardrail, @trace)
—Agent-to-agent communication through delegation tools
—Content safety with built-in guardrails

🎨 Creative Workflow Examples

—Concept → Sketch → Refinement → Curator (full creative process)
—Concept → Curator (quick evaluation)
—Sketch → Refinement → Curator (visual improvement focus)
—Curator → Refinement (quality improvement requests)

🚀 Quick Start

Option 1: Deploy to Hugging Face Spaces (Recommended)

Deploy instantly with one command:

bash

# Clone this repository
git clone https://github.com/your-username/ai-art-studio.git
cd ai-art-studio

# Deploy to Hugging Face Spaces
./deploy_to_hf.sh your-username

Then set your OpenAI API key in the Space settings:

—Go to your Space settings
—Add environment variable: OPENAI_API_KEY=your_actual_key
—Wait for build to complete (2-5 minutes)

Option 2: Local Development

1. Setup Environment

bash

# Clone the repository
git clone <your-repo>
cd art_studio

# Install dependencies
pip install -r requirements.txt

# Set your OpenAI API key
echo "OPENAI_API_KEY=your_key_here" > .env

2. Run the Studio

bash

# Launch the Gradio web interface
python main.py

# Or run examples directly
python example_usage.py

3. Use the Delegation Flow

1.Start with any agent as your primary creative partner
2.Describe your vision - agents will delegate as needed
3.Watch the collaboration unfold naturally
4.Review the results with full execution tracing

🌐 Hugging Face Spaces Deployment

What is Hugging Face Spaces?

Hugging Face Spaces is a free platform for hosting ML applications. It provides:

—🆓 Free hosting for your AI applications
—🚀 Automatic deployment from Git repositories
—🔒 Secure environment variables for API keys
—📱 Public sharing of your AI tools

Deployment Features

—Gradio Interface: Beautiful web UI for your AI Art Studio
—Docker Support: Containerized deployment for reliability
—Environment Variables: Secure API key management
—Auto-scaling: Handles traffic automatically
—Monitoring: Built-in logs and performance tracking

Space Configuration

yaml

# Space Settings
SDK: Docker
Hardware: CPU (free) or GPU (paid)
Visibility: Public or Private

# Docker Configuration
Dockerfile: Included (Python 3.9 + Gradio)
Port: 7860
Health Check: Enabled

Required Environment Variables

OPENAIAPIKEY: youropenaiapikey OPENAIMODEL: gpt-4o-mini OPENAITEMPERATURE: 0.7 OPENAIMAXTOKENS: 2000 DALLEMODEL: dall-e-3


### **Deployment Commands**

Quick deployment

./deploytohf.sh your-username

Manual deployment

git clone https://huggingface.co/spaces/your-username/ai-art-studio cd ai-art-studio

Copy files and push

git add . && git commit -m "Deploy AI Art Studio" && git push


## 🏗️ **Architecture**

### **Project Structure**

ai-art-studio/ ├── app.py # Main entry point (runs on port 7860) ├── main.py # Alternative local entry point ├── requirements.txt # Python dependencies ├── Dockerfile # Container configuration ├── src/ # Source code │ ├── core/ # Core AI logic │ └── ui/ # Gradio interface ├── .gitignore # Git exclusions └── README.md # This file with HF config


### **Core Components**

ArtStudio ├── Agent Management (OpenAI Agents SDK) ├── Delegation Flow Engine ├── Tool System (@tool decorators) ├── Guardrails (@guardrail decorators) ├── Tracing (@trace decorators) └── Gradio Web Interface


### **Delegation Patterns**

Concept Artist ├── Can delegate to: Sketch Artist, Refinement Artist, Curator └── Role: Creative direction and coordination

Sketch Artist ├── Can delegate to: Refinement Artist, Curator └── Role: Visual creation and composition

Refinement Artist ├── Can delegate to: Curator └── Role: Technical improvement and detail work

Curator ├── Can delegate to: Concept Artist, Sketch Artist, Refinement Artist └── Role: Quality evaluation and improvement requests


## 🎯 **Usage Examples**

### **Basic Delegation Flow**

from src.core.art_studio import ArtStudio

Initialize the studio

studio = ArtStudio()

Execute delegation flow

result = await studio.executedelegationflow( "Design a magical forest scene with glowing mushrooms", "concept_artist" # Start with concept artist )

Agents will automatically delegate as needed

print(f"Completed in {result['total_iterations']} iterations")


### **Single Agent Execution**

Execute a specific agent

result = await studio.executeagent( "sketchartist", "Create a sketch based on this concept: futuristic cityscape" )


### **Agent Information**

Get agent capabilities

agentinfo = studio.getagentinfo("conceptartist") print(f"Can delegate to: {agentinfo['candelegate_to']}")


## 🔍 **Tracing & Debugging**

### **Built-in Tracing**
- **All agent executions** are automatically traced
- **Delegation decisions** are logged and tracked
- **Performance metrics** for each agent
- **Full execution chain** visibility

### **Debug Information**
- **Agent delegation patterns**
- **Tool usage statistics**
- **Execution time tracking**
- **Error handling and recovery**

## 🛡️ **Safety & Guardrails**

### **Content Safety**
- **Built-in filtering** for inappropriate content
- **Bias detection** and mitigation
- **Copyright protection** measures
- **Quality standards** enforcement

### **Guardrail System**
- **@guardrail decorators** for input/output filtering
- **Configurable safety rules**
- **Automatic content review**
- **Escalation procedures**

## 🎨 **Creative Workflows**

### **Full Creative Process**
1. **Concept Artist** generates creative vision
2. **Delegates to Sketch Artist** for visual representation
3. **Sketch Artist delegates to Refinement Artist** for details
4. **Refinement Artist delegates to Curator** for evaluation
5. **Curator may request improvements** from any agent

### **Quick Evaluation**
1. **Concept Artist** creates concept
2. **Delegates directly to Curator** for assessment
3. **Curator provides feedback** and recommendations

### **Visual Improvement Focus**
1. **Sketch Artist** creates initial sketch
2. **Delegates to Refinement Artist** for enhancement
3. **Refinement Artist delegates to Curator** for final review

## 🚀 **Advanced Features**

### **Custom Tools**
- **Easy tool creation** with `@tool` decorator
- **Agent-specific tools** for specialized tasks
- **Tool composition** and chaining
- **External API integration**

### **Model Configuration**
- **Per-agent model selection**
- **Parameter customization**
- **Hot-swapping capabilities**
- **Performance optimization**

### **Extensibility**
- **Plugin system** for custom agents
- **External tool integration**
- **Workflow customization**
- **API endpoints** for external access

## 📊 **Performance & Monitoring**

### **Execution Metrics**
- **Agent response times**
- **Delegation frequency**
- **Tool usage patterns**
- **Error rates and recovery**

### **Resource Management**
- **Memory usage optimization**
- **Concurrent execution** support
- **Rate limiting** and throttling
- **Resource cleanup** and management

## 🔮 **Roadmap**

### **Phase 1: Core Delegation** ✅
- [x] Basic delegation flow
- [x] Agent-to-agent communication
- [x] Built-in tracing
- [x] Content safety

### **Phase 2: Advanced Features**
- [ ] Multi-modal support (images, audio)
- [ ] Advanced guardrails
- [ ] Performance optimization
- [ ] External tool integration

### **Phase 3: Enterprise Features**
- [ ] Team collaboration
- [ ] Advanced analytics
- [ ] Custom agent training
- [ ] Enterprise security

## 🚨 **Troubleshooting**

### **Hugging Face Spaces Issues**

**"Missing configuration in README"**
- ✅ **Fixed**: This README now contains complete HF Spaces configuration
- Ensure you're using the latest version of this repository

**"Space is missing an app file"**
- ✅ **Fixed**: `app.py` is properly configured and exposes the `demo` object
- Verify `app.py` exists in your Space root directory

**Build failures**
- Check that `requirements.txt` contains all dependencies
- Ensure Python version is set to 3.9
- Verify environment variables are set correctly

**Import errors**
- Confirm all source files are in the `src/` directory
- Check that `app.py` imports are working locally first

### **Local Development Issues**

**OpenAI API errors**
- Verify your `.env` file contains `OPENAI_API_KEY`
- Check API key validity and account credits
- Ensure you're using supported models

**Gradio interface issues**
- Check that port 7860 is available
- Verify all dependencies are installed
- Check console for error messages

### **Getting Help**
- 📖 **Documentation**: Check this README and `README_HF_SPACES.md`
- 🐛 **Issues**: Report bugs in the GitHub repository
- 💬 **Community**: Join our discussions for support

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### **Development Setup**

Install development dependencies

pip install -r requirements-dev.txt

Run tests

pytest

Code formatting

black src/ isort src/


## 📄 **License**

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 **Acknowledgments**

- **OpenAI Agents SDK** for the powerful agent framework
- **Gradio** for the beautiful web interface
- **Community contributors** for ideas and feedback

---

**🎨 Create, Collaborate, Delegate - Let AI agents work together naturally!**