@mailwoman/kind-classifier 4.10.0 → 4.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +68 -0
  2. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,68 @@
1
+ # @mailwoman/kind-classifier
2
+
3
+ **Stage 2.5 of the Mailwoman runtime pipeline** — query kind classification.
4
+
5
+ Categorizes an input into one of seven `QueryKind`s by composing rule-based
6
+ scorers over the `QueryShape` output. Returns possibilities (alternatives)
7
+ alongside the top pick so the coordinator can fall back when the winning kind
8
+ isn't actionable.
9
+
10
+ ```ts
11
+ import { classifyKind } from "@mailwoman/kind-classifier"
12
+
13
+ const result = await classifyKind(queryShape, localeHint)
14
+ // result.kind → "structured_address"
15
+ // result.alternatives → [{kind: "intersection", confidence: 0.2}, ...]
16
+ ```
17
+
18
+ ## The seven query kinds
19
+
20
+ | Kind | Example |
21
+ | -------------------- | --------------------------------------------------- |
22
+ | `structured_address` | `"1600 Amphitheatre Pkwy, Mountain View, CA 94043"` |
23
+ | `postcode_only` | `"94043"` or `"SW1A 1AA"` |
24
+ | `locality_only` | `"Mountain View"` or `"San Francisco"` |
25
+ | `intersection` | `"Market St & Van Ness Ave"` |
26
+ | `po_box` | `"PO Box 12345"` |
27
+ | `landmark` | `"Eiffel Tower"` |
28
+ | `vague` | `"somewhere near the river"` |
29
+
30
+ ## API
31
+
32
+ ```ts
33
+ classifyKind(shape: QueryShapeLike, locale?: LocaleHint): Promise<QueryKindResult>
34
+ classifyKindSync(shape: QueryShapeLike, locale?: LocaleHint): QueryKindResult
35
+
36
+ // Individual scorers
37
+ scoreStructuredAddress(input: NormalizedInputLite, shape: QueryShapeLike): number
38
+ scorePostcodeOnly(shape: QueryShapeLike): number
39
+ scoreLocalityOnly(shape: QueryShapeLike): number
40
+ scoreIntersection(input: NormalizedInputLite, shape: QueryShapeLike): number
41
+ scorePoBox(input: NormalizedInputLite, shape: QueryShapeLike): number
42
+ scoreLandmark(shape: QueryShapeLike): number
43
+ scoreVague(shape: QueryShapeLike): number
44
+ ```
45
+
46
+ ## Pipeline position
47
+
48
+ ```
49
+ locale-gate → kind-classifier → phrase-grouper → classifier → ...
50
+ ```
51
+
52
+ ## Design
53
+
54
+ - **Pure functions, no ML.** Rule-based v1; a trained classifier is deferred.
55
+ - **Returns alternatives.** The coordinator might skip a `locality_only` parse
56
+ and fall back to a `vague` handler — the alternatives list makes that possible.
57
+ - **Consumes `QueryShape` + `LocaleHint`** from the two preceding stages.
58
+
59
+ ## Related
60
+
61
+ - [`@mailwoman/query-shape`](../query-shape) — feeds structural data into this stage
62
+ - [`@mailwoman/locale-gate`](../locale-gate) — feeds locale context
63
+ - [`@mailwoman/phrase-grouper`](../phrase-grouper) — Stage 2.7, next in the pipeline
64
+ - [Staged Pipeline Contract](https://mailwoman.sister.software/articles/plan/reference/STAGES/)
65
+
66
+ ## License
67
+
68
+ [AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mailwoman/kind-classifier",
3
- "version": "4.10.0",
3
+ "version": "4.11.0",
4
4
  "description": "Stage 2.5 of the runtime pipeline — categorize inputs by query shape (postcode_only / locality_only / structured_address / intersection / po_box / landmark / vague). Rule-based for v1.",
5
5
  "license": "AGPL-3.0-only",
6
6
  "repository": {
@@ -14,7 +14,7 @@
14
14
  ".": "./out/index.js"
15
15
  },
16
16
  "dependencies": {
17
- "@mailwoman/core": "4.10.0"
17
+ "@mailwoman/core": "4.11.0"
18
18
  },
19
19
  "files": [
20
20
  "out/**/*.js",