Metadata-Version: 2.4
Name: plumber-agent
Version: 1.1.1
Summary: Local DCC Agent for Plumber Workflow Editor - Enables Maya, Blender, and Houdini operations
Home-page: https://app.plumber.damnltd.com
Author: Damn Ltd
Author-email: Damn Ltd <info@damnltd.com>
License: MIT
Project-URL: Homepage, https://app.plumber.damnltd.com
Project-URL: Documentation, https://app.plumber.damnltd.com/docs
Project-URL: Repository, https://github.com/damnvfx/plumber-editor
Project-URL: Bug Tracker, https://github.com/damnvfx/plumber-editor/issues
Keywords: workflow,dcc,maya,blender,houdini,automation,vfx
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.104.1
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: websockets>=12.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: psutil>=5.9.6
Requires-Dist: watchdog>=3.0.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: click>=8.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: windows
Requires-Dist: pywin32>=305; sys_platform == "win32" and extra == "windows"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# Plumber Agent

Local DCC agent for [Plumber Workflow Editor](https://app.plumber.damnltd.com).

Keeps Maya, Blender, Houdini, and Nuke running as persistent background servers so Plumber workflows send operations in ~100ms instead of cold-starting the DCC every time (25–200x faster).

---

## Requirements

- Python 3.8, 3.9, 3.10, 3.11, or 3.12
- pip
- At least one DCC application:
  - **Maya** 2022–2026 (requires `mayapy` on PATH, or auto-discovered)
  - **Blender** 4.0–5.0+ (auto-discovered from standard install locations)
  - **Houdini** 20.0+ (requires `hython` on PATH, or auto-discovered)
  - **Nuke** 13–15 (requires `nuke` on PATH, or auto-discovered)

---

## Install

```bash
pip install plumber-agent
```

Upgrade:

```bash
pip install --upgrade plumber-agent
```

---

## Run

Start the agent in the foreground (useful for first-time setup and debugging):

```bash
plumber-agent
```

The agent starts on `http://127.0.0.1:8001`, connects to the Plumber cloud backend, and auto-discovers your installed DCC applications. A status line is printed for each DCC found:

```
[OK] Maya 2026 detected at /usr/autodesk/maya2026/bin/mayapy
[OK] Blender 4.4 detected at /Applications/Blender.app/Contents/MacOS/Blender
[--] Houdini not found
```

### Windows Service (recommended for beta testers)

Run the agent as a background Windows Service that starts automatically with Windows:

```cmd
# Run as Administrator
plumber-agent install-service
plumber-agent start
plumber-agent status
```

Service management:

```cmd
plumber-agent stop
plumber-agent restart
plumber-agent logs          # tail the log file
plumber-agent uninstall-service
```

### macOS / Linux background process

```bash
plumber-agent &             # run in background
plumber-agent logs          # check logs
```

---

## Custom Nodes

Place Python files in `~/plumber/custom_nodes/` and they appear automatically in the editor's node menu. No restart required — the agent hot-reloads when files change.

```
~/plumber/
  custom_nodes/
    my_studio_node.py    ← your nodes go here
    vfx_pipeline.py
```

See the [SDK documentation](../deployment-package/backend/plumber_sdk/README.md) for the full API reference.

Minimal example (`~/plumber/custom_nodes/hello.py`):

```python
from plumber_sdk import Node, Property, Output, ExecutionContext

class HelloNode(Node):
    _description = "Greet the world"
    _category = "Examples"

    name: str = Property(default="World", label="Name")
    greeting: str = Output(type=str, label="Greeting")

    def execute(self, context: ExecutionContext) -> dict:
        return {"greeting": f"Hello, {self.name}!"}
```

---

## Diagnostics

```bash
plumber-agent version       # print installed version
plumber-agent discover      # list detected DCC applications
plumber-agent status        # show running service status and active sessions
plumber-agent logs          # stream the log file
```

Log file location:
- **Windows**: `%LOCALAPPDATA%\plumber-agent\plumber_agent.log`
- **macOS / Linux**: `~/.plumber-agent/plumber_agent.log`

---

## Workspace Variables

Workflows can reference portable paths using `$VAR` placeholders:

```bash
plumber-agent set-var PROJECTS /mnt/studio/projects
plumber-agent set-var RENDERS  /mnt/studio/renders
plumber-agent list-vars
```

In a workflow, use `$PROJECTS/my_shot/scene.ma` and the agent expands it to the full path on each machine. This lets one workflow JSON run correctly across different artists' workstations.

---

## Troubleshooting

### Agent not connecting to the editor
- Confirm `plumber-agent status` shows `running`.
- Check firewall rules — the agent needs outbound HTTPS to `plumber-production-446f.up.railway.app` (port 443) and WebSocket on the same host.

### DCC not discovered
- **Maya**: ensure `mayapy` is on your `PATH`, or set `MAYA_LOCATION`.
- **Blender**: install to the default location for your OS; the agent scans standard paths.
- **Houdini**: ensure `hython` is on your `PATH` (sourcing `houdini_setup` does this).
- **Nuke**: ensure `nuke` is on your `PATH`.
- Run `plumber-agent discover` to see exactly which paths were scanned.

### Custom node not appearing
- Confirm the file is in `~/plumber/custom_nodes/` with a `.py` extension.
- Run `plumber-agent logs` and look for import errors — a syntax error in your file prevents all nodes in that file from loading.
- Make sure the class inherits from `Node` or one of the DCC base classes.

### DCC operation is slow or times out
- The first operation in a workflow warms up the persistent server (~1–10 s depending on DCC). Subsequent operations in the same session should be ~100 ms.
- Increase `timeout` in `_run_raw_script()` for heavy renders or exports.
