Refactor

.env.example

@@ -0,0 +1,24 @@
+# Only needed if you do not use OpenAI as a provider (optional)
+LLM_PROVIDER=OPENAI
+
+OPENAI_API_KEY=
+OPENAI_API_MODEL=gpt-3.5-turbo
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+OLLAMA_API_KEY=none
+OLLAMA_API_MODEL=phi3
+OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
+
+GROQ_API_KEY=
+GROQ_API_MODEL=gemma-7b-it
+GROQ_BASE_URL=https://api.groq.com/openai/v1
+
+MISTRAL_API_KEY=
+MISTRAL_API_MODEL=mistral-medium
+MISTRAL_BASE_URL=https://api.mistral.ai/v1
+
+
+
+ANTHROPIC_API_KEY=
+ANTHROPIC_API_MODEL=claude-3-5-haiku-20241022
+ANTHROPIC_BASE_URL=https://api.anthropic.com

.github/workflows/test.yaml

@@ -0,0 +1,27 @@
+name: Yarn Test
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: setup bun
+        uses: oven-sh/setup-bun@v1
+      - name: install dependencies
+        run: bun install
+      - name: run tests
+        run: |
+          cd  packages/canvas-engine
+          bun test
+      - name: test build
+        run: |
+          cd  packages/canvas-engine
+          bun run build:lib

.gitignore

@@ -1,4 +1,180 @@
-node_modules
+# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
+
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Caches
+
+.cache
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+
 build
 local
-.env
+old
+.obsidian

README.md

@@ -13,13 +13,13 @@ Example 2:
 
 > To be sure to only see what was created **during the hackaton** see [branch: during-hackathon](https://github.com/Davidiusdadi/obsidian-node-canvas/tree/during-hackathon). Right now  [master](https://github.com/Davidiusdadi/obsidian-node-canvas/tree/master)-branch and [during-hackathon](https://github.com/Davidiusdadi/obsidian-node-canvas/tree/during-hackathon)-branch should be almost identical.
 
-**Obsidan-Node-Canvas** is a `javascript`-based workflow/scripting engine build on top of [obsidian](https://obsidian.md/)  (the popular and powerful journaling, knowledge bases, and project management tool ) - and specifically https://obsidian.md/canvas.
+**Obsidian-Node-Canvas** is a `javascript`-based workflow/scripting engine build on top of [obsidian](https://obsidian.md/)  (the popular and powerful journaling, knowledge bases, and project management tool ) - and specifically https://obsidian.md/canvas.
 
-Using Obsidan-Node-Canvas requires at least basic understanding `javascript`-programming. 
+Using Obsidian-Node-Canvas requires at least basic understanding of `javascript` programming. 
 
 You could use it to automate things in your obsidian-vault - but the main obsidian connection is that obsidian acts as a frontend - what you build is up to you. 
 
-**Obsidan-Node-Canvas** makes it possible to:
+**Obsidian-Node-Canvas** makes it possible to:
 
 - ✅ visually _compose_ "function"-blocks (nodes on a canvas) and **execute** them
 - intuitively combine:
@@ -41,7 +41,7 @@ You could use it to automate things in your obsidian-vault - but the main obsidi
 
 ## Conception
 
-**Obsidan-Node-Canvas** has been _**conceived**_ 💥 and _**prototyped**_ 🚀 during the **[Code 2 Community - The Y Berlin x ICP](https://lu.ma/zwblit5f) hackathon**.
+**Obsidian-Node-Canvas** has been _**conceived**_ 💥 and _**prototyped**_ 🚀 during the **[Code 2 Community - The Y Berlin x ICP](https://lu.ma/zwblit5f) hackathon**.
 
 This project has been submitted [here](https://dacade.org/communities/icp/challenges/b35bd8af-51d3-437a-af13-4e649529c7e5/submissions/5605d208-bb84-4551-9697-e89f75901ce0).
 
@@ -56,14 +56,14 @@ Here a rough overview:
 
 - only one node is active at a time
 - the first code block of each node will be executed
-- execution starts at a with just the content: 'start'
+- execution starts at a node with just the content: 'start'
 - there are nodes that do not use code-blocks but special syntax (see below)
 - only directed arrows matter as of now
 - currently all invocations are stored until the canvas complete
   - aka. circular constructs will leak memory 
     - this will be fixed when aggregations get an update
 - these are the special variables
-  - `input` - can be anyting
+  - `input` - can be anything
   - `state` - can be anything - is cloned whenever it passed through an arrow
   - `this` - is persistant during a node's invocations
     - holds special `join` object used for flow control (see below)
@@ -90,8 +90,8 @@ Here a rough overview:
     - supports nunjucks templating
   - "prompt gpt" (specific format required)
     - supports nunjucks templating
-- magic fist word node:
-  - `decide` promptes gpt-3 (will be reworked soon)
+- magic first word node:
+  - `decide` prompts gpt-3 (will be reworked soon)
 - _identity_ - anything that cant be parsed yet is not specifically wrong (e.g. bad js syntax) will be treated as and identity function `(input) => input`
   - an empty node will also be and identity node
 
@@ -137,35 +137,64 @@ Analogous there is also `const list = zipOnState('name').list()` and `const list
 
 ##### zip merge example 1:
 
-![img.png](examples/tutorial/flow-control/images/example-zip-simple-success.png)
+![img.png](examples/feature-tour/2-flow-control/images/example-zip-simple-success.png)
 
 ##### zip merge example 2:
 
-![img_1.png](examples/tutorial/flow-control/images/example-zip-partial-success.png)
+![img_1.png](examples/feature-tour/2-flow-control/images/example-zip-partial-success.png)
 
 ## how to run
 
 > Warning: install run at your own risk. Do not execute `.canvas` that you do not understand.
 
-- clone this repo
-- be sure you have a recent `node` version installed. I used v20.10.0
-- install via [yarn](https://yarnpkg.com/) 
+### Initial Setup
 
-- create a `.env` file
-  - containing `OPENAI_API_KEY=<YOURKEYHERE>`
-  - this is needed as the tutorial.canvas uses LLM-nodes
+1. **Clone this repo**
+2. **Install Node.js** - Recent version required (tested with v20.10.0, works with v22+)
+3. **Install dependencies** via [yarn](https://yarnpkg.com/):
 
-- then:
 ```bash
-# from the checkout root call:
+yarn install
+```
+
+> **Note:** You may see a build warning about the `canvas` package (missing `pangocairo` system dependencies). This is harmless and won't affect basic functionality.
+
+4. **(Optional)** Create a `.env` file for LLM features:
+   - Only needed if you want to use LLM/GPT nodes
+   - Add: `OPENAI_API_KEY=<YOURKEYHERE>`
+   - Not required for basic canvas execution
+
+### Running Examples
+
+All examples should be run from the repository root:
+
+#### Core Features (No API Key Required) ✅
+
+```bash
+# Basic arrow propagation and data flow
+yarn dev --vault examples --canvas feature-tour/1-arrow-propagation/propagation.canvas
+
+# Flow control: aggregation
+yarn dev --vault examples --canvas feature-tour/2-flow-control/aggregate.canvas
 
-yarn install # install dependencies
+# Flow control: zip and aggregate
+yarn dev --vault examples --canvas feature-tour/2-flow-control/zip-and-aggregate.canvas
 
-yarn dev --vault examples --canvas tutorial/tutorial.canvas
-yarn dev --vault examples --canvas tutorial/read-eval-loop/sly-llm-agent.canvas
-yarn dev --vault examples --canvas tutorial/flow-control/zip-and-aggregate.canvas
-yarn dev --vault examples --canvas tutorial/reference-file/hello.canvas
+# Canvas composition and signals
+yarn dev --vault examples --canvas feature-tour/3-canvas-signals/caller.canvas
+
+# Canvas overload patterns
+yarn dev --vault examples --canvas feature-tour/4-canvas-overload/caller.canvas
+```
+
+#### Advanced Examples (Require OpenAI API Key) 🔑
+
+```bash
+# LLM-powered tutorial
+yarn dev --vault examples --canvas feature-tour/tutorial.canvas
 
+# Shell automation with LLM
+yarn dev --vault examples --canvas feature-tour/shell/bash.canvas
 ```
 
 Off you go with your own canvas 🕊️