vertiq 0.2.0__tar.gz → 0.2.2__tar.gz

{vertiq-0.2.0/vertiq.egg-info → vertiq-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vertiq
-Version: 0.2.0
+Version: 0.2.2
 Summary: Self-improving decision intelligence: a local language model that maps any operational dataset and decision models trained on real outcomes, improved through recursive self-improvement under an evaluation gate.
 Author: Biswajit Tripathy
 License: Apache-2.0
@@ -135,7 +135,7 @@ Intervention effects are estimated against control groups rather than inferred f
 
 - **Control-group uplift.** vertiq.uplift compares treated entities with a randomly held-out group over the same window and ranks entities by estimated incremental effect. In the benchmark it estimated a planted −20% offer effect at -20.2%.
 - **Configurable horizons.** window_days sets the prediction horizon, cutoffs the number of historical training points and history the event types used as inputs, so each task matches the operating cycle of the industry.
-- **Small footprint.** The decision engine has no third-party dependencies and no network layer. It runs wherever Python 3.10 runs; the full benchmark suite completes in 196 seconds on a laptop using 4 cores.
+- **Small footprint.** The decision engine has no third-party dependencies and no network layer. It runs wherever Python 3.10 runs; the full benchmark suite completes in 70 seconds on a laptop using 4 cores.
 
 ### Defensive deployment
 
@@ -143,6 +143,7 @@ A candidate model is treated as unproven until it has been evaluated.
 
 - **Held-out evaluation.** Candidates are scored on entities excluded from training, using features built only from events recorded before each cutoff.
 - **Champion–challenger gate.** A candidate must outperform the rule-based baseline and the production model, and its gain over the baseline must be clear at 90% confidence by default. min_gain sets a required margin: an AUC margin for event tasks and a relative error reduction for value tasks.
+- **Segment check.** A candidate that wins on average but is clearly worse than the baseline for a segment of the held-out entities is not promoted. Segments come from the data (entity groups, entity-table labels, length of history), each with at least 30 held-out entities, and the confidence level is corrected for the number checked.
 - **Explicit rejection.** A rejected candidate returns status "kept" with the reason, such as the AUC it reached against the required threshold. The production model remains in service.
 
 | Principle | Mechanism | Configuration | Operational value |
@@ -254,7 +255,7 @@ Plugins add features; the evaluation gate determines whether they improve perfor
 ## Benchmarks
 
 Synthetic scenarios with known ground truth, 5 runs each, mean ± standard deviation (`python benchmarks/run.py`,
-196 seconds on a laptop using 4 cores, arm64, Python 3.10.10).
+70 seconds on a laptop using 4 cores, arm64, Python 3.10.10).
 
 | Scenario | Vertiq | Reference |
 |---|---|---|
@@ -343,7 +344,7 @@ Production-like test set (audit columns and locale-specific number formats):
 
 ## Verify the results
 
-Every decision-engine figure can be reproduced from a clean checkout with Python and pytest; the benchmark suite runs in about 196 seconds on a laptop using 4 cores. Vertiq LM figures require Apple Silicon and the model weights; see [lm/README.md](lm/README.md).
+Every decision-engine figure can be reproduced from a clean checkout with Python and pytest; the benchmark suite runs in about 70 seconds on a laptop using 4 cores. Vertiq LM figures require Apple Silicon and the model weights; see [lm/README.md](lm/README.md).
 
 ```bash
 git clone https://github.com/BiswajitBiswa/vertiq && cd vertiq
@@ -367,50 +368,25 @@ The methods are established and deliberately transparent: regularised logistic a
 
 ## Limitations
 
-- Most benchmarks use synthetic data. They verify that the methods detect planted signal, reject noise and retain the baseline
-  when appropriate; one public dataset (Online Retail II) has been run. None measures accuracy on a specific organisation's data.
-- The gate requires the gain over the baseline to be clear at 90% confidence (`confidence=0.9`, the default). On small datasets this
-  also holds back some real improvements until more data arrives: with 240 assets and a real signal, 7 of 15 candidates were
-  promoted, against 13 of 15 with the check off. `confidence=None` turns the check off; the candidate then only has to not be worse.
-- Plain-language descriptions (`narrate`) are written from templates. A local model can rewrite them, and a rewrite is kept only
-  if every number in it appears in the template and it is no longer. On 17 descriptions, Qwen 3.5 4B given the full result
-  attached real numbers to the wrong quantity in 4; given only the template, its accepted rewrites were close paraphrases, and
-  Qwen 3.5 9B returned the template unchanged. Fluent rewrites would need fine-tuning on reviewed examples.
-- After validation, Vertiq LM maps 54% of held-out tables exactly (42% from domains it was
-  not trained on) and loads 100%
-  without errors. Proposed mappings should be reviewed before production use.
-- Uplift estimation requires a randomised control group. Without one, `causal.matched_att` gives an estimate whose validity
-  depends on every confounder being observed; `design.next_step` reports the experiment size needed to settle the question.
-- On the synthetic benchmarks, boosted trees improve on linear models where effects are non-linear and do not where effects are
-  additive. Across 100 to 6,400 entities the default tree settings were within 0.01 AUC of the best of five alternatives.
-  `learner="auto"` chooses by 3-fold cross-validation on the training entities; with a few hundred entities or fewer its
-  choice is close to random when the two learners are within a point or two of each other.
-- Doubly robust estimates are consistent if either the propensity or the outcome model is right, but they vary more than the
-  outcome model alone (standard deviation 0.17 across benchmark runs); large weights from extreme
-  propensities are clipped and counted in the result.
-- The rule-based mapping proposer gets 57% of roles right on the held-out real exports and Vertiq LM 83%; both are checked by
-  validation, which flags what it cannot settle (for example two complete amount columns, or day/month order), but meaning
-  (which amount is the one that matters) still needs a person or the model.
-- Tables with one row per entity (customer lists, asset registers) often hold totals and dates computed when the file was
-  exported; Vertiq uses them to describe, never as prediction features.
-- `plan` and `guard` rely on uplift tasks, so they are only as good as the recorded actions and control groups; an action
-  that was never measured is excluded from plans and held by the check. `guard` does not decide on its own: it allows only
-  measured, clearly helpful actions.
-- `menu` proposes features from a fixed set of operations; anything outside it (external data, formulas specific to a
-  sector) is added as a plugin by a person and judged by the same gate.
-- `autotune` scores every trial on the same training entities, so many trials can still favour a lucky change; it keeps a change
-  only when most validation folds agree, and the held-out gate makes the final decision.
+- Most benchmarks use synthetic data. They verify that the methods detect planted signal, reject noise and retain the baseline when appropriate; one public dataset (Online Retail II) has been run. None measures accuracy on a specific organisation's data.
+- The gate requires the gain over the baseline to be clear at 90% confidence (`confidence=0.9`, the default). On small datasets this also holds back some real improvements until more data arrives: with 240 assets and a real signal, 7 of 15 candidates were promoted, against 13 of 15 with the check off. `confidence=None` turns the check off; the candidate then only has to not be worse.
+- Plain-language descriptions (`narrate`) are written from templates by default. The trained rewrite model gives real rewrites for 27 of 50 held-out descriptions, and every rewrite is checked: each number must be the template's and stay next to what it described. The checks catch invented and moved numbers, not every misleading sentence.
+- After validation, Vertiq LM maps 54% of held-out tables exactly (42% from domains it was not trained on) and loads 100% without errors. Proposed mappings should be reviewed before production use.
+- Uplift estimation requires a randomised control group. Without one, `causal.matched_att` gives an estimate whose validity depends on every confounder being observed; `design.next_step` reports the experiment size needed to settle the question.
+- On the synthetic benchmarks, boosted trees improve on linear models where effects are non-linear and do not where effects are additive. Across 100 to 6,400 entities the default tree settings were within 0.01 AUC of the best of five alternatives. `learner="auto"` chooses by 3-fold cross-validation on the training entities; with a few hundred entities or fewer its choice is close to random when the two learners are within a point or two of each other.
+- Doubly robust estimates are consistent if either the propensity or the outcome model is right, but they vary more than the outcome model alone (standard deviation 0.17 across benchmark runs); large weights from extreme propensities are clipped and counted in the result.
+- The rule-based mapping proposer gets 57% of roles right on the held-out real exports and Vertiq LM 83%; both are checked by validation, which flags what it cannot settle (for example two complete amount columns, or day/month order), but meaning (which amount is the one that matters) still needs a person or the model.
+- Tables with one row per entity (customer lists, asset registers) often hold totals and dates computed when the file was exported; Vertiq uses them to describe, never as prediction features.
+- `plan` and `guard` rely on uplift tasks, so they are only as good as the recorded actions and control groups; an action that was never measured is excluded from plans and held by the check. `guard` does not decide on its own: it allows only measured, clearly helpful actions.
+- `menu` proposes features from a fixed set of operations; anything outside it (external data, formulas specific to a sector) is added as a plugin by a person and judged by the same gate.
+- `autotune` scores every trial on the same training entities, so many trials can still favour a lucky change; it keeps a change only when most validation folds agree, and the held-out gate makes the final decision.
 - Version 0.2. The API may change before 1.0; changes are recorded in [CHANGELOG.md](CHANGELOG.md).
 
 ## Roadmap
 
-- Further public benchmarks: M5 (value prediction), NASA C-MAPSS (equipment failure),
-  KKBOX (churn), and Hillstrom and Criteo (randomised uplift); protocols in [proposal 0001](proposals/0001-statistical-validation.md), part C.
-- Distribution on PyPI.
-- Vertiq LM: a training round on tables with real-export clutter (`lm/make_data.py --messy`), scored on the synthetic and the real
-  held-out sets; evaluate a 9B student and publish the adapter with a `vertiq map` command.
-- `autotune` for value tasks and uplift; menu operations for group-level signals and external series (weather, prices) joined by
-  date and location; menu items suggested by a language model for a sector, checked by `menu.parse`.
+- Further public benchmarks: M5 (value prediction), NASA C-MAPSS (equipment failure), KKBOX (churn), and Hillstrom and Criteo (randomised uplift); protocols in [proposal 0001](proposals/0001-statistical-validation.md), part C.
+- Vertiq LM: a training round on tables with real-export clutter (`lm/make_data.py --messy`), scored on the synthetic and the real held-out sets; evaluate a 9B student and publish the adapter with a `vertiq map` command.
+- `autotune` for value tasks and uplift; menu operations for group-level signals and external series (weather, prices) joined by date and location; menu items suggested by a language model for a sector, checked by `menu.parse`.
 - Turning free-text fields (support tickets, maintenance notes) into validated events.
 
 Further reading on recursive self-improvement is kept in [proposals/reading-list.md](proposals/reading-list.md), and an external assessment of the competitive landscape in [proposals/landscape-review.md](proposals/landscape-review.md).

{vertiq-0.2.0 → vertiq-0.2.2}/README.md

@@ -105,7 +105,7 @@ Intervention effects are estimated against control groups rather than inferred f
 
 - **Control-group uplift.** vertiq.uplift compares treated entities with a randomly held-out group over the same window and ranks entities by estimated incremental effect. In the benchmark it estimated a planted −20% offer effect at -20.2%.
 - **Configurable horizons.** window_days sets the prediction horizon, cutoffs the number of historical training points and history the event types used as inputs, so each task matches the operating cycle of the industry.
-- **Small footprint.** The decision engine has no third-party dependencies and no network layer. It runs wherever Python 3.10 runs; the full benchmark suite completes in 196 seconds on a laptop using 4 cores.
+- **Small footprint.** The decision engine has no third-party dependencies and no network layer. It runs wherever Python 3.10 runs; the full benchmark suite completes in 70 seconds on a laptop using 4 cores.
 
 ### Defensive deployment
 
@@ -113,6 +113,7 @@ A candidate model is treated as unproven until it has been evaluated.
 
 - **Held-out evaluation.** Candidates are scored on entities excluded from training, using features built only from events recorded before each cutoff.
 - **Champion–challenger gate.** A candidate must outperform the rule-based baseline and the production model, and its gain over the baseline must be clear at 90% confidence by default. min_gain sets a required margin: an AUC margin for event tasks and a relative error reduction for value tasks.
+- **Segment check.** A candidate that wins on average but is clearly worse than the baseline for a segment of the held-out entities is not promoted. Segments come from the data (entity groups, entity-table labels, length of history), each with at least 30 held-out entities, and the confidence level is corrected for the number checked.
 - **Explicit rejection.** A rejected candidate returns status "kept" with the reason, such as the AUC it reached against the required threshold. The production model remains in service.
 
 | Principle | Mechanism | Configuration | Operational value |
@@ -224,7 +225,7 @@ Plugins add features; the evaluation gate determines whether they improve perfor
 ## Benchmarks
 
 Synthetic scenarios with known ground truth, 5 runs each, mean ± standard deviation (`python benchmarks/run.py`,
-196 seconds on a laptop using 4 cores, arm64, Python 3.10.10).
+70 seconds on a laptop using 4 cores, arm64, Python 3.10.10).
 
 | Scenario | Vertiq | Reference |
 |---|---|---|
@@ -313,7 +314,7 @@ Production-like test set (audit columns and locale-specific number formats):
 
 ## Verify the results
 
-Every decision-engine figure can be reproduced from a clean checkout with Python and pytest; the benchmark suite runs in about 196 seconds on a laptop using 4 cores. Vertiq LM figures require Apple Silicon and the model weights; see [lm/README.md](lm/README.md).
+Every decision-engine figure can be reproduced from a clean checkout with Python and pytest; the benchmark suite runs in about 70 seconds on a laptop using 4 cores. Vertiq LM figures require Apple Silicon and the model weights; see [lm/README.md](lm/README.md).
 
 ```bash
 git clone https://github.com/BiswajitBiswa/vertiq && cd vertiq
@@ -337,50 +338,25 @@ The methods are established and deliberately transparent: regularised logistic a
 
 ## Limitations
 
-- Most benchmarks use synthetic data. They verify that the methods detect planted signal, reject noise and retain the baseline
-  when appropriate; one public dataset (Online Retail II) has been run. None measures accuracy on a specific organisation's data.
-- The gate requires the gain over the baseline to be clear at 90% confidence (`confidence=0.9`, the default). On small datasets this
-  also holds back some real improvements until more data arrives: with 240 assets and a real signal, 7 of 15 candidates were
-  promoted, against 13 of 15 with the check off. `confidence=None` turns the check off; the candidate then only has to not be worse.
-- Plain-language descriptions (`narrate`) are written from templates. A local model can rewrite them, and a rewrite is kept only
-  if every number in it appears in the template and it is no longer. On 17 descriptions, Qwen 3.5 4B given the full result
-  attached real numbers to the wrong quantity in 4; given only the template, its accepted rewrites were close paraphrases, and
-  Qwen 3.5 9B returned the template unchanged. Fluent rewrites would need fine-tuning on reviewed examples.
-- After validation, Vertiq LM maps 54% of held-out tables exactly (42% from domains it was
-  not trained on) and loads 100%
-  without errors. Proposed mappings should be reviewed before production use.
-- Uplift estimation requires a randomised control group. Without one, `causal.matched_att` gives an estimate whose validity
-  depends on every confounder being observed; `design.next_step` reports the experiment size needed to settle the question.
-- On the synthetic benchmarks, boosted trees improve on linear models where effects are non-linear and do not where effects are
-  additive. Across 100 to 6,400 entities the default tree settings were within 0.01 AUC of the best of five alternatives.
-  `learner="auto"` chooses by 3-fold cross-validation on the training entities; with a few hundred entities or fewer its
-  choice is close to random when the two learners are within a point or two of each other.
-- Doubly robust estimates are consistent if either the propensity or the outcome model is right, but they vary more than the
-  outcome model alone (standard deviation 0.17 across benchmark runs); large weights from extreme
-  propensities are clipped and counted in the result.
-- The rule-based mapping proposer gets 57% of roles right on the held-out real exports and Vertiq LM 83%; both are checked by
-  validation, which flags what it cannot settle (for example two complete amount columns, or day/month order), but meaning
-  (which amount is the one that matters) still needs a person or the model.
-- Tables with one row per entity (customer lists, asset registers) often hold totals and dates computed when the file was
-  exported; Vertiq uses them to describe, never as prediction features.
-- `plan` and `guard` rely on uplift tasks, so they are only as good as the recorded actions and control groups; an action
-  that was never measured is excluded from plans and held by the check. `guard` does not decide on its own: it allows only
-  measured, clearly helpful actions.
-- `menu` proposes features from a fixed set of operations; anything outside it (external data, formulas specific to a
-  sector) is added as a plugin by a person and judged by the same gate.
-- `autotune` scores every trial on the same training entities, so many trials can still favour a lucky change; it keeps a change
-  only when most validation folds agree, and the held-out gate makes the final decision.
+- Most benchmarks use synthetic data. They verify that the methods detect planted signal, reject noise and retain the baseline when appropriate; one public dataset (Online Retail II) has been run. None measures accuracy on a specific organisation's data.
+- The gate requires the gain over the baseline to be clear at 90% confidence (`confidence=0.9`, the default). On small datasets this also holds back some real improvements until more data arrives: with 240 assets and a real signal, 7 of 15 candidates were promoted, against 13 of 15 with the check off. `confidence=None` turns the check off; the candidate then only has to not be worse.
+- Plain-language descriptions (`narrate`) are written from templates by default. The trained rewrite model gives real rewrites for 27 of 50 held-out descriptions, and every rewrite is checked: each number must be the template's and stay next to what it described. The checks catch invented and moved numbers, not every misleading sentence.
+- After validation, Vertiq LM maps 54% of held-out tables exactly (42% from domains it was not trained on) and loads 100% without errors. Proposed mappings should be reviewed before production use.
+- Uplift estimation requires a randomised control group. Without one, `causal.matched_att` gives an estimate whose validity depends on every confounder being observed; `design.next_step` reports the experiment size needed to settle the question.
+- On the synthetic benchmarks, boosted trees improve on linear models where effects are non-linear and do not where effects are additive. Across 100 to 6,400 entities the default tree settings were within 0.01 AUC of the best of five alternatives. `learner="auto"` chooses by 3-fold cross-validation on the training entities; with a few hundred entities or fewer its choice is close to random when the two learners are within a point or two of each other.
+- Doubly robust estimates are consistent if either the propensity or the outcome model is right, but they vary more than the outcome model alone (standard deviation 0.17 across benchmark runs); large weights from extreme propensities are clipped and counted in the result.
+- The rule-based mapping proposer gets 57% of roles right on the held-out real exports and Vertiq LM 83%; both are checked by validation, which flags what it cannot settle (for example two complete amount columns, or day/month order), but meaning (which amount is the one that matters) still needs a person or the model.
+- Tables with one row per entity (customer lists, asset registers) often hold totals and dates computed when the file was exported; Vertiq uses them to describe, never as prediction features.
+- `plan` and `guard` rely on uplift tasks, so they are only as good as the recorded actions and control groups; an action that was never measured is excluded from plans and held by the check. `guard` does not decide on its own: it allows only measured, clearly helpful actions.
+- `menu` proposes features from a fixed set of operations; anything outside it (external data, formulas specific to a sector) is added as a plugin by a person and judged by the same gate.
+- `autotune` scores every trial on the same training entities, so many trials can still favour a lucky change; it keeps a change only when most validation folds agree, and the held-out gate makes the final decision.
 - Version 0.2. The API may change before 1.0; changes are recorded in [CHANGELOG.md](CHANGELOG.md).
 
 ## Roadmap
 
-- Further public benchmarks: M5 (value prediction), NASA C-MAPSS (equipment failure),
-  KKBOX (churn), and Hillstrom and Criteo (randomised uplift); protocols in [proposal 0001](proposals/0001-statistical-validation.md), part C.
-- Distribution on PyPI.
-- Vertiq LM: a training round on tables with real-export clutter (`lm/make_data.py --messy`), scored on the synthetic and the real
-  held-out sets; evaluate a 9B student and publish the adapter with a `vertiq map` command.
-- `autotune` for value tasks and uplift; menu operations for group-level signals and external series (weather, prices) joined by
-  date and location; menu items suggested by a language model for a sector, checked by `menu.parse`.
+- Further public benchmarks: M5 (value prediction), NASA C-MAPSS (equipment failure), KKBOX (churn), and Hillstrom and Criteo (randomised uplift); protocols in [proposal 0001](proposals/0001-statistical-validation.md), part C.
+- Vertiq LM: a training round on tables with real-export clutter (`lm/make_data.py --messy`), scored on the synthetic and the real held-out sets; evaluate a 9B student and publish the adapter with a `vertiq map` command.
+- `autotune` for value tasks and uplift; menu operations for group-level signals and external series (weather, prices) joined by date and location; menu items suggested by a language model for a sector, checked by `menu.parse`.
 - Turning free-text fields (support tickets, maintenance notes) into validated events.
 
 Further reading on recursive self-improvement is kept in [proposals/reading-list.md](proposals/reading-list.md), and an external assessment of the competitive landscape in [proposals/landscape-review.md](proposals/landscape-review.md).

{vertiq-0.2.0 → vertiq-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vertiq"
-version = "0.2.0"
+version = "0.2.2"
 description = "Self-improving decision intelligence: a local language model that maps any operational dataset and decision models trained on real outcomes, improved through recursive self-improvement under an evaluation gate."
 readme = "README.md"
 requires-python = ">=3.10"

{vertiq-0.2.0 → vertiq-0.2.2}/tests/test_mapping.py

@@ -99,3 +99,20 @@ def test_a_column_that_mixes_decimal_styles_reads_each_value_on_its_own():
 def test_dates_with_times_are_known_formats():
     from vertiq.mapping import date_formats
     assert date_formats(["15/01/2023 09:45", "03/02/2023 18:10"]) == ["%d/%m/%Y %H:%M"]
+
+
+def test_short_customer_numbers_stay_the_entity_and_a_country_never_replaces_them():
+    """Online-store exports: 5-digit customer numbers (an id, not a price) beside a country column with a few
+    dozen values. Repair keeps the customer; a column with few values is a label, not whom records are about."""
+    from vertiq.mapping import fitness, repair
+    import random
+    rnd = random.Random(3)
+    countries = [f"Country {i}" for i in range(24)]
+    rows = [{"Invoice": str(489434 + i), "Date": f"2010-0{1 + i % 9}-1{i % 10} 10:{i % 60:02d}:00",
+             "Customer ID": str(rnd.randint(12000, 18999)), "Country": rnd.choice(countries), "Total": f"{rnd.uniform(5, 900):.2f}"}
+            for i in range(600)]
+    assert fitness(rows, "Customer ID", "entity") > 0.9
+    m, notes = repair(Mapping(entity="Customer ID", time="Date", value="Total", attrs=["Invoice"]), rows, exclude={"Invoice"})
+    assert m.entity == "Customer ID", notes
+    m, notes = repair(Mapping(entity="Date", time="Date", value="Total"), rows, exclude={"Invoice"})
+    assert m.entity != "Country"

{vertiq-0.2.0 → vertiq-0.2.2}/tests/test_patterns.py

@@ -49,3 +49,11 @@ def test_nothing_is_found_in_random_data():
 
 def test_small_data_waits():
     assert patterns.find(_orders(n=12))["status"] == "learning"
+
+
+def test_column_names_and_yes_no_flags_read_as_words():
+    assert patterns._where("payment_mode = Cash") == "where payment mode is Cash"
+    assert patterns._where("is_return = True") == "marked return"
+    assert patterns._where("no_guest = False") == "not marked no guest"
+    assert patterns._does("no_guest = True") == "are marked no guest"
+    assert patterns._does("PaymentMode = Card") == "have payment mode Card"

{vertiq-0.2.0 → vertiq-0.2.2}/tests/test_report.py

@@ -3,9 +3,17 @@ import csv
 import json
 import random
 
+import pytest
+
 from vertiq import report
 from vertiq.tables import find_join, propose
 
+
+@pytest.fixture(autouse=True)
+def _no_search(monkeypatch):
+    """The input search is slow and is tested on its own below; these tests check what the report says."""
+    monkeypatch.setattr(report, "TUNE", False)
+
 MENU = {"Margherita": "Pizza", "Farmhouse": "Pizza", "Cola": "Drinks", "Lemonade": "Drinks", "Fries": "Sides", "Salad": "Sides"}
 
 
@@ -56,7 +64,7 @@ def test_report_runs_from_file_names_only(tmp_path):
     cfg = {"records": {"file": "orders.csv"}, "items": {"file": "lines.csv"}, "noun": "orders", "currency": "₹", "event": "order"}
     (tmp_path / "config.json").write_text(json.dumps(cfg))
     text = report.run(cfg, tmp_path)
-    assert "## Patterns" in text and "include Drinks" in text and "where Channel is Online" in text
+    assert "## Patterns" in text and "include Drinks" in text and "where channel is Online" in text
     assert "a summary row" in text and "placeholder entity" in text
     assert "## Predictions" in text
 
@@ -132,7 +140,7 @@ def test_entity_table_labels_join_events_and_show_in_patterns(tmp_path):
     cfg = {"records": {"file": "orders.csv"}, "entity_table": {"file": "customers.csv"}, "noun": "orders", "entities": "customers"}
     text = report.run(cfg, tmp_path)
     assert "entity table joined on 'Customer Id'" in text
-    assert "where Segment is Gold average" in text or "where Segment is Basic average" in text
+    assert "where segment is Gold average" in text or "where segment is Basic average" in text
 
 
 def test_a_customer_list_alone_is_read_as_one_row_per_entity(tmp_path):
@@ -140,3 +148,105 @@ def test_a_customer_list_alone_is_read_as_one_row_per_entity(tmp_path):
     ds, _g, log = report.build({"records": {"file": "customers.csv"}}, tmp_path)
     assert any("one row per entity" in x for x in log)
     assert '"time": "Last Order"' in next(x for x in log if x.startswith("Mapping used"))
+
+
+def test_a_product_code_beside_the_product_name_is_not_an_item_group():
+    """Online-store lines carry a stock code for each product name. The code is the item again, not a group,
+    so patterns and combos speak in product names."""
+    from vertiq.tables import find_lines
+    rnd = random.Random(4)
+    products = [(f"{20000 + i}", f"PRODUCT NUMBER {i}") for i in range(60)]
+    rows = []
+    for inv in range(300):
+        at = f"2010-03-{1 + inv % 28:02d} 1{inv % 10}:00:00"
+        for code, name in rnd.sample(products, 3):
+            rows.append({"Invoice": str(489000 + inv), "StockCode": code, "Description": name,
+                         "Quantity": str(rnd.randint(1, 12)), "InvoiceDate": at, "Price": f"{rnd.uniform(1, 9):.2f}",
+                         "Customer ID": str(rnd.randint(12000, 12400))})
+    spec, _ = find_lines(rows)
+    assert spec["key"] == "Invoice" and spec["item"] in ("Description", "StockCode")
+    assert spec["item_group"] is None
+
+
+def _with_consent(tmp_path, allow):
+    """The customers table with a trainable column: True for customers `allow` picks."""
+    _customers(tmp_path)
+    rows = list(csv.DictReader(open(tmp_path / "customers.csv")))
+    for r in rows:
+        r["trainable"] = "True" if allow(r["Customer Id"]) else "False"
+    with open(tmp_path / "customers.csv", "w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=list(rows[0]))
+        w.writeheader()
+        w.writerows(rows)
+
+
+def test_no_model_trains_on_entities_that_may_not_be_used(tmp_path):
+    _with_consent(tmp_path, lambda cid: False)
+    cfg = {"records": {"file": "orders.csv"}, "entity_table": {"file": "customers.csv", "trainable": "trainable"}, "noun": "orders"}
+    text = report.run(cfg, tmp_path)
+    assert "No model was trained: none of the" in text and "column 'trainable'" in text
+    assert "was promoted" not in text and "## Patterns" in text            # description still runs
+    assert "No model was trained" in report.run({"records": {"file": "orders.csv"}, "train": False}, tmp_path)
+
+
+def test_models_use_only_trainable_entities(tmp_path, monkeypatch):
+    _with_consent(tmp_path, lambda cid: int(cid[-1]) % 2 == 0 if cid[-1].isdigit() else False)
+    seen = []
+    real = report.predict_event
+
+    def spy(ds, **kw):
+        seen.append({e.entity for e in ds.events})
+        return real(ds, **kw)
+    monkeypatch.setattr(report, "predict_event", spy)
+    cfg = {"records": {"file": "orders.csv"}, "entity_table": {"file": "customers.csv", "trainable": "trainable"}, "noun": "orders"}
+    text = report.run(cfg, tmp_path)
+    assert "Models use only the" in text
+    assert seen and all(int(x[-1]) % 2 == 0 for x in seen[0])
+
+
+def test_promoted_models_score_every_entity(tmp_path, monkeypatch):
+    """Scores come only from promoted models; a kept model gives none."""
+    _customers(tmp_path)
+
+    class FakeTask:
+        def __init__(self, kind, status):
+            self.kind, self.status, self.window = kind, status, 30
+            self.b = type("B", (), {"target": "order", "by": {"C1": [], "C2": [], "anonymous:7": []}})()
+
+        def report(self):
+            return {"status": "learning", "rows": 0, "need_rows": 200, "task": self.kind, "target": "order", "window_days": 30}
+
+        def score(self, eid):
+            return {"entity": eid, "value": 100.0 if eid == "C1" else 50.0, "raises": ["recent orders"], "lowers": []}
+
+    monkeypatch.setattr(report, "predict_event", lambda ds, **kw: FakeTask("event", "kept"))
+    monkeypatch.setattr(report, "predict_value", lambda ds, **kw: FakeTask("value", "trained"))
+    text = report.run({"records": {"file": "orders.csv"}, "noun": "orders", "currency": "₹", "scores": "scores.csv"}, tmp_path)
+    rows = list(csv.DictReader(open(tmp_path / "scores.csv")))
+    assert [r["entity"] for r in rows] == ["C1", "C2"] and all(r["model"] == "value of the next order" for r in rows)
+    assert "- C1: ₹100 (raised by recent orders)" in text
+
+
+def test_items_written_in_one_cell_become_line_items(tmp_path):
+    """A POS "products" column ("Shirtx999,Tshirtx699") is read as line items when there is no items table."""
+    from vertiq.tables import find_item_text, item_tokens
+    assert item_tokens("Shirtx999,Tshirtx199ND; XYXX-TRUNK-L") == [("Shirt", 999.0), ("Tshirt", 199.0), ("XYXX-TRUNK-L", None)]
+    rnd = random.Random(8)
+    goods = ["Shirtx999", "Jeansx1499", "Tshirtx399", "Trouserx799", "Lowerx599"]
+    rows = [{"Bill": f"B{i:05d}", "Guest": f"G{rnd.randint(1, 120):04d}", "Date": f"2026-0{1 + i % 9}-{1 + i % 28:02d}",
+             "Amount": str(rnd.randint(300, 3000)), "Products": ",".join(rnd.sample(goods, rnd.randint(1, 3))),
+             "Remarks": f"note {i}"} for i in range(400)]
+    col, why = find_item_text(rows)
+    assert col == "Products" and "lists" in why[0]
+    with open(tmp_path / "bills.csv", "w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=list(rows[0]))
+        w.writeheader()
+        w.writerows(rows)
+    text = report.run({"records": {"file": "bills.csv"}, "noun": "bills"}, tmp_path)
+    assert "items written in one cell: column 'Products'" in text and "## Items bought together" in text
+
+
+def test_search_inputs_read_as_words():
+    from vertiq.menu import words
+    assert words("share:bill[@item=Jeans]@180d") == "share of bills including Jeans over 180 days"
+    assert words("since:bill[payment_mode=Cash]") == "time since the last bill with payment mode Cash"

vertiq-0.2.2/tests/test_segments.py

@@ -0,0 +1,58 @@
+"""The gate's segment check: a model that wins on average but is clearly worse for one segment is not promoted,
+and checking many segments does not block a model that is better everywhere."""
+import random
+
+from vertiq import harness, narrate, plugins
+
+
+def _data(harm: bool, seed: int = 3, n_entities: int = 1500, extra_dims: int = 0):
+    """Entities in segment A (85%) or B. The outcome follows x in A; in B it follows x too, unless `harm`, when it
+    follows -x. The baseline knows nothing in A and, under `harm`, is right in B. A model trained mostly on A
+    learns x, so under `harm` it wins on average and loses in B."""
+    rnd = random.Random(seed)
+    rows, y, keys, base, segs = [], [], [], [], []
+    for e in range(n_entities):
+        seg = "B" if rnd.random() < 0.15 else "A"
+        extra = {f"dim{d}": rnd.choice(["p", "q", "r"]) for d in range(extra_dims)}
+        for _cut in range(2):
+            x = rnd.gauss(0, 1)
+            sign = -1 if (harm and seg == "B") else 1
+            outcome = 1 if sign * x + rnd.gauss(0, 0.6) > 0 else 0
+            rows.append({"x": x})
+            y.append(outcome)
+            keys.append(f"E{e}")
+            base.append(-x if (harm and seg == "B") else rnd.random())
+            segs.append({"segment": seg, **extra})
+    return rows, y, keys, base, segs
+
+
+def _gate(harm: bool, **kw):
+    rows, y, keys, base, segs = _data(harm, **kw)
+    return harness.evaluate(rows, y, keys, [""] * len(y), base, plugins.learner("linear", "classify"), kind="classify",
+                            segments=segs)
+
+
+def test_a_model_that_harms_one_segment_is_not_promoted():
+    res = _gate(harm=True)
+    b = next(s for s in res["metrics"]["segments"] if s["label"] == "B")
+    assert res["metrics"]["auc"] > res["metrics"]["baseline_auc"]          # it wins on average ...
+    assert b["worse"] and res["status"] == "kept"                         # ... and loses in B, so it is kept
+    assert "segment B" in res["reason"]
+    text = narrate.gate({"status": res["status"], "metrics": res["metrics"], "reason": res["reason"],
+                         "task": "event", "target": "purchase", "window_days": 30})
+    assert "clearly worse than the baseline rule for segment B" in text
+
+
+def test_checking_many_segments_does_not_block_a_model_better_everywhere():
+    res = _gate(harm=False, extra_dims=6)
+    assert res["status"] == "trained"
+    assert len(res["metrics"]["segments"]) >= 10 and not any(s["worse"] for s in res["metrics"]["segments"])
+    text = narrate.gate({"status": "trained", "metrics": res["metrics"], "task": "event", "target": "purchase", "window_days": 30})
+    assert "not clearly worse than the baseline rule in any of them" in text
+
+
+def test_small_segments_are_not_judged():
+    rows, y, keys, base, segs = _data(harm=False, n_entities=1500)
+    segs = [dict(s, tiny="rare" if k in ("E1", "E2", "E3") else "") for s, k in zip(segs, keys)]
+    res = harness.evaluate(rows, y, keys, [""] * len(y), base, plugins.learner("linear", "classify"), kind="classify", segments=segs)
+    assert not any(s["dimension"] == "tiny" for s in res["metrics"]["segments"])

{vertiq-0.2.0 → vertiq-0.2.2}/vertiq/__init__.py

@@ -20,4 +20,4 @@ it likes.
   experiments  comparing message variants against each other and a control group
   verticals    per-vertical settings (windows, nouns, currency, tactics)
 """
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{vertiq-0.2.0 → vertiq-0.2.2}/vertiq/affinity.py

@@ -7,11 +7,14 @@ try next (cross-sell), and items people buy again on a cycle (refills).
   refills      items bought again on a steady cycle, and who is due now
 
 Lift = how many times more often two things go together than if choices were independent:
-1.0 is chance, 2.0 is twice as often. Only pairs seen at least MIN_PAIR times count, so a single
-big order never makes a pattern. Plain data in: [(customer id, bill id, when, item name)].
+1.0 is chance, 2.0 is twice as often. Only pairs seen at least MIN_PAIR times, and on at least 1 in 1,000
+bills (or customers) in large data, count, so a single big order or two rare items never make a pattern.
+Combos rank by how often the pair occurs times log2 of its lift: frequent strong pairs first, not the
+rarest. Plain data in: [(customer id, bill id, when, item name)].
 """
 from __future__ import annotations
 
+import math
 from collections import Counter, defaultdict
 from datetime import datetime, timedelta
 from itertools import combinations
@@ -56,8 +59,8 @@ def analyse(lines, min_pair: int = MIN_PAIR) -> dict:
         pair_cust.update(combinations(sorted(items)[:MAX_ITEMS_PER_BILL * 3], 2))
     result["top_items"] = [{"item": i, "customers": c, "share": round(100 * c / n_cust, 1)}
                            for i, c in item_cust.most_common(8)]
-    result["combos"] = _combos(pair_bills, item_bills, n_bills, min_pair)
-    lifts, cross = _cross_sell(pair_cust, item_cust, n_cust, bought, min_pair)
+    result["combos"] = _combos(pair_bills, item_bills, n_bills, max(min_pair, math.ceil(n_bills / 1000)))
+    lifts, cross = _cross_sell(pair_cust, item_cust, n_cust, bought, max(min_pair, math.ceil(n_cust / 1000)))
     result["cross_sell"], result["_lifts"] = cross, lifts
     result["_bought"] = {cid: {i: max(ds) for i, ds in items.items()} for cid, items in bought.items()}
     result["refills"], result["_cycles"] = _refills(bought)
@@ -75,7 +78,7 @@ def _combos(pair_bills: Counter, item_bills: Counter, n: int, min_pair: int = 5)
         out.append({"items": [a, b], "bills_together": together, "lift": round(lift, 2),
                     "a_then_b": round(100 * together / item_bills[a], 1),
                     "b_then_a": round(100 * together / item_bills[b], 1)})
-    out.sort(key=lambda c: (-c["lift"] * min(c["bills_together"], 50), c["items"]))
+    out.sort(key=lambda c: (-c["bills_together"] * math.log2(c["lift"]), c["items"]))
     return out[:10]