langgraph-platform 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 531a708f8f8929dd7f1e7199b22db36a44fbf247a5f112a4369747f80bb23a7e
+  data.tar.gz: 5aa0040571033f2e6df926d2056c4be0435de08c411c912bd16fb77e27a79afe
+SHA512:
+  metadata.gz: b89d5aebdb0946e58e43d01324cf4126b683aa523d562907e2f89bb6bdf3cef4bcbac88474268283bf856ace40101cc068cc352016fe155a7537abce53263608
+  data.tar.gz: c2ccfa1cff88be79ac0f605c2193b782af89fd253987bbf61bdfd3d1a1a023ab7cc55e537bd80920fc5a1f5958366af8d5a175d331ba095a18d0735a36fb94f8

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-01-01
+
+### Added
+- Initial release of the LangGraph Platform Ruby SDK
+- Complete API client implementation for LangGraph Platform
+- Support for all major resources:
+  - Assistants (create, read, update, delete, search)
+  - Threads (create, read, update, delete, state management)
+  - Runs (create, stream, wait, list, cancel)
+  - Crons (create, read, update, delete, enable/disable)
+  - Store (get, put, delete, list, batch operations)
+  - MCP (tools, resources, prompts, logging)
+- Server-Sent Events (SSE) streaming support
+- Comprehensive error handling with specific error classes
+- Request validation and parameter sanitization
+- Retry mechanism with exponential backoff
+- Configuration management with environment variable support
+- Full test suite with RSpec, VCR, and WebMock
+- Documentation with YARD
+- Usage examples for basic, streaming, and advanced workflows
+- Ruby 2.7+ compatibility
+- Thread-safe operations
+- Zeitwerk autoloading
+
+### Dependencies
+- faraday (~> 2.0) - HTTP client
+- faraday-net_http (~> 3.0) - HTTP adapter
+- multi_json (~> 1.15) - JSON parsing
+- zeitwerk (~> 2.6) - Code loading
+
+### Development Dependencies
+- rspec (~> 3.12) - Testing framework
+- vcr (~> 6.0) - HTTP interaction recording
+- webmock (~> 3.18) - HTTP request stubbing
+- rubocop (~> 1.50) - Code linting
+- yard (~> 0.9) - Documentation generation
+- pry (~> 0.14) - Debugging 

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gys Muller
+
+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,406 @@
+# LangGraph Platform Ruby SDK
+
+An unoffical Ruby SDK for interacting with the [LangGraph Platform API](https://langchain-ai.github.io/langgraph/cloud/reference/api/api_ref.html). This gem provides a Ruby-idiomatic interface for managing assistants, threads, runs, crons, store operations, and Model Context Protocol (MCP) interactions.
+
+## Current Status
+
+This is a work in progress. The SDK is not yet complete and fully tested.
+
+## Roadmap
+
+- [x] Assistants
+- [x] Threads
+- [x] Runs
+- [ ] Crons
+- [ ] Store Operations
+- [ ] Model Context Protocol (MCP)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'langgraph-platform'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install langgraph-platform
+```
+
+## Quick Start
+
+```ruby
+require 'langgraph_platform'
+
+# Initialize the client
+client = LanggraphPlatform::Client.new(
+  api_key: 'your-api-key-here',
+  base_url: 'https://api.langchain.com' # For local development, use http://127.0.0.1:2024
+)
+
+# Create an assistant
+assistant = client.assistants.create(
+  graph_id: 'my-graph',
+  name: 'My Assistant',
+  config: { recursion_limit: 10 }
+)
+
+# Create a thread
+thread = client.threads.create(
+  metadata: { user_id: 'user123' }
+)
+
+# Run the assistant
+run = client.runs.create(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Hello, world!' }
+)
+
+puts "Run status: #{run.status}"
+```
+
+## Configuration
+
+### Environment Variables
+
+The SDK can be configured using environment variables:
+
+- `LANGGRAPH_API_KEY`: Your LangGraph Platform API key (use fake-api-key for local development)
+- `LANGGRAPH_BASE_URL`: Custom base URL (defaults to `https://api.langchain.com`)
+
+### Client Configuration
+
+```ruby
+client = LanggraphPlatform::Client.new(
+  api_key: 'your-api-key',
+  base_url: 'https://custom-api.example.com',
+  timeout: 30,
+  retries: 3
+)
+
+# Or configure after initialization
+client.configure do |config|
+  config.timeout = 60
+  config.retries = 5
+end
+```
+
+## Features
+
+### Assistants
+
+```ruby
+# Create an assistant
+assistant = client.assistants.create(
+  graph_id: 'my-graph',
+  name: 'My Assistant',
+  config: { recursion_limit: 10 },
+  metadata: { version: '1.0' }
+)
+
+# Find an assistant
+assistant = client.assistants.find('assistant-id')
+
+# Search assistants
+assistants = client.assistants.search(
+  metadata: { version: '1.0' },
+  limit: 10
+)
+
+# Update an assistant
+client.assistants.update('assistant-id', name: 'Updated Name')
+
+# Delete an assistant
+client.assistants.delete('assistant-id')
+```
+
+### Threads
+
+```ruby
+# Create a thread
+thread = client.threads.create(
+  metadata: { user_id: 'user123' }
+)
+
+# Get thread state
+state = client.threads.state(thread.thread_id)
+
+# Update thread state
+client.threads.update_state(
+  thread.thread_id,
+  values: { key: 'value' }
+)
+
+# Get thread history
+history = client.threads.history(thread.thread_id, limit: 10)
+
+# Search threads
+threads = client.threads.search(
+  status: 'idle',
+  limit: 10
+)
+```
+
+### Runs
+
+```ruby
+# Create a run
+run = client.runs.create(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Hello!' }
+)
+
+# Create a run with webhook
+run = client.runs.create(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Hello!' },
+  webhook: 'https://your-app.com/webhooks/langgraph'
+)
+
+# Stream a run
+client.runs.stream(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Hello!' }
+) do |type, data, id, reconnection_time|
+  puts "Event: #{type}, Data: #{data}"
+end
+
+# Stream a run with webhook
+client.runs.stream(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Hello!' },
+  webhook: 'https://your-app.com/webhooks/langgraph'
+) do |type, data, id, reconnection_time|
+  puts "Event: #{type}, Data: #{data}"
+end
+
+# Wait for a run to complete
+result = client.runs.wait(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Hello!' }
+)
+
+# Wait for a run with webhook
+result = client.runs.wait(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Hello!' },
+  webhook: 'https://your-app.com/webhooks/langgraph'
+)
+
+# List runs
+runs = client.runs.list(thread.thread_id)
+
+# Cancel a run
+client.runs.cancel(thread.thread_id, run.run_id)
+```
+
+### Crons
+
+**Under development and untested.**
+
+```ruby
+# Create a cron job
+cron = client.crons.create(
+  assistant_id: assistant.assistant_id,
+  schedule: '0 */6 * * *', # Every 6 hours
+  payload: { task: 'periodic_task' }
+)
+
+# List cron jobs
+crons = client.crons.list(assistant_id: assistant.assistant_id)
+
+# Enable/disable cron jobs
+client.crons.enable(cron.cron_id)
+client.crons.disable(cron.cron_id)
+```
+
+### Store Operations
+
+**Under development and untested.**
+
+```ruby
+# Store data
+client.store.put('namespace', 'key', { data: 'value' })
+
+# Retrieve data
+item = client.store.get('namespace', 'key')
+
+# List items in namespace
+items = client.store.list('namespace', prefix: 'user_')
+
+# Delete data
+client.store.delete('namespace', 'key')
+
+# Batch operations
+client.store.batch_put([
+  { namespace: 'ns1', key: 'key1', value: 'value1' },
+  { namespace: 'ns1', key: 'key2', value: 'value2' }
+])
+```
+
+### Model Context Protocol (MCP)
+
+**Under development and untested.**
+
+```ruby
+# List available tools
+tools = client.mcp.list_tools
+
+# Call a tool
+result = client.mcp.call_tool(
+  'tool_name',
+  arguments: { param: 'value' }
+)
+
+# List resources
+resources = client.mcp.list_resources
+
+# Read a resource
+content = client.mcp.read_resource('resource://example')
+
+# Work with prompts
+prompts = client.mcp.list_prompts
+result = client.mcp.complete_prompt('prompt_name', arguments: {})
+```
+
+## Webhooks
+
+The SDK supports webhooks that are called after LangGraph API calls complete. Webhooks can be used with any run creation method:
+
+```ruby
+# Thread-based runs with webhooks
+run = client.runs.create(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Process this data' },
+  webhook: 'https://your-app.com/webhooks/langgraph'
+)
+
+# Stateless runs with webhooks
+client.runs.create_stateless(
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Process this data' },
+  webhook: 'https://your-app.com/webhooks/langgraph'
+)
+
+# Streaming runs with webhooks
+client.runs.stream(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Process this data' },
+  webhook: 'https://your-app.com/webhooks/langgraph'
+) do |type, data, id, reconnection_time|
+  # Handle streaming events
+end
+```
+
+**Webhook Requirements:**
+- Must be a valid URI (up to 65,536 characters)
+- Should handle HTTP POST requests from LangGraph Platform
+- Called after the API call completes
+
+## Streaming
+
+The SDK supports Server-Sent Events (SSE) streaming for real-time responses. Streaming blocks receive four parameters directly from the SSE parser:
+
+- `type`: Event type (e.g., 'messages/partial', 'updates', 'values', 'error')
+- `data`: Parsed JSON data or raw string content
+- `id`: Event ID (optional)
+- `reconnection_time`: SSE reconnection time in milliseconds (optional)
+
+```ruby
+client.runs.stream(
+  thread.thread_id,
+  assistant_id: assistant.assistant_id,
+  input: { message: 'Tell me a story' }
+) do |type, data, id, reconnection_time|
+  case type
+  when 'data'
+    puts "Data: #{data}"
+  when 'message'
+    puts "Message: #{data}"
+  when 'error'
+    puts "Error: #{data}"
+  when 'end'
+    puts "Stream ended"
+  end
+end
+```
+
+## Error Handling
+
+The SDK provides specific error classes for different API errors:
+
+```ruby
+begin
+  assistant = client.assistants.find('nonexistent-id')
+rescue LanggraphPlatform::Errors::NotFoundError => e
+  puts "Assistant not found: #{e.message}"
+rescue LanggraphPlatform::Errors::UnauthorizedError => e
+  puts "Authentication failed: #{e.message}"
+rescue LanggraphPlatform::Errors::APIError => e
+  puts "API error: #{e.message}"
+end
+```
+
+Available error classes:
+- `LanggraphPlatform::Errors::APIError` - Base error class
+- `LanggraphPlatform::Errors::BadRequestError` - 400 errors
+- `LanggraphPlatform::Errors::UnauthorizedError` - 401 errors
+- `LanggraphPlatform::Errors::NotFoundError` - 404 errors
+- `LanggraphPlatform::Errors::ConflictError` - 409 errors
+- `LanggraphPlatform::Errors::ValidationError` - 422 errors
+- `LanggraphPlatform::Errors::ServerError` - 500+ errors
+
+## Examples
+
+Check out the `examples/` directory for more comprehensive examples:
+
+- `examples/basic_usage.rb` - Basic CRUD operations
+- `examples/streaming_example.rb` - Streaming functionality
+
+## Development
+
+To run the tests:
+
+```bash
+$ bundle exec rspec
+```
+
+To run RuboCop:
+
+```bash
+$ bundle exec rubocop
+```
+
+## Acknowledgments
+
+- Thanks to the LangGraph team for their work on the SDKs and for providing the API reference.
+- Thanks to the Shopify team for [event_stream_parser gem](https://github.com/shopify/event_stream_parser).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/gysmuller/langgraph-platform.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes. 

data/lib/langgraph_platform/base_client.rb

@@ -0,0 +1,146 @@
+module LanggraphPlatform
+  class BaseClient
+    def initialize(configuration)
+      @configuration = configuration
+      @http_client = build_http_client
+    end
+
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    def patch(path, body = {})
+      request(:patch, path, body: body)
+    end
+
+    def put(path, body = {})
+      request(:put, path, body: body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    def stream(path, body = {}, &block)
+      response = @http_client.headers(
+        'Accept' => 'text/event-stream',
+        'Cache-Control' => 'no-cache'
+      ).timeout(@configuration.timeout).post("#{@configuration.base_url}#{path}", json: body)
+
+      if block_given?
+        stream_events(response, &block)
+      else
+        response
+      end
+    rescue HTTP::Error => e
+      raise Errors::APIError, "Stream request failed: #{e.message}"
+    end
+
+    private
+
+    def stream_events(response, &block)
+      parser = EventStreamParser::Parser.new
+
+      response.body.each do |chunk|
+        parser.feed(chunk) do |type, data, id, reconnection_time|
+          # Parse JSON data if present
+          parsed_data = parse_data_safely(data)
+
+          # Pass parameters directly to block
+          block.call(type, parsed_data, id, reconnection_time)
+        end
+      end
+    rescue StandardError => e
+      warn "Error processing SSE stream: #{e.message}" if @configuration.debug
+      raise
+    end
+
+    def parse_data_safely(data_string)
+      return data_string if data_string.nil? || data_string.empty?
+
+      MultiJson.load(data_string)
+    rescue MultiJson::ParseError
+      # Return as string if JSON parsing fails
+      data_string
+    end
+
+    def build_http_client
+      HTTP.headers(
+        'Authorization' => "Bearer #{@configuration.api_key}",
+        'User-Agent' => @configuration.user_agent,
+        'Content-Type' => 'application/json'
+      ).timeout(@configuration.timeout)
+    end
+
+    def request(method, path, params: {}, body: {})
+      retries = 0
+
+      begin
+        url = "#{@configuration.base_url}#{path}"
+        response = case method
+                   when :get
+                     @http_client.get(url, params: params)
+                   when :post
+                     @http_client.post(url, json: body)
+                   when :patch
+                     @http_client.patch(url, json: body)
+                   when :put
+                     @http_client.put(url, json: body)
+                   when :delete
+                     @http_client.delete(url)
+                   end
+
+        handle_response(response)
+      rescue HTTP::Error => e
+        retries += 1
+        unless retries <= @configuration.retries
+          raise Errors::APIError, "HTTP request failed after #{@configuration.retries} retries: #{e.message}"
+        end
+
+        sleep(2**retries)
+        retry
+      end
+    end
+
+    def handle_response(response) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+      case response.status
+      when 200..299
+        # Handle empty responses (e.g., 204 No Content)
+        return nil if response.body.nil? || response.body.empty?
+
+        response.parse
+      when 400
+        raise Errors::BadRequestError, extract_error_message(response)
+      when 401
+        raise Errors::UnauthorizedError, extract_error_message(response)
+      when 404
+        raise Errors::NotFoundError, extract_error_message(response)
+      when 409
+        raise Errors::ConflictError, extract_error_message(response)
+      when 422
+        raise Errors::ValidationError, extract_error_message(response)
+      when 500..599
+        raise Errors::ServerError, extract_error_message(response)
+      else
+        raise Errors::APIError, "Unexpected response status: #{response.status}"
+      end
+    end
+
+    def extract_error_message(response)
+      body = response.parse
+      if body.is_a?(Hash) && body['error']
+        body['error']
+      elsif body.is_a?(Hash) && body['message']
+        body['message']
+      else
+        body.to_s
+      end
+    rescue StandardError
+      response.to_s
+    end
+  end
+end

data/lib/langgraph_platform/client.rb

@@ -0,0 +1,42 @@
+module LanggraphPlatform
+  class Client
+    attr_reader :assistants, :threads, :runs, :crons, :store, :mcp, :configuration
+
+    def initialize(api_key: nil, base_url: nil, **options)
+      @configuration = Configuration.new(api_key: api_key, base_url: base_url)
+      @configuration.timeout = options[:timeout] if options[:timeout]
+      @configuration.retries = options[:retries] if options[:retries]
+      @configuration.user_agent = options[:user_agent] if options[:user_agent]
+
+      validate_configuration!
+
+      @http_client = BaseClient.new(@configuration)
+
+      initialize_resources
+    end
+
+    def configure
+      yield(@configuration) if block_given?
+      @http_client = BaseClient.new(@configuration)
+      initialize_resources
+    end
+
+    private
+
+    def validate_configuration!
+      return if @configuration.valid?
+
+      raise Errors::UnauthorizedError,
+            'API key is required. Set it via the api_key parameter or LANGGRAPH_API_KEY environment variable.'
+    end
+
+    def initialize_resources
+      @assistants = Resources::Assistants.new(@http_client)
+      @threads = Resources::Threads.new(@http_client)
+      @runs = Resources::Runs.new(@http_client)
+      @crons = Resources::Crons.new(@http_client)
+      @store = Resources::Store.new(@http_client)
+      @mcp = Resources::Mcp.new(@http_client)
+    end
+  end
+end

data/lib/langgraph_platform/configuration.rb

@@ -0,0 +1,17 @@
+module LanggraphPlatform
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :retries, :user_agent
+
+    def initialize(api_key: nil, base_url: nil)
+      @api_key = api_key || ENV.fetch('LANGGRAPH_API_KEY', nil)
+      @base_url = base_url || ENV['LANGGRAPH_BASE_URL'] || 'https://api.langchain.com'
+      @timeout = 30
+      @retries = 3
+      @user_agent = "langgraph-platform-ruby/#{VERSION}"
+    end
+
+    def valid?
+      !@api_key.nil? && !@api_key.empty?
+    end
+  end
+end