atomicguard 0.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

atomicguard/infrastructure/persistence/checkpoint.py

@@ -0,0 +1,361 @@
+"""
+Filesystem implementation of the Checkpoint DAG.
+
+Provides persistent storage for workflow checkpoints and human amendments,
+enabling resumable workflows after failure/escalation.
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from atomicguard.domain.interfaces import CheckpointDAGInterface
+from atomicguard.domain.models import (
+    AmendmentType,
+    FailureType,
+    HumanAmendment,
+    WorkflowCheckpoint,
+)
+
+
+class FilesystemCheckpointDAG(CheckpointDAGInterface):
+    """
+    Persistent storage for workflow checkpoints and amendments.
+
+    Directory structure:
+    {base_dir}/
+        checkpoints/
+            {prefix}/{checkpoint_id}.json
+        amendments/
+            {prefix}/{amendment_id}.json
+        checkpoint_index.json  # Maps workflow_id -> checkpoint_ids
+    """
+
+    def __init__(self, base_dir: str):
+        self._base_dir = Path(base_dir)
+        self._checkpoints_dir = self._base_dir / "checkpoints"
+        self._amendments_dir = self._base_dir / "amendments"
+        self._index_path = self._base_dir / "checkpoint_index.json"
+        self._cache_checkpoints: dict[str, WorkflowCheckpoint] = {}
+        self._cache_amendments: dict[str, HumanAmendment] = {}
+        self._index: dict[str, Any] = self._load_or_create_index()
+
+    def _load_or_create_index(self) -> dict[str, Any]:
+        """Load existing index or create new one."""
+        self._base_dir.mkdir(parents=True, exist_ok=True)
+        self._checkpoints_dir.mkdir(parents=True, exist_ok=True)
+        self._amendments_dir.mkdir(parents=True, exist_ok=True)
+
+        if self._index_path.exists():
+            with open(self._index_path) as f:
+                result: dict[str, Any] = json.load(f)
+                return result
+
+        return {
+            "version": "1.0",
+            "checkpoints": {},  # checkpoint_id -> metadata
+            "amendments": {},  # amendment_id -> metadata
+            "by_workflow": {},  # workflow_id -> [checkpoint_ids]
+            "by_checkpoint": {},  # checkpoint_id -> [amendment_ids]
+        }
+
+    def _update_index_atomic(self) -> None:
+        """Atomically update index.json using write-to-temp + rename."""
+        temp_path = self._index_path.with_suffix(".tmp")
+        with open(temp_path, "w") as f:
+            json.dump(self._index, f, indent=2)
+        temp_path.rename(self._index_path)
+
+    def _get_checkpoint_path(self, checkpoint_id: str) -> Path:
+        """Get filesystem path for checkpoint (using prefix directories)."""
+        prefix = checkpoint_id[:2]
+        return self._checkpoints_dir / prefix / f"{checkpoint_id}.json"
+
+    def _get_amendment_path(self, amendment_id: str) -> Path:
+        """Get filesystem path for amendment (using prefix directories)."""
+        prefix = amendment_id[:2]
+        return self._amendments_dir / prefix / f"{amendment_id}.json"
+
+    def _checkpoint_to_dict(self, checkpoint: WorkflowCheckpoint) -> dict:
+        """Serialize checkpoint to JSON-compatible dict."""
+        return {
+            "checkpoint_id": checkpoint.checkpoint_id,
+            "workflow_id": checkpoint.workflow_id,
+            "created_at": checkpoint.created_at,
+            "specification": checkpoint.specification,
+            "constraints": checkpoint.constraints,
+            "rmax": checkpoint.rmax,
+            "completed_steps": list(checkpoint.completed_steps),
+            "artifact_ids": dict(checkpoint.artifact_ids),
+            "failure_type": checkpoint.failure_type.value,
+            "failed_step": checkpoint.failed_step,
+            "failed_artifact_id": checkpoint.failed_artifact_id,
+            "failure_feedback": checkpoint.failure_feedback,
+            "provenance_ids": list(checkpoint.provenance_ids),
+        }
+
+    def _dict_to_checkpoint(self, data: dict) -> WorkflowCheckpoint:
+        """Deserialize checkpoint from JSON dict."""
+        return WorkflowCheckpoint(
+            checkpoint_id=data["checkpoint_id"],
+            workflow_id=data["workflow_id"],
+            created_at=data["created_at"],
+            specification=data["specification"],
+            constraints=data["constraints"],
+            rmax=data["rmax"],
+            completed_steps=tuple(data["completed_steps"]),
+            artifact_ids=tuple(data["artifact_ids"].items()),
+            failure_type=FailureType(data["failure_type"]),
+            failed_step=data["failed_step"],
+            failed_artifact_id=data["failed_artifact_id"],
+            failure_feedback=data["failure_feedback"],
+            provenance_ids=tuple(data["provenance_ids"]),
+        )
+
+    def _amendment_to_dict(self, amendment: HumanAmendment) -> dict:
+        """Serialize amendment to JSON-compatible dict."""
+        return {
+            "amendment_id": amendment.amendment_id,
+            "checkpoint_id": amendment.checkpoint_id,
+            "amendment_type": amendment.amendment_type.value,
+            "created_at": amendment.created_at,
+            "created_by": amendment.created_by,
+            "content": amendment.content,
+            "context": amendment.context,
+            "parent_artifact_id": amendment.parent_artifact_id,
+            "additional_rmax": amendment.additional_rmax,
+        }
+
+    def _dict_to_amendment(self, data: dict) -> HumanAmendment:
+        """Deserialize amendment from JSON dict."""
+        return HumanAmendment(
+            amendment_id=data["amendment_id"],
+            checkpoint_id=data["checkpoint_id"],
+            amendment_type=AmendmentType(data["amendment_type"]),
+            created_at=data["created_at"],
+            created_by=data["created_by"],
+            content=data["content"],
+            context=data.get("context", ""),
+            parent_artifact_id=data.get("parent_artifact_id"),
+            additional_rmax=data.get("additional_rmax", 0),
+        )
+
+    def store_checkpoint(self, checkpoint: WorkflowCheckpoint) -> str:
+        """
+        Store a checkpoint and return its ID.
+
+        Args:
+            checkpoint: The checkpoint to store
+
+        Returns:
+            The checkpoint_id
+        """
+        # 1. Serialize to JSON
+        checkpoint_dict = self._checkpoint_to_dict(checkpoint)
+
+        # 2. Write to checkpoints/{prefix}/{checkpoint_id}.json
+        object_path = self._get_checkpoint_path(checkpoint.checkpoint_id)
+        object_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(object_path, "w") as f:
+            json.dump(checkpoint_dict, f, indent=2)
+
+        # 3. Update index
+        self._index["checkpoints"][checkpoint.checkpoint_id] = {
+            "path": str(object_path.relative_to(self._base_dir)),
+            "workflow_id": checkpoint.workflow_id,
+            "failed_step": checkpoint.failed_step,
+            "failure_type": checkpoint.failure_type.value,
+            "created_at": checkpoint.created_at,
+        }
+
+        # Track by workflow
+        if checkpoint.workflow_id not in self._index["by_workflow"]:
+            self._index["by_workflow"][checkpoint.workflow_id] = []
+        self._index["by_workflow"][checkpoint.workflow_id].append(
+            checkpoint.checkpoint_id
+        )
+
+        # 4. Atomically update index
+        self._update_index_atomic()
+
+        # 5. Add to cache
+        self._cache_checkpoints[checkpoint.checkpoint_id] = checkpoint
+
+        return checkpoint.checkpoint_id
+
+    def get_checkpoint(self, checkpoint_id: str) -> WorkflowCheckpoint:
+        """Retrieve checkpoint by ID (cache-first)."""
+        # Check cache first
+        if checkpoint_id in self._cache_checkpoints:
+            return self._cache_checkpoints[checkpoint_id]
+
+        # Check index
+        if checkpoint_id not in self._index["checkpoints"]:
+            raise KeyError(f"Checkpoint not found: {checkpoint_id}")
+
+        # Load from filesystem
+        rel_path = self._index["checkpoints"][checkpoint_id]["path"]
+        object_path = self._base_dir / rel_path
+
+        with open(object_path) as f:
+            data = json.load(f)
+
+        checkpoint = self._dict_to_checkpoint(data)
+        self._cache_checkpoints[checkpoint_id] = checkpoint
+        return checkpoint
+
+    def store_amendment(self, amendment: HumanAmendment) -> str:
+        """
+        Store a human amendment and return its ID.
+
+        Args:
+            amendment: The amendment to store
+
+        Returns:
+            The amendment_id
+        """
+        # 1. Serialize to JSON
+        amendment_dict = self._amendment_to_dict(amendment)
+
+        # 2. Write to amendments/{prefix}/{amendment_id}.json
+        object_path = self._get_amendment_path(amendment.amendment_id)
+        object_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(object_path, "w") as f:
+            json.dump(amendment_dict, f, indent=2)
+
+        # 3. Update index
+        self._index["amendments"][amendment.amendment_id] = {
+            "path": str(object_path.relative_to(self._base_dir)),
+            "checkpoint_id": amendment.checkpoint_id,
+            "amendment_type": amendment.amendment_type.value,
+            "created_at": amendment.created_at,
+        }
+
+        # Track by checkpoint
+        if amendment.checkpoint_id not in self._index["by_checkpoint"]:
+            self._index["by_checkpoint"][amendment.checkpoint_id] = []
+        self._index["by_checkpoint"][amendment.checkpoint_id].append(
+            amendment.amendment_id
+        )
+
+        # 4. Atomically update index
+        self._update_index_atomic()
+
+        # 5. Add to cache
+        self._cache_amendments[amendment.amendment_id] = amendment
+
+        return amendment.amendment_id
+
+    def get_amendment(self, amendment_id: str) -> HumanAmendment:
+        """Retrieve amendment by ID (cache-first)."""
+        # Check cache first
+        if amendment_id in self._cache_amendments:
+            return self._cache_amendments[amendment_id]
+
+        # Check index
+        if amendment_id not in self._index["amendments"]:
+            raise KeyError(f"Amendment not found: {amendment_id}")
+
+        # Load from filesystem
+        rel_path = self._index["amendments"][amendment_id]["path"]
+        object_path = self._base_dir / rel_path
+
+        with open(object_path) as f:
+            data = json.load(f)
+
+        amendment = self._dict_to_amendment(data)
+        self._cache_amendments[amendment_id] = amendment
+        return amendment
+
+    def get_amendments_for_checkpoint(self, checkpoint_id: str) -> list[HumanAmendment]:
+        """Get all amendments for a checkpoint."""
+        if checkpoint_id not in self._index.get("by_checkpoint", {}):
+            return []
+
+        amendment_ids = self._index["by_checkpoint"][checkpoint_id]
+        return [self.get_amendment(aid) for aid in amendment_ids]
+
+    def list_checkpoints(
+        self, workflow_id: str | None = None
+    ) -> list[WorkflowCheckpoint]:
+        """
+        List checkpoints, optionally filtered by workflow_id.
+
+        Args:
+            workflow_id: Optional filter by workflow
+
+        Returns:
+            List of matching checkpoints, newest first
+        """
+        if workflow_id is not None:
+            # Filter by workflow
+            if workflow_id not in self._index.get("by_workflow", {}):
+                return []
+            checkpoint_ids = self._index["by_workflow"][workflow_id]
+        else:
+            # All checkpoints
+            checkpoint_ids = list(self._index.get("checkpoints", {}).keys())
+
+        # Load checkpoints and sort by created_at descending
+        checkpoints = [self.get_checkpoint(cid) for cid in checkpoint_ids]
+        checkpoints.sort(key=lambda c: c.created_at, reverse=True)
+        return checkpoints
+
+
+class InMemoryCheckpointDAG(CheckpointDAGInterface):
+    """
+    In-memory checkpoint storage for testing.
+    """
+
+    def __init__(self) -> None:
+        self._checkpoints: dict[str, WorkflowCheckpoint] = {}
+        self._amendments: dict[str, HumanAmendment] = {}
+        self._by_workflow: dict[str, list[str]] = {}
+        self._by_checkpoint: dict[str, list[str]] = {}
+
+    def store_checkpoint(self, checkpoint: WorkflowCheckpoint) -> str:
+        self._checkpoints[checkpoint.checkpoint_id] = checkpoint
+
+        if checkpoint.workflow_id not in self._by_workflow:
+            self._by_workflow[checkpoint.workflow_id] = []
+        self._by_workflow[checkpoint.workflow_id].append(checkpoint.checkpoint_id)
+
+        return checkpoint.checkpoint_id
+
+    def get_checkpoint(self, checkpoint_id: str) -> WorkflowCheckpoint:
+        if checkpoint_id not in self._checkpoints:
+            raise KeyError(f"Checkpoint not found: {checkpoint_id}")
+        return self._checkpoints[checkpoint_id]
+
+    def store_amendment(self, amendment: HumanAmendment) -> str:
+        self._amendments[amendment.amendment_id] = amendment
+
+        if amendment.checkpoint_id not in self._by_checkpoint:
+            self._by_checkpoint[amendment.checkpoint_id] = []
+        self._by_checkpoint[amendment.checkpoint_id].append(amendment.amendment_id)
+
+        return amendment.amendment_id
+
+    def get_amendment(self, amendment_id: str) -> HumanAmendment:
+        if amendment_id not in self._amendments:
+            raise KeyError(f"Amendment not found: {amendment_id}")
+        return self._amendments[amendment_id]
+
+    def get_amendments_for_checkpoint(self, checkpoint_id: str) -> list[HumanAmendment]:
+        if checkpoint_id not in self._by_checkpoint:
+            return []
+        return [self._amendments[aid] for aid in self._by_checkpoint[checkpoint_id]]
+
+    def list_checkpoints(
+        self, workflow_id: str | None = None
+    ) -> list[WorkflowCheckpoint]:
+        if workflow_id is not None:
+            if workflow_id not in self._by_workflow:
+                return []
+            checkpoint_ids = self._by_workflow[workflow_id]
+        else:
+            checkpoint_ids = list(self._checkpoints.keys())
+
+        checkpoints = [self._checkpoints[cid] for cid in checkpoint_ids]
+        checkpoints.sort(key=lambda c: c.created_at, reverse=True)
+        return checkpoints

atomicguard/infrastructure/persistence/filesystem.py

@@ -43,7 +43,7 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
                 result: dict[str, Any] = json.load(f)
                 return result
 
-        return {"version": "1.0", "artifacts": {}, "action_pairs": {}}
+        return {"version": "1.0", "artifacts": {}, "action_pairs": {}, "workflows": {}}
 
     def _update_index_atomic(self) -> None:
         """Atomically update index.json using write-to-temp + rename."""
@@ -56,8 +56,10 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
         """Serialize artifact to JSON-compatible dict."""
         return {
             "artifact_id": artifact.artifact_id,
+            "workflow_id": artifact.workflow_id,
             "content": artifact.content,
             "previous_attempt_id": artifact.previous_attempt_id,
+            "parent_action_pair_id": artifact.parent_action_pair_id,
             "action_pair_id": artifact.action_pair_id,
             "created_at": artifact.created_at,
             "attempt_number": artifact.attempt_number,
@@ -65,31 +67,43 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
             "guard_result": artifact.guard_result,
             "feedback": artifact.feedback,
             "context": {
+                "workflow_id": artifact.context.workflow_id,
                 "specification": artifact.context.specification,
                 "constraints": artifact.context.constraints,
                 "feedback_history": [
                     {"artifact_id": fe.artifact_id, "feedback": fe.feedback}
                     for fe in artifact.context.feedback_history
                 ],
-                "dependency_ids": list(artifact.context.dependency_ids),
+                # Serialize tuple → dict for JSON object format (matches schema)
+                "dependency_artifacts": dict(artifact.context.dependency_artifacts),
             },
         }
 
     def _dict_to_artifact(self, data: dict) -> Artifact:
         """Deserialize artifact from JSON dict."""
+        # Handle both old format (dependency_ids) and new format (dependency_artifacts)
+        dep_data = data["context"].get("dependency_artifacts", {})
+        if not dep_data:
+            # Backwards compatibility: convert old flat array to empty dict
+            dep_data = {}
+
         context = ContextSnapshot(
+            workflow_id=data["context"].get("workflow_id", "unknown"),
             specification=data["context"]["specification"],
             constraints=data["context"]["constraints"],
             feedback_history=tuple(
                 FeedbackEntry(artifact_id=fe["artifact_id"], feedback=fe["feedback"])
                 for fe in data["context"]["feedback_history"]
             ),
-            dependency_ids=tuple(data["context"]["dependency_ids"]),
+            # Deserialize dict → tuple for immutability
+            dependency_artifacts=tuple(dep_data.items()),
         )
         return Artifact(
             artifact_id=data["artifact_id"],
+            workflow_id=data.get("workflow_id", "unknown"),
             content=data["content"],
             previous_attempt_id=data["previous_attempt_id"],
+            parent_action_pair_id=data.get("parent_action_pair_id"),
             action_pair_id=data["action_pair_id"],
             created_at=data["created_at"],
             attempt_number=data["attempt_number"],
@@ -104,13 +118,12 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
         prefix = artifact_id[:2]
         return self._objects_dir / prefix / f"{artifact_id}.json"
 
-    def store(self, artifact: Artifact, _metadata: str = "") -> str:
+    def store(self, artifact: Artifact) -> str:
         """
         Append artifact to DAG (immutable, append-only).
 
         Args:
             artifact: The artifact to store
-            metadata: Optional metadata string (for compatibility, stored in feedback)
 
         Returns:
             The artifact_id
@@ -127,7 +140,9 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
         # 3. Update index
         self._index["artifacts"][artifact.artifact_id] = {
             "path": str(object_path.relative_to(self._base_dir)),
+            "workflow_id": artifact.workflow_id,
             "action_pair_id": artifact.action_pair_id,
+            "parent_action_pair_id": artifact.parent_action_pair_id,
             "status": artifact.status.value,
             "created_at": artifact.created_at,
         }
@@ -139,6 +154,13 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
             artifact.artifact_id
         )
 
+        # Track by workflow
+        if "workflows" not in self._index:
+            self._index["workflows"] = {}
+        if artifact.workflow_id not in self._index["workflows"]:
+            self._index["workflows"][artifact.workflow_id] = []
+        self._index["workflows"][artifact.workflow_id].append(artifact.artifact_id)
+
         # 4. Atomically update index
         self._update_index_atomic()
 
@@ -207,8 +229,10 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
         # Create updated artifact (immutable, so we create new instance)
         updated = Artifact(
             artifact_id=artifact.artifact_id,
+            workflow_id=artifact.workflow_id,
             content=artifact.content,
             previous_attempt_id=artifact.previous_attempt_id,
+            parent_action_pair_id=artifact.parent_action_pair_id,
             action_pair_id=artifact.action_pair_id,
             created_at=artifact.created_at,
             attempt_number=artifact.attempt_number,
@@ -230,3 +254,43 @@ class FilesystemArtifactDAG(ArtifactDAGInterface):
 
         # Update cache
         self._cache[artifact_id] = updated
+
+    def get_by_workflow(self, workflow_id: str) -> list[Artifact]:
+        """Get all artifacts for a workflow execution."""
+        if "workflows" not in self._index:
+            return []
+        if workflow_id not in self._index["workflows"]:
+            return []
+
+        artifact_ids = self._index["workflows"][workflow_id]
+        return [self.get_artifact(aid) for aid in artifact_ids]
+
+    def get_latest_for_action_pair(
+        self, action_pair_id: str, workflow_id: str
+    ) -> Artifact | None:
+        """
+        Get the most recent artifact for an action pair in a workflow.
+
+        Args:
+            action_pair_id: The action pair identifier (e.g., 'g_test')
+            workflow_id: UUID of the workflow execution instance
+
+        Returns:
+            The most recent artifact, or None if not found
+        """
+        if action_pair_id not in self._index.get("action_pairs", {}):
+            return None
+
+        # Filter by workflow and find latest by created_at
+        candidates = []
+        for artifact_id in self._index["action_pairs"][action_pair_id]:
+            artifact_info = self._index["artifacts"].get(artifact_id, {})
+            if artifact_info.get("workflow_id") == workflow_id:
+                candidates.append((artifact_id, artifact_info.get("created_at", "")))
+
+        if not candidates:
+            return None
+
+        # Sort by created_at descending and return the latest
+        candidates.sort(key=lambda x: x[1], reverse=True)
+        return self.get_artifact(candidates[0][0])

atomicguard/infrastructure/persistence/memory.py

@@ -13,11 +13,9 @@ class InMemoryArtifactDAG(ArtifactDAGInterface):
 
     def __init__(self) -> None:
         self._artifacts: dict[str, Artifact] = {}
-        self._metadata: dict[str, str] = {}
 
-    def store(self, artifact: Artifact, metadata: str = "") -> str:
+    def store(self, artifact: Artifact) -> str:
         self._artifacts[artifact.artifact_id] = artifact
-        self._metadata[artifact.artifact_id] = metadata
         return artifact.artifact_id
 
     def get_artifact(self, artifact_id: str) -> Artifact:
@@ -37,3 +35,27 @@ class InMemoryArtifactDAG(ArtifactDAGInterface):
                 break
             current = self._artifacts.get(current.previous_attempt_id)
         return list(reversed(result))
+
+    def get_latest_for_action_pair(
+        self, action_pair_id: str, workflow_id: str
+    ) -> Artifact | None:
+        """
+        Get the most recent artifact for an action pair in a workflow.
+
+        Args:
+            action_pair_id: The action pair identifier (e.g., 'g_test')
+            workflow_id: UUID of the workflow execution instance
+
+        Returns:
+            The most recent artifact, or None if not found
+        """
+        candidates = [
+            a
+            for a in self._artifacts.values()
+            if a.action_pair_id == action_pair_id and a.workflow_id == workflow_id
+        ]
+        if not candidates:
+            return None
+        # Sort by created_at descending and return the latest
+        candidates.sort(key=lambda a: a.created_at, reverse=True)
+        return candidates[0]

atomicguard/infrastructure/registry.py

@@ -0,0 +1,126 @@
+"""
+Generator Registry with Entry Points Discovery.
+
+Provides dynamic generator loading via Python entry points (atomicguard.generators group).
+External packages can register generators in their pyproject.toml:
+
+    [project.entry-points."atomicguard.generators"]
+    MyGenerator = "mypackage.generators:MyGenerator"
+"""
+
+from importlib.metadata import entry_points
+from typing import Any
+
+from atomicguard.domain.interfaces import GeneratorInterface
+
+
+class GeneratorRegistry:
+    """
+    Registry for GeneratorInterface implementations.
+
+    Discovers generators via the 'atomicguard.generators' entry point group.
+    Uses lazy loading - entry points are only loaded on first access.
+
+    Example usage:
+        registry = GeneratorRegistry()
+        generator = registry.create("OllamaGenerator", model="qwen2.5-coder:14b")
+    """
+
+    _generators: dict[str, type[GeneratorInterface]] = {}
+    _loaded: bool = False
+
+    @classmethod
+    def _load_entry_points(cls) -> None:
+        """Load generators from entry points (lazy, called once)."""
+        if cls._loaded:
+            return
+
+        eps = entry_points(group="atomicguard.generators")
+        for ep in eps:
+            try:
+                generator_class = ep.load()
+                cls._generators[ep.name] = generator_class
+            except Exception as e:
+                import warnings
+
+                warnings.warn(
+                    f"Failed to load generator '{ep.name}' from entry point: {e}",
+                    stacklevel=2,
+                )
+
+        cls._loaded = True
+
+    @classmethod
+    def register(cls, name: str, generator_class: type[GeneratorInterface]) -> None:
+        """
+        Manually register a generator class.
+
+        Useful for testing or dynamically-created generators.
+
+        Args:
+            name: Generator identifier (e.g., "OllamaGenerator")
+            generator_class: Class implementing GeneratorInterface
+        """
+        cls._generators[name] = generator_class
+
+    @classmethod
+    def get(cls, name: str) -> type[GeneratorInterface]:
+        """
+        Get a generator class by name.
+
+        Args:
+            name: Generator identifier
+
+        Returns:
+            The generator class
+
+        Raises:
+            KeyError: If generator not found
+        """
+        cls._load_entry_points()
+        if name not in cls._generators:
+            available = ", ".join(cls._generators.keys()) or "(none)"
+            raise KeyError(
+                f"Generator '{name}' not found. Available generators: {available}"
+            )
+        return cls._generators[name]
+
+    @classmethod
+    def create(cls, name: str, **config: Any) -> GeneratorInterface:
+        """
+        Create a generator instance by name.
+
+        Args:
+            name: Generator identifier
+            **config: Configuration passed to generator constructor
+
+        Returns:
+            Instantiated generator
+
+        Raises:
+            KeyError: If generator not found
+            TypeError: If config doesn't match constructor signature
+        """
+        generator_class = cls.get(name)
+        return generator_class(**config)
+
+    @classmethod
+    def available(cls) -> list[str]:
+        """
+        List available generator names.
+
+        Returns:
+            List of registered generator names
+        """
+        cls._load_entry_points()
+        return list(cls._generators.keys())
+
+    @classmethod
+    def clear(cls) -> None:
+        """
+        Clear all registered generators (useful for testing).
+
+        Also resets the loaded flag so entry points can be reloaded.
+        """
+        cls._generators.clear()
+        cls._loaded = False