microsoft / recognizers-text

Microsoft.Recognizers.Text provides recognition and resolution of numbers, units, date/time, etc. in multiple languages (ZH, EN, FR, ES, PT, DE, IT, TR, HI, NL. Partial support for JA, KO, AR, SV). Packages available at: https://www.nuget.org/profiles/Recognizers.Text, https://www.npmjs.com/~recognizers.text

Microsoft Recognizers Text Overview

Microsoft.Recognizers.Text provides robust recognition and resolution of entities like numbers, units, and date/time; expressed in multiple languages. Full support for Chinese, English, French, Spanish, Portuguese, German, Italian, Turkish, Hindi, and Dutch. Partial support for Japanese, Korean, Arabic, and Swedish. More on the way.

Utilizing the Project

Microsoft.Recognizers.Text powers pre-built entities in LUIS: Language Understanding Intelligent Service, Power Virtual Agents, and Microsoft Bot Framework; base entity types in Text Analytics Cognitive Service; and it is also available as standalone packages (for the base classes and the different entity recognizers).

The Microsoft.Recognizers.Text packages currently target four platforms:

• C#/.NET - NuGet packages available at: https://www.nuget.org/profiles/Recognizers.Text
• JavaScript/TypeScript - NPM packages available at: https://www.npmjs.com/~recognizers.text
• Python - PyPI packages available at: https://pypi.org/user/recognizers-text/ (alpha)
• Java (in progress)

Contributions are greatly welcome! Both for fixes and extensions in the currently supported languages and for expansion to new ones. Especially for Japanese, Korean, Arabic, Swedish, and others! More info below.

.NET is the primary package version and contributions propagate to the other platforms with time.

Citing the Recognizers-Text project

If you utilize the recognizers in academic works, please cite it as below (you can omit the version number or update it to a specific version if relevant):

@software{soft:recognizers-text,
  author    = {Wenhao Huang and Zijia Lin and Chris McConnell and B{\"{o}}rje F. Karlsson},
  title     = {{Recognizers-Text}: {R}ecognition and resolution of numbers, units, and date/time entities expressed across multiple languages},
  month     = jul,
  year      = 2017,
  publisher = {Zenodo},
  version   = {1.0.0},
  doi       = {10.5281/zenodo.6860598},
  url       = {https://doi.org/10.5281/zenodo.6860598}
}

Feel free to change "@software" to "@misc" if it better fits your templates.

Help

If you have any questions, please go ahead and open an issue, even if it's not an actual bug. Issues are an acceptable discussion forum as well.

Contributing

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Good starting points for contribution are:

• the list of open issues (especially those marked as help wanted);
• the json spec cases temporarily marked as NotSupported (Specs); and
• translating json test spec cases that work in English, but don't yet exist in a target language.

The links below describe the project structure and provide both an overview and tips on how to contribute (although some steps may have become a little out-of-date). Thank you!

• Overview and language resources
• Implementing language specific behaviour
• Test specs and testing in general

Supported Entities across Cultures

The table below summarizes the currently supported entities. Support for English is usually more complete than others. The primary platform is .NET (shown in table) and support should propagate to the others.

Entity Type	EN	ZH-CN	NL	FR	DE	IT	JA	KO	PT	ES
Number (cardinal)	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Ordinal	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Percentage	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Number Range	✓	✓	✓	✓	✓	✓	PA/EO	✓	✓	✓
Unit - Age	✓	✓	✓	✓	✓	✓	✓	PA/EO	✓	✓
Unit - Currency	✓	✓	✓	✓	✓	✓	✓	PA/EO	✓	✓
Unit - Dimensions	✓	✓	✓	✓	✓	✓	✓	PA/EO	✓	✓
Unit - Temperature	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Choice - Boolean	✓	✓	✓	✓	✓	✓	✓	SO	✓	✓
Seq. - E-mail	G	G*	G	G	G	G	G*	G*	G	G
Seq. - GUID	G	G	G	G	G	G	G	G	G	G
Seq. - Social	G	G	G	G	G	G	G	G	G	G
Seq. - IP Address	G	G	G	G	G	G	G	G	G	G
Seq. - Phone Number	G	G	G	G	G	G	G	G	G	G
Seq. - URL	G	G*	G	G	G	G	G*	G*	G	G
DateTime (+subtypes)	✓	✓	✓	✓	✓	✓	✓	SO	✓	✓

Entity Type	SV	BG	TR	HI	AR
Number (cardinal)	✓	❌	✓	✓	PA/EO
Ordinal	✓	❌	✓	✓	PA/EO
Percentage	✓	❌	✓	✓	PA/EO
Number Range	❌	❌	✓	✓	PA/EO
Unit - Age	✓	❌	✓	✓	❌
Unit - Currency	✓	❌	✓	✓	❌
Unit - Dimensions	✓	❌	✓	✓	❌
Unit - Temperature	✓	❌	✓	✓	❌
Choice - Boolean	✓	✓	✓	✓	✓
Seq. - E-mail	G	G	G	G	G
Seq. - GUID	G	G	G	G	G
Seq. - Social	G	G	G	G	G
Seq. - IP Address	G	G	G	G	G
Seq. - Phone Number	❌	❌	❌	❌	❌
Seq. - URL	G	G	G	G*	G*
DateTime (+subtypes)	SP	❌	✓	✓	SO

• G: Generic entity, not language-specific (* unicode TLDs not-supported);
• EO: Extraction-only (parsing/resolution/normalization pending);
• PA: Partial support (type not fully supported);
• SO: Specs-only (test specs coverage OK, but support pending);
• SP: Partial specs;
• SI: Very initial specs (typically language support start for a new language).

recognizers-text's Issues

Add support for written decades as range in English

e.g. eighties = 80-89

Support for PT-PT or PT-BR for date-time

I'm interested in date/time for Portuguese. How hard would it be to adapt existing code for Portuguese strings? Is there any steps one could follow?

Thanks in advance.

[French Number] Unit tests failing

It seems that some of the regexes are malformed. To look into this please fix first #13 and #14

@matthewshim-ms

[EN DateTimeV2] Information loss when recognizing terms such as 'this week' or 'next week'

Language such as 'last week', 'this week' and 'next week' are recognized by the datetime recognizers. This is great but the resolution goes to far with the result that the original meaning is lost.

Specifically the utterance is resolved to a daterange relative to now.

Not only is this calculation something the client could easily do for itself, but on some occasions it would have some advantages to doing it itself. Specifically if it wanted to specify what now to base the calculation on. If for example the utterance was captured and the meaning applied later, next week for example. The original meaning would have been lost.

What would be most useful is for the recognizer to just recognize and not calculate ranges.

There is a precedence for just returning the recognition. Consider the case of "now" which resolves to "PRESENT_REF." It would be far better if a phrase like 'this week' resolved to something similar 'PRESENT_WEEK' or some other symbol the client could switch on. Perhaps the range TIMEX syntax could be used - for example something like (PRESENT_REF,,P7D) for this week or (PRESENT_REF+P7D,,P7D) for next week....

[* DateTimeV2] Expose timex configuration parameter for default datetime format for ambiguous cases.

Current code assumes US date-time format for ambiguous date (ex: 11/11/11). Configuration parameters should allow customization of the format to be used in such cases.

Support ordinary number + relative month in datetime extraction

Ex: Set an event for the 20th of next month for event_name."

[EN DateTimeV2] Support hemisphere property conf, so DatePeriodParser can properly resolve seasons

TestDatePeriodParser.cs

BasicTestFuture("I'll leave this summer", 2016, 6, 1, 2016, 9, 1);
BasicTestFuture("I'll leave in summer", 2017, 6, 1, 2017, 9, 1);
BasicTestFuture("I'll leave in winter", 2016, 12, 1, 2017, 3, 1);
BasicTestFuture("I'll leave in winter, 2017", 2017, 12, 1, 2018, 3, 1);

Resolution of season is a matter of difference between north and south hemispheres. Code should support conf parameter for this. And assume a default (north, mentioned in the schema).

Samples link is broken in Readme.md

The following appears to be broken:

https://github.com/Microsoft/Recognizers-Text/blob/master/samples

Support French CurrencyModel, TemperatureModel, DimensionModel, AgeModel

Documentation?

Is there any documentation available?

single number when there is a determined time in the range

from 3 to 4:30, since 4:30 is a determined time, 3 should be extracted as time as well.
from 3 to 4:30 should be a time range.

Lunch/break-first/dinner could be used for am/pm disambiguation

Request from users.

Implement the TODOs for Spanish timex for parity with English

Some cases in Spanish are not covered. The code has some TODOs for it.

[FR Number] The common written form "40 000" should be recognized as number 40000

"Input": "Siegel payé national et 94 000 $ shuster pour laisser tomber toutes les réclamations."

[EN DateTimeV2] Support relative week of days

Sample utterances: "second sunday", "next Sunday", "two sundays from now"

[* Unit] Age recognizer should use TIMEX duration

Rather than returning:
"resolution": {
"value": "50",
"unit": "Year"
},
for the text '50 years old' it would be more consistent to return a TIMEX duration. For this example that would be "P50Y"

[* Unit] Currency recognizer should use ISO 4217 currency codes

It would be very helpful if recognizers returned ISO currency codes.
refer to ISO 4217

This would avoid clients that want to use standard libraries such NumberFormat as having to cross reference.

single number around date

such as tomorrow 3, 3 should be extracted as time if there are date around.
Only effective for calendar mode.

There is a failed unit test(TestDatePeriodParse)

Installation instructions refer to non-existent NPM Packages

The section in the Readme for JavaScript refers to installing three different Node Packages - the last two of the three are missing:

https://github.com/Microsoft/Recognizers-Text/tree/master/JavaScript#installation

Dates with year before 1900 are not recognized

For example:

"Mozart died on 5 December 1791"

does not extract the year, however any year later than 1900 does work, for example:

"Hendrix died on 18 September 1970"

Support test cases with datetime options

[EN DateTimeV2] Support for "within" in datetime extraction

Support date-time alternatives in datetime extraction

Examples:

• "Would be great to get together next week. Copying person_name here, who can schedule a coffee for us. I could do Monday from 12 to 4 or Wednesday from 10 to 11"
• "Please come by. Monday 8-9am or 9-10 am works for me."

Such cases could be recognized as a single entity instead of two separate datetimes.

[EN DateTimeV2] Analyse timex support for complex set/recursion cases

1. every other Tuesday
2. once a month on the last Saturday

Ambiguity for "8p"

it means "8pm" sometime and "8 people" sometime.
Should add a field to say it is ambiguous.

date time recognizers get the ISO week wrong

Try running something like this (using the JavaScript though I think the bug is also in the C# because LUIS also appears to get this wrong.)

dateTimeModel.parse('this week')

Today (I'm writing this on 2017-11-13) resulting TIMEX expression is 2017-W47

In other words the library thinks it is week 47 however, the ISO week is actually week 46.

TIMEX should contain the ISO week number.

For reference there are a bunch of web sites that show this. https://weeknumber.net/ and https://www.epochconverter.com/weeknumbers are a couple of examples.

Alternatively you can use Excel. Open Excel and type =ISOWEEKNUM(TODAY()) into a cell.

Needless to say next week, last week etc. are also wrong.

[EN DateTimeV2] Support extraction of year written in 'full text'

Ex: "in September twenty eight two thousand and fourteen"

Open: should there be a range of supported years values or require it be adjacent to month/weekday?
Both.

Bug in handling "every morning"

Every morning should be recognized as a set. "time": "XXXX-XX-XXTMO"

Currently it returns only "morning":
{ "type": "builtin.datetimeV2.timerange", "entity": "morning", "resolution": { "values": [{"timex": "TMO", "type": "timerange", "start": "08:00:00", "end": "12:00:00"}] }

[* Number] Ordinals recognizer should support relative references

The ordinals recognizer should support relative references like "the first one", "the last one", "the second to last one", "the third one from the beginning"

Manual build instructions for JavaScript don't work

The manual build instructions for JavaScript don't appear to work.

At least the paths are wrong, but even after working around that the "npm run build" failed.

[EN DateTimeV2.Timezone] Support recognition of common timezone short names as entity, providing possible alternatives

For example, in: "schedule a meeting at 3PM CST"
CST should be tagged as timezone, plus the response should include possible alternatives if ambiguous (e.g. "Central Standard Time", "China Standard Time").

datetime recognizer should return simple JavaScript objects and arrays

Current the result of parse appears to contain the new JavaScript data structures, things like Set and Map.

It would be better to restrict this small result to simple JavaScript object and array structures. This would make them easier to work with: the developer could for example trivially use JSON.stringify and then use simple language operators . and []

Add timex support for written decades in Chinese

Unit test failures in JavaScript

When I build the JavaScript code (using the build.cmd as the manual steps appear to be broken) I get three unit tests broken:

5305 passed
3 failed
209 skipped

DateTime - Spanish - DateTimePeriodParser - "Estaré afuera de 2:00pm, 2016-2-21 a 3:32, 04/23/2016"
C:\private\Recognizers-Text\JavaScript\test\runner-datetime.js:100
100: t.is(actual.value.timex, expected.Value.Timex, 'Result.Value.Timex');
Result.Value.Timex
Difference:

• '(2016-02-21T14:00,2016-04-23T03:32,PT1477H)'

• '(2016-02-21T14:00,2016-04-23T03:32,PT1478H)'
  _.zip.forEach.o (test/runner-datetime.js:100:19)
  Test.t [as fn] (test/runner.js:26:35)
  DateTime - English - DateTimePeriodParser - "I'll be out from 2:00pm, 2016-2-21 to 3:32, 04/23/2016"
  C:\private\Recognizers-Text\JavaScript\test\runner-datetime.js:100
  100: t.is(actual.value.timex, expected.Value.Timex, 'Result.Value.Timex');
  Result.Value.Timex
  Difference:

• '(2016-02-21T14:00,2016-04-23T03:32,PT1477H)'

• '(2016-02-21T14:00,2016-04-23T03:32,PT1478H)'
  _.zip.forEach.o (test/runner-datetime.js:100:19)
  Test.t [as fn] (test/runner.js:26:35)
  DateTime - English - DateTimePeriodParser - "I'll be out I'll be out from 2:00pm, 2016-2-21 to 3:32, 04/23/2016"
  C:\private\Recognizers-Text\JavaScript\test\runner-datetime.js:100
  100: t.is(actual.value.timex, expected.Value.Timex, 'Result.Value.Timex');
  Result.Value.Timex
  Difference:

• '(2016-02-21T14:00,2016-04-23T03:32,PT1477H)'

• '(2016-02-21T14:00,2016-04-23T03:32,PT1478H)'

Bug handling "week of September 30th" as a range

Currently recognizing only "September 30". "date": "XXXX-09-30"

Should be:
{ "entity": "september 30th", "type": "builtin.datetimeV2.date", "resolution": { "values": [{ "timex": "XXXX-09-30", "type": "date", "value": "2016-09-30" },{"timex": "XXXX-09-30","type": "date", "value": "2017-09-30" }]} }

Support French DateTime

Schema doesn't match LUIS

The schema returned by the recognizers is close to the LUIS schema for Entities but not exactly the same. It should be exactly the same. For example the number recognizer returns "start", "end", and "text" fields. These are "startIndex", "endIndex", and "entity" fields in LUIS.

A developer should be able to work with an entity the same way, regardless of whether it came from a call to LUIS or a call to a recognizer. The schemas need to be identical for that to be true.

[FR Unit] "cent in "pour cent" should not be recognized as a currency unit

Cent in 8 pour cent should not be detected as currency unit in input like: "Pour les 20 restaurants les plus chers dans la ville, le prix d'un dîner est monté de 63,45 $, aussi une augmentation de 8 pour cent."

[French Number] Incomplete regex

It seems this regex is incomplete

@matthewshim-ms

[French Number] Cardinal Dictionary have duplicated keys

Seems that "un" is duplicated at https://github.com/Microsoft/Recognizers-Text/blob/master/Microsoft.Recognizers.Text.Number/French/Parsers/FrenchNumberParserConfiguration.cs#L107

@matthewshim-ms

[* Unit] Currency recognizer doesn't recognizer compound structures in words

The currency recognizer will find $3.50 in the following:

"it only cost $3.50"

but finds two entities when this same is expressed in words:

"it only cost 3 dollars 50 cents."

[EN DateTimeV2] Output for invalid dates should follow the same format for all cases

2015-02-29
2016-13-20
2017-11-31
2018-01-32

Open: should timex support extracting something like 2017-99-88 as a date??

Merge time periods like “2 weeks and 3 days”, “1 month 3 days”

Time periods such as "1 week and two days" should be extracted as one entity, not two.

[* DateTimeV2] Timex expression for last hour is incorrect

"last hour" is currently resolved as
2017-08-01T13:01:50,2017-08-01T14:01:50,PT1H

We should add PREV before PT1H.

datetime recognizer inconsistent with LUIS

When I give LUIS the string "in 5 minutes" it resolves that to a datetime "2017-11-13T21:39:41"

However, when I use the local JavaScript recognizer is just recognizes the "5 minutes" and produces a duration "PT5M"

The local JavaScript recognizer should have found the datetime.

Analyze support merge of date range and time range into set/recursion

Add more "before" recognizers to datetimeV2. (in advance of, prior to)

I experimented with using composites and a custom workaround. What is strange is that if you use a word like "before", suggested LUIS additions are "in advance of", "prior to", etc. yet the builtin time function does not respond to those very phrases.

[EN DateTimeV2] Does not recognize "less than 24 hours"

If I ask a question like "____________ in the LAST 24 hours" datetime entity works correctly. However, asking "______ for less than 24 hours."

[* Number] Percentage recognizer resolution should resolve to fraction

Recognizing an utterance such as 'fifty percent' as a percentage value is great but it would be more helpful to client code if the resolution was to a floating point value.

Specifically: an utterance such as 'fifty percent' results in:
"resolution": {
"value": "50%"
},

Given the type has been correctly identified as percentage it would be better for the client code to receive a floating point number.

This would also fit more naturally with NumberFormat where the client could use code like this:

        const formatter = new Intl.NumberFormat('en-US', { style: 'percent' });
        return formatter.format(obj.value);

Which would assume obj.value to be 0.5 for 50%