devduck 0.5.4__tar.gz → 0.7.0__tar.gz

{devduck-0.5.4 → devduck-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devduck
-Version: 0.5.4
+Version: 0.7.0
 Summary: 🦆 Extreme minimalist self-adapting AI agent - one file, self-healing, runtime dependencies
 Author-email: Cagatay Cali <cagataycali@icloud.com>
 License: Apache-2.0
@@ -53,6 +53,19 @@ Dynamic: license-file
 
 One Python file that adapts to your environment, fixes itself, and expands capabilities at runtime.
 
+Learn more: https://duck.nyc
+
+## 🎬 See It In Action
+
+| Feature | What You'll See | Video |
+|---------|----------------|-------|
+| 🔥 **Hot-Reload** | Agent detects code changes and restarts instantly—no manual intervention needed. Edit your agent code or tools while running, save the file, and watch it reload automatically. | [Watch Demo](https://redduck.dev/videos/hot-reload.mp4) |
+| 🌐 **Web UI** | Clean, modern web interface for chatting with DevDuck. Real-time streaming responses, tool execution visibility, and beautiful markdown rendering. | [Watch Demo](https://redduck.dev/videos/web-ui.mp4) |
+| 🛠️ **Dynamic Tool Creation** | Create a new tool by simply saving a `.py` file in the `./tools/` directory. No restart, no configuration—the agent loads it instantly and starts using it. Pure hot-reload magic. | [Watch Demo](https://redduck.dev/videos/dynamic-tool-creation.mp4) |
+| 🌊 **TCP Streaming Server** | Connect from any client (netcat, custom apps, other agents) via TCP. Real-time streaming responses with parallel tool execution. Multi-protocol access to the same agent. | [Watch Demo](https://redduck.dev/videos/tcp.mp4) |
+| 🔌 **IPC & macOS Tray** | Unix socket-based inter-process communication with native macOS menu bar integration. DevDuck runs in your menu bar with quick actions, status indicators, and seamless IPC streaming via `/tmp/devduck_main.sock`. | ![Demo](docs/mac-os-tray.jpg) |
+| 💬 **Ambient Overlay** | Floating AI input overlay with glassmorphism UI. Real-time IPC streaming from devduck, auto-focus with blinking cursor, and ESC to hide / Enter to send. Perfect for desktop AI interactions. | [Watch Demo](https://redduck.dev/videos/floating-input.mp4) |
+
 ---
 
 ## Install & Run
@@ -101,7 +114,7 @@ devduck
 | 🧠 **Auto-RAG** | Remembers past conversations | "I prefer FastAPI" → later uses FastAPI automatically |
 | 🌊 **Multi-Protocol** | CLI, Python, TCP, WebSocket, MCP, IPC | `devduck "query"` or `nc localhost 9999` |
 | ☁️ **AWS Deploy** | One-command serverless deployment | `agentcore_config(auto_launch=True)` |
-| 🛠️ **30+ Tools** | Shell, GitHub, file editing, math, UI control | `devduck("create GitHub issue")` |
+| 🛠️ **35+ Tools** | Shell, GitHub, file editing, math, UI control | `devduck("create GitHub issue")` |
 | 🎛️ **Flexible Config** | Load only tools you need | `DEVDUCK_TOOLS="strands_tools:shell,editor"` |
 
 ---
@@ -113,7 +126,7 @@ graph TB
     A[User Input] -->|CLI/TCP/WS/MCP/IPC| B[DevDuck Core]
     B -->|Auto RAG| C[Knowledge Base]
     C -.->|Context Retrieval| B
-    B -->|Tool Calls| D[30+ Built-in Tools]
+    B -->|Tool Calls| D[35+ Built-in Tools]
     D --> E[shell/editor/calculator]
     D --> F[GitHub/AgentCore]
     D --> G[TCP/WebSocket/MCP/IPC]
@@ -165,7 +178,7 @@ devduck("refactor my code to use async/await")
 
 | Provider | Setup | When to Use |
 |----------|-------|-------------|
-| **Bedrock** (auto-detected) | [Get API key](https://console.aws.amazon.com/bedrock) → `export AWS_BEARER_TOKEN_BEDROCK=...` | Production (auto-selected if credentials found) |
+| **Bedrock** (auto-detected) | [Get API key](https://console.aws.amazon.com/bedrock) → `export AWS_BEARER_TOKEN_BEDROCK=...` | Auto-selected if credentials found |
 | **MLX** (macOS auto-detected) | Auto-detected on Apple Silicon | Local, optimized for M-series Macs |
 | **Ollama** (fallback) | `ollama pull qwen3:1.7b` | Local, free, private (used if Bedrock/MLX unavailable) |
 | **Anthropic** | `export ANTHROPIC_API_KEY=...` | Claude API direct access |
@@ -187,8 +200,8 @@ devduck
 | **Dev** | `shell`, `editor`, `file_read`, `calculator` | Code, test, debug |
 | **GitHub** | `use_github`, `create_subagent` | Issues, PRs, CI/CD automation |
 | **Network** | `tcp`, `websocket`, `mcp_server`, `ipc` | Serve agents over protocols |
-| **AWS** | `agentcore_config`, `agentcore_invoke`, `agentcore_logs` | Deploy to serverless |
-| **AI** | `use_agent`, `retrieve`, `store_in_kb` | Multi-agent, memory |
+| **AWS** | `agentcore_config`, `agentcore_invoke`, `agentcore_logs`, `agentcore_agents` | Deploy to serverless |
+| **AI** | `use_agent`, `retrieve`, `store_in_kb`, `state_manager` | Multi-agent, memory, state |
 | **UI** (macOS) | `tray`, `ambient`, `cursor`, `clipboard` | Desktop automation |
 
 <details>
@@ -204,6 +217,7 @@ devduck
 - `create_subagent` - Spawn sub-agents via GitHub Actions
 - `store_in_kb` - Store content in Bedrock Knowledge Base
 - `system_prompt` - Manage agent system prompt
+- `state_manager` - Agent state management with time-travel capabilities
 - `tray` - System tray app control (macOS)
 - `ambient` - Ambient AI input overlay (macOS)
 
@@ -225,6 +239,12 @@ devduck
 - `environment` - Environment variable management
 - `mcp_client` - Connect to external MCP servers
 - `retrieve` - Bedrock Knowledge Base retrieval
+- `scraper` - HTML/XML parsing with BeautifulSoup4
+- `fetch_github_tool` - Fetch and load tools from GitHub
+- `gist` - Comprehensive GitHub Gist management
+- `add_comment` - Add comments to GitHub issues/PRs
+- `list_issues` - List GitHub issues
+- `list_pull_requests` - List GitHub pull requests
 
 ### strands-fun-tools (macOS)
 - `listen` - Background speech transcription with Whisper
@@ -286,22 +306,75 @@ No restart. No configuration. Just works.
 |----------|---------|---------|
 | `MODEL_PROVIDER` | Auto-detect | `bedrock`, `anthropic`, `github`, `mlx`, `ollama` |
 | `STRANDS_MODEL_ID` | Auto | Model name (e.g., `qwen3:1.7b`, `claude-sonnet-4`) |
-| `DEVDUCK_TOOLS` | All | `pkg:tool1,tool2:pkg2:tool3` |
+| `DEVDUCK_TOOLS` | 37 default tools | `package:tool1,tool2:package2:tool3` format |
+| `DEVDUCK_LOAD_TOOLS_FROM_DIR` | `false` | `true`/`false` - Auto-load tools from `./tools/` directory |
 | `DEVDUCK_KNOWLEDGE_BASE_ID` | - | Bedrock KB ID for auto-RAG |
 | `DEVDUCK_TCP_PORT` | `9999` | TCP server port |
 | `DEVDUCK_ENABLE_TCP` | `true` | Enable/disable TCP |
 
-**Minimal config (shell + editor only):**
+### Tool Configuration Format
+
+**Format:** `package:tool1,tool2:package2:tool3`
+
+**Directory Auto-Loading:**
+
+By default, DevDuck **does not** automatically load tools from the `./tools/` directory. This gives you explicit control over which tools are loaded. To enable automatic loading of tools from `./tools/`, set:
+
+```bash
+export DEVDUCK_LOAD_TOOLS_FROM_DIR=true
+devduck
+```
+
+When enabled, any `.py` file in `./tools/` with a `@tool` decorator will be loaded automatically. When disabled (default), you control tool loading via `DEVDUCK_TOOLS` or runtime `manage_tools()` calls.
+
+**Examples:**
 ```bash
+# Minimal (shell + editor only)
 export DEVDUCK_TOOLS="strands_tools:shell,editor"
+
+# Dev tools only
+export DEVDUCK_TOOLS="strands_tools:shell,editor,file_read,file_write,calculator"
+
+# Full DevDuck + Strands (no fun tools)
+export DEVDUCK_TOOLS="devduck.tools:tcp,websocket,mcp_server,use_github:strands_tools:shell,editor,file_read"
+
+# Custom package
+export DEVDUCK_TOOLS="my_tools:custom_tool,another_tool:strands_tools:shell"
+
 devduck
 ```
 
+**Runtime tool management:**
+```python
+# List loaded tools
+manage_tools(action="list")
+
+# Add tools at runtime
+manage_tools(action="add", package="strands_fun_tools", tool_names="cursor,clipboard")
+
+# Remove tools
+manage_tools(action="remove", tool_names="cursor,clipboard")
+
+# Reload specific tools
+manage_tools(action="reload", tool_names="shell,editor")
+
+# Reload all (restart agent)
+manage_tools(action="reload")
+```
+
+**Discover tools before loading:**
+```python
+# List available tools in a package
+install_tools(action="list_available", package="strands-fun-tools", module="strands_fun_tools")
+```
+
 ---
 
 
 ## MCP Integration
 
+### Expose DevDuck as MCP Server
+
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
@@ -316,6 +389,83 @@ devduck
 
 Restart Claude → DevDuck tools appear automatically.
 
+### Load External MCP Servers
+
+DevDuck can act as an MCP client and load tools from external MCP servers automatically.
+
+**Setup:**
+```bash
+export MCP_SERVERS='{
+  "mcpServers": {
+    "strands": {
+      "command": "uvx",
+      "args": ["strands-agents-mcp-server"]
+    }
+  }
+}'
+devduck
+```
+
+**Supported Transport Types:**
+
+| Transport | Configuration | Example |
+|-----------|--------------|---------|
+| **stdio** | `command`, `args`, `env` | Executables via stdin/stdout |
+| **HTTP** | `url`, `headers` | Remote servers via HTTP |
+| **SSE** | `url` (with `/sse` path) | Server-Sent Events streaming |
+
+**Examples:**
+
+```bash
+# Stdio server
+export MCP_SERVERS='{
+  "mcpServers": {
+    "myserver": {
+      "command": "python",
+      "args": ["server.py"],
+      "env": {"API_KEY": "secret"}
+    }
+  }
+}'
+
+# HTTP server
+export MCP_SERVERS='{
+  "mcpServers": {
+    "remote": {
+      "url": "https://api.example.com/mcp",
+      "headers": {"Authorization": "Bearer token"}
+    }
+  }
+}'
+
+# SSE server
+export MCP_SERVERS='{
+  "mcpServers": {
+    "events": {
+      "url": "https://api.example.com/sse"
+    }
+  }
+}'
+
+# Multiple servers
+export MCP_SERVERS='{
+  "mcpServers": {
+    "strands": {
+      "command": "uvx",
+      "args": ["strands-agents-mcp-server"]
+    },
+    "remote": {
+      "url": "https://api.example.com/mcp"
+    }
+  }
+}'
+
+devduck
+# Tools from all MCP servers automatically available
+```
+
+**Tool Prefixing:** Each MCP server's tools are prefixed with the server name (e.g., `strands_tool_name`)
+
 ---
 
 ## Troubleshooting

{devduck-0.5.4 → devduck-0.7.0}/README.md

@@ -6,6 +6,19 @@
 
 One Python file that adapts to your environment, fixes itself, and expands capabilities at runtime.
 
+Learn more: https://duck.nyc
+
+## 🎬 See It In Action
+
+| Feature | What You'll See | Video |
+|---------|----------------|-------|
+| 🔥 **Hot-Reload** | Agent detects code changes and restarts instantly—no manual intervention needed. Edit your agent code or tools while running, save the file, and watch it reload automatically. | [Watch Demo](https://redduck.dev/videos/hot-reload.mp4) |
+| 🌐 **Web UI** | Clean, modern web interface for chatting with DevDuck. Real-time streaming responses, tool execution visibility, and beautiful markdown rendering. | [Watch Demo](https://redduck.dev/videos/web-ui.mp4) |
+| 🛠️ **Dynamic Tool Creation** | Create a new tool by simply saving a `.py` file in the `./tools/` directory. No restart, no configuration—the agent loads it instantly and starts using it. Pure hot-reload magic. | [Watch Demo](https://redduck.dev/videos/dynamic-tool-creation.mp4) |
+| 🌊 **TCP Streaming Server** | Connect from any client (netcat, custom apps, other agents) via TCP. Real-time streaming responses with parallel tool execution. Multi-protocol access to the same agent. | [Watch Demo](https://redduck.dev/videos/tcp.mp4) |
+| 🔌 **IPC & macOS Tray** | Unix socket-based inter-process communication with native macOS menu bar integration. DevDuck runs in your menu bar with quick actions, status indicators, and seamless IPC streaming via `/tmp/devduck_main.sock`. | ![Demo](docs/mac-os-tray.jpg) |
+| 💬 **Ambient Overlay** | Floating AI input overlay with glassmorphism UI. Real-time IPC streaming from devduck, auto-focus with blinking cursor, and ESC to hide / Enter to send. Perfect for desktop AI interactions. | [Watch Demo](https://redduck.dev/videos/floating-input.mp4) |
+
 ---
 
 ## Install & Run
@@ -54,7 +67,7 @@ devduck
 | 🧠 **Auto-RAG** | Remembers past conversations | "I prefer FastAPI" → later uses FastAPI automatically |
 | 🌊 **Multi-Protocol** | CLI, Python, TCP, WebSocket, MCP, IPC | `devduck "query"` or `nc localhost 9999` |
 | ☁️ **AWS Deploy** | One-command serverless deployment | `agentcore_config(auto_launch=True)` |
-| 🛠️ **30+ Tools** | Shell, GitHub, file editing, math, UI control | `devduck("create GitHub issue")` |
+| 🛠️ **35+ Tools** | Shell, GitHub, file editing, math, UI control | `devduck("create GitHub issue")` |
 | 🎛️ **Flexible Config** | Load only tools you need | `DEVDUCK_TOOLS="strands_tools:shell,editor"` |
 
 ---
@@ -66,7 +79,7 @@ graph TB
     A[User Input] -->|CLI/TCP/WS/MCP/IPC| B[DevDuck Core]
     B -->|Auto RAG| C[Knowledge Base]
     C -.->|Context Retrieval| B
-    B -->|Tool Calls| D[30+ Built-in Tools]
+    B -->|Tool Calls| D[35+ Built-in Tools]
     D --> E[shell/editor/calculator]
     D --> F[GitHub/AgentCore]
     D --> G[TCP/WebSocket/MCP/IPC]
@@ -118,7 +131,7 @@ devduck("refactor my code to use async/await")
 
 | Provider | Setup | When to Use |
 |----------|-------|-------------|
-| **Bedrock** (auto-detected) | [Get API key](https://console.aws.amazon.com/bedrock) → `export AWS_BEARER_TOKEN_BEDROCK=...` | Production (auto-selected if credentials found) |
+| **Bedrock** (auto-detected) | [Get API key](https://console.aws.amazon.com/bedrock) → `export AWS_BEARER_TOKEN_BEDROCK=...` | Auto-selected if credentials found |
 | **MLX** (macOS auto-detected) | Auto-detected on Apple Silicon | Local, optimized for M-series Macs |
 | **Ollama** (fallback) | `ollama pull qwen3:1.7b` | Local, free, private (used if Bedrock/MLX unavailable) |
 | **Anthropic** | `export ANTHROPIC_API_KEY=...` | Claude API direct access |
@@ -140,8 +153,8 @@ devduck
 | **Dev** | `shell`, `editor`, `file_read`, `calculator` | Code, test, debug |
 | **GitHub** | `use_github`, `create_subagent` | Issues, PRs, CI/CD automation |
 | **Network** | `tcp`, `websocket`, `mcp_server`, `ipc` | Serve agents over protocols |
-| **AWS** | `agentcore_config`, `agentcore_invoke`, `agentcore_logs` | Deploy to serverless |
-| **AI** | `use_agent`, `retrieve`, `store_in_kb` | Multi-agent, memory |
+| **AWS** | `agentcore_config`, `agentcore_invoke`, `agentcore_logs`, `agentcore_agents` | Deploy to serverless |
+| **AI** | `use_agent`, `retrieve`, `store_in_kb`, `state_manager` | Multi-agent, memory, state |
 | **UI** (macOS) | `tray`, `ambient`, `cursor`, `clipboard` | Desktop automation |
 
 <details>
@@ -157,6 +170,7 @@ devduck
 - `create_subagent` - Spawn sub-agents via GitHub Actions
 - `store_in_kb` - Store content in Bedrock Knowledge Base
 - `system_prompt` - Manage agent system prompt
+- `state_manager` - Agent state management with time-travel capabilities
 - `tray` - System tray app control (macOS)
 - `ambient` - Ambient AI input overlay (macOS)
 
@@ -178,6 +192,12 @@ devduck
 - `environment` - Environment variable management
 - `mcp_client` - Connect to external MCP servers
 - `retrieve` - Bedrock Knowledge Base retrieval
+- `scraper` - HTML/XML parsing with BeautifulSoup4
+- `fetch_github_tool` - Fetch and load tools from GitHub
+- `gist` - Comprehensive GitHub Gist management
+- `add_comment` - Add comments to GitHub issues/PRs
+- `list_issues` - List GitHub issues
+- `list_pull_requests` - List GitHub pull requests
 
 ### strands-fun-tools (macOS)
 - `listen` - Background speech transcription with Whisper
@@ -239,22 +259,75 @@ No restart. No configuration. Just works.
 |----------|---------|---------|
 | `MODEL_PROVIDER` | Auto-detect | `bedrock`, `anthropic`, `github`, `mlx`, `ollama` |
 | `STRANDS_MODEL_ID` | Auto | Model name (e.g., `qwen3:1.7b`, `claude-sonnet-4`) |
-| `DEVDUCK_TOOLS` | All | `pkg:tool1,tool2:pkg2:tool3` |
+| `DEVDUCK_TOOLS` | 37 default tools | `package:tool1,tool2:package2:tool3` format |
+| `DEVDUCK_LOAD_TOOLS_FROM_DIR` | `false` | `true`/`false` - Auto-load tools from `./tools/` directory |
 | `DEVDUCK_KNOWLEDGE_BASE_ID` | - | Bedrock KB ID for auto-RAG |
 | `DEVDUCK_TCP_PORT` | `9999` | TCP server port |
 | `DEVDUCK_ENABLE_TCP` | `true` | Enable/disable TCP |
 
-**Minimal config (shell + editor only):**
+### Tool Configuration Format
+
+**Format:** `package:tool1,tool2:package2:tool3`
+
+**Directory Auto-Loading:**
+
+By default, DevDuck **does not** automatically load tools from the `./tools/` directory. This gives you explicit control over which tools are loaded. To enable automatic loading of tools from `./tools/`, set:
+
+```bash
+export DEVDUCK_LOAD_TOOLS_FROM_DIR=true
+devduck
+```
+
+When enabled, any `.py` file in `./tools/` with a `@tool` decorator will be loaded automatically. When disabled (default), you control tool loading via `DEVDUCK_TOOLS` or runtime `manage_tools()` calls.
+
+**Examples:**
 ```bash
+# Minimal (shell + editor only)
 export DEVDUCK_TOOLS="strands_tools:shell,editor"
+
+# Dev tools only
+export DEVDUCK_TOOLS="strands_tools:shell,editor,file_read,file_write,calculator"
+
+# Full DevDuck + Strands (no fun tools)
+export DEVDUCK_TOOLS="devduck.tools:tcp,websocket,mcp_server,use_github:strands_tools:shell,editor,file_read"
+
+# Custom package
+export DEVDUCK_TOOLS="my_tools:custom_tool,another_tool:strands_tools:shell"
+
 devduck
 ```
 
+**Runtime tool management:**
+```python
+# List loaded tools
+manage_tools(action="list")
+
+# Add tools at runtime
+manage_tools(action="add", package="strands_fun_tools", tool_names="cursor,clipboard")
+
+# Remove tools
+manage_tools(action="remove", tool_names="cursor,clipboard")
+
+# Reload specific tools
+manage_tools(action="reload", tool_names="shell,editor")
+
+# Reload all (restart agent)
+manage_tools(action="reload")
+```
+
+**Discover tools before loading:**
+```python
+# List available tools in a package
+install_tools(action="list_available", package="strands-fun-tools", module="strands_fun_tools")
+```
+
 ---
 
 
 ## MCP Integration
 
+### Expose DevDuck as MCP Server
+
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
@@ -269,6 +342,83 @@ devduck
 
 Restart Claude → DevDuck tools appear automatically.
 
+### Load External MCP Servers
+
+DevDuck can act as an MCP client and load tools from external MCP servers automatically.
+
+**Setup:**
+```bash
+export MCP_SERVERS='{
+  "mcpServers": {
+    "strands": {
+      "command": "uvx",
+      "args": ["strands-agents-mcp-server"]
+    }
+  }
+}'
+devduck
+```
+
+**Supported Transport Types:**
+
+| Transport | Configuration | Example |
+|-----------|--------------|---------|
+| **stdio** | `command`, `args`, `env` | Executables via stdin/stdout |
+| **HTTP** | `url`, `headers` | Remote servers via HTTP |
+| **SSE** | `url` (with `/sse` path) | Server-Sent Events streaming |
+
+**Examples:**
+
+```bash
+# Stdio server
+export MCP_SERVERS='{
+  "mcpServers": {
+    "myserver": {
+      "command": "python",
+      "args": ["server.py"],
+      "env": {"API_KEY": "secret"}
+    }
+  }
+}'
+
+# HTTP server
+export MCP_SERVERS='{
+  "mcpServers": {
+    "remote": {
+      "url": "https://api.example.com/mcp",
+      "headers": {"Authorization": "Bearer token"}
+    }
+  }
+}'
+
+# SSE server
+export MCP_SERVERS='{
+  "mcpServers": {
+    "events": {
+      "url": "https://api.example.com/sse"
+    }
+  }
+}'
+
+# Multiple servers
+export MCP_SERVERS='{
+  "mcpServers": {
+    "strands": {
+      "command": "uvx",
+      "args": ["strands-agents-mcp-server"]
+    },
+    "remote": {
+      "url": "https://api.example.com/mcp"
+    }
+  }
+}'
+
+devduck
+# Tools from all MCP servers automatically available
+```
+
+**Tool Prefixing:** Each MCP server's tools are prefixed with the server name (e.g., `strands_tool_name`)
+
 ---
 
 ## Troubleshooting

{devduck-0.5.4 → devduck-0.7.0}/action.yml

@@ -130,7 +130,7 @@ runs:
     - name: Install DevDuck
       shell: bash
       run: |
-        uv pip install --system -r requirements.txt --quiet
+        uv pip install devduck --system --quiet
 
     - name: Configure Git
       shell: bash