open_router_enhanced 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e01a3e4ebadd327148dc9f04efacd94166195e789adb0f77d20dbc83f70b234
+  data.tar.gz: 902c36d9a9d243e63ab8065456526875d19bc268450720e1ee29ee24493e7e35
+SHA512:
+  metadata.gz: de0e475b38181bec11bcde85a9a571eec12306eb5a755a70fae173d4743e28ee59d232adf7d3e42efc7b2693500947678848381b36b1ae30b47bdf479e51dca0
+  data.tar.gz: f91b409a150fae9af10bedddd9d0c22b6c3683096e9125e4f1310434795b0fea537ea39c1fbdf923e523e61fdc3a5ac9d9b8727e9b78c6d676e0a07d96a5663c

data/.env.example

@@ -0,0 +1 @@
+OPENROUTER_API_KEY=sk-or-

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.3
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes

data/.rubocop_todo.yml

@@ -0,0 +1,130 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-10-07 18:18:35 UTC using RuboCop version 1.79.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# Configuration parameters: Severity, Include.
+# Include: **/*.gemspec
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'open_router_enhanced.gemspec'
+
+# Offense count: 1
+Lint/ShadowedException:
+  Exclude:
+    - 'lib/open_router/model_registry.rb'
+
+# Offense count: 19
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect, IgnoreEmptyBlocks, AllowUnusedKeywordArguments.
+Lint/UnusedBlockArgument:
+  Exclude:
+    - 'spec/force_structured_output_spec.rb'
+    - 'spec/integration/structured_output_flow_spec.rb'
+
+# Offense count: 24
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 69
+
+# Offense count: 183
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 464
+
+# Offense count: 7
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 339
+
+# Offense count: 16
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 21
+
+# Offense count: 44
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 42
+
+# Offense count: 6
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 10
+
+# Offense count: 13
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 22
+
+# Offense count: 1
+Naming/ConstantName:
+  Exclude:
+    - 'spec/response_healing_spec.rb'
+
+# Offense count: 4
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
+# NamePrefix: is_, has_, have_, does_
+# ForbiddenPrefixes: is_, has_, have_, does_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicatePrefix:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/open_router/model_registry.rb'
+    - 'lib/open_router/response.rb'
+
+# Offense count: 6
+# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
+# SupportedStyles: snake_case, normalcase, non_integer
+# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
+Naming/VariableNumber:
+  Exclude:
+    - 'spec/vcr/prompt_template_spec.rb'
+
+# Offense count: 9
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/open_router.rb'
+    - 'lib/open_router/client.rb'
+    - 'lib/open_router/http.rb'
+    - 'lib/open_router/model_registry.rb'
+    - 'lib/open_router/response.rb'
+    - 'lib/open_router/schema.rb'
+    - 'lib/open_router/tool.rb'
+    - 'lib/open_router/tool_call.rb'
+
+# Offense count: 8
+# This cop supports safe autocorrection (--autocorrect).
+Style/IfUnlessModifier:
+  Exclude:
+    - 'lib/open_router/client.rb'
+    - 'lib/open_router/model_registry.rb'
+
+# Offense count: 12
+Style/MultilineBlockChain:
+  Exclude:
+    - 'spec/vcr/error_handling_spec.rb'
+    - 'spec/vcr/model_fallback_spec.rb'
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods.
+# AllowedMethods: respond_to_missing?
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/open_router/schema.rb'
+
+# Offense count: 37
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 210

data/.ruby-version

@@ -0,0 +1 @@
+3.3.9

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+## [Unreleased]
+
+## [1.0.0] - 2025-10-07
+
+### Major Features
+- **Tool Calling**: Complete function calling support with DSL-based tool definitions and automatic validation
+- **Structured Outputs**: Native and forced JSON schema support with automatic response healing
+- **Model Selection**: Intelligent model selection with fluent DSL, capability detection, and cost optimization
+- **Model Fallbacks**: Automatic failover routing with model arrays for reliability
+- **Response Healing**: Self-correcting malformed JSON outputs from non-native structured output models
+- **Streaming Client**: Real-time streaming with comprehensive callback system
+- **Usage Tracking**: Token usage and cost analytics with detailed metrics
+- **Prompt Templates**: Reusable templates with variable interpolation
+
+### Enhanced
+- **Model Registry**: Local caching with automatic capability detection and cost calculation
+- **Response Object**: Rich metadata including tokens, costs, cache hits, and performance analytics
+- **Error Handling**: Comprehensive error hierarchy with specific error types for better debugging
+- **VCR Testing**: Complete real API integration testing coverage
+- **Documentation**: Extensive guides, examples, and API reference
+
+### Compatibility
+- Full backward compatibility with original OpenRouter gem
+- Ruby 3.0+ support
+- Optional dependencies for enhanced features (json-schema for validation)
+
+## [0.3.0] - 2024-05-03
+
+### Changed
+- Uses Faraday's built-in JSON mode
+- Added support for configuring Faraday and its middleware
+- Spec creates a STDOUT logger by default (headers, bodies, errors)  
+- Spec filters Bearer token from logs by default
+
+## [0.1.0] - 2024-03-19
+
+### Added
+- Initial release of OpenRouter Ruby gem
+- Basic chat completion support
+- Model selection and routing
+- OpenRouter API integration

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at opensource@ericstiens.dev. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/CONTRIBUTING.md

@@ -0,0 +1,384 @@
+# Contributing to OpenRouter Ruby Gem
+
+Thank you for your interest in contributing to the OpenRouter Ruby gem! This document provides guidelines for contributing to the project.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Contributing Process](#contributing-process)
+- [Code Standards](#code-standards)
+- [Testing Guidelines](#testing-guidelines)
+- [Documentation](#documentation)
+- [Submitting Changes](#submitting-changes)
+- [Release Process](#release-process)
+
+## Getting Started
+
+### Prerequisites
+
+- Ruby 3.2.2 or higher
+- Bundler
+- Git
+- OpenRouter API key (for VCR tests)
+
+### Development Setup
+
+1. **Fork and Clone**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/open_router.git
+   cd open_router
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   bundle install
+   ```
+
+3. **Set Environment Variables**
+   ```bash
+   export OPENROUTER_API_KEY="your_api_key_here"
+   ```
+
+4. **Run Tests**
+   ```bash
+   bundle exec rspec
+   ```
+
+5. **Interactive Console**
+   ```bash
+   bundle exec pry -I lib -r open_router
+   ```
+
+## Contributing Process
+
+### 1. Choose an Issue
+
+- Look for issues labeled `good first issue` for newcomers
+- Check existing issues or create a new one for discussion
+- Comment on the issue to indicate you're working on it
+
+### 2. Create a Feature Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 3. Follow Development Workflow
+
+1. **Write Tests First** (TDD approach)
+   - Unit tests for new functionality
+   - VCR integration tests for API interactions
+   - Edge case and error handling tests
+
+2. **Implement Feature**
+   - Follow existing code patterns
+   - Add comprehensive error handling
+   - Include documentation comments
+
+3. **Update Documentation**
+   - Update relevant docs/ files
+   - Add examples to README if needed
+   - Update CHANGELOG.md
+
+4. **Test Thoroughly**
+   ```bash
+   bundle exec rspec
+   bundle exec rubocop
+   ```
+
+## Code Standards
+
+### Ruby Style
+
+Follow the existing codebase patterns and RuboCop configuration:
+
+```bash
+# Check style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+### Design Patterns
+
+#### DSL Design
+- Use descriptive method names
+- Chain methods fluently
+- Provide sensible defaults
+- Include parameter validation
+
+```ruby
+# Good
+tool = OpenRouter::Tool.define do
+  name "search_api"
+  description "Search external API for information"
+  
+  parameters do
+    string :query, required: true, description: "Search query"
+    integer :limit, minimum: 1, maximum: 100, default: 10
+  end
+end
+
+# Bad
+tool = OpenRouter::Tool.new(name: "search", params: { q: { type: "string" } })
+```
+
+#### Error Handling
+- Use specific error classes
+- Provide helpful error messages
+- Include context in errors
+
+```ruby
+# Good
+raise OpenRouter::ToolCallError, 
+      "Tool '#{tool_name}' validation failed: #{validation_errors.join(', ')}"
+
+# Bad
+raise StandardError, "Invalid tool"
+```
+
+#### Backward Compatibility
+- Ensure all changes are backward compatible
+- Use feature flags for experimental features
+- Deprecate features gradually with warnings
+
+### Documentation
+
+#### Code Comments
+- Document complex algorithms
+- Explain non-obvious business logic
+- Include examples for public methods
+
+```ruby
+# Calculates the estimated cost for a completion request.
+# Takes into account both input and output token costs.
+#
+# @param model [String] The model identifier
+# @param input_tokens [Integer] Number of input tokens
+# @param output_tokens [Integer] Number of output tokens
+# @return [Float] Estimated cost in USD
+def calculate_estimated_cost(model, input_tokens:, output_tokens:)
+  # Implementation...
+end
+```
+
+#### Markdown Documentation
+- Use clear headings and structure
+- Include practical examples
+- Provide troubleshooting sections
+- Link between related documentation
+
+## Testing Guidelines
+
+### Test Organization
+
+```
+spec/
+├── unit/                    # Fast unit tests
+│   ├── tool_spec.rb
+│   ├── schema_spec.rb
+│   └── model_selector_spec.rb
+├── integration/             # Cross-module integration tests
+│   └── client_integration_spec.rb
+├── vcr/                     # Real API interaction tests
+│   ├── tool_calling_spec.rb
+│   ├── structured_outputs_spec.rb
+│   └── model_registry_spec.rb
+└── support/
+    └── vcr.rb              # VCR configuration
+```
+
+### Test Writing Guidelines
+
+#### Unit Tests
+```ruby
+# Good: Clear, focused test
+RSpec.describe OpenRouter::Tool do
+  describe "#to_json_schema" do
+    it "generates valid JSON schema for simple parameters" do
+      tool = described_class.define do
+        name "test_tool"
+        parameters do
+          string :query, required: true
+        end
+      end
+      
+      schema = tool.to_json_schema
+      expect(schema[:parameters][:required]).to include("query")
+    end
+  end
+end
+```
+
+#### VCR Tests
+```ruby
+# Good: Real API interaction test
+RSpec.describe "Tool Calling", :vcr do
+  it "handles real tool calling workflow" do
+    response = client.complete(
+      messages,
+      model: "anthropic/claude-3.5-sonnet",
+      tools: [tool],
+      tool_choice: "auto"
+    )
+    
+    expect(response.has_tool_calls?).to be true
+    expect(response.tool_calls.first.name).to eq("test_tool")
+  end
+end
+```
+
+### VCR Best Practices
+
+1. **Use Descriptive Cassette Names**
+   ```ruby
+   it "handles complex tool parameters", vcr: { cassette_name: "tool_complex_parameters" } do
+   ```
+
+2. **Filter Sensitive Data**
+   - API keys are automatically filtered
+   - Add custom filters for other sensitive data
+
+3. **Keep Cassettes Fresh**
+   ```bash
+   # Re-record all cassettes
+   rm -rf spec/fixtures/vcr_cassettes/
+   bundle exec rspec spec/vcr/
+   ```
+
+## Documentation
+
+### Types of Documentation
+
+1. **API Documentation** - In-code documentation for public methods
+2. **User Guides** - Step-by-step tutorials in docs/
+3. **Examples** - Working examples in examples/
+4. **README** - Overview and quick start guide
+5. **CHANGELOG** - Version history and breaking changes
+
+### Documentation Standards
+
+- **Clear Examples**: Always include working code examples
+- **Complete Coverage**: Document all public APIs
+- **Troubleshooting**: Include common issues and solutions
+- **Links**: Cross-reference related documentation
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Ensure Quality**
+   ```bash
+   bundle exec rspec      # All tests pass
+   bundle exec rubocop    # Style checks pass
+   ```
+
+2. **Update Documentation**
+   - Add examples for new features
+   - Update relevant docs/ files
+   - Update CHANGELOG.md
+
+3. **Create Pull Request**
+   - Use descriptive title and description
+   - Reference related issues
+   - Include testing notes
+
+4. **Pull Request Template**
+   ```markdown
+   ## Description
+   Brief description of changes
+
+   ## Type of Change
+   - [ ] Bug fix
+   - [ ] New feature
+   - [ ] Breaking change
+   - [ ] Documentation update
+
+   ## Testing
+   - [ ] Unit tests added/updated
+   - [ ] VCR tests added/updated
+   - [ ] Manual testing completed
+
+   ## Checklist
+   - [ ] Code follows style guidelines
+   - [ ] Self-review completed
+   - [ ] Documentation updated
+   - [ ] CHANGELOG.md updated
+   ```
+
+### Code Review Guidelines
+
+#### For Authors
+- Respond to feedback promptly
+- Ask questions if feedback is unclear
+- Make requested changes or explain reasoning
+
+#### For Reviewers
+- Be constructive and specific
+- Focus on code quality and maintainability
+- Test the changes locally when possible
+
+## Release Process
+
+### Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes (backward compatible)
+
+### Release Checklist
+
+1. **Update Version**
+   ```ruby
+   # lib/open_router/version.rb
+   VERSION = "0.4.0"
+   ```
+
+2. **Update CHANGELOG.md**
+   - Move items from [Unreleased] to new version
+   - Add release date
+   - Create new [Unreleased] section
+
+3. **Run Full Test Suite**
+   ```bash
+   bundle exec rspec
+   bundle exec rspec spec/vcr/  # With fresh recordings
+   ```
+
+4. **Update Documentation**
+   - Ensure README is current
+   - Verify all examples work
+   - Check link validity
+
+5. **Create Release**
+   ```bash
+   git tag v0.4.0
+   git push origin v0.4.0
+   gem build open_router.gemspec
+   gem push open_router-0.4.0.gem
+   ```
+
+## Getting Help
+
+- **Questions**: Open a discussion or issue
+- **Bugs**: Create an issue with reproduction steps
+- **Features**: Discuss in an issue before implementing
+
+## Code of Conduct
+
+This project follows our [Code of Conduct](CODE_OF_CONDUCT.md). Please read and follow it in all interactions.
+
+## Recognition
+
+Contributors are recognized in:
+- CHANGELOG.md for significant contributions
+- GitHub contributors page
+- Special thanks in release notes
+
+Thank you for contributing to OpenRouterEnhanced Ruby gem! 🚀

data/Gemfile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in open_router.gemspec
+gemspec
+
+gem "activesupport", ">= 6.0"
+gem "json-schema"
+
+group :development, :test do
+  gem "dotenv", ">= 2"
+  gem "pry", ">= 0.14"
+  gem "vcr", "~> 6.2"
+  gem "webmock", "~> 3.19"
+end
+
+group :development do
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.0"
+  gem "rubocop", require: false
+end