llmp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8faca582b2fb9348ca7659a1e44a16c510ffb91d56381b077fd3b6887ec06ec1
+  data.tar.gz: 55dd40087e0e4a62f63a500d40a953ffe1c96c5e7dccc25b57afcc909f8c9dc2
+SHA512:
+  metadata.gz: cbb418e596938dbc053b6f6e36011ab6b091fe1791a039bb9c56427513bdde4dd3e2995822687835f6bd5c9ec2a7885280cc13cda5dad51ae9befbb2e6d9d389
+  data.tar.gz: dc3683e5a59f2dda7d380f2d3046bc70c12f626e0f24a52fc73b546e275d174c94a6f8edd3f0c50fd4f75fa2069099f01d396940676f003c00e02f40015c4731

data/README.md

@@ -0,0 +1,219 @@
+# llmpipe
+
+A Ruby-based CLI for building composable LLM workflows using the Unix pipe philosophy.
+
+## Overview
+
+`llmp` treats LLM prompts as Unix commands that can be chained together. Each pipe is defined by a YAML configuration file and communicates via standard input/output.
+
+```bash
+llmp summarize < article.txt | llmp translate > output.md
+```
+
+## Installation
+
+```bash
+gem install llmp
+```
+
+With Nix:
+
+```bash
+nix run github:pcboy/llmpipe -- <pipe_name_or_path> [args...] [options]
+```
+
+## Why llmp? You could just do `agent <<< 'my prompt'` and be done with it?
+
+Yes, you could just do `qwen <<< 'my prompt'` and call it a day. That works fine for one-offs.
+
+But you'll miss out on:
+
+- **Caching** : llmp responses are automatically cached by content hash. Same input = instant result, no API call.
+- **Single source of truth** : Prompts live in YAML files under one folder, can easily be version controlled
+- **Composability** : Chain pipes together like Unix commands, with each step reusable and testable.
+
+It's for sure nothing world-changing. It's just a nice way for me to work with quick LLMs operations from the command line.
+
+## Quick Start
+
+### 1. Configure RubyLLM
+
+Create `~/.config/llmp/config.yml`:
+
+```yaml
+# API key for your LLM provider
+openai_api_key: your-api-key
+
+# Custom endpoint (for Ollama, vLLM, LiteLLM, etc.)
+openai_api_base: http://localhost:11434/v1
+```
+
+Any configuration key supported by RubyLLM can be used here. The complete list of available options is documented at [rubyllm.com/configuration](https://rubyllm.com/configuration/).
+
+### 2. Create a Pipe
+
+Create for instance a `translate.yml` in your project directory, or globally at `$XDG_CONFIG_HOME/llmp/pipes/translate.yml`:
+
+```yaml
+provider: openai
+model: qwen3.5
+temperature: 0.6
+
+system_prompt: |
+  Detect the language of the input.
+  If it's English, translate to Japanese, otherwise translate to English.
+  Preserve the original formatting and tone.
+```
+
+### 3. Run the Pipeline
+
+```bash
+➜  echo "Hello, world" | llmp translate
+こんにちは、世界
+```
+
+## CLI Usage
+
+```bash
+llmp <pipe_name_or_path> [args...] [options]
+```
+
+### Arguments
+
+Pipe arguments are available in prompts as `$1`, `$2`, `$3`, etc., and `$*` for all arguments joined:
+
+```bash
+# $1 = "ruby", $2 = "performance"
+llmp review ruby performance < code.rb
+
+# $* = "security audit"
+llmp analyze "security audit" < code.rb
+```
+
+```yaml
+# In your YAML:
+system_prompt: |
+  Review this code for $1 issues.
+  Focus on: $2
+  All args: $*
+```
+
+### Options
+
+| Option          | Description                     |
+| --------------- | ------------------------------- |
+| `-f, --force`   | Bypass cache and force LLM call |
+| `-h, --help`    | Show help message               |
+| `-v, --version` | Print version                   |
+
+### Pipe Resolution
+
+When you run `llmp summarize`, the framework resolves the YAML file using this priority:
+
+1. **Direct path** — If argument contains `/` or ends with `.yml`/`.yaml`
+2. **Current directory** — Looks for `summarize.yml` or `summarize.yaml`
+3. **Environment variable** — Checks `$LLMP_PIPES_PATH/summarize.yml`
+4. **Global fallback** — XDG config directory (`$XDG_CONFIG_HOME/llmp/pipes/summarize.yml`)
+
+## Pipe Definition (YAML Schema)
+
+```yaml
+# Required: Provider and model
+provider: openai # or anthropic, google, etc.
+model: qwen3.5
+
+# Optional: Model parameters
+temperature: 0.7
+
+# Required: System prompt
+system_prompt: |
+  Find Job Title in the given JD
+```
+
+## Configuration
+
+### RubyLLM Configuration
+
+The configuration file is stored following the XDG Base Directory specification:
+
+- **Location**: `$XDG_CONFIG_HOME/llmp/config.yml` (defaults to `~/.config/llmp/config.yml`)
+
+All keys in this file are passed directly to `RubyLLM.configure`:
+
+```yaml
+# Authentication
+openai_api_key: your-api-key
+
+# Custom endpoints
+openai_api_base: http://localhost:11434/v1
+
+# Optional settings
+openai_organization: your-org-id
+openai_timeout: 30
+openai_extra_headers:
+  X-Custom-Header: value
+
+# Logging
+log_level: info
+log_errors: true
+```
+
+Any configuration key supported by RubyLLM can be used here. The complete list of available options is documented at [rubyllm.com/configuration](https://rubyllm.com/configuration/).
+
+## Examples
+
+### Basic Pipeline
+
+```bash
+# Do a code review on current branch, and apply the necessary changes
+git diff master | llmp code-review | qwen -y && \
+  git commit -a -m `git diff | llmp commit-message`
+```
+
+### Everything is cached
+
+```bash
+# First run - cache miss, calls LLM
+llmp summarize < input.txt
+
+# Second run - cache hit, instant result
+llmp summarize < input.txt
+
+# Force refresh - bypass cache
+llmp summarize --force < input.txt
+```
+
+### Custom Pipe Path
+
+```bash
+# Use pipe from current directory (my_pipe.yml)
+llmp my_pipe
+
+# Use pipe from specific path
+llmp ./pipes/custom.yml
+
+# Use pipe from global config directory
+llmp translate  # resolves to ~/.config/llmp/translate.yml
+```
+
+## Caching
+
+`llmp` automatically caches LLM responses to save time and API costs.
+
+- **Cache key**: SHA256 hash of (YAML content + input data)
+- **Cache location**: `.llmp/cache/`
+- **Cache invalidation**: Automatic when YAML or input changes
+- **Bypass cache**: Use `--force` flag
+
+Cache storage: `$XDG_CACHE_HOME/llmp/` (defaults to `~/.cache/llmp/`)
+Config files: `$XDG_CONFIG_HOME/llmp/` (defaults to `~/.config/llmp/`)
+
+## Environment Variables
+
+| Variable          | Description                          |
+| ----------------- | ------------------------------------ |
+| `LLMP_PIPES_PATH` | Custom directory for pipe YAML files |
+
+## License
+
+MIT

data/bin/llmp

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/llmp'
+
+begin
+  opts = Llmp::Cli.parse(ARGV)
+
+  unless opts[:pipe_path]
+    warn "Error: Pipe '#{opts[:pipe]}' not found"
+    exit 1
+  end
+
+  pipe = Llmp::Pipe.new(opts[:pipe_path], args: opts[:args])
+  input_data = $stdin.read
+
+  result = pipe.execute(input_data, force: opts[:force])
+  $stdout.write(result)
+rescue StandardError => e
+  warn "Error: #{e.message}"
+  warn e.backtrace.first(5) if ENV['LLMP_DEBUG']
+  exit 1
+end

data/lib/llmp/cache.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+require 'runcom'
+
+module Llmp
+  class Cache
+    def initialize
+      @cache = Runcom::Cache.new('llmp')
+      @cache_dir = @cache.passive.to_s
+      FileUtils.mkdir_p(@cache_dir)
+    end
+
+    def key_for(yaml_content, input_data)
+      Digest::SHA256.hexdigest(yaml_content + input_data)
+    end
+
+    def cache_path(key)
+      File.join(@cache_dir, "#{key}.json")
+    end
+
+    def lock_path(key)
+      File.join(@cache_dir, "#{key}.lock")
+    end
+
+    def fetch(yaml_content, input_data, force: false)
+      key = key_for(yaml_content, input_data)
+      path = cache_path(key)
+      lock_file = lock_path(key)
+
+      File.open(lock_file, File::CREAT | File::RDWR) do |lf|
+        lf.flock(File::LOCK_EX)
+
+        # Check cache only if not forced
+        if !force && File.exist?(path)
+          cached = JSON.parse(File.read(path), symbolize_names: true)
+          return cached[:output]
+        end
+
+        # Cache miss or forced - compute and store atomically
+        output = yield
+        File.write(path, JSON.pretty_generate({ output: }))
+        output
+      end
+    end
+  end
+end

data/lib/llmp/cli.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'optimist'
+require 'fileutils'
+require 'runcom'
+
+module Llmp
+  class Cli
+    def self.parse(argv = ARGV)
+      opts = build_options(argv)
+
+      positional = argv.reject { |arg| arg.start_with?('-') }
+      if positional.empty? || opts[:help]
+        build_options(['--help'])
+        exit 1
+      end
+
+      opts[:pipe] = positional.first
+      opts[:pipe_path] = resolve_pipe_path(positional.first)
+      opts[:args] = positional.drop(1)
+
+      opts
+    end
+
+    def self.build_options(argv)
+      Optimist.options(argv) do
+        version 'Llmp v0.1.0'
+        banner <<~BANNER
+
+          Usage: llmp <pipe_name_or_path> [args...] [options]
+
+          A Ruby-based CLI framework for composable LLM workflows using Unix pipe philosophy.
+
+          Pipe arguments are available in prompts as $1, $2, $3, etc. and $* for all arguments.
+
+          Examples:
+            llmp summarize < url.txt
+            llmp ./pipes/custom.yml < url.txt
+            llmp translate -f < data.txt
+            llmp review ruby -- -Wno-unused-variable < code.rb
+        BANNER
+
+        opt :force, 'Bypass cache and force LLM call', type: :boolean, default: nil, short: 'f'
+        opt :help, 'Show this message', type: :boolean, default: nil, short: 'h'
+      end
+    end
+
+    def self.resolve_pipe_path(pipe_arg)
+      return pipe_arg if pipe_arg.include?('/') || pipe_arg.end_with?('.yml', '.yaml')
+
+      paths_to_try = [
+        cwd_path(pipe_arg),
+        env_var_path(pipe_arg),
+        global_path(pipe_arg)
+      ].compact
+
+      paths_to_try.each do |path|
+        return path if File.exist?(path)
+      end
+
+      nil
+    end
+
+    def self.cwd_path(pipe_arg)
+      base_name = pipe_arg.end_with?('.yml', '.yaml') ? pipe_arg : "#{pipe_arg}.yml"
+      File.expand_path(base_name)
+    end
+
+    def self.env_var_path(pipe_arg)
+      env_path = ENV['LLMP_PIPES_PATH']
+      return nil if env_path.nil? || env_path.empty?
+
+      base_name = pipe_arg.end_with?('.yml', '.yaml') ? pipe_arg : "#{pipe_arg}.yml"
+      File.expand_path(base_name, env_path)
+    end
+
+    def self.global_path(pipe_arg)
+      config = Runcom::Config.new("llmp/pipes/#{pipe_arg}")
+      base_name = pipe_arg.end_with?('.yml', '.yaml') ? pipe_arg : "#{pipe_arg}.yml"
+      config_path = config.active || config.passive
+      File.join(File.dirname(config_path.to_s), base_name)
+    end
+  end
+end

data/lib/llmp/config.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+require 'runcom'
+
+module Llmp
+  class Config
+    def self.load(path: nil)
+      if path
+        config_path = path
+      else
+        config = Runcom::Config.new('llmp/config.yml')
+        config_path = config.active || config.passive
+      end
+
+      return {} unless config_path
+      return {} unless File.exist?(config_path)
+
+      YAML.safe_load(File.read(config_path.to_s)) || {}
+    rescue Psych::SyntaxError => e
+      warn "Warning: Invalid YAML in #{config_path}: #{e.message}"
+      {}
+    end
+  end
+end

data/lib/llmp/pipe.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+require 'ruby_llm'
+require_relative 'cache'
+require_relative 'config'
+
+module Llmp
+  class Pipe
+    REQUIRED_FIELDS = %w[provider model system_prompt].freeze
+    attr_reader :config, :yaml_content
+
+    def initialize(yaml_path, args: [], cache: nil)
+      @yaml_path = yaml_path
+      @args = args
+      @yaml_content = File.read(yaml_path)
+      @config = YAML.safe_load(substitute_args(@yaml_content))
+
+      missing = REQUIRED_FIELDS.reject { |f| @config.key?(f) }
+      raise "Missing required fields: #{missing.join(', ')}" unless missing.empty?
+
+      @cache = cache || Cache.new
+      @input_data = nil
+    end
+
+    def execute(input_data, force: false)
+      @input_data = input_data
+
+      configure
+
+      @cache.fetch(@yaml_content, @input_data, force: force) do
+        call_llm
+      end
+    end
+
+    private
+
+    def substitute_args(content)
+      return content if @args.empty?
+
+      result = content
+
+      # Replace $* with all arguments joined by space (YAML-escaped)
+      result = result.gsub('$*', escape_yaml_value(@args.join(' ')))
+
+      # Replace $1, $2, $3, etc. with corresponding arguments (YAML-escaped)
+      @args.each_with_index do |arg, index|
+        result = result.gsub("$#{index + 1}", escape_yaml_value(arg))
+      end
+
+      result
+    end
+
+    def escape_yaml_value(value)
+      YAML.dump(value).gsub(/^--- /, '').strip
+    end
+
+    def configure
+      user_config = Config.load
+
+      RubyLLM.configure do |config|
+        user_config.each do |key, value|
+          config.send("#{key}=", value) if config.respond_to?("#{key}=")
+        end
+      end
+    end
+
+    def call_llm
+      provider = @config['provider']
+      model = @config['model']
+      temperature = @config['temperature'] || 0.6
+      system_prompt = @config['system_prompt']
+
+      chat = RubyLLM.chat(model: model, provider: provider, assume_model_exists: true)
+      chat.with_temperature(temperature)
+      chat.with_instructions(system_prompt)
+      response = chat.ask(@input_data)
+
+      response.content
+    end
+  end
+end

data/lib/llmp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Llmp
+  VERSION = '0.1.0'
+end

data/lib/llmp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'llmp/version'
+require_relative 'llmp/config'
+require_relative 'llmp/cache'
+require_relative 'llmp/pipe'
+require_relative 'llmp/cli'
+
+module Llmp
+end

data/llmp.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/llmp/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'llmp'
+  spec.version       = Llmp::VERSION
+  spec.authors       = ['David Hagege']
+  spec.email         = ['david@joynetiks.com']
+
+  spec.summary       = 'A Ruby-based CLI for composable LLM workflows'
+  spec.description   = <<~EOL
+    Build composable LLM workflows using Unix pipe philosophy.
+    Each pipe is a YAML-configured LLM call that communicates via stdin/stdout.
+  EOL
+  spec.homepage      = 'https://github.com/pcboy/llmpipe'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  spec.files = Dir.glob('lib/**/*') + Dir.glob('bin/*') + %w[README.md llmp.gemspec]
+
+  spec.bindir        = 'bin'
+  spec.executables   = ['llmp']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'json', '~> 2.0'
+  spec.add_dependency 'optimist', '~> 3.0'
+  spec.add_dependency 'ruby_llm', '~> 1.16'
+  spec.add_dependency 'runcom', '~> 12.3'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'ruby_llm-test', '~> 0.2'
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: llmp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Hagege
+bindir: bin
+cert_chain: []
+date: 1980-01-01 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'
+- !ruby/object:Gem::Dependency
+  name: optimist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: runcom
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: |
+  Build composable LLM workflows using Unix pipe philosophy.
+  Each pipe is a YAML-configured LLM call that communicates via stdin/stdout.
+email:
+- david@joynetiks.com
+executables:
+- llmp
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/llmp
+- lib/llmp.rb
+- lib/llmp/cache.rb
+- lib/llmp/cli.rb
+- lib/llmp/config.rb
+- lib/llmp/pipe.rb
+- lib/llmp/version.rb
+- llmp.gemspec
+homepage: https://github.com/pcboy/llmpipe
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pcboy/llmpipe
+  source_code_uri: https://github.com/pcboy/llmpipe
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: A Ruby-based CLI for composable LLM workflows
+test_files: []