Class: SwarmSDK::Tools::Stores::Storage

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/tools/stores/storage.rb

Overview

Abstract base class for hierarchical key-value storage with metadata

Provides session-scoped storage for agents with path-based organization. Subclasses implement persistence behavior (volatile vs persistent).

Features:

  • Path-based: Hierarchical organization using file-path-like addresses
  • Metadata-rich: Stores content + title + timestamp + size
  • Search capabilities: Glob patterns and grep-style content search
  • Thread-safe: Mutex-protected operations

Direct Known Subclasses

ScratchpadStorage

Defined Under Namespace

Classes: Entry

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Storage

Initialize storage

Subclasses should call super() in their initialize method. This base implementation does nothing - it exists only to satisfy RuboCop.



24
25
26
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 24

def initialize
  # Base class initialization - subclasses implement their own logic
end

Instance Method Details

#clear ⇒ void

This method returns an undefined value.

Clear all entries

Raises:

  • (NotImplementedError) 


86
87
88
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 86

def clear
  raise NotImplementedError, "Subclass must implement #clear"
end

#delete(file_path:) ⇒ void

This method returns an undefined value.

Delete a specific entry

Parameters:

  • file_path (String) —

    Path to delete

Raises:

  • (ArgumentError) —

    If path not found



53
54
55
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 53

def delete(file_path:)
  raise NotImplementedError, "Subclass must implement #delete"
end

#glob(pattern:) ⇒ Array<Hash>

Search entries by glob pattern

Parameters:

  • pattern (String) —

    Glob pattern (e.g., "**/.txt", "parallel//task_*")

Returns:

  • (Array<Hash>) —

    Array of matching entry metadata, sorted by most recent first

Raises:

  • (NotImplementedError) 


69
70
71
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 69

def glob(pattern:)
  raise NotImplementedError, "Subclass must implement #glob"
end

#grep(pattern:, case_insensitive: false, output_mode: "files_with_matches") ⇒ Array<Hash>, String

Search entry content by pattern

Parameters:

  • pattern (String) —

    Regular expression pattern to search for

  • case_insensitive (Boolean) (defaults to: false) —

    Whether to perform case-insensitive search

  • output_mode (String) (defaults to: "files_with_matches") —

    Output mode: "files_with_matches" (default), "content", or "count"

Returns:

  • (Array<Hash>, String) —

    Results based on output_mode

Raises:

  • (NotImplementedError) 


79
80
81
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 79

def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches")
  raise NotImplementedError, "Subclass must implement #grep"
end

#list(prefix: nil) ⇒ Array<Hash>

List entries, optionally filtered by prefix

Parameters:

  • prefix (String, nil) (defaults to: nil) —

    Filter by path prefix

Returns:

  • (Array<Hash>) —

    Array of entry metadata (path, title, size, updated_at)

Raises:

  • (NotImplementedError) 


61
62
63
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 61

def list(prefix: nil)
  raise NotImplementedError, "Subclass must implement #list"
end

#read(file_path:) ⇒ String

Read content from storage

Parameters:

  • file_path (String) —

    Path to read from

Returns:

  • (String) —

    Content at the path

Raises:

  • (ArgumentError) —

    If path not found



44
45
46
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 44

def read(file_path:)
  raise NotImplementedError, "Subclass must implement #read"
end

#size ⇒ Integer

Get number of entries

Returns:

  • (Integer) —

    Number of entries

Raises:

  • (NotImplementedError) 


100
101
102
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 100

def size
  raise NotImplementedError, "Subclass must implement #size"
end

#total_size ⇒ Integer

Get current total size

Returns:

  • (Integer) —

    Total size in bytes

Raises:

  • (NotImplementedError) 


93
94
95
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 93

def total_size
  raise NotImplementedError, "Subclass must implement #total_size"
end

#write(file_path:, content:, title:) ⇒ Entry

Write content to storage

Parameters:

  • file_path (String) —

    Path to store content

  • content (String) —

    Content to store

  • title (String) —

    Brief title describing the content

Returns:

  • (Entry) —

    The created entry

Raises:

  • (ArgumentError) —

    If size limits are exceeded



35
36
37
 
# File 'lib/swarm_sdk/tools/stores/storage.rb', line 35

def write(file_path:, content:, title:)
  raise NotImplementedError, "Subclass must implement #write"
end