voleum/gr-base
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

add website with docs

Browse source
This commit is contained in:
EatThePooh 2025-08-25 18:17:01 +07:00
parent 870c20e745
commit fcf1979a1d
12 changed files with 541 additions and 314 deletions
Download patch file Download diff file Expand all files Collapse all files

167
README.org
View file

@ -1,58 +1,12 @@
:PROPERTIES:
:ID: 55a85682-80d7-41fe-ab55-d3afe9abbc38
:END:
#+OPTIONS: toc:nil
#+BEGIN_EXPORT html
<style>
body {
font-family: 'Courier New', Courier, monospace;
background-color: ivory;
line-height: 1.5;
padding-right: 1em;
}
h2 {
margin-top: 1.8rem;
padding-left: 0.5rem;
border-left: 4px solid #3498db;
}
table {
width: 100%;
}
#content {
max-width: 48em;
}
.outline-2 div {
padding-left: 1em;
}
a:link {
color: #2E5EAA;
text-decoration: none;
}
a:visited {
color: #663399;
}
a:hover {
color: #1a4480;
text-decoration: underline;
}
</style>
#+END_EXPORT
#+title: Grimu-R
Grimu-R is an *open ecosystem* and a framework for mixed visual-textual *dataflow* scripting.
*Grimu-R* is an open ecosystem and a framework for mixed visual-textual dataflow scripting.
It consists primarily of the following components:
- Execution model allowing computations to be expressed as *reactive graphs*
- *Polyglot scripting* runtime environment
- Interactive web-based *visual-textual* editor
- *Polyglot scripting* runtime environment
- Execution model allowing computations to be expressed as *reactive graphs*
#+TOC: headlines 2
* Table of Contents :TOC_2_gh:noexport:
- [[#inspiration][Inspiration]]
- [[#goals][Goals]]
- [[#immediate-feedback-and-composability][Immediate feedback and composability]]
- [[#embeddable-build-targets][Embeddable build targets]]
@ -66,8 +20,8 @@ It consists primarily of the following components:
- [[#positioning][Positioning]]
- [[#nomenclature][Nomenclature]]
- [[#weave][Weave]]
- [[#ornament][Ornament]]
- [[#spell][Spell]]
- [[#braid][Braid]]
- [[#sigil][Sigil]]
- [[#scroll][Scroll]]
- [[#inscription][Inscription]]
- [[#how-it-works][How it works]]
@ -75,7 +29,6 @@ It consists primarily of the following components:
- [[#workflow][Workflow]]
- [[#cross-language-connections][Cross-language connections]]
- [[#execution-environment][Execution environment]]
- [[#features][Features]]
- [[#faq][FAQ]]
- [[#is-this-a-yet-another-web-framework][Is this a yet another web framework?]]
- [[#how-does-malleability-work-in-client-server-applications][How does malleability work in client-server applications?]]
@ -83,13 +36,8 @@ It consists primarily of the following components:
- [[#how-do-i-test-my-weave][How do I test my weave?]]
- [[#can-i-integrate-ai-models][Can I integrate AI models?]]
- [[#licensing][Licensing]]
- [[#how-it-works-1][How it works]]
- [[#compliance-guide][Compliance guide]]
* Inspiration
- [[https://github.com/enso-org/enso][Enso]]
- [[https://unit.software][Unit]]
- [[https://jupyter.org/][Jupyter Notebooks]]
- [[https://observablehq.com/][Observable]]
* Goals
** Immediate feedback and composability
@ -101,7 +49,7 @@ experiment and reuse previous work.
An interactive visual editor allows one to prototype, debug and run one-off jobs comfortably.
But the work can always be distilled into an executable artifact:
a CLI tool, an RPC server, or a web application, to be distributed as such or integrated into larger workflows.
a CLI tool, an RPC server, or a web application, to be distributed as such or integrated into larger flows.
** Hassle-free reproducible builds
@ -136,19 +84,18 @@ Get started without implementing your own components.
Low code to high code.
* Non-goals
Some things Grimu-R itself will not take care of, delegating them to the surrounding environment:
Some things Grimu-R itself will not take care of, delegating them to the surrounding environment or just omitting:
- Resumable/durable execution
- Distributed deployment orchestration
- Collaborative editing
- Real-time collaborative editing
- Authentication and access control
- Telemetry
* Use cases
- Rapid prototyping of data processing pipelines
- Self-hosted workflow automation
- Dashboards with custom logic
- Internal tooling and automation scripts
- Hacker-friendly, highly customizable applications
- Rapid prototyping of *data processing* pipelines
- *Self-hosted* workflow automation
- *Dashboards* with custom logic
- *Internal tooling* and automation scripts
- Hacker-friendly, highly *customizable* applications
* Positioning
Grimu-R aims to take the best without the worst from:
@ -168,47 +115,49 @@ A Grimu-R project's weave is what changes when someone is working on it ("weavin
It's a persistent, Git-friendly representation of the dataflow graph and its graphic layout.
** Ornament
** Braid
Weaves are composed of ornaments, which serve the dual purpose of reusable modules and entry points.
Weaves are composed of braids, which serve the dual purpose of reusable modules and entry points.
An ornament would correspond to an RPC method or a CLI subcommand.
An braid could correspond to an RPC method or a CLI subcommand in a build.
Ornaments can be nested within other ornaments, appearing as single nodes that encapsulate their internal graphs.
Braids can be nested within other braids, appearing as single nodes that encapsulate their internal graphs.
** Spell
** Sigil
Spells are the basic building blocks for ornaments.
Sigils are the basic building blocks for braids.
A spell is just a normal computer program that acts as:
A sigil is just a normal computer program that acts as:
- data source (e. g. a static CSV sheet)
- data sink (e. g. a POST endpoint)
- data transformer (e. g. grep)
Each spell is based on a scroll and can contain a dynamic script ("inscription") stored in the weave.
Each sigil is based on a scroll and can contain a dynamic script ("inscription") stored in the weave.
** Scroll
Scrolls define a default configuration for spells, as well as the runtime environment to run a spell in.
Scrolls define a default configuration for sigils, as well as the runtime environment to run a sigil in.
They are developed outside of Grimu-R using standard development tooling.
They are developed outside of Grimu-R using standard development tooling and integrated with Nix.
** Inscription
Spells based on interpreter scrolls (like Bash, Node.js) can have their inscriptions edited
Sigils based on interpreter scrolls (like Bash, Node.js) can have their inscriptions edited
directly in the visual editor, enabling live code changes without rebuilding the development environment.
There can be other kinds of inscriptions: templates, configurations, parameters, etc.
* How it works
** Development environment
Grimu-R projects being Nix flakes, the development tooling ("loom") is provisioned in a Nix shell.
It gives you the visual editor, the companion CLI tool and the execution context for spells.
It gives you the visual editor, the companion CLI tool and the execution context for sigils.
** Workflow
- The visual editor is served by a development or application server.
- Changes and execution requests for server-side spells are sent over a bidirectional WebSocket connection.
- Changes and execution requests for natively executed sigils are sent over a bidirectional WebSocket connection.
- User modifications are stored locally in the browser's storage, exportable as a file.
- Weaves are tracked by usual VCS tools.
@ -220,23 +169,13 @@ Think Unix pipes but with structured data formats like JSON lines instead of pla
Purpose-specific scrolls used in a weave have their requirements defined in Nix terms.
For example, if several scrolls need Deno, they can all refer to the same deno Nix package defined in the flake and declare their Deno dependencies normally.
For example, if several scrolls need Deno, they can all refer to the same deno Nix package defined in the flake's nixpkgs overlay and declare their Deno dependencies normally in deno.json.
A single copy of Deno runtime and a shared Deno cache would be bundled in an edition.
A single copy of Deno runtime and a shared Deno cache would be bundled in a build.
However, the general-purpose Deno scroll executing arbitrary TypeScript inscriptions
would have Deno fetch dependencies during runtime.
* Features
| | On the roadmap | Ideas |
|--------------------------+--------------------------------+--------------------|
| Editions (build targets) | Self-sufficient CLI executable | Mobile application |
| | CLI client + RPC server | React component |
| | Web application | |
| | | |
| Scripting languages | TypeScript | DuckDB SQL |
| | Bash | Python |
| | Haskell | R |
* FAQ
** Is this a yet another web framework?
@ -249,8 +188,8 @@ Or you could use any framework you like with the dataflow stuff being incidental
** How does malleability work in client-server applications?
Unlike standalone editions executing entirely on the end user's machine,
client-server editions split the weave between runtime components.
Unlike standalone builds executing entirely on the end user's machine,
client-server builds split the weave between runtime components.
Only the client-side part of the weave can be inspected and edited by
the end user.
@ -260,7 +199,7 @@ the end user.
To some extent, yes.
While Grimu-R is built on top of Nix and wouldn't make a lot of sense otherwise,
you always have the option to access out-of-store files from your spells' inscriptions,
you always have the option to access out-of-store files from your sigils,
at the cost of reproducibility.
So you could use e. g. runtime JS imports or call some executable on PATH from a shell script.
@ -268,27 +207,27 @@ So you could use e. g. runtime JS imports or call some executable on PATH from a
** How do I test my weave?
If you do it manually: right in the visual editor.
Add spells with a constant output as test data sources and stitch them to the spells you want to test.
Add sigils with a constant output as test data sources and connect them to the sigils you want to test.
If you need automation: build an edition and call the ornaments programmatically.
If you already have test data stored in the weave, you can extract it by the spell's id using loom CLI or library.
If you need automation: call the braids programmatically.
If you already have test data stored in the weave, you can extract it by the sigil's id using loom CLI or library.
** Can I integrate AI models?
There are three integration scenarios which would make sense:
1. AI spells in the weave:
1. AI sigils in the weave:
Spells calling inference APIs, equipped with MCP spells and
template spells for prompt composition
Sigils calling inference APIs, equipped with MCP sigils and
template sigils for prompt composition
2. AI weaving copilot:
Loom providing AI tools to edit the weave
3. MCP server editions:
3. MCP server builds:
Ornaments exposed as tools for external AI systems
Braids exposed as tools for external AI systems
#1 is easy to do even with no out-of-the-box support.
@ -296,7 +235,7 @@ There are three integration scenarios which would make sense:
* Licensing
The Grimu-R platform components, including Loom development utilities and
the execution engine, are licensed under AGPL v3.
the weave executor builders, are licensed under AGPL v3.
Base scrolls and other non-platform code are licensed under MIT.
@ -315,9 +254,19 @@ original license terms specified above.
Alternative contribution arrangements may be available upon request.
** How it works
If you fork the platform and build a product on top of its code,
the fork MUST be licensed under AGPL v3 (or a more restrictive copyleft license),
even if it's a cloud product.
** Compliance guide
Your options for licensing your work are restricted in the following scenarios:
All other code can be used without restrictions.
1. You fork Loom or weave executor builders and distribute your fork.
2. You build a product extending the platform's or its fork's functionality
while incorporating their code.
3. Your weave or scrolls make use of third-party copyleft-licensed software.
This is independent of Grimu-R platform's licensing.
Note that AGPL terms apply even for SaaS solutions.
Loom being AGPL does not affect the licensing of weaves you develop using it.
Weave executors being AGPL means that your application using them has
to provide AGPL license notice and link to their source code repository;
your application's code, however, needs not be provided.

69
doc/stories.org
View file

@ -1,69 +0,0 @@
:PROPERTIES:
:ID: bbd0d76c-33c8-47d7-8eb7-79f5f9e5e633
:END:
#+title: Grimu-R stories
#+STARTUP: show3levels
* As a Grimu-R project developer, I want
** To get started quickly
*** And import my lousy shell scripts or code notebooks
*** And have the entire dev environment set up with a single command
*** And employ readily available scrolls, such as
**** A wrapper supporting most Unix utilities specified via inscription
**** HTTP fetch / post / stream / subscribe to event source
**** General purpose templates (Mustache)
**** Basic HTML with simple query param state
**** Large file reader, the file being
***** Arbitrary text (streamed)
***** CSV / JSON lines
***** SQLite / DuckDB database
**** Integrations for services like
***** Telegram
***** Slack
***** Database servers
** To have full granular control over weave's dataflow
*** And push or pull data as needed
*** And batch data
*** And throttle/debounce data
*** And retry computations if they fail
**** With flexible custom retry policies
** To depend on other Grimu-R projects
*** And get their environments composed with mine
*** And use their scrolls
*** And use their ornaments
** To author scroll/spell code in
*** Browser JavaScript
*** Deno TypeScript
*** GHC Haskell
*** SQL (DuckDB, SQLite)
*** Python
** To extend the available toolset
*** By authoring my own scrolls
*** By calling executables outside of the Nix store
*** By upstreaming support for new programming language with its ecosystem
** To deploy my project as
*** Standalone CLI
*** CLI + RPC server
*** Web application server hosting a frontend
*** Mobile application
*** React component
** To interact with the weave programmatically
*** And inspect its contents
*** And run ornaments
*** And edit it
*** And check its validity
* As a Grimu-R project user, I want
** To build and host it myself
** To use loom to edit the client-side part of the weave
** To keep the changes I made
*** In the browser's local storage
*** And export them elsewhere
* As a Grimu-R loom visual editor consumer, I want
** To use it interactively
*** And see the actual data passing across stitches
*** And test parts of the weave with mock data
*** And quickly add debug displays
*** And change the inscriptions
**** Right in the visual editor
**** In an external editor of my preference
*** And undo/redo my changes

87
doc/vocabulary.org
View file

@ -1,87 +0,0 @@
:PROPERTIES:
:ID: 00790dad-7881-4252-8951-23f770e3f070
:END:
#+BEGIN_EXPORT html
<style>
body {
font-family: 'Courier New', Courier, monospace;
background-color: ivory;
line-height: 1.5;
padding-right: 1em;
}
h2 {
margin-top: 1.8rem;
padding-left: 0.5rem;
border-left: 4px solid #3498db;
}
table {
width: 100%;
}
#content {
max-width: 48em;
}
.outline-2 div {
padding-left: 1em;
}
a:link {
color: #2E5EAA;
text-decoration: none;
}
a:visited {
color: #663399;
}
a:hover {
color: #1a4480;
text-decoration: underline;
}
</style>
#+END_EXPORT
#+title: Grimu-R vocabulary
** Weave
Defines a collection of ornaments.
** Ornament
Has reactive inputs and outputs.
Serves as an externally invocable entry point.
Contains spells or nested ornament instances connected by stitches.
Can be distributed within an edition.
** Spell
Has reactive inputs and outputs.
Atomic execution unit.
Cannot be directly invoked by an edition consumer.
May have an inscription.
Created from a scroll and executed in the shelf environment.
** Stitch
Connects a reactive input to a compatible reactive output.
Can be decorated on both upstream and downstream ends.
May be parameterized by a reactive input, consuming variable assignments for the decoration.
** Stitch decorator
Defines reactive behavior.
May refer to variables defined by the reactive input.
** Inscription
Defines code in a scripting language to be run when the corresponding spell is executed.
May be defined statically in the weave or considered a reactive input.
** Scroll
Defines source code, its build dependencies and runtime environment.
Provides a default spell configuration.
Provides default upstream/downstream stitch decorators for outputs/inputs respectively.
Declares runtime compatibility (browser-only, non-browser, or universal).
** Shelf
Contains a collection of scrolls.
Provisions a shared runtime environment for spells based on these scrolls.
** Edition
Represents (a part of) the weave as a grimoire, a servitor, or a consistent collection of these.
** Grimoire
Presents a subweave as a program with human-facing interface.
Uses bridge spells to communicate with servitor-side ornaments within the same edition.
Has a dedicated interface ornament (entry point).
** Servitor
Presents a subweave as a local/remote daemon's/server's endpoints/methods.
** Loom
Provisions tools for interactive or programmatic weaving.

54
flake.lock generated
View file

@ -21,27 +21,27 @@
"type": "github"
}
},
"flake-utils": {
"flake-parts": {
"inputs": {
"systems": "systems"
"nixpkgs-lib": "nixpkgs-lib"
},
"locked": {
"lastModified": 1731533236,
"narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
"owner": "numtide",
"repo": "flake-utils",
"rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
"lastModified": 1754487366,
"narHash": "sha256-pHYj8gUBapuUzKV/kN/tR3Zvqc7o6gdFB9XKXIp1SQ8=",
"owner": "hercules-ci",
"repo": "flake-parts",
"rev": "af66ad14b28a127c5c0f3bbb298218fc63528a18",
"type": "github"
},
"original": {
"owner": "numtide",
"repo": "flake-utils",
"owner": "hercules-ci",
"repo": "flake-parts",
"type": "github"
}
},
"flake-utils_2": {
"flake-utils": {
"inputs": {
"systems": "systems_2"
"systems": "systems"
},
"locked": {
"lastModified": 1731533236,
@ -73,10 +73,25 @@
"type": "github"
}
},
"nixpkgs-lib": {
"locked": {
"lastModified": 1753579242,
"narHash": "sha256-zvaMGVn14/Zz8hnp4VWT9xVnhc8vuL3TStRqwk22biA=",
"owner": "nix-community",
"repo": "nixpkgs.lib",
"rev": "0f36c44e01a6129be94e3ade315a5883f0228a6e",
"type": "github"
},
"original": {
"owner": "nix-community",
"repo": "nixpkgs.lib",
"type": "github"
}
},
"root": {
"inputs": {
"deno-with-packages": "deno-with-packages",
"flake-utils": "flake-utils_2",
"flake-parts": "flake-parts",
"nixpkgs": "nixpkgs"
}
},
@ -94,21 +109,6 @@
"repo": "default",
"type": "github"
}
},
"systems_2": {
"locked": {
"lastModified": 1681028828,
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
"owner": "nix-systems",
"repo": "default",
"rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
"type": "github"
},
"original": {
"owner": "nix-systems",
"repo": "default",
"type": "github"
}
}
},
"root": "root",

46
flake.nix
View file

@ -3,32 +3,34 @@
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
flake-parts.url = "github:hercules-ci/flake-parts";
deno-with-packages.url = "github:voleum-org/deno-with-packages";
deno-with-packages.inputs.nixpkgs.follows = "nixpkgs";
};
outputs = { self, nixpkgs, flake-utils, deno-with-packages }:
flake-utils.lib.eachDefaultSystem (system:
let
pkgs = nixpkgs.legacyPackages.${system};
lib = import ./nix // deno-with-packages.lib.${system};
shelf = import ./shelf {
inherit pkgs system lib;
};
in
{
inherit lib;
outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } {
imports = [
];
systems = [ "x86_64-linux" ];
perSystem = { self', pkgs, config, system, ... }: let
lib = import ./nix // inputs.deno-with-packages.lib.${system};
shelf = import ./shelf {
inherit pkgs system lib;
};
in {
packages.website =
import ./nix/website.nix { inherit pkgs; root = ./.; };
devShells.default = pkgs.mkShell {
buildInputs = [ pkgs.deno ];
shellHook = ''
export DENO_DIR=$PWD/.deno_cache
${shelf.setupScript}/bin/install-deno-cache
devShells.default = pkgs.mkShell {
buildInputs = [ pkgs.deno pkgs.pandoc ];
shellHook = ''
export DENO_DIR=$PWD/.deno_cache
${shelf.setupScript}/bin/install-deno-cache
echo "Availabe scrolls:"
echo ${pkgs.lib.escapeShellArg (builtins.toJSON shelf.scrolls)} | jq .
'';
};
});
echo "Available scrolls:"
echo ${pkgs.lib.escapeShellArg (builtins.toJSON shelf.scrolls)} | jq .
'';
};
};
};
}

78
nix/website.nix Normal file
View file

@ -0,0 +1,78 @@
{ pkgs, root }:
pkgs.stdenv.mkDerivation {
name = "grimu-r-website";
src = pkgs.lib.cleanSourceWith {
src = root;
filter = path: type:
let
baseName = baseNameOf path;
relativePath = pkgs.lib.removePrefix (toString root + "/") (toString path);
in
baseName == "README.org" ||
relativePath == "website" ||
pkgs.lib.hasPrefix "website/" relativePath;
};
buildInputs = [ pkgs.pandoc ];
buildPhase = ''
cp $src/website/pandoc-template.html ./
mkdir -p ./html/doc
cp $src/website/favicon.ico ./html/
cp $src/website/llms.txt ./html/
if [ -d "$src/website/doc" ]; then
echo '<nav class="sidebar"><ul>' > docs-nav.html
for file in $(find $src/website/doc -name "*.org" -type f | sort); do
basename=$(basename "$file" .org)
title=$(grep -m1 -i "^#+TITLE:" "$file" | sed 's/^#+TITLE:[[:space:]]*//I' || echo "$basename")
echo "<li><a href=\"$basename.html\">$title</a></li>" >> docs-nav.html
done
echo '</ul></nav>' >> docs-nav.html
fi
if [ -d "$src/website/doc" ]; then
for file in $src/website/doc/*.org; do
basename=$(basename "$file" .org)
pandoc \
--template=./pandoc-template.html \
--include-before-body=./docs-nav.html \
--shift-heading-level-by=1 \
--section-divs \
-M document-css=false \
"$file" \
-o "./html/doc/$basename.html"
done
fi
pandoc \
--template=./pandoc-template.html \
--shift-heading-level-by=1 \
--section-divs \
-M document-css=false \
$src/README.org \
-o html/index.html
pandoc \
--template=./pandoc-template.html \
--shift-heading-level-by=1 \
--section-divs \
-M document-css=false \
$src/website/pitch.org \
-o html/pitch.html
'';
installPhase = ''
mkdir -p $out/html
mkdir -p $out/bin
cp -r ./html $out/
cat > $out/bin/grimu-r-website <<EOF
#!/usr/bin/env bash
${pkgs.python3}/bin/python3 -m http.server --directory "$out/html"
EOF
chmod +x $out/bin/grimu-r-website
'';
}

46
website/doc/glossary.org Normal file
View file

@ -0,0 +1,46 @@
#+title: Grimu-R glossary
* Weave
Defines a collection of braids.
Represented by files on disk.
* Braid
Has reactive inputs and outputs.
Serves as an externally invocable entry point.
Contains sigils and/or nested braid instances connected by strands.
Can be distributed within a schism aspect.
* Sigil
Has reactive inputs and outputs.
Atomic execution unit.
Cannot be directly invoked by an aspect consumer.
May have an inscription.
Created from a scroll and executed in the grimoire environment.
* Strand
Connects a reactive input to a compatible reactive output.
Can be cadence-decorated on both upstream and downstream ends.
May be parameterized by a reactive input, consuming variable assignments for the cadence decoration.
* Cadence
Defines reactive behavior.
May refer to variables defined by the reactive input.
* Inscription
Defines a script, a template or a configuration for a sigil to be executed with.
May be defined statically in the weave or considered a reactive input.
* Scroll
Defines source code, its build dependencies and runtime environment.
Provides a default sigil configuration.
Provides default upstream/downstream cadence decorators for outputs/inputs respectively.
Declares runtime compatibility (browser-only, non-browser, or universal).
* Grimoire
Complete environment required to execute (a part of) a weave.
* Schism
Splits the weave by grouping its braids into coherent collections of aspects.
* Aspect
Represents a collection of entire braids as an individual program.
Uses rifts to communicate with other aspects within the same schism.
* Rift
Acts as a proxy for a braid instance that was separated into a different aspect.
Enables strands to cross process and network boundaries.
* Binding
Provides a build strategy for a schism.
Maps an aspect to a specific build recipe producing an executable or a container.
* Loom
Provisions tools for interactive or programmatic weaving and execution.

35
website/doc/weaving_guide.org Normal file
View file

@ -0,0 +1,35 @@
#+title: Grimu-R lifecycle guide
* Project initialization
- create your flake
- add Grimu-R base as input
- define and enter a dev shell
* Interactive weaving
- open Loom editor in the browser
- create a braid
- add sigils to it from the scrolls palette
- connect them with strands
- edit sigil inscriptions
- execute sigils by clicking on their buttons
- adjust cadence decoration
* Modular weaving
- factor out braids
- define your own scrolls
- import external scrolls and weaves as flake inputs
- export yours as flake outputs
- call braids from other programs
* Deployment pipeline
- define a schism with aspects containing braids
- define a binding
- build executables / containers
* User-side weaving (malleability)
- add Loom to the binding definition
- deploy the executable
- open Loom editor in the browser
- persist edits in the browser
- rebase persisted edits on top of new versions released by devs
* Testing and test automation
- use Loom in the browser to run and inspect interactively
- define test data right in the weave as static sigils
- extract test data from the weave with Loom CLI
- execute braids with test inputs with Loom CLI

BIN
website/favicon.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 2.7 KiB

60
website/llms.txt Normal file
View file

@ -0,0 +1,60 @@
# Grimu-R
**Grimu-R** is an open-source framework for mixed visual-textual dataflow scripting, combining interactive web-based visual editing with polyglot scripting runtime.
## Core Concepts
**Weave**: A Git-friendly project representation containing the complete dataflow graph and layout
**Braid**: Reusable modules/entry points that can be nested and serve as CLI subcommands or RPC methods
**Sigil**: Basic building blocks - programs that act as data sources, sinks, or transformers
**Scroll**: Defines runtime environment and default configuration for sigils (developed with Nix)
**Inscription**: Dynamic scripts/templates stored in weaves, editable in the visual editor
**Strand**: Connects reactive inputs/outputs with configurable cadence decorators
**Schism/Aspect**: Splits weaves into deployable program collections
**Loom**: Interactive weaving and execution tools
## Key Features
- **Visual-textual editor**: Browser-based with immediate feedback and live code changes
- **Reactive dataflow**: Granular configuration for push/pull, throttling, batching, backpressure
- **Polyglot**: Real code blocks in familiar languages leveraging their ecosystems
- **Nix-powered**: Reproducible builds and environments with minimal setup effort
- **Malleable**: End users can inspect/modify dataflows using the same editor as developers
- **Embeddable**: Builds to CLI tools, RPC servers, web apps, or containers
- **Cross-language**: Structured data (JSON lines) connections between different runtimes
## Development Workflow
1. **Project setup**: Create Nix flake with Grimu-R base, enter dev shell
2. **Interactive weaving**: Use browser-based Loom editor to create braids, add sigils, connect with strands
3. **Modular development**: Factor out reusable braids, define custom scrolls, import/export as flake inputs/outputs
4. **Testing**: Run interactively in browser, define test data as static sigils, extract/execute via Loom CLI
5. **Deployment**: Define schisms with aspects, create bindings, build executables/containers
## Use Cases
- Rapid prototyping of data processing pipelines
- Self-hosted workflow automation
- Custom dashboards with complex logic
- Internal tooling and automation scripts
- Hacker-friendly, highly customizable applications
## Positioning
Takes the best from visual programming environments, script automation, and code notebooks while remaining developer-first. Avoids limitations of proprietary tools, brittleness of script bundles, and opacity of notebooks.
## Licensing
- **Platform components** (Loom tools, weave executors): AGPL v3
- **Base scrolls and non-platform code**: MIT
- AGPL applies to forks/extensions of platform code and SaaS deployments
- Your weaves and applications using Grimu-R are not affected by AGPL terms
## Technical Notes
- Development environment provisioned via Nix shell
- Visual editor communicates over WebSocket
- Changes stored in browser, exportable as files
- Cross-language via structured data pipes (like Unix pipes with JSON)
- Shared runtime dependencies managed by Nix
- Malleability limited to client-side parts in client-server applications

160
website/pandoc-template.html Normal file
View file

@ -0,0 +1,160 @@
<!DOCTYPE html>
<html$if(lang)$ lang="$lang$"$endif$>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
$if(title)$
<title>$title$</title>
$endif$
<style>
html {
display: flex;
}
body {
display: flex;
flex-direction: column;
align-items: center;
flex: 1;
background-color: ivory;
font-family: 'Courier New', Courier, monospace;
margin: 0;
}
header {
display: flex;
align-items: center;
width: 100%;
border-bottom: 1px solid #ddd;
min-height: 4em;
}
header > div {
flex: 1;
}
header > h1 {
text-align: center;
flex: 1;
margin: 10px;
}
.nav {
display: flex;
justify-content: center;
gap: 2em;
}
#content {
display: flex;
width: 100%;
}
.include-before {
flex: 1;
}
.content-body {
flex: 2;
}
@media (max-width: 1400px) {
header > h1, .nav {
flex: 10;
}
.content-body {
flex: 3;
}
}
@media (max-width: 1000px) {
header {
flex-direction: column;
padding-bottom: 10px;
}
}
@media (max-width: 700px) {
.content-body {
margin-left: 1em;
margin-right: 1em;
}
#content {
flex-direction: column;
}
}
#content>div:nth-of-type(3) {
flex: 1;
}
section.level2 > h2 {
border-left: 0.2em solid #3498db;
padding-left: 0.5em;
}
section.level3 > h3 {
margin-left: 1em;
}
section.level2 > p {
margin-left: 1em;
}
section.level3 > p {
margin-left: 2em;
}
section.level3 > ul {
margin-left: 1em;
}
section.level3 > ol {
margin-left: 2em;
}
li {
padding-left: 0.1em;
padding-bottom: 0.3em;
}
a:link {
color: #2E5EAA;
text-decoration: none;
}
a:visited {
color: #663399;
}
a:hover {
color: #1a4480;
text-decoration: underline;
}
</style>
</head>
<body>
<header>
<div></div>
<h1 class='title'>$title$</h1>
<div class="nav">
<a href='/index.html'>home</a>
<a href='/doc/glossary.html'>docs</a>
<a href='/pitch.html'>pitch deck</a>
<a href='/llms.txt'>llms</a>
</div>
</header>
<div id="content">
<div class="include-before">
$for(include-before)$
$include-before$
$endfor$
</div>
<div class="content-body">
$body$
</div>
<div></div>
</div>
</body>
</html>

53
website/pitch.org Normal file
View file

@ -0,0 +1,53 @@
#+title: Grimu-R pitch deck
* Key benefits
** Rapid prototyping
- Visual development and debugging
- Executed directly on dev's machine
- Immediate feedback
** Flexibility
- Not just workflows and dashboards -- anything
- Embed existing software into a Grimu-R project
- Embed a Grimu-R project itself into a larger flow
- No inherent deployment limitations, execute anywhere
** Clear evolution and hardening path
- Start with a visual, interactive prototype
- Decompose into components
- Add builds and deployments
- Call Grimu-R components from non Grimu-R components
- Automate testing
** Malleability
- Power users have the same superpowers as developers
- Can inspect, modify and extend available components in the visual editor
- Highly adaptable, customizable internal tooling
** No more "works on my machine"
- Reproducible environments and builds with Nix
- Every developer has the same tooling installed automatically
** Knowledge transfer
- Visual flow gives a clear overview and facilitates dev onboarding
- Execution graphs are self-documenting, serving both as code and a diagram for it
- Easier participation for less technical team members
** Reusable modules
- Base library components and integrations
- An open ecosystem of third-party utilities, open-source and commercial
- Develop and sell your own modules, or open source and get community support
** Free as in freedom
- The Grimu-R platform is open source, can be employed and extended freely
- Works on your machines, not in some cloud you don't control
* Caveats
** Bespoke reactive dataflow graphs and tooling
- Developers and power users need to get familiar with the mental model and tools
- General, intuitive concepts but still unorthodox
- Nifty and precise but alien jargon
** Nix
- Steep learning curve for developing your own components
- Hated by a huge % of devs
- There are limited ways to opt out
** Performance overhead
- Visual/textual scripts are fast to create, slow to execute
- Compiled binaries can be used at the cost of some convenience
- Deployable bundles are huge in volume
- No single "blessed" way to scale (yet)
** Copyleft licensing
- The platform can be extended, and contributions are welcome
- But your contributions must also be open source
- Only applies to the platform -- not components and modules!