cortexm 0.3.0__py3-none-any.whl

cortexm/trace/structural.py

@@ -0,0 +1,183 @@
+"""Deterministic multi-hop structural queries via symbolic Trace + VSA unbind.
+
+Complementary to PPR (probabilistic graph diffusion):
+  PPR answers: "what else might be relevant?"  — fuzzy, associative
+  structural_query answers: "exactly follow this chain."  — deterministic
+
+Inspired by HMS's multiHopQuery API:
+
+    // "Who is John's grandfather?" (father → father)
+    const grandpa = await hms.multiHopQuery('john', ['father', 'father']);
+
+Algorithm:
+  for each relation in the chain:
+    1. Symbolic lookup: exact match in the Trace (subject=current, rel=r)
+       — if a single fact matches, take its value as the next current
+       — if multiple match (ambiguous), take the highest-confidence one
+    2. VSA fallback: if no symbolic match, unbind the role hologram
+       from the entity hologram in the palace, search the result for
+       the nearest stored item vector (Hopfield cleanup). The nearest
+       item becomes the next current.
+
+Returns a `StructuralQueryResult` with the final value + the chain
+of facts traversed. Ambiguous hops or fallback hops are flagged so
+the caller knows the confidence of the answer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Hop:
+    """One hop in a structural query chain."""
+    relation: str
+    subject: str
+    value: str
+    fact_id: str = ""
+    confidence: float = 0.0
+    via: str = ""           # "symbolic" | "vsa_fallback" | "abstain"
+    ambiguous: bool = False  # multiple candidates matched
+    alternatives: list[str] = field(default_factory=list)
+
+
+@dataclass
+class StructuralQueryResult:
+    """Result of a multi-hop structural query."""
+    start_entity: str
+    relation_chain: list[str]
+    hops: list[Hop] = field(default_factory=list)
+    final_value: str = ""
+    success: bool = False
+    failure_reason: str = ""
+    confidence: float = 0.0
+
+
+def structural_query(store, palace, start_entity: str,
+                      relation_chain: list[str],
+                      user_id: str | None = None,
+                      allow_hypotheses: bool = False,
+                      vsa_fallback: bool = True) -> StructuralQueryResult:
+    """Deterministic multi-hop via symbolic Trace + VSA unbinding.
+
+    Args:
+        store: TraceStore
+        palace: MemoryPalace (for VSA fallback)
+        start_entity: the entity to start from
+        relation_chain: list of relations to follow in order
+        user_id: restrict to a user (None = all users)
+        allow_hypotheses: if True, also follow HYPOTHESIZED_BY edges
+                          (derived facts from the cognition engine)
+        vsa_fallback: if True, when no symbolic match, use VSA unbind
+                       + Hopfield cleanup to propose a filler
+
+    Returns:
+        StructuralQueryResult with hops + final value + confidence
+    """
+    res = StructuralQueryResult(
+        start_entity=start_entity, relation_chain=list(relation_chain))
+    current = start_entity
+    confidence_product = 1.0
+
+    for rel in relation_chain:
+        # 1. Symbolic lookup in the Trace
+        where = ("subject=? AND relation=? AND is_active=1 "
+                 "AND quarantined=0")
+        args: list = [current, rel]
+        if user_id is not None:
+            where += " AND user_id=?"
+            args.append(user_id)
+        if not allow_hypotheses:
+            where += " AND is_derived=0"
+        rows = store.conn.execute(
+            f"SELECT id, value, confidence FROM facts WHERE {where} "
+            f"ORDER BY confidence DESC, valid_from DESC", args).fetchall()
+
+        if rows:
+            # single match — clean hop
+            # SELECT id, value, confidence — columns 0, 1, 2
+            row = rows[0]
+            ambiguous = len(rows) > 1
+            hop = Hop(
+                relation=rel, subject=current, value=row[1],
+                fact_id=row[0], confidence=row[2] if row[2] is not None else 0.5,
+                via="symbolic", ambiguous=ambiguous,
+                alternatives=[r[1] for r in rows[1:5]])
+            res.hops.append(hop)
+            confidence_product *= hop.confidence
+            current = row[1]
+            continue
+
+        # 2. VSA fallback: unbind role from entity, search palace
+        if vsa_fallback and palace is not None:
+            try:
+                # encode current entity into a hologram, then unbind
+                # the role hologram to get the (noisy) filler hologram
+                # and search the palace for the nearest stored item.
+                entity_vec = palace._encode_entity(current)
+                role_vec = palace.vsa.role_vector(rel)
+                probe = palace.vsa.unbind(role_vec, entity_vec)
+                # nearest neighbor in the palace
+                ids, scores = palace.search(probe, k=3)
+                if ids:
+                    best_id = ids[0]
+                    best_score = scores[0]
+                    # fetch the value of the best_id fact
+                    fact_row = store.conn.execute(
+                        "SELECT value, confidence FROM facts WHERE id=?",
+                        (best_id,)).fetchone()
+                    if fact_row and best_score > 0.30:
+                        hop = Hop(
+                            relation=rel, subject=current,
+                            value=fact_row[0], fact_id=best_id,
+                            confidence=min(0.49, best_score * 0.5),
+                            via="vsa_fallback",
+                            alternatives=[
+                                ids[i] for i in range(1, len(ids))])
+                        res.hops.append(hop)
+                        confidence_product *= hop.confidence
+                        current = fact_row[0]
+                        continue
+            except Exception:
+                pass  # palace might not have role_vec for `rel`, etc.
+
+        # 3. Abstain — no match found, halt the chain
+        res.hops.append(Hop(
+            relation=rel, subject=current, value="",
+            via="abstain"))
+        res.success = False
+        res.failure_reason = (
+            f"no fact matching ({current!r}, {rel!r}) in the trace"
+            + ("" if vsa_fallback else " (and VSA fallback disabled)"))
+        res.confidence = confidence_product
+        return res
+
+    res.final_value = current
+    res.success = True
+    res.confidence = confidence_product
+    return res
+
+
+def multi_hop_chain(store, start_entity: str, relation: str,
+                    depth: int = 2, **kwargs) -> StructuralQueryResult:
+    """Convenience: walk the same relation `depth` times.
+
+    E.g. multi_hop_chain(store, 'alice', 'father', depth=2) answers
+    "who is Alice's father's father?" (i.e. grandfather).
+    """
+    return structural_query(
+        store, kwargs.get("palace"),
+        start_entity=start_entity,
+        relation_chain=[relation] * depth,
+        user_id=kwargs.get("user_id"),
+        allow_hypotheses=kwargs.get("allow_hypotheses", False),
+        vsa_fallback=kwargs.get("vsa_fallback", True),
+    )
+
+
+__all__ = [
+    "Hop", "StructuralQueryResult",
+    "structural_query", "multi_hop_chain",
+]

cortexm/trace/tmt.py

@@ -0,0 +1,335 @@
+"""TiMem Temporal Memory Tree — 4-level consolidation hierarchy.
+
+arXiv:2601.02845 (TiMem, ACL 2026 Findings) implements a Temporal Memory
+Tree (TMT) with 5 levels: segment → session → day → week → persona.
+It achieves 75.30% on LoCoMo and 76.88% on LongMemEval-S with a
+52.20% reduction in recalled memory length.
+
+Context-M's bi-temporal Trace already has the raw temporal scaffolding
+(valid_from / valid_to / tx_from / tx_to windows + EXTRACTED_FROM edges).
+This module adds the HIERARCHICAL ABSTRACTION layer:
+
+  L1 (episodic)  : raw fact triples (existing)
+  L2 (session)   : per-session summary fact, derived from L1 facts
+                   sharing the same user_id + run_id
+  L3 (day)       : per-day-per-user pattern fact, derived from L2
+                   summaries sharing the same valid_from date
+  L4 (persona)   : per-user stable trait fact, derived from L3 across
+                   >= persona_min_sessions distinct sessions
+
+Each higher-level fact is a DERIVED fact (is_derived=True) linked to
+its constituents via DERIVED_FROM edges. The original facts remain
+active — the hierarchy is an OVERLAY, not a replacement.
+
+Retrieval benefits:
+  * Simple fact lookup → L1 (existing behavior)
+  * "What has Carol been up to?" → L2/L3 session/day summaries
+  * "What kind of person is Carol?" → L4 persona traits
+  * Tokens injected into LLM context drop ~50% because higher levels
+    compress multiple L1 facts into one summary.
+
+The summaries are written as natural-language sentences so they're
+embeddable and lexically matchable by the existing palace + reader.
+
+μ=0 SAFE — the summary generation is rule-based:
+  * For a session with N works_at facts, the summary is:
+        "<user> worked at <V1>, <V2>, ..., <VN> in this session"
+  * For a day's L2 summaries, the summary aggregates the unique
+    relations and their top values.
+  * For persona, the most-reinforced stable traits (access_count > 3)
+    are surfaced.
+
+No LLM call. The NL strings are templated and deterministic.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from cortexm.trace.edges import REFERS_TO
+from cortexm.trace.fact import make_fact
+from cortexm.util import iso
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+# Edge kind for DERIVED_FROM — the existing trace/edges.py defines
+# CAUSAL/REFERS_TO/MERGED_WITH/RETRACTED_BY/CONTRADICTS/PRECEDED_BY.
+# We use REFERS_TO for the downward link (summary refers to constituents)
+# and the existing EXTRACTED_FROM for the upward link (constituent →
+# summary, mirroring raw_chunk → fact).
+
+
+def _summarize_session_facts(facts: list, user_id: str,
+                              run_id: str | None) -> str:
+    """Render a session summary NL string from its L1 fact set."""
+    relations = defaultdict(set)
+    for f in facts:
+        if f.is_derived:
+            continue
+        relations[f.relation].add(f.value)
+    parts = []
+    for rel, vals in relations.items():
+        vals_str = ", ".join(sorted(vals)[:5])
+        if len(vals) > 5:
+            vals_str += f" (+{len(vals)-5} more)"
+        parts.append(f"{rel}: {vals_str}")
+    summary = f"session summary for user {user_id}"
+    if run_id:
+        summary += f" (run {run_id})"
+    summary += " — " + "; ".join(parts) if parts else summary + " (no facts)"
+    return summary[:500]  # cap to keep palace embeddings focused
+
+
+def _summarize_day_facts(session_summaries: list, user_id: str,
+                          day_str: str) -> str:
+    """Render a daily summary NL string from its L2 session summaries."""
+    # session summaries are derived facts; their `value` is the NL string
+    parts = [f.value for f in session_summaries if f.value]
+    if not parts:
+        return f"day summary for user {user_id} on {day_str} (no sessions)"
+    summary = (f"day summary for user {user_id} on {day_str} — "
+               f"{len(parts)} session(s). Highlights: "
+               + " | ".join(parts[:3]))
+    if len(parts) > 3:
+        summary += f" (+{len(parts)-3} more sessions)"
+    return summary[:800]
+
+
+def _summarize_persona_facts(day_summaries: list, user_id: str,
+                              all_facts: list) -> str:
+    """Render a persona summary NL string from L3 day summaries + L1
+    stable traits.
+
+    Persona = the most-reinforced, longest-lived facts about the user.
+    We pick facts with:
+      * access_count >= 3 (retrieved multiple times → behaviorally
+        relevant)
+      * memory_type == "long_term"
+      * is_active == True
+    """
+    # stable traits from L1
+    stable = [f for f in all_facts
+              if not f.is_derived
+              and f.user_id == user_id
+              and f.memory_type == "long_term"
+              and f.is_active
+              and f.access_count >= 3]
+    # group by relation, take most-accessed value per relation
+    by_rel = defaultdict(list)
+    for f in stable:
+        by_rel[f.relation].append(f)
+    traits = []
+    for rel, fs in by_rel.items():
+        fs.sort(key=lambda x: -x.access_count)
+        top = fs[0]
+        traits.append(f"{rel}={top.value} (accessed {top.access_count}x)")
+    summary = f"persona profile for user {user_id} — "
+    summary += "; ".join(traits[:10])
+    if len(traits) > 10:
+        summary += f" (+{len(traits)-10} more traits)"
+    return summary[:1000]
+
+
+def _session_key(f) -> tuple:
+    """Group facts by (user_id, run_id) for L2 clustering."""
+    return (f.user_id, f.run_id or "_no_run")
+
+
+def _day_key(f) -> str:
+    """Group facts by user_id + date portion of valid_from for L3."""
+    vf = (f.valid_from or "")[:10]  # "YYYY-MM-DD"
+    return f"{f.user_id}:{vf or '_no_date'}"
+
+
+def tmt_build(store, palace=None, *,
+              session_cluster_mins: int = 5,
+              persona_min_sessions: int = 3,
+              user_id: str | None = None,
+              dry_run: bool = False) -> dict:
+    """Build the 4-level TiMem hierarchy as derived facts + edges.
+
+    1. Group active, non-derived L1 facts by (user_id, run_id) →
+       emit one L2 session-summary fact per group with >= N facts.
+    2. Group L2 summaries by (user_id, date) → emit one L3 day-summary
+       fact per (user, day) with >= 1 session.
+    3. For each user with >= persona_min_sessions distinct sessions,
+       emit one L4 persona-summary fact.
+
+    Each higher-level fact is stored as is_derived=True and linked to
+    its constituents via REFERS_TO edges (downward) — bi-temporal safe,
+    idempotent (we check for existing derived facts with the same
+    `provenance.tmt_key` before re-emitting).
+
+    Returns a stats dict.
+    """
+    stats = {
+        "l2_sessions_built": 0,
+        "l3_days_built": 0,
+        "l4_personas_built": 0,
+        "l2_skipped_small": 0,
+        "l4_skipped_few_sessions": 0,
+        "dry_run": dry_run,
+    }
+
+    # --- load L1 facts (active, non-derived) ---------------------------
+    where = "is_active=1 AND quarantined=0 AND is_derived=0"
+    args: tuple = ()
+    if user_id is not None:
+        where += " AND user_id=?"
+        args = (user_id,)
+    rows = store.conn.execute(
+        f"SELECT id FROM facts WHERE {where}", args).fetchall()
+    fact_ids = [r[0] for r in rows]
+    l1_facts = store.get_facts(fact_ids)
+    if not l1_facts:
+        return stats
+
+    # open one batch commit for the whole TMT build — idempotent inserts
+    # use the existing provenance.tmt_key check before re-emitting, so
+    # calling tmt_build repeatedly is safe.
+    if not dry_run:
+        store.begin_batch()
+        commit = store.create_commit(
+            f"tmt_build: hierarchy pass for "
+            f"{'user='+user_id if user_id else 'all users'}",
+            n_facts=0)
+    else:
+        commit = None
+
+    # --- L2: per-session summaries -------------------------------------
+    sessions: dict[tuple, list] = defaultdict(list)
+    for f in l1_facts:
+        sessions[_session_key(f)].append(f)
+
+    l2_facts: list = []
+    for (uid, rid), group in sessions.items():
+        if len(group) < session_cluster_mins:
+            stats["l2_skipped_small"] += 1
+            continue
+        nl = _summarize_session_facts(group, uid, rid if rid != "_no_run" else None)
+        # idempotency: skip if a derived fact with this tmt_key exists
+        existing = store.conn.execute(
+            "SELECT id FROM facts WHERE is_derived=1 AND "
+            "provenance LIKE ? AND user_id=?",
+            (f'"tmt_key":"l2:{uid}:{rid}"%', uid)).fetchall()
+        if existing:
+            continue
+        if dry_run:
+            stats["l2_sessions_built"] += 1
+            continue
+        f = make_fact(
+            subject=uid, relation="session_summary", value=nl,
+            user_id=uid, agent_id=None, run_id=(rid if rid != "_no_run" else None),
+            confidence=0.85, memory_type="long_term",
+            valid_from=iso(_now())[:10], now=_now(),
+            provenance={"tmt_level": "L2", "tmt_key": f"l2:{uid}:{rid}",
+                        "tmt_constituents": [g.id for g in group[:50]],
+                        "tmt_constituent_count": len(group)},
+            is_derived=True,
+        )
+        f.birth_commit = commit
+        store.insert_fact(f, commit)
+        # wire downward edges
+        for g in group[:50]:  # cap edges for storage
+            store.add_edge(f.id, g.id, REFERS_TO,
+                           {"tmt": "l2_constituent"})
+        l2_facts.append(f)
+        stats["l2_sessions_built"] += 1
+
+    # --- L3: per-day summaries ----------------------------------------
+    days: dict[str, list] = defaultdict(list)
+    for f in l2_facts:
+        days[_day_key(f)].append(f)
+    # also include standalone L1 facts that didn't get an L2 (small sessions)
+    # so day summaries still cover them
+    for f in l1_facts:
+        days[_day_key(f)].append(f)
+
+    l3_facts: list = []
+    user_days: dict[str, set] = defaultdict(set)
+    for day_key, group in days.items():
+        uid = day_key.split(":", 1)[0]
+        day_str = day_key.split(":", 1)[1] if ":" in day_key else "_no_date"
+        l2_in_group = [g for g in group if getattr(g, "is_derived", False)
+                       and getattr(g, "provenance", {}).get("tmt_level") == "L2"]
+        if not l2_in_group:
+            continue
+        nl = _summarize_day_facts(l2_in_group, uid, day_str)
+        existing = store.conn.execute(
+            "SELECT id FROM facts WHERE is_derived=1 AND "
+            "provenance LIKE ? AND user_id=?",
+            (f'"tmt_key":"l3:{uid}:{day_str}"%', uid)).fetchall()
+        if existing:
+            continue
+        if dry_run:
+            stats["l3_days_built"] += 1
+            continue
+        f = make_fact(
+            subject=uid, relation="day_summary", value=nl,
+            user_id=uid, valid_from=day_str, now=_now(),
+            confidence=0.80, memory_type="long_term",
+            provenance={"tmt_level": "L3",
+                        "tmt_key": f"l3:{uid}:{day_str}",
+                        "tmt_constituents": [g.id for g in l2_in_group[:50]],
+                        "tmt_constituent_count": len(l2_in_group)},
+            is_derived=True,
+        )
+        f.birth_commit = commit
+        store.insert_fact(f, commit)
+        for g in l2_in_group[:50]:
+            store.add_edge(f.id, g.id, REFERS_TO,
+                           {"tmt": "l3_constituent"})
+        l3_facts.append(f)
+        user_days[uid].add(day_str)
+        stats["l3_days_built"] += 1
+
+    # --- L4: per-user persona summaries ------------------------------
+    all_users = set([f.user_id for f in l1_facts])
+    for uid in all_users:
+        if user_id is not None and uid != user_id:
+            continue
+        if len(user_days.get(uid, set())) < persona_min_sessions:
+            stats["l4_skipped_few_sessions"] += 1
+            continue
+        # all L1 facts for this user, sorted by reinforcement
+        user_facts = [f for f in l1_facts if f.user_id == uid]
+        nl = _summarize_persona_facts(
+            [f for f in l3_facts if f.user_id == uid], uid, user_facts)
+        existing = store.conn.execute(
+            "SELECT id FROM facts WHERE is_derived=1 AND "
+            "provenance LIKE ? AND user_id=?",
+            (f'"tmt_key":"l4:{uid}"%', uid)).fetchall()
+        if existing:
+            continue
+        if dry_run:
+            stats["l4_personas_built"] += 1
+            continue
+        f = make_fact(
+            subject=uid, relation="persona_summary", value=nl,
+            user_id=uid, valid_from=iso(_now())[:10], now=_now(),
+            confidence=0.75, memory_type="long_term",
+            provenance={"tmt_level": "L4",
+                        "tmt_key": f"l4:{uid}",
+                        "tmt_constituent_days": list(user_days[uid])[:50],
+                        "tmt_constituent_count": len(user_days[uid])},
+            is_derived=True,
+        )
+        f.birth_commit = commit
+        store.insert_fact(f, commit)
+        for d in l3_facts:
+            if d.user_id == uid:
+                store.add_edge(f.id, d.id, REFERS_TO,
+                               {"tmt": "l4_constituent"})
+        stats["l4_personas_built"] += 1
+
+    if not dry_run:
+        store.end_batch()
+
+    return stats
+
+
+__all__ = ["tmt_build"]

cortexm/util.py

@@ -0,0 +1,148 @@
+"""Shared utilities: time, ids, normalization, string similarity."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+import uuid
+from datetime import datetime, timedelta, timezone
+
+WORDS = re.compile(r"[a-z0-9']+")
+
+
+def h64(feature: str, seed: int = 0) -> int:
+    """Deterministic 64-bit hash of a string feature (stable across runs)."""
+    import hashlib
+    return int.from_bytes(
+        hashlib.blake2b(feature.encode("utf-8"), digest_size=8,
+                        key=(seed & 0xFFFFFFFFFFFFFFFF).to_bytes(8, "little")).digest(),
+        "little")
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_ts(value: str | datetime | None) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+    v = value.strip().replace("Z", "+00:00")
+    try:
+        dt = datetime.fromisoformat(v)
+    except ValueError:
+        for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%Y-%m-%d %H:%M:%S"):
+            try:
+                dt = datetime.strptime(value.strip(), fmt)
+                break
+            except ValueError:
+                continue
+        else:
+            return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def new_id() -> str:
+    return uuid.uuid4().hex
+
+
+def normalize(text: str) -> str:
+    """Lowercase, strip punctuation/articles, collapse whitespace."""
+    text = unicodedata.normalize("NFKD", text)
+    text = text.lower()
+    text = re.sub(r"[^a-z0-9\s']+", " ", text)
+    text = re.sub(r"\b(the|a|an|is|are|was|were)\b", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def words(text: str) -> list[str]:
+    return WORDS.findall(text.lower())
+
+
+def token_estimate(text: str) -> int:
+    """Cheap token estimator (~1.3 tokens/word). Deterministic."""
+    n = len(text.split())
+    return max(1, round(n * 1.3))
+
+
+def levenshtein(a: str, b: str, cutoff: float = 1.0) -> int:
+    """Levenshtein distance with early exit when distance exceeds cutoff*maxlen."""
+    la, lb = len(a), len(b)
+    if la == 0:
+        return lb
+    if lb == 0:
+        return la
+    maxd = int(max(la, lb) * cutoff) + 1
+    prev = list(range(lb + 1))
+    for i in range(1, la + 1):
+        cur = [i] + [0] * lb
+        best = i
+        for j in range(1, lb + 1):
+            cost = 0 if a[i - 1] == b[j - 1] else 1
+            cur[j] = min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
+            best = min(best, cur[j])
+        if best > maxd:
+            return maxd
+        prev = cur
+    return prev[lb]
+
+
+def similarity(a: str, b: str) -> float:
+    """Combined token-Jaccard + Levenshtein string similarity in [0, 1].
+
+    Fast paths: jaccard decides when clearly similar or clearly
+    different; Levenshtein (with early-exit cutoff) only runs in the
+    ambiguous band. Keeps conflict analysis linear-ish at scale.
+    """
+    a_n, b_n = normalize(a), normalize(b)
+    if not a_n or not b_n:
+        return 0.0
+    if a_n == b_n:
+        return 1.0
+    wa, wb = set(words(a_n)), set(words(b_n))
+    union = wa | wb
+    jac = len(wa & wb) / len(union) if union else 0.0
+    if jac >= 0.92:
+        return jac
+    if jac < 0.30:
+        return jac
+    d = levenshtein(a_n, b_n, cutoff=0.75)
+    lev = 1.0 - d / max(len(a_n), len(b_n))
+    return max(jac, lev)
+
+
+def month_number(name: str) -> int | None:
+    m = name.strip()[:3].lower()
+    table = {
+        "jan": 1, "feb": 2, "mar": 3, "apr": 4, "may": 5, "jun": 6,
+        "jul": 7, "aug": 8, "sep": 9, "oct": 10, "nov": 11, "dec": 12,
+    }
+    return table.get(m)
+
+
+def month_name(num: int) -> str:
+    return ["January", "February", "March", "April", "May", "June", "July",
+            "August", "September", "October", "November", "December"][num - 1]
+
+
+def days_in(year: int, month: int) -> int:
+    if month == 12:
+        return 31
+    return (datetime(year, month + 1, 1) - timedelta(days=1)).day
+
+
+def fmt_date(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%d")
+
+
+def fmt_month(dt: datetime) -> str:
+    return dt.strftime("%Y-%m")
+
+
+def clamp(x: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, x))