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

atomicguard/domain/interfaces.py

@@ -13,10 +13,9 @@ if TYPE_CHECKING:
         Artifact,
         Context,
         GuardResult,
+        HumanAmendment,
+        WorkflowCheckpoint,
     )
-
-if TYPE_CHECKING:
-    from atomicguard.domain.models import Artifact, Context, GuardResult
     from atomicguard.domain.prompts import PromptTemplate
 
 
@@ -25,11 +24,29 @@ class GeneratorInterface(ABC):
     Port for artifact generation.
 
     Implementations connect to LLMs or other generation sources.
+
+    Note (Hierarchical Composition & Semantic Agency):
+        The generator is not constrained to a single inference step. It may be
+        instantiated as an autonomous Semantic Agent (ReAct loop, CoT reasoning,
+        multi-tool orchestration) operating within the stochastic environment.
+        From the workflow's perspective, this agentic process is atomic — the
+        Workflow State tracks only the final artifact's validity via the Guard.
+
+    Note (Side Effects & Idempotency):
+        While generate() formally produces an artifact, implementations
+        may induce side effects (filesystem I/O, API calls). In such cases:
+        1. The artifact serves as a receipt/manifest of the operation
+        2. Guards act as sensors verifying environmental state
+        3. Side-effecting generators MUST be idempotent for retry safety
     """
 
     @abstractmethod
     def generate(
-        self, context: "Context", template: Optional["PromptTemplate"] = None
+        self,
+        context: "Context",
+        template: Optional["PromptTemplate"] = None,
+        action_pair_id: str = "unknown",
+        workflow_id: str = "unknown",
     ) -> "Artifact":
         """
         Generate an artifact based on context.
@@ -37,6 +54,8 @@ class GeneratorInterface(ABC):
         Args:
             context: The generation context including specification and feedback
             template: Optional prompt template for structured generation
+            action_pair_id: Identifier for the action pair requesting generation
+            workflow_id: UUID of the workflow execution instance
 
         Returns:
             A new Artifact containing the generated content
@@ -76,13 +95,12 @@ class ArtifactDAGInterface(ABC):
     """
 
     @abstractmethod
-    def store(self, artifact: "Artifact", metadata: str = "") -> str:
+    def store(self, artifact: "Artifact") -> str:
         """
         Store an artifact in the DAG.
 
         Args:
             artifact: The artifact to store
-            metadata: Optional metadata string
 
         Returns:
             The artifact_id
@@ -117,3 +135,116 @@ class ArtifactDAGInterface(ABC):
             List of artifacts from oldest to newest in the chain
         """
         pass
+
+    @abstractmethod
+    def get_latest_for_action_pair(
+        self, action_pair_id: str, workflow_id: str
+    ) -> Optional["Artifact"]:
+        """
+        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
+        """
+        pass
+
+
+class CheckpointDAGInterface(ABC):
+    """
+    Port for checkpoint persistence.
+
+    Provides storage for workflow checkpoints and human amendments,
+    enabling resumable workflows after failure/escalation.
+    """
+
+    @abstractmethod
+    def store_checkpoint(self, checkpoint: "WorkflowCheckpoint") -> str:
+        """
+        Store a checkpoint and return its ID.
+
+        Args:
+            checkpoint: The checkpoint to store
+
+        Returns:
+            The checkpoint_id
+        """
+        pass
+
+    @abstractmethod
+    def get_checkpoint(self, checkpoint_id: str) -> "WorkflowCheckpoint":
+        """
+        Retrieve checkpoint by ID.
+
+        Args:
+            checkpoint_id: The unique identifier
+
+        Returns:
+            The checkpoint
+
+        Raises:
+            KeyError: If checkpoint not found
+        """
+        pass
+
+    @abstractmethod
+    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
+        """
+        pass
+
+    @abstractmethod
+    def get_amendment(self, amendment_id: str) -> "HumanAmendment":
+        """
+        Retrieve amendment by ID.
+
+        Args:
+            amendment_id: The unique identifier
+
+        Returns:
+            The amendment
+
+        Raises:
+            KeyError: If amendment not found
+        """
+        pass
+
+    @abstractmethod
+    def get_amendments_for_checkpoint(
+        self, checkpoint_id: str
+    ) -> list["HumanAmendment"]:
+        """
+        Get all amendments for a checkpoint.
+
+        Args:
+            checkpoint_id: The checkpoint identifier
+
+        Returns:
+            List of amendments linked to this checkpoint
+        """
+        pass
+
+    @abstractmethod
+    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
+        """
+        pass

atomicguard/domain/models.py

@@ -27,6 +27,14 @@ class ArtifactStatus(Enum):
     SUPERSEDED = "superseded"  # Guard returned ⊤, but later attempt also passed
 
 
+class ArtifactSource(Enum):
+    """Origin of artifact content."""
+
+    GENERATED = "generated"  # LLM-generated
+    HUMAN = "human"  # Human-provided during amendment
+    IMPORTED = "imported"  # Imported from external source
+
+
 @dataclass(frozen=True)
 class FeedbackEntry:
     """Single entry in feedback history H."""
@@ -39,10 +47,13 @@ class FeedbackEntry:
 class ContextSnapshot:
     """Immutable context C that conditioned generation (Definition 5)."""
 
+    workflow_id: str  # UUID of the workflow execution instance
     specification: str  # Ψ - static specification
     constraints: str  # Ω - global constraints
     feedback_history: tuple[FeedbackEntry, ...]  # H - accumulated rejections
-    dependency_ids: tuple[str, ...]  # Artifact IDs from prior workflow steps
+    dependency_artifacts: tuple[
+        tuple[str, str], ...
+    ] = ()  # (action_pair_id, artifact_id) - matches schema
 
 
 @dataclass(frozen=True)
@@ -55,11 +66,13 @@ class Artifact:
 
     # Identity
     artifact_id: str  # Unique identifier (UUID)
+    workflow_id: str  # UUID of the workflow execution instance
     content: str  # The generated code/text
 
     # DAG Structure
     previous_attempt_id: str | None  # Retry chain within same action pair
-    # Cross-step deps are in context.dependency_ids
+    parent_action_pair_id: str | None  # Parent hierarchy for composite generators
+    # Cross-step deps are in context.dependency_artifacts
 
     # Action Pair Coupling (Definition 6: A = ⟨ρ, a_gen, G⟩)
     action_pair_id: str  # Which action pair produced this
@@ -71,6 +84,7 @@ class Artifact:
     guard_result: bool | None  # ⊤ or ⊥ (None if pending)
     feedback: str  # φ - guard feedback (empty if passed)
     context: ContextSnapshot  # Full context snapshot at generation time
+    source: ArtifactSource = ArtifactSource.GENERATED  # Origin of content
 
 
 # =============================================================================
@@ -84,6 +98,7 @@ class GuardResult:
 
     passed: bool
     feedback: str = ""
+    fatal: bool = False  # ⊥_fatal - skip retry, escalate to human
 
 
 # =============================================================================
@@ -107,9 +122,16 @@ class Context:
     specification: str
     current_artifact: str | None = None
     feedback_history: tuple[tuple[str, str], ...] = ()
-    dependencies: tuple[
-        tuple[str, "Artifact"], ...
-    ] = ()  # (key, artifact) pairs from prior steps
+    dependency_artifacts: tuple[
+        tuple[str, str], ...
+    ] = ()  # (action_pair_id, artifact_id) - matches schema
+
+    def get_dependency(self, action_pair_id: str) -> str | None:
+        """Look up artifact_id by action_pair_id."""
+        for key, artifact_id in self.dependency_artifacts:
+            if key == action_pair_id:
+                return artifact_id
+        return None
 
 
 # =============================================================================
@@ -117,6 +139,15 @@ class Context:
 # =============================================================================
 
 
+class WorkflowStatus(Enum):
+    """Workflow execution outcome."""
+
+    SUCCESS = "success"  # All steps completed
+    FAILED = "failed"  # Rmax exhausted on a step
+    ESCALATION = "escalation"  # Fatal guard triggered
+    CHECKPOINT = "checkpoint"  # Workflow paused, checkpoint created for resume
+
+
 @dataclass
 class WorkflowState:
     """Mutable workflow state tracking guard satisfaction."""
@@ -139,7 +170,90 @@ class WorkflowState:
 class WorkflowResult:
     """Result of workflow execution."""
 
-    success: bool
+    status: WorkflowStatus
     artifacts: dict[str, Artifact]
     failed_step: str | None = None
     provenance: tuple[tuple[Artifact, str], ...] = ()
+    escalation_artifact: Artifact | None = None  # Artifact that triggered escalation
+    escalation_feedback: str = ""  # Fatal feedback message
+    checkpoint: "WorkflowCheckpoint | None" = None  # For CHECKPOINT status
+
+
+# =============================================================================
+# CHECKPOINT AND HUMAN AMENDMENT (Resumable Workflow Support)
+# =============================================================================
+
+
+class FailureType(Enum):
+    """Type of workflow failure that triggered checkpoint."""
+
+    ESCALATION = "escalation"  # Guard returned ⊥_fatal
+    RMAX_EXHAUSTED = "rmax_exhausted"  # Retry budget exhausted
+
+
+@dataclass(frozen=True)
+class WorkflowCheckpoint:
+    """
+    Immutable checkpoint capturing workflow state at failure.
+
+    Enables resumption after human amendment by preserving:
+    - Original workflow context and configuration
+    - Completed steps and their artifacts
+    - Failure details for human review
+    """
+
+    # Identity
+    checkpoint_id: str  # UUID
+    workflow_id: str  # Original workflow execution ID
+    created_at: str  # ISO timestamp
+
+    # Workflow Context
+    specification: str  # Original Ψ
+    constraints: str  # Original Ω
+    rmax: int  # Original retry budget
+
+    # Completed State
+    completed_steps: tuple[str, ...]  # guard_ids that passed
+    artifact_ids: tuple[tuple[str, str], ...]  # (guard_id, artifact_id) pairs
+
+    # Failure Details
+    failure_type: FailureType
+    failed_step: str  # guard_id where failure occurred
+    failed_artifact_id: str | None  # Last artifact before failure
+    failure_feedback: str  # Error/feedback message
+    provenance_ids: tuple[str, ...]  # Artifact IDs of all failed attempts
+
+
+class AmendmentType(Enum):
+    """Type of human amendment."""
+
+    ARTIFACT = "artifact"  # Human provides new artifact content
+    FEEDBACK = "feedback"  # Human provides additional guidance for LLM retry
+    SKIP = "skip"  # Human approves skipping this step (for optional steps)
+
+
+@dataclass(frozen=True)
+class HumanAmendment:
+    """
+    Immutable record of human intervention in a workflow.
+
+    Creates a link in the DAG provenance chain from the failed artifact
+    to the human-provided amendment.
+    """
+
+    # Identity
+    amendment_id: str  # UUID
+    checkpoint_id: str  # Links to WorkflowCheckpoint
+    amendment_type: AmendmentType
+    created_at: str  # ISO timestamp
+    created_by: str  # Human identifier (e.g., username, "cli")
+
+    # Content
+    content: str  # Human-provided artifact or feedback
+    context: str = ""  # Additional context/clarification
+
+    # Provenance
+    parent_artifact_id: str | None = None  # Links to failed artifact in DAG
+
+    # Resume Options
+    additional_rmax: int = 0  # Extra retries beyond original budget

atomicguard/guards/__init__.py

@@ -3,17 +3,28 @@ Guards for the Dual-State Framework.
 
 Guards are deterministic validators that return ⊤ (pass) or ⊥ (fail with feedback).
 They can be composed using CompositeGuard for layered validation.
+
+Organization by validation profile:
+- static/: Pure AST-based validation (no execution)
+- dynamic/: Subprocess-based validation (test execution)
+- interactive/: Human-in-loop validation
+- composite/: Guard composition patterns
 """
 
-from atomicguard.guards.base import CompositeGuard
-from atomicguard.guards.human import HumanReviewGuard
-from atomicguard.guards.syntax import SyntaxGuard
-from atomicguard.guards.test_runner import DynamicTestGuard, TestGuard
+from atomicguard.guards.composite import CompositeGuard
+from atomicguard.guards.dynamic import DynamicTestGuard, TestGuard
+from atomicguard.guards.interactive import HumanReviewGuard
+from atomicguard.guards.static import ImportGuard, SyntaxGuard
 
 __all__ = [
-    "CompositeGuard",
+    # Static guards (pure, fast)
     "SyntaxGuard",
+    "ImportGuard",
+    # Dynamic guards (subprocess-based)
     "TestGuard",
     "DynamicTestGuard",
+    # Interactive guards (human-in-loop)
     "HumanReviewGuard",
+    # Composition patterns
+    "CompositeGuard",
 ]

atomicguard/guards/composite/__init__.py

@@ -0,0 +1,11 @@
+"""
+Composite guards - Guard composition patterns.
+
+These guards combine multiple guards using logical operators.
+"""
+
+from atomicguard.guards.composite.base import CompositeGuard
+
+__all__ = [
+    "CompositeGuard",
+]

atomicguard/guards/dynamic/__init__.py

@@ -0,0 +1,13 @@
+"""
+Dynamic guards - Subprocess-based validation with code execution.
+
+These guards run code in isolated subprocesses for safety.
+They are slower but can validate runtime behavior.
+"""
+
+from atomicguard.guards.dynamic.test_runner import DynamicTestGuard, TestGuard
+
+__all__ = [
+    "DynamicTestGuard",
+    "TestGuard",
+]

atomicguard/guards/dynamic/test_runner.py

@@ -0,0 +1,207 @@
+"""
+Test execution guards.
+
+Guards that validate artifacts by running tests against them.
+"""
+
+import multiprocessing
+import sys
+from typing import Any
+
+from atomicguard.domain.interfaces import GuardInterface
+from atomicguard.domain.models import Artifact, GuardResult
+
+
+class TestGuard(GuardInterface):
+    """
+    Validates artifact via test execution in the same process.
+
+    Simple guard that executes test code against artifact content.
+    For isolation, use DynamicTestGuard instead.
+    """
+
+    def __init__(self, test_code: str | None = None):
+        """
+        Args:
+            test_code: Static test code to run (if not using dependencies)
+        """
+        self._static_test_code = test_code
+
+    def validate(self, artifact: Artifact, **deps: Any) -> GuardResult:
+        """
+        Execute test code against artifact.
+
+        Args:
+            artifact: The implementation artifact to test
+            **deps: May include 'test' artifact with test code
+
+        Returns:
+            GuardResult with test outcome
+        """
+        # Auto-detect first dependency (test guards typically have exactly one)
+        test_artifact = next(iter(deps.values()), None) if deps else None
+        test_code = test_artifact.content if test_artifact else self._static_test_code
+
+        if not test_code:
+            return GuardResult(passed=False, feedback="No test code provided")
+
+        namespace: dict[str, Any] = {}
+        try:
+            exec(artifact.content, namespace)
+            exec(test_code, namespace)
+            return GuardResult(passed=True)
+        except AssertionError as e:
+            return GuardResult(passed=False, feedback=f"Test failed: {e}")
+        except Exception as e:
+            return GuardResult(passed=False, feedback=f"{type(e).__name__}: {e}")
+
+
+class DynamicTestGuard(GuardInterface):
+    """
+    Runs test code against implementation in isolated subprocess.
+
+    Can receive test code from:
+    1. Constructor parameter (test_code) - for config-driven workflows
+    2. Dependency artifact (deps['test']) - for multi-step TDD workflows
+
+    Executes tests and returns pass/fail with detailed feedback.
+
+    Uses multiprocessing for isolation to prevent test code from
+    affecting the parent process.
+    """
+
+    def __init__(self, timeout: float = 60.0, test_code: str | None = None):
+        """
+        Args:
+            timeout: Maximum time in seconds to wait for test execution
+            test_code: Static test code to run (if not using dependencies)
+        """
+        self.timeout = timeout
+        self._static_test_code = test_code
+
+    def validate(self, artifact: Artifact, **deps: Any) -> GuardResult:
+        """
+        Run tests in isolated subprocess.
+
+        Args:
+            artifact: The implementation artifact to test
+            **deps: May include 'test' artifact with test code
+
+        Returns:
+            GuardResult with test outcome
+        """
+        # Auto-detect first dependency (test guards typically have exactly one)
+        test_artifact = next(iter(deps.values()), None) if deps else None
+        test_code = test_artifact.content if test_artifact else self._static_test_code
+
+        if not test_code:
+            return GuardResult(
+                passed=False,
+                feedback="No test code provided (via dependency or config)",
+            )
+
+        q: multiprocessing.Queue = multiprocessing.Queue()
+        p = multiprocessing.Process(
+            target=self._run_tests, args=(artifact.content, test_code, q)
+        )
+        p.start()
+        p.join(self.timeout)
+
+        if p.is_alive():
+            p.terminate()
+            p.join()
+            return GuardResult(
+                passed=False,
+                feedback=f"Timeout: Test execution exceeded {self.timeout}s",
+            )
+
+        if not q.empty():
+            passed, msg = q.get()
+            return GuardResult(passed=passed, feedback=msg)
+        return GuardResult(passed=False, feedback="Test execution crashed")
+
+    def _run_tests(self, impl_code: str, test_code: str, q: Any) -> None:
+        """
+        Execute tests using pytest in an isolated temp directory.
+
+        This method runs in a forked process for isolation.
+        Supports pytest classes, fixtures, and parameterized tests.
+
+        Args:
+            impl_code: The implementation code to test
+            test_code: The test code to run against the implementation
+            q: Queue to send results back to parent process
+        """
+        import os
+        import tempfile
+        from io import StringIO
+
+        if not impl_code:
+            q.put((False, "No implementation code"))
+            return
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Write implementation as importable module
+            impl_path = os.path.join(tmpdir, "implementation.py")
+            with open(impl_path, "w") as f:
+                f.write(impl_code)
+
+            # Write test file
+            test_path = os.path.join(tmpdir, "test_generated.py")
+            with open(test_path, "w") as f:
+                f.write(test_code)
+
+            # Add tmpdir to sys.path for imports
+            sys.path.insert(0, tmpdir)
+
+            try:
+                import pytest
+
+                # Capture pytest output
+                captured_output = StringIO()
+
+                class OutputCapture:
+                    """Pytest plugin to capture failure output."""
+
+                    @pytest.hookimpl(hookwrapper=True)
+                    def pytest_runtest_logreport(self, report: Any) -> Any:
+                        yield
+                        if report.failed:
+                            captured_output.write(
+                                f"{report.nodeid}: {report.longreprtext}\n"
+                            )
+
+                # Run pytest
+                exit_code = pytest.main(
+                    [
+                        test_path,
+                        "-v",
+                        "--tb=short",
+                        "-q",
+                        "--no-header",
+                    ],
+                    plugins=[OutputCapture()],
+                )
+
+                if exit_code == pytest.ExitCode.OK:
+                    q.put((True, "All tests passed"))
+                elif exit_code == pytest.ExitCode.NO_TESTS_COLLECTED:
+                    q.put((False, "No tests collected by pytest"))
+                else:
+                    output = captured_output.getvalue()
+                    if output:
+                        q.put((False, f"Test failures:\n{output}"))
+                    else:
+                        q.put((False, f"pytest exited with code {exit_code}"))
+
+            except SyntaxError as e:
+                q.put((False, f"Syntax error: {e}"))
+            except Exception as e:
+                q.put((False, f"pytest execution error: {type(e).__name__}: {e}"))
+            finally:
+                # Clean up sys.path
+                if tmpdir in sys.path:
+                    sys.path.remove(tmpdir)
+                # Clean up implementation module if loaded
+                if "implementation" in sys.modules:
+                    del sys.modules["implementation"]

atomicguard/guards/interactive/__init__.py

@@ -0,0 +1,11 @@
+"""
+Interactive guards - Human-in-the-loop validation.
+
+These guards block workflow execution until human approval.
+"""
+
+from atomicguard.guards.interactive.human import HumanReviewGuard
+
+__all__ = [
+    "HumanReviewGuard",
+]

atomicguard/guards/static/__init__.py

@@ -0,0 +1,13 @@
+"""
+Static guards - Pure AST-based validation with no side effects.
+
+These guards are fast, deterministic, and do not execute code.
+"""
+
+from atomicguard.guards.static.imports import ImportGuard
+from atomicguard.guards.static.syntax import SyntaxGuard
+
+__all__ = [
+    "ImportGuard",
+    "SyntaxGuard",
+]