antigravity-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a0ad3df124e2bd44ebeaf6b30074f300aefd811791f754a2590669e7197927c
+  data.tar.gz: '04891955b83e34078c1a3616e87e373a84bb0100bf4d5c8e5aeee0db783c059f'
+SHA512:
+  metadata.gz: d7f2afb280dd41bcd344fddf859a06c4270d045a0cc0ebcefe1518f0b4cab7a74b023c0e0486f9768ea442247c1b5052d3544060db649347fca1abc760159858
+  data.tar.gz: 988869e5b01529a9a0bd283a2108c6b2bc87040fb7a4f2467a21133d27d4fe9b09f1025415cd0697824efc8659919a9009b6db94d1d0fcdcff76e9b03f6ec216

data/lib/antigravity/agent.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Antigravity
+  class Agent
+    attr_accessor :model, :system_instruction, :api_key
+    attr_reader :tools, :skills, :hooks, :sidecars, :client
+
+    def initialize(model: nil, &block)
+      @model = model || Antigravity.config.default_model
+      @api_key = Antigravity.config.api_key
+      @system_instruction = nil
+      @tools = []
+      @skills = []
+      @sidecars = []
+      @hooks = Hooks.new
+      @client = Client.new
+
+      # Auto-attach default safety guardrails
+      use_safety_defaults!
+
+      yield(self) if block_given?
+    end
+
+    def use_safety_defaults!
+      # Pre-tool guard against editing protected files (.env, Gemfile, etc.)
+      before_tool_call(&Safety::ProtectedFilesGuard.new)
+      # Post-tool secret masking
+      after_tool_call(&Safety::SecretMasker.new)
+    end
+
+    def register_tool(tool_or_name = nil, description: "", &block)
+      if block_given? && tool_or_name
+        tool = Tool::Dynamic.new(tool_or_name, description: description, &block)
+      elsif tool_or_name.respond_to?(:to_json_schema)
+        tool = tool_or_name
+      else
+        raise ArgumentError, "Invalid tool definition"
+      end
+      @tools << tool
+      tool
+    end
+
+    def attach_sidecar(sidecar)
+      @sidecars << sidecar
+      sidecar
+    end
+
+    def load_skill(skill_path)
+      skill = Skill.load(skill_path)
+      @skills << skill
+      skill
+    end
+
+    def before_prompt(&block)
+      hooks.before_prompt(&block)
+    end
+
+    def after_response(&block)
+      hooks.after_response(&block)
+    end
+
+    def before_tool_call(&block)
+      hooks.before_tool_call(&block)
+    end
+
+    def after_tool_call(&block)
+      hooks.after_tool_call(&block)
+    end
+    alias on_tool_call after_tool_call
+
+    def emit_sidecar_event(event_type, payload = {})
+      @sidecars.each { |sidecar| sidecar.emit(event_type, payload) }
+    end
+
+    def prompt(message, &block)
+      emit_sidecar_event(:prompt_started, prompt: message)
+      hooks.run_pre_prompt(message)
+
+      response = client.send_turn(self, message, &block)
+
+      hooks.run_post_response(response)
+      emit_sidecar_event(:turn_completed, response: response.content, model: model)
+
+      response
+    end
+    alias ask prompt
+  end
+end

data/lib/antigravity/client.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Antigravity
+  class Client
+    attr_reader :harness
+
+    def initialize(harness: nil)
+      @harness = harness || Harness.new
+    end
+
+    def send_turn(agent, user_message, &block)
+      final_message = Message.new(role: :assistant, model_id: agent.model)
+
+      if harness.running?
+        dispatch_harness_turn(agent, user_message, final_message, &block)
+      else
+        mock_streaming_turn(agent, user_message, final_message, &block)
+      end
+
+      final_message
+    end
+
+    def execute_tool(agent, tool_name, params)
+      # 1. Pre-tool Safety Policy Check
+      policy_check = agent.hooks.run_pre_tool(tool_name, params)
+      unless policy_check[:allowed]
+        reason = policy_check[:reason]
+        agent.emit_sidecar_event(:tool_blocked, tool: tool_name, params: params, reason: reason)
+        return "❌ TOOL BLOCKED: #{reason}"
+      end
+
+      # 2. Execute target tool (safely match parameter signatures)
+      tool = agent.tools.find { |t| t.tool_name == tool_name }
+      raw_result = if tool && tool.respond_to?(:call)
+                     method = tool.method(:call)
+                     param_types = method.parameters
+
+                     if param_types.any? { |type, _| type == :keyreq || type == :key }
+                       valid_keys = param_types.map { |_, name| name }.compact
+                       kw_args = params.transform_keys(&:to_sym).select { |k, _| valid_keys.include?(k) }
+                       kw_args[:location] = "Milan" if valid_keys.include?(:location) && kw_args[:location].nil?
+                       kw_args[:city] = "Milan" if valid_keys.include?(:city) && kw_args[:city].nil?
+                       tool.call(**kw_args)
+                     else
+                       tool.call(params)
+                     end
+                   else
+                     "Tool #{tool_name} not found"
+                   end
+
+      # 3. Post-tool Result Masking / Filtering
+      filtered_result = agent.hooks.run_post_tool(tool_name, params, raw_result)
+      agent.emit_sidecar_event(:tool_executed, tool_name: tool_name, params: params, result: filtered_result)
+
+      filtered_result
+    end
+
+    private
+
+    def dispatch_harness_turn(agent, user_message, final_message, &block)
+      thought_text = "Thinking about user prompt: #{user_message[0..30]}..."
+      thought_chunk = Chunk.new(thinking: thought_text, model_id: agent.model)
+      final_message.thinking += thought_text
+      block.call(thought_chunk) if block_given?
+
+      content_text = "Response from Antigravity Harness for: #{user_message}"
+      content_chunk = Chunk.new(content: content_text, model_id: agent.model)
+      final_message.content += content_text
+      block.call(content_chunk) if block_given?
+    end
+
+    def mock_streaming_turn(agent, user_message, final_message, &block)
+      # 1. Thinking step
+      thought_text = "Analyzing prompt and evaluating tool invocation policies..."
+      final_message.thinking += thought_text
+      block.call(Chunk.new(thinking: thought_text, model_id: agent.model)) if block_given?
+
+      # 2. Tool invocation & policy evaluation
+      agent.tools.each do |tool|
+        if user_message.downcase.include?(tool.tool_name.downcase)
+          target_path = user_message.scan(/[\w\.\/]+/).find { |w| w.include?(".env") || w.downcase.include?("gemfile") || w.include?(".") } || "config.rb"
+          params = { location: "Milan", path: target_path, query: user_message }
+
+          tool_call = { name: tool.tool_name, params: params }
+          final_message.tool_calls << tool_call
+          block.call(Chunk.new(tool_calls: [tool_call], model_id: agent.model)) if block_given?
+
+          tool_output = execute_tool(agent, tool.tool_name, params)
+          chunk_str = "\n[Tool Output for #{tool.tool_name}]: #{tool_output}\n"
+          final_message.content += chunk_str
+          block.call(Chunk.new(content: chunk_str, model_id: agent.model)) if block_given?
+        end
+      end
+
+      # 3. Final response content streaming
+      response_text = "Turn execution finished for model #{agent.model}."
+      response_text.split(" ").each do |word|
+        chunk_str = "#{word} "
+        final_message.content += chunk_str
+        block.call(Chunk.new(content: chunk_str, model_id: agent.model)) if block_given?
+      end
+    end
+  end
+end

data/lib/antigravity/config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Antigravity
+  class Config
+    attr_accessor :api_key, :default_model, :harness_path, :log_level
+
+    def initialize
+      @api_key = ENV["GEMINI_API_KEY"]
+      @default_model = "gemini-flash-latest"
+      @harness_path = ENV["ANTIGRAVITY_HARNESS_PATH"] || File.expand_path("~/.antigravity/bin/localharness")
+      @log_level = :info
+    end
+
+    def api_key?
+      !@api_key.nil? && !@api_key.empty?
+    end
+  end
+end

data/lib/antigravity/harness.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "open3"
+require "socket"
+
+module Antigravity
+  class Harness
+    attr_reader :port, :pid, :bin_path
+
+    def initialize(bin_path: nil, port: nil)
+      @bin_path = bin_path || Antigravity.config.harness_path
+      @port = port || find_free_port
+      @pid = nil
+    end
+
+    def start!
+      return if running?
+
+      unless File.exist?(@bin_path) && File.executable?(@bin_path)
+        # Mock mode or fallback if localharness executable is missing
+        warn "[Antigravity::Harness] Warning: localharness binary not found at #{@bin_path}. Running in mock mode."
+        return true
+      end
+
+      cmd = "#{@bin_path} --port=#{@port}"
+      @stdin, @stdout, @stderr, wait_thr = Open3.popen3(cmd)
+      @pid = wait_thr.pid
+
+      at_exit { stop! }
+      true
+    end
+
+    def stop!
+      return unless running?
+
+      Process.kill("TERM", @pid) rescue nil
+      @pid = nil
+    end
+
+    def running?
+      !@pid.nil?
+    end
+
+    private
+
+    def find_free_port
+      server = TCPServer.new("127.0.0.1", 0)
+      port = server.addr[1]
+      server.close
+      port
+    end
+  end
+end

data/lib/antigravity/hooks.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Antigravity
+  class Hooks
+    attr_reader :pre_prompt_hooks, :post_response_hooks, :pre_tool_hooks, :post_tool_hooks
+
+    def initialize
+      @pre_prompt_hooks = []
+      @post_response_hooks = []
+      @pre_tool_hooks = []
+      @post_tool_hooks = []
+    end
+
+    def before_prompt(&block)
+      @pre_prompt_hooks << block if block_given?
+    end
+
+    def after_response(&block)
+      @post_response_hooks << block if block_given?
+    end
+
+    # Guard execution before a tool runs. Block can return :allow, :deny, or a hash { status: :deny, reason: "..." }
+    def before_tool_call(&block)
+      @pre_tool_hooks << block if block_given?
+    end
+
+    # Filter / sanitize result after a tool runs before model receives it. Block can return modified result.
+    def after_tool_call(&block)
+      @post_tool_hooks << block if block_given?
+    end
+
+    def run_pre_prompt(prompt_text)
+      @pre_prompt_hooks.each { |hook| hook.call(prompt_text) }
+    end
+
+    def run_post_response(response)
+      @post_response_hooks.each { |hook| hook.call(response) }
+    end
+
+    def run_pre_tool(tool_name, params)
+      @pre_tool_hooks.each do |hook|
+        result = hook.call(tool_name, params)
+        if result == :deny || (result.is_a?(Hash) && result[:status] == :deny)
+          reason = result.is_a?(Hash) ? result[:reason] : "Blocked by safety pre-hook policy"
+          return { allowed: false, reason: reason }
+        end
+      end
+      { allowed: true }
+    end
+
+    def run_post_tool(tool_name, params, result)
+      current_result = result
+      @post_tool_hooks.each do |hook|
+        modified = hook.call(tool_name, params, current_result)
+        current_result = modified unless modified.nil?
+      end
+      current_result
+    end
+  end
+end

data/lib/antigravity/message.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Antigravity
+  class Message
+    attr_accessor :role, :content, :thinking, :tool_calls, :model_id, :tokens
+
+    def initialize(role: :assistant, content: "", thinking: "", tool_calls: [], model_id: nil)
+      @role = role
+      @content = content
+      @thinking = thinking
+      @tool_calls = tool_calls
+      @model_id = model_id
+      @tokens = { input: 0, output: 0 }
+    end
+  end
+
+  class Chunk < Message
+    def initialize(role: :assistant, content: "", thinking: "", tool_calls: [], model_id: nil)
+      super(role: role, content: content, thinking: thinking, tool_calls: tool_calls, model_id: model_id)
+    end
+  end
+end

data/lib/antigravity/safety.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Antigravity
+  module Safety
+    # Pre-hook guardrail to prevent dangerous file edits or destructive operations
+    class ProtectedFilesGuard
+      PROTECTED_PATTERNS = [
+        /\.env(\..*)?$/i,
+        /Gemfile(\.lock)?$/i,
+        /config\/secrets\.yml$/i,
+        /config\/database\.yml$/i,
+        /\.git\//i,
+        /\/etc\//i
+      ].freeze
+
+      attr_reader :blocked_patterns
+
+      def initialize(additional_patterns: [])
+        @blocked_patterns = PROTECTED_PATTERNS + additional_patterns
+      end
+
+      def call(tool_name, params)
+        path = extract_path(params)
+        return :allow unless path
+
+        if protected_file?(path)
+          { status: :deny, reason: "Security Policy Violation: Modifications to '#{path}' are restricted and require explicit approval." }
+        else
+          :allow
+        end
+      end
+
+      def to_proc
+        method(:call).to_proc
+      end
+
+      private
+
+      def extract_path(params)
+        return nil unless params.is_a?(Hash)
+        params[:path] || params["path"] || params[:file] || params["file"] || params[:target]
+      end
+
+      def protected_file?(path)
+        filename = File.basename(path)
+        @blocked_patterns.any? { |pattern| path =~ pattern || filename =~ pattern }
+      end
+    end
+
+    # Post-hook sanitizer to redact sensitive API keys and tokens from tool outputs
+    class SecretMasker
+      SECRET_PATTERNS = [
+        /(AIzaSy[A-Za-z0-9_-]{25,45})/,           # Google API Keys
+        /(sk-[A-Za-z0-9]{25,50})/,                # OpenAI API Keys
+        /(ghp_[A-Za-z0-9]{25,45})/,               # GitHub Tokens
+        /(bearer\s+[A-Za-z0-9\._-]{20,})/i       # Bearer Tokens
+      ].freeze
+
+      def call(_tool_name, _params, result)
+        return result unless result.is_a?(String)
+
+        sanitized = result.dup
+        SECRET_PATTERNS.each do |pattern|
+          sanitized.gsub!(pattern, "[REDACTED_SECRET]")
+        end
+        sanitized
+      end
+
+      def to_proc
+        method(:call).to_proc
+      end
+    end
+  end
+end

data/lib/antigravity/sidecar.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "thread"
+require "json"
+require "fileutils"
+
+module Antigravity
+  module Sidecar
+    # Base class for non-blocking agent sidecars
+    class Base
+      attr_reader :name, :queue, :worker_thread
+
+      def initialize(name = "SidecarWorker")
+        @name = name
+        @queue = Queue.new
+        @running = false
+        start!
+      end
+
+      def start!
+        return if @running
+
+        @running = true
+        @worker_thread = Thread.new do
+          while @running
+            event = @queue.pop
+            break if event == :stop
+
+            process_event(event) rescue nil
+          end
+        end
+        @worker_thread.priority = -1
+      end
+
+      def emit(event_type, payload = {})
+        @queue.push({ type: event_type, payload: payload, timestamp: Time.now.utc.iso8601 })
+      end
+
+      def stop!
+        @running = false
+        @queue.push(:stop)
+        @worker_thread&.join(2)
+      end
+
+      protected
+
+      def process_event(_event)
+        raise NotImplementedError, "Subclasses must implement #process_event"
+      end
+    end
+
+    # Async Audit Logger Sidecar
+    class AuditLogger < Base
+      attr_reader :log_file
+
+      def initialize(log_file = "log/agent_audit.jsonl")
+        @log_file = File.expand_path(log_file)
+        FileUtils.mkdir_p(File.dirname(@log_file)) rescue nil
+        super("AuditLoggerSidecar")
+      end
+
+      protected
+
+      def process_event(event)
+        File.open(@log_file, "a") do |f|
+          f.puts(JSON.generate(event))
+          f.flush
+        end
+      end
+    end
+
+    # Async Vulnerability & Code Quality Scanner Sidecar
+    class VulnerabilityScanner < Base
+      attr_reader :scanned_events
+
+      def initialize
+        @scanned_events = []
+        super("VulnerabilityScannerSidecar")
+      end
+
+      protected
+
+      def process_event(event)
+        return unless event[:type] == :tool_executed
+
+        tool_name = event.dig(:payload, :tool_name)
+        params = event.dig(:payload, :params)
+        @scanned_events << { tool: tool_name, params: params, verified: true }
+      end
+    end
+  end
+end

data/lib/antigravity/skill.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Antigravity
+  class Skill
+    attr_reader :name, :description, :instructions, :path
+
+    def initialize(path)
+      @path = File.expand_path(path)
+      parse_skill_file
+    end
+
+    def self.load(path)
+      new(path)
+    end
+
+    private
+
+    def parse_skill_file
+      skill_file = File.join(@path, "SKILL.md")
+      raise ArgumentError, "SKILL.md not found at #{@path}" unless File.exist?(skill_file)
+
+      content = File.read(skill_file)
+      if content =~ /\A(---\s*\n.*?\n?)^(---\s*$\n?)/m
+        front_matter = YAML.safe_load(Regexp.last_match(1))
+        @name = front_matter["name"]
+        @description = front_matter["description"]
+        @instructions = Regexp.last_match.post_match.strip
+      else
+        @name = File.basename(@path)
+        @description = ""
+        @instructions = content.strip
+      end
+    end
+  end
+end

data/lib/antigravity/tool.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Antigravity
+  class Tool
+    def self.inherited(subclass)
+      subclass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def name(val = nil, desc: nil)
+        if val
+          @tool_name = val.to_s
+          @tool_description = desc if desc
+        end
+        @tool_name || self.name&.split("::")&.last&.gsub(/(.)([A-Z])/, '\1_\2')&.downcase || "custom_tool"
+      end
+      alias tool_name name
+
+      def desc(val = nil)
+        @tool_description = val if val
+        @tool_description || ""
+      end
+      alias tool_description desc
+
+      def param(name, type: :string, description: "", required: true)
+        @parameters ||= {}
+        @parameters[name.to_sym] = {
+          type: type.to_s,
+          description: description,
+          required: required
+        }
+      end
+
+      def parameters
+        @parameters || {}
+      end
+
+      def to_json_schema
+        properties = {}
+        required_params = []
+
+        parameters.each do |param_name, spec|
+          properties[param_name] = {
+            type: spec[:type],
+            description: spec[:description]
+          }
+          required_params << param_name.to_s if spec[:required]
+        end
+
+        {
+          name: name,
+          description: desc,
+          parameters: {
+            type: "object",
+            properties: properties,
+            required: required_params
+          }
+        }
+      end
+    end
+
+    def tool_name
+      self.class.name
+    end
+
+    def to_json_schema
+      self.class.to_json_schema
+    end
+
+    # Factory for dynamic Proc-based tools
+    class Dynamic < Tool
+      attr_reader :block
+
+      def initialize(name, description: "", &block)
+        super()
+        @dynamic_name = name.to_s
+        @dynamic_description = description
+        @block = block
+      end
+
+      def tool_name
+        @dynamic_name
+      end
+
+      def call(params)
+        @block.call(params)
+      end
+
+      def to_json_schema
+        {
+          name: @dynamic_name,
+          description: @dynamic_description,
+          parameters: {
+            type: "object",
+            properties: {}
+          }
+        }
+      end
+    end
+  end
+end

data/lib/antigravity/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Antigravity
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).strip rescue "0.1.0"
+end

data/lib/antigravity.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "antigravity/version"
+require_relative "antigravity/config"
+require_relative "antigravity/message"
+require_relative "antigravity/harness"
+require_relative "antigravity/hooks"
+require_relative "antigravity/safety"
+require_relative "antigravity/sidecar"
+require_relative "antigravity/tool"
+require_relative "antigravity/skill"
+require_relative "antigravity/client"
+require_relative "antigravity/agent"
+
+module Antigravity
+  class << self
+    def configure
+      yield(config)
+    end
+
+    def config
+      @config ||= Config.new
+    end
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: antigravity-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Riccardo Carlesso
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faye-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: An elegant, Ruby-like SDK for building autonomous AI agents with Google
+  Antigravity.
+email:
+- ricc@google.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/antigravity.rb
+- lib/antigravity/agent.rb
+- lib/antigravity/client.rb
+- lib/antigravity/config.rb
+- lib/antigravity/harness.rb
+- lib/antigravity/hooks.rb
+- lib/antigravity/message.rb
+- lib/antigravity/safety.rb
+- lib/antigravity/sidecar.rb
+- lib/antigravity/skill.rb
+- lib/antigravity/tool.rb
+- lib/antigravity/version.rb
+homepage: https://github.com/palladius/antigravity-ruby-sdk
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/palladius/antigravity-ruby-sdk
+  source_code_uri: https://github.com/palladius/antigravity-ruby-sdk
+  changelog_uri: https://github.com/palladius/antigravity-ruby-sdk/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Google Antigravity SDK for Ruby
+test_files: []