skald 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 914d138d114eae0c785f900d311427ff2967b6cddae2fc3a47fa4e8307d1c5a9
+  data.tar.gz: c394e54190914540797834c4587e10b1d335d481d01450ee4362ad54322b851d
+SHA512:
+  metadata.gz: 7c964cda5f764004bd9b8c2f5d2ce40708d1a164ae684bc94c7a7ba235a2783656cd58571d073ee99049ed0f3c6a2416cb1af6defaa1cd25da9f3661f70d6b65
+  data.tar.gz: 369bb564e34ee643b0fb9bd11593f0c583f7526269a8917415d71d58631202f210a9ad4af1ec807b8c68e44aab7b196b5a130c09f53452126ae6848b2ceef0a0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Skald
+
+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,620 @@
+# Skald Ruby SDK
+
+Ruby client library for [Skald](https://useskald.com) - an API platform that allows you to easily push context/knowledge via our API (in the form of memos) and get access to chat, document generation, and semantic search out-of-the-box.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'skald'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install skald
+```
+
+## Requirements
+
+- Ruby 3.0.0 or higher
+
+## Quick Start
+
+```ruby
+require 'skald'
+
+# Initialize the client
+client = Skald.new('your-api-key')
+
+# Create a memo
+client.create_memo(
+  title: "Meeting Notes",
+  content: "Discussed project timeline..."
+)
+
+# Search your memos
+results = client.search(
+  query: "project timeline",
+  search_method: "chunk_vector_search"
+)
+
+# Chat with your memos
+response = client.chat(query: "What were the main discussion points?")
+puts response[:response]
+```
+
+## Initialization
+
+```ruby
+# Default base URL (https://api.useskald.com)
+client = Skald.new('your-api-key')
+
+# Custom base URL (for self-hosted or testing)
+client = Skald.new('your-api-key', 'https://custom.api.com')
+```
+
+## Memo Management
+
+### Create Memo
+
+Create a new memo with content and optional metadata.
+
+```ruby
+result = client.create_memo(
+  title: "Project Planning Meeting",
+  content: "Discussed Q1 goals, resource allocation, and timeline...",
+  metadata: { priority: "high", department: "engineering" },
+  tags: ["meeting", "planning"],
+  source: "notion",
+  reference_id: "notion-page-123",
+  expiration_date: "2025-12-31T23:59:59Z"
+)
+# => { ok: true }
+```
+
+**Parameters:**
+- `title` (String, required): Memo title (max 255 characters)
+- `content` (String, required): Memo content
+- `metadata` (Hash, optional): Custom JSON metadata
+- `tags` (Array<String>, optional): Array of tags
+- `source` (String, optional): Source system (e.g., "notion", "slack", max 255 chars)
+- `reference_id` (String, optional): External reference ID (max 255 chars)
+- `expiration_date` (String, optional): ISO 8601 expiration timestamp
+
+**Response:**
+```ruby
+{ ok: true }
+```
+
+### Get Memo
+
+Retrieve a memo by UUID or reference ID.
+
+```ruby
+# Get by UUID
+memo = client.get_memo("550e8400-e29b-41d4-a716-446655440000")
+
+# Get by reference ID
+memo = client.get_memo("notion-page-123", "reference_id")
+```
+
+**Parameters:**
+- `memo_id` (String, required): Memo UUID or reference ID
+- `id_type` (String, optional): `"memo_uuid"` (default) or `"reference_id"`
+
+**Response:**
+```ruby
+{
+  uuid: "550e8400-e29b-41d4-a716-446655440000",
+  created_at: "2025-01-15T10:30:00Z",
+  updated_at: "2025-01-15T10:30:00Z",
+  title: "Project Planning Meeting",
+  content: "Discussed Q1 goals...",
+  summary: "AI-generated summary of the memo",
+  content_length: 150,
+  metadata: { priority: "high" },
+  client_reference_id: "notion-page-123",
+  source: "notion",
+  type: "memo",
+  expiration_date: nil,
+  archived: false,
+  pending: false,
+  tags: [
+    { uuid: "tag-uuid", tag: "meeting" }
+  ],
+  chunks: [
+    { uuid: "chunk-uuid", chunk_content: "...", chunk_index: 0 }
+  ]
+}
+```
+
+### List Memos
+
+List all memos with pagination.
+
+```ruby
+# Default pagination (page 1, 20 items)
+response = client.list_memos
+
+# Custom pagination
+response = client.list_memos(page: 2, page_size: 50)
+```
+
+**Parameters:**
+- `page` (Integer, optional): Page number (default: 1)
+- `page_size` (Integer, optional): Results per page (default: 20, max: 100)
+
+**Response:**
+```ruby
+{
+  count: 150,
+  next: "https://api.useskald.com/api/v1/memo?page=2",
+  previous: nil,
+  results: [
+    {
+      uuid: "...",
+      title: "Memo 1",
+      summary: "...",
+      # ... other memo fields
+    }
+  ]
+}
+```
+
+### Update Memo
+
+Update an existing memo. Updating `content` triggers reprocessing.
+
+```ruby
+# Update by UUID
+client.update_memo(
+  "550e8400-e29b-41d4-a716-446655440000",
+  {
+    title: "Updated Title",
+    metadata: { priority: "medium", status: "reviewed" }
+  }
+)
+
+# Update by reference ID
+client.update_memo(
+  "notion-page-123",
+  { content: "New content..." },
+  "reference_id"
+)
+```
+
+**Parameters:**
+- `memo_id` (String, required): Memo UUID or reference ID
+- `update_data` (Hash, required): Fields to update
+  - `title` (String, optional): New title
+  - `content` (String, optional): New content (triggers reprocessing)
+  - `metadata` (Hash, optional): New metadata
+  - `client_reference_id` (String, optional): New reference ID
+  - `source` (String, optional): New source
+  - `expiration_date` (String, optional): New expiration date
+- `id_type` (String, optional): `"memo_uuid"` (default) or `"reference_id"`
+
+**Response:**
+```ruby
+{ ok: true }
+```
+
+### Delete Memo
+
+Permanently delete a memo and all associated data.
+
+```ruby
+# Delete by UUID
+client.delete_memo("550e8400-e29b-41d4-a716-446655440000")
+
+# Delete by reference ID
+client.delete_memo("notion-page-123", "reference_id")
+```
+
+**Parameters:**
+- `memo_id` (String, required): Memo UUID or reference ID
+- `id_type` (String, optional): `"memo_uuid"` (default) or `"reference_id"`
+
+**Response:**
+```ruby
+nil
+```
+
+## Search
+
+Search your memos using semantic search or title matching.
+
+### Search Methods
+
+1. **`chunk_vector_search`**: Semantic/vector search on memo content chunks
+2. **`title_contains`**: Case-insensitive substring match on titles
+3. **`title_startswith`**: Case-insensitive prefix match on titles
+
+### Semantic Search
+
+```ruby
+results = client.search(
+  query: "project timeline and milestones",
+  search_method: "chunk_vector_search",
+  limit: 20
+)
+```
+
+### Title Search
+
+```ruby
+# Contains
+results = client.search(
+  query: "meeting",
+  search_method: "title_contains"
+)
+
+# Starts with
+results = client.search(
+  query: "Project",
+  search_method: "title_startswith"
+)
+```
+
+**Parameters:**
+- `query` (String, required): Search query
+- `search_method` (String, required): One of `"chunk_vector_search"`, `"title_contains"`, or `"title_startswith"`
+- `limit` (Integer, optional): Maximum results (1-50, default: 10)
+- `filters` (Array<Hash>, optional): Filters to apply (see [Filters](#filters))
+
+**Response:**
+```ruby
+{
+  results: [
+    {
+      uuid: "550e8400-...",
+      title: "Project Planning Meeting",
+      summary: "Discussed Q1 goals...",
+      content_snippet: "...relevant excerpt from the content...",
+      distance: 0.45  # For vector search: 0-2, lower is better. nil for title searches
+    }
+  ]
+}
+```
+
+## Chat
+
+Ask questions and get answers based on your memos with inline citations.
+
+### Non-Streaming Chat
+
+```ruby
+response = client.chat(
+  query: "What are the main project goals for Q1?"
+)
+
+puts response[:response]
+# => "The main goals are: 1) Launch MVP [[1]], 2) Hire team [[2]]..."
+```
+
+**Parameters:**
+- `query` (String, required): Question to ask
+- `filters` (Array<Hash>, optional): Filters to apply (see [Filters](#filters))
+
+**Response:**
+```ruby
+{
+  ok: true,
+  response: "Answer with inline citations [[1]], [[2]], etc.",
+  intermediate_steps: []  # For debugging
+}
+```
+
+### Streaming Chat
+
+```ruby
+print "Answer: "
+client.streamed_chat(
+  query: "Summarize the meeting notes from last week"
+).each do |event|
+  if event[:type] == "token"
+    print event[:content]
+  elsif event[:type] == "done"
+    puts "\nDone!"
+  end
+end
+```
+
+**Parameters:**
+- Same as non-streaming chat
+
+**Yields:**
+```ruby
+{ type: "token", content: "Each" }
+{ type: "token", content: " word" }
+{ type: "done" }
+```
+
+## Document Generation
+
+Generate documents based on your memos with optional style rules.
+
+### Non-Streaming Generation
+
+```ruby
+response = client.generate_doc(
+  prompt: "Create a comprehensive project status report",
+  rules: "Use bullet points and maintain a professional tone"
+)
+
+puts response[:response]
+# => "# Project Status Report\n\n## Overview\nThe project is on track [[1]]..."
+```
+
+**Parameters:**
+- `prompt` (String, required): What document to generate
+- `rules` (String, optional): Style/format rules
+- `filters` (Array<Hash>, optional): Filters to apply (see [Filters](#filters))
+
+**Response:**
+```ruby
+{
+  ok: true,
+  response: "Generated document with citations [[1]], [[2]]...",
+  intermediate_steps: []
+}
+```
+
+### Streaming Generation
+
+```ruby
+puts "Generated Document:"
+client.streamed_generate_doc(
+  prompt: "Write a technical architecture document",
+  rules: "Include diagrams descriptions and code examples"
+).each do |event|
+  if event[:type] == "token"
+    print event[:content]
+  elsif event[:type] == "done"
+    puts "\nDone!"
+  end
+end
+```
+
+**Parameters:**
+- Same as non-streaming generation
+
+**Yields:**
+```ruby
+{ type: "token", content: "Each" }
+{ type: "token", content: " word" }
+{ type: "done" }
+```
+
+## Filters
+
+Filters allow you to narrow down which memos are used for search, chat, and document generation. Multiple filters use AND logic (all must match).
+
+### Filter Structure
+
+```ruby
+{
+  field: "field_name",
+  operator: "eq",
+  value: "value",
+  filter_type: "native_field"
+}
+```
+
+### Filter Types
+
+1. **`native_field`**: Built-in memo properties
+   - `title`: Memo title
+   - `source`: Source system
+   - `client_reference_id`: Your reference ID
+   - `tags`: Memo tags
+
+2. **`custom_metadata`**: User-defined metadata fields
+
+### Filter Operators
+
+| Operator | Description | Value Type |
+|----------|-------------|------------|
+| `eq` | Exact match | String |
+| `neq` | Not equals | String |
+| `contains` | Substring match (case-insensitive) | String |
+| `startswith` | Prefix match (case-insensitive) | String |
+| `endswith` | Suffix match (case-insensitive) | String |
+| `in` | Value is in array | Array<String> |
+| `not_in` | Value not in array | Array<String> |
+
+### Examples
+
+#### Filter by Native Field
+
+```ruby
+results = client.search(
+  query: "project update",
+  search_method: "chunk_vector_search",
+  filters: [
+    {
+      field: "source",
+      operator: "eq",
+      value: "notion",
+      filter_type: "native_field"
+    }
+  ]
+)
+```
+
+#### Filter by Tags
+
+```ruby
+results = client.search(
+  query: "status",
+  search_method: "chunk_vector_search",
+  filters: [
+    {
+      field: "tags",
+      operator: "in",
+      value: ["project", "important"],
+      filter_type: "native_field"
+    }
+  ]
+)
+```
+
+#### Filter by Custom Metadata
+
+```ruby
+results = client.search(
+  query: "urgent tasks",
+  search_method: "chunk_vector_search",
+  filters: [
+    {
+      field: "priority",
+      operator: "eq",
+      value: "high",
+      filter_type: "custom_metadata"
+    }
+  ]
+)
+```
+
+#### Multiple Filters
+
+```ruby
+results = client.search(
+  query: "engineering work",
+  search_method: "chunk_vector_search",
+  filters: [
+    {
+      field: "source",
+      operator: "eq",
+      value: "jira",
+      filter_type: "native_field"
+    },
+    {
+      field: "tags",
+      operator: "in",
+      value: ["backend", "api"],
+      filter_type: "native_field"
+    },
+    {
+      field: "priority",
+      operator: "eq",
+      value: "high",
+      filter_type: "custom_metadata"
+    }
+  ]
+)
+```
+
+#### Filters in Chat
+
+```ruby
+response = client.chat(
+  query: "What are the high priority backend tasks?",
+  filters: [
+    {
+      field: "department",
+      operator: "eq",
+      value: "engineering",
+      filter_type: "custom_metadata"
+    }
+  ]
+)
+```
+
+#### Filters in Document Generation
+
+```ruby
+response = client.generate_doc(
+  prompt: "Create a security audit summary",
+  rules: "Focus on key findings",
+  filters: [
+    {
+      field: "tags",
+      operator: "in",
+      value: ["security", "audit"],
+      filter_type: "native_field"
+    }
+  ]
+)
+```
+
+## Error Handling
+
+The SDK raises exceptions for API errors. Wrap your calls in begin/rescue blocks:
+
+```ruby
+begin
+  memo = client.get_memo("invalid-id")
+rescue => e
+  puts "Error: #{e.message}"
+  # => "Skald API error (404): Not Found"
+end
+```
+
+All methods may raise `RuntimeError` with the format:
+```
+Skald API error (STATUS_CODE): ERROR_MESSAGE
+```
+
+## Examples
+
+See the [examples](examples/) directory for complete working examples:
+
+- [memo_operations.rb](examples/memo_operations.rb) - Create, read, update, delete memos
+- [search.rb](examples/search.rb) - All search methods and filtering
+- [chat.rb](examples/chat.rb) - Streaming and non-streaming chat
+- [document_generation.rb](examples/document_generation.rb) - Document generation with rules
+- [filters.rb](examples/filters.rb) - Advanced filtering examples
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run tests with coverage
+bundle exec rspec --format documentation
+
+# Run linter
+bundle exec rubocop
+```
+
+## Testing
+
+The SDK includes comprehensive tests with 100% method coverage:
+
+```bash
+bundle exec rspec
+# => 54 examples, 0 failures
+```
+
+Tests use WebMock to mock HTTP requests, so no actual API calls are made during testing.
+
+## API Reference
+
+For complete API documentation, visit the [Skald API Documentation](https://docs.useskald.com).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/skald-org/skald-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Support
+
+- Documentation: https://docs.useskald.com
+- Email: support@useskald.com
+- GitHub Issues: https://github.com/skald-org/skald-ruby/issues

data/lib/skald.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "cgi"
+
+# Skald Ruby SDK
+#
+# A Ruby client library for interacting with the Skald API platform.
+# Provides methods for managing memos, searching, chatting, and generating documents.
+class Skald
+  # Base URL for the Skald API
+  DEFAULT_BASE_URL = "https://api.useskald.com"
+
+  # @return [String] the API key used for authentication
+  attr_reader :api_key
+
+  # @return [String] the base URL for API requests
+  attr_reader :base_url
+
+  # Initialize a new Skald client
+  #
+  # @param api_key [String] Your Skald API key (required)
+  # @param base_url [String] Optional custom base URL (defaults to https://api.useskald.com)
+  #
+  # @example
+  #   client = Skald.new("your-api-key")
+  #   # Or with custom base URL
+  #   client = Skald.new("your-api-key", "https://custom.api.com")
+  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
+
+  # Create a new memo
+  #
+  # @param memo_data [Hash] The memo data
+  # @option memo_data [String] :title The memo title (required, max 255 chars)
+  # @option memo_data [String] :content The memo content (required)
+  # @option memo_data [Hash] :metadata Optional custom metadata (JSON object)
+  # @option memo_data [String] :reference_id Optional external reference ID (max 255 chars)
+  # @option memo_data [Array<String>] :tags Optional array of tags
+  # @option memo_data [String] :source Optional source system (e.g., "notion", max 255 chars)
+  # @option memo_data [String] :expiration_date Optional ISO 8601 expiration timestamp
+  #
+  # @return [Hash] Response with :ok key
+  #
+  # @example
+  #   result = client.create_memo(
+  #     title: "Meeting Notes",
+  #     content: "Discussed project timeline...",
+  #     metadata: { priority: "high" },
+  #     tags: ["meeting", "project"]
+  #   )
+  def create_memo(memo_data)
+    data = memo_data.dup
+    data[:metadata] ||= {}
+
+    request(:post, "/api/v1/memo", data)
+  end
+
+  # Get a memo by ID
+  #
+  # @param memo_id [String] The memo UUID or reference ID
+  # @param id_type [String] Type of ID: "memo_uuid" or "reference_id" (default: "memo_uuid")
+  #
+  # @return [Hash] The memo object with all fields
+  #
+  # @example
+  #   memo = client.get_memo("550e8400-e29b-41d4-a716-446655440000")
+  #   # Or by reference ID
+  #   memo = client.get_memo("my-ref-id", "reference_id")
+  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 with pagination
+  #
+  # @param params [Hash] Optional pagination parameters
+  # @option params [Integer] :page Page number (default: 1)
+  # @option params [Integer] :page_size Number of results per page (default: 20, max: 100)
+  #
+  # @return [Hash] Response with :count, :next, :previous, and :results keys
+  #
+  # @example
+  #   response = client.list_memos(page: 1, page_size: 50)
+  #   response[:results].each do |memo|
+  #     puts memo[:title]
+  #   end
+  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
+
+  # Update an existing memo
+  #
+  # @param memo_id [String] The memo UUID or reference ID
+  # @param update_data [Hash] The fields to update
+  # @option update_data [String] :title New title
+  # @option update_data [String] :content New content (triggers reprocessing)
+  # @option update_data [Hash] :metadata New metadata
+  # @option update_data [String] :client_reference_id New reference ID
+  # @option update_data [String] :source New source
+  # @option update_data [String] :expiration_date New expiration date
+  # @param id_type [String] Type of ID: "memo_uuid" or "reference_id" (default: "memo_uuid")
+  #
+  # @return [Hash] Response with :ok key
+  #
+  # @example
+  #   client.update_memo(
+  #     "550e8400-e29b-41d4-a716-446655440000",
+  #     { title: "Updated Title", metadata: { status: "completed" } }
+  #   )
+  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
+
+  # Delete a memo
+  #
+  # @param memo_id [String] The memo UUID or reference ID
+  # @param id_type [String] Type of ID: "memo_uuid" or "reference_id" (default: "memo_uuid")
+  #
+  # @return [nil]
+  #
+  # @example
+  #   client.delete_memo("550e8400-e29b-41d4-a716-446655440000")
+  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
+
+  # Search for memos
+  #
+  # @param search_params [Hash] Search parameters
+  # @option search_params [String] :query The search query (required)
+  # @option search_params [String] :search_method Search method: "chunk_vector_search", "title_contains", or "title_startswith" (required)
+  # @option search_params [Integer] :limit Maximum number of results (1-50, default: 10)
+  # @option search_params [Array<Hash>] :filters Optional filters to apply
+  #
+  # @return [Hash] Response with :results array
+  #
+  # @example
+  #   results = client.search(
+  #     query: "project timeline",
+  #     search_method: "chunk_vector_search",
+  #     limit: 20
+  #   )
+  def search(search_params)
+    request(:post, "/api/v1/search", search_params)
+  end
+
+  # Chat with your memos (non-streaming)
+  #
+  # @param chat_params [Hash] Chat parameters
+  # @option chat_params [String] :query The question to ask (required)
+  # @option chat_params [Array<Hash>] :filters Optional filters to apply
+  #
+  # @return [Hash] Response with :ok, :response, and :intermediate_steps keys
+  #
+  # @example
+  #   response = client.chat(query: "What are the main project goals?")
+  #   puts response[:response]
+  def chat(chat_params)
+    params = chat_params.dup
+    params[:stream] = false
+    request(:post, "/api/v1/chat", params)
+  end
+
+  # Chat with your memos (streaming)
+  #
+  # @param chat_params [Hash] Chat parameters
+  # @option chat_params [String] :query The question to ask (required)
+  # @option chat_params [Array<Hash>] :filters Optional filters to apply
+  #
+  # @return [Enumerator] An enumerator that yields events
+  #
+  # @example
+  #   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
+  def streamed_chat(chat_params)
+    params = chat_params.dup
+    params[:stream] = true
+    stream_request(:post, "/api/v1/chat", params)
+  end
+
+  # Generate a document (non-streaming)
+  #
+  # @param generate_params [Hash] Generation parameters
+  # @option generate_params [String] :prompt What document to generate (required)
+  # @option generate_params [String] :rules Optional style/format rules
+  # @option generate_params [Array<Hash>] :filters Optional filters to apply
+  #
+  # @return [Hash] Response with :ok, :response, and :intermediate_steps keys
+  #
+  # @example
+  #   doc = client.generate_doc(
+  #     prompt: "Create a project status report",
+  #     rules: "Use bullet points and be concise"
+  #   )
+  #   puts doc[:response]
+  def generate_doc(generate_params)
+    params = generate_params.dup
+    params[:stream] = false
+    request(:post, "/api/v1/generate", params)
+  end
+
+  # Generate a document (streaming)
+  #
+  # @param generate_params [Hash] Generation parameters
+  # @option generate_params [String] :prompt What document to generate (required)
+  # @option generate_params [String] :rules Optional style/format rules
+  # @option generate_params [Array<Hash>] :filters Optional filters to apply
+  #
+  # @return [Enumerator] An enumerator that yields events
+  #
+  # @example
+  #   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
+  def streamed_generate_doc(generate_params)
+    params = generate_params.dup
+    params[:stream] = true
+    stream_request(:post, "/api/v1/generate", params)
+  end
+
+  private
+
+  # Make an HTTP request
+  def request(method, path, body = nil)
+    uri = URI.join(@base_url, path)
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == "https"
+
+    request_class = case method
+                    when :get then Net::HTTP::Get
+                    when :post then Net::HTTP::Post
+                    when :patch then Net::HTTP::Patch
+                    when :delete then Net::HTTP::Delete
+                    else raise ArgumentError, "Unsupported method: #{method}"
+                    end
+
+    request = request_class.new(uri.request_uri)
+    request["Authorization"] = "Bearer #{@api_key}"
+    request["Content-Type"] = "application/json" if body
+
+    request.body = body.to_json if body
+
+    response = http.request(request)
+
+    unless response.is_a?(Net::HTTPSuccess)
+      raise "Skald API error (#{response.code}): #{response.body}"
+    end
+
+    # DELETE returns empty response
+    return nil if response.body.nil? || response.body.empty?
+
+    JSON.parse(response.body, symbolize_names: true)
+  end
+
+  # Make a streaming HTTP request
+  def stream_request(method, path, body)
+    Enumerator.new do |yielder|
+      uri = URI.join(@base_url, path)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 300 # 5 minutes for streaming
+
+      request_class = case method
+                      when :post then Net::HTTP::Post
+                      else raise ArgumentError, "Unsupported streaming method: #{method}"
+                      end
+
+      request = request_class.new(uri.request_uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Content-Type"] = "application/json"
+      request.body = body.to_json
+
+      buffer = ""
+
+      http.request(request) do |response|
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "Skald API error (#{response.code}): #{response.body}"
+        end
+
+        response.read_body do |chunk|
+          buffer += chunk
+
+          # Process complete lines
+          while (newline_index = buffer.index("\n"))
+            line = buffer[0...newline_index].strip
+            buffer = buffer[(newline_index + 1)..-1] || ""
+
+            next if line.empty?
+            next if line.start_with?(": ") # Skip ping events
+
+            # Parse SSE format (data: {...})
+            if line.start_with?("data: ")
+              json_str = line[6..-1]
+              begin
+                event = JSON.parse(json_str, symbolize_names: true)
+                yielder << event
+                break if event[:type] == "done"
+              rescue JSON::ParserError
+                # Skip invalid JSON
+                next
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: skald
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Skald
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: Ruby client library for Skald - an API platform for context/knowledge
+  management with chat, document generation, and semantic search capabilities
+email:
+- support@useskald.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/skald.rb
+homepage: https://github.com/skald-org/skald-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/skald-org/skald-ruby
+  source_code_uri: https://github.com/skald-org/skald-ruby
+  changelog_uri: https://github.com/skald-org/skald-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby SDK for Skald API
+test_files: []