appydave-tools 0.81.0 → 0.83.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09f48a7490c924291dff958e3df8ba53c28c2dae599cae0ab8581ac3e4ad3ee2'
-  data.tar.gz: f1e55198dd31bb3b2b61b61d4f929fc3bda799ecd4cedb96e5f810c994edae4a
+  metadata.gz: 7b1472f59045694d5411b4112d3c66c04dfa724197ff9a6caa6fe8dde4437a6a
+  data.tar.gz: 9088a3cc358367481e06602912df404694af78d5271d2b90458e08ee63dc272c
 SHA512:
-  metadata.gz: 9d4f2bc474af95d2ff538d5360d9ec659b559f155b611c9b7c13f9c475118311a1fc99a40b1f3fc6655b20bee568a3c5fcb4466f709eef948cd400d4efee6709
-  data.tar.gz: 84af7abbcc284e85742f1db64737622e8c929b57815988908a2aba716d970adcfd0f52e29f7a432fb2d544fd8be950fd27254d7ec61fdf705802c126b34e6d84
+  metadata.gz: 9dd76f56f7e9886dbd88b8ab9a2a4e026abd1ddaad935046c61a9fc7a9b72cbf316edb8fcb3d81889a55833cca273c3e09abee6d066bad035b7337afa823aab5
+  data.tar.gz: 1c32c5827d8b838d9c4f723ecfc0c4695c6d5189fc0f19401b365ca9c9888f3e57de8a167fdc9ba67edb4dc56d3519207e19df95c3382f9f7d50b3af5eef85c7

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [0.82.0](https://github.com/appydave/appydave-tools/compare/v0.81.0...v0.82.0) (2026-04-04)
+
+
+### Features
+
+* add random_context tool — randomly surfaces brain/OMI content for discovery; config at ~/.config/appydave/random-queries.yml bootstrapped from bundled seed ([1a98813](https://github.com/appydave/appydave-tools/commit/1a98813951283db7e777b3e7d6a48d60aaa840ad))
+
+# [0.81.0](https://github.com/appydave/appydave-tools/compare/v0.80.0...v0.81.0) (2026-04-04)
+
+
+### Bug Fixes
+
+* 'cops' ([7378a1e](https://github.com/appydave/appydave-tools/commit/7378a1e86e7658eb31924254390abfd967f915ae))
+
+
+### Features
+
+* add --meta flag to query_brain and query_omi returning rich JSON metadata instead of file paths ([3320c5d](https://github.com/appydave/appydave-tools/commit/3320c5dac93ad60591a82e255b5d45ff53396d1d))
+* simplify query_brain and query_omi APIs with unified --find, --active, --days, --limit flags ([12c80e6](https://github.com/appydave/appydave-tools/commit/12c80e6dcee4bb6bbe801985bf75aaeb897f57b9))
+
 # [0.80.0](https://github.com/appydave/appydave-tools/compare/v0.79.0...v0.80.0) (2026-04-03)
 
 

data/bin/llm_context.rb

@@ -81,6 +81,16 @@ def setup_options(opts, options)
     options.show_tokens = true
   end
 
+  opts.on('-s', '--smart', 'Auto-route: clipboard if ≤ threshold tokens, else temp file',
+          'Mutually exclusive with explicit -o clipboard or -o temp') do
+    options.smart = true
+  end
+
+  opts.on('--smart-limit N', Integer,
+          'Token threshold for --smart (default: 100000)') do |n|
+    options.smart_limit = n
+  end
+
   opts.on('--stdin', 'Read file paths from stdin (one per line) instead of using patterns') do
     options.stdin = true
   end
@@ -99,6 +109,7 @@ def setup_help_sections(opts)
   opts.separator '    clipboard - Copy to system clipboard (default)'
   opts.separator '    temp      - Write to system temp dir, copy path to clipboard'
   opts.separator '    filename  - Write to specified file path'
+  opts.separator '    --smart   - Auto-route: clipboard if ≤ 100k tokens, else temp file'
   opts.separator ''
   opts.separator 'INPUT MODES'
   opts.separator '    Patterns (default): -i <glob> and -e <exclude_glob>'
@@ -165,7 +176,12 @@ if options.include_patterns.empty? && options.exclude_patterns.empty? && options
   exit
 end
 
-if options.output_target.empty?
+if options.smart && (options.output_target & %w[clipboard temp]).any?
+  warn 'Error: --smart (-s) cannot be combined with explicit -o clipboard or -o temp'
+  exit 1
+end
+
+if options.output_target.empty? && !options.smart
   puts 'No output target provided. Will default to `clipboard`. You can set the output target using -o'
   options.output_target << 'clipboard'
 end

data/bin/random_context.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'appydave/tools'
+require 'optparse'
+
+options = { meta: false, config: nil }
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: random_context [options]'
+
+  opts.on('--meta', 'Return metadata as JSON instead of file paths') do
+    options[:meta] = true
+  end
+
+  opts.on('--config PATH', 'Path to custom random-queries.yml config') do |path|
+    options[:config] = path
+  end
+
+  opts.on('-v', '--version', 'Show version') do
+    puts "random_context v#{Appydave::Tools::VERSION}"
+    exit 0
+  end
+
+  opts.on('-h', '--help', 'Show this message') do
+    puts opts
+    exit 0
+  end
+end.parse!
+
+randomizer_opts = { meta: options[:meta] }
+randomizer_opts[:config_path] = options[:config] if options[:config]
+
+Appydave::Tools::RandomContext::Randomizer.new(**randomizer_opts).run
+
+exit 0

data/config/random-queries.yml

@@ -0,0 +1,104 @@
+# Random context discovery queries
+# Each entry runs a query tool command and checks result count.
+# Entries with result counts in [min_results, max_results] are eligible for random selection.
+#
+# Format:
+#   label:       Natural language question shown to the user
+#   command:     Shell command to run (query_brain or query_omi)
+#   min_results: Minimum results to be considered a "good" match (default: 1)
+#   max_results: Maximum results to be considered a "good" match (default: 15)
+#
+# The OMI skill can extend this file by appending new entries under queries:.
+
+queries:
+  # --- Brain queries ---
+  - label: "What do I know about paperclip?"
+    command: "query_brain --find paperclip"
+    min_results: 1
+    max_results: 20
+
+  - label: "What do I know about OMI?"
+    command: "query_brain --find omi"
+    min_results: 1
+    max_results: 20
+
+  - label: "What do I know about BMAD method?"
+    command: "query_brain --find bmad"
+    min_results: 1
+    max_results: 20
+
+  - label: "What do I know about agentic engineering?"
+    command: "query_brain --find agentic-engineering"
+    min_results: 1
+    max_results: 30
+
+  - label: "What are my active high-priority brains?"
+    command: "query_brain --active"
+    min_results: 5
+    max_results: 50
+
+  - label: "What do I know about Claude / Anthropic?"
+    command: "query_brain --find anthropic"
+    min_results: 1
+    max_results: 20
+
+  - label: "Browse my agent systems knowledge"
+    command: "query_brain --category agent-systems"
+    min_results: 1
+    max_results: 30
+
+  - label: "Browse my agent frameworks knowledge"
+    command: "query_brain --category agent-frameworks"
+    min_results: 1
+    max_results: 30
+
+  - label: "What do I know about context engineering?"
+    command: "query_brain --find context-engineering"
+    min_results: 1
+    max_results: 20
+
+  - label: "What do I know about FliVideo?"
+    command: "query_brain --find flivideo"
+    min_results: 1
+    max_results: 20
+
+  # --- OMI queries ---
+  - label: "Recent things I learned (TIL)"
+    command: "query_omi --routing til --limit 5"
+    min_results: 1
+    max_results: 5
+
+  - label: "One brain-update session to process"
+    command: "query_omi --routing brain-update --limit 1"
+    min_results: 1
+    max_results: 1
+
+  - label: "Recent brain-update sessions"
+    command: "query_omi --routing brain-update --limit 5"
+    min_results: 1
+    max_results: 5
+
+  - label: "What todo items came up recently?"
+    command: "query_omi --routing todo-item --days 14"
+    min_results: 1
+    max_results: 10
+
+  - label: "Recent OMI conversations about paperclip"
+    command: "query_omi --brain paperclip --limit 3"
+    min_results: 1
+    max_results: 3
+
+  - label: "Recent OMI conversations about BMAD"
+    command: "query_omi --brain bmad --limit 3"
+    min_results: 1
+    max_results: 3
+
+  - label: "What was I planning recently?"
+    command: "query_omi --activity planning --days 14 --limit 5"
+    min_results: 1
+    max_results: 5
+
+  - label: "What was I learning recently?"
+    command: "query_omi --activity learning --days 14 --limit 5"
+    min_results: 1
+    max_results: 5

data/docs/guides/query-tools.md

@@ -25,12 +25,12 @@ The tools are **composable**: query tools select files, `llm_context` loads them
 ## What Is Being Queried
 
 ### query_brain
-Reads `~/dev/ad/brains/audit/brains-index.json` — a pre-built index of all brain folders. Does **not** scan brain files at query time. The index contains per-brain metadata: name, category, activity_level, tags, status, file_count.
+Reads `/Users/davidcruwys/dev/ad/brains/audit/brains-index.json` — a pre-built index of all brain folders. Does **not** scan brain files at query time. The index contains per-brain metadata: name, category, activity_level, tags, status, file_count.
 
-Brain folders live at `~/dev/ad/brains/<brain-name>/`. Each has an `INDEX.md` and optional content files.
+Brain folders live at `/Users/davidcruwys/dev/ad/brains/<brain-name>/`. Each has an `INDEX.md` and optional content files.
 
 ### query_omi
-Scans `~/dev/raw-intake/omi/*.md` and reads YAML frontmatter from each file. Enriched files (processed by Gemini extraction) have rich frontmatter. Raw files (unprocessed transcripts) have minimal frontmatter. Default behaviour: **enriched files only**.
+Scans `/Users/davidcruwys/dev/raw-intake/omi/*.md` and reads YAML frontmatter from each file. Enriched files (processed by Gemini extraction) have rich frontmatter. Raw files (unprocessed transcripts) have minimal frontmatter. Default behaviour: **enriched files only**.
 
 ### llm_context
 Takes file paths (from stdin or arguments) and assembles content for LLM consumption. Two formats: `tree` (file listing) and `content` (file listing + full file content).

data/lib/appydave/tools/llm_context/options.rb

@@ -16,6 +16,8 @@ module Appydave
         :show_tokens,
         :file_paths,
         :stdin,
+        :smart,
+        :smart_limit,
         keyword_init: true
       ) do
         def initialize(**args)
@@ -29,6 +31,8 @@ module Appydave
           self.show_tokens ||= false
           self.file_paths ||= []
           self.stdin ||= false
+          self.smart ||= false
+          self.smart_limit ||= 100_000
         end
       end
     end

data/lib/appydave/tools/llm_context/output_handler.rb

@@ -9,18 +9,15 @@ module Appydave
           @content = content
           @output_targets = options.output_target
           @working_directory = options.working_directory
+          @smart = options.smart
+          @smart_limit = options.smart_limit
         end
 
         def execute
-          @output_targets.each do |target|
-            case target
-            when 'clipboard'
-              Clipboard.copy(@content)
-            when 'temp'
-              write_to_temp
-            when /^.+$/
-              write_to_file(target)
-            end
+          if @smart
+            execute_smart
+          else
+            @output_targets.each { |target| route(target) }
           end
         end
 
@@ -28,23 +25,51 @@ module Appydave
 
         attr_reader :content, :output_targets, :working_directory
 
+        def execute_smart
+          token_estimate = (@content.length / 4.0).ceil
+          if token_estimate <= @smart_limit
+            Clipboard.copy(@content)
+            warn "→ clipboard (#{format_tokens(token_estimate)})"
+          else
+            file_path = write_to_temp_file
+            Clipboard.copy(file_path)
+            warn "→ temp file: #{file_path} (#{format_tokens(token_estimate)})"
+            warn '  Path copied to clipboard.'
+          end
+        end
+
+        def format_tokens(count)
+          "#{(count / 1000.0).round.to_i}k tokens"
+        end
+
+        def route(target)
+          case target
+          when 'clipboard'
+            Clipboard.copy(@content)
+          when 'temp'
+            write_to_temp
+          when /^.+$/
+            write_to_file(target)
+          end
+        end
+
         def write_to_file(target)
           resolved_path = Pathname.new(target).absolute? ? target : File.join(working_directory, target)
           File.write(resolved_path, content)
         end
 
         def write_to_temp
-          # Create in system temp directory with descriptive name
+          file_path = write_to_temp_file
+          Clipboard.copy(file_path)
+          warn "Context saved to: #{file_path}"
+        end
+
+        def write_to_temp_file
           tmp_dir = Dir.tmpdir
           timestamp = Time.now.strftime('%Y%m%d-%H%M%S-%N')[0..18] # millisecond precision
           file_path = File.join(tmp_dir, "llm_context-#{timestamp}.txt")
-
-          # Write content to file
           File.write(file_path, @content)
-
-          # Copy path to clipboard
-          Clipboard.copy(file_path)
-          warn "Context saved to: #{file_path}"
+          file_path
         end
       end
     end

data/lib/appydave/tools/random_context/query_entry.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module RandomContext
+      # Represents one entry in the random-queries.yml config file
+      class QueryEntry
+        attr_reader :label, :command, :min_results, :max_results
+
+        def initialize(data)
+          @label = data['label']
+          @command = data['command']
+          @min_results = data.fetch('min_results', 1)
+          @max_results = data.fetch('max_results', 15)
+        end
+
+        def good_count?(count)
+          count.between?(min_results, max_results)
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/random_context/randomizer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'open3'
+require 'fileutils'
+
+module Appydave
+  module Tools
+    module RandomContext
+      # Loads query library, runs each query to check result count,
+      # filters to entries with "good" result counts, and picks one randomly.
+      class Randomizer
+        BUNDLED_CONFIG_PATH = File.expand_path('../../../../config/random-queries.yml', __dir__)
+        USER_CONFIG_PATH = File.expand_path('~/.config/appydave/random-queries.yml')
+
+        def initialize(config_path: USER_CONFIG_PATH, meta: false, executor: nil,
+                       bundled_config_path: BUNDLED_CONFIG_PATH,
+                       bootstrap: config_path == USER_CONFIG_PATH)
+          @config_path = config_path
+          @meta = meta
+          @executor = executor || method(:shell_execute)
+          @bundled_config_path = bundled_config_path
+          @bootstrap = bootstrap
+        end
+
+        # Returns [QueryEntry, results_array] for the picked entry, or nil if no candidates.
+        def pick
+          candidates = []
+
+          load_entries.each do |entry|
+            results = @executor.call(entry.command)
+            candidates << [entry, results] if entry.good_count?(results.size)
+          end
+
+          candidates.sample
+        end
+
+        # Picks a random candidate and prints label + results to stdout.
+        def run
+          picked = pick
+          unless picked
+            puts 'No matching queries found'
+            return
+          end
+
+          entry, results = picked
+          puts "Question: \"#{entry.label}\""
+
+          if @meta
+            meta_results = @executor.call("#{entry.command} --meta")
+            meta_results.each { |line| puts line }
+          else
+            results.each { |line| puts line }
+          end
+        end
+
+        private
+
+        def load_entries
+          resolved = resolve_config!
+          data = YAML.safe_load(File.read(resolved))
+          (data['queries'] || []).map { |q| QueryEntry.new(q) }
+        end
+
+        def resolve_config!
+          return @config_path if File.exist?(@config_path)
+          raise "Config not found: #{@config_path}" unless @bootstrap
+
+          FileUtils.mkdir_p(File.dirname(@config_path))
+          FileUtils.cp(@bundled_config_path, @config_path)
+          @config_path
+        end
+
+        def shell_execute(command)
+          stdout, _stderr, _status = Open3.capture2(command)
+          stdout.strip.split("\n").reject(&:empty?)
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.81.0'
+    VERSION = '0.83.0'
   end
 end

data/lib/appydave/tools.rb

@@ -41,6 +41,9 @@ require 'appydave/tools/brain_context/options'
 require 'appydave/tools/brain_context/brain_finder'
 require 'appydave/tools/brain_context/omi_finder'
 
+require 'appydave/tools/random_context/query_entry'
+require 'appydave/tools/random_context/randomizer'
+
 require 'appydave/tools/configuration/openai'
 require 'appydave/tools/configuration/configurable'
 require 'appydave/tools/configuration/config'

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.81.0",
+  "version": "0.83.0",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.81.0
+  version: 0.83.0
 platform: ruby
 authors:
 - David Cruwys
@@ -233,6 +233,7 @@ files:
 - bin/prompt_tools.rb
 - bin/query_brain.rb
 - bin/query_omi.rb
+- bin/random_context.rb
 - bin/setup
 - bin/subtitle_manager-old.rb
 - bin/subtitle_manager.rb
@@ -241,6 +242,7 @@ files:
 - bin/youtube_automation.rb
 - bin/youtube_manager.rb
 - bin/zsh_history.rb
+- config/random-queries.yml
 - docs/README.md
 - docs/ai-instructions/behavioral-regression-audit.md
 - docs/ai-instructions/code-quality-retrospective.md
@@ -424,6 +426,8 @@ files:
 - lib/appydave/tools/name_manager/project_name.rb
 - lib/appydave/tools/prompt_tools/_doc.md
 - lib/appydave/tools/prompt_tools/prompt_completion.rb
+- lib/appydave/tools/random_context/query_entry.rb
+- lib/appydave/tools/random_context/randomizer.rb
 - lib/appydave/tools/subtitle_processor/_doc-clean.md
 - lib/appydave/tools/subtitle_processor/_doc-join.md
 - lib/appydave/tools/subtitle_processor/_doc-todo.md