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

atomicguard/domain/extraction.py

@@ -0,0 +1,257 @@
+"""
+Artifact Extraction (Extension 02: Definitions 17-18).
+
+Implements:
+- Predicate base class (Φ: r → {⊤, ⊥})
+- Concrete predicates: StatusPredicate, ActionPairPredicate, WorkflowPredicate, SourcePredicate
+- Compound predicates: AndPredicate, OrPredicate, NotPredicate
+- Extraction function: E: ℛ × Φ → 2^ℛ
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from atomicguard.domain.models import Artifact, ArtifactSource, ArtifactStatus
+
+if TYPE_CHECKING:
+    from atomicguard.domain.interfaces import ArtifactDAGInterface
+
+
+# =============================================================================
+# PREDICATE BASE CLASS (Definition 18)
+# =============================================================================
+
+
+class Predicate(ABC):
+    """
+    Abstract base class for filter predicates Φ: r → {⊤, ⊥} (Definition 18).
+
+    Predicates are boolean functions over repository items that determine
+    whether an artifact should be included in an extraction result.
+    """
+
+    @abstractmethod
+    def matches(self, artifact: Artifact) -> bool:
+        """Evaluate predicate on artifact.
+
+        Args:
+            artifact: The artifact to test.
+
+        Returns:
+            True if artifact matches predicate, False otherwise.
+        """
+        pass
+
+    def __call__(self, artifact: Artifact) -> bool:
+        """Allow predicate(artifact) syntax.
+
+        Enables predicates to be used as Φ(r) per the formal notation.
+        """
+        return self.matches(artifact)
+
+
+# =============================================================================
+# CONCRETE PREDICATES
+# =============================================================================
+
+
+class StatusPredicate(Predicate):
+    """Filter by artifact status (Φ_status).
+
+    Matches artifacts whose status is in the specified set of statuses.
+    """
+
+    def __init__(self, *statuses: ArtifactStatus) -> None:
+        """Initialize with one or more statuses to match.
+
+        Args:
+            *statuses: ArtifactStatus values to match.
+        """
+        self._statuses = set(statuses)
+
+    def matches(self, artifact: Artifact) -> bool:
+        """Check if artifact status is in the specified set."""
+        return artifact.status in self._statuses
+
+
+class ActionPairPredicate(Predicate):
+    """Filter by action pair ID (Φ_action_pair).
+
+    Matches artifacts produced by a specific action pair.
+    """
+
+    def __init__(self, action_pair_id: str) -> None:
+        """Initialize with action pair ID to match.
+
+        Args:
+            action_pair_id: The action_pair_id to match.
+        """
+        self._action_pair_id = action_pair_id
+
+    def matches(self, artifact: Artifact) -> bool:
+        """Check if artifact's action_pair_id matches."""
+        return artifact.action_pair_id == self._action_pair_id
+
+
+class WorkflowPredicate(Predicate):
+    """Filter by workflow ID (Φ_workflow).
+
+    Matches artifacts from a specific workflow execution.
+    """
+
+    def __init__(self, workflow_id: str) -> None:
+        """Initialize with workflow ID to match.
+
+        Args:
+            workflow_id: The workflow_id to match.
+        """
+        self._workflow_id = workflow_id
+
+    def matches(self, artifact: Artifact) -> bool:
+        """Check if artifact's workflow_id matches."""
+        return artifact.workflow_id == self._workflow_id
+
+
+class SourcePredicate(Predicate):
+    """Filter by artifact source (Φ_source).
+
+    Matches artifacts with a specific source (GENERATED, HUMAN, IMPORTED).
+    """
+
+    def __init__(self, source: ArtifactSource) -> None:
+        """Initialize with source to match.
+
+        Args:
+            source: The ArtifactSource to match.
+        """
+        self._source = source
+
+    def matches(self, artifact: Artifact) -> bool:
+        """Check if artifact's source matches."""
+        return artifact.source == self._source
+
+
+# =============================================================================
+# COMPOUND PREDICATES
+# =============================================================================
+
+
+class AndPredicate(Predicate):
+    """Logical AND of two predicates (Φ₁ ∧ Φ₂).
+
+    Matches only if both predicates match.
+    """
+
+    def __init__(self, p1: Predicate, p2: Predicate) -> None:
+        """Initialize with two predicates to AND together.
+
+        Args:
+            p1: First predicate.
+            p2: Second predicate.
+        """
+        self._p1 = p1
+        self._p2 = p2
+
+    def matches(self, artifact: Artifact) -> bool:
+        """Check if both predicates match."""
+        return self._p1.matches(artifact) and self._p2.matches(artifact)
+
+
+class OrPredicate(Predicate):
+    """Logical OR of two predicates (Φ₁ ∨ Φ₂).
+
+    Matches if either predicate matches.
+    """
+
+    def __init__(self, p1: Predicate, p2: Predicate) -> None:
+        """Initialize with two predicates to OR together.
+
+        Args:
+            p1: First predicate.
+            p2: Second predicate.
+        """
+        self._p1 = p1
+        self._p2 = p2
+
+    def matches(self, artifact: Artifact) -> bool:
+        """Check if either predicate matches."""
+        return self._p1.matches(artifact) or self._p2.matches(artifact)
+
+
+class NotPredicate(Predicate):
+    """Logical NOT of a predicate (¬Φ).
+
+    Inverts the result of the wrapped predicate.
+    """
+
+    def __init__(self, predicate: Predicate) -> None:
+        """Initialize with predicate to invert.
+
+        Args:
+            predicate: The predicate to negate.
+        """
+        self._predicate = predicate
+
+    def matches(self, artifact: Artifact) -> bool:
+        """Return inverse of wrapped predicate."""
+        return not self._predicate.matches(artifact)
+
+
+# =============================================================================
+# EXTRACTION FUNCTION (Definition 17)
+# =============================================================================
+
+
+def extract(
+    dag: ArtifactDAGInterface,
+    predicate: Predicate | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    order_by: str | None = None,
+) -> list[Artifact]:
+    """Extract artifacts from repository matching predicate (Definition 17).
+
+    E: ℛ × Φ → 2^ℛ
+
+    This is a read-only operation that does not modify the repository.
+    Implements Theorem 3: Extraction Invariance - extraction is idempotent
+    and referentially transparent.
+
+    Args:
+        dag: The artifact repository to extract from.
+        predicate: Filter predicate Φ. If None, matches all artifacts.
+        limit: Maximum number of artifacts to return.
+        offset: Number of artifacts to skip before returning.
+        order_by: Field name to sort by. Prefix with '-' for descending order.
+
+    Returns:
+        List of artifacts matching the predicate, with pagination applied.
+    """
+    # Get all artifacts from DAG via interface method
+    all_artifacts = dag.get_all()
+
+    # Apply predicate filter
+    if predicate is not None:
+        all_artifacts = [a for a in all_artifacts if predicate.matches(a)]
+
+    # Apply ordering
+    if order_by is not None:
+        descending = order_by.startswith("-")
+        field_name = order_by.lstrip("-")
+
+        def get_sort_key(artifact: Artifact) -> str:
+            return getattr(artifact, field_name, "")
+
+        all_artifacts.sort(key=get_sort_key, reverse=descending)
+
+    # Apply offset
+    if offset is not None and offset > 0:
+        all_artifacts = all_artifacts[offset:]
+
+    # Apply limit
+    if limit is not None and limit > 0:
+        all_artifacts = all_artifacts[:limit]
+
+    return all_artifacts

atomicguard/domain/interfaces.py

@@ -44,18 +44,20 @@ class GeneratorInterface(ABC):
     def generate(
         self,
         context: "Context",
-        template: Optional["PromptTemplate"] = None,
+        template: "PromptTemplate",
         action_pair_id: str = "unknown",
         workflow_id: str = "unknown",
+        workflow_ref: str | None = None,
     ) -> "Artifact":
         """
         Generate an artifact based on context.
 
         Args:
             context: The generation context including specification and feedback
-            template: Optional prompt template for structured generation
+            template: Prompt template for structured generation
             action_pair_id: Identifier for the action pair requesting generation
             workflow_id: UUID of the workflow execution instance
+            workflow_ref: Content-addressed workflow hash (Extension 01, Def 11)
 
         Returns:
             A new Artifact containing the generated content
@@ -152,6 +154,19 @@ class ArtifactDAGInterface(ABC):
         """
         pass
 
+    @abstractmethod
+    def get_all(self) -> list["Artifact"]:
+        """
+        Return all artifacts in the DAG.
+
+        Used by extraction queries that need to filter across all artifacts.
+        Implementations should return artifacts in a consistent order (e.g., by created_at).
+
+        Returns:
+            List of all artifacts in the repository.
+        """
+        pass
+
 
 class CheckpointDAGInterface(ABC):
     """

atomicguard/domain/models.py

@@ -7,12 +7,48 @@ All models are immutable (frozen dataclasses) to ensure referential transparency
 
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import TYPE_CHECKING
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from atomicguard.domain.interfaces import ArtifactDAGInterface
 
 
+# =============================================================================
+# GUARD RESULT (moved before Artifact for forward reference)
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class SubGuardOutcome:
+    """Outcome from a single sub-guard within a composite (Definition 43).
+
+    Captures individual guard result for attribution in composite validations.
+    """
+
+    guard_name: str  # Class name of the sub-guard
+    passed: bool  # Whether this sub-guard passed
+    feedback: str  # Feedback from this sub-guard
+    execution_time_ms: float = 0.0  # Time spent in this sub-guard
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    """Immutable guard validation outcome (Definition 6).
+
+    G(α, C) → {v, φ} where:
+    - v = passed (⊤ or ⊥)
+    - φ = feedback signal
+    - fatal = ⊥_fatal (non-recoverable, requires escalation)
+    """
+
+    passed: bool
+    feedback: str = ""
+    fatal: bool = False  # ⊥_fatal - skip retry, escalate to human
+    guard_name: str | None = None  # Name of the guard that produced this result
+    sub_results: tuple[SubGuardOutcome, ...] = ()  # For composite guards (Extension 08)
+
+
 # =============================================================================
 # ARTIFACT MODEL (Definition 4-6)
 # =============================================================================
@@ -81,24 +117,27 @@ class Artifact:
     created_at: str  # ISO timestamp
     attempt_number: int  # Attempt within this action pair context
     status: ArtifactStatus  # pending/rejected/accepted/superseded
-    guard_result: bool | None  # ⊤ or ⊥ (None if pending)
-    feedback: str  # φ - guard feedback (empty if passed)
+    guard_result: GuardResult | None  # Full guard result (None if pending)
     context: ContextSnapshot  # Full context snapshot at generation time
     source: ArtifactSource = ArtifactSource.GENERATED  # Origin of content
 
+    # Extension 01: Versioned Environment (Definition 10)
+    workflow_ref: str | None = None  # W_ref: Content-addressed workflow hash (Def 11)
 
-# =============================================================================
-# GUARD RESULT
-# =============================================================================
+    # Extension 07: Incremental Execution (Definition 33)
+    config_ref: str | None = (
+        None  # Ψ_ref: Configuration fingerprint for change detection
+    )
 
+    metadata: MappingProxyType[str, Any] = field(
+        default_factory=lambda: MappingProxyType({})
+    )  # Immutable metadata dict
 
-@dataclass(frozen=True)
-class GuardResult:
-    """Immutable guard validation outcome."""
-
-    passed: bool
-    feedback: str = ""
-    fatal: bool = False  # ⊥_fatal - skip retry, escalate to human
+    def __post_init__(self) -> None:
+        """Convert metadata dict to immutable MappingProxyType if needed."""
+        # Handle case where metadata is passed as a regular dict
+        if isinstance(object.__getattribute__(self, "metadata"), dict):
+            object.__setattr__(self, "metadata", MappingProxyType(self.metadata))
 
 
 # =============================================================================
@@ -125,6 +164,7 @@ class Context:
     dependency_artifacts: tuple[
         tuple[str, str], ...
     ] = ()  # (action_pair_id, artifact_id) - matches schema
+    workflow_id: str | None = None  # Extension 03: Agent workflow identifier (Def 19)
 
     def get_dependency(self, action_pair_id: str) -> str | None:
         """Look up artifact_id by action_pair_id."""
@@ -133,6 +173,41 @@ class Context:
                 return artifact_id
         return None
 
+    def amend(self, delta_spec: str = "", delta_constraints: str = "") -> "Context":
+        """Monotonic configuration amendment (⊕ operator, Definition 12).
+
+        Creates a new Context with appended specification and/or constraints.
+        Original Context remains unchanged (immutability preserved).
+
+        Args:
+            delta_spec: Additional specification to append to current specification.
+            delta_constraints: Additional constraints to append to ambient constraints.
+
+        Returns:
+            New Context with amended specification and constraints.
+        """
+        new_spec = self.specification
+        if delta_spec:
+            new_spec = f"{self.specification}\n{delta_spec}"
+
+        new_constraints = self.ambient.constraints
+        if delta_constraints:
+            new_constraints = f"{self.ambient.constraints}\n{delta_constraints}"
+
+        new_ambient = AmbientEnvironment(
+            repository=self.ambient.repository,
+            constraints=new_constraints,
+        )
+
+        return Context(
+            ambient=new_ambient,
+            specification=new_spec,
+            current_artifact=self.current_artifact,
+            feedback_history=self.feedback_history,
+            dependency_artifacts=self.dependency_artifacts,
+            workflow_id=self.workflow_id,
+        )
+
 
 # =============================================================================
 # WORKFLOW STATE
@@ -223,6 +298,9 @@ class WorkflowCheckpoint:
     failure_feedback: str  # Error/feedback message
     provenance_ids: tuple[str, ...]  # Artifact IDs of all failed attempts
 
+    # Extension 01: Versioned Environment (Definition 11)
+    workflow_ref: str | None = None  # W_ref: Content-addressed workflow hash
+
 
 class AmendmentType(Enum):
     """Type of human amendment."""