ruby_pymill 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c88e00a96d006073f8007aa6395eea1ecb5ccecf530430e9e73b288cb1df18d
+  data.tar.gz: da982b4b979d75075f5d1ce914feb8e79f0844441f18f4d1f2dd2b34e4502517
+SHA512:
+  metadata.gz: bdb19766137d960b14a59513b522e65ea11147c940e708969a7a63a19500920c4880d341bcdb694eed013a8f92a6eaaee546cefd6d293d9fb6cf77ab620eabec
+  data.tar.gz: 7d263d39baae7f1055134014f2a6babeb76a931ac3bf51b6bcb47cc053770ec224e6d71701abc337e8647a9ecf08124dba30e1f49d4ac35be68a51f6c116b416

data/LICENSE

@@ -0,0 +1,12 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

data/README.md

@@ -0,0 +1,106 @@
+# RubyPyMill
+Running Notebooks the Ruby Way — RubyPyMill and the Art of PoC Automation
+
+## Background and Purpose
+RubyPyMill is a lightweight runner and automation starter that allows Ruby
+to control Papermill (a Python Notebook runner).
+
+Its purpose is to bridge insights born from Proof of Concept (PoC) work
+into real-world systems.
+
+PoC is not the end — it is the beginning of organizational knowledge circulation.
+
+By connecting Ruby’s expressive power with Python’s execution ecosystem,
+RubyPyMill enables a development cycle where teams collaborate with data
+in a Ruby-native way.
+
+## Design Philosophy — Inspired by Ruby 4.0 @30
+RubyPyMill follows Ruby 4.0’s philosophy of “multi-language collaboration”.
+
+- Ruby is responsible for DSLs, orchestration, and control.
+- Python is responsible for execution, computation, and visualization via notebooks.
+
+By clearly separating these roles and bridging them automatically,
+RubyPyMill enables reproducible notebook execution from the Ruby ecosystem.
+
+“Ruby aims to connect people with people, and tools with tools.”  
+— Yukihiro “Matz” Matsumoto
+
+## Project Structure
+| Directory | Description |
+|----------|-------------|
+| .vscode/ | VS Code settings (extensions, lint/format, tasks, debug) |
+| .github/workflows/ | CI for Ruby and Python |
+| bin/ | CLI entry point (`ruby_pymill`) |
+| lib/ | RubyPyMill core library |
+| py/ | Python-side environment (Papermill execution) |
+| examples/ | Example notebooks, parameters, and outputs |
+
+## Setup
+
+### Ruby
+```bash
+bundle install
+```
+
+### Python
+```bash
+python -m venv .venv
+
+# macOS / Linux
+source .venv/bin/activate
+
+# Windows (PowerShell)
+.\.venv\Scripts\activate
+
+pip install -r py/requirements.txt
+python -m ipykernel install --user --name rpymill
+```
+
+## Basic Usage (CLI)
+```bash
+bundle exec ruby bin/ruby_pymill exec <input.ipynb> \
+  --output <output.ipynb> \
+  [--kernel rpymill] \
+  [--params params.json] \
+  [--cell_tags "parameters,setup,analysis"] \
+  [--dry-run]
+```
+
+## Processing Overview
+1. Load the notebook as JSON.
+2. Filter cells by specified tags (the `parameters` cell is always preserved).
+3. Generate a temporary filtered notebook.
+4. Execute the filtered notebook once using Papermill.
+5. Save the executed result as an output notebook.
+
+RubyPyMill acts as a higher-level orchestration layer on top of Papermill,
+ensuring logical structure, reproducibility, and Ruby-friendly control.
+
+## Example: Ruby vs Python Radar Chart
+The `examples/` directory includes a notebook that compares Ruby and Python strengths
+using a radar chart.
+
+This example demonstrates:
+- Parameter injection via JSON
+- Tag-based execution control
+- Separation of preview and output generation
+- Reproducible notebook execution via RubyPyMill
+
+For a detailed explanation in Japanese, see `README.jp.md`.
+
+## Programmatic Usage (Experimental)
+RubyPyMill is primarily designed as a CLI tool.
+
+Internally, it exposes a Ruby execution API (`RubyPyMill::API`),
+which allows direct invocation from Ruby code.
+
+This enables integration with batch jobs, schedulers,
+or future web APIs.
+
+The CLI is considered the stable interface.
+The Ruby API is experimental and may change.
+
+## License
+MIT License  
+Copyright (c) 2025 Hiroshi Inoue / OSS-Vision

data/bin/ruby_pymill

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# lib/ を読み込みパスに追加
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "thor"
+require "ruby_pymill"
+require "shellwords"
+
+class RubyPyMillCLI < Thor
+  # Thor の予約語 run を避ける。ユーザーが `run` と打っても :exec に転送
+  map "run" => :exec
+
+  desc "exec INPUT_IPYNB", "Run papermill with Ruby wrapper"
+  method_option :output,   type: :string, aliases: "-o", required: true, desc: "Output notebook path"
+  method_option :kernel,   type: :string, default: "python3",            desc: "Jupyter kernel name"
+  method_option :params,   type: :string,                                 desc: "Path to params.json or JSON string"
+  method_option :cwd,      type: :string,                                 desc: "Working directory"
+  method_option :dry_run,  type: :boolean, default: false,                desc: "Print command only"
+  # ★ 追加: タグ実行
+  method_option :cell_tag,  type: :string,                                desc: "Execute only cells with this tag (Papermill --cell_tag)"
+  method_option :cell_tags, type: :array,                                 desc:  "Execute only cells with these tags (space/comma-separated)"
+  
+  def exec(input_ipynb)
+  #  runner = RubyPyMill::Runner.new(kernel: options[:kernel], cwd: options[:cwd])
+    # --cell-tag / --cell-tags を正規化（nil/空/カンマを吸収）
+    tags = []
+    tags << options[:cell_tag] if options[:cell_tag]
+    tags.concat(options[:cell_tags]) if options[:cell_tags]
+    cell_tags = tags.compact.flat_map { |t| t.to_s.split(",") }.map(&:strip).reject(&:empty?)
+
+    runner = RubyPyMill::Runner.new(
+      kernel: options[:kernel],
+      cwd:    options[:cwd],
+      cell_tags: cell_tags
+    )
+    ok = runner.run(
+      input_ipynb:  input_ipynb,
+      output_ipynb: options[:output],
+      params_json:  options[:params],
+      dry_run:      options[:dry_run]
+    )
+    exit(ok ? 0 : 1)
+  end
+
+  desc "version", "Show RubyPyMill version"
+  def version
+    puts RubyPyMill::VERSION
+  end
+
+end
+
+RubyPyMillCLI.start(ARGV)

data/lib/ruby_pymill/api.rb

@@ -0,0 +1,59 @@
+# lib/ruby_pymill/api.rb
+require "open3"
+
+module RubyPyMill
+  module API
+    # Ruby から notebook を実行する公式API
+    #
+    # 例:
+    #   RubyPyMill::API.run(
+    #     notebook: "demo/notebooks/xxx.ipynb",
+    #     output:   "demo/outputs/out.ipynb",
+    #     kernel:   "rpymill",
+    #     cell_tags:"setup,preprocess,report",
+    #     params:   "demo/params/kodama.json",
+    #     log:      "demo/logs/run_xxx.log"
+    #   )
+    #
+    def self.run(
+      notebook:,
+      output:,
+      kernel: "rpymill",
+      cell_tags: nil,
+      params: nil,
+      log: nil
+    )
+      cmd = [
+        "ruby_pymill", "exec",
+        notebook,
+        "--output", output,
+        "--kernel", kernel,
+      ]
+      cmd += ["--cell-tag", cell_tags] if cell_tags && !cell_tags.empty?
+      cmd += ["--params", params]      if params && !params.empty?
+
+      stdout_all = +""
+      status = nil
+
+      Open3.popen2e(*cmd) do |_stdin, stdout_err, wait_thr|
+        stdout_err.each do |line|
+          print line          # コンソールにも流す
+          stdout_all << line  # ログにも残す
+        end
+        status = wait_thr.value
+      end
+
+      if log
+        log_dir = File.dirname(log)
+        Dir.mkdir(log_dir) unless Dir.exist?(log_dir)
+        File.write(log, stdout_all)
+      end
+
+      unless status&.success?
+        raise "ruby_pymill failed (status=#{status.exitstatus})"
+      end
+
+      stdout_all
+    end
+  end
+end

data/lib/ruby_pymill/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module RubyPyMill
+  VERSION = "0.2.0"
+end

data/lib/ruby_pymill.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "ruby_pymill/version"
+require_relative "ruby_pymill/api"
+require "json"
+require "open3"
+require "tmpdir"
+
+module RubyPyMill
+  class Runner
+    def initialize(kernel: "rpymill", cwd: nil, logger: $stdout, cell_tags: [])
+      @kernel    = kernel
+      @cwd       = cwd
+      @logger    = logger
+      @cell_tags = normalize_tags(cell_tags)  # ← 文字列/配列どちらでもOKに
+    end
+
+    # params_json: path to json file or JSON string
+    # cell_tags  : initialize の指定を上書き可能（カンマ/空白区切り文字列 or 配列）
+    def run(input_ipynb:, output_ipynb:, params_json: nil, kernel: nil, dry_run: false, cell_tags: nil)
+      k    = kernel || @kernel
+      tags = normalize_tags(cell_tags.nil? ? @cell_tags : cell_tags)  # ← 正規化して複数タグ対応
+
+      # 1) タグ指定があればノートを事前フィルタ
+      filtered_input = tags.empty? ? input_ipynb : filter_by_tags(input_ipynb, tags)
+
+      # 2) papermill コマンドを組み立て
+      args = ["papermill", filtered_input, output_ipynb, "-k", k]
+
+      if params_json
+        if File.exist?(params_json)
+          args += ["-f", params_json]
+        else
+          tmpdir = Dir.mktmpdir("rpymill_params")
+          tmp    = File.join(tmpdir, "params.json")
+          File.write(tmp, params_json)
+          args += ["-f", tmp]
+        end
+      end
+
+      cmd = args.join(" ")
+      @logger.puts "[RubyPyMill] #{dry_run ? 'DRY' : 'RUN'}: #{cmd}"
+      return true if dry_run
+
+      stdout_str, stderr_str, status = Open3.capture3(cmd, chdir: @cwd || Dir.pwd)
+      @logger.puts stdout_str unless stdout_str.empty?
+      @logger.puts stderr_str unless stderr_str.empty?
+      status.success?
+    end
+
+    private
+
+    # "preprocess, analysis" / "preprocess analysis" / ["preprocess","analysis"] いずれもOKに
+    def normalize_tags(value)
+      Array(value)
+        .flat_map { |v| v.to_s.split(/[,\s]+/) }
+        .map(&:strip)
+        .reject(&:empty?)
+        .uniq
+    end
+
+    # 指定タグ OR マッチ。parameters / injected-parameters は常に残す
+    def filter_by_tags(ipynb_path, tags)
+      data  = JSON.parse(File.read(ipynb_path))
+      cells = data["cells"] || []
+
+      kept = cells.select do |cell|
+        ctags = Array(cell.dig("metadata", "tags")).map(&:to_s)
+        (ctags & %w[parameters injected-parameters]).any? || (ctags & tags).any?
+      end
+
+      # 万一ゼロ件なら parameters 系のみ確保
+      if kept.empty?
+        kept = cells.select { |c| (Array(c.dig("metadata", "tags")) & %w[parameters injected-parameters]).any? }
+      end
+
+      filtered = data.dup
+      filtered["cells"] = kept
+
+      tmpdir = Dir.mktmpdir("rpymill_nb")
+      tmpnb  = File.join(tmpdir, File.basename(ipynb_path, ".ipynb") + ".filtered.ipynb")
+      File.write(tmpnb, JSON.pretty_generate(filtered))
+      tmpnb
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: ruby_pymill
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Hiroshi Inoue
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Ruby orchestrator to filter/execute tagged Jupyter cells via Papermill.
+email:
+- hiroshi.inoue@gmail.com
+executables:
+- ruby_pymill
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/ruby_pymill
+- lib/ruby_pymill.rb
+- lib/ruby_pymill/api.rb
+- lib/ruby_pymill/version.rb
+homepage: https://github.com/inoue-0852/RubyPyMill
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Run Jupyter Notebooks from Ruby using Papermill
+test_files: []