atomicguard 1.2.0__tar.gz → 2.1.0__tar.gz

{atomicguard-1.2.0/src/atomicguard.egg-info → atomicguard-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomicguard
-Version: 1.2.0
+Version: 2.1.0
 Summary: A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops
 Author-email: Matthew Thompson <thompsonson@gmail.com>
 Maintainer-email: Matthew Thompson <thompsonson@gmail.com>
@@ -30,6 +30,11 @@ Requires-Dist: matplotlib>=3.10.0
 Requires-Dist: openhands-ai>=0.27.0
 Requires-Dist: pydantic-ai>=1.0.0
 Requires-Dist: pytestarch>=4.0.1
+Provides-Extra: experiment
+Requires-Dist: datasets>=2.0.0; extra == "experiment"
+Requires-Dist: huggingface_hub>=0.20; extra == "experiment"
+Requires-Dist: swebench>=2.0.0; extra == "experiment"
+Requires-Dist: docker>=7.0.0; extra == "experiment"
 Dynamic: license-file
 
 # AtomicGuard

{atomicguard-1.2.0 → atomicguard-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atomicguard"
-version = "1.2.0"
+version = "2.1.0"
 description = "A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops"
 readme = "README.md"
 license = { text = "MIT" }
@@ -54,8 +54,15 @@ OllamaGenerator = "atomicguard.infrastructure.llm:OllamaGenerator"
 HuggingFaceGenerator = "atomicguard.infrastructure.llm:HuggingFaceGenerator"
 MockGenerator = "atomicguard.infrastructure.llm:MockGenerator"
 
+[project.optional-dependencies]
+experiment = [
+    "datasets>=2.0.0",
+    "huggingface_hub>=0.20",
+    "swebench>=2.0.0",
+    "docker>=7.0.0",
+]
+
 # Note: Dev dependencies are in [dependency-groups] below, not here.
-# [project.optional-dependencies] is for end-user extras only.
 
 [build-system]
 requires = ["setuptools>=75.0.0", "wheel"]

{atomicguard-1.2.0 → atomicguard-2.1.0}/src/atomicguard/__init__.py

@@ -5,13 +5,14 @@ A framework for managing stochastic LLM outputs through deterministic
 control flow, implementing the formal model from Thompson (2025).
 
 Example:
-    from atomicguard import Workflow, ActionPair
+    from atomicguard import Workflow, ActionPair, PromptTemplate
     from atomicguard.guards import SyntaxGuard
     from atomicguard.infrastructure import OllamaGenerator
 
     generator = OllamaGenerator(model="qwen2.5-coder:7b")
     guard = SyntaxGuard()
-    action_pair = ActionPair(generator=generator, guard=guard)
+    template = PromptTemplate(role="code generator", constraints="write clean Python code", task="generate code")
+    action_pair = ActionPair(generator=generator, guard=guard, prompt_template=template)
 
     workflow = Workflow(rmax=3)
     workflow.add_step('g_code', action_pair=action_pair)
@@ -73,7 +74,7 @@ from atomicguard.infrastructure.persistence import (
     InMemoryArtifactDAG,
 )
 
-__version__ = "1.2.0"
+__version__ = "2.1.0"
 
 __all__ = [
     # Version

{atomicguard-1.2.0 → atomicguard-2.1.0}/src/atomicguard/application/__init__.py

@@ -6,11 +6,16 @@ Contains use cases and orchestration logic that coordinates domain objects.
 
 from atomicguard.application.action_pair import ActionPair
 from atomicguard.application.agent import DualStateAgent
+from atomicguard.application.checkpoint_service import CheckpointService
+from atomicguard.application.resume_service import ResumeResult, WorkflowResumeService
 from atomicguard.application.workflow import Workflow, WorkflowStep
 
 __all__ = [
     "ActionPair",
+    "CheckpointService",
     "DualStateAgent",
+    "ResumeResult",
     "Workflow",
+    "WorkflowResumeService",
     "WorkflowStep",
 ]

{atomicguard-1.2.0 → atomicguard-2.1.0}/src/atomicguard/application/action_pair.py

@@ -22,13 +22,13 @@ class ActionPair:
         self,
         generator: GeneratorInterface,
         guard: GuardInterface,
-        prompt_template: PromptTemplate | None = None,
+        prompt_template: PromptTemplate,
     ):
         """
         Args:
             generator: The artifact generator
             guard: The validator for generated artifacts
-            prompt_template: Optional structured prompt template
+            prompt_template: Structured prompt template for generation
         """
         self._generator = generator
         self._guard = guard

{atomicguard-1.2.0 → atomicguard-2.1.0}/src/atomicguard/application/agent.py

@@ -92,15 +92,14 @@ class DualStateAgent:
                 for a, f in feedback_history
             )
 
-            # Update artifact with guard result AND provenance metadata
+            # Update artifact with full GuardResult (Extension 08: Composite Guards)
             artifact = replace(
                 artifact,
                 previous_attempt_id=previous_id,
                 status=ArtifactStatus.ACCEPTED
                 if result.passed
                 else ArtifactStatus.REJECTED,
-                guard_result=result.passed,
-                feedback=result.feedback,
+                guard_result=result,  # Store full GuardResult, not just bool
                 context=replace(
                     artifact.context,
                     feedback_history=fb_entries,

atomicguard-2.1.0/src/atomicguard/application/checkpoint_service.py

@@ -0,0 +1,130 @@
+"""Application service for checkpoint operations.
+
+Provides clean separation of checkpoint creation from workflow execution,
+with Extension 01 W_ref support for workflow integrity verification.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from atomicguard.domain.models import FailureType, WorkflowCheckpoint
+from atomicguard.domain.workflow import compute_workflow_ref
+
+if TYPE_CHECKING:
+    from atomicguard.domain.interfaces import (
+        ArtifactDAGInterface,
+        CheckpointDAGInterface,
+    )
+
+
+class CheckpointService:
+    """Application service for creating and managing checkpoints.
+
+    Separates checkpoint creation concerns from Workflow execution,
+    enabling cleaner DDD architecture with proper layering.
+    """
+
+    def __init__(
+        self,
+        checkpoint_dag: CheckpointDAGInterface,
+        artifact_dag: ArtifactDAGInterface | None = None,
+    ) -> None:
+        """Initialize checkpoint service.
+
+        Args:
+            checkpoint_dag: DAG for storing checkpoints.
+            artifact_dag: DAG for storing artifacts (optional).
+        """
+        self._checkpoint_dag = checkpoint_dag
+        self._artifact_dag = artifact_dag
+
+    def create_checkpoint(
+        self,
+        workflow_definition: dict,
+        workflow_id: str,
+        specification: str,
+        constraints: str,
+        rmax: int,
+        completed_steps: tuple[str, ...],
+        artifact_ids: tuple[tuple[str, str], ...],
+        failure_type: FailureType,
+        failed_step: str,
+        failed_artifact_id: str | None,
+        failure_feedback: str,
+        provenance_ids: tuple[str, ...],
+    ) -> WorkflowCheckpoint:
+        """Create checkpoint with W_ref for integrity verification.
+
+        Computes the W_ref (content-addressed workflow hash) from the
+        workflow definition and stores it with the checkpoint. This
+        enables resume-time verification that the workflow hasn't changed.
+
+        Args:
+            workflow_definition: Dict representing workflow structure for W_ref computation.
+            workflow_id: UUID of the workflow execution instance.
+            specification: Original task specification (Ψ).
+            constraints: Global constraints (Ω).
+            rmax: Original retry budget.
+            completed_steps: Guard IDs that completed successfully.
+            artifact_ids: (guard_id, artifact_id) pairs for completed artifacts.
+            failure_type: Type of failure (ESCALATION or RMAX_EXHAUSTED).
+            failed_step: Guard ID where failure occurred.
+            failed_artifact_id: ID of the last artifact before failure.
+            failure_feedback: Error/feedback message from the guard.
+            provenance_ids: Artifact IDs of all failed attempts.
+
+        Returns:
+            WorkflowCheckpoint with W_ref for integrity verification.
+        """
+        # Compute W_ref using domain layer (stores in registry for later resolution)
+        w_ref = compute_workflow_ref(workflow_definition, store=True)
+
+        checkpoint = WorkflowCheckpoint(
+            checkpoint_id=str(uuid.uuid4()),
+            workflow_id=workflow_id,
+            created_at=datetime.now(UTC).isoformat(),
+            specification=specification,
+            constraints=constraints,
+            rmax=rmax,
+            completed_steps=completed_steps,
+            artifact_ids=artifact_ids,
+            failure_type=failure_type,
+            failed_step=failed_step,
+            failed_artifact_id=failed_artifact_id,
+            failure_feedback=failure_feedback,
+            provenance_ids=provenance_ids,
+            workflow_ref=w_ref,  # Extension 01: W_ref for integrity
+        )
+
+        self._checkpoint_dag.store_checkpoint(checkpoint)
+        return checkpoint
+
+    def get_checkpoint(self, checkpoint_id: str) -> WorkflowCheckpoint:
+        """Retrieve a checkpoint by ID.
+
+        Args:
+            checkpoint_id: The checkpoint identifier.
+
+        Returns:
+            The WorkflowCheckpoint.
+
+        Raises:
+            KeyError: If checkpoint not found.
+        """
+        return self._checkpoint_dag.get_checkpoint(checkpoint_id)
+
+    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.
+        """
+        return self._checkpoint_dag.list_checkpoints(workflow_id)

atomicguard-2.1.0/src/atomicguard/application/resume_service.py

@@ -0,0 +1,242 @@
+"""Application service for workflow resume operations.
+
+Provides clean separation of resume logic from workflow execution,
+with Extension 01 W_ref support for workflow integrity verification.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from atomicguard.domain.models import (
+    AmendmentType,
+    Artifact,
+    ArtifactStatus,
+    GuardResult,
+    HumanAmendment,
+)
+from atomicguard.domain.workflow import (
+    HumanAmendmentProcessor,
+    WorkflowResumer,
+    compute_workflow_ref,
+)
+
+if TYPE_CHECKING:
+    from atomicguard.domain.interfaces import (
+        ArtifactDAGInterface,
+        CheckpointDAGInterface,
+        GuardInterface,
+    )
+    from atomicguard.domain.models import Context
+    from atomicguard.domain.workflow import RestoredWorkflowState
+
+
+class ResumeResult:
+    """Result of resume operation.
+
+    Attributes:
+        success: Whether the resume completed without errors.
+        artifact: The artifact created from the amendment (if any).
+        guard_result: The guard validation result (if validation occurred).
+        needs_retry: Whether the workflow needs a retry (feedback amendment or guard failure).
+        error: Error message if success is False.
+        amended_context: The amended context for retry (feedback amendment only).
+    """
+
+    def __init__(
+        self,
+        success: bool,
+        artifact: Artifact | None = None,
+        guard_result: GuardResult | None = None,
+        needs_retry: bool = False,
+        error: str | None = None,
+        amended_context: object | None = None,
+    ) -> None:
+        self.success = success
+        self.artifact = artifact
+        self.guard_result = guard_result
+        self.needs_retry = needs_retry
+        self.error = error
+        self.amended_context = amended_context
+
+
+class WorkflowResumeService:
+    """Application service for resuming workflows from checkpoints.
+
+    Delegates to domain layer components (WorkflowResumer, HumanAmendmentProcessor)
+    while providing a clean interface for the presentation layer.
+
+    Extension 01 compliant: Verifies W_ref integrity on resume.
+    """
+
+    def __init__(
+        self,
+        checkpoint_dag: CheckpointDAGInterface,
+        artifact_dag: ArtifactDAGInterface,
+    ) -> None:
+        """Initialize resume service.
+
+        Args:
+            checkpoint_dag: DAG for storing checkpoints and amendments.
+            artifact_dag: DAG for storing artifacts.
+        """
+        self._checkpoint_dag = checkpoint_dag
+        self._artifact_dag = artifact_dag
+
+        # Initialize domain layer components
+        self._resumer = WorkflowResumer(checkpoint_dag, artifact_dag)
+        self._processor = HumanAmendmentProcessor(checkpoint_dag, artifact_dag)
+
+    def resume(
+        self,
+        checkpoint_id: str,
+        amendment: HumanAmendment,
+        current_workflow_definition: dict,
+        guard: GuardInterface,
+        dependencies: dict[str, Artifact] | None = None,
+    ) -> ResumeResult:
+        """Resume workflow from checkpoint with W_ref verification.
+
+        Args:
+            checkpoint_id: ID of checkpoint to resume from.
+            amendment: Human-provided amendment.
+            current_workflow_definition: Current workflow dict for W_ref verification.
+            guard: Guard to validate the human artifact.
+            dependencies: Artifact dependencies for guard validation.
+
+        Returns:
+            ResumeResult with success status and artifact.
+
+        Raises:
+            WorkflowIntegrityError: If workflow changed since checkpoint.
+        """
+        dependencies = dependencies or {}
+
+        # 1. Store amendment (required by HumanAmendmentProcessor)
+        self._checkpoint_dag.store_amendment(amendment)
+
+        # 2. Verify W_ref integrity using domain layer
+        current_w_ref = compute_workflow_ref(current_workflow_definition, store=False)
+        resume_result = self._resumer.resume(checkpoint_id, current_w_ref)
+
+        if not resume_result.success:
+            return ResumeResult(success=False, error=resume_result.error)
+
+        # 3. Process amendment based on type
+        if amendment.amendment_type == AmendmentType.ARTIFACT:
+            return self._handle_artifact_amendment(amendment, guard, dependencies)
+
+        elif amendment.amendment_type == AmendmentType.FEEDBACK:
+            # Return amended context for agent retry
+            amended_context = self._processor.apply_amendment_to_context(
+                amendment.amendment_id
+            )
+            return ResumeResult(
+                success=True,
+                needs_retry=True,
+                amended_context=amended_context,
+            )
+
+        return ResumeResult(
+            success=False, error=f"Unknown amendment type: {amendment.amendment_type}"
+        )
+
+    def _handle_artifact_amendment(
+        self,
+        amendment: HumanAmendment,
+        guard: GuardInterface,
+        dependencies: dict[str, Artifact],
+    ) -> ResumeResult:
+        """Process artifact amendment using domain layer.
+
+        Args:
+            amendment: The human amendment with artifact content.
+            guard: Guard to validate the artifact.
+            dependencies: Artifact dependencies for guard validation.
+
+        Returns:
+            ResumeResult with artifact and guard result.
+        """
+        try:
+            # Create artifact from amendment using domain layer
+            human_artifact = self._processor.create_artifact_from_amendment(
+                amendment.amendment_id
+            )
+        except KeyError as e:
+            return ResumeResult(
+                success=False,
+                error=f"Failed to create artifact from amendment: {e}",
+            )
+        except ValueError as e:
+            return ResumeResult(
+                success=False,
+                error=f"Invalid amendment: {e}",
+            )
+
+        # Validate with guard
+        guard_result = guard.validate(human_artifact, **dependencies)
+
+        if guard_result.passed:
+            # Update artifact status
+            accepted_artifact = replace(
+                human_artifact,
+                status=ArtifactStatus.ACCEPTED,
+                guard_result=guard_result,  # Store full GuardResult
+            )
+            self._artifact_dag.store(accepted_artifact)
+
+            return ResumeResult(
+                success=True,
+                artifact=accepted_artifact,
+                guard_result=guard_result,
+            )
+        else:
+            # Guard failed - return for new checkpoint
+            return ResumeResult(
+                success=True,
+                artifact=human_artifact,
+                guard_result=guard_result,
+                needs_retry=True,
+            )
+
+    def get_restored_state(self, checkpoint_id: str) -> RestoredWorkflowState:
+        """Get restored workflow state from checkpoint.
+
+        Args:
+            checkpoint_id: ID of checkpoint to restore from.
+
+        Returns:
+            RestoredWorkflowState with completed steps and artifact IDs.
+        """
+        return self._resumer.restore_state(checkpoint_id)
+
+    def get_reconstructed_context(self, checkpoint_id: str) -> Context:
+        """Get reconstructed context from checkpoint.
+
+        Args:
+            checkpoint_id: ID of checkpoint.
+
+        Returns:
+            Reconstructed Context.
+        """
+        return self._resumer.reconstruct_context(checkpoint_id)
+
+    def verify_workflow_integrity(
+        self, checkpoint_id: str, current_workflow_definition: dict
+    ) -> bool:
+        """Verify workflow integrity without resuming.
+
+        Args:
+            checkpoint_id: ID of checkpoint to verify against.
+            current_workflow_definition: Current workflow dict.
+
+        Returns:
+            True if workflow matches checkpoint, False otherwise.
+
+        Raises:
+            WorkflowIntegrityError: If workflow changed since checkpoint.
+        """
+        current_w_ref = compute_workflow_ref(current_workflow_definition, store=False)
+        result = self._resumer.resume(checkpoint_id, current_w_ref)
+        return result.success

{atomicguard-1.2.0 → atomicguard-2.1.0}/src/atomicguard/application/workflow.py

@@ -5,6 +5,7 @@ Owns WorkflowState and infers preconditions from step dependencies.
 """
 
 import uuid
+import warnings
 from dataclasses import dataclass, replace
 from datetime import UTC, datetime
 
@@ -175,11 +176,55 @@ class Workflow:
             self._workflow_state.is_satisfied(step.guard_id) for step in self._steps
         )
 
+    def get_workflow_definition(self) -> dict:
+        """Build workflow definition dict for W_ref computation.
+
+        Returns a serializable dict representing the workflow structure.
+        Used by CheckpointService for W_ref computation.
+
+        Returns:
+            Dict with steps, rmax, and constraints for hashing.
+        """
+        return {
+            "steps": [
+                {
+                    "guard_id": step.guard_id,
+                    "requires": list(step.requires),
+                    "deps": list(step.deps),
+                }
+                for step in self._steps
+            ],
+            "rmax": self._rmax,
+            "constraints": self._constraints,
+        }
+
+    def get_step(self, guard_id: str) -> WorkflowStep:
+        """Get a workflow step by guard_id.
+
+        Args:
+            guard_id: The identifier of the step to retrieve.
+
+        Returns:
+            The WorkflowStep with the given guard_id.
+
+        Raises:
+            KeyError: If no step with the given guard_id exists.
+        """
+        for step in self._steps:
+            if step.guard_id == guard_id:
+                return step
+        raise KeyError(f"Step not found: {guard_id}")
+
 
 class ResumableWorkflow(Workflow):
     """
     Workflow with checkpoint and resume support.
 
+    .. deprecated::
+        Use Workflow + CheckpointService + WorkflowResumeService instead.
+        This class is maintained for backwards compatibility but will be
+        removed in a future version.
+
     Extends Workflow with:
     - Automatic checkpoint creation on failure
     - Resume from checkpoint with human amendment
@@ -202,6 +247,12 @@ class ResumableWorkflow(Workflow):
             constraints: Global constraints for the ambient environment
             auto_checkpoint: Create checkpoint on failure (default True)
         """
+        warnings.warn(
+            "ResumableWorkflow is deprecated. Use Workflow + CheckpointService + "
+            "WorkflowResumeService instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(artifact_dag, rmax, constraints)
 
         if checkpoint_dag is None:
@@ -357,7 +408,7 @@ class ResumableWorkflow(Workflow):
                 updated_artifact = replace(
                     human_artifact,
                     status=ArtifactStatus.ACCEPTED,
-                    guard_result=True,
+                    guard_result=result,  # Store full GuardResult
                 )
                 self._dag.store(updated_artifact)
                 self._artifacts[step.guard_id] = updated_artifact
@@ -546,8 +597,7 @@ class ResumableWorkflow(Workflow):
             created_at=datetime.now(UTC).isoformat(),
             attempt_number=attempt_number,
             status=ArtifactStatus.PENDING,
-            guard_result=None,
-            feedback="",
+            guard_result=None,  # Guard result set after validation
             context=context,
             source=ArtifactSource.HUMAN,
         )

{atomicguard-1.2.0 → atomicguard-2.1.0}/src/atomicguard/domain/__init__.py

@@ -18,6 +18,7 @@ from atomicguard.domain.models import (
     ContextSnapshot,
     FeedbackEntry,
     GuardResult,
+    SubGuardOutcome,
     WorkflowResult,
     WorkflowState,
     WorkflowStatus,
@@ -37,6 +38,7 @@ __all__ = [
     "Context",
     "AmbientEnvironment",
     "GuardResult",
+    "SubGuardOutcome",
     "WorkflowState",
     "WorkflowResult",
     "WorkflowStatus",