honeyc 0.3.0__tar.gz

honeyc-0.3.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: honeyc
+Version: 0.3.0
+Summary: A compiler and CLI for Dense Rune-Chain Notation
+Requires-Python: >=3.11
+Requires-Dist: lark>=1.1
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"

honeyc-0.3.0/README.md

@@ -0,0 +1,138 @@
+# HoneyC
+
+A compiler and CLI for **Dense Rune-Chain Notation** — a compact symbolic
+notation for entities, relations, types, scopes, transforms, bounded mediator
+objects, placeholders, and agent-executable chains.
+
+HoneyC turns dense rune text into an AST, normalized semantic triples, Prolog
+facts, Neo4j Cypher, and human-readable lenses, and it validates chains with
+rewrite suggestions.
+
+```txt
+RuneText → AST → Semantic Triples → Prolog → Cypher → Rendered Lenses
+```
+
+This is the back-end compiler in a larger system: a **rule-catcher** learns an
+emergent notation's grammar from examples; HoneyC compiles a ratified grammar
+into IR + lenses; domain compilers (e.g. DietC, or cognition-chain compilers for
+attention-chains / CoRs / skillchains) sit on top.
+
+## Install
+
+```bash
+python3 -m pip install --no-build-isolation -e .
+```
+
+## CLI
+
+```bash
+honeyc parse   examples/mbr.rune
+honeyc norm    examples/mbr.rune
+honeyc prolog  examples/mbr.rune
+honeyc cypher  examples/mbr.rune
+honeyc render  examples/mbr.rune --as readable    # also: --as triples | --as prose
+honeyc check   examples/mbr.rune
+```
+
+## Core notation
+
+One reading of every marker the grammar (`src/honeyc/grammar.lark`) defines. **Triples** are the statements `honeyc
+norm` prints for the **Example**, leaving out each term's own marker statement (`A entity true`, `A symbol true`,
+`🍯 glyph true`) save in the three rows that define them. `tests/test_readme_notation.py` parses every example in this
+table and checks that it gives exactly these triples.
+
+| Marker | Reads as | Example | Triples |
+|---|---|---|---|
+| `[X]` | a named entity | `[A]` | `A entity true` |
+| `X` | a bare name: a symbol | `A` | `A symbol true` |
+| a glyph | a glyph — a run of characters that are neither structure nor an ASCII name (`symbols.py` names the known ones) | `🍯` | `🍯 glyph true` |
+| `X: T` | `X` has type `T` | `[A]: T` | `A has_type T` |
+| `\|X\|` | `X` is bounded — stabilized, a handleable object | `\|[A]\|` | `A bounded true` |
+| `A ⇔ B` | operational equivalence, both ways | `[A] ⇔ [B]` | `A equiv B` · `B equiv A` |
+| `A ⇒ B` | `A` produces `B` | `[A] ⇒ [B]` | `A produces B` |
+| `A ⇢ B` | `A` compiles to `B` | `[A] ⇢ [B]` | `A compiles_to B` |
+| `A ↦ B` | `A` maps to `B` | `[A] ↦ [B]` | `A maps_to B` |
+| `A → B` | `A` points to `B` | `[A] → [B]` | `A points_to B` |
+| `A ⟶ B` | `A` transitions to `B` | `[A] ⟶ [B]` | `A transitions_to B` |
+| `A ⟼ B` | `A` transforms into `B` at run time | `[A] ⟼ [B]` | `A runtime_transform B` |
+| `A -rel-> B` | the relation `rel(A, B)` | `[A] -owns-> [B]` | `A owns B` |
+| `A <rel- B` | the same relation `rel(A, B)`, written the other way | `[A] <owns- [B]` | `A owns B` |
+| `A <rel> B` | the relation both ways: `rel(A, B)` and `rel(B, A)` | `[A] <owns> [B]` | `A owns B` · `B owns A` |
+| `A:{ B, C }` | a scope: `A` contains `B` and `C` (a `,` separates its members) | `[A]:{ [B], [C] }` | `A contains B` · `A contains C` |
+| `{ B, C }` | a scope with no name: its owner is `_group` | `{ [B], [C] }` | `_group contains B` · `_group contains C` |
+| `📃` | a drilldown placeholder: expand this one level deeper | `[A]:{ 📃 }` | `A placeholder drilldown` |
+| `${A ⇒ B}` | the transform from `A` to `B` as a first-class object, named `xf_` and eight hex digits of a hash of its chain | `${[A] ⇒ [B]}` | `xf_… transform true` · `A produces B` · `xf_… source A` · `xf_… target B` · `xf_… operator produces` |
+| `A := B` | `A` is assigned `B` | `[A] := [B]` | `A assign B` |
+
+**`-rel->` and `<rel-` are two spellings of one relation.** `[A] -owns-> [B]` and `[A] <owns- [B]` both read
+`owns(A, B)`; `<owns>` reads it both ways. A lens that writes the chain back writes each relation the way it was read.
+
+**Backbone rule:** every connector but a relation advances the chain's backbone; a relation hangs its operand as a
+*leaf* off the current backbone node. So `[A] -owns-> [B] ⇔ [C]` reads `owns(A, B)` **and** `equiv(A, C)` — `B` does not
+become the left operand of the `⇔`.
+
+A bounded term sitting between two backbone links is inferred as a **mediator**: `[A] ⇔ |🍯| ⇔ [B]` reads
+`mediates(🍯, A, B)` — `honeyc norm` prints `🍯 mediates A target=B`. A relation an author names `mediates`
+(`[A] -mediates-> [B]`) is an ordinary relation, `A mediates B`. `honeyc check` warns of an unbounded term in a
+mediator's place and suggests the whole chain as it was written with that term bounded: `[A] ⇔ 🍯 ⇔ [B]` →
+`[A] ⇔ |🍯| ⇔ [B]`, which parses back to the chain's statements plus `🍯 bounded true` and the mediation.
+
+## Core example
+
+```txt
+[Mbr]: M*Boundary <is_a-🌸‍💧 ⇔ |🍯| ⇔ [Mbl]: M*Blanket <is_a-🍹
+```
+
+`honeyc render --as triples` (the statements, each term's own marker left out) →
+
+```txt
+Mbr has_type M*Boundary
+🍯 bounded true
+Mbl has_type M*Blanket
+Mbr is_a 🌸‍💧
+Mbr equiv 🍯
+🍯 equiv Mbr
+🍯 equiv Mbl
+Mbl equiv 🍯
+Mbl is_a 🍹
+🍯 mediates Mbr target=Mbl
+```
+
+## The lenses
+
+`readable` writes the chain back — each relation in the spelling it was read, each known glyph with its name beside
+it (`[🌸‍💧: Nectar]`), so it is for reading; `triples`, `prose`, Prolog (`honeyc prolog`) and Cypher (`honeyc cypher`) are
+read from the statements.
+
+## Pipeline
+
+```txt
+parser.py     RuneText ⇢ Lark tree ⇢ AST dataclasses (ast_nodes.py)
+normalize.py  AST ⇢ flat Statement triples
+emit_prolog.py / emit_cypher.py   triples ⇢ facts / graph
+render.py     AST/triples ⇢ readable | triples | prose
+check.py      AST ⇢ warnings + suggested rewrites
+```
+
+## Extending
+
+- **New connector/glyph:** add a terminal to `grammar.lark`, a handler in
+  `parser.py`, a predicate in `normalize._CONNECTOR_PREDICATE`, and a label in
+  the emitters / `symbols.py`.
+- **New renderer lens:** add a mode to `render.render`.
+- **New domain compiler:** consume `honeyc.normalize` output and add your own
+  ontology/engine on top (this is how DietC is built).
+
+## MVP limitations
+
+- Cypher is emitted as text (no live Neo4j driver); Prolog is emitted as text
+  (no embedded SWI-Prolog).
+- The third bundled example (`transform_chain.rune`) parses but exercises only
+  partial transform-object semantics.
+- Unicode tokenization is permissive by design — validation happens in `check`.
+
+## Tests
+
+```bash
+pytest        # the parser, normalize, the emitters, the lenses, check, this README's notation table, and dietc
+```

honeyc-0.3.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "honeyc"
+version = "0.3.0"
+description = "A compiler and CLI for Dense Rune-Chain Notation"
+requires-python = ">=3.11"
+dependencies = ["lark>=1.1", "click>=8.0", "pyyaml>=6.0"]
+
+[project.scripts]
+honeyc = "honeyc.cli:main"
+dietc = "dietc.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+honeyc = ["grammar.lark"]

honeyc-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

honeyc-0.3.0/src/dietc/__init__.py

@@ -0,0 +1,4 @@
+"""DietC — a modular nutrition compiler built on HoneyC. NOT medical advice."""
+from __future__ import annotations
+
+__version__ = "0.3.0"

honeyc-0.3.0/src/dietc/cli.py

@@ -0,0 +1,74 @@
+"""DietC command-line interface."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from .engine import compile_day
+from .load import load_modules, load_profile
+from .render import render_prose
+from .rune import render_rune, render_rune_block, render_via_honeyc
+
+_day_arg = click.argument("day", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+_profile_opt = click.option("--profile", required=True, type=click.Path(exists=True, dir_okay=False, path_type=Path))
+_modules_opt = click.option("--modules", type=click.Path(exists=True, dir_okay=False, path_type=Path), default=None)
+
+
+@click.group()
+@click.version_option(message="dietc %(version)s")
+def main() -> None:
+    """DietC — modular nutrition compiler on HoneyC. Not medical advice."""
+
+
+@main.command()
+@_day_arg
+@_profile_opt
+@_modules_opt
+def compile(day: Path, profile: Path, modules: Path | None) -> None:
+    """Compile a day: totals, gaps, caps, and recommended patches."""
+    state = compile_day(day, load_profile(profile), load_modules(modules) if modules else None)
+    click.echo(f"Day summary: {state.label}")
+    click.echo(f"  gaps:    {', '.join(state.gaps) or 'none'}")
+    click.echo(f"  caps:    {', '.join(state.caps) or 'none'}")
+    click.echo(f"  matrix:  {', '.join(state.matrix_gaps) or 'ok'}")
+    click.echo(f"  patches: {', '.join(r.name for r in state.patches) or 'none'}")
+    for w in state.warnings:
+        click.echo(f"  ! {w}")
+
+
+@main.command()
+@_day_arg
+@_profile_opt
+def summary(day: Path, profile: Path) -> None:
+    """Prose summary of the day (no patch modules required)."""
+    state = compile_day(day, load_profile(profile))
+    click.echo(render_prose(state))
+
+
+@main.command()
+@_day_arg
+@_profile_opt
+@_modules_opt
+@click.option("--honeyc/--no-honeyc", default=False, help="Pass the rune block through HoneyC.")
+def rune(day: Path, profile: Path, modules: Path | None, honeyc: bool) -> None:
+    """Render the day as Dense Rune-Chain notation."""
+    state = compile_day(day, load_profile(profile), load_modules(modules) if modules else None)
+    click.echo(render_rune(state))
+    if honeyc:
+        out = render_via_honeyc(state)
+        click.echo("\n# via HoneyC:\n" + out if out else "\n(HoneyC not available)")
+
+
+@main.command()
+@_day_arg
+@_profile_opt
+@_modules_opt
+def check(day: Path, profile: Path, modules: Path | None) -> None:
+    """Show prose + the recommended patches with their reasons."""
+    state = compile_day(day, load_profile(profile), load_modules(modules) if modules else None)
+    click.echo(render_prose(state))
+
+
+if __name__ == "__main__":
+    main()

honeyc-0.3.0/src/dietc/engine.py

@@ -0,0 +1,48 @@
+"""Orchestrate the DietC daily compile loop."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import gapcap, patch, safety
+from .load import load_day, load_items, load_modules, load_profile
+from .models import DayState, GoalProfile, IntakeEvent, IntakeItem, PatchModule
+from .vectors import MatrixVector, NutrientVector, SafetyVector
+
+
+def build_day_state(events: list[IntakeEvent], items: dict[str, IntakeItem], label: str = "Day") -> DayState:
+    nutrient = NutrientVector()
+    matrix = MatrixVector()
+    safety_state = SafetyVector()
+    for ev in events:
+        item = items.get(ev.item_id)
+        if item is None:
+            safety_state.notes.append(f"unknown item: {ev.item_id}")
+            continue
+        nutrient = nutrient + item.nutrient_vector.scale(ev.amount)
+        matrix = matrix + item.matrix_vector.scale(ev.amount)
+    return DayState(events=events, nutrient_totals=nutrient, matrix_totals=matrix,
+                    safety_state=safety_state, label=label)
+
+
+def compile_day(
+    day_path: Path | str,
+    profile: GoalProfile,
+    modules: dict[str, PatchModule] | None = None,
+    *,
+    items_override: dict[str, IntakeItem] | None = None,
+) -> DayState:
+    events, items_file, label = load_day(day_path)
+    if items_override is not None:
+        items = items_override
+    else:
+        base = Path(day_path).parent
+        items = load_items(base / items_file) if items_file else {}
+    state = build_day_state(events, items, label=label)
+
+    gaps, caps, matrix_gaps, warnings = gapcap.compute(state.nutrient_totals, state.matrix_totals, profile)
+    state.gaps, state.caps, state.matrix_gaps, state.warnings = gaps, caps, matrix_gaps, warnings
+
+    if modules:
+        state.patches = patch.plan(gaps, caps, matrix_gaps, modules, profile)
+        state.warnings += safety.check(state.patches, modules, caps, profile)
+    return state

honeyc-0.3.0/src/dietc/gapcap.py

@@ -0,0 +1,40 @@
+"""Compute nutrient gaps, upper-limit caps, matrix gaps, and pattern warnings."""
+from __future__ import annotations
+
+from .models import GoalProfile
+from .vectors import MatrixVector, NutrientVector, positive_cap, positive_gap
+
+_NEAR_LIMIT_FRACTION = 0.8
+_CAP_WATCH_KEYS = ["added_sugar_g", "sodium_mg", "saturated_fat_g"]
+
+
+def compute(
+    nutrient_totals: NutrientVector,
+    matrix_totals: MatrixVector,
+    profile: GoalProfile,
+) -> tuple[dict[str, float], dict[str, float], dict[str, float], list[str]]:
+    current = nutrient_totals.to_dict()
+    targets = {k: v for k, v in profile.targets.to_dict().items() if v > 0}
+    limits = {k: v for k, v in profile.upper_limits.to_dict().items() if v > 0}
+    min_matrix = {k: v for k, v in profile.minimum_matrix.to_dict().items() if v > 0}
+
+    gaps = positive_gap(targets, current)
+    caps = positive_cap(current, limits)
+    matrix_gaps = positive_gap(min_matrix, matrix_totals.to_dict())
+
+    warnings: list[str] = []
+    # near (but not over) upper limits
+    for key in _CAP_WATCH_KEYS:
+        if key in limits and key not in caps:
+            if current.get(key, 0) >= _NEAR_LIMIT_FRACTION * limits[key]:
+                warnings.append(f"{key} is approaching its upper limit "
+                                f"({current.get(key, 0):.0f}/{limits[key]:.0f}).")
+    # over limit
+    for key, over in caps.items():
+        warnings.append(f"{key} exceeds its upper limit by {over:.0f}.")
+    # technically-patchable-but-poor-pattern signal
+    micros_ok = not any(k in gaps for k in ("calcium_mg", "magnesium_mg", "potassium_mg"))
+    if matrix_gaps and micros_ok and matrix_totals.whole_food_score < 2:
+        warnings.append("matrix/diversity is low even though some micronutrients are met; "
+                        "pattern quality may be poor despite patching.")
+    return gaps, caps, matrix_gaps, warnings

honeyc-0.3.0/src/dietc/load.py

@@ -0,0 +1,87 @@
+"""Load DietC items, profiles, patch modules, and day logs from YAML/JSON."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .models import GoalProfile, IntakeEvent, IntakeItem, PatchModule
+from .vectors import MatrixVector, NutrientVector, SafetyVector
+
+
+def _read(path: Path | str) -> dict:
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+
+
+def load_items(path: Path | str) -> dict[str, IntakeItem]:
+    data = _read(path)
+    items: dict[str, IntakeItem] = {}
+    for raw in data.get("items", []):
+        item = IntakeItem(
+            id=raw["id"],
+            name=raw.get("name", raw["id"]),
+            category=raw.get("category", "unknown"),
+            serving_size=float(raw.get("serving_size", 1)),
+            serving_unit=raw.get("serving_unit", "serving"),
+            nutrient_vector=NutrientVector.from_dict(raw.get("nutrient_vector")),
+            matrix_vector=MatrixVector.from_dict(raw.get("matrix_vector")),
+            safety_vector=SafetyVector.from_dict(raw.get("safety_vector")),
+            tags=list(raw.get("tags", [])),
+            confidence=float(raw.get("confidence", 1.0)),
+        )
+        items[item.id] = item
+    return items
+
+
+def load_profile(path: Path | str) -> GoalProfile:
+    data = _read(path)
+    return GoalProfile(
+        id=data.get("id", "profile"),
+        name=data.get("name", "Profile"),
+        targets=NutrientVector.from_dict(data.get("targets")),
+        upper_limits=NutrientVector.from_dict(data.get("upper_limits")),
+        minimum_matrix=MatrixVector.from_dict(data.get("minimum_matrix")),
+        preferences=dict(data.get("preferences", {})),
+        constraints=dict(data.get("constraints", {})),
+    )
+
+
+def load_modules(path: Path | str) -> dict[str, PatchModule]:
+    data = _read(path)
+    modules: dict[str, PatchModule] = {}
+    for raw in data.get("modules", []):
+        module = PatchModule(
+            id=raw["id"],
+            name=raw.get("name", raw["id"]),
+            category=raw.get("category", "unknown"),
+            contributes=NutrientVector.from_dict(raw.get("contributes")),
+            matrix=MatrixVector.from_dict(raw.get("matrix")),
+            avoids=list(raw.get("avoids", [])),
+            dose_min=float(raw.get("dose_min", 0)),
+            dose_max=float(raw.get("dose_max", 1)),
+            dose_step=float(raw.get("dose_step", 1)),
+            unit=raw.get("unit", "serving"),
+            tags=list(raw.get("tags", [])),
+            warnings=list(raw.get("warnings", [])),
+            cost_score=float(raw.get("cost_score", 0)),
+            adherence_score=float(raw.get("adherence_score", 0)),
+        )
+        modules[module.id] = module
+    return modules
+
+
+def load_day(path: Path | str) -> tuple[list[IntakeEvent], str | None, str]:
+    """Return (events, items_file (relative), label)."""
+    data = _read(path)
+    events = [
+        IntakeEvent(
+            item_id=e["item_id"],
+            amount=float(e.get("amount", 1)),
+            unit=e.get("unit", "serving"),
+            timestamp=e.get("timestamp"),
+            notes=e.get("notes"),
+        )
+        for e in data.get("events", [])
+    ]
+    label = data.get("label") or Path(path).stem.replace("_", " ").title().replace(" ", "")
+    return events, data.get("items_file"), label

honeyc-0.3.0/src/dietc/models.py

@@ -0,0 +1,83 @@
+"""Container models for DietC."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .vectors import MatrixVector, NutrientVector, SafetyVector
+
+
+@dataclass
+class IntakeItem:
+    id: str
+    name: str
+    category: str
+    nutrient_vector: NutrientVector
+    matrix_vector: MatrixVector
+    safety_vector: SafetyVector
+    serving_size: float = 1
+    serving_unit: str = "serving"
+    tags: list[str] = field(default_factory=list)
+    confidence: float = 1.0
+
+
+@dataclass
+class IntakeEvent:
+    item_id: str
+    amount: float = 1
+    unit: str = "serving"
+    timestamp: str | None = None
+    notes: str | None = None
+
+
+@dataclass
+class GoalProfile:
+    id: str
+    name: str
+    targets: NutrientVector
+    upper_limits: NutrientVector
+    minimum_matrix: MatrixVector
+    preferences: dict[str, Any] = field(default_factory=dict)
+    constraints: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PatchModule:
+    id: str
+    name: str
+    category: str
+    contributes: NutrientVector
+    matrix: MatrixVector
+    avoids: list[str] = field(default_factory=list)
+    dose_min: float = 0
+    dose_max: float = 1
+    dose_step: float = 1
+    unit: str = "serving"
+    tags: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    cost_score: float = 0
+    adherence_score: float = 0
+
+
+@dataclass
+class PatchRecommendation:
+    module_id: str
+    name: str
+    dose: float
+    unit: str
+    reasons: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DayState:
+    events: list[IntakeEvent]
+    nutrient_totals: NutrientVector
+    matrix_totals: MatrixVector
+    safety_state: SafetyVector
+    gaps: dict[str, float] = field(default_factory=dict)
+    caps: dict[str, float] = field(default_factory=dict)
+    matrix_gaps: dict[str, float] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    patches: list[PatchRecommendation] = field(default_factory=list)
+    label: str = "Day"

honeyc-0.3.0/src/dietc/patch.py

@@ -0,0 +1,109 @@
+"""Greedy patch planner: pick modules that close gaps without violating caps."""
+from __future__ import annotations
+
+import math
+
+from .models import GoalProfile, PatchModule, PatchRecommendation
+
+_NUTRIENT_LABEL = {
+    "protein_g": "protein", "fiber_g": "fiber", "omega3_g": "omega-3",
+    "potassium_mg": "potassium", "magnesium_mg": "magnesium", "calcium_mg": "calcium",
+}
+
+
+def plan(
+    gaps: dict[str, float],
+    caps: dict[str, float],
+    matrix_gaps: dict[str, float],
+    modules: dict[str, PatchModule],
+    profile: GoalProfile,
+    *,
+    max_modules: int = 6,
+) -> list[PatchRecommendation]:
+    remaining_n = dict(gaps)
+    remaining_m = dict(matrix_gaps)
+    prefs = profile.preferences
+    chosen: list[PatchRecommendation] = []
+    available = dict(modules)
+
+    while available and (remaining_n or remaining_m) and len(chosen) < max_modules:
+        best_id, best_score, best = None, 0.0, None
+        for mid, m in available.items():
+            score = _score(m, remaining_n, remaining_m, caps, prefs)
+            if score > best_score:
+                best_id, best_score, best = mid, score, m
+        if best is None:
+            break
+        available.pop(best_id)
+        rec = _recommend(best, remaining_n, remaining_m, prefs)
+        chosen.append(rec)
+        # subtract contribution at the chosen dose
+        contributes = best.contributes.scale(rec.dose).to_dict()
+        matrix = best.matrix.scale(rec.dose).to_dict()
+        for k, v in contributes.items():
+            if k in remaining_n:
+                remaining_n[k] = max(0.0, remaining_n[k] - v)
+                if remaining_n[k] <= 1e-9:
+                    remaining_n.pop(k)
+        for k, v in matrix.items():
+            if k in remaining_m:
+                remaining_m[k] = max(0.0, remaining_m[k] - v)
+                if remaining_m[k] <= 1e-9:
+                    remaining_m.pop(k)
+    return chosen
+
+
+def _adds_to_capped(module: PatchModule, caps: dict[str, float]) -> bool:
+    contributes = module.contributes.to_dict()
+    return any(contributes.get(k, 0) > 0 for k in caps)
+
+
+def _score(module: PatchModule, gaps, matrix_gaps, caps, prefs) -> float:
+    contributes = module.contributes.to_dict()
+    matrix = module.matrix.to_dict()
+    gap_cover = sum(1 for k in gaps if contributes.get(k, 0) > 0)
+    matrix_cover = sum(1 for k in matrix_gaps if matrix.get(k, 0) > 0)
+    score = 2.0 * gap_cover + 1.5 * matrix_cover + module.adherence_score - module.cost_score
+    if _adds_to_capped(module, caps):
+        score -= 3.0
+    if prefs.get("avoid_high_sodium_patches") and contributes.get("sodium_mg", 0) > 50:
+        score -= 2.0
+    if prefs.get("prefer_drinks") and module.category == "drink":
+        score += 0.5
+    if prefs.get("prefer_low_prep") and module.category in ("drink", "capsule", "bar", "powder"):
+        score += 0.3
+    return score
+
+
+def _recommend(module: PatchModule, gaps, matrix_gaps, prefs) -> PatchRecommendation:
+    contributes = module.contributes.to_dict()
+    matrix = module.matrix.to_dict()
+    addressed_n = [k for k in gaps if contributes.get(k, 0) > 0]
+    addressed_m = [k for k in matrix_gaps if matrix.get(k, 0) > 0]
+
+    # meter dose to the largest nutrient gap it covers, clamped to the module's range
+    dose = module.dose_step or 1
+    if addressed_n:
+        needs = max(gaps[k] / contributes[k] for k in addressed_n)
+        steps = max(1, math.ceil(needs / (module.dose_step or 1)))
+        dose = min(module.dose_max, steps * (module.dose_step or 1))
+    dose = max(dose, module.dose_min or 0) or (module.dose_step or 1)
+
+    reasons: list[str] = []
+    if addressed_n:
+        names = ", ".join(_NUTRIENT_LABEL.get(k, k) for k in addressed_n)
+        reasons.append(f"improves {names} (below target)")
+    if addressed_m:
+        reasons.append("improves plant/color/polyphenol matrix coverage")
+    if prefs.get("avoid_high_sodium_patches") and contributes.get("sodium_mg", 0) <= 50 and "potassium_mg" in addressed_n:
+        reasons.append("adds potassium without adding sodium")
+    if not reasons:
+        reasons.append("supports overall coverage")
+    return PatchRecommendation(
+        module_id=module.id,
+        name=module.name,
+        dose=dose,
+        unit=module.unit,
+        reasons=reasons,
+        warnings=list(module.warnings),
+    )

honeyc-0.3.0/src/dietc/render.py

@@ -0,0 +1,48 @@
+"""Prose rendering of a DayState."""
+from __future__ import annotations
+
+from .models import DayState
+
+_GAP_WORD = {
+    "protein_g": "protein", "fiber_g": "fiber", "omega3_g": "omega-3",
+    "potassium_mg": "potassium", "magnesium_mg": "magnesium", "calcium_mg": "calcium",
+    "calories": "calories",
+}
+_MATRIX_WORD = {
+    "plant_diversity_score": "plant diversity", "color_diversity_score": "color diversity",
+    "berry_count": "berries", "green_leafy_count": "leafy greens", "polyphenol_score": "polyphenols",
+}
+
+
+def render_prose(state: DayState) -> str:
+    # opening inline sentences
+    sentences: list[str] = []
+    items = ", ".join(dict.fromkeys(e.item_id.replace("_", " ") for e in state.events))
+    sentences.append(f"This day ({state.label}) is built from {items}.")
+
+    short = [_GAP_WORD.get(k, k) for k in state.gaps] + [_MATRIX_WORD.get(k, k) for k in state.matrix_gaps]
+    if short:
+        sentences.append("It remains low in " + _join(short) + ".")
+    if state.caps:
+        sentences.append("It exceeds limits on " + _join(list(state.caps)) + ".")
+
+    blocks: list[str] = [" ".join(sentences)]
+
+    if state.patches:
+        lines = ["Recommended patches:"]
+        for i, r in enumerate(state.patches, 1):
+            warn = (" " + " ".join(r.warnings)) if r.warnings else ""
+            lines.append(f"{i}. {r.name} ({r.dose:g} {r.unit}): {'; '.join(r.reasons)}.{warn}")
+        blocks.append("\n".join(lines))
+
+    if state.warnings:
+        blocks.append("Warnings:\n" + "\n".join(f"- {w}" for w in state.warnings))
+
+    return "\n\n".join(blocks)
+
+
+def _join(words: list[str]) -> str:
+    words = list(dict.fromkeys(words))
+    if len(words) == 1:
+        return words[0]
+    return ", ".join(words[:-1]) + f", and {words[-1]}"