atomicguard 0.1.0__py3-none-any.whl

atomicguard/domain/models.py

@@ -0,0 +1,145 @@
+"""
+Domain models for the Dual-State Framework.
+
+These are pure data structures aligned with paper Definitions 4-6.
+All models are immutable (frozen dataclasses) to ensure referential transparency.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from atomicguard.domain.interfaces import ArtifactDAGInterface
+
+
+# =============================================================================
+# ARTIFACT MODEL (Definition 4-6)
+# =============================================================================
+
+
+class ArtifactStatus(Enum):
+    """Status of an artifact in the DAG."""
+
+    PENDING = "pending"  # Generated, not yet validated
+    REJECTED = "rejected"  # Guard returned ⊥
+    ACCEPTED = "accepted"  # Guard returned ⊤, final for this step
+    SUPERSEDED = "superseded"  # Guard returned ⊤, but later attempt also passed
+
+
+@dataclass(frozen=True)
+class FeedbackEntry:
+    """Single entry in feedback history H."""
+
+    artifact_id: str  # Reference to the rejected artifact
+    feedback: str  # Guard's rejection message φ
+
+
+@dataclass(frozen=True)
+class ContextSnapshot:
+    """Immutable context C that conditioned generation (Definition 5)."""
+
+    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
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """
+    Immutable node in the Versioned Repository DAG (Definition 4).
+
+    Represents a single generation attempt with full provenance tracking.
+    """
+
+    # Identity
+    artifact_id: str  # Unique identifier (UUID)
+    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
+
+    # Action Pair Coupling (Definition 6: A = ⟨ρ, a_gen, G⟩)
+    action_pair_id: str  # Which action pair produced this
+
+    # Metadata
+    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)
+    context: ContextSnapshot  # Full context snapshot at generation time
+
+
+# =============================================================================
+# GUARD RESULT
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    """Immutable guard validation outcome."""
+
+    passed: bool
+    feedback: str = ""
+
+
+# =============================================================================
+# CONTEXT AND ENVIRONMENT
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class AmbientEnvironment:
+    """Ambient Environment E = ⟨R, Ω⟩"""
+
+    repository: "ArtifactDAGInterface"
+    constraints: str = ""
+
+
+@dataclass(frozen=True)
+class Context:
+    """Immutable hierarchical context composition (Definition 5)."""
+
+    ambient: AmbientEnvironment
+    specification: str
+    current_artifact: str | None = None
+    feedback_history: tuple[tuple[str, str], ...] = ()
+    dependencies: tuple[
+        tuple[str, "Artifact"], ...
+    ] = ()  # (key, artifact) pairs from prior steps
+
+
+# =============================================================================
+# WORKFLOW STATE
+# =============================================================================
+
+
+@dataclass
+class WorkflowState:
+    """Mutable workflow state tracking guard satisfaction."""
+
+    guards: dict[str, bool] = field(default_factory=dict)
+    artifact_ids: dict[str, str] = field(default_factory=dict)
+
+    def is_satisfied(self, guard_id: str) -> bool:
+        return self.guards.get(guard_id, False)
+
+    def satisfy(self, guard_id: str, artifact_id: str) -> None:
+        self.guards[guard_id] = True
+        self.artifact_ids[guard_id] = artifact_id
+
+    def get_artifact_id(self, guard_id: str) -> str | None:
+        return self.artifact_ids.get(guard_id)
+
+
+@dataclass(frozen=True)
+class WorkflowResult:
+    """Result of workflow execution."""
+
+    success: bool
+    artifacts: dict[str, Artifact]
+    failed_step: str | None = None
+    provenance: tuple[tuple[Artifact, str], ...] = ()

atomicguard/domain/prompts.py

@@ -0,0 +1,85 @@
+"""
+Prompt and task definitions for the Dual-State Framework.
+
+This module provides:
+- PromptTemplate: Structured prompt rendering
+- StepDefinition: Single workflow step specification
+- TaskDefinition: Complete task with multiple steps
+
+These are domain structures (schemas) only. Actual task content should be
+defined by the calling application (e.g., benchmarks), not hardcoded here.
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from atomicguard.domain.models import Context
+
+
+# =============================================================================
+# PROMPT TEMPLATE (moved from models.py)
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class PromptTemplate:
+    """Structured prompt template for generator."""
+
+    role: str
+    constraints: str
+    task: str
+    feedback_wrapper: str = (
+        "GUARD REJECTION:\n{feedback}\nInstruction: Address the rejection above."
+    )
+
+    def render(self, context: "Context") -> str:
+        """Render prompt with context."""
+        parts = [
+            f"# ROLE\n{self.role}",
+            f"# CONSTRAINTS\n{self.constraints}",
+        ]
+
+        if context.ambient.constraints:
+            parts.append(f"# CONTEXT\n{context.ambient.constraints}")
+
+        if context.feedback_history:
+            parts.append("# HISTORY (Context Refinement)")
+            for i, (_artifact_content, feedback) in enumerate(context.feedback_history):
+                wrapped = self.feedback_wrapper.format(feedback=feedback)
+                parts.append(f"--- Attempt {i + 1} ---\n{wrapped}")
+
+        parts.append(f"# TASK\n{self.task}")
+        return "\n\n".join(parts)
+
+
+# =============================================================================
+# TASK DEFINITIONS (DS-PDDL semantic layer)
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class StepDefinition:
+    """Single workflow step specification."""
+
+    step_id: str  # e.g., "g_test", "g_impl"
+    prompt: str  # Prompt template with {placeholders}
+    guard: str  # Guard type: "syntax", "dynamic_test", "human", etc.
+    requires: tuple[str, ...] = ()  # Step IDs this depends on
+
+
+@dataclass(frozen=True)
+class TaskDefinition:
+    """Complete task definition with multiple workflow steps."""
+
+    task_id: str  # e.g., "tdd_stack"
+    name: str  # Human-readable name
+    specification: str  # High-level task description (Ψ)
+    steps: tuple[StepDefinition, ...]  # Ordered workflow steps
+
+    def get_step(self, step_id: str) -> StepDefinition | None:
+        """Get a step by ID."""
+        for step in self.steps:
+            if step.step_id == step_id:
+                return step
+        return None

atomicguard/guards/__init__.py

@@ -0,0 +1,19 @@
+"""
+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.
+"""
+
+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
+
+__all__ = [
+    "CompositeGuard",
+    "SyntaxGuard",
+    "TestGuard",
+    "DynamicTestGuard",
+    "HumanReviewGuard",
+]

atomicguard/guards/base.py

@@ -0,0 +1,41 @@
+"""
+Base guard implementations and composition patterns.
+
+CompositeGuard implements the Decorator pattern for guard composition.
+"""
+
+from typing import Any
+
+from atomicguard.domain.interfaces import GuardInterface
+from atomicguard.domain.models import Artifact, GuardResult
+
+
+class CompositeGuard(GuardInterface):
+    """
+    Logical AND of multiple guards. All must pass.
+
+    Evaluates guards in order, short-circuits on first failure.
+    This ensures automated checks run before human review.
+
+    Per paper section on Composite Guards:
+    G_composite = G_automated ∧ G_human
+    """
+
+    def __init__(self, *guards: GuardInterface):
+        """
+        Args:
+            *guards: Guards to compose (evaluated in order)
+        """
+        self.guards = guards
+
+    def validate(self, artifact: Artifact, **deps: Any) -> GuardResult:
+        """
+        Validate artifact against all composed guards.
+
+        Short-circuits on first failure.
+        """
+        for guard in self.guards:
+            result = guard.validate(artifact, **deps)
+            if not result.passed:
+                return result  # Short-circuit on failure
+        return GuardResult(passed=True, feedback="All guards passed")

atomicguard/guards/human.py

@@ -0,0 +1,85 @@
+"""
+Human-in-the-loop review guard.
+
+Blocks workflow until human approval via CLI prompts.
+"""
+
+from typing import Any
+
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.syntax import Syntax
+
+from atomicguard.domain.interfaces import GuardInterface
+from atomicguard.domain.models import Artifact, GuardResult
+
+
+class HumanReviewGuard(GuardInterface):
+    """
+    Blocks workflow until human approval.
+
+    Per paper Phase 8 (Human Oversight):
+    - Pauses workflow to poll external oracle (human)
+    - Returns approval or rejection with feedback
+    - Feedback flows back to generator for retry
+
+    This implementation uses synchronous CLI prompts.
+    For async/distributed use, extend with file-based or webhook polling.
+    """
+
+    def __init__(self, prompt_title: str = "HUMAN REVIEW REQUIRED"):
+        """
+        Args:
+            prompt_title: Title displayed in the review prompt
+        """
+        self.prompt_title = prompt_title
+        self.console = Console()
+
+    def validate(self, artifact: Artifact, **deps: Any) -> GuardResult:
+        """
+        Display artifact and prompt for human approval.
+
+        Args:
+            artifact: The artifact to review
+            **deps: Dependencies shown for context
+
+        Returns:
+            GuardResult based on human decision
+        """
+        self.console.print(f"\n[bold yellow]═══ {self.prompt_title} ═══[/bold yellow]")
+        self.console.print(f"[dim]Artifact ID: {artifact.artifact_id}[/dim]")
+        self.console.print(f"[dim]Action Pair: {artifact.action_pair_id}[/dim]\n")
+
+        # Display the artifact content with syntax highlighting
+        self.console.print(
+            Syntax(artifact.content, "python", theme="monokai", line_numbers=True)
+        )
+
+        # Show dependencies if present
+        if deps:
+            self.console.print("\n[dim]Dependencies:[/dim]")
+            for key, dep_artifact in deps.items():
+                self.console.print(f"  [dim]{key}: {dep_artifact.artifact_id}[/dim]")
+
+        # Prompt for decision
+        decision = Prompt.ask(
+            "\n[bold]Approve this artifact?[/bold]", choices=["y", "n", "v"]
+        )
+
+        if decision == "v":
+            # View more context
+            self.console.print("\n[dim]Context:[/dim]")
+            self.console.print(
+                f"  Specification: {artifact.context.specification[:200]}..."
+            )
+            if artifact.context.feedback_history:
+                self.console.print(
+                    f"  Previous failures: {len(artifact.context.feedback_history)}"
+                )
+            decision = Prompt.ask("\n[bold]Approve?[/bold]", choices=["y", "n"])
+
+        if decision == "y":
+            return GuardResult(passed=True, feedback="Human approved")
+        else:
+            feedback = Prompt.ask("[bold]Rejection reason[/bold]")
+            return GuardResult(passed=False, feedback=f"Human rejected: {feedback}")

atomicguard/guards/syntax.py

@@ -0,0 +1,33 @@
+"""
+Syntax validation guard.
+
+Pure guard with no I/O dependencies - validates Python AST.
+"""
+
+import ast
+from typing import Any
+
+from atomicguard.domain.interfaces import GuardInterface
+from atomicguard.domain.models import Artifact, GuardResult
+
+
+class SyntaxGuard(GuardInterface):
+    """
+    Validates Python syntax using AST parsing.
+
+    This is a pure guard with no I/O - it only validates
+    that the artifact content is syntactically valid Python.
+    """
+
+    def validate(self, artifact: Artifact, **_deps: Any) -> GuardResult:
+        """
+        Parse artifact content as Python AST.
+
+        Returns:
+            GuardResult with passed=True if syntax is valid
+        """
+        try:
+            ast.parse(artifact.content)
+            return GuardResult(passed=True, feedback="Syntax valid")
+        except SyntaxError as e:
+            return GuardResult(passed=False, feedback=f"Syntax error: {e}")

atomicguard/guards/test_runner.py

@@ -0,0 +1,176 @@
+"""
+Test execution guards.
+
+Guards that validate artifacts by running tests against them.
+"""
+
+import multiprocessing
+import sys
+import types
+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
+        """
+        test_artifact = deps.get("test")
+        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.
+
+    Expects 'test' dependency containing the test artifact.
+    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):
+        """
+        Args:
+            timeout: Maximum time in seconds to wait for test execution
+        """
+        self.timeout = timeout
+
+    def validate(self, artifact: Artifact, **deps: Any) -> GuardResult:
+        """
+        Run tests in isolated subprocess.
+
+        Args:
+            artifact: The implementation artifact to test
+            **deps: Must include 'test' artifact with test code
+
+        Returns:
+            GuardResult with test outcome
+        """
+        test_artifact = deps.get("test")
+        if not test_artifact:
+            return GuardResult(
+                passed=False, feedback="No test artifact in dependencies"
+            )
+
+        q: multiprocessing.Queue = multiprocessing.Queue()
+        p = multiprocessing.Process(
+            target=self._run_tests, args=(artifact, test_artifact, 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_artifact: Artifact, test_artifact: Artifact, q: Any
+    ) -> None:
+        """
+        Execute tests in subprocess.
+
+        This method runs in a forked process for isolation.
+        """
+        try:
+            impl_code = impl_artifact.content
+            test_code = test_artifact.content
+
+            if not impl_code:
+                q.put((False, "No implementation code"))
+                return
+
+            if not test_code:
+                q.put((False, "No test code"))
+                return
+
+            # Create mock 'implementation' module
+            impl_module = types.ModuleType("implementation")
+            exec(impl_code, impl_module.__dict__)
+            sys.modules["implementation"] = impl_module
+
+            # Execute test code (pytest already in sys.modules from parent)
+            import pytest
+
+            test_scope = {"__builtins__": __builtins__, "pytest": pytest}
+            exec(test_code, test_scope)
+
+            # Find and run test functions
+            test_funcs = [
+                v
+                for k, v in test_scope.items()
+                if k.startswith("test_") and callable(v)
+            ]
+
+            if not test_funcs:
+                q.put((False, "No test functions found"))
+                return
+
+            failures = []
+            for func in test_funcs:
+                try:
+                    func()
+                except AssertionError as e:
+                    failures.append(f"{func.__name__}: AssertionError - {e}")
+                except Exception as e:
+                    failures.append(f"{func.__name__}: {type(e).__name__} - {e}")
+
+            if failures:
+                q.put((False, "Test failures:\n" + "\n".join(failures)))
+            else:
+                q.put((True, f"All {len(test_funcs)} tests passed"))
+
+        except SyntaxError as e:
+            q.put((False, f"Syntax error: {e}"))
+        except Exception as e:
+            q.put((False, f"Execution error: {e}"))
+        finally:
+            if "implementation" in sys.modules:
+                del sys.modules["implementation"]

atomicguard/infrastructure/__init__.py

@@ -0,0 +1,23 @@
+"""
+Infrastructure layer for the Dual-State Framework.
+
+Contains adapters for external concerns (persistence, LLMs, etc.).
+"""
+
+from atomicguard.infrastructure.llm import (
+    MockGenerator,
+    OllamaGenerator,
+)
+from atomicguard.infrastructure.persistence import (
+    FilesystemArtifactDAG,
+    InMemoryArtifactDAG,
+)
+
+__all__ = [
+    # Persistence
+    "InMemoryArtifactDAG",
+    "FilesystemArtifactDAG",
+    # LLM
+    "OllamaGenerator",
+    "MockGenerator",
+]

atomicguard/infrastructure/llm/__init__.py

@@ -0,0 +1,11 @@
+"""
+LLM adapters for artifact generation.
+"""
+
+from atomicguard.infrastructure.llm.mock import MockGenerator
+from atomicguard.infrastructure.llm.ollama import OllamaGenerator
+
+__all__ = [
+    "OllamaGenerator",
+    "MockGenerator",
+]

atomicguard/infrastructure/llm/mock.py

@@ -0,0 +1,61 @@
+"""
+Mock generator for testing without LLM.
+
+Returns predefined responses in sequence.
+"""
+
+import uuid
+from datetime import datetime
+
+from atomicguard.domain.interfaces import GeneratorInterface
+from atomicguard.domain.models import Artifact, ArtifactStatus, Context, ContextSnapshot
+from atomicguard.domain.prompts import PromptTemplate
+
+
+class MockGenerator(GeneratorInterface):
+    """Returns predefined responses for testing."""
+
+    def __init__(self, responses: list[str]):
+        """
+        Args:
+            responses: List of response strings to return in sequence
+        """
+        self._responses = responses
+        self._call_count = 0
+
+    def generate(
+        self, _context: Context, _template: PromptTemplate | None = None
+    ) -> Artifact:
+        """Return the next predefined response."""
+        if self._call_count >= len(self._responses):
+            raise RuntimeError("MockGenerator exhausted responses")
+
+        content = self._responses[self._call_count]
+        self._call_count += 1
+
+        return Artifact(
+            artifact_id=str(uuid.uuid4()),
+            content=content,
+            previous_attempt_id=None,
+            action_pair_id="mock",
+            created_at=datetime.now().isoformat(),
+            attempt_number=self._call_count,
+            status=ArtifactStatus.PENDING,
+            guard_result=None,
+            feedback="",
+            context=ContextSnapshot(
+                specification="",
+                constraints="",
+                feedback_history=(),
+                dependency_ids=(),
+            ),
+        )
+
+    @property
+    def call_count(self) -> int:
+        """Number of times generate() has been called."""
+        return self._call_count
+
+    def reset(self) -> None:
+        """Reset the call counter to reuse responses."""
+        self._call_count = 0