artificial 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20d89e77f87e37c150c0e2b3ebc0677f0a65e77c6a674aba37a9834d3986ba3b
+  data.tar.gz: baf31ac8198a8626ecac93a2719390c89155c49736321614b1375ca2889b46ea
+SHA512:
+  metadata.gz: 36291dba209504dbdcca673c6dcc4e6393807fef54e5184b0576b7f5137cb6873d69d23e3cf5926c414c6a9756ed809798dd03b4b70806c320de968f78b0b6b3
+  data.tar.gz: 53432117f9d4ba5465bc8b9a35f6c7c0a56e0e050d42a112751fc51dcfc47ddd94e9655998c02b140e4031466a9450a58c46dbd01e686f8e82f801160cc32427

data/README.md

@@ -0,0 +1,303 @@
+# Artificial
+
+A comprehensive Ruby gem for prompt engineering and management. Build, optimize, and maintain AI prompts with advanced features like role-based prompting, data separation, multi-format input support, and structured XML output.
+
+## Features
+
+- **Multi-format Input Support**: String, XML, YAML, JSON, and message arrays
+- **Role-based Prompting**: Expert role assignment for optimal AI performance
+- **Data Separation**: Clear separation between instructions and data
+- **XML Structure**: Structured prompts with proper organization
+- **Method Chaining**: Fluent API for building complex prompts
+- **Validation**: Built-in validation for messages and roles
+- **Hallucination Prevention**: Grounding requirements and source attribution
+- **Tool Integration**: Support for function calling and external tools
+- **Long Context Optimization**: Efficient handling of large documents
+- **Example Management**: Structured examples with input/output pairs
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add artificial
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install artificial
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'artificial'
+
+# Simple prompt creation
+prompt = Artificial::Prompt.new("What is Ruby?")
+puts prompt.to_s
+```
+
+### Role-based Prompting
+
+```ruby
+# Expert role assignment
+prompt = Artificial::Prompt.new(
+  text: "Explain object-oriented programming",
+  system: "You are a Ruby programming expert with 10 years of experience"
+)
+puts prompt.to_s
+```
+
+### Method Chaining
+
+```ruby
+# Fluent API for building complex prompts
+prompt = Artificial::Prompt.new("Analyze this code")
+  .with_system("You are a senior Ruby developer")
+  .with_context(audience: "junior developers", goal: "code review")
+  .with_examples({ input: "class MyClass; end", output: "Simple class definition" })
+  .with_thinking(enabled: true)
+  .with_grounding(require_quotes: true, require_sources: true)
+
+puts prompt.to_s
+```
+
+### Data Separation
+
+```ruby
+# Clear separation between instructions and data
+prompt = Artificial::Prompt.new(
+  instructions: "Analyze the sales data and identify trends",
+  data: {
+    q1_sales: "100000",
+    q2_sales: "120000",
+    q3_sales: "110000",
+    q4_sales: "130000"
+  }
+)
+puts prompt.to_s
+```
+
+### Tool Integration
+
+```ruby
+# Function calling support
+prompt = Artificial::Prompt.new("Calculate financial metrics")
+  .with_tools(
+    { name: "calculate_ratios", parameters: { data: "quarterly_reports" } },
+    { name: "generate_chart", parameters: { chart_type: "trend" } }
+  )
+puts prompt.to_s
+```
+
+### Message Arrays (Conversation Format)
+
+```ruby
+# Multi-turn conversations
+messages = [
+  { role: "system", content: "You are a helpful Ruby programming assistant" },
+  { role: "user", content: "How do I create a class in Ruby?" },
+  { role: "assistant", content: "You can create a class using the 'class' keyword" },
+  { role: "user", content: "Can you show me an example?" }
+]
+
+prompt = Artificial::Prompt.new(messages)
+puts prompt.to_s
+```
+
+### Multi-format Input Parsing
+
+```ruby
+# YAML format
+yaml_input = <<~YAML
+  text: "Explain Ruby blocks"
+  system: "You are a Ruby expert"
+  context:
+    audience: "beginners"
+    goal: "education"
+YAML
+
+parsed = Artificial.parse(yaml_input)
+puts parsed.to_hash[:text]  # "Explain Ruby blocks"
+
+# JSON format
+json_input = '{"text": "What are Ruby gems?", "system": "You are a Ruby expert"}'
+parsed = Artificial.parse(json_input)
+puts parsed.to_hash[:text]  # "What are Ruby gems?"
+
+# Auto-detection
+parsed = Artificial.parse("Simple text prompt")
+puts parsed.to_hash[:format]  # "string"
+```
+
+### Validation
+
+```ruby
+# Message validation
+messages = [
+  { role: "system", content: "You are helpful" },
+  { role: "user", content: "Hello" }
+]
+
+validator = Artificial.validate_messages(messages)
+puts validator.valid?  # true
+
+# Role validation with optimization suggestions
+validator = Artificial.validate_role("You are a Ruby programming expert")
+puts validator.valid?      # true
+puts validator.effective?  # true
+puts validator.optimization_suggestions.join("; ")
+```
+
+### Long Context Documents
+
+```ruby
+# Efficient handling of large documents
+prompt = Artificial::Prompt.new("Summarize the key findings")
+  .with_documents(
+    {
+      content: "Long research document content...",
+      source: "research_report.pdf",
+      metadata: { author: "Dr. Smith", date: "2024-01-15" }
+    }
+  )
+puts prompt.to_s
+```
+
+### Advanced Features
+
+```ruby
+# Comprehensive prompt with all features
+prompt = Artificial::Prompt.new(
+  text: "Analyze this code",
+  system: "You are a senior Ruby developer",
+  context: {
+    audience: "junior developers",
+    goal: "identify improvements",
+    workflow: "code_review"
+  },
+  examples: [
+    { input: "bad_code.rb", output: "improvement_suggestions" }
+  ],
+  thinking: { enabled: true, style: "step_by_step" },
+  grounding: {
+    require_quotes: true,
+    require_sources: true,
+    allow_uncertainty: true
+  },
+  constraints: [
+    "Quote specific code sections",
+    "Provide actionable suggestions",
+    "Consider performance implications"
+  ]
+)
+
+puts prompt.to_s
+```
+
+## API Reference
+
+### Artificial::Prompt
+
+Main class for creating and managing prompts.
+
+#### Methods
+
+- `new(input = nil, **options)` - Create a new prompt
+- `to_s` - Generate the final prompt string
+- `with_system(system_prompt)` - Set system prompt with role validation
+- `with_context(**context_options)` - Add contextual information
+- `with_examples(*examples)` - Add structured examples
+- `with_thinking(enabled: true, style: 'step_by_step')` - Enable step-by-step reasoning
+- `with_grounding(**options)` - Add hallucination prevention
+- `with_constraints(*constraints)` - Add explicit constraints
+- `with_tools(*tools)` - Add function calling tools
+- `with_documents(*documents)` - Add long context documents
+- `with_data(data_hash)` - Add data separate from instructions
+- `with_prefill(text)` - Set assistant response prefill
+
+### Artificial Module Methods
+
+- `Artificial.create_prompt(input, **options)` - Factory method for creating prompts
+- `Artificial.parse(input, format: :auto)` - Parse input in various formats
+- `Artificial.validate_messages(messages)` - Validate message array structure
+- `Artificial.validate_role(system_prompt)` - Validate and optimize role prompts
+
+## Advanced Usage
+
+### Custom Parsers
+
+The gem supports multiple input formats with automatic detection:
+
+```ruby
+# Explicit format specification
+xml_parsed = Artificial.parse(xml_string, format: :xml)
+yaml_parsed = Artificial.parse(yaml_string, format: :yaml)
+json_parsed = Artificial.parse(json_string, format: :json)
+
+# Auto-detection (recommended)
+auto_parsed = Artificial.parse(input_string)  # Automatically detects format
+```
+
+### Validation and Optimization
+
+```ruby
+# Role optimization suggestions
+validator = Artificial.validate_role("You are helpful")
+puts validator.effective?  # false - generic role
+puts validator.optimization_suggestions
+# => ["Generic roles may reduce AI performance. Consider specifying domain expertise"]
+
+# Effective role
+validator = Artificial.validate_role("You are a Ruby programming expert with 10 years of experience")
+puts validator.effective?  # true
+puts validator.optimization_suggestions
+# => ["Excellent! Domain expert roles typically improve response quality by 20-30%"]
+```
+
+### Error Handling
+
+```ruby
+begin
+  # Invalid message structure
+  messages = [{ role: "invalid", content: "test" }]
+  Artificial::Prompt.new(messages)
+rescue ArgumentError => e
+  puts e.message  # "Message at index 0 has invalid role 'invalid'"
+end
+```
+
+## Examples
+
+See the `examples/demo.rb` file for a comprehensive demonstration of all features.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/roboruby/artificial.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Performance Benefits
+
+Based on industry best practices from Anthropic's research, this gem provides:
+
+- **Reduced hallucinations** through grounding requirements and source attribution
+- **Better context handling** for long documents (20K+ tokens)
+- **Structured output** that's easier to parse and validate
+- **Optimized prompts** that follow proven patterns for maximum effectiveness
+
+## Alignment with Industry Standards
+
+This gem implements prompt engineering techniques aligned with:
+
+- Anthropic's Interactive Prompt Engineering Tutorial
+- OpenAI's best practices for function calling
+- Production-ready hallucination prevention strategies

data/Rakefile

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+# Default task runs tests
+task default: [:test]
+
+# Main test task - runs all tests
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
+  t.verbose = true
+end
+
+# Individual test tasks for specific test files
+namespace :test do
+  desc 'Run all tests'
+  Rake::TestTask.new(:all) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.test_files = FileList['test/**/test_*.rb']
+    t.verbose = true
+  end
+
+  desc 'Run core prompt tests'
+  Rake::TestTask.new(:prompt) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.test_files = FileList['test/test_artificial.rb']
+    t.verbose = true
+  end
+
+  desc 'Run parser and validator tests'
+  Rake::TestTask.new(:parsers) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.test_files = FileList['test/test_parsers.rb']
+    t.verbose = true
+  end
+
+  desc 'Run tests with verbose output'
+  Rake::TestTask.new(:verbose) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.test_files = FileList['test/**/test_*.rb']
+    t.verbose = true
+    t.options = '--verbose'
+  end
+end
+
+# Demo task to run the examples
+desc 'Run the demo script'
+task :demo do
+  ruby 'examples/demo.rb'
+end
+
+# Code quality tasks
+desc 'Run RuboCop'
+task :rubocop do
+  sh 'rubocop'
+end
+
+desc 'Run all quality checks'
+task quality: %i[test rubocop]
+
+# Help task
+desc 'Show available tasks'
+task :help do
+  puts <<~HELP
+    Available Rake tasks:
+
+    Main tasks:
+      rake                 # Run all tests (default)
+      rake test            # Run all tests
+      rake demo            # Run the demo script
+
+    Test tasks:
+      rake test:all        # Run all tests
+      rake test:prompt     # Run core prompt tests only
+      rake test:parsers    # Run parser and validator tests only
+      rake test:verbose    # Run tests with verbose output
+
+    Quality tasks:
+      rake rubocop         # Run RuboCop code analysis
+      rake quality         # Run tests and RuboCop
+
+    Other tasks:
+      rake build           # Build gem
+      rake install         # Install gem locally
+      rake release         # Release gem (maintainers only)
+      rake help            # Show this help message
+
+    Examples:
+      rake                 # Quick test run
+      rake test:prompt     # Test just the core functionality
+      rake demo            # See the gem in action
+      rake quality         # Full quality check before committing
+  HELP
+end

data/examples/demo.rb

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add lib to the load path
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'artificial'
+
+puts '=== Artificial Ruby Gem Demo ==='
+puts "Version: #{Artificial::VERSION}"
+puts
+
+# Example 1: Basic prompt creation
+puts '1. Basic Prompt Creation:'
+prompt = Artificial::Prompt.new('What is Ruby?')
+puts prompt
+puts
+
+# Example 2: Role-based prompting
+puts '2. Role-Based Prompting:'
+prompt = Artificial::Prompt.new(
+  text: 'Explain object-oriented programming',
+  system: 'You are a Ruby programming expert with 10 years of experience'
+)
+puts prompt
+puts
+
+# Example 3: Method chaining
+puts '3. Method Chaining:'
+prompt = Artificial::Prompt.new('Analyze this code')
+                           .with_system('You are a senior Ruby developer')
+                           .with_context(audience: 'junior developers', goal: 'code review')
+                           .with_examples({ input: 'class MyClass; end', output: 'Simple class definition' })
+                           .with_thinking(enabled: true)
+                           .with_grounding(require_quotes: true, require_sources: true)
+
+puts prompt
+puts
+
+# Example 4: Data separation
+puts '4. Data Separation:'
+prompt = Artificial::Prompt.new(
+  instructions: 'Analyze the sales data and identify trends',
+  data: {
+    q1_sales: '100000',
+    q2_sales: '120000',
+    q3_sales: '110000',
+    q4_sales: '130000'
+  }
+)
+puts prompt
+puts
+
+# Example 5: Tool integration
+puts '5. Tool Integration:'
+prompt = Artificial::Prompt.new('Calculate financial metrics')
+                           .with_tools(
+                             { name: 'calculate_ratios', parameters: { data: 'quarterly_reports' } },
+                             { name: 'generate_chart', parameters: { chart_type: 'trend' } }
+                           )
+puts prompt
+puts
+
+# Example 6: Long context documents
+puts '6. Long Context Documents:'
+prompt = Artificial::Prompt.new('Summarize the key findings')
+                           .with_documents(
+                             {
+                               content: 'This is a sample research document with important findings...',
+                               source: 'research_report.pdf',
+                               metadata: { author: 'Dr. Smith', date: '2024-01-15' }
+                             }
+                           )
+puts prompt
+puts
+
+# Example 7: Message array (conversation format)
+puts '7. Message Array (Conversation Format):'
+messages = [
+  { role: 'system', content: 'You are a helpful Ruby programming assistant' },
+  { role: 'user', content: 'How do I create a class in Ruby?' },
+  { role: 'assistant', content: "You can create a class using the 'class' keyword" },
+  { role: 'user', content: 'Can you show me an example?' }
+]
+prompt = Artificial::Prompt.new(messages)
+puts prompt
+puts
+
+# Example 8: Auto-parsing different formats
+puts '8. Auto-Parsing Different Formats:'
+
+# YAML format
+yaml_input = <<~YAML
+  text: "Explain Ruby blocks"
+  system: "You are a Ruby expert"
+  context:
+    audience: "beginners"
+    goal: "education"
+YAML
+
+parsed_yaml = Artificial.parse(yaml_input)
+puts "YAML parsed as: #{parsed_yaml.to_hash[:format]}"
+puts "Text: #{parsed_yaml.to_hash[:text]}"
+puts
+
+# JSON format
+json_input = '{"text": "What are Ruby gems?", "system": "You are a Ruby expert"}'
+parsed_json = Artificial.parse(json_input)
+puts "JSON parsed as: #{parsed_json.to_hash[:format]}"
+puts "Text: #{parsed_json.to_hash[:text]}"
+puts
+
+# Example 9: Validation
+puts '9. Validation:'
+
+# Valid messages
+valid_messages = [
+  { role: 'system', content: 'You are helpful' },
+  { role: 'user', content: 'Hello' }
+]
+validator = Artificial.validate_messages(valid_messages)
+puts "Messages valid: #{validator.valid?}"
+
+# Role validation
+role_validator = Artificial.validate_role('You are a Ruby programming expert')
+puts "Role valid: #{role_validator.valid?}"
+puts "Role effective: #{role_validator.effective?}"
+puts "Suggestions: #{role_validator.optimization_suggestions.join('; ')}"
+puts
+
+# Example 10: Factory method
+puts '10. Factory Method:'
+prompt = Artificial.create_prompt('Hello world', system: 'You are helpful')
+puts prompt
+puts
+
+puts '=== Demo Complete ==='
+puts 'For more examples, check the documentation at https://rubydoc.info/gems/artificial'

data/lib/artificial/parsers/json_parser.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Artificial
+  module Parsers
+    class JSONParser
+      attr_reader :input, :parsed_data, :errors
+
+      def initialize(input)
+        @input = input
+        @parsed_data = {}
+        @errors = []
+      end
+
+      def parse
+        return self unless valid?
+
+        begin
+          json_data = JSON.parse(@input)
+          @parsed_data = normalize_json_data(json_data)
+          @parsed_data[:format] = 'json'
+          @parsed_data[:type] = 'structured_json'
+        rescue JSON::ParserError => e
+          @errors << "JSON parsing error: #{e.message}"
+        rescue StandardError => e
+          @errors << "JSON processing error: #{e.message}"
+        end
+
+        self
+      end
+
+      def valid?
+        return false unless @input.is_a?(String)
+        return false if @input.strip.empty?
+
+        begin
+          JSON.parse(@input)
+          true
+        rescue JSON::ParserError => e
+          @errors << "Invalid JSON: #{e.message}"
+          false
+        rescue StandardError => e
+          @errors << "JSON validation error: #{e.message}"
+          false
+        end
+      end
+
+      def to_hash
+        @parsed_data
+      end
+
+      private
+
+      def normalize_json_data(json_data)
+        return {} unless json_data.is_a?(Hash)
+
+        # Convert string keys to symbols for consistency
+        normalized = {}
+        json_data.each do |key, value|
+          symbol_key = key.to_s.to_sym
+          normalized[symbol_key] = normalize_value(value)
+        end
+
+        # Ensure common fields are present
+        normalized[:text] ||= normalized[:instructions]
+        normalized[:examples] ||= []
+        normalized[:context] ||= {}
+        normalized[:grounding] ||= {}
+        normalized[:tools] ||= []
+
+        # Handle special JSON structures
+        normalized[:messages] = normalize_messages(normalized[:messages]) if normalized[:messages].is_a?(Array)
+
+        normalized
+      end
+
+      def normalize_value(value)
+        case value
+        when Hash
+          value.transform_keys { |k| k.to_s.to_sym }
+        when Array
+          value.map { |v| normalize_value(v) }
+        else
+          value
+        end
+      end
+
+      def normalize_messages(messages)
+        messages.map do |message|
+          if message.is_a?(Hash)
+            {
+              role: message['role']&.to_s || message[:role]&.to_s,
+              content: message['content'] || message[:content]
+            }
+          else
+            message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/artificial/parsers/string_parser.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Artificial
+  module Parsers
+    class StringParser
+      attr_reader :input, :parsed_data
+
+      def initialize(input)
+        @input = input
+        @parsed_data = {}
+      end
+
+      def parse
+        @parsed_data = {
+          text: @input,
+          format: 'string',
+          type: 'simple_text'
+        }
+        self
+      end
+
+      def valid?
+        @input.is_a?(String) && !@input.empty?
+      end
+
+      def to_hash
+        @parsed_data
+      end
+    end
+  end
+end