pedicab 0.3.1 → 0.3.3

data/README.md

@@ -1,23 +1,342 @@
 # Pedicab
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/pedicab`. To experiment with that code, run `bin/console` for an interactive prompt.
+A lightweight Ruby framework for conversational AI interfaces using local LLM models. Pedicab provides a clean, intuitive API for building AI-powered applications with context management and structured responses.
 
-TODO: Delete this and the text above, and describe your gem
+## Overview
+
+Pedicab is designed to be "the fastest LLMs in the west" - a streamlined interface for local language model inference. It focuses on the essential mechanics of conversational AI while maintaining simplicity and performance.
+
+### Core Features
+
+- **Local LLM Integration**: Uses GGUF model files with Python llama-cpp backend
+- **Context Management**: Automatic conversation context tracking and management
+- **Elegant Syntax**: Intuitive `[]` and `<<` operators for different interaction patterns
+- **State Management**: Persistent conversation state with reset capabilities
+- **Performance Tracking**: Built-in benchmarking and timing information
+- **Conditional Logic**: Support for boolean conditions and flow control
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+### Prerequisites
+
+1. **Ruby** >= 2.6.0
+2. **Python** with llama-cpp-python package
+3. **Local LLM Models** in GGUF format
+
+### Setup
+
+1. Install the gem:
+```bash
+gem install pedicab
+```
+
+2. Install Python dependencies:
+```bash
+pip install llama-cpp-python
+```
+
+3. Download LLM models to `/models/` directory:
+```bash
+# Example: Download a model
+wget https://example.com/model.gguf -O /models/qwen.gguf
+```
+
+4. Set up the Python backend (included with the gem)
+
+## Quick Start
+
+### Sample Pry Console
+
+```ruby
+require 'pry'
+require "bundler/setup"
+# 1. include the Pedicab module
+require 'pedicab'
+
+# 2. create local Pedicab
+@me = Pedicab["me"]
+
+if File.exist? 'me.txt'
+  # 3. use the me.txt file to predefine context.
+  @me[File.read('me.txt')]
+end
+
+# 4. start interactive session
+Pry.start
+# ... that's it.
+```
+
+### Basic Usage
+
+```ruby
+require 'pedicab'
+
+# Create a new conversation instance
+ai = Pedicab['my_assistant']
+
+# Start a fresh conversation
+response = ai["Hello, how are you?"]
+puts response.out
+# => "I'm doing well, thank you for asking!"
+
+# Continue the conversation with context
+response = ai["Tell me about Ruby programming"]
+puts response.out
+# => "Ruby is a dynamic, object-oriented programming language..."
+```
+
+### Context Management
+
+```ruby
+# Reset conversation context
+ai.reset!
+
+# The [] operator starts fresh
+ai["What's the capital of France?"]  # New conversation
+
+# The << operator continues with context
+ai["What about Germany?"]           # Knows we're discussing countries
+```
+
+### Custom Handlers
+
+```ruby
+# Define custom response handling
+ai.handle do |response|
+  puts "AI Response: #{response.out}"
+  puts "Processing time: #{response.took}s"
+  response
+end
+
+ai["Explain quantum computing"]
+# => AI Response: Quantum computing is a revolutionary...
+# => Processing time: 1.23s
+```
+
+## Core API
+
+### Pedicab::P Class
+
+The main interface for AI conversations.
+
+#### Methods
+
+- `initialize(id)` - Create new conversation instance
+- `reset!` - Clear conversation context and state
+- `[](prompt)` - Start fresh conversation with prompt
+- `<<(prompt)` - Continue conversation with context
+- `handle(&block)` - Set custom response handler
+- `life()` - Total processing time for all requests
+
+#### Attributes
+
+- `took` - Time taken for last request
+- `prompt` - Last prompt sent
+- `response` - Array of all responses
+- `out` - Last response content
+- `last` - Array of previous prompts
+- `thoughts` - LLM thinking process (if available)
+- `context` - Current conversation context
+- `handler` - Response handler lambda
+
+### Pedicab::Ride Class
+
+Low-level LLM interface for direct model interaction.
+
+#### Methods
+
+- `go(prompt, &block)` - Send prompt to model, optionally process each line
+- `if?(condition, &block)` - Evaluate boolean condition, optionally execute block
+- `reset!` - Clear ride state
+- `[](key)` - Access state value
+- `[]=(key, value)` - Set state value
+- `to_h` - Get state as hash
+
+#### State
+
+The ride maintains internal state including:
+- `:content` - Model response content
+- `:thought` - Model thinking process
+- `:action` - Current action description
+- `:yes` - Boolean result for conditions
+- `:took` - Processing time
+
+### Module Methods
+
+- `Pedicab.[](id)` - Create new conversation instance
+- `Pedicab.models` - List available models in `/models/`
+- `Pedicab.ride(id)` - Create new ride instance
+
+## Advanced Usage
+
+### Conditional Processing
+
+```ruby
+ai = Pedicab['conditional_bot']
+
+# Use conditional logic
+if ai.ride.if?("the user wants programming help")
+  ai["I'll help you with programming!"]
+else
+  ai["How can I assist you today?"]
+end
+```
+
+### Iterating Over Responses
+
+```ruby
+# Process each line of a response
+ai.ride.go("List 3 programming languages") do |line|
+  puts "Language: #{line[:for]}"
+end
+```
+
+### State Management
+
+```ruby
+ride = Pedicab.ride['stateful_bot']
+
+# Store custom state
+ride[:user_preference] = "detailed"
+ride[:last_topic] = "Ruby"
+
+# Access state later
+puts ride[:user_preference]  # => "detailed"
+puts ride.to_h              # => { user_preference: "detailed", last_topic: "Ruby" }
+```
+
+### Performance Monitoring
+
+```ruby
+ai = Pedicab['monitored_bot']
+
+ai["First question"]     # Processes
+puts ai.took            # Time for last request: 0.85s
+
+ai["Follow up question"] # Processes
+puts ai.life            # Total time: 1.67s
+```
+
+## Configuration
+
+### Environment Variables
+
+- `MODEL` - Default model name (default: 'qwen')
+- `DEBUG` - Debug level (0=off, 1=basic, 2=verbose)
+
+### Model Management
+
+```ruby
+# List available models
+puts Pedicab.models
+# => ["qwen", "llama2", "mistral"]
+
+# Models should be placed in /models/ directory as .gguf files
+# /models/qwen.gguf
+# /models/llama2.gguf
+# /models/mistral.gguf
+```
+
+## Architecture
+
+### Core Components
+
+1. **Ruby Interface** (`lib/pedicab.rb`)
+   - Main API and conversation management
+   - Context tracking and state management
+   - Elegant operator interface
+
+2. **Ride Layer** (`lib/pedicab/ride.rb`)
+   - Low-level LLM communication
+   - JSON-based protocol with Python backend
+   - State management and error handling
+
+3. **Python Backend** (`lib/pedicab.py`)
+   - llama-cpp-python integration
+   - Model loading and inference
+   - Grammar-based constrained outputs
+
+### Communication Flow
+
+```
+Ruby P Class -> Ride Class -> Python Backend -> LLM Model -> Response
+```
+
+1. Ruby sends JSON request to Python process
+2. Python processes with llama-cpp-python
+3. Response includes content and thinking process
+4. Ruby parses and manages state
+
+## Error Handling
+
+```ruby
+begin
+  ai = Pedicab['test_bot']
+  response = ai["Some question"]
+rescue Pedicab::Error => e
+  puts "Pedicab error: #{e.message}"
+rescue => e
+  puts "Unexpected error: #{e.message}"
+end
+```
+
+## Debugging
+
+Enable debug output:
+
+```ruby
+# In your shell
+export DEBUG=1  # Basic debugging
+export DEBUG=2  # Verbose debugging
+
+# Or in Ruby
+ENV['DEBUG'] = '1'
+```
+
+Debug output includes:
+- Action descriptions
+- Processing times
+- Full state information
+- Error details
+
+## Performance Tips
+
+1. **Model Selection**: Choose appropriate model size for your use case
+2. **Context Management**: Reset conversations when starting new topics
+3. **Batch Processing**: Use the iteration methods for list responses
+4. **Monitoring**: Track processing times with `took` and `life` methods
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Changelog
+
+### Version 0.3.2
 
-    $ bundle add pedicab
+- Simplified core architecture
+- Removed auxiliary modules for focus on essential mechanics
+- Improved performance and reduced dependencies
+- Enhanced error handling and debugging capabilities
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Previous Versions
 
-    $ gem install pedicab
+See git history for detailed changelog.
 
-## Usage
+## Support
 
-What to say?
+For issues and questions:
+- GitHub Issues: https://github.com/xorgnak/pedicab/issues
+- Documentation: https://github.com/xorgnak/pedicab
 
-Oh, the gem!? okay.  Here's the short fast and loud. "AI" has been around since before buddy holly. Not citiong sources.  Short-fast-n-lould is their're a tech you should "understand"; no judgment.
+---
 
-usage: @me = Pedicab['me']
+*Pedicab: A better way to go with local LLMs*

data/lib/pedicab/#city.rb#

@@ -0,0 +1,27 @@
+module Pedicab
+  module City
+    class C
+      attr_accessor :data
+      def initialize(i)
+        @id = i
+        @data = {}
+      end
+      
+      def to_markdown
+        @carpet.to_markdown(@data)
+      end
+      
+      def to_html
+        @carpet.to_html(@data)
+      end
+    end
+    
+    def self.[](k)
+      C.new(k)
+    end
+  end
+  
+  def self.city
+    City
+  end
+end

data/lib/pedicab/ride.rb

@@ -1,109 +1,88 @@
 module Pedicab
-  @@Ride = Hash.new { |h,k| h[k] = Ride.new(k) }
   class Ride
-    attr_accessor :state, :action, :goal, :ride, :info, :tale, :path, :model
-    def initialize k
+    attr_accessor :state, :model
+    def initialize(k)
       @id = k
-      @model = 'model'
+      @model = ENV['MODEL'] || 'qwen'
       reset!
     end
+    
     def reset!
       @state = {}
-      @ride = []
-      @path = []
-      @info = ""
     end
-    
-    ##
-    # tell the "tale" of the ride.
-    def tale
-      a = []
-      if @ride.length > 0
-      	h = @ride[-1]
-        @ride.shift
-      	return %[#{h[:input]}\n#{h[:output]}\n]
+
+    def go(prompt, &b)
+      @state[:action] = "respond: #{prompt}"
+      rider(role: 'user', model: @model, content: prompt)
+      def each &b
+        @state[:content].split("\n").each { |e| @state[:for] = e; b.call(self) }
+      end
+      if block_given?
+        b.call(self)
       else
-      	return ""
+        @state[:content]
       end
     end
-    
-    ##
-    # process input.
-    def go i
-      @path << "go #{i}"
-      @state[:action] = "go"
-      @state[:input] = i
-#      puts %[#===============[work]>\n#{i}\n#===============[work]];
-      Pedicab.on[:work].call(self)
-      @state[:output] = rider(role: 'user', model: 'work', content: "#{@info}#{tale}#{i}")
-      @ride << @state
-      @state[:output].gsub(/\n+/, "\n")
-    end
-    
-    ##
-    # process condition
-    def go? i
-      @path << "go? #{i}"
-      @state[:action] = "go?"
-      @state[:input] = i
+    def if?(condition, &b)
+      @state[:action] = "gate: #{condition}"
       @state[:yes] = false
-#      puts %[#>>>>>[gate]>\n#{i}\n#>>>>>[gate]];
-      Pedicab.on[:gate].call(self)
-      if rider(role: 'system', model: 'gate', content: %[#{@info}#{tale}if the following statement is true respond 'yes', otherwise respond 'no':\n#{i}], response: 'bool' ) == 'yes'
-        @state[:yes] = true
-        Pedicab.on[:go].call(self)
+      gate_prompt = "If the following statement is true respond 'yes', otherwise respond 'no':\n#{condition}"
+      rider(role: 'system', model: @model, content: gate_prompt)
+      @state[:yes] = (@state[:content] == 'yes')
+      if block_given? && @state[:yes] == true
+        b.call(self)
+      else
+        @state[:yes]
       end
-      @ride << @state
-      @state[:yes]
     end
-    
-    ##
-    # process list
-    def go! i, p, &b
-      @path << "with #{i} of #{p}"
-      @state[:action] = "go! fork" 
-      @state[:input] = %[#{@info}#{tale}List only #{i} unnumbered without repeating yourself:\n#{p}]
-      Pedicab.on[:fork].call(self)
-      @state[:list] = rider(role: 'user', model: 'fork', content: @state[:input]).split("\n").uniq.map { |e|
-        if e.strip.length > 0;
-#          puts %[#----------[fork]>\nfor: #{i}\nin: #{p}\nat: #{e}\n#----------[fork]];
-          Pedicab.on[:with].call(self);
-          b.call(e.strip);
-        end;
-      }
-      @ride << @state
-      @state[:list]
+
+    def [] k
+      @state[k]
+    end
+
+    def []= k,v
+      @state[k] = v
+    end
+
+    def to_h
+      @state
     end
     
     private
 
-    def rider h={}, &b
+    def rider(h = {})
       @state[:content] = "I don't know."
-#      puts %[#====[ #{@ride.length} ][#{@state[:action]}]\n#{@state[:input]}]
-      Pedicab.on[:before].call(self)
+      if ENV['DEBUG'].to_i > 1
+        puts "# #{@state[:action]}"
+      end
+      
       @state[:took] = Benchmark.realtime do
         Open3.popen3("pedicab /models/#{h[:model]}.gguf") do |stdin, stdout, stderr, wait_thread|
-    	  x = lambda { stdin.puts(JSON.generate(h)); stdout.gets }
-    	  begin
-	    xx = x.call()
-   	    if "#{xx}".strip.length > 0                                                                                                                                                               
-       	      @state[:content] = JSON.parse("#{xx}")['content']
-       	    end
-          rescue => e
-  	    @state[:content] = "Error: #{e}"
-  	  end
+          stdin.puts(JSON.generate(h))
+          response = stdout.gets
+          
+          if response && response.strip.length > 0
+            content = JSON.parse(response)['content']
+            if match = /<think>([\s\S]*)<\/think>([\s\S]*)/.match(content)
+              @state[:thought] = match[1].strip.gsub(/\n+/, "\n").gsub('\\n', "\n")
+              @state[:content] = match[2].strip.gsub(/\n+/, "\n").gsub('\\n', "\n")
+            else
+              @state[:thought] = h[:content].gsub('\\n', "\n")
+              @state[:content] = content.strip.gsub(/\n+/, "\n").gsub('\\n', "\n")
+            end
+          end
+        rescue => e
+          @state[:content] = "Error: #{e}"
         end
       end
-      Pedicab.on[:after].call(self)
-#      puts %[#====[ #{@ride.length} ] took: #{@state[:took]} seconds.\n#{@state[:content].gsub(/\n+/,"\n")}]
-      if block_given?
-        return b.call(self).gsub(/\n+/, "\n")
-      else
-        return @state[:content].gsub(/\n+/, "\n")
+      
+      if ENV['DEBUG'].to_i > 0
+        @state.each_pair { |k, v| puts "#{k}: #{v}" }
       end
     end
   end
-  def self.ride
-    @@Ride
+  
+  def self.ride(k)
+    Ride.new(k)
   end
 end

data/lib/pedicab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pedicab
-  VERSION = "0.3.1"
+  VERSION = "0.3.3"
 end

data/lib/pedicab.py

@@ -5,19 +5,15 @@ import json
 
 llm = Llama(
     model_path=sys.argv[1],
-#    model_path="/models/planner.gguf",
-#      model_path="/models/smollm.gguf",
       verbose=False,
       errors="ignore",
       n_ctx=8192
 )
 
-__sys = "A conversation between a curious Human and an all knowing Assistant who responds only to what was asked in simple terms and never repeats itself.\n\nWhen asked to respond with a single value, respond with only that value.\nWhen asked to list items, respond with the list of items sepearated by a newline only and again - never repeat yourself.\nWhen asked to respond with a mathmatical formula, respond with only the bare formula in the format necessary to be evaluated by the ruby eqn gem.\nOtherwise, respond with a single level outline and NEVER repeat yourself."
+__sys = "A conversation between a curious Human and an all knowing Assistant who responds only to what was asked in simple terms and never repeats itself.\n\nWhen asked to respond with a single value, respond with only that value.\nWhen asked to respond with an empty list, respond only with an empty string.\nWhen asked to list items respond with the list of items sepearated by a newline only and again - never repeat yourself.\nWhen asked to respond with a mathmatical formula, respond with only the bare formula in the format necessary to be evaluated by the ruby eqn gem.\nOtherwise, respond with a single level outline and NEVER repeat yourself."
 #__sys = "A conversation between a Human and an all knowing Llama."
 
-
-prompt = __sys
-convo = [{ "role": "system", "content": prompt }]
+convo = [{ "role": "system", "content": __sys }]
 grammars = { 
   "bool": 'root ::= ("yes" | "no")',
   "number": "root ::= (\"-\"?([0-9]+))",
@@ -30,8 +26,7 @@ while True:
     user = json.loads(input(""))
 
     if (user["role"] == "assistant"):
-        convo.append({ "role": "user", "content": user["content"] })
-        convo.append({ "role": "assistant", "content": user["response"] })
+        convo = [{ "role": "system", "content": user["content"] }]
    
     if (user["role"] == "system"):
         output = llm( user["content"], stop=["\n"], echo=False, temperature=0.0, grammar=LlamaGrammar.from_string(grammars[user['response']]))["choices"][0]["text"]