chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/model/relations.py

@@ -0,0 +1,61 @@
+"""Relations between Design Model entities (DESIGN.md 4.2)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from chipgraph.core.model.json_value import JSONValue
+from chipgraph.core.model.provenance import Provenance
+
+CoreRelationKind = Literal[
+    "implements",
+    "verifies",
+    "connects",
+    "derives_from",
+    "contains",
+    "instantiates",
+    "instance_of",
+]
+"""The relation kinds DESIGN.md names, plus `contains`/`instantiates`/`instance_of`.
+
+DESIGN.md 4.2 only lists `implements`, `verifies`, `connects`, `derives_from`. Building
+`DesignModel.children()` needs a way to walk hierarchy (block -> module -> port,
+module -> module instance), so this adds `contains` (a owns b, e.g. block contains
+module) and `instantiates` (a module instantiates another module) as core kinds.
+`instance_of` links a block that is an instance on the memory map to the IP block it is a
+copy of (`block:<instance>` -> `block:<ip>`, D38). Packs may add further relation kinds;
+`Relation.kind` is a plain `str` so those round-trip too.
+"""
+
+CORE_RELATION_KINDS: tuple[str, ...] = (
+    "implements",
+    "verifies",
+    "connects",
+    "derives_from",
+    "contains",
+    "instantiates",
+    "instance_of",
+)
+
+
+class Relation(BaseModel):
+    """A directed edge between two entities, identified by their model keys."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    kind: str = Field(
+        description=(
+            "The relation kind: one of CORE_RELATION_KINDS, or a pack-defined kind string."
+        )
+    )
+    src: str = Field(description="Model key of the source entity.")
+    dst: str = Field(description="Model key of the destination entity.")
+    source: Provenance = Field(
+        default_factory=Provenance, description="Where this fact was learned from."
+    )
+    attrs: dict[str, JSONValue] = Field(
+        default_factory=dict, description="Open-ended extra facts not covered by typed fields."
+    )

chipgraph/core/model/store.py

@@ -0,0 +1,279 @@
+"""`ModelStore`: the SQLite-backed, rebuildable index for a `DesignModel` (DESIGN.md 4.5).
+
+The index lives at ``.chipgraph/state/cache/model.db`` by default (`default_model_db_path`)
+and is never the source of truth: it is always rebuildable from the project's own spec
+and RTL files (M1-06 `ingest`). `write()` replaces the whole file atomically so a reader
+never observes a half-written database, and `read()` reconstructs an equivalent
+`DesignModel` from it.
+
+The store also holds an FTS5 index, both over entities (name plus their text-ish
+fields/attrs) and over registered documents (`add_document`), for the `/ask` full-text
+search in a later task (M1-13). If the running Python's sqlite3 lacks the FTS5
+extension, `ModelStore()` raises `ModelStoreError` immediately, rather than failing
+later on first use.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import uuid
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from chipgraph.core.model.entities import EntityBase
+from chipgraph.core.model.model import DesignModel
+from chipgraph.core.model.registry import DEFAULT_ENTITY_KINDS, EntityKinds
+from chipgraph.core.model.relations import Relation
+from chipgraph.core.state.layout import StateLayout
+
+_SCHEMA_VERSION = 1
+
+
+class ModelStoreError(RuntimeError):
+    """Raised for store-level problems, e.g. a SQLite build without the FTS5 extension."""
+
+
+@dataclass(frozen=True, slots=True)
+class SearchHit:
+    """A single full-text search result: either a model entity, or a document line."""
+
+    text: str
+    score: float
+    key: str | None = None
+    file: str | None = None
+    line: int | None = None
+
+    @property
+    def citation(self) -> str:
+        """A human-readable citation: the model key, or ``file:line``."""
+        if self.key is not None:
+            return self.key
+        if self.file is not None and self.line is not None:
+            return f"{self.file}:{self.line}"
+        if self.file is not None:
+            return self.file
+        raise ValueError("SearchHit has neither a key nor a file to cite")
+
+
+def default_model_db_path(root: Path) -> Path:
+    """The default `ModelStore` path for a project rooted at `root`."""
+    return StateLayout(root).cache_dir / "model.db"
+
+
+class ModelStore:
+    """Reads and writes a `DesignModel` to a single SQLite file at `path`."""
+
+    def __init__(self, path: Path, entity_kinds: EntityKinds | None = None) -> None:
+        _check_fts5_available()
+        self.path = path
+        self._entity_kinds = entity_kinds if entity_kinds is not None else DEFAULT_ENTITY_KINDS
+
+    def write(self, model: DesignModel, *, build_inputs_hash: str | None = None) -> None:
+        """Atomically replace the store's content with `model`.
+
+        Writes a fresh database to a temp file next to `path`, then `os.replace`s it
+        into place. If anything fails before the replace, `path` is left untouched.
+        """
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = self.path.with_name(f".{self.path.name}.tmp-{os.getpid()}-{uuid.uuid4().hex}")
+        try:
+            conn = sqlite3.connect(tmp_path)
+            try:
+                _init_schema(conn)
+                _write_entities(conn, model.entities.values())
+                _write_relations(conn, model.relations)
+                _write_meta(conn, build_inputs_hash=build_inputs_hash)
+                conn.commit()
+            finally:
+                conn.close()
+            os.replace(tmp_path, self.path)
+        finally:
+            tmp_path.unlink(missing_ok=True)
+
+    def read(self) -> DesignModel:
+        """Return the `DesignModel` currently stored, or an empty model if none exists."""
+        if not self.path.is_file():
+            return DesignModel.build([], [])
+        conn = sqlite3.connect(self.path)
+        try:
+            entities = [
+                self._entity_kinds.parse(json.loads(raw))
+                for (raw,) in conn.execute("SELECT json FROM entities")
+            ]
+            relations = [
+                Relation.model_validate(json.loads(raw))
+                for (raw,) in conn.execute("SELECT json FROM relations")
+            ]
+        finally:
+            conn.close()
+        return DesignModel.build(entities, relations)
+
+    def add_document(
+        self,
+        path: str,
+        text: str,
+        anchors: Sequence[tuple[int, str]] | None = None,
+    ) -> None:
+        """Register a document's text for full-text search, replacing any prior copy.
+
+        Stores one row per line so hits can cite `file:line`. By default, lines are
+        `text.splitlines()` numbered from 1; pass `anchors` (explicit `(line, text)`
+        pairs) when the caller already knows the true source line for each chunk (e.g.
+        after stripping something from the original file).
+        """
+        conn = self._connect_ensuring_schema()
+        try:
+            conn.execute("DELETE FROM documents WHERE path = ?", (path,))
+            conn.execute("DELETE FROM documents_fts WHERE path = ?", (path,))
+            rows = anchors if anchors is not None else list(enumerate(text.splitlines(), start=1))
+            conn.executemany(
+                "INSERT INTO documents (path, line, text) VALUES (?, ?, ?)",
+                [(path, line, line_text) for line, line_text in rows],
+            )
+            conn.executemany(
+                "INSERT INTO documents_fts (path, line, text) VALUES (?, ?, ?)",
+                [(path, line, line_text) for line, line_text in rows],
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def search(
+        self,
+        query: str,
+        kinds: Iterable[str] | None = None,
+        limit: int = 20,
+    ) -> tuple[SearchHit, ...]:
+        """Full-text search over entities and (unless `kinds` is given) documents.
+
+        Returns hits ordered by relevance (best first). Each hit cites either a model
+        `key` (entity) or `file`/`line` (document).
+        """
+        if not self.path.is_file():
+            return ()
+        conn = sqlite3.connect(self.path)
+        try:
+            hits: list[SearchHit] = []
+            kind_set = set(kinds) if kinds is not None else None
+            entity_rows = conn.execute(
+                "SELECT key, kind, text, bm25(entities_fts) FROM entities_fts "
+                "WHERE entities_fts MATCH ? ORDER BY bm25(entities_fts) LIMIT ?",
+                (query, limit),
+            )
+            for key, kind, text, score in entity_rows:
+                if kind_set is not None and kind not in kind_set:
+                    continue
+                hits.append(SearchHit(key=key, text=text, score=score))
+            if kind_set is None:
+                doc_rows = conn.execute(
+                    "SELECT path, line, text, bm25(documents_fts) FROM documents_fts "
+                    "WHERE documents_fts MATCH ? ORDER BY bm25(documents_fts) LIMIT ?",
+                    (query, limit),
+                )
+                for doc_path, line, text, score in doc_rows:
+                    hits.append(SearchHit(file=doc_path, line=line, text=text, score=score))
+        finally:
+            conn.close()
+        hits.sort(key=lambda hit: hit.score)
+        return tuple(hits[:limit])
+
+    def _connect_ensuring_schema(self) -> sqlite3.Connection:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        is_new = not self.path.is_file()
+        conn = sqlite3.connect(self.path)
+        if is_new:
+            _init_schema(conn)
+            conn.commit()
+        return conn
+
+
+def _check_fts5_available() -> None:
+    conn = sqlite3.connect(":memory:")
+    try:
+        conn.execute("CREATE VIRTUAL TABLE _fts5_check USING fts5(x)")
+    except sqlite3.OperationalError as exc:
+        raise ModelStoreError(
+            "this Python's sqlite3 build lacks the FTS5 extension, which ModelStore "
+            "requires for full-text search over the Design Model; rebuild Python (or its "
+            "sqlite3 dependency) with FTS5 enabled"
+        ) from exc
+    finally:
+        conn.close()
+
+
+def _init_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(
+        """
+        CREATE TABLE entities (
+            key  TEXT PRIMARY KEY,
+            kind TEXT NOT NULL,
+            name TEXT NOT NULL,
+            json TEXT NOT NULL
+        );
+        CREATE TABLE relations (
+            id   INTEGER PRIMARY KEY AUTOINCREMENT,
+            kind TEXT NOT NULL,
+            src  TEXT NOT NULL,
+            dst  TEXT NOT NULL,
+            json TEXT NOT NULL
+        );
+        CREATE TABLE meta (
+            key   TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+        );
+        CREATE VIRTUAL TABLE entities_fts USING fts5(key UNINDEXED, kind UNINDEXED, text);
+        CREATE TABLE documents (
+            path TEXT NOT NULL,
+            line INTEGER NOT NULL,
+            text TEXT NOT NULL
+        );
+        CREATE VIRTUAL TABLE documents_fts USING fts5(path UNINDEXED, line UNINDEXED, text);
+        """
+    )
+
+
+def _write_entities(conn: sqlite3.Connection, entities: Iterable[EntityBase]) -> None:
+    for entity in entities:
+        payload = json.dumps(entity.model_dump(mode="json"))
+        conn.execute(
+            "INSERT INTO entities (key, kind, name, json) VALUES (?, ?, ?, ?)",
+            (entity.key, entity.kind, entity.name, payload),
+        )
+        conn.execute(
+            "INSERT INTO entities_fts (key, kind, text) VALUES (?, ?, ?)",
+            (entity.key, entity.kind, _entity_search_text(entity)),
+        )
+
+
+def _entity_search_text(entity: EntityBase) -> str:
+    parts = [entity.name]
+    for field_name in ("text", "rationale"):
+        value = getattr(entity, field_name, None)
+        if isinstance(value, str):
+            parts.append(value)
+    for value in entity.attrs.values():
+        if isinstance(value, str):
+            parts.append(value)
+    return " ".join(parts)
+
+
+def _write_relations(conn: sqlite3.Connection, relations: Iterable[Relation]) -> None:
+    for relation in relations:
+        payload = json.dumps(relation.model_dump(mode="json"))
+        conn.execute(
+            "INSERT INTO relations (kind, src, dst, json) VALUES (?, ?, ?, ?)",
+            (relation.kind, relation.src, relation.dst, payload),
+        )
+
+
+def _write_meta(conn: sqlite3.Connection, *, build_inputs_hash: str | None) -> None:
+    conn.execute(
+        "INSERT INTO meta (key, value) VALUES ('schema_version', ?)", (str(_SCHEMA_VERSION),)
+    )
+    if build_inputs_hash is not None:
+        conn.execute(
+            "INSERT INTO meta (key, value) VALUES ('build_inputs_hash', ?)", (build_inputs_hash,)
+        )

chipgraph/core/plugin_api/__init__.py

@@ -0,0 +1,81 @@
+"""The plugin API: protocols adapters implement, a registry, and pack loading.
+
+`chipgraph.core.plugin_api` knows nothing about chips or tools: no project, bus, PDK or
+tool names appear here. Concrete adapters live under `chipgraph.adapters`, which core
+never imports.
+"""
+
+from chipgraph.core.plugin_api.local import (
+    LocalPluginApi,
+    LocalPluginRecord,
+    load_local_plugins,
+)
+from chipgraph.core.plugin_api.pack import (
+    Pack,
+    PackManifest,
+    PackProvides,
+    PackRequires,
+    discover_packs,
+    load_pack,
+    resolve_requires,
+)
+from chipgraph.core.plugin_api.protocols import (
+    AgentRuntime,
+    Check,
+    Extractor,
+    FormatAdapter,
+    Generator,
+    LlmProvider,
+    LogParser,
+    ReviewAdapter,
+    Runner,
+    ToolAdapter,
+    VcsAdapter,
+)
+from chipgraph.core.plugin_api.registry import KINDS, PluginError, Registry
+from chipgraph.core.plugin_api.types import (
+    AgentTask,
+    LlmMessage,
+    LlmRequest,
+    LlmResponse,
+    RunResult,
+    ToolContext,
+)
+
+__all__ = [
+    "KINDS",
+    "AgentRuntime",
+    "AgentTask",
+    "Check",
+    "Extractor",
+    "FormatAdapter",
+    "Generator",
+    "LlmMessage",
+    "LlmProvider",
+    "LlmRequest",
+    "LlmResponse",
+    "LocalPluginApi",
+    "LocalPluginRecord",
+    "LogParser",
+    "Pack",
+    "PackManifest",
+    "PackProvides",
+    "PackRequires",
+    "PluginError",
+    "Registry",
+    "ReviewAdapter",
+    "RunResult",
+    "Runner",
+    "ToolAdapter",
+    "ToolContext",
+    "VcsAdapter",
+    "discover_packs",
+    "load_local_plugins",
+    "load_pack",
+    "resolve_requires",
+]
+
+# `ToolContext.runner` names the `Runner` protocol, which types.py can only import under
+# TYPE_CHECKING (protocols.py imports types.py). Resolve the reference once, here, so any
+# import of the plugin API gives a usable `ToolContext`.
+ToolContext.model_rebuild(_types_namespace={"Runner": Runner})

chipgraph/core/plugin_api/local.py

@@ -0,0 +1,167 @@
+"""Load a project's own plugins from files it lists, through the plugin API.
+
+A project may keep small Python plugins next to its code, under `<root>/.chipgraph/plugins/`,
+and list them in the profile so the tool loads them into the registry. They run code: an
+organization can forbid them with a `deny` policy, a user can switch them off with an
+environment variable, and the caller decides whether loading is enabled.
+
+This module stays generic: it knows nothing about chips, tools or any concrete plugin kind.
+A listed file must define ``register(api)`` and call ``api.register(kind, name, obj)`` for
+each thing it contributes; a class is instantiated the same way the entry-point `discover`
+does. A plugin may not replace an existing registration.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from chipgraph.core.plugin_api.registry import PluginError, Registry
+
+_PLUGINS_SUBDIR = (".chipgraph", "plugins")
+
+
+class LocalPluginRecord(BaseModel):
+    """What loading one listed plugin produced: its file, its hash, what it registered."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    entry: str = Field(description="The plugin path exactly as the profile listed it.")
+    path: str | None = Field(
+        default=None,
+        description="Repo-relative path of the resolved file, or None when not loaded.",
+    )
+    sha256: str | None = Field(
+        default=None, description="SHA-256 of the file's bytes, or None when not loaded."
+    )
+    registered: tuple[tuple[str, str], ...] = Field(
+        default=(), description="The (kind, name) pairs this plugin registered, in order."
+    )
+    loaded: bool = Field(default=True, description="Whether the plugin was actually loaded.")
+    disabled_reason: str | None = Field(
+        default=None, description="Why loading was skipped, when it was."
+    )
+
+
+class LocalPluginApi:
+    """The object handed to a plugin's ``register`` function.
+
+    It forwards to the real `Registry` and records every ``(kind, name)`` the plugin
+    registers, so callers can report what a plugin contributed. It mirrors the registry's
+    own rules: a class is instantiated, a duplicate name is refused.
+    """
+
+    def __init__(self, registry: Registry) -> None:
+        self._registry = registry
+        self._registered: list[tuple[str, str]] = []
+
+    def register(self, kind: str, name: str, obj: object) -> None:
+        """Register `obj` under `kind`/`name`, instantiating it if it is a class/factory."""
+        instance = obj() if inspect.isclass(obj) or inspect.isfunction(obj) else obj
+        self._registry.register(kind, name, instance)
+        self._registered.append((kind, name))
+
+    @property
+    def registered(self) -> tuple[tuple[str, str], ...]:
+        """The (kind, name) pairs registered so far, in registration order."""
+        return tuple(self._registered)
+
+
+def _resolve_under_plugins_dir(root: Path, entry: str) -> Path:
+    """Resolve `entry` (repo-relative) to a real `.py` file under `<root>/.chipgraph/plugins/`.
+
+    Rejects absolute paths, `..` escapes, files outside the plugins directory (after
+    following symlinks), missing files, and non-`.py` files, each as a `PluginError`.
+    """
+    if Path(entry).is_absolute():
+        raise PluginError(f"local plugin {entry!r}: must be a repo-relative path, not absolute")
+
+    plugins_dir = root.joinpath(*_PLUGINS_SUBDIR).resolve()
+    target = (root / entry).resolve()
+
+    if not target.is_relative_to(plugins_dir):
+        raise PluginError(
+            f"local plugin {entry!r}: must resolve to a file under "
+            f"{Path(*_PLUGINS_SUBDIR)}/, got {target}"
+        )
+    if not target.is_file():
+        raise PluginError(f"local plugin {entry!r}: no file at {target}")
+    if target.suffix != ".py":
+        raise PluginError(f"local plugin {entry!r}: must be a .py file")
+    return target
+
+
+def _module_name(path: Path, digest: str) -> str:
+    """A unique module name that cannot shadow a real package."""
+    return f"chipgraph_local_plugin_{path.stem}_{digest[:8]}"
+
+
+def _load_one(root: Path, entry: str, registry: Registry) -> LocalPluginRecord:
+    root = root.resolve()
+    target = _resolve_under_plugins_dir(root, entry)
+    data = target.read_bytes()
+    digest = hashlib.sha256(data).hexdigest()
+    rel = target.relative_to(root).as_posix()
+
+    module_name = _module_name(target, digest)
+    spec = importlib.util.spec_from_file_location(module_name, target)
+    if spec is None or spec.loader is None:  # pragma: no cover - defensive
+        raise PluginError(f"local plugin {entry!r}: cannot create an import spec for {target}")
+
+    module = importlib.util.module_from_spec(spec)
+    # The module must be in `sys.modules` while it runs (e.g. `dataclasses` looks its
+    # module up there). The name is unique to this file's content, so it cannot shadow a
+    # real package; it is removed again if the import fails.
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        sys.modules.pop(module_name, None)
+        raise PluginError(f"local plugin {entry!r}: failed to import: {exc}") from exc
+
+    register = getattr(module, "register", None)
+    if not callable(register):
+        raise PluginError(f"local plugin {entry!r}: must define a callable register(api)")
+
+    api = LocalPluginApi(registry)
+    try:
+        register(api)
+    except PluginError as exc:
+        raise PluginError(f"local plugin {entry!r}: {exc}") from exc
+    except Exception as exc:
+        raise PluginError(f"local plugin {entry!r}: register() failed: {exc}") from exc
+
+    return LocalPluginRecord(
+        entry=entry, path=rel, sha256=digest, registered=api.registered, loaded=True
+    )
+
+
+def load_local_plugins(
+    root: Path,
+    entries: tuple[str, ...],
+    registry: Registry,
+    *,
+    enabled: bool,
+    disabled_reason: str | None = None,
+) -> tuple[LocalPluginRecord, ...]:
+    """Load each listed plugin into `registry`, in profile order.
+
+    When `enabled` is False nothing is loaded: a record per entry is returned, marked not
+    loaded, carrying `disabled_reason`. When enabled, each entry is resolved under
+    `<root>/.chipgraph/plugins/`, imported and asked to `register`; any failure raises a
+    `PluginError` naming the entry (the cause stays chained).
+    """
+    if not enabled:
+        return tuple(
+            LocalPluginRecord(entry=entry, loaded=False, disabled_reason=disabled_reason)
+            for entry in entries
+        )
+    return tuple(_load_one(root, entry, registry) for entry in entries)
+
+
+__all__ = ["LocalPluginApi", "LocalPluginRecord", "load_local_plugins"]