eywa-client 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3cb389c11a653f8a4d9b9e73d49619c2438b62dd12dd61ce0f523541d348f24d
+  data.tar.gz: 54cfff0b41310d46354f93ea02f6f9ff022f260e7afff99398533fe21782fe88
+SHA512:
+  metadata.gz: d4e3e0bbced5016f5b293222a6e8761b0b2f9f7fd13e2fd0e862fbe9b705db9887ad649c47a2a073ef4ee07f2f5fa5f0e08d945021f71a0500d1940958770802
+  data.tar.gz: 689c54a748b37a357d7b8b3bc7d15816ebe313eca02e1c479a001aca06e2c5cc79822e32323cd99f6af0e7755cad1cb19cbdfd0b863d9ce084616370b0cd5a93

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Robert Gersak / Neyho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,370 @@
+# EYWA Client for Ruby
+
+[![Gem Version](https://badge.fury.io/rb/eywa-client.svg)](https://badge.fury.io/rb/eywa-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+EYWA client library for Ruby providing JSON-RPC communication, GraphQL queries, and task management for EYWA robots.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'eywa-client'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install eywa-client
+```
+
+## Quick Start
+
+```ruby
+require 'eywa'
+
+# Initialize the client
+open_pipe
+
+# Log messages
+info("Robot started")
+
+# Execute GraphQL queries
+result_thread = graphql('
+  {
+    searchUser(_limit: 10) {
+      euuid
+      name
+      type
+    }
+  }
+')
+
+result = result_thread.value
+info("Users found", result)
+
+# Update task status
+update_task(PROCESSING)
+
+# Complete the task
+close_task(SUCCESS)
+```
+
+## Features
+
+- 🚀 **Thread-Based Async** - Ruby native threading for async operations
+- 📊 **GraphQL Integration** - Execute queries and mutations against EYWA datasets
+- 📝 **Comprehensive Logging** - Multiple log levels with metadata support
+- 🔄 **Task Management** - Update status, report progress, handle task lifecycle
+- 🎯 **Thread-Safe** - Mutex protection for concurrent operations
+- 💎 **Ruby Idioms** - Keyword arguments and blocks for handlers
+
+## API Reference
+
+### Initialization
+
+#### `open_pipe`
+Initialize stdin/stdout communication with EYWA runtime. Must be called before using other functions.
+
+```ruby
+open_pipe
+```
+
+### Logging Functions
+
+#### `log(event: "INFO", message:, data: nil, duration: nil, coordinates: nil, time: Time.now)`
+Log a message with full control over all parameters.
+
+```ruby
+log(
+  event: "INFO",
+  message: "Processing item",
+  data: { item_id: 123 },
+  duration: 1500,
+  coordinates: { x: 10, y: 20 }
+)
+```
+
+#### `info()`, `error()`, `warn()`, `debug()`, `trace()`, `exception()`
+Convenience methods for different log levels.
+
+```ruby
+info("User logged in", { user_id: "abc123" })
+error("Failed to process", { error: e.message })
+exception("Unhandled error", { stack: e.backtrace[0..5] })
+```
+
+### Task Management
+
+#### `get_task`
+Get current task information. Returns a Thread.
+
+```ruby
+task_thread = get_task
+begin
+  task = task_thread.value
+  info("Processing task", { task_id: task["euuid"] })
+rescue => e
+  warn("Could not get task", { error: e.message })
+end
+```
+
+#### `update_task(status = PROCESSING)`
+Update the current task status.
+
+```ruby
+update_task(PROCESSING)
+```
+
+#### `close_task(status = SUCCESS)`
+Close the task with a final status and exit the process.
+
+```ruby
+begin
+  # Do work...
+  close_task(SUCCESS)
+rescue => e
+  error("Task failed", { error: e.message })
+  close_task(ERROR)
+end
+```
+
+#### `return_task`
+Return control to EYWA without closing the task.
+
+```ruby
+return_task
+```
+
+### Reporting
+
+#### `report(message, data = nil, image = nil)`
+Send a task report with optional data and image.
+
+```ruby
+report("Analysis complete", {
+  accuracy: 0.95,
+  processed: 1000
+}, chart_image_base64)
+```
+
+### GraphQL
+
+#### `graphql(query, variables = nil)`
+Execute a GraphQL query against the EYWA server. Returns a Thread.
+
+```ruby
+# Simple query
+thread = graphql('{ searchUser { name email } }')
+result = thread.value
+
+# Query with variables
+thread = graphql('
+  mutation CreateUser($input: UserInput!) {
+    syncUser(data: $input) {
+      euuid
+      name
+    }
+  }
+', {
+  input: {
+    name: "John Doe",
+    active: true
+  }
+})
+
+begin
+  result = thread.value
+  info("User created", result)
+rescue => e
+  error("Creation failed", { error: e.message })
+end
+```
+
+### JSON-RPC
+
+#### `send_request(data)`
+Send a JSON-RPC request and get a Thread for the response.
+
+```ruby
+thread = send_request({
+  "method" => "custom.method",
+  "params" => { "foo" => "bar" }
+})
+
+begin
+  result = thread.value
+  info("Response received", result)
+rescue => e
+  error("Request failed", { error: e.message })
+end
+```
+
+#### `send_notification(data)`
+Send a JSON-RPC notification without expecting a response.
+
+```ruby
+send_notification({
+  "method" => "custom.event",
+  "params" => { "status" => "ready" }
+})
+```
+
+#### `register_handler(method, &handler)`
+Register a handler for incoming JSON-RPC method calls.
+
+```ruby
+register_handler("custom.ping") do |request|
+  info("Received ping", request["params"])
+  send_notification({
+    "method" => "custom.pong",
+    "params" => { "timestamp" => Time.now.to_i }
+  })
+end
+```
+
+## Module Structure
+
+The library uses a modular structure with a global client for ease of use:
+
+```ruby
+# Direct usage (recommended)
+info("Hello")
+
+# Or use the client instance
+Eywa.client.info("Hello")
+
+# Access constants
+SUCCESS    # => "SUCCESS"
+ERROR      # => "ERROR"
+PROCESSING # => "PROCESSING"
+EXCEPTION  # => "EXCEPTION"
+```
+
+## Complete Example
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'eywa'
+
+def process_data
+  # Get task
+  task_thread = get_task
+  task = task_thread.value
+  
+  info("Starting task", {
+    task_id: task["euuid"],
+    message: task["message"]
+  })
+  
+  # Update status
+  update_task(PROCESSING)
+  
+  # Query data
+  result_thread = graphql('
+    query GetActiveUsers {
+      searchUser(_where: {active: {_eq: true}}) {
+        euuid
+        name
+        email
+      }
+    }
+  ')
+  
+  result = result_thread.value
+  users = result.dig("data", "searchUser") || []
+  
+  info("Found users", { count: users.length })
+  
+  # Process users
+  users.each do |user|
+    debug("Processing user", { user_id: user["euuid"] })
+    # ... do something
+  end
+  
+  # Report results
+  report("Found active users", {
+    count: users.length,
+    user_names: users.map { |u| u["name"] }
+  })
+  
+  info("Task completed")
+rescue => e
+  error("Task processing failed", {
+    error: e.message,
+    backtrace: e.backtrace[0..5]
+  })
+  raise
+end
+
+def main
+  # Initialize
+  open_pipe
+  sleep(0.1)
+  
+  info("Robot started")
+  
+  begin
+    process_data
+    close_task(SUCCESS)
+  rescue => e
+    error("Task failed", { error: e.message })
+    close_task(ERROR)
+  end
+end
+
+main
+```
+
+## Error Handling
+
+Threads return exceptions that can be caught:
+
+```ruby
+thread = graphql("{ invalid }")
+begin
+  result = thread.value
+rescue => e
+  error("GraphQL failed", { error: e.message })
+end
+```
+
+## Thread Safety
+
+All operations are thread-safe:
+- Mutex protection for callbacks and handlers
+- Thread-safe Queue for request/response correlation
+- Safe concurrent access to shared state
+
+## Testing
+
+Test your robot locally using the EYWA CLI:
+
+```bash
+eywa run -c 'ruby my_robot.rb'
+```
+
+## Requirements
+
+- Ruby 2.5+
+- No external gem dependencies (uses only standard library)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues and questions, please visit the [EYWA repository](https://github.com/neyho/eywa).

data/lib/eywa.rb

@@ -0,0 +1,242 @@
+require 'securerandom'
+require 'json'
+require 'time'
+
+module Eywa
+  # Version
+  VERSION = "0.3.0"
+  
+  # Task status constants
+  SUCCESS = 'SUCCESS'
+  ERROR = 'ERROR'
+  PROCESSING = 'PROCESSING'
+  EXCEPTION = 'EXCEPTION'
+
+  class Client
+    def initialize
+      @rpc_callbacks = {}
+      @handlers = {}
+      @mutex = Mutex.new
+    end
+
+    def open_pipe
+      Thread.new do
+        while (line = STDIN.gets)
+          begin
+            json = JSON.parse(line)
+            handle_data(json)
+          rescue JSON::ParserError => e
+            STDERR.puts("Failed to parse JSON: #{e.message}")
+          rescue => e
+            STDERR.puts("Error handling data: #{e.message}")
+          end
+        end
+      end
+    end
+
+    def send_request(data)
+      id = SecureRandom.uuid
+      data['jsonrpc'] = '2.0'
+      data['id'] = id
+
+      # Create a queue for this request
+      queue = Queue.new
+      
+      @mutex.synchronize do
+        @rpc_callbacks[id] = queue
+      end
+
+      # Send the request
+      STDOUT.puts(data.to_json)
+      STDOUT.flush
+
+      # Wait for response in a thread
+      Thread.new do
+        response = queue.pop
+        @mutex.synchronize do
+          @rpc_callbacks.delete(id)
+        end
+        
+        if response['error']
+          raise StandardError.new(response['error']['message'] || response['error'].to_s)
+        else
+          response['result']
+        end
+      end
+    end
+
+    def send_notification(data)
+      data['jsonrpc'] = '2.0'
+      STDOUT.puts(data.to_json)
+      STDOUT.flush
+    end
+
+    def register_handler(method, &handler)
+      @mutex.synchronize do
+        @handlers[method] = handler
+      end
+    end
+
+    def log(event: 'INFO', message:, data: nil, duration: nil, coordinates: nil, time: Time.now)
+      send_notification(
+        'method' => 'task.log',
+        'params' => {
+          'time' => time.iso8601,
+          'event' => event,
+          'message' => message,
+          'data' => data,
+          'coordinates' => coordinates,
+          'duration' => duration
+        }
+      )
+    end
+
+    def info(message, data = nil)
+      log(event: 'INFO', message: message, data: data)
+    end
+
+    def error(message, data = nil)
+      log(event: 'ERROR', message: message, data: data)
+    end
+
+    def warn(message, data = nil)
+      log(event: 'WARN', message: message, data: data)
+    end
+
+    def debug(message, data = nil)
+      log(event: 'DEBUG', message: message, data: data)
+    end
+
+    def trace(message, data = nil)
+      log(event: 'TRACE', message: message, data: data)
+    end
+
+    def exception(message, data = nil)
+      log(event: 'EXCEPTION', message: message, data: data)
+    end
+
+    def report(message, data = nil, image = nil)
+      send_notification(
+        'method' => 'task.report',
+        'params' => {
+          'message' => message,
+          'data' => data,
+          'image' => image
+        }
+      )
+    end
+
+    def close_task(status = SUCCESS)
+      send_notification(
+        'method' => 'task.close',
+        'params' => {
+          'status' => status
+        }
+      )
+
+      exit(status == SUCCESS ? 0 : 1)
+    end
+
+    def update_task(status = PROCESSING)
+      send_notification(
+        'method' => 'task.update',
+        'params' => {
+          'status' => status
+        }
+      )
+    end
+
+    def get_task
+      send_request('method' => 'task.get')
+    end
+
+    def return_task
+      send_notification('method' => 'task.return')
+      exit(0)
+    end
+
+    def graphql(query, variables = nil)
+      send_request(
+        'method' => 'eywa.datasets.graphql',
+        'params' => {
+          'query' => query,
+          'variables' => variables
+        }
+      )
+    end
+
+    private
+
+    def handle_data(data)
+      method = data['method']
+      id = data['id']
+      result = data['result']
+      error = data['error']
+
+      if method
+        handle_request(data)
+      elsif (result || error) && id
+        handle_response(data)
+      else
+        STDERR.puts("Received invalid JSON-RPC:\n#{data}")
+      end
+    end
+
+    def handle_request(data)
+      method = data['method']
+      
+      @mutex.synchronize do
+        handler = @handlers[method]
+        if handler
+          handler.call(data)
+        else
+          STDERR.puts("Method #{method} doesn't have registered handler")
+        end
+      end
+    end
+
+    def handle_response(data)
+      id = data['id']
+      
+      @mutex.synchronize do
+        queue = @rpc_callbacks[id]
+        if queue
+          queue.push(data)
+        else
+          STDERR.puts("RPC callback not registered for request with id = #{id}")
+        end
+      end
+    end
+  end
+
+  # Convenience module for global access
+  module GlobalClient
+    extend self
+
+    def client
+      @client ||= Client.new
+    end
+
+    # Delegate all methods to the client instance
+    def method_missing(method_name, *args, **kwargs, &block)
+      if client.respond_to?(method_name)
+        client.send(method_name, *args, **kwargs, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      client.respond_to?(method_name, include_private) || super
+    end
+  end
+end
+
+# For backward compatibility and ease of use
+include Eywa::GlobalClient
+
+# Export constants for easy access
+SUCCESS = Eywa::SUCCESS
+ERROR = Eywa::ERROR
+PROCESSING = Eywa::PROCESSING
+EXCEPTION = Eywa::EXCEPTION

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: eywa-client
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Robert Gersak
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-06-06 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: 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: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A Ruby gem that provides a client for EYWA server with JSON-RPC communication,
+  GraphQL support, and task management.
+email:
+- robi@neyho.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/eywa.rb
+homepage: https://github.com/neyho/eywa
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/neyho/eywa
+  source_code_uri: https://github.com/neyho/eywa
+  changelog_uri: https://github.com/neyho/eywa/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: EYWA client for asynchronous communication with EYWA server
+test_files: []