Upload README.md

README.md

@@ -1,10 +1,167 @@
 ---
-title: Ml Intern Custom
-emoji: 📚
-colorFrom: green
-colorTo: red
+title: AI Agent Workspace
+colorFrom: purple
+colorTo: blue
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<p align="center">
+  <h1>🤖 AI Agent Workspace</h1>
+  <p><i>A customizable autonomous AI agent for research, coding, and ML workflows</i></p>
+</p>
+
+---
+
+## What This Is
+
+A fork of the [ML Intern](https://hf.co/spaces/smolagents/ml-intern) architecture — an autonomous AI agent that researches, writes code, and ships projects using the Hugging Face ecosystem.
+
+**Key capabilities:**
+- 🔬 **Research** — Search papers, datasets, models, and documentation
+- 💻 **Code** — Write, test, and execute Python scripts in sandboxes
+- 🚀 **Deploy** — Launch training jobs, manage repos, push to Hub
+- 📚 **Learn** — Read documentation and GitHub repos to understand APIs
+
+## Architecture
+
+```
+User (Web UI / CLI)
+    ↕
+FastAPI Backend (SSE events)
+    ↕
+Agent Loop (LiteLLM + tool router)
+    ↕
+Tools: HF docs | Papers | Datasets | GitHub | Jobs | Sandbox | MCP
+```
+
+**Stack:**
+- **Frontend:** React + Vite + TypeScript
+- **Backend:** FastAPI + SSE streaming
+- **Agent:** LiteLLM (multi-provider) + custom tool system
+- **Tools:** Hugging Face APIs, GitHub, sandbox execution, MCP servers
+
+## Quick Start
+
+### Local CLI
+
+```bash
+git clone https://huggingface.co/spaces/ScottzillaSystems/ml-intern-custom
+cd ml-intern-custom
+
+# Install dependencies (requires Python 3.11+, uv)
+uv sync
+
+# Run interactive mode
+python -m agent.main
+
+# Or headless
+python -m agent.main "your task here"
+```
+
+### Environment Variables
+
+Create `.env`:
+```bash
+# Required
+HF_TOKEN=hf_...                    # Hugging Face token
+
+# Optional - for non-HF-router models
+ANTHROPIC_API_KEY=sk-ant-...       # Claude models
+OPENAI_API_KEY=sk-...              # OpenAI models
+GITHUB_TOKEN=ghp_...               # GitHub code search
+```
+
+### Web UI
+
+The Space runs the web UI automatically. For local dev:
+```bash
+cd frontend && npm install && npm run dev   # Vite dev server
+cd backend && python main.py                 # FastAPI backend
+```
+
+## Customization Guide
+
+### 1. Change the Model
+
+Edit `configs/frontend_agent_config.json` or `configs/cli_agent_config.json`:
+
+```json
+{
+  "model_name": "moonshotai/Kimi-K2.6",
+  "mcpServers": { ... }
+}
+```
+
+**Available models via HF Router (free tier):**
+- `moonshotai/Kimi-K2.6`
+- `MiniMaxAI/MiniMax-M2.7`
+- `zai-org/GLM-5.1`
+
+**Or any LiteLLM-compatible model:**
+- `anthropic/claude-sonnet-4-5-20250929`
+- `openai/gpt-4o`
+- `google/gemini-2.5-pro`
+
+### 2. Add/Remove Tools
+
+Edit `agent/core/tools.py`:
+
+```python
+def create_builtin_tools(local_mode=False):
+    tools = [
+        # Your custom tools here
+        ToolSpec(name="my_tool", ...),
+        # ... existing tools
+    ]
+    return tools
+```
+
+### 3. Add MCP Servers
+
+Edit `configs/frontend_agent_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "transport": "http",
+      "url": "https://my-mcp-server.com/mcp",
+      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
+    }
+  }
+}
+```
+
+### 4. Customize System Prompt
+
+Edit `agent/prompts/system_prompt.yaml` to change the agent's personality and instructions.
+
+### 5. Change Branding
+
+- Frontend: Edit `frontend/src/theme.ts` for colors
+- Frontend: Edit `frontend/src/components/WelcomeScreen/WelcomeScreen.tsx` for welcome text
+- Backend: Edit `backend/main.py` for API metadata
+
+## Project Structure
+
+```
+agent/
+  core/           # Agent loop, session, context manager
+  tools/          # Tool implementations (HF, GitHub, sandbox, etc.)
+  prompts/        # System prompts
+  main.py         # CLI entry point
+backend/
+  main.py         # FastAPI app
+  routes/         # API endpoints
+  session_manager.py
+frontend/
+  src/            # React components
+configs/
+  frontend_agent_config.json
+  cli_agent_config.json
+```
+
+## Original
+
+Based on [smolagents/ml-intern](https://hf.co/spaces/smolagents/ml-intern) by Hugging Face.