ruby-you 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 542555c1df3a5af0c3f0d7450d334ba2e2daf4b803f9a0786f16d5f3b07befb4
+  data.tar.gz: 01054bcce46bff8b1a124565c7101dffdd12b23e41f4bc22cb26d66bf6db91ad
+SHA512:
+  metadata.gz: f013e19f9caea16b43191e4b9141d73ad67365ef6b434b4e8d7daa7ca9513ef72f7ec5156cdff3802ab4aba40e7cb7e757bc0636cf3e2d7f4c59c3cd0b1c37a3
+  data.tar.gz: 4feac155583bf3f567205dd77f2aa86fd55ca0a42a4631b6f34f130924ce1b13108c3787acd00c3fe8a0625cde52c723c3ec423603ba903a68385202ac1cf80a

data/README.md

@@ -0,0 +1,175 @@
+# ruby-you
+
+|  Tests |  Coverage  |
+|:-:|:-:|
+| [![Tests](https://github.com/arkimedes-dev/ruby-you/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/arkimedes-dev/ruby-you/actions/workflows/main.yml)  |  [![Codecov Coverage](https://codecov.io/github/arkimedes-dev/ruby-you/graph/badge.svg?token=SKTT14JJGV)](https://codecov.io/github/arkimedes-dev/ruby-you) |
+
+
+A Ruby client for interacting with the You.com API, including the Smart, Research, Search, and News endpoints. This gem provides a simple and consistent interface, along with configurable retry logic, rate-limit handling, debugging options, and comprehensive error handling.
+
+## Features
+
+- **Smart API**: Send queries to `https://chat-api.you.com/smart`.
+- **Research API**: Send queries to `https://chat-api.you.com/research`.
+- **Search API**: Query `https://api.ydc-index.io/search` for web search results.
+- **News API**: Query `https://api.ydc-index.io/news` for news results.
+
+## Requirements
+
+- Ruby 2.6 or higher.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby-you'
+```
+
+Then execute
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem build ruby-you.gemspec
+gem install ruby-you-0.1.1.gem
+```
+
+## Configuration
+
+The client requires an API key. You can provide this as an environment variable YOU_API_KEY or pass it directly when initializing the client.
+
+You can also configure logging and debugging:
+
+```rb
+require 'you'
+
+You.configure do |config|
+  config.debug = true                  # enable debug mode for verbose logging
+  config.logger = Logger.new($stdout)  # customize the logger, defaults to $stdout with WARN level
+end
+```
+
+## Usage
+
+```rb
+require 'you'
+
+client = You.client(api_key: "YOUR_API_KEY")
+
+# Smart API
+response = client.smart(query: "What is the capital of France?", instructions: "Respond in bullet points.")
+puts response["answer"]
+
+# Research API
+research_result = client.research(query: "Explain quantum computing in simple terms")
+puts research_result["answer"]
+
+# Search API
+search_result = client.search(query: "Ruby programming", num_web_results: 5, safesearch: "moderate")
+puts search_result["hits"]
+
+# News API
+news_result = client.news(query: "latest tech news", count: 5, recency: "day")
+puts news_result["news"]["results"]
+```
+
+## Endpoints and Parameters
+
+### Smart API (POST /smart)
+
+- query (String, required)
+- chat_id (String, optional)
+- instructions (String, optional)
+
+### Research API (POST /research)
+
+- query (String, required)
+- chat_id (String, optional)
+
+### Search API (GET /search)
+
+- query (String, required)
+- num_web_results (Integer, optional)
+- offset (Integer, optional)
+- country (String, optional)
+- safesearch (String, optional, defaults to moderate)
+
+### News API (GET /news)
+
+- query (String, required)
+- count (Integer, optional)
+- offset (Integer, optional)
+- country (String, optional)
+- search_lang (String, optional)
+- ui_lang (String, optional)
+- safesearch (String, optional)
+- spellcheck (Boolean, optional)
+- recency (String, optional: day, week, month, year)
+
+### Error Handling
+
+The client raises custom exceptions for non-200 responses:
+
+- You::BadRequestError (400)
+- You::UnauthorizedError (401)
+- You::ForbiddenError (403)
+- You::NotFoundError (404)
+- You::UnprocessableEntityError (422)
+- You::RateLimitError (429)
+- You::InternalServerError (500)
+- You::BadGatewayError (502)
+- You::ServiceUnavailableError (503)
+- You::GatewayTimeoutError (504)
+- You::Error for all other errors.
+
+Rate-limit errors (429) are retried up to max_retries times with an exponential backoff or a Retry-After delay if provided by the server.
+
+### Debugging and Logging
+
+Set `You.configuration.debug = true` to enable detailed logs of requests and responses. These logs include:
+
+- Outgoing request method, URL, and parameters.
+- Response status code, headers, and body.
+
+You can customize the logger with You.configuration.logger.
+
+## Testing
+
+This gem uses RSpec and WebMock for testing.
+
+Install the dependencies:
+
+```bash
+bundle install
+```
+
+Run the tests:
+
+```bash
+rspec
+```
+
+The test suite covers:
+
+- Successful requests
+- Various error responses and the corresponding exceptions
+- Rate-limit handling and retry logic
+- Debug/logging functionality
+
+## Contributing
+
+- Fork the project
+- Create a new feature branch (git checkout -b feature/my-feature)
+- Commit your changes (git commit -m 'Add new feature')
+- Push to the branch (git push origin feature/my-feature)
+- Create a new Pull Request
+- Release the gem: `bundle exec rake release`
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.txt](https://github.com/arkimedes-dev/ruby-you/blob/main/LICENSE.txt) file for details.

data/lib/you/client.rb

@@ -0,0 +1,140 @@
+require "you/error"
+require "uri"
+require "faraday"
+require "faraday/retry"
+
+module You
+  class Client
+    SMART_API_BASE_URL = "https://chat-api.you.com".freeze
+    SEARCH_API_BASE_URL = "https://api.ydc-index.io".freeze
+
+    attr_accessor :api_key, :max_retries, :initial_wait_time
+
+    def initialize(api_key: nil, max_retries: 3, initial_wait_time: 1)
+      @api_key = api_key || ENV["YOU_API_KEY"]
+
+      raise You::Error, "No API key provided. Set YOU_API_KEY env or pass api_key." unless @api_key
+
+      @max_retries = max_retries
+      @initial_wait_time = initial_wait_time
+    end
+
+    # SMART Endpoint
+    def smart(query:, chat_id: nil, instructions: nil)
+      post("#{SMART_API_BASE_URL}/smart", {query: query, chat_id: chat_id, instructions: instructions}.compact)
+    end
+
+    # RESEARCH Endpoint
+    def research(query:, chat_id: nil)
+      post("#{SMART_API_BASE_URL}/research", {query: query, chat_id: chat_id}.compact)
+    end
+
+    # SEARCH Endpoint (GET)
+    def search(query:, **params)
+      get("#{SEARCH_API_BASE_URL}/search", {query: query}.merge(params))
+    end
+
+    # NEWS Endpoint (GET)
+    def news(query:, **params)
+      get("#{SEARCH_API_BASE_URL}/news", {query: query}.merge(params))
+    end
+
+    private
+
+    def connection(base_url)
+      Faraday.new(base_url) do |faraday|
+        faraday.request :json
+        faraday.response :json
+
+        # If debug mode is on, we add a Faraday logger middleware that outputs to You.configuration.logger
+        if You.configuration.debug
+          faraday.response :logger, You.configuration.logger, {bodies: true}
+        end
+
+        # Retries a request after refreshing the token if we get an UnauthorizedError
+        faraday.request :retry, {
+          retry_statuses: [429, 500, 502, 503, 504],
+          methods: [:get, :post],
+          max: max_retries,
+          interval_randomness: 0.5,
+          interval: initial_wait_time,
+          backoff_factor: 2
+        }
+
+        faraday.adapter Faraday.default_adapter
+        faraday.headers["X-API-Key"] = @api_key
+      end
+    end
+
+    def get(url, params = {})
+      log_request("GET", url, params)
+      resp = connection(base_url(url)).get do |req|
+        req.url endpoint_path(url)
+        req.params.update(params)
+      end
+      handle_response(resp)
+    end
+
+    def post(url, payload)
+      log_request("POST", url, payload)
+      resp = connection(base_url(url)).post do |req|
+        req.url endpoint_path(url)
+        req.body = payload
+      end
+      handle_response(resp)
+    end
+
+    def handle_response(response)
+      log_response(response)
+      case response.status
+      when 200
+        response.body
+      when 400
+        raise You::BadRequestError, "Bad Request: #{response.body}"
+      when 401
+        raise You::UnauthorizedError, "Unauthorized: #{response.body}"
+      when 403
+        raise You::ForbiddenError, "Forbidden: #{response.body}"
+      when 404
+        raise You::NotFoundError, "Not Found: #{response.body}"
+      when 422
+        raise You::UnprocessableEntityError, "Unprocessable Entity: #{response.body}"
+      when 429
+        retry_after = response.headers["Retry-After"]
+        msg = "Rate Limit Reached: #{response.body}"
+        msg << " (Retry-After: #{retry_after})" if retry_after
+        raise You::RateLimitError, msg
+      when 500
+        raise You::InternalServerError, "Internal Server Error: #{response.body}"
+      when 502
+        raise You::BadGatewayError, "Bad Gateway: #{response.body}"
+      when 503
+        raise You::ServiceUnavailableError, "Service Unavailable: #{response.body}"
+      when 504
+        raise You::GatewayTimeoutError, "Gateway Timeout: #{response.body}"
+      else
+        raise You::Error, "Request failed with status #{response.status}: #{response.body}"
+      end
+    end
+
+    def base_url(full_url)
+      uri = URI(full_url)
+      "#{uri.scheme}://#{uri.host}"
+    end
+
+    def endpoint_path(full_url)
+      uri = URI(full_url)
+      uri.path
+    end
+
+    def log_request(method, url, params_or_body)
+      return unless You.configuration.debug
+      You.configuration.logger.info("You API Request: #{method} #{url} with #{params_or_body}")
+    end
+
+    def log_response(response)
+      return unless You.configuration.debug
+      You.configuration.logger.info("You API Response: Status #{response.status}, Headers: #{response.headers}, Body: #{response.body}")
+    end
+  end
+end

data/lib/you/configuration.rb

@@ -0,0 +1,13 @@
+require "logger"
+
+module You
+  class Configuration
+    attr_accessor :logger, :debug
+
+    def initialize
+      @logger = Logger.new($stdout)
+      @logger.level = Logger::WARN
+      @debug = false
+    end
+  end
+end

data/lib/you/error.rb

@@ -0,0 +1,23 @@
+module You
+  class Error < StandardError; end
+
+  class BadRequestError < Error; end          # 400
+
+  class UnauthorizedError < Error; end        # 401
+
+  class ForbiddenError < Error; end           # 403
+
+  class NotFoundError < Error; end            # 404
+
+  class UnprocessableEntityError < Error; end # 422
+
+  class RateLimitError < Error; end           # 429
+
+  class InternalServerError < Error; end      # 500
+
+  class BadGatewayError < Error; end          # 502
+
+  class ServiceUnavailableError < Error; end  # 503
+
+  class GatewayTimeoutError < Error; end      # 504
+end

data/lib/you/version.rb

@@ -0,0 +1,3 @@
+module You
+  VERSION = "0.1.1".freeze
+end

data/lib/you.rb

@@ -0,0 +1,20 @@
+require "you/version"
+require "you/configuration"
+require "you/client"
+
+module You
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # A convenience method to access a default client directly
+    def client
+      @client ||= You::Client.new
+    end
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: ruby-you
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Martin Mochetti
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  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: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.17'
+description: Provides a simple Ruby interface for interacting with the You.com Smart,
+  Research, Search, and News endpoints.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/you.rb
+- lib/you/client.rb
+- lib/you/configuration.rb
+- lib/you/error.rb
+- lib/you/version.rb
+homepage: https://github.com/arkimedes-dev/ruby-you
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/arkimedes-dev/ruby-you
+  source_code_uri: https://github.com/arkimedes-dev/ruby-you
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: A Ruby client for the You.com API.
+test_files: []