pedicab 0.3.0 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 702ea275719220820fd42a4619ff3d1bc23ec7436effb74b1c6df2e67a6aad96
-  data.tar.gz: 5c1c20e35ae8d24c7011f45b1dab63d30f3306dcdc72a2d9016ed05cc413681e
+  metadata.gz: f02a2dcd924ea83d8d045d1366f1ea6043141f8887c1d5ae40e36372d49deac6
+  data.tar.gz: 5487597657aaec6b3474599a4d2d74d7b99822f4a876e10037825147603c6e2b
 SHA512:
-  metadata.gz: ad3f2468798402d8f14e6f566e22ce2cd8c9c8aadced16cc882b2fff0daa0468d993788f10ee4d2edab84dffbffe9ae7e7e011c49198ae01aa08447c0c95a5c3
-  data.tar.gz: 7e0ea54c87fdaf6f54f25afa1df7cf91f09f1c902c88b161d2ae178b5a9565fb3f2b54ffeb931c4e18792645acdcbf5c5a4bd51fbf3db73d85d8cf6fa263e96a
+  metadata.gz: 3bcf9fc60bf98a9bd1e864343752a01ab1971c9e071dc778623a70500e5b06eb0f1161cbe0a82e38ee4e9f555a46ba866ec4b3f69bee76a839cef57be96224dc
+  data.tar.gz: 3be66f8fcaf8bfb84905c13eb0c7ad5d476d1b521126cd014ee891caa67043ace0ce9953f6c4fbf82b056582a6259e837c52583105d31260c26ab51708ed4f3f

data/API.md

@@ -0,0 +1,401 @@
+# API Documentation
+
+## Pedicab Module
+
+### Module Methods
+
+#### `Pedicab.memory -> allowcated context size`
+
+Get the number of inputs and outputs to consider as context when handling a request.
+
+**Returns:** allowcated context
+
+**Example:**
+```ruby
+Pedicab.memory
+```
+
+#### `Pedicab.[](id) -> Pedicab::P`
+
+Set the number of inputs and outputs to consider as context when handling a request.
+
+**Parameters:**
+- `id` (Integer) - new context size
+
+**Example:**
+```ruby
+Pedicab.memory = 5
+```
+
+
+#### `Pedicab.[](id) -> Pedicab::P`
+
+Creates a new conversation instance with the given identifier.
+
+**Parameters:**
+- `id` (String) - Unique identifier for the conversation instance
+
+**Returns:** `Pedicab::P` instance
+
+**Example:**
+```ruby
+ai = Pedicab['my_assistant']
+response = ai["Hello, world!"]
+```
+
+#### `Pedicab.models -> Array[String]`
+
+Lists all available GGUF models in the `/models/` directory.
+
+**Returns:** Array of model names (without .gguf extension)
+
+**Example:**
+```ruby
+puts Pedicab.models
+# => ["qwen", "llama2", "mistral"]
+```
+
+#### `Pedicab.ride(id) -> Pedicab::Ride`
+
+Creates a new low-level ride instance for direct model interaction.
+
+**Parameters:**
+- `id` (String) - Identifier for the ride instance
+
+**Returns:** `Pedicab::Ride` instance
+
+**Example:**
+```ruby
+ride = Pedicab.ride['direct_ride']
+response = ride.go("What is Ruby?")
+```
+
+---
+
+## Pedicab::P Class
+
+The main conversation interface that manages context, state, and interactions with the LLM.
+
+### Constructor
+
+#### `initialize(id)`
+
+Creates a new conversation instance.
+
+**Parameters:**
+- `id` (String) - Unique identifier for the conversation
+
+**Attributes:**
+- `id` - Conversation identifier
+- `ride` - Associated Ride instance
+- `handler` - Response handler lambda (default: returns `out`)
+- `context` - Current conversation context hash
+
+### Public Methods
+
+#### `reset! -> void`
+
+Clears all conversation state, context, and history.
+
+**Example:**
+```ruby
+ai = Pedicab['bot']
+ai["First question"]
+ai.reset!  # Clears everything for fresh start
+```
+
+#### `[](prompt) -> Object`
+
+Starts a fresh conversation with the given prompt. Clears previous context.
+
+**Parameters:**
+- `prompt` (String) - The prompt to send to the LLM
+
+**Returns:** Result of the handler (typically the response object)
+
+**Example:**
+```ruby
+response = ai["What is the meaning of life?"]
+puts response.out
+```
+
+#### `<<(prompt) -> Object`
+
+Continues an existing conversation with context. Maintains previous exchanges.
+
+**Parameters:**
+- `prompt` (String) - The prompt to send to the LLM
+
+**Returns:** Result of the handler (typically the response object)
+
+**Example:**
+```ruby
+ai["What is Ruby?"]           # First question
+ai << "What about Python?"    # Continues with context
+```
+
+#### `handle(&block) -> Proc/Object`
+
+Sets or executes the response handler.
+
+**Parameters:**
+- `block` (Proc) - Optional handler that receives the response object
+
+**Returns:** Handler proc if setting, or handler result if executing
+
+**Example:**
+```ruby
+# Set custom handler
+ai.handle do |response|
+  puts "AI said: #{response.out}"
+  puts "Time: #{response.took}s"
+  response
+end
+
+# Execute handler
+ai.handle
+```
+
+#### `life -> Float`
+
+Returns total processing time for all requests in the current conversation.
+
+**Returns:** Total time in seconds
+
+**Example:**
+```ruby
+ai["Question 1"]
+ai["Question 2"]
+puts "Total time: #{ai.life}s"
+```
+
+### Attributes (Readers)
+
+- `took` (Float) - Time taken for the last request in seconds
+- `time` (Array[Float]) - Array of processing times for all requests
+- `thoughts` (Array[String]) - Array of LLM thinking processes
+- `prompt` (String) - The last prompt sent
+- `response` (Array[String]) - Array of all responses received
+- `out` (String) - The last response content
+- `ride` (Pedicab::Ride) - The associated ride instance
+- `last` (Array[String]) - Array of previous prompts
+- `context` (Hash) - Current conversation context
+
+### Attributes (Accessors)
+
+- `handler` (Proc) - Response handler lambda
+- `context` (Hash) - Current conversation context
+
+---
+
+## Pedicab::Ride Class
+
+Low-level interface for direct communication with the LLM model.
+
+### Constructor
+
+#### `initialize(id)`
+
+Creates a new ride instance.
+
+**Parameters:**
+- `id` (String) - Identifier for the ride
+
+**Attributes:**
+- `id` - Ride identifier
+- `model` (String) - Model name (from ENV['MODEL'] or 'qwen')
+- `state` (Hash) - Current ride state
+
+### Public Methods
+
+#### `go(prompt, &block) -> String/Nil`
+
+Sends a prompt to the LLM and returns the response.
+
+**Parameters:**
+- `prompt` (String) - The prompt to send
+- `block` (Proc, optional) - Block to execute for each line of response
+
+**Returns:** Response content, or nil if block given
+
+**Example:**
+```ruby
+# Simple usage
+response = ride.go("What is 2+2?")
+puts response
+
+# With block for line-by-line processing
+ride.go("List 3 colors") do |line|
+  puts "Color: #{line[:for]}"
+end
+```
+
+#### `if?(condition, &block) -> Boolean/Object`
+
+Evaluates a boolean condition using the LLM.
+
+**Parameters:**
+- `condition` (String) - The condition to evaluate
+- `block` (Proc, optional) - Block to execute if condition is true
+
+**Returns:** Boolean result, or block result if block given and true
+
+**Example:**
+```ruby
+# Boolean check
+is_helpful = ride.if?("Ruby is a programming language")
+
+# With block
+ride.if?("user wants help") do
+  puts "Providing help..."
+end
+```
+
+#### `reset! -> void`
+
+Clears the ride state.
+
+#### `[](key) -> Object`
+
+Accesses a state value.
+
+**Parameters:**
+- `key` (Symbol/String) - State key
+
+**Returns:** State value
+
+#### `[]=(key, value) -> Object`
+
+Sets a state value.
+
+**Parameters:**
+- `key` (Symbol/String) - State key
+- `value` (Object) - State value
+
+**Returns:** Set value
+
+#### `to_h -> Hash`
+
+Returns the complete state as a hash.
+
+### State Keys
+
+The ride maintains these state keys:
+
+- `:content` - Model response content
+- `:thought` - Model thinking process (if available)
+- `:action` - Description of current action
+- `:yes` - Boolean result for conditional queries
+- `:took` - Processing time in seconds
+- `:for` - Current line when iterating (internal use)
+
+---
+
+## Environment Variables
+
+### MODEL
+
+Specifies the default model name to use.
+
+**Default:** `'qwen'`
+
+**Example:**
+```bash
+export MODEL=llama2
+```
+
+### DEBUG
+
+Controls debug output level.
+
+**Values:**
+- `0` - No debug output (default)
+- `1` - Basic debugging (action descriptions)
+- `2` - Verbose debugging (full state dumps)
+
+**Example:**
+```bash
+export DEBUG=1
+```
+
+---
+
+## Error Handling
+
+### Pedicab::Error
+
+Base exception class for Pedicab-specific errors.
+
+### Common Error Scenarios
+
+1. **Model not found** - When the specified GGUF file doesn't exist
+2. **Python process error** - When the backend process fails to start
+3. **Invalid JSON** - When communication with Python fails
+4. **Model inference error** - When the LLM fails to process the prompt
+
+**Example:**
+```ruby
+begin
+  response = ai["Some prompt"]
+rescue Pedicab::Error => e
+  puts "Pedicab error: #{e.message}"
+  # Handle the error appropriately
+end
+```
+
+---
+
+## Communication Protocol
+
+### Ruby → Python JSON Format
+
+```json
+{
+  "role": "user|assistant|system",
+  "model": "model_name",
+  "content": "prompt_content",
+  "response": "grammar_type"  // Optional, for constrained outputs
+}
+```
+
+### Python → Ruby JSON Format
+
+```json
+{
+  "role": "assistant",
+  "content": "response_content",
+  "thought": "thinking_process"  // Optional
+}
+```
+
+### Grammar Types
+
+The Python backend supports these grammar constraints:
+
+- `"bool"` - Yes/No responses
+- `"number"` - Numeric responses  
+- `"string"` - Single-line string responses
+
+---
+
+## Performance Considerations
+
+### Benchmarking
+
+Both `Pedicab::P` and `Pedicab::Ride` track processing times:
+
+- `P.took` - Last request time
+- `P.life` - Total conversation time
+- `Ride.state[:took]` - Last ride request time
+
+### Memory Usage
+
+- Conversation history grows with each exchange
+- Use `reset!` to clear memory when starting new topics
+- State is maintained in memory for the duration of the instance
+
+### Model Selection
+
+- Larger models provide better quality but slower responses
+- Consider model size based on your use case and hardware constraints
+- The `MODEL` environment variable allows easy switching between models