# NodeCraft
A modular framework for building composable AI workflows with a "building blocks" design philosophy.
## Overview
NodeCraft provides a pluggable Node and Scenario system that allows you to discover, create, and compose reusable AI workflow components. Think of it as building blocks for AI-powered code analysis and automation.
## Key Features
- Node-based architecture with automatic discovery
- YAML-based scenario definition
- Template-based Node and Scenario creation
- Configuration file system for team collaboration
- Dynamic CLI generation from scenarios
- Built-in scenarios for common tasks
## Installation
```bash
# Install from PyPI
pip install NodeCraft
# Set up API key
export ANTHROPIC_API_KEY="your-api-key-here"
```
After installation, the `nodecraft` command is available globally.
## Quick Start
### Discover Available Nodes and Scenarios
```bash
# List all available nodes
nodecraft nodes list
# Show node details
nodecraft nodes show @common/get_files
# List all scenarios
nodecraft scenarios list
# Show scenario details
nodecraft scenarios show simple_rag
```
### Create New Nodes and Scenarios
```bash
# Create a function-based node
nodecraft nodes create --name my_analyzer
# Create a class-based node with retry logic
nodecraft nodes create --name api_caller --type class
# Create a scenario from template
nodecraft scenarios create --name my_workflow --template rag-query
# View available templates
nodecraft scenarios create --name test --template custom --dry-run
```
### Register Custom Nodes and Scenarios
```bash
# Register a single node
nodecraft nodes register ./custom_nodes/my_node.py
# Register all nodes in a directory
nodecraft nodes register ./custom_nodes/ --recursive
# Register a scenario
nodecraft scenarios register ./my_scenario.yaml
```
## Configuration
Create a `.nodecraft.yaml` file in your project root:
```yaml
nodes:
search_paths:
- ".nodecraft/nodes"
- "./custom_nodes"
scenarios:
search_paths:
- ".nodecraft/scenarios"
- "./workflows"
llm:
default_model: "claude-3-haiku-20240307"
api_timeout: 60
```
Configuration priority: CLI arguments > Project config > Global config > Defaults
Global config location: `~/.nodecraft/config.yaml`
## Built-in Scenarios
OutcomeForge includes several built-in scenarios for common tasks:
- **snapshot**: Create snapshots of your codebase with AI analysis
- **adapt**: Analyze open-source repositories and generate adaptation plans
- **regression**: AI-powered quality gate based on test metrics
- **arch-drift**: Detect architecture violations and structural drift
- **rag**: Lightweight RAG for codebase Q&A
- **code-review**: Security, quality, and performance code review
- **wiki**: Generate structured wiki documentation from codebases
Example usage:
```bash
# Snapshot Management - Create version control points for your code
# Create a snapshot (saved to .ai-snapshots/ by default)
nodecraft snapshot --patterns "**/*.py"
nodecraft snapshot --patterns "**/*.py" --patterns "**/*.js" --model claude-3-haiku-20240307
# Create snapshot with custom output directory
nodecraft snapshot --output-dir ~/project-backups
nodecraft snapshot --output-dir ./snapshots --patterns "src/**/*.ts"
# List all snapshots (from default .ai-snapshots/ directory)
nodecraft snapshot-list
# List snapshots from custom directory
nodecraft snapshot-list --snapshot-dir ~/project-backups
# Restore from a snapshot (from default directory)
nodecraft snapshot-restore 20251019_025204
# Restore from snapshot in custom directory
nodecraft snapshot-restore 20251019_025204 --snapshot-dir ~/project-backups
# Ask questions about your codebase
nodecraft rag --patterns "**/*.py" --query "How does this work?"
# Review code changes
nodecraft code-review --git-diff
# Generate wiki documentation
nodecraft wiki --local-dir ./my-project
```
## CLI Usage
### Node Management
```bash
# List nodes
nodecraft nodes list [--namespace <namespace>]
# Show node details
nodecraft nodes show <node_id>
# Create new node from template
nodecraft nodes create --name <name> [--type function|class]
# Register custom node
nodecraft nodes register <path> [--recursive]
```
### Scenario Management
```bash
# List scenarios
nodecraft scenarios list
# Show scenario details
nodecraft scenarios show <scenario_id>
# Create new scenario from template
nodecraft scenarios create --name <name> --template <template>
# Register custom scenario
nodecraft scenarios register <path> [--recursive]
# Run a scenario
nodecraft <scenario_id> [OPTIONS]
```
Available scenario templates:
- `rag-query`: RAG-based codebase Q&A
- `file-process`: File collection and processing
- `analyze-report`: Code analysis with report generation
- `gate-check`: Quality gate enforcement
- `snapshot-restore`: Version control and rollback
- `custom`: Blank template for custom workflows
### Tutorial System
```bash
# Get started tutorial
nodecraft tutorial
# Node creation tutorial
nodecraft tutorial node
# Scenario tutorial
nodecraft tutorial scenario
```
## Architecture
### Node System
Nodes are the smallest units of work. Each node has three phases:
1. **prep**: Validate inputs and prepare parameters
2. **exec**: Execute the main operation
3. **post**: Process results and update context
Nodes are discovered automatically from:
- Framework built-in nodes (`nodes/common/`)
- Global user nodes (`~/.nodecraft/nodes/`)
- Project nodes (`.nodecraft/nodes/`)
- Configured search paths
### Scenario System
Scenarios are workflows composed of nodes. They can be defined in:
1. **Python** (programmatic):
```python
from engine import flow
from nodes.common import get_files_node, call_llm_node
def my_scenario(config):
f = flow()
f.add(get_files_node(), name="get_files")
f.add(call_llm_node(), name="analyze")
return f
```
2. **YAML** (declarative):
```yaml
scenario:
id: my_scenario
name: My Scenario
description: Custom workflow
parameters:
patterns:
type: list
default: ["**/*.py"]
steps:
- node: "@common/get_files"
name: get_files
params:
patterns: "{{params.patterns}}"
- node: "@common/call_llm"
name: analyze
```
### Context Flow
Data flows through the scenario via a shared context dictionary. Each node:
- Reads data from context using `input_keys`
- Writes results to context using `output_keys`
- Can access parameters via `{{params.name}}` syntax in YAML
## Development
### Project Structure
```
nodecraft/
├── core/ # Core framework
│ ├── registry.py # Node discovery and registration
│ ├── scenario_registry.py # Scenario management
│ ├── template_generator.py # Template generation
│ └── config.py # Configuration management
├── nodes/
│ └── common/ # Built-in nodes
├── scenarios/ # Built-in scenarios
├── templates/ # Node and scenario templates
│ ├── nodes/
│ └── scenarios/
└── cli.py # CLI entry point
```
### Running Tests
```bash
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_template_creation.py -v
```
## Requirements
- Python 3.7+
- anthropic (Claude API)
- openai (OpenAI API)
- click (CLI framework)
- pyyaml (YAML parsing)
- gitpython (Git operations)
- jinja2 (Template rendering)
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/bethneyQQ/NodeCraft",
"name": "NodeCraft",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "code-analysis, llm, ai, devops, quality-assurance",
"author": "NodeCraft Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b3/c0/fba95b300e8a0d8fdd0244b2c83873f651a034891f7ad166a49f73c270a4/nodecraft-0.2.2.tar.gz",
"platform": null,
"description": "# NodeCraft\n\nA modular framework for building composable AI workflows with a \"building blocks\" design philosophy.\n\n## Overview\n\nNodeCraft provides a pluggable Node and Scenario system that allows you to discover, create, and compose reusable AI workflow components. Think of it as building blocks for AI-powered code analysis and automation.\n\n## Key Features\n\n- Node-based architecture with automatic discovery\n- YAML-based scenario definition\n- Template-based Node and Scenario creation\n- Configuration file system for team collaboration\n- Dynamic CLI generation from scenarios\n- Built-in scenarios for common tasks\n\n## Installation\n\n```bash\n# Install from PyPI\npip install NodeCraft\n\n# Set up API key\nexport ANTHROPIC_API_KEY=\"your-api-key-here\"\n```\n\nAfter installation, the `nodecraft` command is available globally.\n\n## Quick Start\n\n### Discover Available Nodes and Scenarios\n\n```bash\n# List all available nodes\nnodecraft nodes list\n\n# Show node details\nnodecraft nodes show @common/get_files\n\n# List all scenarios\nnodecraft scenarios list\n\n# Show scenario details\nnodecraft scenarios show simple_rag\n```\n\n### Create New Nodes and Scenarios\n\n```bash\n# Create a function-based node\nnodecraft nodes create --name my_analyzer\n\n# Create a class-based node with retry logic\nnodecraft nodes create --name api_caller --type class\n\n# Create a scenario from template\nnodecraft scenarios create --name my_workflow --template rag-query\n\n# View available templates\nnodecraft scenarios create --name test --template custom --dry-run\n```\n\n### Register Custom Nodes and Scenarios\n\n```bash\n# Register a single node\nnodecraft nodes register ./custom_nodes/my_node.py\n\n# Register all nodes in a directory\nnodecraft nodes register ./custom_nodes/ --recursive\n\n# Register a scenario\nnodecraft scenarios register ./my_scenario.yaml\n```\n\n## Configuration\n\nCreate a `.nodecraft.yaml` file in your project root:\n\n```yaml\nnodes:\n search_paths:\n - \".nodecraft/nodes\"\n - \"./custom_nodes\"\n\nscenarios:\n search_paths:\n - \".nodecraft/scenarios\"\n - \"./workflows\"\n\nllm:\n default_model: \"claude-3-haiku-20240307\"\n api_timeout: 60\n```\n\nConfiguration priority: CLI arguments > Project config > Global config > Defaults\n\nGlobal config location: `~/.nodecraft/config.yaml`\n\n## Built-in Scenarios\n\nOutcomeForge includes several built-in scenarios for common tasks:\n\n- **snapshot**: Create snapshots of your codebase with AI analysis\n- **adapt**: Analyze open-source repositories and generate adaptation plans\n- **regression**: AI-powered quality gate based on test metrics\n- **arch-drift**: Detect architecture violations and structural drift\n- **rag**: Lightweight RAG for codebase Q&A\n- **code-review**: Security, quality, and performance code review\n- **wiki**: Generate structured wiki documentation from codebases\n\nExample usage:\n\n```bash\n# Snapshot Management - Create version control points for your code\n# Create a snapshot (saved to .ai-snapshots/ by default)\nnodecraft snapshot --patterns \"**/*.py\"\nnodecraft snapshot --patterns \"**/*.py\" --patterns \"**/*.js\" --model claude-3-haiku-20240307\n\n# Create snapshot with custom output directory\nnodecraft snapshot --output-dir ~/project-backups\nnodecraft snapshot --output-dir ./snapshots --patterns \"src/**/*.ts\"\n\n# List all snapshots (from default .ai-snapshots/ directory)\nnodecraft snapshot-list\n\n# List snapshots from custom directory\nnodecraft snapshot-list --snapshot-dir ~/project-backups\n\n# Restore from a snapshot (from default directory)\nnodecraft snapshot-restore 20251019_025204\n\n# Restore from snapshot in custom directory\nnodecraft snapshot-restore 20251019_025204 --snapshot-dir ~/project-backups\n\n# Ask questions about your codebase\nnodecraft rag --patterns \"**/*.py\" --query \"How does this work?\"\n\n# Review code changes\nnodecraft code-review --git-diff\n\n# Generate wiki documentation\nnodecraft wiki --local-dir ./my-project\n```\n\n## CLI Usage\n\n### Node Management\n\n```bash\n# List nodes\nnodecraft nodes list [--namespace <namespace>]\n\n# Show node details\nnodecraft nodes show <node_id>\n\n# Create new node from template\nnodecraft nodes create --name <name> [--type function|class]\n\n# Register custom node\nnodecraft nodes register <path> [--recursive]\n```\n\n### Scenario Management\n\n```bash\n# List scenarios\nnodecraft scenarios list\n\n# Show scenario details\nnodecraft scenarios show <scenario_id>\n\n# Create new scenario from template\nnodecraft scenarios create --name <name> --template <template>\n\n# Register custom scenario\nnodecraft scenarios register <path> [--recursive]\n\n# Run a scenario\nnodecraft <scenario_id> [OPTIONS]\n```\n\nAvailable scenario templates:\n- `rag-query`: RAG-based codebase Q&A\n- `file-process`: File collection and processing\n- `analyze-report`: Code analysis with report generation\n- `gate-check`: Quality gate enforcement\n- `snapshot-restore`: Version control and rollback\n- `custom`: Blank template for custom workflows\n\n### Tutorial System\n\n```bash\n# Get started tutorial\nnodecraft tutorial\n\n# Node creation tutorial\nnodecraft tutorial node\n\n# Scenario tutorial\nnodecraft tutorial scenario\n```\n\n## Architecture\n\n### Node System\n\nNodes are the smallest units of work. Each node has three phases:\n\n1. **prep**: Validate inputs and prepare parameters\n2. **exec**: Execute the main operation\n3. **post**: Process results and update context\n\nNodes are discovered automatically from:\n- Framework built-in nodes (`nodes/common/`)\n- Global user nodes (`~/.nodecraft/nodes/`)\n- Project nodes (`.nodecraft/nodes/`)\n- Configured search paths\n\n### Scenario System\n\nScenarios are workflows composed of nodes. They can be defined in:\n\n1. **Python** (programmatic):\n```python\nfrom engine import flow\nfrom nodes.common import get_files_node, call_llm_node\n\ndef my_scenario(config):\n f = flow()\n f.add(get_files_node(), name=\"get_files\")\n f.add(call_llm_node(), name=\"analyze\")\n return f\n```\n\n2. **YAML** (declarative):\n```yaml\nscenario:\n id: my_scenario\n name: My Scenario\n description: Custom workflow\n\nparameters:\n patterns:\n type: list\n default: [\"**/*.py\"]\n\nsteps:\n - node: \"@common/get_files\"\n name: get_files\n params:\n patterns: \"{{params.patterns}}\"\n\n - node: \"@common/call_llm\"\n name: analyze\n```\n\n### Context Flow\n\nData flows through the scenario via a shared context dictionary. Each node:\n- Reads data from context using `input_keys`\n- Writes results to context using `output_keys`\n- Can access parameters via `{{params.name}}` syntax in YAML\n\n## Development\n\n### Project Structure\n\n```\nnodecraft/\n\u251c\u2500\u2500 core/ # Core framework\n\u2502 \u251c\u2500\u2500 registry.py # Node discovery and registration\n\u2502 \u251c\u2500\u2500 scenario_registry.py # Scenario management\n\u2502 \u251c\u2500\u2500 template_generator.py # Template generation\n\u2502 \u2514\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 nodes/\n\u2502 \u2514\u2500\u2500 common/ # Built-in nodes\n\u251c\u2500\u2500 scenarios/ # Built-in scenarios\n\u251c\u2500\u2500 templates/ # Node and scenario templates\n\u2502 \u251c\u2500\u2500 nodes/\n\u2502 \u2514\u2500\u2500 scenarios/\n\u2514\u2500\u2500 cli.py # CLI entry point\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest tests/\n\n# Run specific test file\npytest tests/test_template_creation.py -v\n```\n\n## Requirements\n\n- Python 3.7+\n- anthropic (Claude API)\n- openai (OpenAI API)\n- click (CLI framework)\n- pyyaml (YAML parsing)\n- gitpython (Git operations)\n- jinja2 (Template rendering)\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": null,
"summary": "A modular framework for building composable AI workflows",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://github.com/bethneyQQ/NodeCraft#readme",
"Homepage": "https://github.com/bethneyQQ/NodeCraft",
"Issues": "https://github.com/bethneyQQ/NodeCraft/issues",
"Repository": "https://github.com/bethneyQQ/NodeCraft"
},
"split_keywords": [
"code-analysis",
" llm",
" ai",
" devops",
" quality-assurance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "51ee80123a9f8b47cff5d30b4375bf03b63704004342f048ff75c211e3ed0a90",
"md5": "d78dd7f6c3e356ddcf38d2c6e73de19c",
"sha256": "3e9a6aa3c2bd8999e426bee0960bf613e90f5fde7633fc39073d2f35bb303cff"
},
"downloads": -1,
"filename": "nodecraft-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d78dd7f6c3e356ddcf38d2c6e73de19c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 139908,
"upload_time": "2025-10-21T01:24:33",
"upload_time_iso_8601": "2025-10-21T01:24:33.269473Z",
"url": "https://files.pythonhosted.org/packages/51/ee/80123a9f8b47cff5d30b4375bf03b63704004342f048ff75c211e3ed0a90/nodecraft-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b3c0fba95b300e8a0d8fdd0244b2c83873f651a034891f7ad166a49f73c270a4",
"md5": "4b1ce0f7cad5293fb4833647e1ef32ae",
"sha256": "8732d9594d4c06e1244e98cf342cabd15efd9c3534454e2e4d9af2371091816a"
},
"downloads": -1,
"filename": "nodecraft-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "4b1ce0f7cad5293fb4833647e1ef32ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 152045,
"upload_time": "2025-10-21T01:24:34",
"upload_time_iso_8601": "2025-10-21T01:24:34.988887Z",
"url": "https://files.pythonhosted.org/packages/b3/c0/fba95b300e8a0d8fdd0244b2c83873f651a034891f7ad166a49f73c270a4/nodecraft-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 01:24:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bethneyQQ",
"github_project": "NodeCraft",
"github_not_found": true,
"lcname": "nodecraft"
}
JSON
