Upload README.md

README.md

@@ -1,116 +1,180 @@
-# MCO Protocol Hackathon Submission
+---
+title: MCO Protocol Real Agent Orchestration
+emoji: 🚀
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_file: app.py
+pinned: false
+---
 
-## Real AutoGPT Agent with MCO Orchestration
+# 🚀 MCO Protocol: Real Agent Orchestration Demo
 
-This project demonstrates the power of MCO (Model Configuration Orchestration) as the missing orchestration layer for agent frameworks. It features a real AutoGPT-like agent built with Modal API that is orchestrated by the MCO MCP server, with a single-page UI showing the agent's thinking process and orchestration logs.
+**agent-demo-track**
 
-## Key Features
+## 🎯 Hackathon Submission: Track 3 - Agentic Demo
+
+This is a complete Gradio app showcasing the power of **MCO (Model Configuration Orchestration)** - the missing orchestration layer for AI agents. Experience real AutoGPT-style agents being orchestrated by an actual MCO MCP server with progressive revelation and persistent memory.
 
-- **Real Modal API Integration**: Genuine LLM inference with Claude
-- **Real MCO Orchestration**: Using the actual MCO MCP server (not simulated)
-- **Single-Page UI**: Shows Claude's thinking process and MCO orchestration logs
-- **Visual SNLP Generator**: Edit values and NLP with a simple toggle
-- **Code Review Agent**: Specialized for analyzing and improving code
+## 🎮 Live Demo
 
-## Project Structure
+🔗 **[Try the Live Demo](https://huggingface.co/spaces/Agents-MCP-Hackathon/mco-protocol-real-orchestration)**
 
-- `main.py`: Main entry point that integrates all components
-- `modal_implementation.py`: AutoGPT-like agent implementation using Modal
-- `gradio_ui.py`: Single-page Gradio UI for demonstration
-- `mco-config/`: Directory containing SNLP files for orchestration
-- `knowledge_graph.md`: Research on Modal, MCO, and Gradio integration
-- `modal_agent_design.md`: Detailed design of the Modal agent
-- `integration_documentation.md`: Documentation of the complete system
+## 📹 Video Overview
 
-## Getting Started
+🎥 **[Watch the App Overview Video](https://youtu.be/VIDEO_ID_HERE)** *(Video explaining usage and purpose)*
 
-### Prerequisites
+## ✨ What Makes This Demo Special
 
-- Python 3.8+
-- Node.js 14+
-- Modal account with API key
-- Anthropic API key for Claude
+### 🤖 **Real AutoGPT Agent + Real MCO Orchestration**
+- **Generic AutoGPT Agent**: Standard agent with tools (not MCO-specific)
+- **Real MCO MCP Server**: Actual subprocess orchestration (Docker-enabled)
+- **Progressive Revelation**: Watch MCO strategically inject context at optimal moments
+- **Live Modal Credits**: Real LLM inference with Claude via Modal API
 
-### Installation
+### 🎛️ **Single-Page Experience**
+- **Side-by-Side Logs**: See Claude's `<thinking>` process and MCO orchestration in real-time
+- **Visual SNLP Generator**: Create MCO workflow files without learning syntax
+- **Downloadable Results**: Export generated SNLP configurations
 
-1. Clone this repository:
-   ```
-   git clone https://github.com/yourusername/mco-hackathon.git
-   cd mco-hackathon
-   ```
-
-2. Install Python dependencies:
-   ```
-   pip install -r requirements.txt
-   ```
-
-3. Install MCO Protocol:
-   ```
-   npm install @paradiselabs/mco-protocol
-   ```
-
-4. Set up environment variables:
-   ```
-   export ANTHROPIC_API_KEY=your_anthropic_api_key
-   export MODAL_TOKEN_ID=your_modal_token_id
-   export MODAL_TOKEN_SECRET=your_modal_token_secret
-   ```
-
-### Running the Demo
-
-1. Start the application:
-   ```
-   python main.py
-   ```
-
-2. Open your browser and navigate to the provided URL
-
-3. Use the Agent Demo tab to run the agent with MCO orchestration
-
-4. Use the SNLP Generator tab to create and edit MCO workflow files
-
-## Using MCO with Your Own Agent
-
-1. Install the MCO package:
-   ```
-   npm install @paradiselabs/mco-protocol
-   ```
-
-2. Add MCO to your MCP config:
-   ```json
-   {
-     "mcpServers": {
-       "mco-orchestration": {
-         "command": "node",
-         "args": ["path/to/mco-mcp-server.js"],
-         "env": {
-           "MCO_CONFIG_DIR": "path/to/config"
-         }
-       }
-     }
-   }
-   ```
-
-3. Create SNLP files using the generator
-
-4. Run your agent with MCO orchestration
-
-## Why MCO?
-
-MCO completes the "Agentic Trifecta" alongside MCP and A2P, providing the missing orchestration layer for truly agentic AI. It solves key challenges in agent reliability through:
-
-1. **Progressive Revelation**: Strategically reveal information to agents at the right time
-2. **Structured Workflows**: Define clear steps and success criteria for agent tasks
-3. **MCP Integration**: Works with any MCP-enabled framework with one line of config
-4. **Visual Configuration**: Create SNLP files without learning syntax
-
-## License
-
-This project is licensed under the MIT License - see the LICENSE file for details.
-
-## Acknowledgements
-
-- The Modal team for their excellent serverless compute platform
-- The Anthropic team for Claude API
-- The MCP community for the Model Context Protocol
-- The Gradio team for their UI framework
+## 🛠️ Technical Architecture
+
+![Technical Architecture Diagram](https://i.imgur.com/JdK8fLm.png)
+
+## 🚀 Key Features Demonstrated
+
+### **1. Real Agent Orchestration**
+- Agent receives generic instruction: *"Use the MCO server tool to get a code review task"*
+- MCO handles all orchestration logic through existing workflow files
+- Progressive revelation injects features and styles at optimal moments
+- Agent completes task autonomously with structured workflow
+
+### **2. Live MCP Server Integration**
+- Docker container runs real Node.js + Python environment
+- MCO MCP server starts as actual subprocess
+- Real stdio communication using MCP protocol
+- Proper AsyncExitStack resource management
+
+### **3. Visual SNLP Configuration**
+- Generate complete MCO workflow files visually
+- Edit workflow names and types through simple UI
+- Download generated `mco.core`, `mco.sc`, `mco.features`, `mco.styles`
+- No need to learn SNLP syntax
+
+## 💡 The MCO Revolution
+
+This demo showcases **MCO Protocol** - completing the "Agentic Trifecta":
+- 📊 **MCP**: Data integration (*"What can I access?"*)
+- 🤝 **A2P**: Agent communication (*"How do we coordinate?"*)  
+- 🎛️ **MCO**: Reliable orchestration (*"How do we actually get things done?"*)
+
+### Before MCO vs After MCO
+
+![Before and After MCO Comparison](https://i.imgur.com/nRdLfP2.png)
+
+## 🔧 How to Use the Demo
+
+1. **Agent Demo**: 
+   - Enter any instruction for the agent
+   - Watch Claude's thinking process in real-time
+   - See MCO orchestration logs show progressive revelation
+   - Agent automatically uses MCO server tool when appropriate
+
+2. **SNLP Generator**:
+   - Set workflow name and type
+   - Generate complete MCO configuration files
+   - Download all files as a bundle
+   - Use in your own MCO projects
+
+## 🏗️ Technical Implementation
+
+### Docker Setup
+```dockerfile
+FROM node:18-slim
+RUN npm install -g @paradiselabs/mco-protocol
+# Python + dependencies
+COPY . .
+CMD ["python", "app.py"]
+```
+
+### Agent Architecture
+```python
+class GenericAutoGPTAgent:
+    # NOT MCO-specific - just a standard agent with tools
+    async def process_instruction(self, instruction):
+        # Agent decides what to do, calls MCO as needed
+        if "mco" in instruction.lower():
+            await self.call_mcp_tool("mco-orchestration", "get_next_directive", {})
+```
+
+### Real MCP Connection
+```python
+server_params = StdioServerParameters(
+    command="npx",
+    args=["@paradiselabs/mco-protocol", "--config-dir", "/app/workflow"]
+)
+# Real subprocess with AsyncExitStack
+```
+
+## 🌟 Why This Demo Matters
+
+This demo proves that **MCO solves the reliability problem** that has plagued autonomous agents since AutoGPT:
+
+1. **Progressive Revelation**: No more context overload
+2. **Structured Workflows**: Clear steps and success criteria  
+3. **MCP Integration**: Works with any framework in one line
+4. **Production Ready**: Real implementation, not just a concept
+
+## 🚀 Get Started with MCO
+
+```bash
+# Install MCO Protocol
+npm install -g @paradiselabs/mco-protocol
+
+# Add to any MCP-enabled framework
+{
+  "mcpServers": {
+    "mco-orchestration": {
+      "command": "npx",
+      "args": ["@paradiselabs/mco-protocol", "--config-dir", "./workflow"]
+    }
+  }
+}
+```
+
+## 📦 Project Structure
+
+```
+/
+├── app.py              # Main Gradio application
+├── Dockerfile          # Docker container setup
+├── requirements.txt    # Python dependencies
+├── modal_llm_client.py # Modal API integration
+├── workflow/           # MCO configuration files
+│   ├── mco.core       # Persistent memory
+│   ├── mco.sc         # Success criteria
+│   ├── mco.features   # Strategic injections
+│   └── mco.styles     # Strategic injections
+└── README.md          # This file
+```
+
+## 🏆 Hackathon Achievement
+
+This demo showcases:
+- ✅ **Real MCP Server**: Actual MCO protocol implementation
+- ✅ **Creative Agent Use**: Novel orchestration approach
+- ✅ **Production Ready**: Deployed and functional
+- ✅ **Educational Value**: Clear demonstration of agent reliability
+- ✅ **Technical Innovation**: First orchestration protocol for MCP ecosystem
+
+## 🔗 Links
+
+- 🎮 **[Live Demo](https://huggingface.co/spaces/Agents-MCP-Hackathon/mco-protocol-real-orchestration)**
+- 📹 **[Video Overview](https://youtu.be/VIDEO_ID_HERE)**
+- 📦 **[MCO NPM Package](https://www.npmjs.com/package/@paradiselabs/mco-protocol)**
+- 🐙 **[GitHub Repository](https://github.com/paradiselabs-ai/MCO-Protocol)**
+- 💬 **[Discord Community](https://discord.gg/uQ69vc4Agc)**
+
+---
+
+**agent-demo-track** | Built with ❤️ for MCP Hackathon 2025 | [Paradise Labs](https://paradiselabs.co)