duckling: A Haskell library for parsing text into structured data.

[ bsd3, library, program, systems ] [ Propose Tags ]

Duckling is a library for parsing text into structured data.

[Skip to Readme]


[Index] [Quick Jump]


Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Versions [RSS],,,,,,,,
Change log
Dependencies aeson (>= && <1.6), array (>= && <0.6), attoparsec (>= && <0.15), base (>=4.8.2 && <5.0), bytestring (>= && <0.12), containers (>= && <0.7), deepseq (>= && <1.5), dependent-sum (>= && <0.8), directory (>= && <1.4), duckling, extra (>=1.4.10 && <1.8), filepath (>= && <1.5), hashable (>= && <1.4), haskell-src-exts (>=1.18 && <1.30), regex-base (>=0.93.2 && <0.95), regex-pcre (>=0.94.4 && <0.96), regex-pcre-builtin (>=0.94.4 && <0.96), snap-core (>= && <1.1), snap-server (>= && <1.2), text (>= && <1.3), text-show (>=2.1.2 && <3.10), time (>= && <2), timezone-olson (>=0.1.7 && <0.3), timezone-series (>= && <0.2), unordered-containers (>= && <0.3) [details]
License BSD-3-Clause
Copyright Copyright (c) 2014-present, Facebook, Inc.
Author Facebook, Inc.
Revised Revision 1 made by chessai at 2021-04-17T00:03:48Z
Category Systems
Home page
Bug tracker
Source repo head: git clone
Uploaded by chessai at 2021-04-15T22:53:17Z
Executables duckling-expensive, duckling-request-sample, custom-dimension-example, duckling-example-exe, duckling-regen-exe
Downloads 5572 total (35 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2021-04-15 [all 1 reports]

Readme for duckling-

[back to package description]

Duckling Logo

Duckling Build Status

Duckling is a Haskell library that parses text into structured data.

"the first Tuesday of October"
=> {"value":"2017-10-03T00:00:00.000-07:00","grain":"day"}


A Haskell environment is required. We recommend using stack.

On macOS you'll need to install PCRE development headers. The easiest way to do that is with Homebrew:

brew install pcre

If that doesn't help, try running brew doctor and fix the issues it finds.


To compile and run the binary:

$ stack build
$ stack exec duckling-example-exe

The first time you run it, it will download all required packages.

This runs a basic HTTP server. Example request:

$ curl -XPOST --data 'locale=en_GB&text=tomorrow at eight'

In the example application, all dimensions are enabled by default. Provide the parameter dims to specify which ones you want. Examples:

Identify credit card numbers only:
$ curl -XPOST --data 'locale=en_US&text="4111-1111-1111-1111"&dims="[\"credit-card-number\"]"'
If you want multiple dimensions, comma-separate them in the array:
$ curl -XPOST --data 'locale=en_US&text="3 cups of sugar"&dims="[\"quantity\",\"numeral\"]"'

See exe/ExampleMain.hs for an example on how to integrate Duckling in your project. If your backend doesn't run Haskell or if you don't want to spin your own Duckling server, you can directly use's built-in entities.

Supported dimensions

Duckling supports many languages, but most don't support all dimensions yet (we need your help!). Please look into this directory for language-specific support.

Dimension Example input Example value output
AmountOfMoney "42€" {"value":42,"type":"value","unit":"EUR"}
CreditCardNumber "4111-1111-1111-1111" {"value":"4111111111111111","issuer":"visa"}
Distance "6 miles" {"value":6,"type":"value","unit":"mile"}
Duration "3 mins" {"value":3,"minute":3,"unit":"minute","normalized":{"value":180,"unit":"second"}}
Email "" {"value":""}
Numeral "eighty eight" {"value":88,"type":"value"}
Ordinal "33rd" {"value":33,"type":"value"}
PhoneNumber "+1 (650) 123-4567" {"value":"(+1) 6501234567"}
Quantity "3 cups of sugar" {"value":3,"type":"value","product":"sugar","unit":"cup"}
Temperature "80F" {"value":80,"type":"value","unit":"fahrenheit"}
Time "today at 9am" {"values":[{"value":"2016-12-14T09:00:00.000-08:00","grain":"hour","type":"value"}],"value":"2016-12-14T09:00:00.000-08:00","grain":"hour","type":"value"}
Url "" {"value":"","domain":""}
Volume "4 gallons" {"value":4,"type":"value","unit":"gallon"}

Custom dimensions are also supported.

Extending Duckling

To regenerate the classifiers and run the test suite:

$ stack build :duckling-regen-exe && stack exec duckling-regen-exe && stack test

It's important to regenerate the classifiers after updating the code and before running the test suite.

To extend Duckling's support for a dimension in a given language, typically 4 files need to be updated:

  • Duckling/<Dimension>/<Lang>/Rules.hs
  • Duckling/<Dimension>/<Lang>/Corpus.hs
  • Duckling/Dimensions/<Lang>.hs (if not already present in Duckling/Dimensions/Common.hs)
  • Duckling/Rules/<Lang>.hs

To add a new language:

To add a new locale:

Rules have a name, a pattern and a production. Patterns are used to perform character-level matching (regexes on input) and concept-level matching (predicates on tokens). Productions are arbitrary functions that take a list of tokens and return a new token.

The corpus (resp. negative corpus) is a list of examples that should (resp. shouldn't) parse. The reference time for the corpus is Tuesday Feb 12, 2013 at 4:30am.

Duckling.Debug provides a few debugging tools:

$ stack repl --no-load
> :l Duckling.Debug
> debug (makeLocale EN $ Just US) "in two minutes" [Seal Time]
in|within|after <duration> (in two minutes)
-- regex (in)
-- <integer> <unit-of-duration> (two minutes)
-- -- integer (0..19) (two)
-- -- -- regex (two)
-- -- minute (grain) (minutes)
-- -- -- regex (minutes)
[Entity {dim = "time", body = "in two minutes", value = RVal Time (TimeValue (SimpleValue (InstantValue {vValue = 2013-02-12 04:32:00 -0200, vGrain = Second})) [SimpleValue (InstantValue {vValue = 2013-02-12 04:32:00 -0200, vGrain = Second})] Nothing), start = 0, end = 14}]


Duckling is BSD-licensed.