btape 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18261c2d64fe2120e746ab4e2991a85d8c6327aa32ad497125e6b8b1efb3779a
-  data.tar.gz: aa731da95d316a63404d3ae6a89f03d3c435bea95ff26eeda824c699f8390ef7
+  metadata.gz: f7ea547bca5c9c270e16d779e170c68b0ab30b8bc4156cde58d4cfe7560ebbe4
+  data.tar.gz: fb55fff428c21bfbc889aa653708a1d02c77ffe795c515238716ad9e246fecf6
 SHA512:
-  metadata.gz: dbb660a8f316b473a9c0a62e9842f3cc131e28d5061b49227cdc7b474be90abae39a7dfd5104e5cca26931458e60140a3423c41043de72a2d0e27b2adb51e155
-  data.tar.gz: 89ddb3f16ff21c0710dce00bfdef3a5588e3ee70a0d7df29373afb32b8e0dbf976ba30f63b83971aedd460ad8ff8c16b980f086f0d58f8d4699fe335554c1144
+  metadata.gz: 715e86c7d8e3d18834de6350eacac2ddad337d031faf3fae46f57d86364c445679509d9ef9db25e74688df5ac5c8c341a34418d85fb597b82ec312f2d02fd9d9
+  data.tar.gz: 3b67abd203cd1619bc2de88fb4259437a994ec970ef58e81c937ca68efc0ebebc71588942942efa06e6dc56191af8935891c945d5241d87df3c5440787fa18be

data/README.md

@@ -9,6 +9,11 @@
 and captures PNG frames, and a pure-Ruby encoder produces the GIF. It
 does not require Playwright, Selenium, ffmpeg, or an external service.
 
+Tapes are written by hand, or asked of a language model running on the same
+machine: `btape generate` describes the language to LM Studio, Ollama or
+anything else speaking their API, and holds the answer to the parser before
+handing it over.
+
 ## Commands
 
 ```text
@@ -88,10 +93,79 @@ Usage: btape [options] SCRIPT.tape
   --set NAME=VALUE Override a setting, as a Set line would
   --frames-dir DIR Write the PNG frames here and keep them
   --verbose        Report each command on stderr as it runs
+
+Subcommands:
+  generate DESCRIPTION  Write a tape by asking a local model; btape generate --help
 ```
 
 `BTAPE_WS_URL` is used when neither `--ws-url` nor `--set WsUrl=` is given.
 
+### Fonts, and text that is not Latin
+
+Glyphs come from the fonts the browser can see, which is not necessarily the
+machine btape runs on: the host when btape launches Chromium itself, the other
+machine when `Set WsUrl` points at one, and the image when either of those is
+a container. Nothing raises when a script has no coverage — the page records as
+rows of tofu boxes instead — so a font missing from a headless image shows up
+in the GIF and nowhere earlier.
+
+Install fonts covering the scripts the tapes visit. On Debian or Ubuntu:
+
+```sh
+apt-get install fonts-noto-core                # most scripts, Latin included
+apt-get install fonts-noto-cjk                 # Chinese, Japanese, Korean
+apt-get install fonts-ipafont fonts-ipaexfont  # Japanese, as IPAGothic, IPAexGothic, IPAMincho
+```
+
+Fontconfig reads `/usr/share/fonts`, `/usr/local/share/fonts`,
+`~/.local/share/fonts` and `~/.fonts`, and font files copied in by hand need
+an `fc-cache -f` after them. The home directory in that list is the one
+belonging to whoever launches the browser, which under a service manager is
+often not the user who installed the font — `sudo -u deploy fc-list` settles
+that faster than another recording does. Chromium reads the configuration as
+it starts, and btape starts one browser per run; a browser shared over `WsUrl`
+keeps the fonts it was launched with until it is restarted.
+
+Where one installed font covers a script, that is the whole job: the browser
+falls back to it even for a page that asked for `sans-serif`. Naming a family
+matters when several cover the same script — Noto CJK and IPA together, or a
+developer's macOS with Hiragino already on it. Either force it from the tape:
+
+```text
+Evaluate "document.head.insertAdjacentHTML('beforeend', '<style>*{font-family:IPAexGothic!important}</style>')"
+```
+
+which lasts as long as the document it ran in, so it is repeated after each
+`Goto` and inside a `Frame`; or prefer it for everything the machine renders,
+in `/etc/fonts/local.conf`:
+
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+<fontconfig>
+  <alias><family>sans-serif</family><prefer><family>IPAexGothic</family></prefer></alias>
+  <alias><family>serif</family><prefer><family>IPAexMincho</family></prefer></alias>
+  <alias><family>monospace</family><prefer><family>IPAGothic</family></prefer></alias>
+</fontconfig>
+```
+
+An alias only answers for the generic families. A page naming `Helvetica,
+Arial` ahead of `sans-serif` keeps whatever those resolve to — Liberation Sans,
+in an image that has it — so such a page is served by forcing the family from
+the tape, or by matching those names in the fontconfig file as well. macOS has
+no fontconfig at all, and there the tape is the only route.
+
+A tape can check that the font arrived rather than trust the image it runs in,
+since a family that is not installed measures the same as one that does not
+exist:
+
+```text
+WaitForJS "(() => { const c = document.createElement('canvas').getContext('2d'); const w = (f) => { c.font = '48px ' + f; return c.measureText('AあÄ0').width; }; return w('IPAexGothic') !== w('__missing__'); })()" 3s
+```
+
+Tape files themselves are read as UTF-8 whatever the locale says, so a `Type`
+line or a `text=` selector can be written in any script.
+
 ### A browser running somewhere else
 
 btape launches its own Chromium by default. Point it at one that is already
@@ -116,6 +190,77 @@ unwinds. `--frames-dir` keeps them:
 btape --frames-dir frames examples/thumbnails.tape
 ```
 
+## Writing a tape with a local model
+
+`btape generate` describes the language to a model running on your own
+machine and asks it for a tape:
+
+```sh
+btape generate "record signing in at localhost:3000 and landing on the dashboard" -o signin.tape
+btape signin.tape
+```
+
+The default is `http://localhost:1234/v1`, which is where LM Studio serves.
+Anything else speaking the same API answers just as well — Ollama on
+`http://localhost:11434/v1`, llama.cpp's server, vLLM — so nothing about the
+description or the page being recorded leaves the machine unless you point
+`--llm-url` somewhere that it does.
+
+```text
+Usage: btape generate [options] DESCRIPTION
+
+  --llm-url URL    The OpenAI-compatible model server to ask
+  --model NAME     Ask for this model rather than whichever one is loaded
+  --temperature N  How freely the model writes; 0.2 by default
+  --context FILE   Give the model this file as context: selectors, notes, markup
+  -o, --out FILE   Write the tape here rather than to standard output
+  --verbose        Report each attempt on stderr
+```
+
+`BTAPE_LLM_URL`, `BTAPE_LLM_MODEL` and `BTAPE_LLM_KEY` stand in for the first
+two flags and for a key, which a local server rarely wants and a proxy in
+front of one usually does. With no model named, the server is asked which one
+it has loaded — the name a download was given is not worth remembering.
+
+The description can be piped in rather than quoted, which is easier for
+anything longer than a line:
+
+```sh
+btape generate --context app/views/sessions/new.html.erb < what-to-record.txt
+```
+
+What comes back is parsed before you see it, and a tape that does not parse
+goes back to the model with the parser's own complaint — `line 4: unknown
+command "Navigate"` — for it to fix, up to three times. That loop is why this
+is worth more than pasting the command list into a chat window: a small model
+reliably invents a command or drops a quote, and just as reliably repairs it
+when told which line. What it cannot know is your markup, so a tape it wrote
+still names selectors that have to be checked against the page. Read it before
+you run it, the way you would read anything else generated for you.
+
+### A model that is not on this machine
+
+`--llm-url` is the whole of the configuration, so a hosted endpoint speaking
+the same API works as well as a local one. Name the model rather than leaving
+it to be discovered: these servers answer `/v1/models` with a catalogue rather
+than with the one thing they have loaded, and the first entry of it is not
+necessarily something that holds a conversation.
+
+```sh
+BTAPE_LLM_KEY=sk-... btape generate --llm-url https://api.openai.com/v1 --model gpt-4.1 "record signing in"
+```
+
+Anthropic serves an OpenAI-compatible layer on the same host as its own API,
+so `--llm-url https://api.anthropic.com/v1 --model claude-opus-5` records too.
+It is meant for trying models rather than for living on, but nothing btape
+asks of it is among the parts that are missing. A model that refuses
+`--temperature` at anything but its default wants `--temperature 1`.
+
+Sending the work somewhere else is the thing to weigh, not the flag. A local
+model keeps the description and the `--context` file on the machine that ran
+the command; a hosted one is handed both, and a context file is usually a page
+of your own markup rather than something you would have published.
+
 ## From Ruby
 
 `Runner#run` returns a `Btape::Result`:
@@ -155,9 +300,20 @@ or use the encoder on its own, with PNG paths or ChunkyPNG images:
 Btape::GifEncoder.new(delay: 150, width: 640).encode(frame_paths) # => String
 ```
 
+The generator is a plain object too, so an application that already knows what
+it wants recorded can go from a sentence to a GIF without a file in between:
+
+```ruby
+generator = Btape::LLM::Generator.new(client: Btape::LLM::Client.new(base_url: ENV['BTAPE_LLM_URL']))
+tape = generator.call('record the dashboard loading', context: page_markup)
+
+Btape::Runner.new.run(Btape::Parser.new.parse(tape), base_directory: '.', output: buffer)
+```
+
 ## Container development with dip or wip
 
-The development image contains Ruby and Chromium.
+The development image contains Ruby, Chromium and Latin fonts; tapes that
+record other scripts need fonts for them added to it.
 
 ```sh
 dip provision

data/lib/btape/cli.rb

@@ -2,6 +2,8 @@
 
 require 'logger'
 require 'optparse'
+require_relative 'generate_command'
+require_relative 'parser'
 
 module Btape
   # Entry point invoked by the `btape` executable: parses argv, runs the
@@ -11,23 +13,24 @@ module Btape
 
     USAGE = 'Usage: btape [options] SCRIPT.tape'
     HELP_ARGUMENTS = %w[help -h --help].freeze
-    HELP_COMMANDS = ['Output PATH', 'Viewport WIDTHxHEIGHT', 'Goto URL', 'Click SELECTOR',
-                     'Type SELECTOR TEXT', 'Sleep DURATION', 'Set NAME VALUE', 'Screenshot [NAME]',
-                     'Evaluate JAVASCRIPT', 'WaitFor SELECTOR [TIMEOUT]',
-                     'WaitForJS JAVASCRIPT [TIMEOUT]', 'Frame SELECTOR|main',
-                     'Press KEY [COUNT]'].freeze
+    HELP_COMMANDS = Parser::SIGNATURES.map { |name, arguments| "#{name} #{arguments}".strip }.freeze
+    GENERATE = 'generate'
     # The two ways a flag can name a browser: --ws-url and --set WsUrl=.
     WS_URL_KEYS = [:ws_url, 'WsUrl'].freeze
 
     # The runner is built after the flags are read, so that --verbose can
     # reach it. Pass one to use it as given.
-    def initialize(out: $stdout, err: $stderr, runner: nil)
+    def initialize(out: $stdout, err: $stderr, stdin: $stdin, runner: nil, generator: nil)
       @out = out
       @err = err
+      @stdin = stdin
       @runner = runner
+      @generator = generator
     end
 
     def run(argv)
+      return generate(argv.drop(1)) if argv.first == GENERATE
+
       options = Options.new(false, {}, nil, false)
       arguments = parse_options(argv, options)
       return print_help if options.help || arguments.empty? || HELP_ARGUMENTS.include?(arguments.first)
@@ -42,9 +45,13 @@ module Btape
 
     private
 
+    def generate(argv)
+      GenerateCommand.new(out: @out, err: @err, stdin: @stdin, generator: @generator).run(argv)
+    end
+
     def record(argument, options)
       script = File.expand_path(argument)
-      commands = Parser.new.parse(File.read(script))
+      commands = Parser.new.parse(read_script(script))
       result = runner(options).run(
         commands,
         base_directory: File.dirname(script),
@@ -55,6 +62,15 @@ module Btape
       report_frames(result)
     end
 
+    # Tapes are UTF-8, not whatever the locale happens to be. A tape that
+    # types text or matches on it is as likely to be written in Japanese or
+    # Greek as in ASCII, and read through the default external encoding a
+    # machine with LANG unset would reject those bytes while parsing rather
+    # than while recording.
+    def read_script(path)
+      File.read(path, encoding: Encoding::UTF_8)
+    end
+
     def runner(options)
       @runner || Runner.new(logger: logger(options))
     end
@@ -119,6 +135,9 @@ module Btape
       @out.puts '  --frames-dir DIR Write the PNG frames here and keep them'
       @out.puts '  --verbose        Report each command on stderr as it runs'
       @out.puts
+      @out.puts 'Subcommands:'
+      @out.puts '  generate DESCRIPTION  Write a tape by asking a local model; btape generate --help'
+      @out.puts
       @out.puts 'Commands:'
       HELP_COMMANDS.each { |command| @out.puts "  #{command}" }
       @out.puts

data/lib/btape/generate_command.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'optparse'
+require_relative 'error'
+require_relative 'llm/client'
+require_relative 'llm/generator'
+require_relative 'null_logger'
+
+module Btape
+  # `btape generate` — asks a model running on this machine for a tape and
+  # writes it out, having first checked that what came back is one.
+  #
+  # It is a separate command rather than a flag on a recording because it
+  # records nothing: no browser is opened, and the answer is a file to read,
+  # edit and then run like any other tape.
+  class GenerateCommand
+    USAGE = 'Usage: btape generate [options] DESCRIPTION'
+
+    Options = Struct.new(:help, :output_path, :context_path, :client, :verbose, keyword_init: true)
+
+    def initialize(out: $stdout, err: $stderr, stdin: $stdin, generator: nil)
+      @out = out
+      @err = err
+      @stdin = stdin
+      @generator = generator
+    end
+
+    def run(argv)
+      options = Options.new(help: false, client: {}, verbose: false)
+      words = parse_options(argv, options)
+      return print_help if options.help
+
+      write(generator(options).call(description(words), context: context(options)), options)
+      0
+    end
+
+    private
+
+    def write(script, options)
+      return @out.print(script) unless options.output_path
+
+      path = File.expand_path(options.output_path)
+      File.write(path, script, encoding: Encoding::UTF_8)
+      @out.puts "Wrote #{path}"
+    end
+
+    # The description is the words left after the flags, or standard input
+    # when there are none — a paragraph about what to record is easier to
+    # write in a file, or to pipe in, than to quote on a command line.
+    def description(words)
+      return words.join(' ') unless words.empty?
+      raise Error, USAGE if @stdin.tty?
+
+      piped = @stdin.read.to_s
+      raise Error, USAGE if piped.strip.empty?
+
+      piped
+    end
+
+    def context(options)
+      return nil unless options.context_path
+
+      File.read(File.expand_path(options.context_path), encoding: Encoding::UTF_8)
+    end
+
+    def generator(options)
+      @generator || LLM::Generator.new(client: LLM::Client.new(**options.client), logger: logger(options))
+    end
+
+    def logger(options)
+      return NullLogger.new unless options.verbose
+
+      Logger.new(@err, level: Logger::DEBUG, formatter: ->(_severity, _time, _program, message) { "#{message}\n" })
+    end
+
+    def parse_options(argv, options)
+      option_parser(options).parse(argv)
+    rescue OptionParser::ParseError => e
+      raise Error, e.message
+    end
+
+    def option_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = USAGE
+        parser.on('--llm-url URL', 'The OpenAI-compatible model server to ask') do |url|
+          options.client[:base_url] = url
+        end
+        parser.on('--model NAME', 'Ask for this model rather than whichever one is loaded') do |name|
+          options.client[:model] = name
+        end
+        parser.on('--temperature N', Float, 'How freely the model writes; 0.2 by default') do |value|
+          options.client[:temperature] = value
+        end
+        parser.on('--context FILE', 'Give the model this file as context: selectors, notes, markup') do |path|
+          options.context_path = path
+        end
+        parser.on('-o', '--out FILE', 'Write the tape here rather than to standard output') do |path|
+          options.output_path = path
+        end
+        parser.on('--verbose', 'Report each attempt on stderr') { options.verbose = true }
+        parser.on('-h', '--help', 'Show this message') { options.help = true }
+      end
+    end
+
+    def print_help
+      @out.puts USAGE
+      @out.puts
+      @out.puts 'Options:'
+      @out.puts '  --llm-url URL    The OpenAI-compatible model server to ask'
+      @out.puts '  --model NAME     Ask for this model rather than whichever one is loaded'
+      @out.puts '  --temperature N  How freely the model writes; 0.2 by default'
+      @out.puts '  --context FILE   Give the model this file as context: selectors, notes, markup'
+      @out.puts '  -o, --out FILE   Write the tape here rather than to standard output'
+      @out.puts '  --verbose        Report each attempt on stderr'
+      @out.puts
+      @out.puts "Defaults to #{LLM::Client::DEFAULT_BASE_URL}, which is where LM Studio serves."
+      @out.puts 'Ollama serves the same API at http://localhost:11434/v1.'
+      @out.puts 'BTAPE_LLM_URL, BTAPE_LLM_MODEL and BTAPE_LLM_KEY are used when the flags are not given.'
+      0
+    end
+  end
+end

data/lib/btape/llm/client.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative '../error'
+
+module Btape
+  # Talking to a language model, which btape does for one purpose: writing a
+  # tape from a description of the recording someone wants.
+  module LLM
+    # Raised when the model, or the server in front of it, could not answer.
+    class Error < Btape::Error; end
+
+    # A chat client for an OpenAI-compatible server. Nothing here knows which
+    # one it is talking to: LM Studio, Ollama, llama.cpp's server and vLLM all
+    # answer `/v1/chat/completions` in the same shape, so pointing `--llm-url`
+    # at one of them is the whole of the configuration.
+    #
+    # The defaults assume the model is running on this machine, where there is
+    # usually no key to send and no reason for the request to leave it.
+    class Client
+      # LM Studio's; Ollama serves the same API on 11434.
+      DEFAULT_BASE_URL = 'http://localhost:1234/v1'
+      DEFAULT_TEMPERATURE = 0.2
+      # A local model on a CPU answers in tens of seconds rather than the
+      # hundreds of milliseconds a hosted one would take.
+      DEFAULT_TIMEOUT = 300
+
+      # How much of a server's error body to quote back. Enough to name the
+      # problem, not so much that a stack trace fills the terminal.
+      ERROR_BODY_LIMIT = 500
+
+      attr_reader :base_url
+
+      def initialize(base_url: nil, model: nil, api_key: nil, temperature: nil, timeout: nil)
+        @base_url = (base_url || ENV.fetch('BTAPE_LLM_URL', DEFAULT_BASE_URL)).chomp('/')
+        @model = model || ENV.fetch('BTAPE_LLM_MODEL', nil)
+        @api_key = api_key || ENV.fetch('BTAPE_LLM_KEY', nil)
+        @temperature = temperature || DEFAULT_TEMPERATURE
+        @timeout = timeout || DEFAULT_TIMEOUT
+      end
+
+      # Sends the conversation and returns the reply's text.
+      def complete(messages)
+        payload = { model: model, messages: messages, temperature: @temperature, stream: false }
+        body = post('/chat/completions', payload)
+        content = body.dig('choices', 0, 'message', 'content')
+        # Not every server answers with a String there: some hand back the
+        # content as a list of parts, and a reasoning model may answer with
+        # nothing but its thoughts. Both are this client's error to report,
+        # rather than a NoMethodError from inside it.
+        raise Error, "#{@base_url} answered without a message" unless content.is_a?(String) && !content.strip.empty?
+
+        content
+      end
+
+      # The model to ask for. A server hosting one model still wants to be
+      # told which, and the name differs with every download — so when nobody
+      # has said, the loaded one is asked for by name.
+      def model
+        @model ||= first_loaded_model
+      end
+
+      private
+
+      def first_loaded_model
+        entry = get('/models')['data']&.first
+        name = entry['id'] if entry.is_a?(Hash)
+        raise Error, "no model is loaded at #{@base_url}; load one, or name it with --model" unless name
+
+        name
+      end
+
+      def post(path, payload)
+        request = Net::HTTP::Post.new(url_for(path))
+        request['content-type'] = 'application/json'
+        request.body = JSON.generate(payload)
+        send_request(request)
+      end
+
+      def get(path)
+        send_request(Net::HTTP::Get.new(url_for(path)))
+      end
+
+      def url_for(path)
+        URI.parse("#{@base_url}#{path}")
+      end
+
+      def send_request(request)
+        request['authorization'] = "Bearer #{@api_key}" if @api_key
+        response = transport(request.uri).request(request)
+        parse(response)
+      # A local server generating a long answer is the one most likely to be
+      # killed part way through it, and the connection dropping is how that
+      # arrives here.
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE, Net::HTTPBadResponse
+        raise Error, "#{@base_url} closed the connection before answering; did the model run out of memory?"
+      # Everything else the network can say — refused, unreachable, no such
+      # host, a route that went away — is the same thing to whoever ran the
+      # command, and it is worth naming the address they can go and check.
+      rescue SocketError, SystemCallError => e
+        raise Error, "could not reach a model server at #{@base_url} (#{e.message}); is it running?"
+      # Net::OpenTimeout and Net::ReadTimeout are both Timeout::Errors, so
+      # this covers a server that accepted the connection and then thought
+      # about it for too long as well as one that never accepted it.
+      rescue Timeout::Error
+        raise Error, "#{@base_url} did not answer within #{@timeout}s"
+      end
+
+      def transport(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http
+      end
+
+      def parse(response)
+        body = begin
+          JSON.parse(response.body.to_s)
+        rescue JSON::ParserError
+          nil
+        end
+        raise Error, failure_message(response, body) unless response.is_a?(Net::HTTPSuccess)
+        raise Error, "#{@base_url} answered with something that is not JSON" if body.nil?
+
+        body
+      end
+
+      # An OpenAI-compatible server reports its own failures as
+      # `{"error": {"message": ...}}`, and the ones that do not are quoted as
+      # they came so the reason is not lost to the status code alone.
+      def failure_message(response, body)
+        detail = body.is_a?(Hash) ? (body.dig('error', 'message') || body['error']) : nil
+        detail = response.body.to_s.strip[0, ERROR_BODY_LIMIT] if detail.nil? || detail.to_s.empty?
+        "#{@base_url} answered #{response.code}#{": #{detail}" unless detail.to_s.empty?}"
+      end
+    end
+  end
+end

data/lib/btape/llm/generator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+require_relative '../null_logger'
+require_relative '../parser'
+require_relative 'client'
+require_relative 'prompt'
+
+module Btape
+  module LLM
+    # Turns a description of a recording into a tape, by asking a model for
+    # one and then holding it to the language: what comes back is parsed
+    # before it is handed on, and a reply that does not parse goes back with
+    # the parser's complaint attached.
+    #
+    # That loop is the point of generating a tape rather than pasting one out
+    # of a chat window. A small local model reliably invents a command or
+    # forgets a quote; it just as reliably fixes it when told which line.
+    class Generator
+      ATTEMPTS = 3
+
+      # Models are told not to fence their answer, and fence it anyway.
+      FENCED = /```[\w+-]*\n(.*?)```/m
+
+      def initialize(client: Client.new, attempts: ATTEMPTS, logger: NullLogger.new)
+        @client = client
+        @attempts = attempts
+        @logger = logger
+      end
+
+      # Returns the tape as a String. Raises LLM::Error if the model could not
+      # be reached, or would not produce a tape that parses.
+      def call(description, context: nil)
+        raise Error, 'nothing was said about what to record' if description.to_s.strip.empty?
+
+        messages = [
+          { role: 'system', content: Prompt.system },
+          { role: 'user', content: Prompt.user(description.strip, context: context) }
+        ]
+        attempt(messages)
+      end
+
+      private
+
+      def attempt(messages)
+        reason = nil
+        @attempts.times do |index|
+          @logger.debug("btape: asking #{@client.model} for a tape (attempt #{index + 1} of #{@attempts})")
+          script = extract(@client.complete(messages))
+          reason = fault(script)
+          return script if reason.nil?
+
+          @logger.debug("btape: the tape did not parse (#{reason}); asking again")
+          messages += [{ role: 'assistant', content: script }, { role: 'user', content: Prompt.repair(reason) }]
+        end
+        raise Error, "the model did not write a tape that parses, after #{@attempts} attempts: #{reason}"
+      end
+
+      # Why this is not a tape, or nil when it is one. The parser answers most
+      # of it; Output is checked here because it is the one requirement that
+      # belongs to the script as a whole rather than to any line of it, and a
+      # tape without it fails at the start of a recording instead.
+      #
+      # A second Output is worth another round too: the runner takes the first
+      # and says nothing about the rest, so a model that wrote two would
+      # otherwise be told it had got it right while half of what it wrote was
+      # quietly dropped.
+      def fault(script)
+        commands = Parser.new.parse(script)
+        return 'it contained no commands' if commands.empty?
+
+        outputs = commands.count { |command| command.name == 'Output' }
+        return 'it has no Output line, so there is nowhere for the GIF to go' if outputs.zero?
+        return "it has #{outputs} Output lines, and a run writes one GIF" if outputs > 1
+
+        nil
+      rescue ScriptError => e
+        e.message
+      end
+
+      # The tape out of the reply. A fenced block is taken as the answer and
+      # any prose around it dropped; everything else is passed through whole,
+      # so that a stray sentence reaches the parser and comes back as
+      # something the model is asked to fix.
+      def extract(reply)
+        match = FENCED.match(reply)
+        "#{(match ? match[1] : reply).strip}\n"
+      end
+    end
+  end
+end

data/lib/btape/llm/prompt.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative '../parser'
+require_relative '../settings'
+
+module Btape
+  module LLM
+    # What the model is told before it is asked for a tape.
+    #
+    # The command list and the settings table are built from Parser and
+    # Settings rather than written out again here, so a command added to the
+    # language is a command the model is told about, and a setting cannot be
+    # described to it with a default it no longer has.
+    module Prompt
+      RULES = [
+        'Answer with the contents of a .tape file and nothing else: no explanation, no code fences.',
+        'The script must contain exactly one Output line, naming a .gif file, and it comes first.',
+        'One command per line. Lines starting with # are comments.',
+        'The line is split like a shell command, so any argument containing a space must be quoted ' \
+        'with double quotes.',
+        'Click, WaitFor and Frame take a CSS selector, or text=Some text to match on visible text.',
+        'Durations are a number followed by ms or s, such as 500ms or 1.5s.',
+        'Prefer WaitFor or WaitForJS over Sleep for anything the page has to finish doing; ' \
+        'Sleep is for holding a finished frame on screen long enough to be seen.',
+        'Use only the commands and settings listed above. Do not invent either, ' \
+        'and do not use a shell, a comment or a blank line to stand in for one.'
+      ].freeze
+
+      EXAMPLE = <<~TAPE
+        # Signing in, recorded at half size
+        Output signin.gif
+        Viewport 1280x720
+        Set Scale 0.5
+
+        Goto http://localhost:3000/signin
+        WaitFor "#email"
+        Type "#email" "demo@example.com"
+        Type "#password" "correct horse"
+        Click "text=Sign in"
+        WaitFor "text=Welcome back" 5s
+        Sleep 2s
+      TAPE
+
+      # What a setting takes, as the coercions in Settings enforce it. A
+      # default is shown as a tape would have to write it rather than as
+      # Settings holds it, since `Set FrameDelay 0.1` is not something the
+      # parser would accept back.
+      VALUES = {
+        duration: 'a duration',
+        url: "a #{Settings::URL_SCHEMES.join(', ')} url",
+        count: 'a whole number, 0 or more',
+        positive_integer: 'a whole number, 1 or more',
+        positive_float: 'a number'
+      }.freeze
+
+      module_function
+
+      def system
+        <<~PROMPT
+          You write btape scripts. btape runs a .tape file against Chromium and records
+          the run as an animated GIF, so a tape is a short, deliberate demonstration
+          rather than a test: it moves at a pace somebody can watch.
+
+          The commands, one per line:
+
+          #{indent(commands)}
+
+          A run is configured with `Set NAME VALUE`:
+
+          #{indent(settings)}
+
+          Rules:
+
+          #{indent(RULES.map { |rule| "- #{rule}" }.join("\n"))}
+
+          An example of a whole tape:
+
+          #{indent(EXAMPLE)}
+        PROMPT
+      end
+
+      def user(description, context: nil)
+        return description if context.nil? || context.strip.empty?
+
+        <<~PROMPT
+          #{description}
+
+          Context about the page being recorded — prefer the selectors it names over
+          any you would otherwise guess at:
+
+          #{context}
+        PROMPT
+      end
+
+      # A tape that did not parse goes back with the parser's own complaint,
+      # which names the line and what was wrong with it. Saying so beats
+      # asking again and hoping, since the model can see what it wrote.
+      def repair(reason)
+        <<~PROMPT
+          btape rejected that tape: #{reason}
+
+          Answer with the whole corrected tape, and nothing else.
+        PROMPT
+      end
+
+      def commands
+        Parser::SIGNATURES.map { |name, arguments| "#{name} #{arguments}".strip }.join("\n")
+      end
+
+      def settings
+        Settings::DEFINITIONS.map do |name, (_attribute, coercion, default)|
+          takes = coercion.is_a?(Array) ? coercion.join('|') : VALUES.fetch(coercion)
+          "Set #{name} <#{takes}>#{" — #{literal(coercion, default)} by default" unless default.nil?}"
+        end.join("\n")
+      end
+
+      # A coerced default as a tape would write it: durations are held in
+      # seconds and go back to the ms or s they were read from.
+      def literal(coercion, default)
+        return default.to_s unless coercion == :duration
+        return "#{(default * 1000).round}ms" if default < 1
+
+        "#{default.to_i == default ? default.to_i : default}s"
+      end
+
+      # Blank lines are left alone, so that indenting a block into the prompt
+      # does not leave trailing whitespace through the middle of it.
+      def indent(text)
+        text.strip.gsub(/^(?=.)/, '  ')
+      end
+    end
+  end
+end

data/lib/btape/parser.rb

@@ -19,6 +19,17 @@ module Btape
       'Frame' => 1, 'Press' => 1..2
     }.freeze
 
+    # The same commands as they read to somebody being told about them, which
+    # is what `btape help` prints and what a model is handed before it is
+    # asked for a tape. ARITY is what a script is held to; a spec keeps the
+    # two lists from drifting apart.
+    SIGNATURES = {
+      'Output' => 'PATH', 'Viewport' => 'WIDTHxHEIGHT', 'Goto' => 'URL', 'Click' => 'SELECTOR',
+      'Type' => 'SELECTOR TEXT', 'Press' => 'KEY [COUNT]', 'Frame' => 'SELECTOR|main',
+      'Evaluate' => 'JAVASCRIPT', 'WaitFor' => 'SELECTOR [TIMEOUT]', 'WaitForJS' => 'JAVASCRIPT [TIMEOUT]',
+      'Screenshot' => '[NAME]', 'Sleep' => 'DURATION', 'Set' => 'NAME VALUE'
+    }.freeze
+
     def parse(source)
       source.each_line.with_index(1).filter_map do |line, number|
         text = line.strip

data/lib/btape/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Btape
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/btape.rb

@@ -12,4 +12,8 @@ require_relative 'btape/gif_encoder'
 require_relative 'btape/recorder'
 require_relative 'btape/executor'
 require_relative 'btape/runner'
+require_relative 'btape/llm/client'
+require_relative 'btape/llm/prompt'
+require_relative 'btape/llm/generator'
+require_relative 'btape/generate_command'
 require_relative 'btape/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: btape
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - btape contributors
@@ -65,7 +65,11 @@ files:
 - lib/btape/duration.rb
 - lib/btape/error.rb
 - lib/btape/executor.rb
+- lib/btape/generate_command.rb
 - lib/btape/gif_encoder.rb
+- lib/btape/llm/client.rb
+- lib/btape/llm/generator.rb
+- lib/btape/llm/prompt.rb
 - lib/btape/lzw_compressor.rb
 - lib/btape/null_logger.rb
 - lib/btape/palette.rb