Metadata-Version: 2.4
Name: devduck
Version: 0.4.1
Summary: 🦆 Extreme minimalist self-adapting AI agent - one file, self-healing, runtime dependencies
Author-email: duck <hey@devduck.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cagataycali/devduck
Project-URL: Repository, https://github.com/cagataycali/devduck.git
Project-URL: Documentation, https://github.com/cagataycali/devduck#readme
Project-URL: Bug Tracker, https://github.com/cagataycali/devduck/issues
Keywords: ai,agent,minimalist,self-healing,ollama,strands-agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: strands-agents
Requires-Dist: prompt_toolkit
Requires-Dist: strands-agents[ollama]
Requires-Dist: strands-agents-tools
Requires-Dist: strands-agentcore-tools
Requires-Dist: beautifulsoup4
Requires-Dist: colorama
Requires-Dist: websockets
Requires-Dist: strands-mcp-server
Provides-Extra: all
Requires-Dist: strands-agents[openai]; extra == "all"
Requires-Dist: strands-agents[anthropic]; extra == "all"
Requires-Dist: strands-fun-tools[audio]; extra == "all"
Requires-Dist: strands-fun-tools[vision]; extra == "all"
Requires-Dist: strands-fun-tools[all]; extra == "all"
Dynamic: license-file

# 🦆 DevDuck

**Self-healing agent. One file. Zero config.**

Minimalist AI that adapts to your environment and fixes itself when things break.

## Install

**Homebrew (macOS/Linux):**
```bash
brew tap cagataycali/devduck
brew install devduck
```

**pipx (all platforms):**
```bash
pipx install "devduck[all]"  # Full install (recommended)
```

**uvx (instant run, no install):**
```bash
uvx devduck "hello world"
```

Requires: Python 3.10+, Ollama (or set `MODEL_PROVIDER`)

## Quick Start

```bash
devduck                      # Interactive mode (auto-starts servers)
devduck "analyze this code"  # CLI mode
```

```python
import devduck
devduck("calculate 2+2")  # Python API
```

## Core Features

- **🔧 Self-healing** - Auto-fixes dependencies, models, errors
- **🔥 Hot-reload** - Save `.py` files in `./tools/`, use instantly (no restart)
- **🧠 RAG memory** - Set `STRANDS_KNOWLEDGE_BASE_ID` for automatic context retrieval/storage
- **🌍 Multi-protocol** - TCP (9999), WebSocket (8080), MCP (8000), CLI, Python
- **📚 19+ tools** - shell, editor, calculator, python, GitHub, subagents, and more
- **🎯 Adaptive** - Auto-selects model by OS (macOS: 1.7b, Linux: 30b)

## Auto-Started Servers

When you run `devduck`, 3 servers start automatically:

| Server | Endpoint | Usage |
|--------|----------|-------|
| 🌐 **Web UI** | [cagataycali.github.io/devduck](http://cagataycali.github.io/devduck) | Browser interface |
| 🔌 **TCP** | `localhost:9999` | `nc localhost 9999` |
| 🌊 **WebSocket** | `ws://localhost:8080` | Structured JSON messages |
| 🔗 **MCP** | `http://localhost:8000/mcp` | Model Context Protocol |

**Customize ports:**
```bash
devduck --tcp-port 9000 --ws-port 8001 --mcp-port 3000
devduck --no-tcp --no-ws  # Disable specific servers
```

## Connect Options

### MCP Client (Claude Desktop)

**Simple stdio mode (recommended):**
```json
{
  "mcpServers": {
    "devduck": {
      "command": "uvx",
      "args": ["devduck", "--mcp"]
    }
  }
}
```

**Proxy mode (if devduck already running):**
```json
{
  "mcpServers": {
    "devduck": {
      "command": "uvx",
      "args": ["strands-mcp-server", "--upstream-url", "http://localhost:8000/mcp/"]
    }
  }
}
```

### Terminal (TCP)
```bash
nc localhost 9999
> analyze logs
```

### Shell Prefix
```bash
devduck
🦆 ! git status  # Run shell commands with !
```

## Hot-Reload Tool Creation

Create tools instantly—no restart needed:

```python
# ./tools/tip_calc.py
from strands import tool

@tool
def calculate_tip(amount: float, percent: float = 15.0) -> str:
    """Calculate restaurant tip."""
    tip = amount * (percent / 100)
    return f"Tip: ${tip:.2f} | Total: ${amount + tip:.2f}"
```

Save → Available instantly → Use: `devduck "calculate tip for $42"`

## Built-in Tools (19+)

| Category | Tools |
|----------|-------|
| **Development** | shell, editor, python_repl, load_tool, environment |
| **GitHub** | use_github, create_subagent, gist, add_comment, list_issues |
| **Network** | tcp, websocket, mcp_server, mcp_client, http_request |
| **AI** | use_agent, install_tools, retrieve, store_in_kb |
| **Utilities** | calculator, image_reader, scraper, system_prompt, view_logs |

## Multi-Model Support

Switch models via environment variables:

```bash
# Bedrock (Claude)
export MODEL_PROVIDER="bedrock"
export STRANDS_MODEL_ID="us.anthropic.claude-sonnet-4-5-20250929-v1:0"
export STRANDS_MAX_TOKENS="64000"

# Anthropic API
export MODEL_PROVIDER="anthropic"
export STRANDS_MODEL_ID="claude-sonnet-4-20250514"

# Ollama (default)
export MODEL_PROVIDER="ollama"
export OLLAMA_HOST="http://localhost:11434"
```

## Knowledge Base (RAG)

Enable automatic memory across sessions:

```bash
export STRANDS_KNOWLEDGE_BASE_ID="your-kb-id"
devduck  # Auto-retrieves context before queries, stores after responses
```

Works with AWS Bedrock Knowledge Bases.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MODEL_PROVIDER` | `ollama` | Model provider (bedrock, anthropic, ollama) |
| `STRANDS_KNOWLEDGE_BASE_ID` | - | Enable auto-RAG with KB ID |
| `DEVDUCK_TCP_PORT` | `9999` | TCP server port |
| `DEVDUCK_WS_PORT` | `8080` | WebSocket port |
| `DEVDUCK_MCP_PORT` | `8000` | MCP server port |
| `DEVDUCK_ENABLE_TCP` | `true` | Enable TCP server |
| `DEVDUCK_ENABLE_WS` | `true` | Enable WebSocket |
| `DEVDUCK_ENABLE_MCP` | `true` | Enable MCP server |
| `DEVDUCK_LOG_LINE_COUNT` | `50` | Log lines in context |
| `SYSTEM_PROMPT` | - | Custom system prompt |

## Dynamic Tool Loading

Load tools from any Python package at runtime:

```python
devduck
🦆 install_tools(action="install_and_load", 
              package="strands-fun-tools", 
              module="strands_fun_tools")
```

No restart required—tools available immediately.

## System Prompt Management

Modify agent behavior dynamically:

```bash
devduck
🦆 system_prompt(action="update", prompt="You are a senior Python expert.")
🦆 system_prompt(action="view")  # See current prompt
```

## Logs

```bash
devduck
🦆 view_logs(action="view", lines=100)
🦆 view_logs(action="search", pattern="error")
🦆 view_logs(action="stats")
```

Log location: `/tmp/devduck/logs/devduck.log`

## GitHub Actions

Run DevDuck in CI/CD:

```yaml
name: AI Assistant
on: [issues, pull_request]

jobs:
  assistant:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write
    steps:
      - uses: cagataycali/devduck@main
        with:
          task: "Help with this issue or PR"
          provider: "github"
          model: "openai/o4-mini"
```

---

**One file. 19+ tools. Self-healing. Hot-reload. RAG memory.**

*Built with [Strands Agents SDK](https://github.com/strands-agents/sdk-python)*
