Skip to content

pushkarsingh32/semanticpen-ruby-sdk

Repository files navigation

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:

gem 'semantic_pen'

And then execute:

bundle install

Or install it yourself as:

gem install semantic_pen

Quick Start

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

client = SemanticPen::Client.new(api_key: 'your-api-key')

Custom Configuration

client = SemanticPen::Client.new(
  api_key: 'your-api-key',
  base_url: 'https://api.semanticpen.com',
  timeout: 120  # 2 minutes
)

Global Configuration

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:

export SEMANTIC_PEN_API_KEY=your-api-key
export SEMANTIC_PEN_BASE_URL=https://www.semanticpen.com
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:

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:

article = client.get_article('article-id')

Parameters:

  • article_id (required): The ID of the article to retrieve

Returns: SemanticPen::Models::Article

Models

Article

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

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:

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:

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:

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:

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:

bundle install

To run tests:

bundle exec rspec

To run RuboCop for code style:

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.

License

This project is licensed under the MIT License - see the 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

About

Official Ruby SDK for SemanticPen API - AI-powered content generation

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages