chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/plugin_api/pack.py

@@ -0,0 +1,159 @@
+"""Packs: domain bundles of rules, roles, skills, checks, templates and commands.
+
+A pack is a directory containing a `pack.yml` manifest. Core loads and validates the
+manifest and checks that every path it advertises actually exists; it does not interpret
+rules, skills or templates itself (that is packs' own concern, or later tasks').
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Annotated, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+from chipgraph.core.plugin_api.registry import PluginError
+
+_NAME_PATTERN = r"^[a-z0-9][a-z0-9-]*$"
+_VERSION_PATTERN = r"^\d+\.\d+\.\d+$"
+
+PackName = Annotated[str, StringConstraints(pattern=_NAME_PATTERN)]
+PackVersion = Annotated[str, StringConstraints(pattern=_VERSION_PATTERN)]
+
+
+class PackRequires(BaseModel):
+    """What a pack needs: a core version range, other packs, and capabilities."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    core: str = Field(default=">=0.0", description="Version range of chipgraph core required.")
+    packs: tuple[str, ...] = Field(default=(), description="Names of packs this pack requires.")
+    capabilities: tuple[str, ...] = Field(
+        default=(), description="Adapter capabilities this pack requires, e.g. 'lint'."
+    )
+
+
+class PackProvides(BaseModel):
+    """What a pack provides: paths (relative to the pack directory) to its contents."""
+
+    # `schemas` is written `schema:` in pack.yml; the Python name avoids shadowing
+    # pydantic's deprecated BaseModel.schema().
+    model_config = ConfigDict(extra="forbid", frozen=True, populate_by_name=True)
+
+    rules: tuple[str, ...] = Field(default=(), description="Paths to rule definitions.")
+    agents: tuple[str, ...] = Field(default=(), description="Paths to agent role definitions.")
+    skills: tuple[str, ...] = Field(default=(), description="Paths to skill definitions.")
+    checks: tuple[str, ...] = Field(default=(), description="Paths to check definitions.")
+    workflows: tuple[str, ...] = Field(default=(), description="Paths to workflow definitions.")
+    templates: tuple[str, ...] = Field(default=(), description="Paths to templates.")
+    commands: tuple[str, ...] = Field(
+        default=(), description="Command names this pack provides, e.g. '/rtl'."
+    )
+    schemas: tuple[str, ...] = Field(
+        default=(),
+        alias="schema",
+        description="Paths to schema extensions (`schema:` in pack.yml).",
+    )
+
+
+class PackManifest(BaseModel):
+    """The validated contents of a pack's `pack.yml`."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    name: PackName = Field(description="The pack's name, e.g. 'digital-rtl'.")
+    version: PackVersion = Field(description="The pack's version, MAJOR.MINOR.PATCH.")
+    description: str = Field(default="", description="A short, plain-English description.")
+    requires: PackRequires = Field(
+        default_factory=PackRequires, description="What this pack needs."
+    )
+    provides: PackProvides = Field(
+        default_factory=PackProvides, description="What this pack provides."
+    )
+
+
+class Pack:
+    """A loaded pack: its manifest, plus the directory it lives in."""
+
+    def __init__(self, manifest: PackManifest, root: Path) -> None:
+        self.manifest = manifest
+        self.root = root
+
+    def path(self, rel: str) -> Path:
+        """Resolve a path relative to this pack's directory."""
+        return self.root / rel
+
+    def __repr__(self) -> str:
+        return (
+            f"Pack(name={self.manifest.name!r}, "
+            f"version={self.manifest.version!r}, root={self.root!r})"
+        )
+
+
+_PROVIDES_PATH_FIELDS = ("rules", "agents", "skills", "checks", "workflows", "templates", "schemas")
+
+
+def load_pack(directory: Path) -> Pack:
+    """Load and validate the pack at `directory`.
+
+    Raises `PluginError` if `pack.yml` is missing or invalid, or if any path listed in
+    `provides` (other than `commands`, which are names, not paths) does not exist under
+    `directory`.
+    """
+    manifest_path = directory / "pack.yml"
+    if not manifest_path.is_file():
+        raise PluginError(f"no pack.yml found in {directory}")
+    try:
+        raw = yaml.safe_load(manifest_path.read_text()) or {}
+        manifest = PackManifest.model_validate(raw)
+    except Exception as exc:
+        raise PluginError(f"invalid pack manifest at {manifest_path}: {exc}") from exc
+
+    for field in _PROVIDES_PATH_FIELDS:
+        for rel in getattr(manifest.provides, field):
+            if not (directory / rel).exists():
+                raise PluginError(
+                    f"pack {manifest.name!r} provides missing path {rel!r} "
+                    f"(expected at {directory / rel})"
+                )
+
+    return Pack(manifest, directory)
+
+
+def discover_packs(search_paths: Iterable[Path]) -> dict[str, Pack]:
+    """Load every pack found as an immediate subdirectory (containing `pack.yml`) of any path.
+
+    Raises `PluginError` if two discovered packs share a name.
+    """
+    packs: dict[str, Pack] = {}
+    for search_path in search_paths:
+        if not search_path.is_dir():
+            continue
+        for entry in sorted(search_path.iterdir()):
+            if not entry.is_dir() or not (entry / "pack.yml").is_file():
+                continue
+            pack = load_pack(entry)
+            name = pack.manifest.name
+            if name in packs:
+                raise PluginError(
+                    f"duplicate pack name {name!r}: found at {packs[name].root} and {entry}"
+                )
+            packs[name] = pack
+    return packs
+
+
+def resolve_requires(packs: Mapping[str, Pack]) -> None:
+    """Check that every pack's `requires.packs` is present in `packs`.
+
+    Raises `PluginError` naming the first missing dependency found.
+    """
+    for pack in packs.values():
+        for required in pack.manifest.requires.packs:
+            if required not in packs:
+                raise PluginError(
+                    f"pack {pack.manifest.name!r} requires pack {required!r}, "
+                    "which is not available"
+                )

chipgraph/core/plugin_api/protocols.py

@@ -0,0 +1,177 @@
+"""Plugin protocols: the structural interfaces adapters, checks and packs implement.
+
+Every protocol here is `@runtime_checkable`, so `isinstance(obj, Protocol)` works for
+registry validation (see `registry.py`). Each protocol carries a `name: str` attribute
+identifying the concrete implementation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from chipgraph.core.contracts import AgentResult, Approval, CheckResult, CheckSpec, Issue
+from chipgraph.core.plugin_api.types import (
+    AgentTask,
+    LlmRequest,
+    LlmResponse,
+    RunResult,
+    ToolContext,
+)
+
+
+@runtime_checkable
+class Runner(Protocol):
+    """Runs subprocess commands. Core never calls `subprocess` directly; it goes through this."""
+
+    name: str
+
+    async def run(
+        self,
+        cmd: Sequence[str],
+        *,
+        cwd: Path,
+        env: Mapping[str, str] | None = None,
+        timeout_s: float | None = None,
+    ) -> RunResult:
+        """Run `cmd` in `cwd` and return its result."""
+        ...
+
+
+@runtime_checkable
+class LogParser(Protocol):
+    """Parses a tool's raw log text into structured issues."""
+
+    name: str
+
+    def parse(self, log: str) -> tuple[Issue, ...]:
+        """Extract issues from `log`."""
+        ...
+
+
+@runtime_checkable
+class ToolAdapter(Protocol):
+    """Wraps an external EDA tool (or other command-line tool) behind a common interface."""
+
+    name: str
+    capability: str
+
+    async def run(self, spec: CheckSpec, ctx: ToolContext) -> CheckResult:
+        """Run the check described by `spec` under `ctx` and return its result."""
+        ...
+
+
+@runtime_checkable
+class Check(Protocol):
+    """A built-in, deterministic check that needs no external tool."""
+
+    name: str
+    id: str
+
+    async def run(self, spec: CheckSpec, ctx: ToolContext) -> CheckResult:
+        """Run this check for `spec` under `ctx` and return its result."""
+        ...
+
+
+@runtime_checkable
+class VcsAdapter(Protocol):
+    """Version control operations the engine needs: head, diffs, and disposable workspaces."""
+
+    name: str
+
+    def head(self, root: Path) -> str:
+        """Return the current head revision of the repo at `root`."""
+        ...
+
+    def changed_files(self, root: Path, since: str | None = None) -> tuple[str, ...]:
+        """Return paths changed since `since` (or since the last commit, if None)."""
+        ...
+
+    def create_workspace(self, root: Path, name: str) -> Path:
+        """Create a disposable workspace (e.g. a worktree) named `name` and return its path."""
+        ...
+
+    def remove_workspace(self, path: Path) -> None:
+        """Remove a workspace previously created by `create_workspace`."""
+        ...
+
+
+@runtime_checkable
+class ReviewAdapter(Protocol):
+    """Records and retrieves human approvals against gates."""
+
+    name: str
+
+    def record(self, approval: Approval) -> None:
+        """Persist `approval`."""
+        ...
+
+    def approvals(self, gate_id: str) -> tuple[Approval, ...]:
+        """Return every approval recorded against `gate_id`."""
+        ...
+
+
+@runtime_checkable
+class LlmProvider(Protocol):
+    """Completes LLM requests. `local` gates whether it may see data labeled 'nda'."""
+
+    name: str
+    local: bool
+    """True when this provider is self-hosted; only then may it receive 'nda'-labeled data."""
+
+    async def complete(self, request: LlmRequest) -> LlmResponse:
+        """Complete `request` and return the response."""
+        ...
+
+
+@runtime_checkable
+class AgentRuntime(Protocol):
+    """Runs an `AgentTask` to completion (or to a stopping point) via some agent harness."""
+
+    name: str
+
+    async def run_task(self, task: AgentTask) -> AgentResult:
+        """Run `task` and return its result."""
+        ...
+
+
+@runtime_checkable
+class FormatAdapter(Protocol):
+    """Loads a domain file format into raw facts.
+
+    Returns raw facts (plain mappings), not the typed Design Model: the typed model
+    arrives in M1-01. Callers that need the Design Model translate these facts themselves.
+    """
+
+    name: str
+
+    def load(self, path: Path) -> Iterable[Mapping[str, object]]:
+        """Load `path` and yield its facts."""
+        ...
+
+
+@runtime_checkable
+class Extractor(Protocol):
+    """Extracts facts from a source file (e.g. RTL) by parsing it.
+
+    Returns raw facts (plain mappings), not the typed Design Model: the typed model
+    arrives in M1-01. Callers that need the Design Model translate these facts themselves.
+    """
+
+    name: str
+
+    def extract(self, path: Path) -> Iterable[Mapping[str, object]]:
+        """Extract facts from `path`."""
+        ...
+
+
+@runtime_checkable
+class Generator(Protocol):
+    """Generates output files from facts, e.g. rendering a template."""
+
+    name: str
+
+    def generate(self, out_dir: Path, facts: Iterable[Mapping[str, object]]) -> tuple[Path, ...]:
+        """Write generated files under `out_dir` from `facts` and return their paths."""
+        ...

chipgraph/core/plugin_api/registry.py

@@ -0,0 +1,111 @@
+"""The plugin registry: where adapters, checks and other plugins register themselves.
+
+Plugins register either directly (`Registry.register`) or by Python entry points
+(`Registry.discover`), under the group `chipgraph.adapters.<kind>` for each kind in `KINDS`.
+"""
+
+from __future__ import annotations
+
+import inspect
+from importlib.metadata import entry_points
+from typing import Any
+
+from chipgraph.core.plugin_api.protocols import (
+    AgentRuntime,
+    Check,
+    Extractor,
+    FormatAdapter,
+    Generator,
+    LlmProvider,
+    LogParser,
+    ReviewAdapter,
+    Runner,
+    ToolAdapter,
+    VcsAdapter,
+)
+
+KINDS: dict[str, type] = {
+    "runner": Runner,
+    "parser": LogParser,
+    "tool": ToolAdapter,
+    "check": Check,
+    "vcs": VcsAdapter,
+    "review": ReviewAdapter,
+    "llm": LlmProvider,
+    "runtime": AgentRuntime,
+    "format": FormatAdapter,
+    "extractor": Extractor,
+    "generator": Generator,
+}
+"""Maps a plugin kind name to the protocol it must satisfy."""
+
+
+class PluginError(Exception):
+    """Raised for any registry or pack error: unknown kind, duplicate name, bad plugin, ..."""
+
+
+class Registry:
+    """Holds registered plugin instances, keyed by kind and name."""
+
+    def __init__(self) -> None:
+        self._plugins: dict[str, dict[str, object]] = {kind: {} for kind in KINDS}
+
+    def register(self, kind: str, name: str, obj: object) -> None:
+        """Register `obj` under `kind`/`name`.
+
+        Raises `PluginError` if `kind` is unknown, `name` is already registered for that
+        kind, or `obj` does not satisfy the protocol for `kind`.
+        """
+        if kind not in KINDS:
+            raise PluginError(f"unknown plugin kind {kind!r}; known kinds: {sorted(KINDS)}")
+        if name in self._plugins[kind]:
+            raise PluginError(f"{kind}/{name} is already registered")
+        protocol = KINDS[kind]
+        if not isinstance(obj, protocol):
+            raise PluginError(
+                f"{obj!r} does not satisfy the {protocol.__name__} protocol for kind {kind!r}"
+            )
+        self._plugins[kind][name] = obj
+
+    def get(self, kind: str, name: str) -> Any:
+        """Return the plugin registered under `kind`/`name`.
+
+        Raises `PluginError` if `kind` is unknown, listing the registered names otherwise.
+        """
+        if kind not in KINDS:
+            raise PluginError(f"unknown plugin kind {kind!r}; known kinds: {sorted(KINDS)}")
+        try:
+            return self._plugins[kind][name]
+        except KeyError:
+            available = sorted(self._plugins[kind])
+            raise PluginError(f"no {kind} plugin named {name!r}; available: {available}") from None
+
+    def names(self, kind: str) -> tuple[str, ...]:
+        """Return the sorted names registered under `kind`."""
+        if kind not in KINDS:
+            raise PluginError(f"unknown plugin kind {kind!r}; known kinds: {sorted(KINDS)}")
+        return tuple(sorted(self._plugins[kind]))
+
+    def discover(self) -> int:
+        """Load plugins from Python entry points, one group per kind.
+
+        For each kind, entry points under group `chipgraph.adapters.<kind>` are loaded.
+        A loaded object that is a class or a no-argument factory is called to produce the
+        plugin instance; anything else is registered as-is. Returns the number registered.
+        Any error loading or registering one entry point becomes a `PluginError` naming it.
+        """
+        count = 0
+        for kind in KINDS:
+            group = f"chipgraph.adapters.{kind}"
+            for entry_point in entry_points(group=group):
+                try:
+                    loaded = entry_point.load()
+                    is_factory = inspect.isclass(loaded) or inspect.isfunction(loaded)
+                    obj = loaded() if is_factory else loaded
+                    self.register(kind, entry_point.name, obj)
+                except Exception as exc:
+                    raise PluginError(
+                        f"failed to load entry point {entry_point.name!r} in group {group!r}: {exc}"
+                    ) from exc
+                count += 1
+        return count

chipgraph/core/plugin_api/types.py

@@ -0,0 +1,94 @@
+"""Shared plugin types: in-process data passed to and from plugin protocols.
+
+These models are not persisted (no `schema_version`) and are not part of the artifact
+store; they only carry data between core and adapters/packs during a single run.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from chipgraph.core.contracts import Budget, DataLabel, RuleInstance
+
+if TYPE_CHECKING:
+    from chipgraph.core.plugin_api.protocols import Runner
+
+
+class RunResult(BaseModel):
+    """The outcome of running a subprocess command via a `Runner`."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    returncode: int = Field(description="The process's exit code.")
+    stdout: str = Field(description="Captured standard output.")
+    stderr: str = Field(description="Captured standard error.")
+    duration_s: float = Field(ge=0, description="How long the command took, in seconds.")
+    timed_out: bool = Field(default=False, description="Whether the command was killed on timeout.")
+
+
+class ToolContext(BaseModel):
+    """Context a `ToolAdapter` or `Check` runs with: repo, runner, env, and free params."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True, arbitrary_types_allowed=True)
+
+    repo_root: Path = Field(description="Root of the repo (or workspace member) being worked on.")
+    runner: Runner = Field(description="The subprocess runner to use for any command.")
+    env: dict[str, str] = Field(default={}, description="Extra environment variables.")
+    params: dict[str, str] = Field(
+        default={}, description="Free-form parameters, e.g. block, module."
+    )
+
+
+class LlmMessage(BaseModel):
+    """A single message in an LLM conversation."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    role: Literal["system", "user", "assistant"] = Field(description="Who sent this message.")
+    content: str = Field(description="The message text.")
+
+
+class LlmRequest(BaseModel):
+    """A request to complete a conversation with an LLM."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    model: str = Field(description="The model id to use.")
+    messages: tuple[LlmMessage, ...] = Field(min_length=1, description="The conversation so far.")
+    max_tokens: int = Field(ge=1, description="Maximum number of tokens to generate.")
+    labels: tuple[DataLabel, ...] = Field(
+        default=(),
+        description=(
+            "Data labels of everything in the context. A provider must refuse a request "
+            "carrying 'nda' unless it is local (see LlmProvider.local)."
+        ),
+    )
+
+
+class LlmResponse(BaseModel):
+    """The result of completing an LLM request."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    text: str = Field(description="The generated text.")
+    input_tokens: int = Field(ge=0, description="Tokens consumed by the input.")
+    output_tokens: int = Field(ge=0, description="Tokens consumed by the output.")
+    model: str = Field(description="The model id that actually served the request.")
+
+
+class AgentTask(BaseModel):
+    """A single task handed to an `AgentRuntime`: what to do, and under what constraints."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    instance: RuleInstance = Field(description="The rule instance this task fulfils.")
+    role: str = Field(description="The agent role that runs this task.")
+    skills: tuple[str, ...] = Field(default=(), description="Skill ids available to the agent.")
+    allowed_writes: tuple[str, ...] = Field(
+        min_length=1, description="Repo-relative paths the agent is allowed to write."
+    )
+    context: dict[str, str] = Field(default={}, description="Free-form context for the agent.")
+    budget: Budget = Field(description="Resource budget for this task.")

chipgraph/core/runtime/__init__.py

@@ -0,0 +1,41 @@
+"""Agent runtime state: the task queue an out-of-process agent runtime works from, and
+the executor that hands agent rules to an `AgentRuntime` (DESIGN.md 5.2, 5.5; D35). The
+roles and skills, as data, are in `chipgraph.core.runtime.roles` (DESIGN.md 5.1; D8).
+
+`chipgraph.core.runtime` is generic: it knows nothing about any agent harness, model or
+tool. Runtimes live in `chipgraph.adapters.runtime`.
+"""
+
+from chipgraph.core.runtime.executor import (
+    AgentRuntimeExecutor,
+    instance_inputs_hash,
+    outcome_for,
+    task_for,
+)
+from chipgraph.core.runtime.queue import (
+    ACTIVE_STATUSES,
+    DEFAULT_TOOL_CALL_CAP,
+    OPEN_STATUSES,
+    AgentBinding,
+    AgentTaskRecord,
+    QueueError,
+    TaskQueue,
+    TaskStatus,
+    state_key,
+)
+
+__all__ = [
+    "ACTIVE_STATUSES",
+    "DEFAULT_TOOL_CALL_CAP",
+    "OPEN_STATUSES",
+    "AgentBinding",
+    "AgentRuntimeExecutor",
+    "AgentTaskRecord",
+    "QueueError",
+    "TaskQueue",
+    "TaskStatus",
+    "instance_inputs_hash",
+    "outcome_for",
+    "state_key",
+    "task_for",
+]

chipgraph/core/runtime/executor.py

@@ -0,0 +1,79 @@
+"""`AgentRuntimeExecutor`: runs `kind: agent` rules through an `AgentRuntime` (DESIGN.md 5.2).
+
+The scheduler knows `Executor`s; agent runtimes implement `AgentRuntime.run_task`. This
+executor turns a rule instance into an `AgentTask` (role, skills, budget, and the
+instance's concrete outputs as the only files the agent may write) and maps the
+runtime's `AgentResult` back to an `ExecOutcome`:
+
+- `done` -> ok; the scheduler then runs the rule's checks and records the outputs.
+- `needs_human` -> not ok (`planning`): the open questions are the message. A runtime
+  that runs outside the engine uses this for "the task is waiting for an agent" too.
+- `budget_exhausted` / `failed` -> not ok (`verification`).
+"""
+
+from __future__ import annotations
+
+from chipgraph.core.contracts import AgentResult, RuleInstance, RuleSpec
+from chipgraph.core.contracts.types import FailureLabel
+from chipgraph.core.engine.scheduler import ExecOutcome
+from chipgraph.core.plugin_api.protocols import AgentRuntime
+from chipgraph.core.plugin_api.types import AgentTask
+from chipgraph.core.state.artifacts import ArtifactStore, hash_inputs
+
+
+def instance_inputs_hash(store: ArtifactStore, instance: RuleInstance) -> str:
+    """A hash over the instance's inputs, the same way the scheduler's records hash them.
+
+    File inputs hash their content (a missing file counts as empty); model inputs are
+    keyed by their model key only, since the Design Model hashes its own entities.
+    """
+    path_refs = [ref for ref in instance.inputs if ref.path is not None]
+    current = store.current_hashes(path_refs)
+    pairs = []
+    for ref in instance.inputs:
+        locator = ref.path if ref.path is not None else ref.model_key
+        key = f"{ref.repo}:{locator}"
+        pairs.append((key, current.get(key, "")))
+    return hash_inputs(pairs)
+
+
+def task_for(rule: RuleSpec, instance: RuleInstance) -> AgentTask:
+    """The `AgentTask` for one instance of an agent rule."""
+    if rule.role is None:
+        raise ValueError(f"rule {rule.id!r} has no role")
+    writes = tuple(ref.path for ref in instance.outputs if ref.path is not None)
+    return AgentTask(
+        instance=instance,
+        role=rule.role,
+        skills=rule.skills,
+        allowed_writes=writes,
+        budget=rule.budget,
+    )
+
+
+def outcome_for(result: AgentResult, *, task_id: str) -> ExecOutcome:
+    """Map an `AgentResult` to the scheduler's `ExecOutcome`."""
+    if result.status == "done":
+        return ExecOutcome(ok=True)
+    label: FailureLabel = "planning" if result.status == "needs_human" else "verification"
+    detail = "; ".join(result.open_questions)
+    default = f"agent task {task_id!r} ended with status {result.status!r}"
+    return ExecOutcome(ok=False, failure_label=label, message=detail or default)
+
+
+class AgentRuntimeExecutor:
+    """An `Executor` for `kind: agent` rules, backed by an `AgentRuntime`."""
+
+    def __init__(self, runtime: AgentRuntime) -> None:
+        self.runtime = runtime
+
+    async def execute(self, rule: RuleSpec, instance: RuleInstance) -> ExecOutcome:
+        try:
+            task = task_for(rule, instance)
+        except ValueError as exc:
+            return ExecOutcome(ok=False, failure_label="planning", message=str(exc))
+        result = await self.runtime.run_task(task)
+        return outcome_for(result, task_id=instance.instance_id)
+
+
+__all__ = ["AgentRuntimeExecutor", "instance_inputs_hash", "outcome_for", "task_for"]