# Pharos AI Doc Genie — Document Generation Skill

> **Built for Pharos Skill-to-Agent Dual Cascade Hackathon — Phase 1**
>
> A reusable, standardized Skill module that enables any AI Agent in the Pharos ecosystem to generate **real Office documents** (.pptx, .docx, .xlsx) and **source code** from natural language — powered by DashScope LLM API.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/Protocol-MCP_2024--11--05-blue.svg)](https://modelcontextprotocol.io/)

---

## 🎯 Problem Statement

AI Agents in the Pharos economy need to **produce tangible outputs** — not just text responses. When an agent helps a user prepare a business proposal, it should deliver a real `.docx` file. When it analyzes data, it should produce an actual `.xlsx` spreadsheet. When it creates a presentation, it should output a `.pptx` that opens in PowerPoint.

**Existing solutions** either:
- Generate plain text/Markdown that requires manual formatting
- Depend on proprietary cloud APIs with unpredictable availability
- Lack standardized interfaces for agent-to-skill communication

**Pharos AI Doc Genie** fills this gap with a production-ready, standardized Skill that generates real Office files and code from natural language.

---

## 🧩 Skill Architecture

```
┌──────────────────────────────────────────────┐
│                AI Agent (Pharos)              │
│         (Any MCP-compatible Agent)            │
└─────────────────┬────────────────────────────┘
                  │ MCP Protocol (JSON-RPC 2.0)
                  │ stdio transport
┌─────────────────▼────────────────────────────┐
│          Pharos AI Doc Genie Skill            │
│                                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │ generate │ │ generate │ │ generate │      │
│  │ _word    │ │  _ppt    │ │ _excel   │ ...  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘      │
│       │            │            │             │
│  ┌────▼────────────▼────────────▼──────┐      │
│  │        LLM (DashScope qwen)         │      │
│  │    Content Generation Layer         │      │
│  └────────────────┬────────────────────┘      │
│                   │                            │
│  ┌────────────────▼────────────────────┐      │
│  │     Python (python-pptx, etc.)      │      │
│  │     File Conversion Layer           │      │
│  │     Markdown → real .pptx/.docx     │      │
│  └────────────────┬────────────────────┘      │
└───────────────────┼───────────────────────────┘
                    │
         ┌──────────▼──────────┐
         │   Output Files      │
         │  .pptx  .docx       │
         │  .xlsx  .py/.js/... │
         └─────────────────────┘
```

**Key design principles:**
- **Stateless**: Each tool call is independent — no session state needed
- **Idempotent**: Same input produces consistent output structure
- **Self-contained**: Zero external service dependencies beyond the LLM API
- **Standardized**: MCP protocol ensures any compatible Agent can call it

---

## 🛠️ Tools (4 Skills)

| Tool | Output | Use Case | Model |
|------|--------|----------|-------|
| `generate_ppt` | `.pptx` presentation | Pitch decks, training, reports | qwen3.7-plus |
| `generate_word` | `.docx` document | Proposals, manuals, reports | qwen3.7-plus |
| `generate_excel` | `.xlsx` spreadsheet | Data tables, financials, inventory | qwen3.7-plus |
| `generate_code` | Source code (.py/.js/.go/...) | Rapid prototyping, boilerplate | qwen-long-latest |

### Tool Schema Examples

**generate_ppt**: Create a professional presentation
```json
{
  "name": "generate_ppt",
  "arguments": {
    "topic": "AI in Enterprise: 2026 Trends",
    "requirements": "Executive summary for CTO audience, 12 slides, focus on ROI and adoption metrics",
    "slide_count": 12
  }
}
```

**generate_excel**: Generate structured data
```json
{
  "name": "generate_excel",
  "arguments": {
    "description": "Q2 2026 sales data: Region, Product Category, Revenue, Units Sold, Growth%, Top Salesperson",
    "rows": 30
  }
}
```

---

## 🚀 Quick Start

### Prerequisites
- **Node.js** >= 18
- **Python** 3.8+ with `python-pptx`, `python-docx`, `openpyxl`
- **DashScope API Key** (Alibaba BaiLian)

### Install Python dependencies
```bash
pip install python-pptx python-docx openpyxl
```

### Run the MCP Server
```bash
node src/mcp-server.js
```

The server listens on **stdin/stdout** using the MCP stdio transport. Configure your Agent's MCP client to launch this process.

### Test with MCP Inspector
```bash
npx @modelcontextprotocol/inspector node src/mcp-server.js
```

### Manual Test (JSON-RPC via pipe)
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node src/mcp-server.js
```

---

## 📁 Project Structure

```
pharos-ai-doc-genie/
├── src/
│   └── mcp-server.js       # MCP stdio server (self-contained)
├── convert.py               # Python: Markdown → .pptx/.docx/.xlsx
├── output/                  # Generated Office files
├── package.json             # Node.js project config
├── README.md                # This file
├── LICENSE                  # MIT License
└── .gitignore
```

---

## 🔌 Integration

### With Claude Desktop
```json
{
  "mcpServers": {
    "pharos-ai-doc-genie": {
      "command": "node",
      "args": ["/absolute/path/to/pharos-ai-doc-genie/src/mcp-server.js"]
    }
  }
}
```

### With OpenAI Agents
The server uses standard MCP tool schemas that are directly compatible with OpenAI function calling format. Simply configure your Agent to launch the server as an MCP subprocess.

### With Pharos Agents
Pharos Agents can call this Skill via the MCP protocol. Once the Skill is registered, Agents discover it through `tools/list` and call it through `tools/call`.

---

## 🧪 Testing

```bash
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node src/mcp-server.js

# Generate a Word document
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_word","arguments":{"topic":"Project Proposal: AI Chatbot","requirements":"A formal proposal for building an enterprise AI chatbot. Include: executive summary, technical approach, timeline, budget estimate.","length":"medium"}}}' | node src/mcp-server.js

# Generate code
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"generate_code","arguments":{"requirement":"A Python async function that fetches data from a REST API with exponential backoff retry logic","language":"python","comments":"en"}}}' | node src/mcp-server.js
```

---

## ⚡ Performance

| Tool | Avg. Response Time | Max Tokens | File Size |
|------|--------------------|------------|-----------|
| generate_word | ~20-40s | 16384 | 30-50 KB (.docx) |
| generate_ppt | ~30-60s | 16384 | 25-40 KB (.pptx) |
| generate_excel | ~15-25s | 16384 | 5-15 KB (.xlsx) |
| generate_code | ~15-30s | 16384 | N/A (text) |

---

## 🔒 Security

- **No API key exposure**: The DashScope API key is server-side only and never sent to Agents
- **Input validation**: All Agent inputs are validated before processing
- **Output isolation**: Generated files are written to a dedicated output directory
- **No persistent state**: Each tool call is isolated with no cross-call data leakage

---

## 🗺️ Roadmap

### Phase 2 (Agent Arena)
- [ ] Deploy as a persistent Skill on Pharos chain
- [ ] On-chain billing per document generation
- [ ] NFT-based document ownership and verification
- [ ] Multi-agent collaborative document editing

### Beyond
- [ ] PDF generation and manipulation
- [ ] Image-to-document conversion (OCR → formatted docx)
- [ ] Multi-language document templates
- [ ] Real-time collaborative editing via WebSocket

---

## 👤 Author

**huimingchen081-beep** ([GitHub](https://github.com/huimingchen081-beep))

Built for the Pharos Skill-to-Agent Dual Cascade Hackathon — Phase 1 (Skill Hackathon).

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **Pharos Network** — for building the AI Agent economy infrastructure
- **DashScope (Alibaba BaiLian)** — for the LLM API powering content generation
- **Model Context Protocol (Anthropic)** — for the standardized agent-skill communication protocol
- **python-pptx / python-docx / openpyxl** — for Office file generation