semantic_pen 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1b2846b64e0b8d626bf54c2da6590fd0aa0d18151be75064e6965d5b16184937
+  data.tar.gz: 88366157f967caa712db22d45cab9c6096484b01f4837be3a28e1fec6ebb130e
+SHA512:
+  metadata.gz: cbcd7a114c6b0a453e6dbe3c13e0bb4f503fb2c547245844108b95591e6dc4a25e61d1f45ca641951358cef2a293a64a18c53ff4a5dbe525934fdcdfdc5a4b58
+  data.tar.gz: db7bd1a601fda864616da2f1ea51a057e01909d934f4084c3a8f8790b419b6ff82b5270e5f773656ff18e2c5e0d144141cc3332dc4b2643414c5a908e9fc6f54

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SemanticPen Team
+
+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,319 @@
+# SemanticPen Ruby SDK
+
+Official Ruby SDK for the SemanticPen API - AI-powered content generation made simple.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'semantic_pen'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install semantic_pen
+```
+
+## Quick Start
+
+```ruby
+require 'semantic_pen'
+
+# Initialize the client
+client = SemanticPen::Client.new(api_key: 'your-api-key')
+
+# Generate an article
+response = client.generate_article('AI in healthcare', project_name: 'Medical Blog')
+
+if response.success? && response.has_article_ids?
+  article_id = response.first_article_id
+  
+  # Check article status
+  article = client.get_article(article_id)
+  puts "Status: #{article.status} (#{article.progress}% complete)"
+end
+```
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+client = SemanticPen::Client.new(api_key: 'your-api-key')
+```
+
+### Custom Configuration
+
+```ruby
+client = SemanticPen::Client.new(
+  api_key: 'your-api-key',
+  base_url: 'https://api.semanticpen.com',
+  timeout: 120  # 2 minutes
+)
+```
+
+### Global Configuration
+
+```ruby
+SemanticPen.configure do |config|
+  config.api_key = 'your-api-key'
+  config.base_url = 'https://www.semanticpen.com'
+  config.timeout = 60
+end
+```
+
+### Environment Variables
+
+You can also configure the SDK using environment variables:
+
+```bash
+export SEMANTIC_PEN_API_KEY=your-api-key
+export SEMANTIC_PEN_BASE_URL=https://www.semanticpen.com
+```
+
+```ruby
+client = SemanticPen::Client.new(
+  api_key: ENV['SEMANTIC_PEN_API_KEY'],
+  base_url: ENV['SEMANTIC_PEN_BASE_URL']
+)
+```
+
+## API Methods
+
+### Generate Article
+
+Generate a new article with AI-powered content:
+
+```ruby
+response = client.generate_article('target keyword', project_name: 'My Project')
+```
+
+**Parameters:**
+- `target_keyword` (required): The main keyword for the article
+- `project_name` (optional): Project name for organization
+
+**Returns:** `SemanticPen::Models::GenerateArticleResponse`
+
+### Get Article Status
+
+Retrieve the current status and content of an article:
+
+```ruby
+article = client.get_article('article-id')
+```
+
+**Parameters:**
+- `article_id` (required): The ID of the article to retrieve
+
+**Returns:** `SemanticPen::Models::Article`
+
+## Models
+
+### Article
+
+```ruby
+article = client.get_article('article-id')
+
+# Properties
+article.id              # Article ID
+article.title           # Article title
+article.content         # Article content
+article.status          # Current status
+article.progress        # Progress percentage (0-100)
+article.target_keyword  # Target keyword
+article.project_name    # Project name
+article.created_at      # Creation timestamp
+article.updated_at      # Last update timestamp
+
+# Status methods
+article.completed?      # true if status is 'completed'
+article.in_progress?    # true if status is 'in_progress' or 'processing'
+article.failed?         # true if status is 'failed' or 'error'
+
+# Convert to hash
+article.to_h
+```
+
+### Generate Article Response
+
+```ruby
+response = client.generate_article('keyword')
+
+# Properties
+response.message        # Response message
+response.success        # Boolean success status
+response.article_ids    # Array of generated article IDs
+
+# Methods
+response.success?           # true if generation was successful
+response.has_article_ids?   # true if article IDs are present
+response.first_article_id   # First article ID (convenience method)
+
+# Convert to hash
+response.to_h
+```
+
+## Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+```ruby
+begin
+  response = client.generate_article('keyword')
+rescue SemanticPen::ValidationError => e
+  puts "Validation Error: #{e.message}"
+rescue SemanticPen::AuthenticationError => e
+  puts "Authentication Error: #{e.message}"
+rescue SemanticPen::NotFoundError => e
+  puts "Not Found Error: #{e.message}"
+rescue SemanticPen::RateLimitError => e
+  puts "Rate Limit Error: #{e.message}"
+rescue SemanticPen::NetworkError => e
+  puts "Network Error: #{e.message}"
+rescue SemanticPen::ApiError => e
+  puts "API Error: #{e.message} (HTTP #{e.http_status_code})"
+rescue SemanticPen::Error => e
+  puts "SemanticPen Error: #{e.message}"
+end
+```
+
+### Error Types
+
+- `SemanticPen::ValidationError` - Invalid input parameters
+- `SemanticPen::AuthenticationError` - Invalid API key or authentication issues
+- `SemanticPen::NotFoundError` - Requested resource not found
+- `SemanticPen::RateLimitError` - Rate limit exceeded
+- `SemanticPen::NetworkError` - Network connectivity issues
+- `SemanticPen::ApiError` - General API errors
+- `SemanticPen::Error` - Base error class
+
+## Advanced Usage
+
+### Polling for Completion
+
+Use the built-in `StatusPoller` to wait for article completion:
+
+```ruby
+response = client.generate_article('AI trends 2025')
+
+if response.success? && response.has_article_ids?
+  article_id = response.first_article_id
+  
+  # Poll for completion
+  poller = SemanticPen::Models::StatusPoller.new(
+    client, 
+    article_id, 
+    max_attempts: 60,  # Maximum polling attempts
+    delay: 5           # Delay between attempts (seconds)
+  )
+  
+  article = poller.wait_for_completion
+  
+  if article.completed?
+    puts "Article ready: #{article.title}"
+  else
+    puts "Article failed to complete"
+  end
+end
+```
+
+### Bulk Generation
+
+Generate multiple articles efficiently:
+
+```ruby
+keywords = ['AI in healthcare', 'machine learning', 'data science']
+articles = []
+
+keywords.each do |keyword|
+  begin
+    response = client.generate_article(keyword, project_name: 'Tech Blog')
+    articles << response.first_article_id if response.success?
+    sleep(1)  # Rate limiting
+  rescue SemanticPen::Error => e
+    puts "Failed to generate article for #{keyword}: #{e.message}"
+  end
+end
+
+# Check status of all articles
+articles.each do |article_id|
+  article = client.get_article(article_id)
+  puts "#{article.target_keyword}: #{article.status} (#{article.progress}%)"
+end
+```
+
+## Examples
+
+The `examples/` directory contains comprehensive usage examples:
+
+- `basic_usage.rb` - Simple article generation and status checking
+- `polling_example.rb` - Using StatusPoller for completion waiting
+- `bulk_generation.rb` - Generating multiple articles efficiently
+- `configuration_example.rb` - Various configuration options and error handling
+
+To run an example:
+
+```bash
+cd examples
+ruby basic_usage.rb
+```
+
+## Requirements
+
+- Ruby 2.6.0 or higher
+- `faraday` gem for HTTP requests
+- `json` gem for JSON parsing
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+To run tests:
+
+```bash
+bundle exec rspec
+```
+
+To run RuboCop for code style:
+
+```bash
+bundle exec rubocop
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -am 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Support
+
+For support and questions, please visit [SemanticPen API Documentation](https://www.semanticpen.com/api-documentation).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### 1.0.0 (2025-01-19)
+
+- Initial release
+- Basic article generation and retrieval
+- Comprehensive error handling
+- Built-in status polling
+- Full test suite and documentation

data/examples/basic_usage.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/semantic_pen'
+
+begin
+  # Initialize the client with your API key
+  client = SemanticPen::Client.new(api_key: 'your-api-key-here')
+
+  # Generate an article
+  puts 'Generating article...'
+  response = client.generate_article('AI in healthcare', project_name: 'Medical Blog')
+
+  if response.success? && response.has_article_ids?
+    article_id = response.first_article_id
+    puts "Article generation started. ID: #{article_id}"
+    puts "Message: #{response.message}"
+
+    # Check article status
+    puts "\nChecking article status..."
+    article = client.get_article(article_id)
+    puts "Status: #{article.status} (#{article.progress}% complete)"
+    puts "Target Keyword: #{article.target_keyword}"
+    puts "Project: #{article.project_name}"
+
+    if article.completed?
+      puts "\nArticle completed!"
+      puts "Title: #{article.title}" if article.title
+      puts "Content preview: #{article.content[0..200]}..." if article.content
+    elsif article.in_progress?
+      puts "\nArticle is still being generated..."
+    elsif article.failed?
+      puts "\nArticle generation failed."
+    end
+  else
+    puts "Failed to generate article: #{response.message}"
+  end
+
+rescue SemanticPen::ValidationError => e
+  puts "Validation Error: #{e.message}"
+rescue SemanticPen::AuthenticationError => e
+  puts "Authentication Error: #{e.message}"
+rescue SemanticPen::NotFoundError => e
+  puts "Not Found Error: #{e.message}"
+rescue SemanticPen::NetworkError => e
+  puts "Network Error: #{e.message}"
+rescue SemanticPen::ApiError => e
+  puts "API Error: #{e.message} (HTTP #{e.http_status_code})"
+rescue SemanticPen::Error => e
+  puts "SemanticPen Error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected Error: #{e.message}"
+end

data/examples/bulk_generation.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/semantic_pen'
+
+begin
+  # Initialize the client
+  client = SemanticPen::Client.new(api_key: 'your-api-key-here')
+
+  # Define keywords to generate articles for
+  keywords = [
+    'artificial intelligence trends 2025',
+    'sustainable energy solutions',
+    'remote work productivity tips',
+    'cybersecurity best practices',
+    'blockchain technology applications'
+  ]
+
+  project_name = 'Tech Blog Batch'
+  generated_articles = []
+
+  puts "Starting bulk generation for #{keywords.length} articles..."
+
+  # Generate all articles
+  keywords.each_with_index do |keyword, index|
+    puts "\n#{index + 1}/#{keywords.length}: Generating article for '#{keyword}'"
+    
+    begin
+      response = client.generate_article(keyword, project_name: project_name)
+      
+      if response.success? && response.has_article_ids?
+        article_id = response.first_article_id
+        generated_articles << { keyword: keyword, id: article_id }
+        puts "✅ Started generation (ID: #{article_id})"
+      else
+        puts "❌ Failed: #{response.message}"
+      end
+    rescue SemanticPen::Error => e
+      puts "❌ Error generating article for '#{keyword}': #{e.message}"
+    end
+    
+    # Small delay to avoid hitting rate limits
+    sleep(1) unless index == keywords.length - 1
+  end
+
+  if generated_articles.empty?
+    puts "\nNo articles were successfully started."
+    exit
+  end
+
+  puts "\n#{generated_articles.length} articles started. Checking status..."
+
+  # Check status of all generated articles
+  generated_articles.each do |article_info|
+    begin
+      article = client.get_article(article_info[:id])
+      status_emoji = case article.status
+                    when 'completed' then '✅'
+                    when 'failed', 'error' then '❌'
+                    else '⏳'
+                    end
+      
+      puts "#{status_emoji} #{article_info[:keyword]}: #{article.status} (#{article.progress}%)"
+    rescue SemanticPen::Error => e
+      puts "❌ Error checking #{article_info[:keyword]}: #{e.message}"
+    end
+  end
+
+  # Wait for completion of all articles (simplified polling)
+  puts "\nWaiting for articles to complete..."
+  completed_count = 0
+  max_wait_minutes = 10
+
+  (1..max_wait_minutes).each do |minute|
+    puts "\nChecking progress (minute #{minute}/#{max_wait_minutes})..."
+    completed_count = 0
+    
+    generated_articles.each do |article_info|
+      begin
+        article = client.get_article(article_info[:id])
+        completed_count += 1 if article.completed?
+      rescue SemanticPen::Error
+        # Article might still be processing
+      end
+    end
+    
+    puts "#{completed_count}/#{generated_articles.length} articles completed"
+    
+    break if completed_count == generated_articles.length
+    
+    sleep(60) # Wait 1 minute before checking again
+  end
+
+  puts "\nFinal summary:"
+  puts "#{completed_count}/#{generated_articles.length} articles completed"
+
+rescue SemanticPen::Error => e
+  puts "SemanticPen Error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected Error: #{e.message}"
+end

data/examples/configuration_example.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/semantic_pen'
+
+begin
+  # Example 1: Basic configuration
+  puts "=== Basic Configuration ==="
+  client = SemanticPen::Client.new(api_key: 'your-api-key-here')
+  puts "Client initialized with default settings"
+
+  # Example 2: Custom configuration
+  puts "\n=== Custom Configuration ==="
+  custom_client = SemanticPen::Client.new(
+    api_key: 'your-api-key-here',
+    base_url: 'https://api.semanticpen.com',  # Custom base URL
+    timeout: 120                               # 2 minute timeout
+  )
+  puts "Client initialized with custom base URL and timeout"
+
+  # Example 3: Global configuration (alternative approach)
+  puts "\n=== Global Configuration ==="
+  SemanticPen.configure do |config|
+    config.api_key = 'your-api-key-here'
+    config.base_url = 'https://www.semanticpen.com'
+    config.timeout = 90
+  end
+  puts "Global configuration set"
+
+  # Example 4: Environment-based configuration
+  puts "\n=== Environment-based Configuration ==="
+  api_key = ENV['SEMANTIC_PEN_API_KEY'] || 'your-api-key-here'
+  base_url = ENV['SEMANTIC_PEN_BASE_URL'] || 'https://www.semanticpen.com'
+  
+  env_client = SemanticPen::Client.new(
+    api_key: api_key,
+    base_url: base_url
+  )
+  puts "Client configured from environment variables"
+
+  # Example 5: Comprehensive error handling
+  puts "\n=== Error Handling Examples ==="
+  
+  # Test with invalid API key
+  begin
+    invalid_client = SemanticPen::Client.new(api_key: 'invalid-key')
+    invalid_client.generate_article('test keyword')
+  rescue SemanticPen::AuthenticationError => e
+    puts "✅ Caught authentication error: #{e.message}"
+  end
+
+  # Test with empty keyword
+  begin
+    client.generate_article('')
+  rescue SemanticPen::ValidationError => e
+    puts "✅ Caught validation error: #{e.message}"
+  end
+
+  # Test with invalid article ID
+  begin
+    client.get_article('non-existent-id')
+  rescue SemanticPen::NotFoundError => e
+    puts "✅ Caught not found error: #{e.message}"
+  end
+
+  # Example 6: Working with responses
+  puts "\n=== Response Handling ==="
+  
+  # This would work with a valid API key
+  # response = client.generate_article('ruby programming')
+  # 
+  # puts "Response success: #{response.success?}"
+  # puts "Message: #{response.message}"
+  # puts "Article IDs: #{response.article_ids}"
+  # puts "Has article IDs: #{response.has_article_ids?}"
+  # puts "First article ID: #{response.first_article_id}" if response.has_article_ids?
+
+  puts "\n=== Article Model Examples ==="
+  
+  # Example article data structure
+  sample_article_data = {
+    'id' => 'article-123',
+    'title' => 'Introduction to Ruby Programming',
+    'content' => 'Ruby is a dynamic, open source programming language...',
+    'status' => 'completed',
+    'progress' => 100,
+    'target_keyword' => 'ruby programming',
+    'project_name' => 'Tech Blog',
+    'created_at' => '2025-01-01T10:00:00Z',
+    'updated_at' => '2025-01-01T10:30:00Z'
+  }
+
+  article = SemanticPen::Models::Article.new(sample_article_data)
+  
+  puts "Article ID: #{article.id}"
+  puts "Title: #{article.title}"
+  puts "Status: #{article.status}"
+  puts "Progress: #{article.progress}%"
+  puts "Is completed: #{article.completed?}"
+  puts "Is in progress: #{article.in_progress?}"
+  puts "Is failed: #{article.failed?}"
+  puts "Article hash: #{article.to_h}"
+
+rescue SemanticPen::Error => e
+  puts "SemanticPen Error: #{e.message}"
+  puts "Error Code: #{e.error_code}" if e.error_code
+  puts "HTTP Status: #{e.http_status_code}" if e.http_status_code
+rescue StandardError => e
+  puts "Unexpected Error: #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+end

data/examples/polling_example.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/semantic_pen'
+
+begin
+  # Initialize the client
+  client = SemanticPen::Client.new(api_key: 'your-api-key-here')
+
+  # Generate an article
+  puts 'Generating article: "Machine Learning Basics"'
+  response = client.generate_article('machine learning basics', project_name: 'Tech Blog')
+
+  if response.success? && response.has_article_ids?
+    article_id = response.first_article_id
+    puts "Article generation started. ID: #{article_id}"
+
+    # Poll for completion using the StatusPoller utility
+    puts "\nWaiting for article to complete (polling every 5 seconds)..."
+    poller = SemanticPen::Models::StatusPoller.new(client, article_id, max_attempts: 30, delay: 5)
+    
+    article = poller.wait_for_completion
+    
+    if article.completed?
+      puts "\n✅ Article completed successfully!"
+      puts "Title: #{article.title}"
+      puts "Status: #{article.status}"
+      puts "Progress: #{article.progress}%"
+      puts "Created at: #{article.created_at}"
+      puts "Updated at: #{article.updated_at}"
+      
+      if article.content
+        puts "\nContent preview:"
+        puts article.content[0..500] + (article.content.length > 500 ? '...' : '')
+      end
+    else
+      puts "\n❌ Article generation failed"
+      puts "Status: #{article.status}"
+    end
+  else
+    puts "Failed to start article generation: #{response.message}"
+  end
+
+rescue SemanticPen::Error => e
+  puts "SemanticPen Error: #{e.message}"
+  puts "Error Code: #{e.error_code}" if e.error_code
+  puts "HTTP Status: #{e.http_status_code}" if e.http_status_code
+rescue StandardError => e
+  puts "Unexpected Error: #{e.message}"
+  puts e.backtrace.join("\n")
+end

data/lib/semantic_pen/client.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module SemanticPen
+  class Client
+    def initialize(api_key: nil, base_url: nil, timeout: nil)
+      @configuration = build_configuration(api_key, base_url, timeout)
+      @configuration.validate!
+      @connection = build_connection
+    end
+
+    def generate_article(target_keyword, project_name: nil)
+      raise ValidationError, 'Target keyword cannot be nil or empty' if target_keyword.nil? || target_keyword.strip.empty?
+
+      request_body = {
+        target_keyword: target_keyword.strip,
+        project_name: project_name
+      }.compact
+
+      response = post('/api/articles', request_body)
+      Models::GenerateArticleResponse.new(response)
+    rescue Faraday::Error => e
+      raise NetworkError.new("Failed to send request: #{e.message}", original_error: e)
+    end
+
+    def get_article(article_id)
+      raise ValidationError, 'Article ID cannot be nil or empty' if article_id.nil? || article_id.strip.empty?
+
+      response = get("/api/articles/#{article_id.strip}")
+      Models::Article.new(response)
+    rescue Faraday::Error => e
+      raise NetworkError.new("Failed to send request: #{e.message}", original_error: e)
+    end
+
+    private
+
+    def build_configuration(api_key, base_url, timeout)
+      config = Configuration.new
+      config.api_key = api_key
+      config.base_url = base_url if base_url
+      config.timeout = timeout if timeout
+      config
+    end
+
+    def build_connection
+      Faraday.new(url: @configuration.base_url) do |f|
+        f.request :json
+        f.response :json
+        f.request :authorization, 'Bearer', @configuration.api_key
+        f.headers['User-Agent'] = 'SemanticPen-Ruby-SDK/1.0.0'
+        f.adapter Faraday.default_adapter
+        f.options.timeout = @configuration.timeout
+      end
+    end
+
+    def get(path)
+      handle_response(@connection.get(path))
+    end
+
+    def post(path, body)
+      handle_response(@connection.post(path, body))
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 401
+        raise AuthenticationError, extract_error_message(response)
+      when 404
+        raise NotFoundError, extract_error_message(response)
+      when 429
+        raise RateLimitError, extract_error_message(response)
+      else
+        raise ApiError.new(extract_error_message(response), http_status_code: response.status)
+      end
+    end
+
+    def extract_error_message(response)
+      return response.body if response.body.is_a?(String)
+
+      response.body&.dig('message') || response.body&.dig('error') || 'Unknown error occurred'
+    rescue StandardError
+      'Unknown error occurred'
+    end
+  end
+end

data/lib/semantic_pen/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SemanticPen
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout
+
+    def initialize
+      @base_url = 'https://www.semanticpen.com'
+      @timeout = 60
+    end
+
+    def validate!
+      raise ArgumentError, 'API key is required' if api_key.nil? || api_key.empty?
+      raise ArgumentError, 'Base URL is required' if base_url.nil? || base_url.empty?
+    end
+  end
+end

data/lib/semantic_pen/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SemanticPen
+  class Error < StandardError
+    attr_reader :error_code, :http_status_code
+
+    def initialize(message, error_code: nil, http_status_code: nil)
+      super(message)
+      @error_code = error_code
+      @http_status_code = http_status_code
+    end
+  end
+
+  class NetworkError < Error
+    def initialize(message, original_error: nil)
+      super("Network error: #{message}", error_code: 'NETWORK_ERROR')
+      @original_error = original_error
+    end
+  end
+
+  class ValidationError < Error
+    def initialize(message)
+      super("Validation error: #{message}", error_code: 'VALIDATION_ERROR')
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message)
+      super("Authentication error: #{message}", error_code: 'AUTHENTICATION_ERROR', http_status_code: 401)
+    end
+  end
+
+  class NotFoundError < Error
+    def initialize(message)
+      super("Not found: #{message}", error_code: 'NOT_FOUND_ERROR', http_status_code: 404)
+    end
+  end
+
+  class ApiError < Error
+    def initialize(message, http_status_code: nil)
+      super("API error: #{message}", error_code: 'API_ERROR', http_status_code: http_status_code)
+    end
+  end
+
+  class RateLimitError < Error
+    def initialize(message)
+      super("Rate limit exceeded: #{message}", error_code: 'RATE_LIMIT_ERROR', http_status_code: 429)
+    end
+  end
+end

data/lib/semantic_pen/models.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module SemanticPen
+  module Models
+    class Article
+      attr_reader :id, :title, :content, :status, :progress, :target_keyword, :project_name, :created_at, :updated_at
+
+      def initialize(data)
+        @id = data['id']
+        @title = data['title']
+        @content = data['content']
+        @status = data['status']
+        @progress = data['progress']
+        @target_keyword = data['target_keyword']
+        @project_name = data['project_name']
+        @created_at = data['created_at']
+        @updated_at = data['updated_at']
+      end
+
+      def completed?
+        status == 'completed'
+      end
+
+      def in_progress?
+        status == 'in_progress' || status == 'processing'
+      end
+
+      def failed?
+        status == 'failed' || status == 'error'
+      end
+
+      def to_h
+        {
+          id: id,
+          title: title,
+          content: content,
+          status: status,
+          progress: progress,
+          target_keyword: target_keyword,
+          project_name: project_name,
+          created_at: created_at,
+          updated_at: updated_at
+        }
+      end
+    end
+
+    class GenerateArticleResponse
+      attr_reader :message, :success, :article_ids
+
+      def initialize(data)
+        @message = data['message']
+        @success = data['success']
+        @article_ids = data['article_ids'] || []
+      end
+
+      def success?
+        success == true
+      end
+
+      def has_article_ids?
+        !article_ids.empty?
+      end
+
+      def first_article_id
+        article_ids.first
+      end
+
+      def to_h
+        {
+          message: message,
+          success: success,
+          article_ids: article_ids
+        }
+      end
+    end
+
+    class GenerateArticleRequest
+      attr_reader :target_keyword, :project_name
+
+      def initialize(target_keyword, project_name = nil)
+        @target_keyword = target_keyword
+        @project_name = project_name
+      end
+
+      def to_h
+        {
+          target_keyword: target_keyword,
+          project_name: project_name
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
+    class StatusPoller
+      def initialize(client, article_id, max_attempts: 60, delay: 5)
+        @client = client
+        @article_id = article_id
+        @max_attempts = max_attempts
+        @delay = delay
+      end
+
+      def wait_for_completion
+        attempts = 0
+
+        loop do
+          article = @client.get_article(@article_id)
+          
+          return article if article.completed? || article.failed?
+
+          attempts += 1
+          if attempts >= @max_attempts
+            raise Error, "Article generation timed out after #{@max_attempts} attempts"
+          end
+
+          sleep(@delay)
+        end
+      end
+    end
+  end
+end

data/lib/semantic_pen/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SemanticPen
+  VERSION = '1.0.0'
+end

data/lib/semantic_pen.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'semantic_pen/version'
+require_relative 'semantic_pen/configuration'
+require_relative 'semantic_pen/client'
+require_relative 'semantic_pen/errors'
+require_relative 'semantic_pen/models'
+
+module SemanticPen
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+  end
+end

data/semantic_pen.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/semantic_pen/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'semantic_pen'
+  spec.version       = SemanticPen::VERSION
+  spec.authors       = ['SemanticPen Team']
+  spec.email         = ['support@semanticpen.com']
+
+  spec.summary       = 'Official Ruby SDK for SemanticPen API - AI-powered content generation'
+  spec.description   = 'A Ruby SDK for SemanticPen API that provides AI-powered content generation capabilities with a simple and intuitive interface.'
+  spec.homepage      = 'https://www.semanticpen.com'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/pushkarsingh32/semanticpen-ruby-sdk'
+  spec.metadata['changelog_uri'] = 'https://github.com/pushkarsingh32/semanticpen-ruby-sdk/blob/main/CHANGELOG.md'
+
+  spec.files = Dir['lib/**/*', 'examples/**/*', 'README.md', 'LICENSE', 'semantic_pen.gemspec']
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.6.0'
+
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'json', '~> 2.0'
+
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'webmock', '~> 3.0'
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: semantic_pen
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- SemanticPen Team
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-07-19 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: json
+  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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby SDK for SemanticPen API that provides AI-powered content generation
+  capabilities with a simple and intuitive interface.
+email:
+- support@semanticpen.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/basic_usage.rb
+- examples/bulk_generation.rb
+- examples/configuration_example.rb
+- examples/polling_example.rb
+- lib/semantic_pen.rb
+- lib/semantic_pen/client.rb
+- lib/semantic_pen/configuration.rb
+- lib/semantic_pen/errors.rb
+- lib/semantic_pen/models.rb
+- lib/semantic_pen/version.rb
+- semantic_pen.gemspec
+homepage: https://www.semanticpen.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.semanticpen.com
+  source_code_uri: https://github.com/pushkarsingh32/semanticpen-ruby-sdk
+  changelog_uri: https://github.com/pushkarsingh32/semanticpen-ruby-sdk/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: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for SemanticPen API - AI-powered content generation
+test_files: []