pangram 0.1.0

data/docs/API_REFERENCE.md

@@ -0,0 +1,254 @@
+# API Reference
+
+The public API is exposed through `Pangram::Client`. `Pangram.new` is a
+convenience constructor for the same client.
+
+```ruby
+require 'pangram'
+
+client = Pangram.new(api_key: ENV.fetch('PANGRAM_API_KEY'))
+# Equivalent to Pangram::Client.new(...)
+```
+
+All successful API responses remain ordinary Ruby `Hash` and `Array` values.
+Hash keys are strings and match Pangram's JSON response fields.
+
+## Authentication
+
+```ruby
+Pangram.new(api_key: 'your-api-key')
+```
+
+When `api_key:` is omitted, the client reads `PANGRAM_API_KEY`. An explicit
+argument takes precedence over the environment. If neither is available,
+construction raises `Pangram::AuthenticationError`.
+
+Every request sends the key through the `x-api-key` header.
+
+## Model discovery
+
+### `list_models`
+
+```ruby
+models = client.list_models
+# => ["default", "pangram-4"]
+```
+
+Returns the server-ordered selectors available to the current API key. The
+catalog is entitlement- and availability-aware, so callers should not
+hard-code it.
+
+The client validates that the response contains unique, non-blank model names
+and the `default` selector.
+
+## Text prediction
+
+### `predict`
+
+```ruby
+result = client.predict(
+  text,
+  model: 'pangram-4',
+  public_dashboard_link: false,
+  timeout: 300,
+  poll_interval: 0.5
+)
+```
+
+Submits `POST /task`, polls `GET /task/{task_id}`, and returns when the task
+reaches `STAGE_SUCCESS`.
+
+| Keyword | Default | Description |
+| --- | --- | --- |
+| `model` | `nil` | Selector returned by `list_models` |
+| `public_dashboard_link` | `false` | Request a public result link |
+| `timeout` | `300` | Total deadline for submission and polling, in seconds |
+| `poll_interval` | `0.5` | Delay between polls, clamped to at least 0.1 seconds |
+
+Omitting `model` currently preserves Pangram's legacy wire payload and emits a
+deprecation warning. New integrations should pass `model: "default"` or
+another selector returned by `list_models`.
+
+A successful result can include:
+
+- `stage`, `text`, `version`, `headline`, `prediction`, and `prediction_short`
+- `fraction_ai`, `fraction_ai_assisted`, and `fraction_human`
+- segment counters and `dashboard_link` when requested
+- `windows`, including labels, scores, confidence, character offsets, word and
+  token counts, and Pangram 4 humanizer fields
+
+The SDK returns the server payload without renaming or symbolizing fields.
+
+### `predict_with_dashboard_link`
+
+```ruby
+result = client.predict_with_dashboard_link(
+  text,
+  model: 'pangram-4',
+  timeout: 300,
+  poll_interval: 0.5
+)
+```
+
+Equivalent to `predict(..., public_dashboard_link: true)`.
+
+## Bulk jobs
+
+### `submit_bulk`
+
+Submit exactly one payload shape:
+
+```ruby
+client.submit_bulk(text: ['first', 'second'], model: 'pangram-4')
+
+client.submit_bulk(
+  items: [
+    { id: 'row-1', text: 'first' },
+    { id: 'row-2', text: 'second' }
+  ],
+  model: 'pangram-4'
+)
+```
+
+Returns the accepted `202` response, including `bulk_id`, initial status,
+accepted items, and immediate validation failures.
+
+One model applies to the whole bulk job. Per-item model selectors are not
+supported.
+
+### `get_bulk_status`
+
+```ruby
+status = client.get_bulk_status(bulk_id)
+```
+
+Returns job status, counters, and creation/completion timestamps. Terminal
+statuses are `succeeded`, `failed`, and `partial`.
+
+### `wait_for_bulk`
+
+```ruby
+status = client.wait_for_bulk(
+  bulk_id,
+  timeout: 3600,
+  poll_interval: 0.5
+)
+```
+
+Polls until the job reaches a terminal status. Transient network failures are
+retried within the total deadline.
+
+### `get_bulk_items`
+
+```ruby
+page = client.get_bulk_items(bulk_id, offset: 0, limit: 100)
+```
+
+Returns one page of item metadata.
+
+### `get_bulk_results_page`
+
+```ruby
+page = client.get_bulk_results_page(bulk_id, offset: 0, limit: 100)
+```
+
+Returns one submitted-item page with successful or in-progress items in
+`items` and failures in `failed_items`.
+
+### `get_bulk_results`
+
+```ruby
+results = client.get_bulk_results(bulk_id, page_size: 1000, timeout: 3600)
+```
+
+Fetches every results page and returns a single aggregate containing
+`bulk_id`, `total_items`, `items`, and `failed_items`. `page_size` must be from
+1 through 1,000. `timeout` is the total deadline in seconds for fetching all
+pages; transient failures are retried until that deadline. The aggregate's
+`total_items` is locked to the first page so in-progress jobs cannot truncate
+the result mid-pagination.
+
+This method materializes all pages in memory. Process
+`get_bulk_results_page` incrementally for very large jobs.
+
+## File prediction
+
+File prediction uses Pangram's default model and does not accept `model:`.
+
+### `predict_file`
+
+```ruby
+result = client.predict_file(
+  'document.pdf',
+  public_dashboard_link: true,
+  timeout: 300
+)
+```
+
+Uploads one file and returns its result.
+
+### `predict_files`
+
+```ruby
+results = client.predict_files(
+  ['first.docx', 'second.pdf'],
+  public_dashboard_link: true,
+  timeout: 300
+)
+```
+
+Uploads multiple files in one multipart request. Each path is sent as a
+repeated form field named `files`, not `files[]`. Every file handle is closed
+after success or failure, including partial file-open failures.
+
+## Plagiarism detection
+
+### `check_plagiarism`
+
+```ruby
+result = client.check_plagiarism('Text to check')
+```
+
+Returns Pangram's plagiarism response, including detection status, matched
+content, sentence counts, and plagiarism percentage.
+
+## Deprecated compatibility methods
+
+The following methods mirror compatibility behavior still present in the
+Python SDK:
+
+- `predict_short(text, model:)` uses the current prediction flow.
+- `batch_predict(texts, model:)` predicts each input sequentially.
+
+Use `predict` for one input and `submit_bulk` for many inputs.
+
+## Errors
+
+All SDK-defined exceptions inherit from `Pangram::Error`.
+
+| Exception | Raised when |
+| --- | --- |
+| `Pangram::AuthenticationError` | No API key is configured |
+| `Pangram::ValidationError` | A local argument is invalid |
+| `Pangram::APIError` | Pangram rejects a request or an async task fails |
+| `Pangram::InvalidResponseError` | A response is not valid JSON or has an invalid top-level contract |
+| `Pangram::NetworkError` | An HTTP request fails at the transport layer |
+| `Pangram::TimeoutError` | Prediction or bulk polling exceeds its total deadline |
+
+```ruby
+begin
+  client.predict(text, model: 'default')
+rescue Pangram::TimeoutError => e
+  warn e.message
+rescue Pangram::Error => e
+  warn "Pangram failed: #{e.message}"
+end
+```
+
+API errors carry the HTTP `status` and raw response `body` when they come from
+a rejected response. `Pangram::InvalidResponseError` is a subclass of
+`Pangram::APIError`, so rescuing `APIError` also catches schema violations.
+
+Transport errors and responses with status 408, 429, 500, 502, 503, or 504 are
+retried until the total deadline during prediction polling, bulk polling, and
+bulk results pagination. Other API errors are not retried.

data/docs/DEVELOPMENT.md

@@ -0,0 +1,113 @@
+# Development Guide
+
+## Repository layout
+
+```text
+lib/pangram.rb             Public entry point and Pangram.new
+lib/pangram/client.rb      API client, polling, pagination, and uploads
+lib/pangram/errors.rb      SDK exception hierarchy
+lib/pangram/version.rb     Gem version
+spec/                      Offline contract tests
+docs/                      Extended project documentation
+pangram.gemspec            Package metadata and dependencies
+```
+
+## Setup
+
+Ruby is managed through [mise](https://mise.jdx.dev/):
+
+```bash
+mise trust
+mise install
+bundle install
+```
+
+The gem requires Ruby 3.1 or newer. The lockfile is constrained so all
+development dependencies also remain compatible with Ruby 3.1.
+
+## Make targets
+
+Run `make help` to list available commands.
+
+| Command | Purpose |
+| --- | --- |
+| `make install` | Install Bundler dependencies |
+| `make test` or `make spec` | Run all RSpec tests |
+| `make coverage` | Run tests and print the coverage report path |
+| `make lint` | Run RuboCop |
+| `make lint-fix` | Run RuboCop auto-correction |
+| `make docs` | Generate YARD documentation under `doc/` |
+| `make build` | Build `pkg/pangram-VERSION.gem` |
+| `make verify` | Run tests, lint, docs, and build |
+| `make console` | Start IRB with `pangram` loaded |
+| `make clean` | Remove generated artifacts |
+
+## Testing
+
+```bash
+make test
+```
+
+The test suite uses WebMock and must not contact Pangram's live services. It
+verifies:
+
+- request URLs, headers, JSON payloads, and status codes
+- model catalog validation
+- prediction and bulk polling, retry, failure, and timeout paths
+- bulk result pagination and aggregation
+- exact multipart field names and file-handle cleanup
+- API, network, validation, and invalid-response errors
+
+SimpleCov writes its report to `coverage/index.html` and enforces at least 90%
+line coverage.
+
+## Linting
+
+```bash
+make lint
+```
+
+RuboCop targets Ruby 3.1. Prefer correcting the implementation over disabling
+a cop for a local exception.
+
+## API documentation
+
+Public methods use YARD-compatible comments. Generate HTML documentation with:
+
+```bash
+make docs
+```
+
+Generated files are written to `doc/` and are excluded from source control.
+
+## Building and inspecting the gem
+
+```bash
+make build
+gem specification pkg/pangram-0.1.0.gem
+gem contents --show-install-dir pangram
+```
+
+For an isolated installation smoke test:
+
+```bash
+tmp_dir="$(mktemp -d)"
+GEM_HOME="$tmp_dir" GEM_PATH="$tmp_dir" \
+  gem install pkg/pangram-0.1.0.gem --no-document
+GEM_HOME="$tmp_dir" GEM_PATH="$tmp_dir" \
+  ruby -e 'require "pangram"; puts Pangram::VERSION'
+rm -rf "$tmp_dir"
+```
+
+Use the current value from `lib/pangram/version.rb` instead of `0.1.0` when
+building a later release.
+
+## Adding or changing an API method
+
+1. Confirm the current REST contract in the official Pangram documentation.
+2. Keep HTTP ownership in `Pangram::Client` and reuse existing request helpers.
+3. Preserve response field names and string keys.
+4. Add WebMock coverage for the request and relevant failure paths.
+5. Update `docs/API_REFERENCE.md`, the project README when user-facing, and
+   `CHANGELOG.md`.
+6. Run `make verify`.

data/docs/README.md

@@ -0,0 +1,25 @@
+# Pangram Ruby SDK Documentation
+
+This directory contains the extended documentation for the `pangram` gem.
+
+## Documentation index
+
+- [API reference](API_REFERENCE.md) — client construction, method signatures,
+  response contracts, polling behavior, and errors.
+- [Development guide](DEVELOPMENT.md) — repository layout, local setup,
+  testing, linting, documentation generation, and gem builds.
+- [Release guide](RELEASING.md) — versioning, verification, package inspection,
+  and the manual RubyGems publishing checklist.
+
+## Quick links
+
+- [Project README](../README.md)
+- [Changelog](../CHANGELOG.md)
+- [Client implementation](../lib/pangram/client.rb)
+- [Contract tests](../spec/pangram/client_spec.rb)
+- [Official Pangram API documentation](https://docs.pangram.com/api-reference/introduction)
+
+## Supported Ruby versions
+
+The gem requires Ruby 3.1 or newer. CI covers Ruby 3.1, 3.2, 3.3, 3.4,
+and 4.0.

data/docs/RELEASING.md

@@ -0,0 +1,72 @@
+# Release Guide
+
+Publishing a gem is a shared, irreversible action. Complete the checks below,
+review the built package, and publish only with explicit maintainer approval.
+
+## 1. Update release metadata
+
+1. Change `Pangram::VERSION` in `lib/pangram/version.rb`.
+2. Move the relevant entries in `CHANGELOG.md` from `Unreleased` into a dated
+   version section.
+3. Confirm README and API reference examples still match the implementation.
+
+The version must follow semantic versioning and must not already exist on
+RubyGems.
+
+## 2. Verify the source
+
+```bash
+make verify
+```
+
+This runs the complete test suite, RuboCop, YARD generation, and gem build.
+Do not publish if any command fails.
+
+CI also tests the supported Ruby matrix from 3.1 through 4.0.
+
+## 3. Inspect the package
+
+```bash
+gem specification pkg/pangram-VERSION.gem
+gem unpack pkg/pangram-VERSION.gem --target /tmp/pangram-gem-review
+```
+
+Confirm that:
+
+- the name is `pangram` and the version is correct
+- `lib/`, README, license, changelog, and docs are present
+- test artifacts, coverage output, and credentials are absent
+- runtime dependencies and Ruby requirements are correct
+
+## 4. Test an isolated install
+
+```bash
+tmp_dir="$(mktemp -d)"
+GEM_HOME="$tmp_dir" GEM_PATH="$tmp_dir" \
+  gem install pkg/pangram-VERSION.gem --no-document
+GEM_HOME="$tmp_dir" GEM_PATH="$tmp_dir" \
+  ruby -e 'require "pangram"; puts Pangram::VERSION'
+rm -rf "$tmp_dir"
+```
+
+## 5. Commit and tag
+
+After review, commit the version and changelog changes. Create an annotated tag
+using the same version:
+
+```bash
+git tag -a vVERSION -m "Release vVERSION"
+```
+
+Pushing commits or tags requires explicit approval.
+
+## 6. Publish manually
+
+With maintainer approval and valid RubyGems credentials:
+
+```bash
+gem push pkg/pangram-VERSION.gem
+```
+
+After publishing, install `pangram` from RubyGems in a clean environment and
+verify its version and `require "pangram"` entry point.