pylimid 0.1.0__py3-none-any.whl

pylimid/__init__.py

@@ -0,0 +1,49 @@
+"""
+pylimid — limited-memory influence diagrams with mixed-type variables.
+
+Build a diagram from chance, decision and utility nodes, then query it with
+`infer` or find the optimal policy with `solve`::
+
+    from pylimid import ChanceNode, DecisionNode, InfluenceDiagram, UtilityNode
+    from pylimid import infer, solve
+
+The graph layer (`pylimid.graph`) holds the node types and the diagram;
+the inference layer (`pylimid.inference`) holds `infer`, `solve` and
+their result types.
+"""
+
+from pylimid._version import __version__
+from pylimid.graph import (
+    ChanceNode,
+    DecisionNode,
+    InfluenceDiagram,
+    UtilityNode,
+)
+from pylimid.inference import (
+    InferenceError,
+    InferenceResult,
+    Policy,
+    Posterior,
+    Solution,
+    SolveMethod,
+    SolverName,
+    infer,
+    solve,
+)
+
+__all__ = [
+    "ChanceNode",
+    "DecisionNode",
+    "InferenceError",
+    "InferenceResult",
+    "InfluenceDiagram",
+    "Policy",
+    "Posterior",
+    "Solution",
+    "SolveMethod",
+    "SolverName",
+    "UtilityNode",
+    "__version__",
+    "infer",
+    "solve",
+]

pylimid/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

pylimid/graph/__init__.py

@@ -0,0 +1,37 @@
+"""
+Graph layer: nodes and diagram representation.
+
+Backend-agnostic. Nothing in this package imports a probabilistic
+programming system; the ``dist`` callables carried by chance nodes return
+distribution objects whose concrete type is the backend's concern.
+
+Node types
+----------
+Three node kinds share a common base (`Node`):
+
+- `ChanceNode` — a random variable, ``P(name | parents)``.
+- `DecisionNode` — a variable the agent controls; ``parents`` are its
+  *information set* (observed when deciding), ``states`` its actions.
+- `UtilityNode` — a deterministic payoff ``U(parents)``; always a sink.
+
+A Bayesian network is an `InfluenceDiagram` containing only chance nodes.
+"""
+
+from pylimid.graph.chance_node import ChanceNode
+from pylimid.graph.decision_node import DecisionNode
+from pylimid.graph.diagram import InfluenceDiagram
+from pylimid.graph.node import Consistency, Node, NodeKind
+from pylimid.graph.utility_node import UtilityNode
+from pylimid.graph.validation import DiagramProblem, ProblemKind
+
+__all__ = [
+    "ChanceNode",
+    "Consistency",
+    "DecisionNode",
+    "DiagramProblem",
+    "InfluenceDiagram",
+    "Node",
+    "NodeKind",
+    "ProblemKind",
+    "UtilityNode",
+]

pylimid/graph/chance_node.py

@@ -0,0 +1,121 @@
+"""
+Chance node — a random variable conditioned on its parents.
+
+A chance node is ``P(name | parents)`` — a random variable whose distribution
+depends on its parents (a causal / statistical dependency, as distinct from a
+decision node's information set). It inherits the shared mutable-node contract
+from `Node` — field-level validation on every assignment, and the `Consistency`
+gate (optional ``dist``, derived consistency) for cross-field checking.
+
+The ``dist`` callable receives resolved parent values as **keyword arguments**
+(keyed by parent name), so it is tied to parent *names*, which are stable,
+rather than parent *order*, which is incidental.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from pylimid.graph.node import Consistency, Node, NodeKind, _signature_matches
+
+#: Factory returning a distribution object given resolved parent values.
+#:
+#: The graph layer is opaque to the concrete distribution type a backend uses,
+#: so the return is typed ``Any`` here. The backend's translator narrows it.
+DistFactory = Callable[..., Any]
+
+
+@dataclass
+class ChanceNode(Node):
+    """
+    A random variable in an influence diagram: ``P(name | parents)``.
+
+    The node is mutable. Field-level validation runs on every assignment
+    (including during construction), so a bad value is rejected at the moment
+    it is set rather than later. Cross-field consistency (``dist`` signature
+    vs ``parents``) is *not* enforced on assignment — it is queryable via
+    `consistency` and gated via `validate`.
+
+    Attributes:
+        name: Identifier for the node.
+        parents: Names of the nodes this one conditionally depends on. Empty
+            for a root node. May be edited after construction.
+        dist: Callable invoked as ``dist(**parent_values)`` returning the
+            node's distribution. ``None`` (the default) marks the node as
+            not-yet-configured.
+        states: Human-facing labels for a discrete node's outcomes. ``None``
+            marks the node as continuous. Values flowing through the graph are
+            integer indices into this tuple.
+    """
+
+    dist: DistFactory | None = field(default=None, kw_only=True)
+    states: tuple[str, ...] | None = field(default=None, kw_only=True)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        """Validate ``dist`` / ``states`` (chance-specific) then defer to base."""
+        if key == "dist":
+            _validate_dist(value)
+        elif key == "states":
+            _validate_states(value)
+        super().__setattr__(key, value)
+
+    # --- kind / structure ---------------------------------------------------
+
+    @property
+    def kind(self) -> NodeKind:
+        """`NodeKind.CHANCE`."""
+        return NodeKind.CHANCE
+
+    @property
+    def is_discrete(self) -> bool:
+        """Whether the node has a declared set of discrete states."""
+        return self.states is not None
+
+    # --- consistency --------------------------------------------------------
+
+    def _compute_consistency(self) -> Consistency:
+        if self.dist is None:
+            return Consistency.UNCONFIGURED
+        if _signature_matches(self.dist, self.parents):
+            return Consistency.CONSISTENT
+        return Consistency.STALE
+
+    def consistency_message(self, state: Consistency) -> str:
+        """Chance-node wording for a non-CONSISTENT state (see base)."""
+        if state is Consistency.UNCONFIGURED:
+            return f"Node {self.name!r} has no `dist` configured yet."
+        # STALE is the only remaining non-CONSISTENT state.
+        return (
+            f"Node {self.name!r}'s `dist` signature does not match its "
+            f"parents {self.parents!r}; reconfigure `dist` after changing "
+            f"the parent set."
+        )
+
+
+# --- chance-specific field validators ---------------------------------------
+
+
+def _validate_dist(dist: Any) -> None:
+    if dist is not None and not callable(dist):
+        raise TypeError(
+            f"`dist` must be callable or None, "
+            f"got object of type {type(dist).__name__}."
+        )
+
+
+def _validate_states(states: Any) -> None:
+    if states is None:
+        return
+    if not isinstance(states, tuple):
+        raise TypeError(
+            f"`states` must be a tuple or None, got {type(states).__name__}."
+        )
+    if not states:
+        raise ValueError(
+            "`states`, when provided, must be non-empty; use `None` for a "
+            "continuous node."
+        )
+    if not all(isinstance(s, str) and s.strip() for s in states):
+        raise ValueError(f"`states` must all be non-empty strings, got {states!r}.")
+    if len(set(states)) != len(states):
+        raise ValueError(f"`states` must be unique, got {states!r}.")

pylimid/graph/decision_node.py

@@ -0,0 +1,119 @@
+"""
+Decision node — a variable the agent controls.
+
+A decision node has **no distribution**: its value is chosen, not sampled. What
+it does carry is:
+
+- an **information set** (the ``parents`` field — the variables observed when
+  the decision is made), and
+- an **action space** (``states`` — the available choices).
+
+The information set is structural, not causal
+---------------------------------------------
+A decision's ``parents`` are *not* a statistical dependency. They record what
+the agent observes before acting. This is the standard influence-diagram
+convention: the same ``parents`` tuple that drives topological ordering and
+cycle prevention for chance nodes is reused here, but its meaning is
+"information available at decision time." Keeping one field name means the
+container's shared bookkeeping (validation, ordering) is reused unchanged —
+see `pylimid.graph.node`.
+
+Consistency
+-----------
+A decision is `Consistency.CONSISTENT` once its action ``states`` are
+declared; before that it is `Consistency.UNCONFIGURED`. There is no
+`Consistency.STALE` state for a decision: the action space does not depend
+on the information set's size, so adding or removing an information parent
+never invalidates it.
+
+Continuous decisions are not supported: ``states=None`` leaves the node
+unconfigured.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from pylimid.graph.node import (
+    Consistency,
+    Node,
+    NodeKind,
+)
+
+
+@dataclass
+class DecisionNode(Node):
+    """
+    A decision variable in an influence diagram.
+
+    Attributes:
+        name: Identifier for the node.
+        parents: The **information set** — names of the variables observed
+            when this decision is made. Not a causal dependency. May be edited
+            after construction.
+        states: Labels for the available actions. ``None`` (the default) marks
+            the decision as not-yet-configured. Values flowing through the
+            graph are integer indices into this tuple.
+    """
+
+    states: tuple[str, ...] | None = field(default=None, kw_only=True)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        """Validate ``states`` (decision-specific) then defer to base."""
+        if key == "states":
+            _validate_states(value)
+        super().__setattr__(key, value)
+
+    # --- kind / structure ---------------------------------------------------
+
+    @property
+    def kind(self) -> NodeKind:
+        """`NodeKind.DECISION`."""
+        return NodeKind.DECISION
+
+    @property
+    def is_discrete(self) -> bool:
+        """
+        Whether the decision has a declared, enumerable action space.
+
+        ``True`` when ``states`` is set (a discrete decision, the kind the
+        solvers handle). ``False`` when ``states`` is ``None``, which marks
+        the decision as not-yet-configured.
+        """
+        return self.states is not None
+
+    # --- consistency --------------------------------------------------------
+
+    def _compute_consistency(self) -> Consistency:
+        if self.states is None:
+            return Consistency.UNCONFIGURED
+        return Consistency.CONSISTENT
+
+    def consistency_message(self, state: Consistency) -> str:
+        """Decision-node wording for a non-CONSISTENT state (see base)."""
+        # UNCONFIGURED is the only non-CONSISTENT state for a decision.
+        return (
+            f"Decision {self.name!r} has no action space (`states`) declared; "
+            f"set `states` to the available actions."
+        )
+
+
+# --- decision-specific field validators -------------------------------------
+
+
+def _validate_states(states: Any) -> None:
+    """Validate the action ``states`` (mirrors the chance-node states check)."""
+    if states is None:
+        return
+    if not isinstance(states, tuple):
+        raise TypeError(
+            f"`states` must be a tuple or None, got {type(states).__name__}."
+        )
+    if not states:
+        raise ValueError(
+            "`states`, when provided, must be non-empty; use `None` for an "
+            "undeclared (or future continuous) decision."
+        )
+    if not all(isinstance(s, str) and s.strip() for s in states):
+        raise ValueError(f"`states` must all be non-empty strings, got {states!r}.")
+    if len(set(states)) != len(states):
+        raise ValueError(f"`states` must be unique, got {states!r}.")