Class: Skald

Inherits:
Object
  • Object
show all
Defined in:
lib/skald.rb

Overview

Skald Ruby SDK

A Ruby client library for interacting with the Skald API platform. Provides methods for managing memos, searching, chatting, and generating documents.

Constant Summary collapse

DEFAULT_BASE_URL =

Base URL for the Skald API

"https://api.useskald.com"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, base_url = DEFAULT_BASE_URL) ⇒ Skald

Initialize a new Skald client

Examples:

client = Skald.new("your-api-key")
# Or with custom base URL
client = Skald.new("your-api-key", "https://custom.api.com")

Parameters:

  • api_key (String) —

    Your Skald API key (required)

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    Optional custom base URL (defaults to https://api.useskald.com)

Raises:

  • (ArgumentError) 


31
32
33
34
35
36
 
# File 'lib/skald.rb', line 31

def initialize(api_key, base_url = DEFAULT_BASE_URL)
  raise ArgumentError, "API key is required" if api_key.nil? || api_key.empty?

  @api_key = api_key
  @base_url = base_url.gsub(%r{/+$}, "") # Remove trailing slashes
end

Instance Attribute Details

#api_key ⇒ String (readonly)

Returns the API key used for authentication.

Returns:

  • (String) —

    the API key used for authentication



17
18
19
 
# File 'lib/skald.rb', line 17

def api_key
  @api_key
end

#base_url ⇒ String (readonly)

Returns the base URL for API requests.

Returns:

  • (String) —

    the base URL for API requests



20
21
22
 
# File 'lib/skald.rb', line 20

def base_url
  @base_url
end

Instance Method Details

#chat(chat_params) ⇒ Hash

Chat with your memos (non-streaming)

Examples:

response = client.chat(query: "What are the main project goals?")
puts response[:response]

Parameters:

  • chat_params (Hash) —

    Chat parameters

Options Hash (chat_params):

  • :query (String) —

    The question to ask (required)

  • :filters (Array<Hash>) —

    Optional filters to apply

Returns:

  • (Hash) —

    Response with :ok, :response, and :intermediate_steps keys



176
177
178
179
180
 
# File 'lib/skald.rb', line 176

def chat(chat_params)
  params = chat_params.dup
  params[:stream] = false
  request(:post, "/api/v1/chat", params)
end

#create_memo(memo_data) ⇒ Hash

Create a new memo

Examples:

result = client.create_memo(
  title: "Meeting Notes",
  content: "Discussed project timeline...",
  metadata: { priority: "high" },
  tags: ["meeting", "project"]
)

Parameters:

  • memo_data (Hash) —

    The memo data

Options Hash (memo_data):

  • :title (String) —

    The memo title (required, max 255 chars)

  • :content (String) —

    The memo content (required)

  • :metadata (Hash) —

    Optional custom metadata (JSON object)

  • :reference_id (String) —

    Optional external reference ID (max 255 chars)

  • :tags (Array<String>) —

    Optional array of tags

  • :source (String) —

    Optional source system (e.g., "notion", max 255 chars)

  • :expiration_date (String) —

    Optional ISO 8601 expiration timestamp

Returns:

  • (Hash) —

    Response with :ok key



58
59
60
61
62
63
 
# File 'lib/skald.rb', line 58

def create_memo(memo_data)
  data = memo_data.dup
  data[:metadata] ||= {}

  request(:post, "/api/v1/memo", data)
end

#delete_memo(memo_id, id_type = "memo_uuid") ⇒ nil

Delete a memo

Examples:

client.delete_memo("550e8400-e29b-41d4-a716-446655440000")

Parameters:

  • memo_id (String) —

    The memo UUID or reference ID

  • id_type (String) (defaults to: "memo_uuid") —

    Type of ID: "memo_uuid" or "reference_id" (default: "memo_uuid")

Returns:

  • (nil) 


138
139
140
141
142
143
 
# File 'lib/skald.rb', line 138

def delete_memo(memo_id, id_type = "memo_uuid")
  encoded_id = CGI.escape(memo_id)
  params = id_type != "memo_uuid" ? "?id_type=#{id_type}" : ""
  request(:delete, "/api/v1/memo/#{encoded_id}#{params}")
  nil
end

#generate_doc(generate_params) ⇒ Hash

Generate a document (non-streaming)

Examples:

doc = client.generate_doc(
  prompt: "Create a project status report",
  rules: "Use bullet points and be concise"
)
puts doc[:response]

Parameters:

  • generate_params (Hash) —

    Generation parameters

Options Hash (generate_params):

  • :prompt (String) —

    What document to generate (required)

  • :rules (String) —

    Optional style/format rules

  • :filters (Array<Hash>) —

    Optional filters to apply

Returns:

  • (Hash) —

    Response with :ok, :response, and :intermediate_steps keys



219
220
221
222
223
 
# File 'lib/skald.rb', line 219

def generate_doc(generate_params)
  params = generate_params.dup
  params[:stream] = false
  request(:post, "/api/v1/generate", params)
end

#get_memo(memo_id, id_type = "memo_uuid") ⇒ Hash

Get a memo by ID

Examples:

memo = client.get_memo("550e8400-e29b-41d4-a716-446655440000")
# Or by reference ID
memo = client.get_memo("my-ref-id", "reference_id")

Parameters:

  • memo_id (String) —

    The memo UUID or reference ID

  • id_type (String) (defaults to: "memo_uuid") —

    Type of ID: "memo_uuid" or "reference_id" (default: "memo_uuid")

Returns:

  • (Hash) —

    The memo object with all fields



76
77
78
79
80
 
# File 'lib/skald.rb', line 76

def get_memo(memo_id, id_type = "memo_uuid")
  encoded_id = CGI.escape(memo_id)
  params = id_type != "memo_uuid" ? "?id_type=#{id_type}" : ""
  request(:get, "/api/v1/memo/#{encoded_id}#{params}")
end

#list_memos(params = {}) ⇒ Hash

List memos with pagination

Examples:

response = client.list_memos(page: 1, page_size: 50)
response[:results].each do |memo|
  puts memo[:title]
end

Parameters:

  • params (Hash) (defaults to: {}) —

    Optional pagination parameters

Options Hash (params):

  • :page (Integer) —

    Page number (default: 1)

  • :page_size (Integer) —

    Number of results per page (default: 20, max: 100)

Returns:

  • (Hash) —

    Response with :count, :next, :previous, and :results keys



95
96
97
98
99
100
101
102
 
# File 'lib/skald.rb', line 95

def list_memos(params = {})
  query_params = []
  query_params << "page=#{params[:page]}" if params[:page]
  query_params << "page_size=#{params[:page_size]}" if params[:page_size]
  query_string = query_params.empty? ? "" : "?#{query_params.join('&')}"

  request(:get, "/api/v1/memo#{query_string}")
end

#search(search_params) ⇒ Hash

Search for memos

Examples:

results = client.search(
  query: "project timeline",
  search_method: "chunk_vector_search",
  limit: 20
)

Parameters:

  • search_params (Hash) —

    Search parameters

Options Hash (search_params):

  • :query (String) —

    The search query (required)

  • :search_method (String) —

    Search method: "chunk_vector_search", "title_contains", or "title_startswith" (required)

  • :limit (Integer) —

    Maximum number of results (1-50, default: 10)

  • :filters (Array<Hash>) —

    Optional filters to apply

Returns:

  • (Hash) —

    Response with :results array



161
162
163
 
# File 'lib/skald.rb', line 161

def search(search_params)
  request(:post, "/api/v1/search", search_params)
end

#streamed_chat(chat_params) ⇒ Enumerator

Chat with your memos (streaming)

Examples:

client.streamed_chat(query: "Summarize the project").each do |event|
  if event[:type] == "token"
    print event[:content]
  elsif event[:type] == "done"
    puts "\nDone!"
  end
end

Parameters:

  • chat_params (Hash) —

    Chat parameters

Options Hash (chat_params):

  • :query (String) —

    The question to ask (required)

  • :filters (Array<Hash>) —

    Optional filters to apply

Returns:

  • (Enumerator) —

    An enumerator that yields events



198
199
200
201
202
 
# File 'lib/skald.rb', line 198

def streamed_chat(chat_params)
  params = chat_params.dup
  params[:stream] = true
  stream_request(:post, "/api/v1/chat", params)
end

#streamed_generate_doc(generate_params) ⇒ Enumerator

Generate a document (streaming)

Examples:

client.streamed_generate_doc(prompt: "Write a summary").each do |event|
  if event[:type] == "token"
    print event[:content]
  elsif event[:type] == "done"
    puts "\nDone!"
  end
end

Parameters:

  • generate_params (Hash) —

    Generation parameters

Options Hash (generate_params):

  • :prompt (String) —

    What document to generate (required)

  • :rules (String) —

    Optional style/format rules

  • :filters (Array<Hash>) —

    Optional filters to apply

Returns:

  • (Enumerator) —

    An enumerator that yields events



242
243
244
245
246
 
# File 'lib/skald.rb', line 242

def streamed_generate_doc(generate_params)
  params = generate_params.dup
  params[:stream] = true
  stream_request(:post, "/api/v1/generate", params)
end

#update_memo(memo_id, update_data, id_type = "memo_uuid") ⇒ Hash

Update an existing memo

Examples:

client.update_memo(
  "550e8400-e29b-41d4-a716-446655440000",
  { title: "Updated Title", metadata: { status: "completed" } }
)

Parameters:

  • memo_id (String) —

    The memo UUID or reference ID

  • update_data (Hash) —

    The fields to update

  • id_type (String) (defaults to: "memo_uuid") —

    Type of ID: "memo_uuid" or "reference_id" (default: "memo_uuid")

Options Hash (update_data):

  • :title (String) —

    New title

  • :content (String) —

    New content (triggers reprocessing)

  • :metadata (Hash) —

    New metadata

  • :client_reference_id (String) —

    New reference ID

  • :source (String) —

    New source

  • :expiration_date (String) —

    New expiration date

Returns:

  • (Hash) —

    Response with :ok key



123
124
125
126
127
 
# File 'lib/skald.rb', line 123

def update_memo(memo_id, update_data, id_type = "memo_uuid")
  encoded_id = CGI.escape(memo_id)
  params = id_type != "memo_uuid" ? "?id_type=#{id_type}" : ""
  request(:patch, "/api/v1/memo/#{encoded_id}#{params}", update_data)
end