Add Hugging Face Space app files

README.md

@@ -1,12 +1,38 @@
 ---
-title: Mcp
-emoji: ⚡
-colorFrom: yellow
-colorTo: yellow
+title: Forge AI Agent
+emoji: Forge AI Agent 🚀
+colorFrom: blue
+colorTo: green
 sdk: gradio
-sdk_version: 5.36.2
+sdk_version: 4.28.3
+python_version: 3.10
 app_file: app.py
-pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Forge - The Autonomous AI Software Engineer
+
+This Hugging Face Space demonstrates the "Forge" concept: an autonomous AI agent that can understand a high-level goal, create a plan, and execute it using a suite of tools exposed via the Model Context Protocol (MCP).
+
+## How It Works
+
+1.  **User Goal**: You provide a high-level software development task in the textbox.
+2.  **Planning**: An AI agent (mocked in this demo) receives the goal and a list of available tools. It generates a step-by-step plan to achieve the goal.
+3.  **Execution**: The Forge orchestrator executes each step in the plan by calling the appropriate tool from a mock MCP server.
+4.  **Live Feedback**: The agent's thoughts, actions, and results are streamed to the UI in real-time.
+
+## Running Locally
+
+This application is designed to be self-contained, but for local development, you need to run the mock MCP servers that the agent communicates with.
+
+1.  **Install dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+2.  **Run the mock servers in a separate terminal:**
+    ```bash
+    python mock_mcp_servers/run_servers.py
+    ```
+3.  **Run the Gradio app:**
+    ```bash
+    gradio app.py
+    ```

app.py

@@ -0,0 +1,83 @@
+import gradio as gr
+import asyncio
+import os
+import multiprocessing
+import uvicorn
+import time
+from src.forge_agent import ForgeApp
+
+def run_server(app_path: str, port: int):
+    """Helper function to run a uvicorn server."""
+    uvicorn.run(app_path, host="127.0.0.1", port=port, log_level="info")
+
+# --- Launch background MCP servers ---
+# This code runs once when the Gradio app starts.
+servers_to_run = {
+    "mock_mcp_servers.github_server:app": 8001,
+    "mock_mcp_servers.sandbox_server:app": 8002,
+}
+for app_path, port in servers_to_run.items():
+    process = multiprocessing.Process(target=run_server, args=(app_path, port), daemon=True)
+    process.start()
+time.sleep(2) # Give servers a moment to start
+
+async def run_forge_agent(goal: str, hf_token: str, progress=gr.Progress(track_tqdm=True)):
+    """
+    The main function to be called by the Gradio interface.
+    It instantiates and runs the ForgeApp, yielding updates to the UI.
+    """
+    if not goal:
+        yield "Please enter a goal.", ""
+        return
+    
+    if not hf_token:
+        yield [("Please provide a Hugging Face API Token to use the planner agent.", None)]
+        return
+
+    # These are the URLs for our mock servers. In a real scenario,
+    # these could point to any deployed MCP server.
+    mcp_server_urls = [
+        "http://127.0.0.1:8001",  # Mock GitHub Server
+        "http://127.0.0.1:8002",  # Mock Sandbox Server
+    ]
+
+    app = ForgeApp(goal=goal, mcp_server_urls=mcp_server_urls, hf_token=hf_token)
+    
+    # The chatbot history will store the conversation
+    chatbot_history = []
+    full_log = ""
+
+    # The run method is a generator, yielding updates as it progresses.
+    async for update in app.run():
+        # Append the update to the full log and update the chatbot history
+        full_log += update + "\n"
+        chatbot_history.append((None, update.strip()))
+        yield chatbot_history
+
+
+with gr.Blocks(theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# 🚀 Forge - The Autonomous AI Agent")
+    gr.Markdown("Enter a high-level goal, and watch the AI agent create and execute a plan to achieve it.")
+
+    chatbot = gr.Chatbot(label="Agent Log", height=500, show_copy_button=True)
+    
+    with gr.Row():
+        goal_input = gr.Textbox(
+            label="Agent's Goal",
+            placeholder="e.g., Scaffold a new Next.js blog and create a GitHub repo for it.",
+            scale=4,
+        )
+        run_button = gr.Button("Start", variant="primary", scale=1)
+    
+    with gr.Accordion("Advanced Settings", open=False):
+        hf_token_input = gr.Textbox(
+            label="Hugging Face API Token",
+            placeholder="hf_...",
+            type="password",
+            value=os.environ.get("HF_TOKEN", ""), # Read from Space secrets if available
+        )
+
+    run_button.click(fn=run_forge_agent, inputs=[goal_input, hf_token_input], outputs=[chatbot])
+
+if __name__ == "__main__":
+    demo.launch()

forge_agent.py

@@ -0,0 +1,147 @@
+import asyncio
+import json
+from typing import List, Dict, Any
+from huggingface_hub import AsyncInferenceClient
+from .mcp_client import MCPClient
+
+class ToolRegistry:
+    """Manages connections to all required MCP servers and their tools."""
+    def __init__(self, server_urls: List[str]):
+        self.servers: Dict[str, MCPClient] = {url: MCPClient(url) for url in server_urls}
+        self.tools: Dict[str, Dict[str, Any]] = {}
+
+    async def discover_tools(self):
+        """Discovers all available tools from all connected MCP servers."""
+        discovery_tasks = [client.list_tools() for client in self.servers.values()]
+        results = await asyncio.gather(*discovery_tasks, return_exceptions=True)
+
+        for i, client in enumerate(self.servers.values()):
+            server_tools = results[i]
+            if isinstance(server_tools, list):
+                for tool in server_tools:
+                    self.tools[tool["name"]] = {"client": client, "description": tool["description"]}
+
+    async def execute(self, tool_name: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Finds the correct MCP server and executes the tool."""
+        if tool_name not in self.tools:
+            raise ValueError(f"Tool '{tool_name}' not found in registry.")
+        tool_info = self.tools[tool_name]
+        return await tool_info["client"].execute_tool(tool_name, params)
+
+    async def close_all(self):
+        """Closes all client connections."""
+        await asyncio.gather(*(client.close() for client in self.servers.values()))
+
+class HuggingFaceAgent:
+    """An AI agent that uses a Hugging Face model to generate plans."""
+    def __init__(self, hf_token: str, model_name: str = "mistralai/Mixtral-8x7B-Instruct-v0.1"):
+        self.model = model_name
+        self.client = AsyncInferenceClient(model=model_name, token=hf_token)
+
+    def _construct_prompt(self, goal: str, available_tools: List[Dict[str, Any]], previous_steps: List = None, error: str = None) -> str:
+        """Constructs the detailed prompt for the LLM."""
+        tools_json_string = json.dumps(available_tools, indent=2)
+        
+        prompt = f"""You are Forge, an autonomous AI agent. Your task is to create a step-by-step plan to achieve a goal.
+You must respond with a valid JSON array of objects, where each object represents a step in the plan.
+Each step must have 'step', 'thought', 'tool', and 'params' keys.
+The final step must always use the 'report_success' tool.
+
+Available Tools:
+{tools_json_string}
+
+Goal: "{goal}"
+"""
+        if previous_steps:
+            prompt += f"\nYou have already completed these steps:\n{json.dumps(previous_steps, indent=2)}\n"
+        if error:
+            prompt += f"\nAn error occurred during the last step: {error}\nAnalyze the error and create a new, corrected plan to achieve the original goal. Start the new plan from the current state."
+
+        prompt += "\nGenerate the JSON plan now:"
+        return prompt
+
+    async def _invoke_llm(self, prompt: str) -> List[Dict[str, Any]]:
+        """Invokes the LLM and parses the JSON response."""
+        try:
+            response = await self.client.text_generation(prompt, max_new_tokens=1024)
+            # The response might contain the JSON within backticks or other text.
+            json_response_str = response.strip().split('```json')[-1].split('```')[0].strip()
+            plan = json.loads(json_response_str)
+            if isinstance(plan, list):
+                return plan
+            else:
+                raise ValueError("LLM did not return a JSON list.")
+        except (json.JSONDecodeError, ValueError, IndexError) as e:
+            print(f"Error parsing LLM response: {e}\nRaw response:\n{response}")
+            # Fallback or re-try logic could be added here
+            return [{"step": 1, "thought": "Failed to generate a plan due to a parsing error.", "tool": "report_failure", "params": {"message": f"LLM response parsing failed: {e}"}}]
+
+    async def generate_plan(self, goal: str, available_tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Generates a step-by-step plan.
+        """
+        prompt = self._construct_prompt(goal, available_tools)
+        return await self._invoke_llm(prompt)
+
+    async def regenerate_plan_on_error(self, goal: str, available_tools: List[Dict[str, Any]], completed_steps: List, error_message: str) -> List[Dict[str, Any]]:
+        """Generates a new plan after an error occurred."""
+        prompt = self._construct_prompt(goal, available_tools, previous_steps=completed_steps, error=error_message)
+        return await self._invoke_llm(prompt)
+
+class ForgeApp:
+    """The main orchestrator for the Forge application."""
+    def __init__(self, goal: str, mcp_server_urls: List[str], hf_token: str):
+        self.goal = goal
+        self.planner = HuggingFaceAgent(hf_token=hf_token)
+        self.tool_registry = ToolRegistry(server_urls=mcp_server_urls)
+
+    async def run(self):
+        """
+        Runs the agent and yields status updates as a generator.
+        """
+        yield "🚀 **Starting Forge... Initializing systems.**"
+        await self.tool_registry.discover_tools()
+        yield f"✅ **Tool Discovery Complete.** Found {len(self.tool_registry.tools)} tools."
+        
+        # Provide the LLM with full tool details, not just names
+        available_tools_details = [{"name": name, "description": data["description"]} for name, data in self.tool_registry.tools.items()]
+        
+        yield f"🧠 **Generating a plan for your goal:** '{self.goal}'"
+        plan = await self.planner.generate_plan(self.goal, available_tools_details)
+        yield "📝 **Plan Generated!** Starting execution..."
+
+        completed_steps = []
+        while plan:
+            task = plan.pop(0)
+            yield f"\n**[Step {task.get('step', '?')}]** 🤔 **Thought:** {task.get('thought', 'N/A')}"
+
+            tool_name = task.get("tool")
+            if tool_name in ["report_success", "report_failure"]:
+                emoji = "🎉" if tool_name == "report_success" else "🛑"
+                yield f"{emoji} **Final Result:** {task.get('params', {}).get('message', 'N/A')}"
+                plan = [] # End execution
+                continue
+
+            try:
+                yield f"🛠️ **Action:** Executing tool `{tool_name}` with params: `{task.get('params', {})}`"
+                result = await self.tool_registry.execute(tool_name, task.get("params", {}))
+                
+                if result.get("status") == "error":
+                    error_message = result.get('result', 'Unknown error')
+                    yield f"❌ **Error:** {error_message}"
+                    yield "🧠 **Agent is re-evaluating the plan based on the error...**"
+                    completed_steps.append({"step": task, "outcome": "error", "details": error_message})
+                    plan = await self.planner.regenerate_plan_on_error(self.goal, available_tools_details, completed_steps, error_message)
+                    yield "📝 **New Plan Generated!** Resuming execution..."
+                else:
+                    observation = result.get('result', 'Tool executed successfully.')
+                    yield f"✅ **Observation:** {observation}"
+                    completed_steps.append({"step": task, "outcome": "success", "details": observation})
+
+            except Exception as e:
+                yield f"❌ **Critical Error executing step {task.get('step', '?')}:** {e}"
+                yield "🛑 **Execution Halted due to critical error.**"
+                plan = [] # End execution
+        
+        await self.tool_registry.close_all()
+        yield "\n🏁 **Forge execution finished.**"

mock_mcp_servers/github_server.py

@@ -0,0 +1,22 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/mcp/tools")
+async def list_tools():
+    return {
+        "tools": [
+            {
+                "name": "create_repo",
+                "description": "Creates a new GitHub repository.",
+                "input_schema": {"name": "string", "private": "boolean"},
+            }
+        ]
+    }
+
+@app.post("/mcp/tools/create_repo")
+async def create_repo(payload: dict):
+    params = payload.get("params", {})
+    repo_name = params.get("name", "unnamed-repo")
+    print(f"[GitHub Server] Received request to create repo: {repo_name}")
+    return {"status": "success", "result": f"Successfully created GitHub repository '{repo_name}'."}

mock_mcp_servers/run_servers.py

@@ -0,0 +1,18 @@
+import uvicorn
+import multiprocessing
+
+def run_github_server():
+    uvicorn.run("mock_mcp_servers.github_server:app", host="127.0.0.1", port=8001, log_level="info")
+
+def run_sandbox_server():
+    uvicorn.run("mock_mcp_servers.sandbox_server:app", host="127.0.0.1", port=8002, log_level="info")
+
+if __name__ == "__main__":
+    p1 = multiprocessing.Process(target=run_github_server)
+    p2 = multiprocessing.Process(target=run_sandbox_server)
+
+    p1.start()
+    p2.start()
+
+    p1.join()
+    p2.join()

mock_mcp_servers/sandbox_server.py

@@ -0,0 +1,50 @@
+from fastapi import FastAPI
+import subprocess
+import os
+
+app = FastAPI()
+
+@app.get("/mcp/tools")
+async def list_tools():
+    return {
+        "tools": [
+            {
+                "name": "execute_shell",
+                "description": "Executes a shell command in a secure sandbox.",
+                "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]},
+            },
+            {
+                "name": "list_files",
+                "description": "Lists files and directories in a given path within the sandbox.",
+                "input_schema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]},
+            }
+        ]
+    }
+
+@app.post("/mcp/tools/execute_shell")
+async def execute_shell(payload: dict):
+    params = payload.get("params", {})
+    command = params.get("command")
+    if not command:
+        return {"status": "error", "result": "No command provided."}
+    
+    print(f"[Sandbox Server] Executing: {command}")
+    try:
+        # In a real-world scenario, this would be a heavily secured, isolated container.
+        # For this demo, we use subprocess with a timeout.
+        result = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=30, check=True)
+        output = f"STDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"
+        return {"status": "success", "result": output}
+    except subprocess.CalledProcessError as e:
+        return {"status": "error", "result": f"Command failed with exit code {e.returncode}.\nSTDOUT:\n{e.stdout}\nSTDERR:\n{e.stderr}"}
+    except subprocess.TimeoutExpired:
+        return {"status": "error", "result": "Command timed out after 30 seconds."}
+
+@app.post("/mcp/tools/list_files")
+async def list_files(payload: dict):
+    path = payload.get("params", {}).get("path", ".")
+    try:
+        files = os.listdir(path)
+        return {"status": "success", "result": f"Files in '{path}': {files}"}
+    except FileNotFoundError:
+        return {"status": "error", "result": f"Path not found: {path}"}

requirements.txt

@@ -0,0 +1,6 @@
+gradio==4.28.3
+httpx==0.27.0
+fastapi==0.111.0
+uvicorn==0.29.0
+aiohttp==3.9.5
+huggingface_hub==0.22.2

src/forge_agent.py

@@ -0,0 +1,99 @@
+import asyncio
+from typing import List, Dict, Any
+from .mcp_client import MCPClient
+
+class ToolRegistry:
+    """Manages connections to all required MCP servers and their tools."""
+    def __init__(self, server_urls: List[str]):
+        self.servers: Dict[str, MCPClient] = {url: MCPClient(url) for url in server_urls}
+        self.tools: Dict[str, Dict[str, Any]] = {}
+
+    async def discover_tools(self):
+        """Discovers all available tools from all connected MCP servers."""
+        discovery_tasks = [client.list_tools() for client in self.servers.values()]
+        results = await asyncio.gather(*discovery_tasks, return_exceptions=True)
+
+        for i, client in enumerate(self.servers.values()):
+            server_tools = results[i]
+            if isinstance(server_tools, list):
+                for tool in server_tools:
+                    self.tools[tool["name"]] = {"client": client, "description": tool["description"]}
+
+    async def execute(self, tool_name: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Finds the correct MCP server and executes the tool."""
+        if tool_name not in self.tools:
+            raise ValueError(f"Tool '{tool_name}' not found in registry.")
+        tool_info = self.tools[tool_name]
+        return await tool_info["client"].execute_tool(tool_name, params)
+
+    async def close_all(self):
+        """Closes all client connections."""
+        await asyncio.gather(*(client.close() for client in self.servers.values()))
+
+class AIAgent:
+    """A mock AI agent that generates a plan based on a goal."""
+    def __init__(self, model_name: str = "mock-planner"):
+        self.model = model_name
+
+    async def generate_plan(self, goal: str, available_tools: List[str]) -> List[Dict[str, Any]]:
+        """
+        Generates a step-by-step plan.
+        In a real application, this would involve a call to a powerful LLM.
+        Here, we use a hardcoded plan for demonstration.
+        """
+        await asyncio.sleep(1)  # Simulate LLM thinking time
+        
+        # This is a mock plan. A real LLM would generate this dynamically.
+        plan = [
+            {"step": 1, "thought": "I need a place to store the code. I'll use the `create_repo` tool.", "tool": "create_repo", "params": {"name": "my-awesome-blog", "private": False}},
+            {"step": 2, "thought": "Now I need to scaffold a new Next.js application inside a secure sandbox.", "tool": "execute_shell", "params": {"command": "npx create-next-app@latest my-awesome-blog --yes"}},
+            {"step": 3, "thought": "The project is created. I should commit the initial code.", "tool": "execute_shell", "params": {"command": "cd my-awesome-blog && git init && git add . && git commit -m 'Initial commit'"}},
+            {"step": 4, "thought": "The plan is complete. I will report success.", "tool": "report_success", "params": {"message": "Blog project scaffolded successfully."}}
+        ]
+        return plan
+
+class ForgeApp:
+    """The main orchestrator for the Forge application."""
+    def __init__(self, goal: str, mcp_server_urls: List[str]):
+        self.goal = goal
+        self.planner = AIAgent()
+        self.tool_registry = ToolRegistry(server_urls=mcp_server_urls)
+
+    async def run(self):
+        """
+        Runs the agent and yields status updates as a generator.
+        """
+        yield "🚀 **Starting Forge... Initializing systems.**"
+        await self.tool_registry.discover_tools()
+        yield f"✅ **Tool Discovery Complete.** Found {len(self.tool_registry.tools)} tools."
+
+        available_tool_names = list(self.tool_registry.tools.keys())
+        yield f"🧠 **Generating a plan for your goal:** '{self.goal}'"
+        plan = await self.planner.generate_plan(self.goal, available_tool_names)
+        yield "📝 **Plan Generated!** Starting execution..."
+
+        for task in plan:
+            yield f"\n**[Step {task['step']}]** 🤔 **Thought:** {task['thought']}"
+            
+            if task["tool"] == "report_success":
+                yield f"🎉 **Final Result:** {task['params']['message']}"
+                break
+
+            try:
+                yield f"🛠️ **Action:** Executing tool `{task['tool']}` with params: `{task['params']}`"
+                result = await self.tool_registry.execute(task["tool"], task["params"])
+                
+                if result.get("status") == "error":
+                    yield f"❌ **Error:** {result.get('result', 'Unknown error')}"
+                    yield "🛑 **Execution Halted due to error.**"
+                    break
+                else:
+                    yield f"✅ **Observation:** {result.get('result', 'Tool executed successfully.')}"
+
+            except Exception as e:
+                yield f"❌ **Critical Error executing step {task['step']}:** {e}"
+                yield "🛑 **Execution Halted due to critical error.**"
+                break
+        
+        await self.tool_registry.close_all()
+        yield "\n🏁 **Forge execution finished.**"

src/mcp_client.py

@@ -0,0 +1,45 @@
+import httpx
+from typing import List, Dict, Any
+
+class MCPClient:
+    """
+    A client for interacting with a Model Context Protocol (MCP) server.
+    Handles listing and executing tools via HTTP requests.
+    """
+    def __init__(self, server_url: str):
+        self.server_url = server_url.rstrip('/')
+        self.http_client = httpx.AsyncClient(timeout=30.0)
+
+    async def list_tools(self) -> List[Dict[str, Any]]:
+        """Fetches the list of available tools from the MCP server."""
+        try:
+            response = await self.http_client.get(f"{self.server_url}/mcp/tools")
+            response.raise_for_status()
+            tools_response = response.json()
+            # Ensure the response is in the expected format
+            if "tools" in tools_response and isinstance(tools_response["tools"], list):
+                return tools_response["tools"]
+            return []
+        except (httpx.RequestError, httpx.HTTPStatusError) as e:
+            print(f"Error fetching tools from {self.server_url}: {e}")
+            return []
+
+    async def execute_tool(self, tool_name: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Executes a specific tool on the MCP server with the given parameters."""
+        try:
+            response = await self.http_client.post(
+                f"{self.server_url}/mcp/tools/{tool_name}",
+                json={"params": params}
+            )
+            response.raise_for_status()
+            return response.json()
+        except (httpx.RequestError, httpx.HTTPStatusError) as e:
+            print(f"Error executing tool '{tool_name}' on {self.server_url}: {e}")
+            return {
+                "status": "error",
+                "result": f"Failed to connect or execute tool on {self.server_url}. Error: {e}"
+            }
+
+    async def close(self):
+        """Closes the underlying HTTP client."""
+        await self.http_client.aclose()