chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/model/keys.py

@@ -0,0 +1,95 @@
+"""The Design Model key grammar: how every entity gets a stable, parseable ``key``.
+
+A model key has the form::
+
+    <kind>:<part>[.<part>...]
+
+``kind`` is the entity kind (``block``, ``module``, ``port``, ``register``, ``field``,
+``requirement``, ...). The parts after ``:`` are joined with ``.`` and describe the
+entity's position, most-general first. There is no single fixed number of parts: each
+kind picks a grammar that is convenient and stable for that kind, for example:
+
+======================  ===============================
+Kind                     Example key
+======================  ===============================
+``project``              ``project:qsoc``
+``block``                ``block:timer``
+``module``               ``module:tiny_timer``
+``port``                 ``port:tiny_timer.i_clk``
+``clock``                ``clock:peri``
+``reset``                ``reset:rst_n``
+``parameter``            ``parameter:tiny_timer.WIDTH``
+``register``             ``register:timer.CTRL``
+``field``                ``field:timer.CTRL.EN``
+``interrupt``            ``interrupt:timer.overflow``
+``memory_region``        ``memory_region:timer``
+``interface``            ``interface:timer.apb``
+``requirement``          ``requirement:REQ-TIM-004``
+``decision``             ``decision:D-timer-0001``
+``open_item``            ``open_item:OI-timer-0001``
+``test``                 ``test:tb_timer_cnt.test_overflow``
+======================  ===============================
+
+A part must not contain ``:`` (reserved for the kind separator) or be empty. Parts may
+contain ``.`` internally only if that ``.`` is not meant as a separator; callers that
+need a literal ``.`` inside a part should avoid this grammar or escape at a higher
+layer, since ``parse_key`` always splits on every ``.``.
+
+Extension kinds registered by packs (:mod:`chipgraph.core.model.registry`) follow the
+same grammar: ``<pack_kind>:<part>[.<part>...]``.
+"""
+
+from __future__ import annotations
+
+_KIND_SEPARATOR = ":"
+_PART_SEPARATOR = "."
+
+
+class InvalidKeyError(ValueError):
+    """Raised when a model key does not follow the key grammar."""
+
+
+def make_key(kind: str, *parts: str) -> str:
+    """Build a model key for ``kind`` from one or more ``parts``.
+
+    Example: ``make_key("register", "timer", "CTRL") == "register:timer.CTRL"``.
+    """
+    if not kind:
+        raise InvalidKeyError("kind must not be empty")
+    if _KIND_SEPARATOR in kind:
+        raise InvalidKeyError(f"kind must not contain {_KIND_SEPARATOR!r}: {kind!r}")
+    if not parts:
+        raise InvalidKeyError(f"make_key({kind!r}) needs at least one part")
+    for part in parts:
+        _check_part(part)
+    return f"{kind}{_KIND_SEPARATOR}{_PART_SEPARATOR.join(parts)}"
+
+
+def parse_key(key: str) -> tuple[str, tuple[str, ...]]:
+    """Split a model key into ``(kind, parts)``. Raises `InvalidKeyError` if malformed."""
+    if _KIND_SEPARATOR not in key:
+        raise InvalidKeyError(f"not a valid model key (missing {_KIND_SEPARATOR!r}): {key!r}")
+    kind, _, rest = key.partition(_KIND_SEPARATOR)
+    if not kind:
+        raise InvalidKeyError(f"not a valid model key (empty kind): {key!r}")
+    if not rest:
+        raise InvalidKeyError(
+            f"not a valid model key (no parts after {_KIND_SEPARATOR!r}): {key!r}"
+        )
+    parts = tuple(rest.split(_PART_SEPARATOR))
+    for part in parts:
+        _check_part(part)
+    return kind, parts
+
+
+def key_kind(key: str) -> str:
+    """Return just the kind of a model key, without fully parsing its parts."""
+    kind, _ = parse_key(key)
+    return kind
+
+
+def _check_part(part: str) -> None:
+    if not part:
+        raise InvalidKeyError("key parts must not be empty")
+    if _KIND_SEPARATOR in part:
+        raise InvalidKeyError(f"key parts must not contain {_KIND_SEPARATOR!r}: {part!r}")

chipgraph/core/model/model.py

@@ -0,0 +1,153 @@
+"""`DesignModel`: an immutable in-memory set of entities and relations.
+
+This is the object every query in M1-02 (`model.block(...)`, `model.find(...)`, ...) is
+built on top of. It never talks to disk: that is `ModelStore`'s job.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+
+from chipgraph.core.model.entities import EntityBase
+from chipgraph.core.model.provenance import Provenance
+from chipgraph.core.model.relations import Relation
+
+
+class ModelConflict(Exception):
+    """Two entities share a `key` but disagree on content.
+
+    Raised by `DesignModel.merge()` (and the `build`/`from_entities` constructors) when
+    the same key appears with two different entities. Both provenances are attached so
+    the caller can point a human at both sources.
+    """
+
+    def __init__(self, key: str, first: EntityBase, second: EntityBase) -> None:
+        self.key = key
+        self.first = first
+        self.second = second
+        super().__init__(
+            f"conflicting entities for key {key!r}: {_describe(first)} vs {_describe(second)}"
+        )
+
+
+def _describe(entity: EntityBase) -> str:
+    return f"kind={entity.kind!r} source={entity.source!r}"
+
+
+@dataclass(frozen=True, slots=True)
+class DesignModel:
+    """An immutable snapshot of entities and relations.
+
+    Construct with `DesignModel.build(...)`, not the dataclass constructor directly,
+    so duplicate keys are always checked.
+    """
+
+    entities: Mapping[str, EntityBase] = field(default_factory=dict)
+    relations: tuple[Relation, ...] = field(default_factory=tuple)
+
+    @classmethod
+    def build(
+        cls, entities: Iterable[EntityBase], relations: Iterable[Relation] = ()
+    ) -> DesignModel:
+        """Build a `DesignModel`, raising `ModelConflict` on duplicate, differing keys."""
+        by_key: dict[str, EntityBase] = {}
+        for entity in entities:
+            existing = by_key.get(entity.key)
+            if existing is not None and existing != entity:
+                raise ModelConflict(entity.key, existing, entity)
+            by_key[entity.key] = entity
+        return cls(entities=by_key, relations=tuple(relations))
+
+    def get(self, key: str) -> EntityBase | None:
+        """Return the entity for `key`, or None if it is not in the model."""
+        return self.entities.get(key)
+
+    def by_kind(self, kind: str) -> tuple[EntityBase, ...]:
+        """Return every entity of a given `kind`, in insertion order."""
+        return tuple(e for e in self.entities.values() if e.kind == kind)
+
+    def children(self, key: str) -> tuple[EntityBase, ...]:
+        """Return entities this entity `contains` or `instantiates`, in relation order."""
+        hierarchy_kinds = ("contains", "instantiates")
+        dsts = [r.dst for r in self.relations if r.src == key and r.kind in hierarchy_kinds]
+        return tuple(self.entities[dst] for dst in dsts if dst in self.entities)
+
+    def find(self, kind: str | None = None, **attrs: object) -> tuple[EntityBase, ...]:
+        """Return entities matching `kind` (if given) and every `attrs` filter.
+
+        Each keyword is matched first against a typed field on the entity, then against
+        `entity.attrs`. An entity that lacks the field/attr entirely does not match.
+        """
+        result: list[EntityBase] = []
+        for entity in self.entities.values():
+            if kind is not None and entity.kind != kind:
+                continue
+            if _matches(entity, attrs):
+                result.append(entity)
+        return tuple(result)
+
+    def get_relations(
+        self,
+        src: str | None = None,
+        dst: str | None = None,
+        kind: str | None = None,
+    ) -> tuple[Relation, ...]:
+        """Return relations filtered by any combination of `src`, `dst`, `kind`."""
+        return tuple(
+            r
+            for r in self.relations
+            if (src is None or r.src == src)
+            and (dst is None or r.dst == dst)
+            and (kind is None or r.kind == kind)
+        )
+
+    def merge(self, other: DesignModel) -> DesignModel:
+        """Return a new `DesignModel` combining `self` and `other`.
+
+        Raises `ModelConflict` if the same key maps to different entities in the two
+        models. Relations are concatenated (duplicates are harmless and kept as-is).
+        """
+        by_key: dict[str, EntityBase] = dict(self.entities)
+        for key, entity in other.entities.items():
+            existing = by_key.get(key)
+            if existing is not None and existing != entity:
+                raise ModelConflict(key, existing, entity)
+            by_key[key] = entity
+        return DesignModel(entities=by_key, relations=self.relations + other.relations)
+
+    def validate_relations(self) -> list[str]:
+        """Return human-readable errors for every relation with a dangling endpoint.
+
+        Does not raise: callers decide whether dangling relations should block anything.
+        An empty list means every relation's `src` and `dst` resolve to a known entity.
+        """
+        errors: list[str] = []
+        for i, relation in enumerate(self.relations):
+            if relation.src not in self.entities:
+                errors.append(
+                    f"relation[{i}] kind={relation.kind!r}: "
+                    f"src {relation.src!r} is not a known entity"
+                )
+            if relation.dst not in self.entities:
+                errors.append(
+                    f"relation[{i}] kind={relation.kind!r}: "
+                    f"dst {relation.dst!r} is not a known entity"
+                )
+        return errors
+
+
+def _matches(entity: EntityBase, attrs: Mapping[str, object]) -> bool:
+    for name, expected in attrs.items():
+        if hasattr(entity, name):
+            if getattr(entity, name) != expected:
+                return False
+        elif name in entity.attrs:
+            if entity.attrs[name] != expected:
+                return False
+        else:
+            return False
+    return True
+
+
+__all__ = ["DesignModel", "ModelConflict", "Provenance"]

chipgraph/core/model/provenance.py

@@ -0,0 +1,27 @@
+"""Provenance: where a Design Model fact came from."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from chipgraph.core.contracts.types import Sha256
+
+
+class Provenance(BaseModel):
+    """Records where a single entity or relation fact was learned from."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    file: str | None = Field(
+        default=None, description="POSIX path the fact was read from, relative to the repo root."
+    )
+    line: int | None = Field(default=None, ge=1, description="The 1-based line number, if any.")
+    extractor: str | None = Field(
+        default=None, description="The extractor or format adapter id that produced this fact."
+    )
+    artifact: Sha256 | None = Field(
+        default=None, description="Content hash of the source artifact, if known."
+    )