griptape-nodes 0.37.1__tar.gz → 0.38.1__tar.gz

{griptape_nodes-0.37.1 → griptape_nodes-0.38.1}/.github/workflows/claude.yml

@@ -34,4 +34,11 @@ jobs:
         uses: anthropics/claude-code-action@beta
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-
+          # https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude
+          allowed_tools: |
+            WebFetch
+            WebSearch
+            Bash
+            Edit
+            Write
+            Replace

{griptape_nodes-0.37.1 → griptape_nodes-0.38.1}/.github/workflows/publish.yml

@@ -23,8 +23,52 @@ jobs:
       - name: uv Publish
         run: uv publish --token ${{ secrets.PYPI_TOKEN }}
 
-  push_to_registries:
-    name: Push Docker images to multiple registries
+  push_cpu_image:
+    name: Push CPU Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            griptape/griptape-nodes
+            ghcr.io/${{ github.repository }}
+
+      - name: Build and push CPU image
+        id: push_cpu
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          build-args: |
+            BUILD_TYPE=cpu
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  push_gpu_image:
+    name: Push GPU Docker image
     runs-on: ubuntu-latest
     permissions:
       packages: write
@@ -82,17 +126,6 @@ jobs:
 
           echo "tags=$GPU_TAGS" >> $GITHUB_OUTPUT
 
-      - name: Build and push CPU image
-        id: push_cpu
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: true
-          build-args: |
-            BUILD_TYPE=cpu
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-
       - name: Build and push GPU image
         id: push_gpu
         uses: docker/build-push-action@v6

{griptape_nodes-0.37.1 → griptape_nodes-0.38.1}/.gitignore

@@ -187,6 +187,9 @@ GriptapeNodes/
 # Generated Output
 request_payload_schemas.json
 
+# Profile Output
+profiles/
+
 # JetBrains
 .idea/
 

griptape_nodes-0.38.1/.vscode/tasks.json

@@ -0,0 +1,321 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Profile Griptape Nodes App: CPU profiling - uses sudo (may be required for some systems such as Mac)",
+            "type": "shell",
+            "command": "sudo",
+            "args": [
+                ".venv/bin/austin",
+                "-i", "100us",
+                "-C",
+                "-b",
+                "-o", "profiles/profile_griptape_nodes_cpu.mojo",
+                ".venv/bin/python",
+                "-m", "src.griptape_nodes.__init__",
+                "--no-update"
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Profile Griptape Nodes App: Memory profiling - uses sudo (may be required for some systems such as Mac)",
+            "type": "shell",
+            "command": "sudo",
+            "args": [
+                ".venv/bin/austin",
+                "-i", "100us",
+                "-m",
+                "-C",
+                "-b",
+                "-o", "profiles/profile_griptape_nodes_memory.mojo",
+                ".venv/bin/python",
+                "-m", "src.griptape_nodes.__init__",
+                "--no-update"
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Profile Griptape Nodes App: CPU profiling - does NOT use sudo",
+            "type": "shell",
+            "command": ".venv/bin/austin",
+            "args": [
+                "-i", "100us",
+                "-C",
+                "-b",
+                "-o", "profiles/profile_griptape_nodes_cpu.mojo",
+                ".venv/bin/python",
+                "-m", "src.griptape_nodes.__init__",
+                "--no-update"
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Profile Griptape Nodes App: Memory profiling - does NOT use sudo",
+            "type": "shell",
+            "command": ".venv/bin/austin",
+            "args": [
+                "-i", "100us",
+                "-m",
+                "-C",
+                "-b",
+                "-o", "profiles/profile_griptape_nodes_memory.mojo",
+                ".venv/bin/python",
+                "-m", "src.griptape_nodes.__init__",
+                "--no-update"
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Find Griptape Nodes Process ID",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "pgrep -f \"debugpy.*--connect.*src\\.griptape_nodes\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Attach to Griptape Nodes App: CPU profiling - uses sudo (may be required for some systems such as Mac)",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "sudo .venv/bin/austin -i 10us -C -b -p ${input:griptapeNodesPid} -o \"profiles/profile_attach_cpu_$(date +%Y%m%d_%H%M%S).mojo\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": true,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Attach to Griptape Nodes App: Memory profiling - uses sudo (may be required for some systems such as Mac)",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "sudo .venv/bin/austin -i 10us -m -C -b -p ${input:griptapeNodesPid} -o \"profiles/profile_attach_memory_$(date +%Y%m%d_%H%M%S).mojo\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": true,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Attach to Griptape Nodes App: CPU profiling - does NOT use sudo",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                ".venv/bin/austin -i 10us -C -b -p ${input:griptapeNodesPid} -o \"profiles/profile_attach_cpu_$(date +%Y%m%d_%H%M%S).mojo\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": true,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Attach to Griptape Nodes App: Memory profiling - does NOT use sudo",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                ".venv/bin/austin -i 10us -m -C -b -p ${input:griptapeNodesPid} -o \"profiles/profile_attach_memory_$(date +%Y%m%d_%H%M%S).mojo\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": true,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Stop/Detach CPU Profiling",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "pkill -f \"austin.*profile.*cpu.mojo\" || echo \"No CPU profiling process found\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Stop/Detach Memory Profiling",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "pkill -f \"austin.*profile.*memory.mojo\" || echo \"No memory profiling process found\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Stop/Detach All Profiling",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "pkill -f \"austin.*profile.*\\.mojo\" && echo \"Stopped all profiling processes\" || echo \"No profiling processes found\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Stop/Detach CPU Profiling - uses sudo",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "sudo pkill -f \"austin.*profile.*cpu.mojo\" && echo \"Stopped CPU profiling\" || echo \"No CPU profiling process found\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Stop/Detach Memory Profiling - uses sudo",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "sudo pkill -f \"austin.*profile.*memory.mojo\" && echo \"Stopped memory profiling\" || echo \"No memory profiling process found\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Stop/Detach All Profiling - uses sudo",
+            "type": "shell",
+            "command": "bash",
+            "args": [
+                "-c",
+                "sudo pkill -f \"austin.*profile.*\\.mojo\" && echo \"Stopped all profiling processes\" || echo \"No profiling processes found\""
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": []
+        }
+    ],
+    "inputs": [
+        {
+            "id": "griptapeNodesPid",
+            "description": "Enter the Griptape Nodes PID (use 'Find Griptape Nodes Process ID' task first):",
+            "type": "promptString"
+        }
+    ]
+}

griptape_nodes-0.38.1/CLAUDE.md

@@ -0,0 +1,185 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+All development commands use the Makefile:
+
+**Development workflow:**
+
+```bash
+make install          # Install all dependencies (core + dev + test + docs)
+make run               # Run the engine locally (--no-update flag)
+make run/watch         # Run engine in watch mode for development
+```
+
+**Testing:**
+
+```bash
+make test              # Run all tests (unit, integration, workflow)
+make test/unit         # Run unit tests only
+make test/integration  # Run integration tests only
+make test/workflows    # Run workflow tests only
+```
+
+**Code quality:**
+
+```bash
+make check             # Run all checks (format, lint, types, spell)
+make lint              # Run ruff linting with auto-fix
+make format            # Format code with ruff + mdformat
+make fix               # Format + unsafe ruff fixes (excludes libraries/tests)
+```
+
+**IMPORTANT - AI Agent Linting Workflow:**
+
+Claude Code must follow this pattern to prevent lint debt accumulation:
+
+1. **After completing a logical group of changes** (e.g., implementing a feature, fixing a bug)
+1. **Run lint check**: `make check`
+1. **Fix any issues found** before moving to next major task. Ask the user if they are comfortable running `make fix` (which will make all changes for them) or if they want to step through them one by one.
+1. **Always check before completing work sessions**
+
+**Goal: Zero lint errors, always.** Never let lint issues accumulate for "later cleanup."
+
+```bash
+# Check specific files/directories:
+uv run ruff check path/to/file.py
+uv run ruff check libraries/griptape_nodes_neo4j_library/
+
+# Auto-fix simple issues:
+uv run ruff check --fix path/to/file.py
+
+# Quick status check:
+uv run ruff check --statistics
+```
+
+**Documentation:**
+
+```bash
+make docs              # Build documentation with mkdocs
+make docs/serve        # Serve docs locally for development
+```
+
+**Version management:**
+
+```bash
+make version/patch     # Bump patch version
+make version/minor     # Bump minor version 
+make version/major     # Bump major version
+make version/publish   # Create and push git tags
+```
+
+Single test execution: `uv run pytest tests/path/to/test.py::test_function`
+
+## Architecture Overview
+
+**Core Engine Architecture:**
+
+- `src/griptape_nodes/` - Main engine package
+- `src/griptape_nodes/retained_mode/` - Core retained mode API system
+- `src/griptape_nodes/app/` - FastAPI application and WebSocket handling
+- `src/griptape_nodes/node_library/` - Node library registration system
+
+**Node Library System:**
+
+- Libraries are defined by JSON schema files (`griptape_nodes_library.json`)
+- Each library contains node definitions with metadata, categories, and file paths
+- Libraries are registered via `LibraryRegistry` singleton
+- Node creation flows through `LibraryRegistry.create_node()` -> `Library.create_node()`
+- Libraries can define dependencies, settings, and workflows
+
+**Event-Driven Communication:**
+
+- All operations flow through event requests/responses in `retained_mode/events/`
+- Event types: `node_events`, `flow_events`, `execution_events`, `config_events`, etc.
+- Events are handled by `GriptapeNodes.handle_request()` singleton
+- Real-time communication via WebSockets through `NodesApiSocketManager`
+
+**Execution Model:**
+
+- Flows contain multiple nodes with parameter connections
+- Execution state managed by `FlowManager` and `NodeManager`
+- Supports step-by-step debugging and flow control
+- Node resolution and validation before execution
+
+**Storage Architecture:**
+
+- Configurable storage backends: local filesystem or Griptape Cloud
+- Static file serving via FastAPI for media assets
+- Workspace directory contains flows, configurations, and generated assets
+
+**Retained Mode API:**
+The `RetainedMode` class in `retained_mode/retained_mode.py` provides the scriptable Python interface for:
+
+- Flow management: `create_flow()`, `run_flow()`, `single_step()`
+- Node operations: `create_node()`, `set_value()`, `get_value()`, `connect()`
+- Library introspection: `get_available_libraries()`, `get_node_types_in_library()`
+- Configuration: `get_config_value()`, `set_config_value()`
+
+**Key Patterns:**
+
+- All managers are singletons accessed via `GriptapeNodes.ManagerName()`
+- Node parameters support indexed access (e.g., `node.param[0][1]`)
+- Execution chains can be created with `exec_chain()` helper
+- Metadata flows from library definitions to runtime node instances
+
+## Node Development
+
+**Creating Custom Nodes:**
+
+1. Extend `BaseNode` from `exe_types/node_types.py`
+1. Define in library JSON with category, metadata, and file path
+1. Register library through bootstrap system
+1. Nodes automatically inherit parameter system and execution framework
+
+**Library Registration:**
+
+- Default library: `libraries/griptape_nodes_library/`
+- Advanced library: `libraries/griptape_nodes_advanced_media_library/`
+- Custom libraries registered via config: `app_events.on_app_initialization_complete.libraries_to_register`
+
+**Bootstrap System:**
+
+- `bootstrap/register_libraries_script.py` handles library discovery and registration
+- Workflow runners in `bootstrap/workflow_runners/` for different execution contexts
+- Structure defined in `bootstrap/structure_config.yaml`
+
+## Profiling (Optional)
+
+**Installation (for advanced users):**
+
+```bash
+uv add griptape-nodes[profiling]  # Add profiling extra to existing project
+# OR
+uv sync --extra profiling         # Sync with profiling extra in development
+```
+
+**VS Code Tasks Available:**
+
+- **Find Griptape Nodes Process ID** - Finds running Griptape process PID
+- **Attach to Griptape Nodes App: CPU/Memory profiling** - Start profiling (4 variants: with/without sudo, CPU/memory)
+- **Stop/Detach Profiling** - Stop profiling sessions (6 variants: with/without sudo, CPU/memory/all)
+
+**Profiling Workflow:**
+
+1. Start Griptape Nodes in debug mode
+1. Run "Find Griptape Nodes Process ID" task to get PID
+1. Run attach profiling task (use sudo variants on Mac if needed)
+1. Exercise your application
+1. Run stop/detach task to save profile
+1. Profile files saved to `profiles/` with timestamps: `profile_attach_cpu_YYYYMMDD_HHMMSS.mojo`
+
+**Key Points:**
+
+- Austin overwrites existing files - timestamped filenames prevent data loss
+- Use detach tasks rather than killing main program for complete data
+- Sudo variants required on some systems (especially Mac) for process attachment
+
+# important-instruction-reminders
+
+Do what has been asked; nothing more, nothing less.
+NEVER create files unless they're absolutely necessary for achieving your goal.
+ALWAYS prefer editing an existing file to creating a new one.
+NEVER proactively create documentation files (\*.md) or README files. Only create documentation files if explicitly requested by the User.

{griptape_nodes-0.37.1 → griptape_nodes-0.38.1}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: griptape-nodes
-Version: 0.37.1
+Version: 0.38.1
 Summary: Add your description here
 License-File: LICENSE
 Requires-Python: ~=3.12
 Requires-Dist: fastapi>=0.115.12
 Requires-Dist: griptape[drivers-prompt-amazon-bedrock,drivers-prompt-anthropic,drivers-prompt-cohere,drivers-prompt-ollama,drivers-web-scraper-trafilatura,drivers-web-search-duckduckgo,drivers-web-search-exa,loaders-image]>=1.7.1
 Requires-Dist: httpx<1.0.0,>=0.28.0
+Requires-Dist: imageio-ffmpeg>=0.6.0
 Requires-Dist: json-repair>=0.46.1
 Requires-Dist: packaging>=25.0
 Requires-Dist: pydantic>=2.10.6
@@ -17,6 +18,8 @@ Requires-Dist: uv>=0.6.16
 Requires-Dist: uvicorn>=0.34.2
 Requires-Dist: websockets<16.0.0,>=15.0.1
 Requires-Dist: xdg-base-dirs>=6.0.2
+Provides-Extra: profiling
+Requires-Dist: austin-dist>=3.7.0; extra == 'profiling'
 Description-Content-Type: text/markdown
 
 # Griptape Nodes

{griptape_nodes-0.37.1 → griptape_nodes-0.38.1}/docs/command_line_interface.md

@@ -69,17 +69,17 @@ Subcommands:
 - `uninstall` - Uninstall the CLI, removing configuration and data directories
 - `version` - Display the current version of the CLI
 
-### `assets`
+### `libraries`
 
-Manage local assets (libraries, workflows, etc.).
+Manage local libraries.
 
 ```
-griptape-nodes assets SUBCOMMAND
+griptape-nodes libraries SUBCOMMAND
 ```
 
 Subcommands:
 
-- `update` - Update bundled assets to the latest version
+- `sync` - Sync libraries with your current engine version
 
 ## Configuration
 

{griptape_nodes-0.37.1 → griptape_nodes-0.38.1}/docs/faq.md

@@ -87,14 +87,14 @@ If you would like to _manually_ update, you can always use either of these comma
 
 ```bash
 griptape-nodes self update
-griptape-nodes assets update
+griptape-nodes libraries sync
 ```
 
 or
 
 ```bash
 gtn self update
-gtn assets update
+gtn libraries sync
 ```
 
 ## I'm seeing `failed to locate pyvenv.cfg: The system cannot find the file specified.` - What should I do?

griptape_nodes-0.38.1/docs/mkdocs.yaml

@@ -0,0 +1,16 @@
+nav:
+  - Home: index.md
+  - Nodes:
+    - Lists:
+      - Add To List: nodes/lists/add_to_list.md
+      - Combine Lists: nodes/lists/combine_lists.md
+      - Create List: nodes/lists/create_list.md
+      - Display List: nodes/lists/display_list.md
+      - Get Index Of Item: nodes/lists/get_index_of_item.md
+      - Get From List: nodes/lists/get_from_list.md
+      - Get List Contains Item: nodes/lists/get_list_contains_item.md
+      - Get List Is Empty: nodes/lists/get_list_is_empty.md
+      - Get List Length: nodes/lists/get_list_length.md
+      - Remove From List: nodes/lists/remove_from_list.md
+      - Replace In List: nodes/lists/replace_in_list.md
+      - Split List: nodes/lists/split_list.md