Prepare ULTK for release: fix packaging, source bugs, and tests

## Packaging

- Bump version from invalid `0.0.1c` to PEP 440-compliant `0.1.0`
- Add `tqdm` to runtime dependencies (imported by `effcomm/optimization.py`
  and `language/sampling.py` but was missing from `pyproject.toml`)
- Move dev-only tools (`mypy`, `pytest`, `scipy-stubs`) out of `dependencies`
  and into a `[dependency-groups] dev` section so they are not installed by
  end-users of the library
- Delete `setup.py` legacy shim, which conflicted with the `uv_build` backend

## Source-code bug fixes

- `language/sampling.py` `all_meanings()`: fix `Meaning` construction to use
  the tuple-based API (boolean values indexed parallel to `universe.referents`)
  instead of passing a raw referent subset-tuple, which broke after the
  `FrozenDict`→tuple refactor
- `language/language.py` `Expression` default: replace
  `Meaning(FrozenDict(), ...)` with `Meaning(tuple(), ...)` and remove the
  now-unused `FrozenDict` import
- `language/grammar/grammar.py`:
  - `complement()`: replace the non-existent `.referents` attribute with
    `tuple(not val for val in self.meaning.mapping)`
  - `draw_referent()`: replace `.referents` attribute access with correct
    `zip(universe.referents, mapping)` iteration

## Test fixes

- `test_language.py`: replace all `FrozenDict({ref: bool})` `Meaning`
  constructors with `tuple(bool for ref in ...)`, fix `isAnimal` helper to
  iterate via `zip(universe.referents, mapping)` instead of dict `.items()`,
  rename duplicate `test_exp_subset` method to `test_exp_can_express_positive`
  so both positive and negative can_express tests actually run, remove unused
  `FrozenDict` import
- `test_grammar.py`: fix `goal_meaning` to use the tuple-based `Meaning` API

## CI workflows

- Replace `actions/setup-python` + `pip` with `astral-sh/setup-uv@v5` + `uv`
  in all three workflows (`test.yml`, `docs.yml`, `pypi-publish.yml`)
- `test.yml`: `uv sync --group dev` + `uv run pytest src/tests/`
- `docs.yml`: `uv sync` + `uv run pdoc ...`; upgrade to Python 3.13
- `pypi-publish.yml`: replace `python -m build` with `uv build`

## Documentation

- `README.md`: update install instructions to recommend `uv sync`, note
  Python 3.13 requirement, update testing section to use `uv run pytest`
- `CLAUDE.md`: update commands to use `uv sync --group dev` and
  `uv run pytest src/tests/`

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: shanest

.github/workflows/docs.yml

@@ -19,16 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v5
 
-      # ADJUST THIS: install all dependencies (including pdoc)
-      - run: pip install -e .
-      - run: pip install pdoc
-      # ADJUST THIS: build your documentation into docs/.
-      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
-      - run: pdoc src/ultk -d google --math -o ./docs
+      - run: uv sync
+      - run: uv run pdoc src/ultk -d google --math -o ./docs
 
       - uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/pypi-publish.yml

@@ -13,15 +13,10 @@ jobs:
       id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     steps:
     # retrieve your distributions here
-    - uses: actions/checkout@v3
-    - uses: actions/setup-python@v4
-      with:
-          python-version: '3.11'
-    - name: Install package 
-      run:  pip install --upgrade build
-            pip install -e .
+    - uses: actions/checkout@v4
+    - uses: astral-sh/setup-uv@v5
     - name: Build dist
-      run:  python -m build
+      run: uv build
     - name: Publish package distributions to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       with:

.github/workflows/test.yml

@@ -6,14 +6,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.11'
-      - name: Install package 
-        run: pip install -e .
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --group dev
       - name: Test with pytest
-        run: |
-          pip install pytest 
-          pytest
+        run: uv run pytest src/tests/

CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ULTK (Unnatural Language ToolKit) is a Python library for computational semantic typology research — specifically for "efficient communication" analyses that explain natural language structure in terms of competing pressures: minimizing cognitive complexity vs. maximizing communicative accuracy.
+
+## Commands
+
+```bash
+# Install all dependencies (including dev group for tests)
+uv sync --group dev
+
+# Run all tests
+uv run pytest src/tests/
+
+# Run a single test file
+uv run pytest src/tests/test_language.py
+
+# Run a single test by name
+uv run pytest src/tests/test_language.py::TestLanguage::test_name
+
+# Format code (Black is enforced via CI on PRs)
+black src/
+```
+
+Tests are discovered automatically by pytest from `src/tests/`. The CI workflow runs `uv run pytest src/tests/` from the repo root.
+
+## Architecture
+
+### Two Main Modules
+
+**`ultk.language`** — Core data structures for semantic representations:
+- `semantics.py`: `Referent` (immutable semantic object), `Universe` (collection of Referents with a prior distribution), `Meaning` (mapping from Universe to arbitrary type T — e.g., booleans for truth values)
+- `language.py`: `Expression` (form + meaning pair), `Language` (frozenset of Expressions sharing a Universe). Helper `aggregate_expression_complexity()` bridges language and effcomm.
+- `sampling.py`: Generators for all meanings, expressions, and languages from a universe — used to enumerate the full hypothesis space.
+- `grammar/`: A probabilistic context-free grammar (PCFG) framework for building expressions as programs in a Language of Thought. `grammar.py` defines `Rule` and `Grammar`/`GrammaticalExpression`; `likelihood.py` provides scoring functions; `inference.py` handles MDL/Bayesian inference.
+
+**`ultk.effcomm`** — Efficient communication analysis tools:
+- `agent.py`: RSA (Rational Speech Act) agents — `LiteralSpeaker`, `LiteralListener`, `PragmaticSpeaker`, `PragmaticListener` — represented as weight matrices.
+- `informativity.py`: `informativity()` and `communicative_success()` — compute how well a language supports communication (vectorized as `diag(prior) @ S @ R ⊙ U`).
+- `tradeoff.py`: Pareto front computation (`pareto_optimal_languages`, `non_dominated_2d`, `dominates`) for simplicity/informativeness trade-off analysis.
+- `optimization.py`: `EvolutionaryOptimizer` — iterative algorithm to approximate the Pareto frontier via mutations (`AddExpression`, `RemoveExpression`).
+- `sampling.py`: `get_hypothetical_variants()` — generates null-hypothesis languages by permuting speaker weight matrices.
+- `analysis.py`: Aggregation utilities for building results DataFrames.
+
+**`ultk.util`**:
+- `frozendict.py`: `FrozenDict` — an immutable dict used extensively as keys in frozen dataclasses.
+- `io.py`: I/O helpers.
+
+### Key Design Patterns
+
+- Core objects (`Universe`, `Meaning`, `Expression`) are **frozen/immutable** (`@dataclass(frozen=True)` or manual `_frozen` flag), enabling hashing and use as dict keys.
+- `Meaning` stores its mapping as a `tuple[T, ...]` indexed parallel to `Universe.referents`, with `_ref_to_idx` for O(1) lookup. Access via `meaning[referent]`.
+- `Language` stores expressions as a `frozenset` — order-independent, hashable.
+- Grammar rules are defined via Python type annotations; `Rule.from_callable()` introspects function signatures to build rules automatically.
+
+### Examples
+
+`src/examples/` contains complete worked analyses:
+- `indefinites/` — efficient communication analysis of indefinite pronouns
+- `modals/` — semantic universals for modals
+- `learn_quant/` — quantifier learning

README.md

@@ -9,13 +9,21 @@ Read the [documentation](https://clmbr.shane.st/ultk).
 
 ## Installing ULTK
 
-First, set up a virtual environment (e.g. via [miniconda](https://docs.conda.io/en/latest/miniconda.html), `conda create -n ultk python=3.11`, and `conda activate ultk`).
+ULTK requires Python 3.13+. We recommend using [uv](https://docs.astral.sh/uv/) to manage dependencies.
 
 1. Download or clone this repository and navigate to the root folder.
 
-2. Install ULTK (We recommend doing this inside a virtual environment)
+2. Install ULTK and all dependencies:
 
-    `pip install -e .`
+    ```
+    uv sync
+    ```
+
+    Alternatively, if you prefer pip inside an activated virtual environment:
+
+    ```
+    pip install -e .
+    ```
 
 ## Getting started
 
@@ -33,7 +41,13 @@ The source code is available on github [here](https://github.com/CLMBRs/ultk).
 
 ## Testing
 
-Unit tests are written in [pytest](https://docs.pytest.org/en/7.3.x/) and executed via running `pytest` in the `src/tests` folder.
+Unit tests are written in [pytest](https://docs.pytest.org/en/7.3.x/) and executed via:
+
+```
+uv run pytest src/tests/
+```
+
+Or, if inside an activated virtual environment: `pytest src/tests/`.
 
 ## References
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ultk"
-version = "0.0.1c"
+version = "0.1.0"
 authors = [
   { name="Chris Haberland", email="haberc@uw.edu"},
   { name="Nathaniel Imel", email="nimel@uci.edu"},
@@ -16,18 +16,19 @@ classifiers = [
 ]
 license = {file = "LICENSE.txt"}
 dependencies = [
-    "mypy",
     "numpy",
     "nltk",
     "pyyaml",
     "pandas",
     "plotnine",
     "pathos",
-    "pytest",
     "scipy>=1.7.3",
-    "scipy-stubs[scipy]>=1.16.3.3",
+    "tqdm",
 ]
 
+[dependency-groups]
+dev = ["mypy", "pytest", "scipy-stubs[scipy]>=1.16.3.3"]
+
 [project.urls]
 "Homepage" = "https://clmbr.shane.st/ultk"
 "Bug Tracker" = "https://github.com/CLMBRs/ultk/issues"

setup.py

@@ -25,7 +25,7 @@ def test_meaning(self):
         parsed_expression = TestGrammar.grammar.parse(TestGrammar.geq2_expr_str)
         expr_meaning = parsed_expression.evaluate(TestGrammar.universe)
         goal_meaning = Meaning(
-            {referent: referent.num > 2 for referent in TestGrammar.referents},
+            tuple(referent.num > 2 for referent in TestGrammar.referents),
             TestGrammar.universe,
         )
         assert expr_meaning == goal_meaning

src/tests/test_grammar.py

@@ -4,7 +4,6 @@
 
 from ultk.language.language import Expression, Language
 from ultk.language.semantics import Referent, Universe, Meaning
-from ultk.util.frozendict import FrozenDict
 
 
 class TestLanguage:
@@ -27,35 +26,35 @@ class TestLanguage:
     dog = Expression(
         form="dog",
         meaning=Meaning(
-            mapping=FrozenDict({ref: ref.name == "dog" for ref in uni_refs}),
+            mapping=tuple(ref.name == "dog" for ref in uni_refs),
             universe=uni,
         ),
     )
     cat = Expression(
         form="cat",
         meaning=Meaning(
-            mapping=FrozenDict({ref: ref.name == "cat" for ref in uni_refs}),
+            mapping=tuple(ref.name == "cat" for ref in uni_refs),
             universe=uni,
         ),
     )
     tree = Expression(
         form="tree",
         meaning=Meaning(
-            mapping=FrozenDict({ref: ref.name == "tree" for ref in uni_refs}),
+            mapping=tuple(ref.name == "tree" for ref in uni_refs),
             universe=uni,
         ),
     )
     shroom = Expression(
         form="shroom",
         meaning=Meaning(
-            mapping=FrozenDict({ref: ref.name == "shroom" for ref in uni_refs}),
+            mapping=tuple(ref.name == "shroom" for ref in uni_refs),
             universe=uni,
         ),
     )
     bird = Expression(
         form="bird",
         meaning=Meaning(
-            mapping=FrozenDict({ref: ref.name == "bird" for ref in uni_refs}),
+            mapping=tuple(ref.name == "bird" for ref in uni_refs),
             universe=uni,
         ),
     )
@@ -65,7 +64,7 @@ class TestLanguage:
     lang_subset_expr = Language(expressions=tuple([dog, cat, tree]))
     lang_of_different_order = Language(expressions=tuple([dog, cat, shroom, tree]))
 
-    def test_exp_subset(self):
+    def test_exp_can_express_positive(self):
         assert TestLanguage.dog.can_express(Referent("dog", {"phylum": "animal"}))
 
     def test_exp_subset(self):
@@ -83,11 +82,9 @@ def test_language_universe_check(self):
                     Expression(
                         form="dog",
                         meaning=Meaning(
-                            mapping=FrozenDict(
-                                {
-                                    ref: ref.name == "dog"
-                                    for ref in TestLanguage.uni.referents
-                                }
+                            mapping=tuple(
+                                ref.name == "dog"
+                                for ref in TestLanguage.uni.referents
                             ),
                             universe=TestLanguage.uni2,
                         ),
@@ -98,8 +95,8 @@ def test_language_universe_check(self):
     def test_language_degree(self):
         def isAnimal(exp: Expression) -> bool:
             print("checking phylum of " + str(exp))
-            for k, v in exp.meaning.mapping.items():
-                if v and k.phylum != "animal":
+            for ref, v in zip(exp.meaning.universe.referents, exp.meaning.mapping):
+                if v and ref.phylum != "animal":
                     return False
             return True
 

src/tests/test_language.py

@@ -168,15 +168,16 @@ def complement(self) -> Meaning:
         the expression evaluates to False."""
 
         return Meaning(
-            tuple(set(self.meaning.universe.referents) - set(self.meaning.referents)),
+            tuple(not val for val in self.meaning.mapping),
             self.meaning.universe,
         )
 
     def draw_referent(self, complement=False):
         """Get a random referent from the meaning's referents."""
+        universe_refs = self.meaning.universe.referents
         if complement:
-            return random.choice(list(self.complement().referents))
-        return random.choice(list(self.meaning.referents))
+            return random.choice([r for r, v in zip(universe_refs, self.meaning.mapping) if not v])
+        return random.choice([r for r, v in zip(universe_refs, self.meaning.mapping) if v])
 
     def to_dict(self) -> dict:
         the_dict = super().to_dict()