Add Skill: graph-based-node-workflow

Extracted from: https://github.com/temiroff/Blacknode.git
Score: 1.0

skills/graph-based-node-workflow/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: graph-based-node-workflow
+version: 1.0.0
+description: Create and execute typed node graphs for AI/robotics workflows by defining
+  nodes with inputs/outputs and connecting them with edges, then cooking the graph
+  to run the workflow.
+inputs:
+- bn.Graph() - the graph container for the workflow
+- Node definitions (Literal, Text, LLMAgent, Concat, Output, etc.) with specified
+  inputs and outputs
+- Edge connections mapping from_port to to_port between nodes
+steps:
+- 'Step 1: Initialize a bn.Graph() instance to serve as the workflow container'
+- 'Step 2: Define individual nodes with their required inputs and outputs (e.g., Literal
+  for data, LLMAgent for inference, Concat for combining, Output for final results)'
+- 'Step 3: Create edges connecting nodes by specifying source from_port and destination
+  to_port for each data flow'
+- 'Step 4: Execute the graph by calling g.cook() to process the defined workflow and
+  produce results'
+outputs:
+- Executed workflow results stored in the graph's output nodes
+- Cooked graph ready for inspection, replay, or deployment
+- Potential error states if node dependencies are missing or ports don't match
+tags: []
+metadata:
+  source_repo: https://github.com/temiroff/Blacknode.git
+  extracted_at: ''
+  confidence: 0.95
+---
+
+# graph-based-node-workflow
+
+Create and execute typed node graphs for AI/robotics workflows by defining nodes with inputs/outputs and connecting them with edges, then cooking the graph to run the workflow.
+
+## Setup
+
+**Dependencies:**
+
+```text
+pip install blacknode (core Python package) anthropic, openai, docker, petgraph (dependencies) Rust extensions in blacknode-core, blacknode-runtime (optional)
+```
+
+**Setup steps:**
+
+1. Install blacknode with Python 3.11+ and required dependencies
+1. Clone repository and navigate to project directory
+1. Run examples/converted_text_pipeline.py to see basic graph execution
+1. Modify node definitions and edges to create custom workflows
+
+## Key Files
+
+- `examples/converted_text_pipeline.py - basic pipeline pattern`
+- `examples/hello_agent.py - LLM agent workflow pattern`
+- `examples/research_pipeline.py - multi-node research workflow`
+- `blacknode.py - main CLI entry point`
+
+## Steps
+
+1. Step 1: Initialize a bn.Graph() instance to serve as the workflow container
+2. Step 2: Define individual nodes with their required inputs and outputs (e.g., Literal for data, LLMAgent for inference, Concat for combining, Output for final results)
+3. Step 3: Create edges connecting nodes by specifying source from_port and destination to_port for each data flow
+4. Step 4: Execute the graph by calling g.cook() to process the defined workflow and produce results
+
+## Implementation Details
+
+```python
+g = bn.Graph()
+```
+
+```python
+g._edges = [{"from": "model", "from_port": "value", "to": "agent", "to_port": "model"}]
+```
+
+```python
+result = g.cook(output, "value")
+```
+
+## Inputs
+
+- bn.Graph() - the graph container for the workflow
+- Node definitions (Literal, Text, LLMAgent, Concat, Output, etc.) with specified inputs and outputs
+- Edge connections mapping from_port to to_port between nodes
+
+## Outputs
+
+- Executed workflow results stored in the graph's output nodes
+- Cooked graph ready for inspection, replay, or deployment
+- Potential error states if node dependencies are missing or ports don't match
+
+## Failure Modes
+
+- Missing node dependencies causing undefined variable errors
+- Port mismatch in edge connections leading to no data flow
+- Incomplete graph definition causing cook() to fail
+- Model API key missing or invalid for LLMAgent nodes
+
+## Source
+
+Extracted from: [https://github.com/temiroff/Blacknode.git](https://github.com/temiroff/Blacknode.git)
+Confidence: 0.95

skills/graph-based-node-workflow/commands.md

@@ -0,0 +1,6 @@
+# Commands: graph-based-node-workflow
+
+## Available Commands
+
+- `/skill graph-based-node-workflow` — Load this skill
+- `/run graph-based-node-workflow` — Execute workflow

skills/graph-based-node-workflow/examples.md

@@ -0,0 +1,10 @@
+# Examples: graph-based-node-workflow
+
+## Usage Example
+
+```python
+# How to use this skill
+# Inputs: bn.Graph() - the graph container for the workflow, Node definitions (Literal, Text, LLMAgent, Concat, Output, etc.) with specified inputs and outputs, Edge connections mapping from_port to to_port between nodes
+# Process: Step 1: Initialize a bn.Graph() instance to serve as the workflow container → Step 2: Define individual nodes with their required inputs and outputs (e.g., Literal for data, LLMAgent for inference, Concat for combining, Output for final results) → Step 3: Create edges connecting nodes by specifying source from_port and destination to_port for each data flow
+# Outputs: Executed workflow results stored in the graph's output nodes, Cooked graph ready for inspection, replay, or deployment, Potential error states if node dependencies are missing or ports don't match
+```

skills/graph-based-node-workflow/metadata.json

@@ -0,0 +1,31 @@
+{
+  "name": "graph-based-node-workflow",
+  "version": "1.0.0",
+  "goal": "Create and execute typed node graphs for AI/robotics workflows by defining nodes with inputs/outputs and connecting them with edges, then cooking the graph to run the workflow.",
+  "inputs": [
+    "bn.Graph() - the graph container for the workflow",
+    "Node definitions (Literal, Text, LLMAgent, Concat, Output, etc.) with specified inputs and outputs",
+    "Edge connections mapping from_port to to_port between nodes"
+  ],
+  "steps": [
+    "Step 1: Initialize a bn.Graph() instance to serve as the workflow container",
+    "Step 2: Define individual nodes with their required inputs and outputs (e.g., Literal for data, LLMAgent for inference, Concat for combining, Output for final results)",
+    "Step 3: Create edges connecting nodes by specifying source from_port and destination to_port for each data flow",
+    "Step 4: Execute the graph by calling g.cook() to process the defined workflow and produce results"
+  ],
+  "outputs": [
+    "Executed workflow results stored in the graph's output nodes",
+    "Cooked graph ready for inspection, replay, or deployment",
+    "Potential error states if node dependencies are missing or ports don't match"
+  ],
+  "failure_modes": [
+    "Missing node dependencies causing undefined variable errors",
+    "Port mismatch in edge connections leading to no data flow",
+    "Incomplete graph definition causing cook() to fail",
+    "Model API key missing or invalid for LLMAgent nodes"
+  ],
+  "confidence": 0.95,
+  "explanation": "This workflow pattern is reusable across different AI/robotics applications because it provides a standardized way to compose complex pipelines from typed nodes. The pattern can be adapted to various use cases like research pipelines, agent workflows, or robotics control graphs by simply adding/removing nodes and edges while maintaining the same graph-cooking execution model.",
+  "source_repo": "https://github.com/temiroff/Blacknode.git",
+  "score": 1.0
+}

skills/graph-based-node-workflow/tests.md

@@ -1,4 +1,4 @@
-# Tests: local-document-research-with-traceable-citations
+# Tests: graph-based-node-workflow
 
 ## Test Checklist
 

skills/local-document-research-with-traceable-citations/SKILL.md

@@ -1,82 +0,0 @@
----
-name: local-document-research-with-traceable-citations
-version: 1.0.0
-description: Enable users to import local documents, asynchronously process them into
-  an indexed knowledge base, and obtain AI-generated answers that cite specific page
-  locations and OCR evidence.
-inputs:
-- Local document files (PDF, DOCX, PPTX, XLSX, images, TXT)
-- Configured LLM API endpoint and keys (via .env or settings)
-- Optional web search service config if enabled
-- Local OCR model cache (downloaded on first use)
-steps:
-- Import documents into a project; files are queued for asynchronous processing.
-- Convert non-PDF formats (DOCX, PPTX, XLSX) to PDF using native Office or LibreOffice
-  fallback.
-- Run OCR (PaddleOCR) on PDF pages/images to extract text, page numbers, polygons,
-  and confidence scores.
-- Chunk text and generate embeddings; publish to LanceDB hybrid index (dense vector
-  + full-text) only when fully processed.
-- User starts a research session or branch; Leader agent analyzes query.
-- Hybrid RAG retrieves candidate chunks from ready documents; dynamic material scope
-  ensures no half-indexed docs.
-- Leader delegates tasks to sub-agents (researcher, reviewer, writer) via constrained
-  task capability; each delegation logs start, completion, duration, and evidence.
-- Generate answer that references only actually used evidence; citations include document
-  ID, page, coordinates.
-- User clicks citation to open original document and view highlighted OCR location.
-outputs:
-- Project with indexed document library (SQLite metadata + LanceDB vectors)
-- AI answers with verifiable citations to source pages
-- Evidence preview with page image and OCR highlight polygons
-- Persistent session history, branches, and long-term memory
-tags: []
-metadata:
-  source_repo: https://github.com/0verL1nk/PaperSage.git
-  extracted_at: ''
-  confidence: 0.85
----
-
-# local-document-research-with-traceable-citations
-
-Enable users to import local documents, asynchronously process them into an indexed knowledge base, and obtain AI-generated answers that cite specific page locations and OCR evidence.
-
-## Steps
-
-1. Import documents into a project; files are queued for asynchronous processing.
-2. Convert non-PDF formats (DOCX, PPTX, XLSX) to PDF using native Office or LibreOffice fallback.
-3. Run OCR (PaddleOCR) on PDF pages/images to extract text, page numbers, polygons, and confidence scores.
-4. Chunk text and generate embeddings; publish to LanceDB hybrid index (dense vector + full-text) only when fully processed.
-5. User starts a research session or branch; Leader agent analyzes query.
-6. Hybrid RAG retrieves candidate chunks from ready documents; dynamic material scope ensures no half-indexed docs.
-7. Leader delegates tasks to sub-agents (researcher, reviewer, writer) via constrained task capability; each delegation logs start, completion, duration, and evidence.
-8. Generate answer that references only actually used evidence; citations include document ID, page, coordinates.
-9. User clicks citation to open original document and view highlighted OCR location.
-
-## Inputs
-
-- Local document files (PDF, DOCX, PPTX, XLSX, images, TXT)
-- Configured LLM API endpoint and keys (via .env or settings)
-- Optional web search service config if enabled
-- Local OCR model cache (downloaded on first use)
-
-## Outputs
-
-- Project with indexed document library (SQLite metadata + LanceDB vectors)
-- AI answers with verifiable citations to source pages
-- Evidence preview with page image and OCR highlight polygons
-- Persistent session history, branches, and long-term memory
-
-## Failure Modes
-
-- OCR quality low for scanned images leading to poor extraction
-- Missing Office/LibreOffice causes conversion failure for Office docs
-- Interrupted indexing leaves documents unpublished and excluded from retrieval
-- LLM API outage or misconfiguration yields no answer
-- Citation coordinates mismatch due to chunk drift
-- Sub-agent recursion if constraints not enforced
-
-## Source
-
-Extracted from: [https://github.com/0verL1nk/PaperSage.git](https://github.com/0verL1nk/PaperSage.git)
-Confidence: 0.85

skills/local-document-research-with-traceable-citations/commands.md

@@ -1,6 +0,0 @@
-# Commands: local-document-research-with-traceable-citations
-
-## Available Commands
-
-- `/skill local-document-research-with-traceable-citations` — Load this skill
-- `/run local-document-research-with-traceable-citations` — Execute workflow

skills/local-document-research-with-traceable-citations/examples.md

@@ -1,10 +0,0 @@
-# Examples: local-document-research-with-traceable-citations
-
-## Usage Example
-
-```python
-# How to use this skill
-# Inputs: Local document files (PDF, DOCX, PPTX, XLSX, images, TXT), Configured LLM API endpoint and keys (via .env or settings), Optional web search service config if enabled, Local OCR model cache (downloaded on first use)
-# Process: Import documents into a project; files are queued for asynchronous processing. → Convert non-PDF formats (DOCX, PPTX, XLSX) to PDF using native Office or LibreOffice fallback. → Run OCR (PaddleOCR) on PDF pages/images to extract text, page numbers, polygons, and confidence scores.
-# Outputs: Project with indexed document library (SQLite metadata + LanceDB vectors), AI answers with verifiable citations to source pages, Evidence preview with page image and OCR highlight polygons, Persistent session history, branches, and long-term memory
-```

skills/local-document-research-with-traceable-citations/metadata.json

@@ -1,40 +0,0 @@
-{
-  "name": "local-document-research-with-traceable-citations",
-  "version": "1.0.0",
-  "goal": "Enable users to import local documents, asynchronously process them into an indexed knowledge base, and obtain AI-generated answers that cite specific page locations and OCR evidence.",
-  "inputs": [
-    "Local document files (PDF, DOCX, PPTX, XLSX, images, TXT)",
-    "Configured LLM API endpoint and keys (via .env or settings)",
-    "Optional web search service config if enabled",
-    "Local OCR model cache (downloaded on first use)"
-  ],
-  "steps": [
-    "Import documents into a project; files are queued for asynchronous processing.",
-    "Convert non-PDF formats (DOCX, PPTX, XLSX) to PDF using native Office or LibreOffice fallback.",
-    "Run OCR (PaddleOCR) on PDF pages/images to extract text, page numbers, polygons, and confidence scores.",
-    "Chunk text and generate embeddings; publish to LanceDB hybrid index (dense vector + full-text) only when fully processed.",
-    "User starts a research session or branch; Leader agent analyzes query.",
-    "Hybrid RAG retrieves candidate chunks from ready documents; dynamic material scope ensures no half-indexed docs.",
-    "Leader delegates tasks to sub-agents (researcher, reviewer, writer) via constrained task capability; each delegation logs start, completion, duration, and evidence.",
-    "Generate answer that references only actually used evidence; citations include document ID, page, coordinates.",
-    "User clicks citation to open original document and view highlighted OCR location."
-  ],
-  "outputs": [
-    "Project with indexed document library (SQLite metadata + LanceDB vectors)",
-    "AI answers with verifiable citations to source pages",
-    "Evidence preview with page image and OCR highlight polygons",
-    "Persistent session history, branches, and long-term memory"
-  ],
-  "failure_modes": [
-    "OCR quality low for scanned images leading to poor extraction",
-    "Missing Office/LibreOffice causes conversion failure for Office docs",
-    "Interrupted indexing leaves documents unpublished and excluded from retrieval",
-    "LLM API outage or misconfiguration yields no answer",
-    "Citation coordinates mismatch due to chunk drift",
-    "Sub-agent recursion if constraints not enforced"
-  ],
-  "confidence": 0.85,
-  "explanation": "The README outlines a clear pipeline from document import to cited answer with evidence location, which is a reusable pattern for local-first RAG applications requiring traceability.",
-  "source_repo": "https://github.com/0verL1nk/PaperSage.git",
-  "score": 1.0
-}