SearchLibrium 0.0.272__tar.gz → 0.0.274__tar.gz

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 (100) hide show
  1. {searchlibrium-0.0.272/src/SearchLibrium.egg-info → searchlibrium-0.0.274}/PKG-INFO +216 -3
  2. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/README.md +215 -2
  3. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/pyproject.toml +1 -1
  4. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/MixedLogit.py +7 -2
  5. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/__init__.py +12 -0
  6. searchlibrium-0.0.274/src/SearchLibrium/delphos.py +773 -0
  7. searchlibrium-0.0.274/src/SearchLibrium/delphos_q.py +605 -0
  8. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/larch_compat.py +5 -2
  9. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/latent_class.py +57 -15
  10. searchlibrium-0.0.274/src/SearchLibrium/lc_ml.py +777 -0
  11. searchlibrium-0.0.274/src/SearchLibrium/llm.py +1794 -0
  12. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/multinomial_logit.py +43 -1
  13. searchlibrium-0.0.274/src/SearchLibrium/route_choice.py +164 -0
  14. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/search.py +133 -34
  15. searchlibrium-0.0.274/src/SearchLibrium/spec_grammar.py +449 -0
  16. searchlibrium-0.0.274/src/SearchLibrium/version.txt +1 -0
  17. {searchlibrium-0.0.272 → searchlibrium-0.0.274/src/SearchLibrium.egg-info}/PKG-INFO +216 -3
  18. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/SOURCES.txt +13 -0
  19. searchlibrium-0.0.274/tests/test_delphos.py +392 -0
  20. searchlibrium-0.0.274/tests/test_delphos_q.py +169 -0
  21. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_larch_compat.py +4 -1
  22. searchlibrium-0.0.274/tests/test_lc_membership_intercept.py +78 -0
  23. searchlibrium-0.0.274/tests/test_lc_ml.py +132 -0
  24. searchlibrium-0.0.274/tests/test_llm_assistant.py +204 -0
  25. searchlibrium-0.0.274/tests/test_route_choice.py +76 -0
  26. searchlibrium-0.0.274/tests/test_spec_grammar.py +102 -0
  27. searchlibrium-0.0.272/src/SearchLibrium/version.txt +0 -1
  28. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/LICENSE +0 -0
  29. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/MANIFEST.in +0 -0
  30. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/setup.cfg +0 -0
  31. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/BEHier.py +0 -0
  32. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/Halton.py +0 -0
  33. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/MixedLogitGSE.py +0 -0
  34. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/Mode_Activity_Nested.py +0 -0
  35. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/RandomP.py +0 -0
  36. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/SEARCH_SM_MARIO.py +0 -0
  37. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/Two_Level_Nest.py +0 -0
  38. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/__main__.py +0 -0
  39. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/_choice_model.py +0 -0
  40. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/_device.py +0 -0
  41. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/abm.py +0 -0
  42. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/accessibility.py +0 -0
  43. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/banditsa.py +0 -0
  44. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/boxcox_functions.py +0 -0
  45. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/call_meta.py +0 -0
  46. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/constraints_builder.py +0 -0
  47. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/coupled_solver.py +0 -0
  48. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/data/Swissmetro_final.csv +0 -0
  49. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/data/TravelMode.csv +0 -0
  50. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/data/electricity.csv +0 -0
  51. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/destination_distances.py +0 -0
  52. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/harmony.py +0 -0
  53. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/hspbil.py +0 -0
  54. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/jax_utils.py +0 -0
  55. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/larch_models.py +0 -0
  56. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/latent_spec.py +0 -0
  57. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/lc_rail_guard.py +0 -0
  58. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/logistic_regression.py +0 -0
  59. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/main.py +0 -0
  60. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/main_debug.py +0 -0
  61. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/mdcev.py +0 -0
  62. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/mh_choice_estimator.py +0 -0
  63. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/misc.py +0 -0
  64. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/mixed_logit.py +0 -0
  65. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/mixed_nested.py +0 -0
  66. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/mixedrrm.py +0 -0
  67. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/multinomial_nested.py +0 -0
  68. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/multinomial_probit.py +0 -0
  69. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/numba_engine.py +0 -0
  70. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/numba_mxl.py +0 -0
  71. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/numba_rrm.py +0 -0
  72. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/ordered_logit.py +0 -0
  73. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/ordered_logit_mixed.py +0 -0
  74. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/predict.py +0 -0
  75. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/regularization.py +0 -0
  76. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/rrm.py +0 -0
  77. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/sample_data.py +0 -0
  78. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/sapbil.py +0 -0
  79. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/selection_models.py +0 -0
  80. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/setup.py +0 -0
  81. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/siman.py +0 -0
  82. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/skims.py +0 -0
  83. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/sparseea_agds.py +0 -0
  84. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/test_lc_de.py +0 -0
  85. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/test_mario_searches.py +0 -0
  86. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/test_sapbil_vs_banditsa.py +0 -0
  87. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/threshold.py +0 -0
  88. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium/zero_inflated_ordered_probit.py +0 -0
  89. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/dependency_links.txt +0 -0
  90. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/entry_points.txt +0 -0
  91. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/requires.txt +0 -0
  92. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/top_level.txt +0 -0
  93. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_destination_distances.py +0 -0
  94. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_jax_mask_equivalence.py +0 -0
  95. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_larch_integration.py +0 -0
  96. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_lc_smart_init.py +0 -0
  97. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_mh_choice_estimator.py +0 -0
  98. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_mxl_random_starts.py +0 -0
  99. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_per_alternative_random.py +0 -0
  100. {searchlibrium-0.0.272 → searchlibrium-0.0.274}/tests/test_zero_inflated_ordered_probit.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: SearchLibrium
3
- Version: 0.0.272
3
+ Version: 0.0.274
4
4
  Summary: Automated specification search for discrete choice models (logit, mixed logit, nested logit, RRM and more) using metaheuristic optimisation
5
5
  Author: Zeke Ahern, Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
6
6
  Maintainer-email: Zeke Ahern <z.ahern@qut.edu.au>
@@ -104,8 +104,10 @@ estimation of each candidate model.
104
104
  12. [Bundled datasets](#bundled-datasets)
105
105
  13. [CLI](#cli)
106
106
  14. [Differential Evolution warm start](#differential-evolution-warm-start)
107
- 15. [Troubleshooting & FAQ](#troubleshooting--faq)
108
- 16. [License](#license) / [Citation](#citation)
107
+ 15. [ML-guided latent classes](#ml-guided-latent-classes)
108
+ 16. [LLM-assisted experiment setup](#llm-assisted-experiment-setup)
109
+ 17. [Troubleshooting & FAQ](#troubleshooting--faq)
110
+ 18. [License](#license) / [Citation](#citation)
109
111
 
110
112
  ---
111
113
 
@@ -581,6 +583,217 @@ You can also pass `de_init=False` explicitly to guarantee it stays off.
581
583
 
582
584
  ---
583
585
 
586
+ ## ML-guided latent classes
587
+
588
+ `SearchLibrium.lc_ml` implements a practical answer to *"what is the class-membership
589
+ model, and what is the best choice model inside each class?"*:
590
+
591
+ 1. **Fit latent classes** with EM (`fit_latent_classes`). The posterior class
592
+ probabilities define behaviourally distinct segments without imposing a
593
+ membership equation.
594
+ 2. **Discover the membership model with ML** (`discover_membership`). An Extra
595
+ Trees classifier (or Random Forest) predicts class membership from
596
+ person/household covariates. You get cross-validated AUC / accuracy /
597
+ log-loss, permutation importance, a compact multinomial logit and
598
+ decision-tree rules.
599
+ 3. **Search inside each class** (`search_within_classes`). People are assigned
600
+ to their most likely class, and the ordinary SearchLibrium search runs
601
+ independently inside every class. Each class gets its own best MNL/MXL/RRM/...
602
+ specification.
603
+ 4. **Or search jointly** (`search_joint_latent_class`). The ML-discovered
604
+ membership covariates seed a latent-class specification search in which
605
+ SearchLibrium also searches the per-class utility specifications.
606
+
607
+ ```python
608
+ from SearchLibrium import (
609
+ fit_latent_classes, discover_membership, search_within_classes,
610
+ )
611
+
612
+ # long_df: balanced long format, one row per alternative per choice task
613
+ # person_frame: one row per person/panel, indexed by the panel id
614
+ lc = fit_latent_classes(
615
+ long_df,
616
+ utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
617
+ n_classes=2, n_init=2, maxiter=120,
618
+ )
619
+
620
+ disc = discover_membership(
621
+ lc, person_frame,
622
+ candidate_vars=["INCOME", "CARS", "AGE", "LICENCE", "WORKSTATUS"],
623
+ top_k=5,
624
+ )
625
+ print(disc.summary()) # CV scores + importance + decision rules
626
+ print(disc.selected_vars) # the discovered membership covariates
627
+
628
+ # Assign each person to a class, then run the usual search per class.
629
+ assignment = dict(zip(lc.panel_ids, disc.hard_labels))
630
+ per_class = search_within_classes(
631
+ long_df, assignment,
632
+ utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
633
+ models=["multinomial"], criterions=[("bic", -1)],
634
+ ctrl=(300, 0.01, 15, 10),
635
+ )
636
+ for cls, best in per_class.items():
637
+ print(cls, best["asvars"], best["bic"])
638
+ ```
639
+
640
+ Notes:
641
+
642
+ - Class labels are estimated, so `discover_membership` scores are
643
+ *pseudo-label* scores unless you fit the LC model on a training split and
644
+ evaluate the classifier on held-out people.
645
+ - `search_within_classes` uses hard assignments; `search_joint_latent_class`
646
+ keeps the soft membership equation.
647
+ - Use a held-out choice log-likelihood to compare the pooled and segmented
648
+ models; per-class BICs are not directly comparable to a pooled BIC.
649
+ - A complete HHTS mode-choice example, including pooled-vs-segmented test
650
+ log-likelihood and soft-membership prediction, is in
651
+ `benchmarks/lc_ml_hhts.py`:
652
+
653
+ ```bash
654
+ python benchmarks/lc_ml_hhts.py --classes 2 --ctrl 300,0.01,15,10
655
+ ```
656
+
657
+ `membership_intercept=True` on `LatentClassMixedLogit` (or `'_inter'` in a
658
+ membership spec) adds the class-share constant to the membership equation.
659
+
660
+ ---
661
+
662
+ ## LLM-assisted experiment setup
663
+
664
+ Yes — the package ships an optional, provider-agnostic experiment assistant.
665
+ It drives the *setup* conversation (data path → response → model classes →
666
+ variable pruning → constraint hierarchy → objective), then runs the ordinary
667
+ SearchLibrium search, diagnoses the result, and can revise the constraints for
668
+ another round.
669
+
670
+ The LLM is **not required**. With no API key it uses a deterministic offline
671
+ planner. With a provider configured it receives only the schema and summary
672
+ statistics by default — never your rows.
673
+
674
+ ```python
675
+ from SearchLibrium import ExperimentAssistant, LLMConfig
676
+
677
+ exp = ExperimentAssistant(
678
+ data=r"C:\data\mode_choice.csv",
679
+ response="choice", # the count/response column
680
+ config=LLMConfig.from_env(), # offline if nothing is configured
681
+ )
682
+
683
+ print(exp.profile().summary()) # file shape, dtypes, missingness
684
+ print(exp.roles().summary()) # choice / alt / ids / AS / IS
685
+
686
+ plan = exp.plan() # models, variables, constraints,
687
+ # objectives, open questions
688
+ print(plan.summary())
689
+
690
+ best = exp.run(plan) # ordinary, full SearchLibrium search
691
+ issues = exp.diagnose(best) # non-convergence, singularity,
692
+ # class collapse, insignificance, ...
693
+ print(issues)
694
+ plan = exp.revise(issues) # apply suggested constraints
695
+ best = exp.run(plan) # retry with the revised plan
696
+ ```
697
+
698
+ Interactive mode asks the questions directly:
699
+
700
+ ```python
701
+ exp = ExperimentAssistant(interactive=True)
702
+ exp.chat()
703
+ ```
704
+
705
+ Provider configuration is via `LLMConfig` or standard environment variables:
706
+
707
+ | Provider | Configuration |
708
+ | --- | --- |
709
+ | OpenAI / OpenAI-compatible | `OPENAI_API_KEY`, or `LLMConfig(provider="openai", model="gpt-4o-mini")` |
710
+ | Anthropic | `ANTHROPIC_API_KEY`, or `LLMConfig(provider="anthropic")` |
711
+ | Ollama (local) | `OLLAMA_HOST`, or `LLMConfig(provider="ollama")` |
712
+ | Downloaded GGUF (local) | `LLMConfig(provider="local", model_path=r"C:\models\model.gguf")` |
713
+ | Custom endpoint | `LLMConfig(provider="custom", base_url=..., api_key=...)` |
714
+ | Offline (default) | no configuration; deterministic planner |
715
+
716
+ ### Using a free downloaded local LLM
717
+
718
+ The simplest route is **Ollama** (free, no API key):
719
+
720
+ ```bash
721
+ ollama pull qwen2.5:7b-instruct
722
+ ```
723
+
724
+ ```python
725
+ from SearchLibrium import ExperimentAssistant, LLMConfig
726
+
727
+ exp = ExperimentAssistant(
728
+ data=r"C:\data\mode_choice.csv",
729
+ response="choice",
730
+ config=LLMConfig(provider="ollama", model="qwen2.5:7b-instruct"),
731
+ )
732
+ ```
733
+
734
+ If you already have a **GGUF file** (e.g. from Hugging Face, LM Studio, or
735
+ TheBloke), use the direct local backend:
736
+
737
+ ```bash
738
+ pip install llama-cpp-python
739
+ ```
740
+
741
+ ```python
742
+ from SearchLibrium import ExperimentAssistant, LLMConfig, find_local_models
743
+
744
+ # Optional: search common model folders for *.gguf files.
745
+ print(find_local_models(r"C:\models"))
746
+
747
+ exp = ExperimentAssistant(
748
+ data=r"C:\data\mode_choice.csv",
749
+ response="choice",
750
+ config=LLMConfig(
751
+ provider="local",
752
+ model_path=r"C:\models\Qwen2.5-7B-Instruct-Q4_K_M.gguf",
753
+ n_ctx=8192,
754
+ n_gpu_layers=-1, # offload all layers when the build supports it
755
+ ),
756
+ )
757
+ ```
758
+
759
+ LM Studio is also free and exposes an OpenAI-compatible local server:
760
+
761
+ ```python
762
+ LLMConfig(
763
+ provider="custom",
764
+ base_url="http://localhost:1234/v1",
765
+ api_key="lm-studio",
766
+ model="local-model",
767
+ )
768
+ ```
769
+
770
+ Suggested small models for experiment planning: **Qwen2.5-7B-Instruct**,
771
+ **Llama-3.1-8B-Instruct**, **Mistral-7B-Instruct**, or **Phi-3.5-mini**.
772
+ A 4-bit quantised 7B/8B model runs on a normal laptop CPU (slowly) or a
773
+ reasonably sized GPU. Once the model is downloaded, setup and planning are
774
+ fully offline; only the schema/summary is sent to the model.
775
+
776
+ Useful details:
777
+
778
+ - `ExperimentAssistant.plan(answers={...})` accepts explicit overrides such as
779
+ `models`, `objectives`, `p_val`, `allow_random`, `force_include`,
780
+ `force_exclude`, `mutually_exclusive` and `min_behavioral`.
781
+ - `diagnose` returns machine-readable `Issue` objects with a `patch` that
782
+ `revise` can apply (e.g. add a mutual-exclusion constraint, increase
783
+ `maxiter`, reduce the number of latent classes).
784
+ - `run_loop(max_rounds=3)` automates run → diagnose → revise → re-run.
785
+ - `send_data=False` (the default) keeps raw values local; only column names,
786
+ dtypes and summary statistics are sent to a remote provider.
787
+ - `read_table` supports CSV/TSV, Parquet, pickle, JSON, Excel and Stata.
788
+
789
+ A zero-configuration demo on the bundled travel-mode dataset:
790
+
791
+ ```bash
792
+ python benchmarks/llm_setup_demo.py
793
+ ```
794
+
795
+ ---
796
+
584
797
  ## Troubleshooting & FAQ
585
798
 
586
799
  **A model reports `converged: False`.**
@@ -37,8 +37,10 @@ estimation of each candidate model.
37
37
  12. [Bundled datasets](#bundled-datasets)
38
38
  13. [CLI](#cli)
39
39
  14. [Differential Evolution warm start](#differential-evolution-warm-start)
40
- 15. [Troubleshooting & FAQ](#troubleshooting--faq)
41
- 16. [License](#license) / [Citation](#citation)
40
+ 15. [ML-guided latent classes](#ml-guided-latent-classes)
41
+ 16. [LLM-assisted experiment setup](#llm-assisted-experiment-setup)
42
+ 17. [Troubleshooting & FAQ](#troubleshooting--faq)
43
+ 18. [License](#license) / [Citation](#citation)
42
44
 
43
45
  ---
44
46
 
@@ -514,6 +516,217 @@ You can also pass `de_init=False` explicitly to guarantee it stays off.
514
516
 
515
517
  ---
516
518
 
519
+ ## ML-guided latent classes
520
+
521
+ `SearchLibrium.lc_ml` implements a practical answer to *"what is the class-membership
522
+ model, and what is the best choice model inside each class?"*:
523
+
524
+ 1. **Fit latent classes** with EM (`fit_latent_classes`). The posterior class
525
+ probabilities define behaviourally distinct segments without imposing a
526
+ membership equation.
527
+ 2. **Discover the membership model with ML** (`discover_membership`). An Extra
528
+ Trees classifier (or Random Forest) predicts class membership from
529
+ person/household covariates. You get cross-validated AUC / accuracy /
530
+ log-loss, permutation importance, a compact multinomial logit and
531
+ decision-tree rules.
532
+ 3. **Search inside each class** (`search_within_classes`). People are assigned
533
+ to their most likely class, and the ordinary SearchLibrium search runs
534
+ independently inside every class. Each class gets its own best MNL/MXL/RRM/...
535
+ specification.
536
+ 4. **Or search jointly** (`search_joint_latent_class`). The ML-discovered
537
+ membership covariates seed a latent-class specification search in which
538
+ SearchLibrium also searches the per-class utility specifications.
539
+
540
+ ```python
541
+ from SearchLibrium import (
542
+ fit_latent_classes, discover_membership, search_within_classes,
543
+ )
544
+
545
+ # long_df: balanced long format, one row per alternative per choice task
546
+ # person_frame: one row per person/panel, indexed by the panel id
547
+ lc = fit_latent_classes(
548
+ long_df,
549
+ utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
550
+ n_classes=2, n_init=2, maxiter=120,
551
+ )
552
+
553
+ disc = discover_membership(
554
+ lc, person_frame,
555
+ candidate_vars=["INCOME", "CARS", "AGE", "LICENCE", "WORKSTATUS"],
556
+ top_k=5,
557
+ )
558
+ print(disc.summary()) # CV scores + importance + decision rules
559
+ print(disc.selected_vars) # the discovered membership covariates
560
+
561
+ # Assign each person to a class, then run the usual search per class.
562
+ assignment = dict(zip(lc.panel_ids, disc.hard_labels))
563
+ per_class = search_within_classes(
564
+ long_df, assignment,
565
+ utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
566
+ models=["multinomial"], criterions=[("bic", -1)],
567
+ ctrl=(300, 0.01, 15, 10),
568
+ )
569
+ for cls, best in per_class.items():
570
+ print(cls, best["asvars"], best["bic"])
571
+ ```
572
+
573
+ Notes:
574
+
575
+ - Class labels are estimated, so `discover_membership` scores are
576
+ *pseudo-label* scores unless you fit the LC model on a training split and
577
+ evaluate the classifier on held-out people.
578
+ - `search_within_classes` uses hard assignments; `search_joint_latent_class`
579
+ keeps the soft membership equation.
580
+ - Use a held-out choice log-likelihood to compare the pooled and segmented
581
+ models; per-class BICs are not directly comparable to a pooled BIC.
582
+ - A complete HHTS mode-choice example, including pooled-vs-segmented test
583
+ log-likelihood and soft-membership prediction, is in
584
+ `benchmarks/lc_ml_hhts.py`:
585
+
586
+ ```bash
587
+ python benchmarks/lc_ml_hhts.py --classes 2 --ctrl 300,0.01,15,10
588
+ ```
589
+
590
+ `membership_intercept=True` on `LatentClassMixedLogit` (or `'_inter'` in a
591
+ membership spec) adds the class-share constant to the membership equation.
592
+
593
+ ---
594
+
595
+ ## LLM-assisted experiment setup
596
+
597
+ Yes — the package ships an optional, provider-agnostic experiment assistant.
598
+ It drives the *setup* conversation (data path → response → model classes →
599
+ variable pruning → constraint hierarchy → objective), then runs the ordinary
600
+ SearchLibrium search, diagnoses the result, and can revise the constraints for
601
+ another round.
602
+
603
+ The LLM is **not required**. With no API key it uses a deterministic offline
604
+ planner. With a provider configured it receives only the schema and summary
605
+ statistics by default — never your rows.
606
+
607
+ ```python
608
+ from SearchLibrium import ExperimentAssistant, LLMConfig
609
+
610
+ exp = ExperimentAssistant(
611
+ data=r"C:\data\mode_choice.csv",
612
+ response="choice", # the count/response column
613
+ config=LLMConfig.from_env(), # offline if nothing is configured
614
+ )
615
+
616
+ print(exp.profile().summary()) # file shape, dtypes, missingness
617
+ print(exp.roles().summary()) # choice / alt / ids / AS / IS
618
+
619
+ plan = exp.plan() # models, variables, constraints,
620
+ # objectives, open questions
621
+ print(plan.summary())
622
+
623
+ best = exp.run(plan) # ordinary, full SearchLibrium search
624
+ issues = exp.diagnose(best) # non-convergence, singularity,
625
+ # class collapse, insignificance, ...
626
+ print(issues)
627
+ plan = exp.revise(issues) # apply suggested constraints
628
+ best = exp.run(plan) # retry with the revised plan
629
+ ```
630
+
631
+ Interactive mode asks the questions directly:
632
+
633
+ ```python
634
+ exp = ExperimentAssistant(interactive=True)
635
+ exp.chat()
636
+ ```
637
+
638
+ Provider configuration is via `LLMConfig` or standard environment variables:
639
+
640
+ | Provider | Configuration |
641
+ | --- | --- |
642
+ | OpenAI / OpenAI-compatible | `OPENAI_API_KEY`, or `LLMConfig(provider="openai", model="gpt-4o-mini")` |
643
+ | Anthropic | `ANTHROPIC_API_KEY`, or `LLMConfig(provider="anthropic")` |
644
+ | Ollama (local) | `OLLAMA_HOST`, or `LLMConfig(provider="ollama")` |
645
+ | Downloaded GGUF (local) | `LLMConfig(provider="local", model_path=r"C:\models\model.gguf")` |
646
+ | Custom endpoint | `LLMConfig(provider="custom", base_url=..., api_key=...)` |
647
+ | Offline (default) | no configuration; deterministic planner |
648
+
649
+ ### Using a free downloaded local LLM
650
+
651
+ The simplest route is **Ollama** (free, no API key):
652
+
653
+ ```bash
654
+ ollama pull qwen2.5:7b-instruct
655
+ ```
656
+
657
+ ```python
658
+ from SearchLibrium import ExperimentAssistant, LLMConfig
659
+
660
+ exp = ExperimentAssistant(
661
+ data=r"C:\data\mode_choice.csv",
662
+ response="choice",
663
+ config=LLMConfig(provider="ollama", model="qwen2.5:7b-instruct"),
664
+ )
665
+ ```
666
+
667
+ If you already have a **GGUF file** (e.g. from Hugging Face, LM Studio, or
668
+ TheBloke), use the direct local backend:
669
+
670
+ ```bash
671
+ pip install llama-cpp-python
672
+ ```
673
+
674
+ ```python
675
+ from SearchLibrium import ExperimentAssistant, LLMConfig, find_local_models
676
+
677
+ # Optional: search common model folders for *.gguf files.
678
+ print(find_local_models(r"C:\models"))
679
+
680
+ exp = ExperimentAssistant(
681
+ data=r"C:\data\mode_choice.csv",
682
+ response="choice",
683
+ config=LLMConfig(
684
+ provider="local",
685
+ model_path=r"C:\models\Qwen2.5-7B-Instruct-Q4_K_M.gguf",
686
+ n_ctx=8192,
687
+ n_gpu_layers=-1, # offload all layers when the build supports it
688
+ ),
689
+ )
690
+ ```
691
+
692
+ LM Studio is also free and exposes an OpenAI-compatible local server:
693
+
694
+ ```python
695
+ LLMConfig(
696
+ provider="custom",
697
+ base_url="http://localhost:1234/v1",
698
+ api_key="lm-studio",
699
+ model="local-model",
700
+ )
701
+ ```
702
+
703
+ Suggested small models for experiment planning: **Qwen2.5-7B-Instruct**,
704
+ **Llama-3.1-8B-Instruct**, **Mistral-7B-Instruct**, or **Phi-3.5-mini**.
705
+ A 4-bit quantised 7B/8B model runs on a normal laptop CPU (slowly) or a
706
+ reasonably sized GPU. Once the model is downloaded, setup and planning are
707
+ fully offline; only the schema/summary is sent to the model.
708
+
709
+ Useful details:
710
+
711
+ - `ExperimentAssistant.plan(answers={...})` accepts explicit overrides such as
712
+ `models`, `objectives`, `p_val`, `allow_random`, `force_include`,
713
+ `force_exclude`, `mutually_exclusive` and `min_behavioral`.
714
+ - `diagnose` returns machine-readable `Issue` objects with a `patch` that
715
+ `revise` can apply (e.g. add a mutual-exclusion constraint, increase
716
+ `maxiter`, reduce the number of latent classes).
717
+ - `run_loop(max_rounds=3)` automates run → diagnose → revise → re-run.
718
+ - `send_data=False` (the default) keeps raw values local; only column names,
719
+ dtypes and summary statistics are sent to a remote provider.
720
+ - `read_table` supports CSV/TSV, Parquet, pickle, JSON, Excel and Stata.
721
+
722
+ A zero-configuration demo on the bundled travel-mode dataset:
723
+
724
+ ```bash
725
+ python benchmarks/llm_setup_demo.py
726
+ ```
727
+
728
+ ---
729
+
517
730
  ## Troubleshooting & FAQ
518
731
 
519
732
  **A model reports `converged: False`.**
@@ -132,7 +132,7 @@ Documentation = "https://pypi.org/project/SearchLibrium/"
132
132
  realpython = "SearchLibrium.__main__:main"
133
133
 
134
134
  [tool.bumpver]
135
- current_version = "0.0.272"
135
+ current_version = "0.0.274"
136
136
  version_pattern = "MAJOR.MINOR.PATCH"
137
137
  commit_message = "[skip ci] Bump version {old_version} -> {new_version}"
138
138
  commit = true
@@ -339,8 +339,13 @@ class MixedLogit(DiscreteChoiceModel):
339
339
  self._person_batch_active = False
340
340
  self.draw_seed = int(draw_seed)
341
341
  self.halton_opts = dict(halton_opts or {})
342
- if self.person_batch_size is not None:
343
- self.halton_opts.setdefault("seed", self.draw_seed)
342
+ # Always seed the draw stream. Draws default to scrambled Sobol,
343
+ # whose scramble is fresh entropy whenever the seed is None, so an
344
+ # identical specification fitted in two processes returned different
345
+ # log-likelihoods (TravelMode, 200 draws: -193.55 vs -193.48). A
346
+ # search that is trained on such a reward is fitting the draw noise.
347
+ # ``draw_seed`` defaults to 0, so this is stable for existing callers.
348
+ self.halton_opts.setdefault("seed", self.draw_seed)
344
349
 
345
350
  # CRITICAL FIX: Recreate draws_generator with proper halton_opts AND rvdist
346
351
  # The __init__ creates it with halton_opts=None, but setup() gets the actual options
@@ -170,6 +170,13 @@ _IMPORT_GROUPS = [
170
170
  ('zero_inflated_ordered_probit', ['ZeroInflatedOrderedProbit',
171
171
  'ZeroInflatedProbit']),
172
172
  ('latent_class', ['LatentClassMixedLogit']),
173
+ ('lc_ml', ['MembershipDiscovery', 'discover_membership',
174
+ 'fit_latent_classes', 'search_within_classes',
175
+ 'search_joint_latent_class']),
176
+ ('llm', ['ExperimentAssistant', 'LLMConfig', 'LLMClient', 'LLMUnavailable',
177
+ 'DataProfile', 'DataRoles', 'ExperimentPlan', 'Issue',
178
+ 'read_table', 'profile_frame', 'infer_data_roles',
179
+ 'find_local_models']),
173
180
  ('lc_rail_guard', ['lc_result_rail']),
174
181
  ('latent_spec', ['vip_table', 'near_unidentified_report', 'align_classes',
175
182
  'propose_class_params_spec']),
@@ -239,6 +246,11 @@ __all__ = [
239
246
  "ZeroInflatedOrderedProbit", "ZeroInflatedProbit",
240
247
  "LatentClassMixedLogit", "vip_table", "near_unidentified_report",
241
248
  "align_classes", "propose_class_params_spec", "MDCEVFitResult", "MDCEVModel", "MultinomialProbit",
249
+ "MembershipDiscovery", "discover_membership", "fit_latent_classes",
250
+ "search_within_classes", "search_joint_latent_class",
251
+ "ExperimentAssistant", "LLMConfig", "LLMClient", "LLMUnavailable",
252
+ "DataProfile", "DataRoles", "ExperimentPlan", "Issue",
253
+ "read_table", "profile_frame", "infer_data_roles", "find_local_models",
242
254
  "MixedLogitGSE", "RandomParameters", "ConstraintBuilder", "create_constraints",
243
255
  "Parameters", "misc",
244
256
  "ChoiceEstimate", "ChoiceEstimateResult", "ChoiceSetFrame",