duckling 0.4.7-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7f01e7c1806a99f56a2eb7a2624849e3a378b16a007927da8e98fecaa9075cb
+  data.tar.gz: 59882deda0bb0bd9abb16d75c6d39cf1b3293a5b595c71578722d5efcc85e42f
+SHA512:
+  metadata.gz: 1cd48c2532aa2f7ad1a34d91bcdacf1a4526946f1547ced4ca79cce2fff812f0794a8a10d37478a6ffd24ca22d313e0134ef79cde6020c0c693962a4bb1bbe35
+  data.tar.gz: b1926802b968fbee4bff4f896202aee26c0efbe7409e3b0ce4ff72043ea5ad020f2fdfa3eff8db9b1db568100fa0872a37860a185438a60463e965c4ff149ff6

data/Brewfile

@@ -0,0 +1,3 @@
+brew "rust"
+brew "gh"
+brew "hk"

data/CHANGELOG.md

@@ -0,0 +1,218 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.4.6] - 2026-08-13
+
+## What's Changed
+* Benchmark results (github-actions, 0.4.5) by @cpb in https://github.com/cpb/duckling/pull/148
+* Push only the source gem to GitHub Packages; release 0.4.6 by @cpb in https://github.com/cpb/duckling/pull/149
+
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.4.5...v0.4.6
+
+
+## [0.4.5] - 2026-08-13
+
+## What's Changed
+* Benchmark results (github-actions, 0.4.4) by @github-actions[bot] in https://github.com/cpb/duckling/pull/146
+* Fix release-time credential wiring; release 0.4.5 by @cpb in https://github.com/cpb/duckling/pull/147
+
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.4.4...v0.4.5
+
+
+## [0.4.4] - 2026-08-13
+
+## What's Changed
+* Benchmark results (github-actions, 0.4.3) by @github-actions[bot] in https://github.com/cpb/duckling/pull/138
+* Update CHANGELOG for v0.4.3 by @github-actions[bot] in https://github.com/cpb/duckling/pull/139
+* Benchmark results (github-actions, 0.4.3) by @cpb in https://github.com/cpb/duckling/pull/141
+* Default bin/worktree harness to Pi; add --pi/--claude/--gemini flags by @cpb in https://github.com/cpb/duckling/pull/142
+* Document Pi as the default bin/worktree harness by @cpb in https://github.com/cpb/duckling/pull/143
+* Skip the CI suite for docs-only PRs by @cpb in https://github.com/cpb/duckling/pull/144
+* Publish release gems to GitHub Packages as well as RubyGems; release 0.4.4 by @cpb in https://github.com/cpb/duckling/pull/145
+
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.4.3...v0.4.4
+
+
+## [0.4.3] - 2026-08-11
+
+## What's Changed
+* Update CHANGELOG for v0.4.2 by @github-actions[bot] in https://github.com/cpb/duckling/pull/134
+* Benchmark results (github-actions, 0.3.0-0.4.2) by @cpb in https://github.com/cpb/duckling/pull/135
+* Bump actions/download-artifact from 7.0.0 to 8.0.1 by @dependabot[bot] in https://github.com/cpb/duckling/pull/116
+* Open release-automation PRs with a PAT so CI runs on them by @cpb in https://github.com/cpb/duckling/pull/136
+* Require MFA for RubyGems operations; release 0.4.3 by @cpb in https://github.com/cpb/duckling/pull/137
+
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.4.2...v0.4.3
+
+
+## [0.4.2] - 2026-08-11
+
+## What's Changed
+* Publish releases via RubyGems Trusted Publishing instead of a long-lived API key by @cpb in https://github.com/cpb/duckling/pull/131
+* Bump Duckling::VERSION to 0.4.2 by @cpb in https://github.com/cpb/duckling/pull/132
+
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.4.1...v0.4.2
+
+
+## [0.4.1] - 2026-08-10
+
+### Fixed
+
+- The packaged gem no longer includes agent- and development-tooling files.
+  0.3.0 and 0.4.0 shipped `.claude/settings.json`, `AGENTS.md`, and
+  `CLAUDE.md`: the gemspec built its file list from `git ls-files` with a
+  reject-list of paths to exclude, so every newly tracked dotfile or tool
+  directory was packaged by default. The gemspec now allow-lists what ships
+  (`lib/`, `ext/`, `docs/` other than `docs/benchmarks/`, and a named set of
+  root files), so anything new stays out of the gem unless it is added
+  deliberately. Regression coverage checks the gemspec's file list in the
+  main suite and the built artifacts in `test/gem/packaged_gem_test.rb`.
+  None of the previously shipped files contained secrets — they are
+  development configuration and documentation, all public in the repository
+  — so the already-published 0.3.0/0.4.0 gems are unaffected in behavior and
+  have been left in place.
+
+## [0.4.0] - 2026-08-10
+
+### Changed
+
+- **On a stock Debian/Ubuntu host, roughly a hundred IANA zone identifiers
+  stop resolving.** `reference_zone: "US/Eastern"` — and every other
+  backward-compatibility name, such as `"US/Pacific"`, `"Europe/Kiev"`, or
+  `"Japan"` — now raises `ArgumentError` there. Those names live in the
+  `tzdata-legacy` system package, which is not installed by default. Two ways
+  to get them back, either of which restores the previous behavior exactly:
+
+  ```ruby
+  gem "tzinfo-data"   # in your Gemfile
+  ```
+  ```bash
+  apt install tzdata-legacy   # on the host
+  ```
+
+  Canonical identifiers (`"America/New_York"`, `"Europe/Kyiv"`) are
+  unaffected. A host with no zoneinfo files at all — a scratch or distroless
+  container — needs the gem for `reference_zone:` to work at all.
+
+  The error message names the tz database that answered, how many identifiers
+  it has, and both remedies, so this is distinguishable from a typo. The
+  datasource and the count describe whichever database answered on your host,
+  so both differ from the example below:
+
+  ```
+  invalid reference_zone: "US/Eastern" (resolved against system zoneinfo at
+  /usr/share/zoneinfo, which provides 497 identifiers; this database has no
+  backward-compat names (US/Eastern and ~100 others), so if that is what this
+  is, it needs either the tzinfo-data gem or the tzdata-legacy system package)
+  ```
+
+  The remedy is worded as a condition rather than a claim about the name you
+  passed: whether a given identifier is one of the ~100 in IANA's `backward`
+  file isn't knowable without shipping that list, and asserting it would tell
+  every typo on such a host that `tzdata-legacy` will supply it.
+
+  A second, quieter difference comes with the same change: some distributions
+  compile tzdata in *rearguard* format, which strips negative DST, and on such
+  a host `Europe/Dublin` is modelled as an ordinary positive-DST zone rather
+  than a negative-DST one. Which distributions is not guessable — Ubuntu 24.04
+  is rearguard, Debian trixie is vanguard — so if you depend on tzinfo's
+  `dst?` flag, read it from the host rather than assuming. Resolved offsets
+  are the same either way, so no `Duckling.parse` result changes because of
+  it.
+
+- `tzinfo-data` is no longer a runtime dependency. `tzinfo` already prefers
+  that gem when it is installed and falls back to the host's zoneinfo files
+  otherwise, so depending on it forced bundled tz data on every consumer to
+  serve the ones who want it. This is the change that produces the identifier
+  behavior above. Consumers who add `gem "tzinfo-data"` themselves get exactly
+  the previous behavior with no code change, and can still pick up a
+  tz-database revision by bumping that one gem. Dropping it means the bundled
+  tz data is no longer loaded at boot, so the first zone lookup does less
+  work; steady-state parsing is unaffected either way, since `reference_zone:`
+  resolution goes through the same tzinfo call once a database is loaded.
+
+### Added
+
+- `Duckling::TZDataUnavailable`, raised when `reference_zone:` is given on a
+  host with no tz database at all — no zoneinfo files and no `tzinfo-data`
+  gem, as in a scratch or distroless container. Newly reachable because of the
+  dependency change above; previously a database always existed. It names both
+  fixes, where the underlying tzinfo error mentioned neither this gem nor
+  `reference_zone:`. Deliberately not an `ArgumentError`: it reports the
+  deployment's state, not a bad argument, so code rescuing `ArgumentError`
+  around caller-supplied zone names does not swallow it. Every other keyword
+  works without a tz database.
+
+## [0.3.0] - 2026-08-04
+
+### Changed
+
+- **Breaking:** `reference_time:` now requires a Ruby `Time` object (or
+  `nil`), not a Unix-seconds Integer. This lets the caller's `utc_offset` be
+  preserved into offset-aware `Instant` results (e.g. `"in one hour"`),
+  which previously always came back as UTC+0 regardless of the intended
+  anchor. Accepted values: a `Time`, or anything responding to `to_time`
+  (`ActiveSupport::TimeWithZone`, stdlib `DateTime`, etc.), which is coerced
+  automatically. Migrate a raw Integer by wrapping it in `Time.at(seconds)`.
+- **Breaking:** a time result's `:value` (and an interval's `:from`/`:to`) is
+  now a real Ruby `Time`, not a formatted String. This applies to both
+  `Naive` (wall-clock, e.g. `"tomorrow"`, `"5pm"`) and `Instant` (e.g. `"in
+  one hour"`) results — `reference_time:`'s offset is now applied to
+  `Naive` results too, not just `Instant` ones. Callers parsing the old
+  ISO-ish string (with or without an offset suffix) should read `.value`
+  directly as a `Time` instead.
+- **Breaking:** `:time`'s `:value` now uses the same unified,
+  externally-tagged shape as every other dimension: a single result is
+  `{Time: {Single: {value: {Naive:|Instant: {value:, grain:}}, values: [...],
+  holidayBeta: "..."}}}`, and an interval result is `{Time: {Interval: {from:
+  {Naive:|Instant: {...}}, to: {...}, values: [...]}}}`. Previously `:time`
+  kept its own bespoke flattened shape (`{type:, value:, grain:, values:}` /
+  `{type:, from:, to:}`) even after every other dimension moved onto the
+  tagged convention. `:value` is still always a real Ruby `Time`, never a
+  String, and `grain` is still the lowercase-snake_case symbol convention
+  (`:second`, `:no_grain`, ...) — only the wrapping shape changed. Migrate by
+  reaching through the new tags, e.g.
+  `entity[:value][:Time][:Single][:value][:Naive][:value]` in place of the
+  old `entity[:value][:value]`. One behavior change bundled with the shape
+  migration: an unbounded interval (e.g. `"after 3pm"`) now carries an
+  explicit `to: nil` (or `from: nil`) key instead of omitting the key
+  entirely — check `interval[:to].nil?` rather than `interval.key?(:to)`
+  to detect an unbounded endpoint.
+
+## [0.2.0] - 2026-07-01
+
+## What's Changed
+* Ship duckling gem: time extraction via Magnus + wafer-inc-duckling by @cpb in https://github.com/cpb/duckling/pull/2
+
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.1.2...v0.2.0
+
+
+## [0.1.2] - 2026-07-01
+
+## What's Changed
+* Retry release pipeline as 0.1.2 by @cpb in https://github.com/cpb/duckling/pull/7
+
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.1.1...v0.1.2
+
+
+## [0.1.1] - 2026-07-01
+
+## What's Changed
+* Automate gem release: tag-triggered publish to RubyGems by @cpb in https://github.com/cpb/duckling/pull/5
+
+## New Contributors
+* @cpb made their first contribution in https://github.com/cpb/duckling/pull/5
+
+**Full Changelog**: https://github.com/cpb/duckling/compare/v0.1.0...v0.1.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"duckling" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["me@cpb.ca"](mailto:"me@cpb.ca").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Caleb Buxton
+
+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/NOTICES

@@ -0,0 +1,52 @@
+Third-Party Notices
+===================
+
+The duckling gem's native extension (the compiled .bundle/.so — shipped
+precompiled in the platform gems, built at install time from the source
+gem) statically links the third-party component listed below. The gem
+itself remains MIT-licensed (see LICENSE.txt); this file exists because
+the component's BSD-3-Clause license requires binary redistributions to
+reproduce its copyright notice, conditions, and disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+Component: duckling (Rust crate)
+Upstream:  https://github.com/wafer-inc/duckling
+License:   BSD-3-Clause
+Version:   as locked in this repository's Cargo.lock
+
+The license text below is reproduced verbatim from the component's
+LICENSE file.
+
+---------------------------------------------------------------------------
+
+BSD License
+
+For Duckling software
+
+Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+Rust port copyright (c) 2024-present, contributors.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook nor the names of its contributors may be used to
+   endorse or promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,253 @@
+# Duckling
+
+Ruby FFI adapter to a Rust [Duckling](https://github.com/wafer-inc/duckling) NER engine — no HTTP service required.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add duckling
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install duckling
+```
+
+## Usage
+
+```ruby
+require "duckling"
+
+Duckling.parse("tomorrow", locale: "en")
+# =>
+# [{ body: "tomorrow", start: 0, end: 8, dim: :time,
+#    value: { Time: { Single: { value: { Naive: { value: 2026-07-02 00:00:00 +0000, grain: :day } },
+#                                values: [...] } } } }]
+# (the date resolves relative to now; pass reference_time: for a fixed anchor)
+```
+
+`Duckling.parse` takes required text plus keyword options, and returns an
+`Array` of entity `Hash`es (empty if nothing matched):
+
+```ruby
+Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false, reference_zone: nil)
+```
+
+### Keyword arguments
+
+- `locale:` (String, default `"en"`) — a `lang[-region]` tag, e.g. `"en"` or
+  `"en-GB"`. An unrecognized language or region raises `ArgumentError`.
+- `dims:` (Array of String, default `["time"]`) — which dimensions to
+  extract. See "Supported dimensions" below. An unrecognized dimension name
+  raises `ArgumentError`.
+- `reference_time:` (`Time`, default `nil`) — anchors relative expressions
+  like "tomorrow" or "next week". Its `utc_offset` is preserved into every
+  time result's `:value` — both wall-clock expressions ("tomorrow", "next
+  week") and offset-aware ones ("in one hour"), not flattened to UTC.
+  Defaults to the current UTC time; pass an explicit `Time` for deterministic
+  output. Anything else responding to `to_time` —
+  `ActiveSupport::TimeWithZone` (`Time.current`/`Time.zone.now`), stdlib
+  `DateTime`, etc. — is coerced to a `Time` automatically. A value that's
+  neither a `Time` nor `to_time`-able (e.g. a raw Integer Unix timestamp)
+  raises `TypeError`; wrap it in `Time.at(seconds)` first.
+- `with_latent:` (Boolean, default `false`) — include ambiguous/latent
+  matches (e.g. a bare "morning") in the results.
+- `reference_zone:` (String, default `nil`) — an IANA zone name, e.g.
+  `"America/New_York"`. Resolves each wall-clock result's UTC offset against
+  that zone on the result's *own* date, so a result before a DST transition
+  and one after it get different offsets instead of sharing
+  `reference_time:`'s single fixed one. An unknown identifier raises
+  `ArgumentError`; so does a `reference_time:` whose `utc_offset` disagrees
+  with the zone at that instant. It does not anchor the parse — see "Time
+  zone data" below.
+
+There is no `Duckling::Error` class — invalid `locale:`/`dims:` values raise
+plain `ArgumentError`, as do an unknown `reference_zone:` and a
+`reference_time:` whose offset disagrees with it. The one named error a caller
+is likely to meet is `Duckling::TZDataUnavailable`, for a host with no tz
+database at all — see "Time zone data" below.
+
+### Time zone data
+
+`reference_zone:` resolves against [tzinfo][], which uses the `tzinfo-data`
+gem when it is installed and the host's own zoneinfo files otherwise. This gem
+does not depend on `tzinfo-data`, so by default you get the host's database.
+
+That is usually what you want, and it is the faster of the two to start up.
+Two cases where it is not:
+
+- **Backward-compatibility names.** Debian and Ubuntu ship names like
+  `"US/Eastern"` in a separate `tzdata-legacy` package that is not installed
+  by default, so roughly a hundred valid IANA identifiers raise
+  `ArgumentError` on a stock host. Either `gem "tzinfo-data"` or
+  `apt install tzdata-legacy` restores them. The error message names whichever
+  database answered and how many identifiers it has, so you can tell this
+  apart from a typo.
+- **No zoneinfo files at all**, as in a scratch or distroless container.
+  `reference_zone:` raises `Duckling::TZDataUnavailable` there, naming both
+  fixes. Add `gem "tzinfo-data"` to bundle the data with your app, where you
+  can also patch its vintage by bumping one gem, or install the system
+  `tzdata` package. Every other keyword works without a tz database.
+
+`reference_zone:` reinterprets result offsets; it does not anchor the parse.
+Given without `reference_time:`, a relative expression like `"tomorrow"` still
+anchors on the machine-local clock rather than on "now" in that zone — pass a
+`reference_time:` in the zone to anchor as well.
+
+[tzinfo]: https://github.com/tzinfo/tzinfo
+
+### Return value
+
+Each entity in the returned array is a `Hash` with:
+
+- `:body` (String) — the matched substring.
+- `:start` / `:end` (Integer) — character offsets into the input text.
+- `:dim` (Symbol) — the dimension, e.g. `:time`.
+- `:latent` (Boolean) — present only when the match is latent.
+- `:value` — every entity carries one; its shape depends on `:dim`.
+
+  Every dimension's `:value` is serde's externally-tagged representation of
+  the underlying Rust value, with all Hash keys symbolized — a one-pair
+  `Hash` keyed by a PascalCase tag matching the dimension (`{Numeral: 42.0}`,
+  `{Email: "user@example.com"}`, `{Url: {value: "...", domain: "..."}}`,
+  `{Temperature: {Value: {value: 37.0, unit: "celsius"}}}`). See
+  `test/duckling_parse_dimensions_test.rb` for the exact shape of every
+  dimension.
+
+  `:time` is the one dimension with additional nested tagging, since its
+  underlying leaf datetimes aren't serde-serializable as Ruby `Time`
+  objects and need patching after the fact (see `ext/duckling/src/lib.rs`'s
+  `patch_time_value`/`patch_time_point`):
+
+  ```ruby
+  # a single point in time, e.g. "tomorrow"
+  { Time: { Single: { value: { Naive: { value: 2026-07-02 00:00:00 +0000, grain: :day } },
+                       values: [...] } } }
+
+  # an interval, e.g. "from 3pm to 5pm"
+  { Time: { Interval: {
+      from: { Naive: { value: 2013-02-12 15:00:00 -0200, grain: :hour } },
+      to:   { Naive: { value: 2013-02-12 18:00:00 -0200, grain: :hour } },
+      values: [...] } } }
+  ```
+
+  Every `TimePoint` (the primary `value:`, each `values:` recurrence entry,
+  and an interval's `from:`/`to:`) is tagged `Naive` (wall-clock, no
+  timezone assumption — e.g. "tomorrow", "5pm") or `Instant` (offset-aware —
+  e.g. "in one hour", "now"). `grain` is one of `second`, `minute`, `hour`,
+  `day`, `week`, `month`, `quarter`, `year`. The nested `value:` is always a
+  real Ruby `Time`, not a formatted string — its `utc_offset` matches
+  `reference_time:`'s (or UTC, if `reference_time:` was omitted). A holiday
+  match (e.g. "christmas") additionally carries `holidayBeta:` (a String)
+  alongside `Single`'s `value:`/`values:`.
+
+  **Gotcha:** an interval's `:to` is the *exclusive* boundary, not the
+  literal named time — `"from 3pm to 5pm"` resolves `:to` to `18:00`, not
+  `17:00`. This matches upstream [duckling](https://github.com/wafer-inc/duckling)
+  behavior.
+
+  **Gotcha:** an unbounded interval (e.g. `"after 3pm"`, `"until 5pm"`)
+  still carries both `:from` and `:to` keys — the missing bound is an
+  explicit `nil` value, not an absent key. Check `interval[:to].nil?`
+  (not `interval.key?(:to)`) to detect an unbounded endpoint.
+
+### Supported dimensions
+
+`dims:` accepts `time`, `number`, `ordinal`, `temperature`, `distance`,
+`volume`, `quantity`, `amount-of-money`, `email`, `phone-number`, `url`,
+`credit-card-number`, `time-grain`, and `duration` — every entity comes back
+with a populated `:value` (see "Return value" above for the shape). An
+unrecognized dimension name raises `ArgumentError`.
+
+### Known limitation: bare comma-separated lists
+
+A run of date/time expressions joined by bare commas, with nothing else
+between them, collapses into a single entity — every date after the first
+in that run is silently dropped:
+
+```ruby
+Duckling.parse("birthdays are march 3, march 9, april 12 and may 5", locale: "en")
+  .select { |r| r[:dim] == :time }
+  .map { |r| r[:value][:value] }
+# => [2013-03-03 00:00:00 +0000, 2013-05-05 00:00:00 +0000]
+# (march 9 and april 12 are silently dropped)
+```
+
+This is an upstream grammar/ranking behavior in the wrapped
+[duckling](https://github.com/wafer-inc/duckling) engine, not something this
+gem can work around. Joining
+dates with "and", periods, or a name/label immediately before each date
+avoids the collapse:
+
+```ruby
+Duckling.parse("march 3 and march 9 and april 12 and may 5", locale: "en")
+  .select { |r| r[:dim] == :time }
+  .map { |r| r[:value][:value] }
+# => [2013-03-03 00:00:00 +0000, 2013-03-09 00:00:00 +0000, 2013-04-12 00:00:00 +0000, 2013-05-05 00:00:00 +0000]
+```
+
+See `test/duckling_comma_list_test.rb` for the full characterization,
+including cases where the surviving value isn't even reliably the leftmost
+date in the collapsed run.
+
+## Performance
+
+Benchmarked with [benchmark-ips](https://github.com/evanphx/benchmark-ips)
+against `Duckling.parse`, including Magnus/Ruby conversion overhead (not
+just the underlying Rust engine), plus GC pressure and threaded-worker-pool
+throughput. See [`docs/benchmarks/`](docs/benchmarks/) for the latest
+numbers, broken out by environment (GitHub Actions CI, Claude Code Web,
+local dev) — results vary enough by machine that comparing across
+environments is more meaningful than a single blended trend.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Building
+the native Rust extension requires a Rust toolchain; on macOS with Homebrew
+installed, `bin/setup` installs it automatically via `brew bundle` and the
+project's `Brewfile` (no-op if Homebrew isn't present). Then run
+`rake compile` to build the extension before running `rake test`, or just run
+`rake` (or `bundle exec rake`) with no arguments to lint, compile, and test in
+order. You can also run `bin/console` for an interactive prompt that will
+allow you to experiment.
+
+`bin/setup` also seeds a `.env.local` file (from `.env.local.example`) with
+`RB_SYS_CARGO_PROFILE=dev`, so local `rake compile` runs build the extension
+in Cargo's dev profile by default — slower at runtime, but much faster to
+compile while iterating. `.env.local` is gitignored and untouched by CI, so
+CI and `rake release` still build the optimized release profile. Delete or
+edit `.env.local` to opt back into a release-profile local build, or run
+`bundle exec rake dev compile test` for a one-off dev-profile build without
+`.env.local` in place.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version: bump `Duckling::VERSION` in `version.rb`, merge that change to `main`, then run `bundle exec rake release` (or push a matching `vX.Y.Z` tag directly) to create and push the git tag. Pushing the tag triggers a GitHub Actions pipeline that re-runs CI as a gate, cross-compiles `x86_64-linux`/`aarch64-linux`/`x86_64-darwin`/`arm64-darwin` binary gems, verifies the tag matches `Duckling::VERSION`, builds and publishes the gems (source + one binary gem per platform) to [rubygems.org](https://rubygems.org) plus the source gem to the [GitHub Packages RubyGems registry](https://rubygems.pkg.github.com/cpb) (which keys uniqueness on name+version and so cannot hold the platform gems), cuts a GitHub release, and opens a PR appending an entry to `CHANGELOG.md`.
+
+`bin/benchmark` (or `bundle exec rake benchmark`) runs the `benchmark-ips`
+suite locally and prints results to the console — no files written.
+`bin/benchmark record` (or `rake benchmark:record`) additionally writes
+`docs/benchmarks/<environment>/<version>.json` and regenerates
+`docs/benchmarks/README.md`. `bin/benchmark record-pr` (or `rake
+benchmark:record_pr`) does the same against a fresh branch off `origin/main`
+and opens (and auto-merges) a PR via `gh` — this is what the release
+pipeline runs automatically, and what you'd also run from a Claude Code Web
+session or a local dev machine to contribute that environment's numbers
+ahead of a release. `gh` needs to be installed (`bin/setup` does this via
+the `Brewfile` on macOS) and authenticated (`gh auth login`) for the
+`record-pr` variant.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/cpb/duckling. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/cpb/duckling/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+The native extension statically links the [duckling](https://github.com/wafer-inc/duckling) Rust crate (a Rust port of Facebook's Duckling), which is licensed under the BSD 3-Clause License. Its copyright notice and disclaimer are reproduced in [NOTICES](NOTICES), as that license requires of binary redistributions.
+
+## Code of Conduct
+
+Everyone interacting in the Duckling project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/cpb/duckling/blob/master/CODE_OF_CONDUCT.md).