atomicguard 0.1.0__py3-none-any.whl

atomicguard/__init__.py

@@ -0,0 +1,116 @@
+"""
+AtomicGuard: Dual-State Framework for LLM Output Management.
+
+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.guards import SyntaxGuard
+    from atomicguard.infrastructure import OllamaGenerator
+
+    generator = OllamaGenerator(model="qwen2.5-coder:7b")
+    guard = SyntaxGuard()
+    action_pair = ActionPair(generator=generator, guard=guard)
+
+    workflow = Workflow(rmax=3)
+    workflow.add_step('g_code', action_pair=action_pair)
+    result = workflow.execute("Write a function that adds two numbers")
+"""
+
+# Domain models (most commonly used)
+# Application layer (orchestration)
+from atomicguard.application.action_pair import ActionPair
+from atomicguard.application.agent import DualStateAgent
+from atomicguard.application.workflow import Workflow, WorkflowStep
+
+# Domain exceptions
+from atomicguard.domain.exceptions import RmaxExhausted
+
+# Domain interfaces (for type hints and custom implementations)
+from atomicguard.domain.interfaces import (
+    ArtifactDAGInterface,
+    GeneratorInterface,
+    GuardInterface,
+)
+from atomicguard.domain.models import (
+    AmbientEnvironment,
+    Artifact,
+    ArtifactStatus,
+    Context,
+    ContextSnapshot,
+    FeedbackEntry,
+    GuardResult,
+    WorkflowResult,
+    WorkflowState,
+)
+
+# Prompts and tasks (structures only - content defined by calling applications)
+from atomicguard.domain.prompts import (
+    PromptTemplate,
+    StepDefinition,
+    TaskDefinition,
+)
+
+# Guards (commonly composed)
+from atomicguard.guards import (
+    CompositeGuard,
+    DynamicTestGuard,
+    HumanReviewGuard,
+    SyntaxGuard,
+    TestGuard,
+)
+from atomicguard.infrastructure.llm import (
+    MockGenerator,
+    OllamaGenerator,
+)
+
+# Infrastructure (explicit import encouraged for dependency injection)
+from atomicguard.infrastructure.persistence import (
+    FilesystemArtifactDAG,
+    InMemoryArtifactDAG,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Domain models
+    "Artifact",
+    "ArtifactStatus",
+    "ContextSnapshot",
+    "FeedbackEntry",
+    "Context",
+    "AmbientEnvironment",
+    "GuardResult",
+    "WorkflowState",
+    "WorkflowResult",
+    # Prompts and tasks (structures only)
+    "PromptTemplate",
+    "StepDefinition",
+    "TaskDefinition",
+    # Domain interfaces
+    "GeneratorInterface",
+    "GuardInterface",
+    "ArtifactDAGInterface",
+    # Domain exceptions
+    "RmaxExhausted",
+    # Application layer
+    "ActionPair",
+    "DualStateAgent",
+    "Workflow",
+    "WorkflowStep",
+    # Infrastructure - Persistence
+    "InMemoryArtifactDAG",
+    "FilesystemArtifactDAG",
+    # Infrastructure - LLM
+    "OllamaGenerator",
+    "MockGenerator",
+    # Guards
+    "CompositeGuard",
+    "SyntaxGuard",
+    "TestGuard",
+    "DynamicTestGuard",
+    "HumanReviewGuard",
+]

atomicguard/application/__init__.py

@@ -0,0 +1,16 @@
+"""
+Application layer for the Dual-State Framework.
+
+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.workflow import Workflow, WorkflowStep
+
+__all__ = [
+    "ActionPair",
+    "DualStateAgent",
+    "Workflow",
+    "WorkflowStep",
+]

atomicguard/application/action_pair.py

@@ -0,0 +1,65 @@
+"""
+ActionPair: Atomic generation-verification transaction.
+
+Paper Definition 6: A = ⟨a_gen, G⟩
+Precondition ρ is handled at the Workflow level.
+"""
+
+from atomicguard.domain.interfaces import GeneratorInterface, GuardInterface
+from atomicguard.domain.models import Artifact, Context, GuardResult
+from atomicguard.domain.prompts import PromptTemplate
+
+
+class ActionPair:
+    """
+    Atomic generation-verification transaction.
+
+    Couples a generator with a guard to form an indivisible unit.
+    The precondition ρ is handled at the Workflow level.
+    """
+
+    def __init__(
+        self,
+        generator: GeneratorInterface,
+        guard: GuardInterface,
+        prompt_template: PromptTemplate | None = None,
+    ):
+        """
+        Args:
+            generator: The artifact generator
+            guard: The validator for generated artifacts
+            prompt_template: Optional structured prompt template
+        """
+        self._generator = generator
+        self._guard = guard
+        self._prompt_template = prompt_template
+
+    @property
+    def generator(self) -> GeneratorInterface:
+        """Access the generator (read-only)."""
+        return self._generator
+
+    @property
+    def guard(self) -> GuardInterface:
+        """Access the guard (read-only)."""
+        return self._guard
+
+    def execute(
+        self,
+        context: Context,
+        dependencies: dict[str, Artifact] | None = None,
+    ) -> tuple[Artifact, GuardResult]:
+        """
+        Execute the atomic generate-then-validate transaction.
+
+        Args:
+            context: Generation context
+            dependencies: Artifacts from prior workflow steps
+
+        Returns:
+            Tuple of (generated artifact, guard result)
+        """
+        dependencies = dependencies or {}
+        artifact = self._generator.generate(context, self._prompt_template)
+        result = self._guard.validate(artifact, **dependencies)
+        return artifact, result

atomicguard/application/agent.py

@@ -0,0 +1,129 @@
+"""
+DualStateAgent: Stateless executor for a single ActionPair.
+
+Manages only EnvironmentState (the retry loop).
+WorkflowState is managed by Workflow.
+"""
+
+from atomicguard.application.action_pair import ActionPair
+from atomicguard.domain.exceptions import RmaxExhausted
+from atomicguard.domain.interfaces import ArtifactDAGInterface
+from atomicguard.domain.models import (
+    AmbientEnvironment,
+    Artifact,
+    Context,
+)
+
+
+class DualStateAgent:
+    """
+    Stateless executor for a single ActionPair.
+
+    Manages only EnvironmentState (retry loop).
+    WorkflowState is managed by Workflow.
+
+    Dependencies from prior workflow steps are passed to both:
+    - Generator (via Context.dependencies) - so it can see prior artifacts
+    - Guard (via validate(**deps)) - for validation against prior artifacts
+    """
+
+    def __init__(
+        self,
+        action_pair: ActionPair,
+        artifact_dag: ArtifactDAGInterface,
+        rmax: int = 3,
+        constraints: str = "",
+    ):
+        """
+        Args:
+            action_pair: The generator-guard pair to execute
+            artifact_dag: Repository for storing artifacts
+            rmax: Maximum retry attempts (default: 3)
+            constraints: Global constraints for the ambient environment
+        """
+        self._action_pair = action_pair
+        self._artifact_dag = artifact_dag
+        self._rmax = rmax
+        self._constraints = constraints
+
+    def execute(
+        self,
+        specification: str,
+        dependencies: dict[str, Artifact] | None = None,
+    ) -> Artifact:
+        """
+        Execute the action pair with retry logic.
+
+        Args:
+            specification: The task specification
+            dependencies: Artifacts from prior workflow steps (key -> Artifact)
+                         Passed to both generator (via Context) and guard (via validate)
+
+        Returns:
+            The accepted artifact
+
+        Raises:
+            RmaxExhausted: If all retries fail
+        """
+        dependencies = dependencies or {}
+        context = self._compose_context(specification, dependencies)
+        feedback_history: list[tuple[Artifact, str]] = []
+        retry_count = 0
+
+        while retry_count <= self._rmax:
+            artifact, result = self._action_pair.execute(context, dependencies)
+
+            self._artifact_dag.store(
+                artifact, metadata="" if result.passed else result.feedback
+            )
+
+            if result.passed:
+                return artifact
+            else:
+                feedback_history.append((artifact, result.feedback))
+                retry_count += 1
+                context = self._refine_context(
+                    specification, artifact, feedback_history, dependencies
+                )
+
+        raise RmaxExhausted(
+            f"Failed after {self._rmax} retries", provenance=feedback_history
+        )
+
+    def _compose_context(
+        self,
+        specification: str,
+        dependencies: dict[str, Artifact] | None = None,
+    ) -> Context:
+        """Compose initial context with dependencies."""
+        dependencies = dependencies or {}
+        ambient = AmbientEnvironment(
+            repository=self._artifact_dag, constraints=self._constraints
+        )
+        return Context(
+            ambient=ambient,
+            specification=specification,
+            current_artifact=None,
+            feedback_history=(),
+            dependencies=tuple(dependencies.items()),  # Pass to generator
+        )
+
+    def _refine_context(
+        self,
+        specification: str,
+        artifact: Artifact,
+        feedback_history: list[tuple[Artifact, str]],
+        dependencies: dict[str, Artifact] | None = None,
+    ) -> Context:
+        """Refine context with feedback from failed attempt."""
+        dependencies = dependencies or {}
+        ambient = AmbientEnvironment(
+            repository=self._artifact_dag, constraints=self._constraints
+        )
+        return Context(
+            ambient=ambient,
+            specification=specification,
+            current_artifact=artifact.content,
+            feedback_history=tuple((a.content, f) for a, f in feedback_history),
+            dependencies=tuple(dependencies.items()),  # Preserve dependencies on retry
+        )

atomicguard/application/workflow.py

@@ -0,0 +1,149 @@
+"""
+Workflow: Orchestrates ActionPair execution across multiple steps.
+
+Owns WorkflowState and infers preconditions from step dependencies.
+"""
+
+from dataclasses import dataclass
+
+from atomicguard.application.action_pair import ActionPair
+from atomicguard.application.agent import DualStateAgent
+from atomicguard.domain.exceptions import RmaxExhausted
+from atomicguard.domain.interfaces import ArtifactDAGInterface
+from atomicguard.domain.models import Artifact, WorkflowResult, WorkflowState
+
+
+@dataclass(frozen=True)
+class WorkflowStep:
+    """Internal step representation."""
+
+    guard_id: str
+    action_pair: ActionPair
+    requires: tuple[str, ...]
+    deps: tuple[str, ...]  # Artifacts to pass to guard
+
+
+class Workflow:
+    """
+    Orchestrates ActionPair execution.
+
+    Owns WorkflowState and infers preconditions from requires.
+    """
+
+    def __init__(
+        self,
+        artifact_dag: ArtifactDAGInterface | None = None,
+        rmax: int = 3,
+        constraints: str = "",
+    ):
+        """
+        Args:
+            artifact_dag: Repository for storing artifacts (creates InMemory if None)
+            rmax: Maximum retries per step
+            constraints: Global constraints for the ambient environment
+        """
+        # Lazy import to avoid circular dependency
+        if artifact_dag is None:
+            from atomicguard.infrastructure.persistence import InMemoryArtifactDAG
+
+            artifact_dag = InMemoryArtifactDAG()
+
+        self._dag = artifact_dag
+        self._rmax = rmax
+        self._constraints = constraints
+        self._steps: list[WorkflowStep] = []
+        self._workflow_state = WorkflowState()
+        self._artifacts: dict[str, Artifact] = {}
+
+    def add_step(
+        self,
+        guard_id: str,
+        action_pair: ActionPair,
+        requires: tuple[str, ...] = (),
+        deps: tuple[str, ...] | None = None,
+    ) -> "Workflow":
+        """
+        Register a step. Precondition inferred from requires.
+
+        Args:
+            guard_id: Unique identifier for this step (e.g., 'g_test', 'g_impl')
+            action_pair: The generator-guard pair for this step
+            requires: Guard IDs that must be satisfied before this step
+            deps: Artifact dependencies to pass to guard (defaults to requires)
+
+        Returns:
+            Self for fluent chaining
+        """
+        if deps is None:
+            deps = requires
+        self._steps.append(WorkflowStep(guard_id, action_pair, requires, deps))
+        return self  # Fluent
+
+    def execute(self, specification: str) -> WorkflowResult:
+        """
+        Execute the workflow until completion or failure.
+
+        Args:
+            specification: The task specification
+
+        Returns:
+            WorkflowResult with success status and artifacts
+        """
+        while not self._is_goal_state():
+            step = self._find_applicable()
+
+            if step is None:
+                return WorkflowResult(
+                    success=False,
+                    artifacts=self._artifacts,
+                    failed_step="No applicable step",
+                )
+
+            # Extract dependencies
+            dependencies = {
+                gid.replace("g_", ""): self._artifacts[gid]
+                for gid in step.deps
+                if gid in self._artifacts
+            }
+
+            # Execute via stateless agent
+            agent = DualStateAgent(
+                action_pair=step.action_pair,
+                artifact_dag=self._dag,
+                rmax=self._rmax,
+                constraints=self._constraints,
+            )
+
+            try:
+                artifact = agent.execute(specification, dependencies)
+                self._artifacts[step.guard_id] = artifact
+                self._workflow_state.satisfy(step.guard_id, artifact.artifact_id)
+
+            except RmaxExhausted as e:
+                return WorkflowResult(
+                    success=False,
+                    artifacts=self._artifacts,
+                    failed_step=step.guard_id,
+                    provenance=tuple(e.provenance),
+                )
+
+        return WorkflowResult(success=True, artifacts=self._artifacts)
+
+    def _precondition_met(self, step: WorkflowStep) -> bool:
+        """Precondition: all required guards satisfied."""
+        return all(self._workflow_state.is_satisfied(req) for req in step.requires)
+
+    def _find_applicable(self) -> WorkflowStep | None:
+        """Find first step not done and with precondition met."""
+        for step in self._steps:
+            if not self._workflow_state.is_satisfied(
+                step.guard_id
+            ) and self._precondition_met(step):
+                return step
+        return None
+
+    def _is_goal_state(self) -> bool:
+        """Check if all steps are satisfied."""
+        return all(
+            self._workflow_state.is_satisfied(step.guard_id) for step in self._steps
+        )

atomicguard/domain/__init__.py

@@ -0,0 +1,51 @@
+"""
+Domain layer for the Dual-State Framework.
+
+Contains core business logic with no external dependencies.
+"""
+
+from atomicguard.domain.exceptions import RmaxExhausted
+from atomicguard.domain.interfaces import (
+    ArtifactDAGInterface,
+    GeneratorInterface,
+    GuardInterface,
+)
+from atomicguard.domain.models import (
+    AmbientEnvironment,
+    Artifact,
+    ArtifactStatus,
+    Context,
+    ContextSnapshot,
+    FeedbackEntry,
+    GuardResult,
+    WorkflowResult,
+    WorkflowState,
+)
+from atomicguard.domain.prompts import (
+    PromptTemplate,
+    StepDefinition,
+    TaskDefinition,
+)
+
+__all__ = [
+    # Models
+    "Artifact",
+    "ArtifactStatus",
+    "ContextSnapshot",
+    "FeedbackEntry",
+    "Context",
+    "AmbientEnvironment",
+    "GuardResult",
+    "WorkflowState",
+    "WorkflowResult",
+    # Prompts and Tasks (structures only, no content)
+    "PromptTemplate",
+    "StepDefinition",
+    "TaskDefinition",
+    # Interfaces
+    "GeneratorInterface",
+    "GuardInterface",
+    "ArtifactDAGInterface",
+    # Exceptions
+    "RmaxExhausted",
+]

atomicguard/domain/exceptions.py

@@ -0,0 +1,28 @@
+"""
+Domain exceptions for the Dual-State Framework.
+
+These represent business rule violations in the domain layer.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from atomicguard.domain.models import Artifact
+
+
+class RmaxExhausted(Exception):
+    """
+    Raised when maximum retry attempts are exhausted.
+
+    This is a domain exception representing the business rule that
+    generation must succeed within r_max attempts.
+    """
+
+    def __init__(self, message: str, provenance: list[tuple["Artifact", str]]):
+        """
+        Args:
+            message: Human-readable error message
+            provenance: List of (artifact, feedback) tuples for each failed attempt
+        """
+        super().__init__(message)
+        self.provenance = provenance

atomicguard/domain/interfaces.py

@@ -0,0 +1,119 @@
+"""
+Domain interfaces (Ports) for the Dual-State Framework.
+
+These abstract base classes define the contracts that implementations must satisfy.
+They have no external dependencies and represent the core domain boundaries.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from atomicguard.domain.models import (
+        Artifact,
+        Context,
+        GuardResult,
+    )
+
+if TYPE_CHECKING:
+    from atomicguard.domain.models import Artifact, Context, GuardResult
+    from atomicguard.domain.prompts import PromptTemplate
+
+
+class GeneratorInterface(ABC):
+    """
+    Port for artifact generation.
+
+    Implementations connect to LLMs or other generation sources.
+    """
+
+    @abstractmethod
+    def generate(
+        self, context: "Context", template: Optional["PromptTemplate"] = None
+    ) -> "Artifact":
+        """
+        Generate an artifact based on context.
+
+        Args:
+            context: The generation context including specification and feedback
+            template: Optional prompt template for structured generation
+
+        Returns:
+            A new Artifact containing the generated content
+        """
+        pass
+
+
+class GuardInterface(ABC):
+    """
+    Port for artifact validation.
+
+    Guards are deterministic validators that return ⊤ (pass) or ⊥ (fail with feedback).
+    """
+
+    @abstractmethod
+    def validate(
+        self, artifact: "Artifact", **dependencies: "Artifact"
+    ) -> "GuardResult":
+        """
+        Validate an artifact.
+
+        Args:
+            artifact: The artifact to validate
+            **dependencies: Artifacts from prior workflow steps (key -> Artifact)
+
+        Returns:
+            GuardResult with passed=True/False and optional feedback
+        """
+        pass
+
+
+class ArtifactDAGInterface(ABC):
+    """
+    Port for artifact persistence.
+
+    Implementations provide append-only storage for the Versioned Repository (Definition 4).
+    """
+
+    @abstractmethod
+    def store(self, artifact: "Artifact", metadata: str = "") -> str:
+        """
+        Store an artifact in the DAG.
+
+        Args:
+            artifact: The artifact to store
+            metadata: Optional metadata string
+
+        Returns:
+            The artifact_id
+        """
+        pass
+
+    @abstractmethod
+    def get_artifact(self, artifact_id: str) -> "Artifact":
+        """
+        Retrieve an artifact by ID.
+
+        Args:
+            artifact_id: The unique identifier
+
+        Returns:
+            The artifact
+
+        Raises:
+            KeyError: If artifact not found
+        """
+        pass
+
+    @abstractmethod
+    def get_provenance(self, artifact_id: str) -> list["Artifact"]:
+        """
+        Trace the retry chain via previous_attempt_id.
+
+        Args:
+            artifact_id: Starting artifact
+
+        Returns:
+            List of artifacts from oldest to newest in the chain
+        """
+        pass