pangram 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0366ca93432eaa95c91f307b3b1ebc3bfb7d3e0e23c13e57ae6ce32b03e15b94
+  data.tar.gz: e1b5a5f13e60dad75b78781446759b66219f060088aae07f3c135403a0dade37
+SHA512:
+  metadata.gz: 0a5b2d970317274451d40d5ee847fce196bd776612dc2bddef6f680150bcdb2ccb9c6b4deafc10728998ec238e0c5195e6cc4a5adc1b3aa411202b019a7f17d6
+  data.tar.gz: 0abcdcf76d3199b9dff883e364a5894292901b3bb03127ff5f03d550bc811d078bfb0f622de4e4e80be1948e6d27aa250d037e0820ab10f0a192bbafe5bda2aa

data/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.1', '3.2', '3.3', '3.4', '4.0']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - run: bundle exec rake spec
+
+  lint-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+      - run: bundle exec rubocop
+      - run: bundle exec rake build

data/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release Gem
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '4.0'
+        bundler-cache: true
+
+    - name: Verify tag matches gem version
+      id: version
+      run: |
+        tag="${GITHUB_REF_NAME#v}"
+        version="$(ruby -Ilib -e 'require "pangram/version"; print Pangram::VERSION')"
+        if [ "$tag" != "$version" ]; then
+          echo "Tag v$tag does not match Pangram::VERSION $version"
+          exit 1
+        fi
+        echo "version=$version" >> "$GITHUB_OUTPUT"
+
+    - name: Extract release notes from CHANGELOG.md
+      env:
+        VERSION: ${{ steps.version.outputs.version }}
+      run: |
+        awk -v ver="$VERSION" '
+          index($0, "## [" ver "]") == 1 { found=1; next }
+          found && /^## / { exit }
+          found { print }
+        ' CHANGELOG.md > release_notes.md
+        if ! grep -q '[^[:space:]]' release_notes.md; then
+          echo "No CHANGELOG.md entry found for version $VERSION"
+          exit 1
+        fi
+
+    - name: Run tests
+      run: bundle exec rake spec
+
+    - name: Run RuboCop
+      run: bundle exec rubocop
+
+    - name: Build gem
+      run: bundle exec rake build
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        files: pkg/pangram-${{ steps.version.outputs.version }}.gem
+        body_path: release_notes.md
+        draft: false
+        prerelease: false
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Publish to RubyGems
+      run: |
+        if [ -z "$GEM_HOST_API_KEY" ]; then
+          echo "Secret RUBYGEMS_API_KEY is not set"
+          exit 1
+        fi
+        gem push "pkg/pangram-${VERSION}.gem"
+      env:
+        VERSION: ${{ steps.version.outputs.version }}
+        GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,11 @@
+*.gem
+/.bundle/
+/.yardoc/
+/coverage/
+/doc/
+/pkg/
+/tmp/
+/vendor/bundle/
+.DS_Store
+.ruby-lsp/
+.rspec_status

data/.mise.toml

@@ -0,0 +1,3 @@
+# Project toolchain configuration. Run `mise install` after cloning.
+[tools]
+ruby = "latest"

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,31 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'Gemfile'
+    - 'Rakefile'
+    - 'pangram.gemspec'
+    - 'vendor/**/*'
+
+Layout/LineLength:
+  Max: 120
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Max: 500
+
+Metrics/MethodLength:
+  Max: 45
+
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/ParameterLists:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-14
+
+- Add model discovery and asynchronous text prediction.
+- Add bulk submission, status polling, pagination, and result aggregation.
+- Add single and multi-file prediction.
+- Add plagiarism detection.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,110 @@
+PATH
+  remote: .
+  specs:
+    pangram (0.1.0)
+      faraday (>= 1.8, < 3.0)
+      faraday-multipart (~> 1.0)
+      faraday-net_http (>= 1.0, < 4.0)
+      json (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.1.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    faraday (2.14.3)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-multipart (1.2.0)
+      multipart-post (~> 2.0)
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
+    hashdiff (1.2.1)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    multipart-post (2.4.1)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    parallel (1.28.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.89.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.45)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  bundler (>= 2.0, < 3.0)
+  pangram!
+  parallel (~> 1.0)
+  public_suffix (< 7.0)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.0)
+  simplecov (~> 0.22)
+  webmock (~> 3.0)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.6.9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pangram Ruby SDK Contributors
+
+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/Makefile

@@ -0,0 +1,66 @@
+.PHONY: help install test spec coverage lint lint-fix docs build verify clean console tag
+
+help: ## Show available commands
+	@awk 'BEGIN {FS = ":.*## "; printf "Usage: make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*## / {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Install gem dependencies
+	bundle install
+
+spec: ## Run the RSpec test suite
+	bundle exec rake spec
+
+test: spec ## Alias for spec
+
+coverage: spec ## Generate the test coverage report
+	@echo "Coverage report: coverage/index.html"
+
+lint: ## Run RuboCop
+	bundle exec rubocop
+
+lint-fix: ## Run RuboCop with safe and unsafe auto-corrections
+	bundle exec rubocop -A
+
+docs: ## Generate YARD API documentation in doc/
+	bundle exec yard doc --output-dir doc
+
+build: ## Build the gem in pkg/
+	bundle exec rake build
+
+verify: spec lint docs build ## Run all release checks
+
+clean: ## Remove generated artifacts
+	rm -rf .yardoc coverage doc pkg .rspec_status
+
+console: ## Start IRB with Pangram loaded
+	bundle exec irb -Ilib -rpangram
+
+tag: ## Tag a release and push it. Usage: make tag [VERSION=x.y.z] [FORCE=1]
+	@set -e; \
+	git diff --cached --quiet || { echo "Error: 索引中已有暂存改动，请先提交或 git reset"; exit 1; }; \
+	git fetch --tags --quiet; \
+	CURRENT=$$(ruby -Ilib -rpangram/version -e 'print Pangram::VERSION'); \
+	if [ -n "$(VERSION)" ]; then \
+		NEW_VERSION=$$(echo "$(VERSION)" | sed 's/^v//'); \
+	elif git rev-parse -q --verify "refs/tags/v$$CURRENT" >/dev/null; then \
+		NEW_VERSION=$$(ruby -e 'a = ARGV[0].split("."); a[2] = a[2].to_i + 1; print a.join(".")' "$$CURRENT"); \
+	else \
+		NEW_VERSION=$$CURRENT; \
+	fi; \
+	echo "$$NEW_VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$$' || { echo "Error: 非法版本号 $$NEW_VERSION"; exit 1; }; \
+	NEW_TAG="v$$NEW_VERSION"; \
+	if git rev-parse -q --verify "refs/tags/$$NEW_TAG" >/dev/null; then \
+		[ -n "$(FORCE)" ] || { echo "Error: $$NEW_TAG 已存在。RubyGems 同版本不可重复发布，确认要重来请加 FORCE=1"; exit 1; }; \
+		echo "FORCE: 删除已存在的 $$NEW_TAG ..."; \
+		git tag -d "$$NEW_TAG"; \
+		git push origin --delete "$$NEW_TAG" || true; \
+	fi; \
+	grep -q "^## \[$$NEW_VERSION\]" CHANGELOG.md || { echo "Error: CHANGELOG.md 缺少 ## [$$NEW_VERSION] 条目"; exit 1; }; \
+	echo "Updating version to $$NEW_VERSION ..."; \
+	ruby -pi -e "sub(/VERSION = .*/, \"VERSION = '$$NEW_VERSION'\")" lib/pangram/version.rb; \
+	bundle install --quiet; \
+	git add lib/pangram/version.rb Gemfile.lock; \
+	git diff --cached --quiet || git commit -m "Release $$NEW_TAG"; \
+	git tag "$$NEW_TAG"; \
+	echo "Pushing $$NEW_TAG ..."; \
+	git push origin HEAD && git push origin "$$NEW_TAG"; \
+	echo "Done! Tagged and pushed $$NEW_TAG"

data/README.md

@@ -0,0 +1,228 @@
+# Pangram Ruby SDK
+
+Ruby client for the [Pangram Labs API](https://docs.pangram.com), with support
+for AI detection, asynchronous bulk jobs, file uploads, and plagiarism checks.
+
+## Requirements
+
+- Ruby 3.1 or newer
+- A Pangram API key
+
+## Installation
+
+Add the gem to your application:
+
+```ruby
+gem 'pangram'
+```
+
+Then run `bundle install`, or install it directly:
+
+```bash
+gem install pangram
+```
+
+## Client setup
+
+Set your API key in the environment:
+
+```bash
+export PANGRAM_API_KEY='your-api-key'
+```
+
+```ruby
+require 'pangram'
+
+client = Pangram.new
+```
+
+You can also pass the key directly. A constructor argument takes precedence
+over `PANGRAM_API_KEY`.
+
+```ruby
+client = Pangram.new(api_key: 'your-api-key')
+# Equivalent: Pangram::Client.new(api_key: 'your-api-key')
+```
+
+All API responses are ordinary Ruby `Hash` and `Array` values. Response keys
+remain strings and match Pangram's JSON schema.
+
+## Discover models
+
+Model access depends on the API key and current service availability. Discover
+selectors instead of hard-coding a model catalog:
+
+```ruby
+models = client.list_models
+# => ["default", "pangram-4"]
+```
+
+Pass `model: "default"` to track Pangram's default, or pass another selector
+returned by `list_models`. Omitting `model` is temporarily supported but emits
+a deprecation warning; Pangram plans to require it after September 30, 2026.
+
+## AI detection
+
+`predict` submits an asynchronous task, polls until it succeeds, and returns
+the completed result:
+
+```ruby
+result = client.predict(
+  'Text to analyze',
+  model: 'pangram-4',
+  timeout: 300,
+  poll_interval: 0.5
+)
+
+puts result['prediction_short']
+puts result['fraction_ai']
+
+result['windows'].each do |window|
+  puts "#{window['label']}: #{window['ai_assistance_score']}"
+end
+```
+
+Request a public dashboard link either directly or with the convenience
+method:
+
+```ruby
+result = client.predict(
+  'Text to analyze',
+  model: 'pangram-4',
+  public_dashboard_link: true
+)
+
+result = client.predict_with_dashboard_link(
+  'Text to analyze',
+  model: 'pangram-4'
+)
+```
+
+Polling intervals below 0.1 seconds are clamped to 0.1. `timeout` is a total
+deadline covering task submission and polling.
+
+## Bulk jobs
+
+Submit either a plain `text` list or an `items` list with optional customer
+IDs. Do not pass both.
+
+```ruby
+bulk = client.submit_bulk(
+  items: [
+    { id: 'row-001', text: 'First text' },
+    { id: 'row-002', text: 'Second text' }
+  ],
+  model: 'pangram-4'
+)
+
+bulk_id = bulk['bulk_id']
+status = client.wait_for_bulk(bulk_id, timeout: 3600, poll_interval: 1)
+results = client.get_bulk_results(bulk_id)
+
+results['items'].each do |item|
+  prediction = item['result']
+  puts "#{item['id']}: #{prediction['prediction_short']}" if prediction
+end
+
+results['failed_items'].each do |item|
+  warn "#{item['id']}: #{item['error']}"
+end
+```
+
+Use the lower-level methods to inspect a job without materializing all result
+pages:
+
+```ruby
+client.get_bulk_status(bulk_id)
+client.get_bulk_items(bulk_id, offset: 0, limit: 100)
+client.get_bulk_results_page(bulk_id, offset: 0, limit: 100)
+```
+
+`get_bulk_results` requests all pages and stores them in memory. For very large
+jobs, process `get_bulk_results_page` one page at a time. The API accepts at
+most 1,000 submitted item slots per results page.
+
+## File uploads
+
+File prediction uses Pangram's default model and does not accept `model`.
+
+```ruby
+result = client.predict_file(
+  'document.pdf',
+  public_dashboard_link: true,
+  timeout: 300
+)
+
+results = client.predict_files(
+  ['first.docx', 'second.pdf'],
+  public_dashboard_link: true
+)
+```
+
+The SDK sends one multipart field named `files` for each path and closes every
+opened file after the request, including when the request fails.
+
+## Plagiarism detection
+
+```ruby
+result = client.check_plagiarism('Text to check')
+
+puts result['plagiarism_detected']
+puts result['percent_plagiarized']
+```
+
+## Errors
+
+All SDK errors inherit from `Pangram::Error`:
+
+| Error | Meaning |
+| --- | --- |
+| `Pangram::AuthenticationError` | No API key was configured |
+| `Pangram::ValidationError` | A local argument is invalid |
+| `Pangram::APIError` | Pangram rejected the request or a task failed |
+| `Pangram::InvalidResponseError` | Pangram returned invalid JSON or an unexpected schema |
+| `Pangram::NetworkError` | The HTTP connection failed or a request timed out |
+| `Pangram::TimeoutError` | An async prediction or bulk job exceeded its total deadline |
+
+```ruby
+begin
+  client.predict('Text', model: 'default')
+rescue Pangram::TimeoutError => e
+  warn e.message
+rescue Pangram::Error => e
+  warn "Pangram request failed: #{e.message}"
+end
+```
+
+Transient network failures and responses with status 408, 429, 500, 502, 503,
+or 504 are retried until the total deadline while polling a prediction or bulk
+job and while paginating bulk results. Other API errors are raised immediately
+with the HTTP `status` and response `body` attached.
+
+## Deprecated compatibility methods
+
+The current Python SDK still includes these methods, so Ruby provides matching
+compatibility helpers:
+
+- `predict_short(text, model:)` forwards to the current prediction flow.
+- `batch_predict(texts, model:)` calls the prediction flow sequentially.
+
+Prefer `predict` for one input and `submit_bulk` for many inputs.
+
+## Development
+
+Extended documentation is available in [`docs/`](docs/README.md), including
+the [API reference](docs/API_REFERENCE.md), [development guide](docs/DEVELOPMENT.md),
+and [release checklist](docs/RELEASING.md).
+
+```bash
+mise install
+bundle install
+make verify
+```
+
+The test suite uses WebMock and never needs a live Pangram API key.
+
+## License
+
+[MIT](LICENSE)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec