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

atomicguard/guards/static/imports.py

@@ -0,0 +1,177 @@
+"""
+Import validation guard.
+
+Pure AST-based guard that validates all used names are imported or defined.
+Does NOT execute code - uses static analysis only.
+"""
+
+import ast
+import builtins
+from typing import Any
+
+from atomicguard.domain.interfaces import GuardInterface
+from atomicguard.domain.models import Artifact, GuardResult
+
+
+class ImportGuard(GuardInterface):
+    """
+    Validates that all names used in code are imported or defined.
+
+    Pure, static guard using AST analysis. Does NOT execute code.
+    Single responsibility: verify that referenced names exist.
+
+    This catches common LLM mistakes like using `pytest.raises()`
+    without `import pytest`.
+    """
+
+    # Python builtins that don't need to be imported
+    BUILTINS = set(dir(builtins))
+
+    def validate(self, artifact: Artifact, **_deps: Any) -> GuardResult:
+        """
+        Validate that all used names are defined or imported.
+
+        Args:
+            artifact: The code artifact to validate
+            **_deps: Ignored dependencies
+
+        Returns:
+            GuardResult with pass/fail and feedback
+        """
+        code = artifact.content
+        if not code:
+            return GuardResult(passed=False, feedback="No code provided")
+
+        try:
+            tree = ast.parse(code)
+        except SyntaxError as e:
+            return GuardResult(passed=False, feedback=f"Syntax error: {e}")
+
+        defined = self._collect_defined_names(tree)
+        used = self._collect_used_names(tree)
+
+        # Names that are used but not defined, imported, or builtin
+        undefined = used - defined - self.BUILTINS
+
+        if undefined:
+            sorted_names = ", ".join(sorted(undefined))
+            return GuardResult(
+                passed=False,
+                feedback=f"Undefined names (missing imports?): {sorted_names}",
+            )
+        return GuardResult(passed=True, feedback="All imports valid")
+
+    def _collect_defined_names(self, tree: ast.AST) -> set[str]:
+        """
+        Collect all names defined in the code.
+
+        Includes:
+        - Import statements (import X, from X import Y)
+        - Function definitions (def foo)
+        - Class definitions (class Bar)
+        - Assignments (x = ...)
+        - For loop variables (for x in ...)
+        - With statement variables (with ... as x)
+        - Exception handlers (except E as e)
+        - Comprehension variables
+        """
+        defined: set[str] = set()
+
+        for node in ast.walk(tree):
+            # Import statements
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    name = alias.asname if alias.asname else alias.name.split(".")[0]
+                    defined.add(name)
+
+            elif isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    name = alias.asname if alias.asname else alias.name
+                    if name != "*":  # from X import * doesn't define specific names
+                        defined.add(name)
+
+            # Function and class definitions
+            elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                defined.add(node.name)
+                # Add parameter names
+                for arg in node.args.args:
+                    defined.add(arg.arg)
+                for arg in node.args.posonlyargs:
+                    defined.add(arg.arg)
+                for arg in node.args.kwonlyargs:
+                    defined.add(arg.arg)
+                if node.args.vararg:
+                    defined.add(node.args.vararg.arg)
+                if node.args.kwarg:
+                    defined.add(node.args.kwarg.arg)
+
+            elif isinstance(node, ast.ClassDef):
+                defined.add(node.name)
+
+            # Assignments
+            elif isinstance(node, ast.Assign):
+                for target in node.targets:
+                    defined.update(self._extract_names_from_target(target))
+
+            elif isinstance(node, ast.AnnAssign):
+                if node.target:
+                    defined.update(self._extract_names_from_target(node.target))
+
+            elif isinstance(node, ast.AugAssign):
+                defined.update(self._extract_names_from_target(node.target))
+
+            elif isinstance(node, ast.NamedExpr):  # Walrus operator :=
+                defined.add(node.target.id)
+
+            # For loop variables
+            elif isinstance(node, ast.For):
+                defined.update(self._extract_names_from_target(node.target))
+
+            # With statement variables
+            elif isinstance(node, ast.With):
+                for item in node.items:
+                    if item.optional_vars:
+                        defined.update(
+                            self._extract_names_from_target(item.optional_vars)
+                        )
+
+            # Exception handlers
+            elif isinstance(node, ast.ExceptHandler):
+                if node.name:
+                    defined.add(node.name)
+
+            # Comprehension variables
+            elif isinstance(node, ast.comprehension):
+                defined.update(self._extract_names_from_target(node.target))
+
+        return defined
+
+    def _extract_names_from_target(self, target: ast.AST) -> set[str]:
+        """Extract variable names from an assignment target."""
+        names: set[str] = set()
+
+        if isinstance(target, ast.Name):
+            names.add(target.id)
+        elif isinstance(target, ast.Tuple | ast.List):
+            for elt in target.elts:
+                names.update(self._extract_names_from_target(elt))
+        elif isinstance(target, ast.Starred):
+            names.update(self._extract_names_from_target(target.value))
+        # ast.Attribute and ast.Subscript don't define new names
+
+        return names
+
+    def _collect_used_names(self, tree: ast.AST) -> set[str]:
+        """
+        Collect all names used (referenced) in the code.
+
+        Only collects top-level names (e.g., `pytest` from `pytest.raises()`).
+        """
+        used: set[str] = set()
+
+        for node in ast.walk(tree):
+            # Check if this is a Name node in Load context (being read, not assigned)
+            if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+                used.add(node.id)
+
+        return used

atomicguard/infrastructure/__init__.py

@@ -1,7 +1,7 @@
 """
 Infrastructure layer for the Dual-State Framework.
 
-Contains adapters for external concerns (persistence, LLMs, etc.).
+Contains adapters for external concerns (persistence, LLMs, registry, etc.).
 """
 
 from atomicguard.infrastructure.llm import (
@@ -12,6 +12,7 @@ from atomicguard.infrastructure.persistence import (
     FilesystemArtifactDAG,
     InMemoryArtifactDAG,
 )
+from atomicguard.infrastructure.registry import GeneratorRegistry
 
 __all__ = [
     # Persistence
@@ -20,4 +21,6 @@ __all__ = [
     # LLM
     "OllamaGenerator",
     "MockGenerator",
+    # Registry
+    "GeneratorRegistry",
 ]

atomicguard/infrastructure/llm/__init__.py

@@ -2,10 +2,12 @@
 LLM adapters for artifact generation.
 """
 
+from atomicguard.infrastructure.llm.huggingface import HuggingFaceGenerator
 from atomicguard.infrastructure.llm.mock import MockGenerator
 from atomicguard.infrastructure.llm.ollama import OllamaGenerator
 
 __all__ = [
-    "OllamaGenerator",
+    "HuggingFaceGenerator",
     "MockGenerator",
+    "OllamaGenerator",
 ]

atomicguard/infrastructure/llm/huggingface.py

@@ -0,0 +1,180 @@
+"""
+HuggingFace Inference API generator implementation.
+
+Connects to HuggingFace Inference Providers via the huggingface_hub
+InferenceClient for chat completion.
+"""
+
+import os
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, cast
+
+from atomicguard.domain.interfaces import GeneratorInterface
+from atomicguard.domain.models import (
+    Artifact,
+    ArtifactStatus,
+    Context,
+    ContextSnapshot,
+)
+from atomicguard.domain.prompts import PromptTemplate
+
+
+@dataclass
+class HuggingFaceGeneratorConfig:
+    """Configuration for HuggingFaceGenerator.
+
+    This typed config ensures unknown fields are rejected at construction time.
+    """
+
+    model: str = "Qwen/Qwen2.5-Coder-32B-Instruct"
+    api_key: str | None = None  # Auto-detects from HF_TOKEN env var
+    provider: str | None = None  # e.g. "auto", "hf-inference", "together"
+    timeout: float = 120.0
+    temperature: float = 0.7
+    max_tokens: int = 4096
+
+
+class HuggingFaceGenerator(GeneratorInterface):
+    """Connects to HuggingFace Inference API using huggingface_hub."""
+
+    config_class = HuggingFaceGeneratorConfig
+
+    def __init__(
+        self, config: HuggingFaceGeneratorConfig | None = None, **kwargs: Any
+    ) -> None:
+        """
+        Args:
+            config: Typed configuration object (preferred)
+            **kwargs: Legacy kwargs for backward compatibility (deprecated)
+        """
+        if config is None:
+            config = HuggingFaceGeneratorConfig(**kwargs)
+
+        try:
+            from huggingface_hub import InferenceClient
+        except ImportError as err:
+            raise ImportError(
+                "huggingface_hub library required: pip install huggingface_hub"
+            ) from err
+
+        api_key = config.api_key
+        if api_key is None:
+            api_key = os.environ.get("HF_TOKEN")
+            if not api_key:
+                raise ValueError(
+                    "HuggingFace API key required: set HF_TOKEN environment "
+                    "variable or pass api_key in config"
+                )
+
+        client_kwargs: dict[str, Any] = {
+            "api_key": api_key,
+            "timeout": config.timeout,
+        }
+        if config.provider is not None:
+            client_kwargs["provider"] = config.provider
+
+        self._model = config.model
+        self._client = InferenceClient(**client_kwargs)
+        self._temperature = config.temperature
+        self._max_tokens = config.max_tokens
+        self._version_counter = 0
+
+    def generate(
+        self,
+        context: Context,
+        template: PromptTemplate | None = None,
+        action_pair_id: str = "unknown",
+        workflow_id: str = "unknown",
+    ) -> Artifact:
+        """Generate an artifact based on context."""
+        if template:
+            prompt = template.render(context)
+        else:
+            prompt = self._build_basic_prompt(context)
+
+        messages: list[dict[str, str]] = [
+            {
+                "role": "system",
+                "content": (
+                    "You are a Python programming assistant. "
+                    "Provide complete, runnable code in a markdown block:\n"
+                    "```python\n# code\n```"
+                ),
+            },
+            {"role": "user", "content": prompt},
+        ]
+
+        response = self._client.chat_completion(
+            messages=cast(Any, messages),
+            model=self._model,
+            temperature=self._temperature,
+            max_tokens=self._max_tokens,
+        )
+
+        content = response.choices[0].message.content or ""
+        code = self._extract_code(content)
+
+        self._version_counter += 1
+
+        return Artifact(
+            artifact_id=str(uuid.uuid4()),
+            workflow_id=workflow_id,
+            content=code,
+            previous_attempt_id=None,
+            parent_action_pair_id=None,
+            action_pair_id=action_pair_id,
+            created_at=datetime.now().isoformat(),
+            attempt_number=self._version_counter,
+            status=ArtifactStatus.PENDING,
+            guard_result=None,
+            feedback="",
+            context=ContextSnapshot(
+                workflow_id=workflow_id,
+                specification=context.specification,
+                constraints=context.ambient.constraints,
+                feedback_history=(),
+                dependency_artifacts=context.dependency_artifacts,
+            ),
+        )
+
+    def _extract_code(self, content: str) -> str:
+        """Extract Python code from response."""
+        if not content or content.isspace():
+            return ""
+
+        # Try python block
+        match = re.search(r"```python\n(.*?)\n```", content, re.DOTALL)
+        if match:
+            return match.group(1)
+
+        # Try generic block
+        match = re.search(r"```\n(.*?)\n```", content, re.DOTALL)
+        if match:
+            return match.group(1)
+
+        # Try first def/import/class
+        match = re.search(r"^(def |import |class )", content, re.MULTILINE)
+        if match:
+            return content[match.start() :]
+
+        # No code block found - return empty to trigger guard validation failure
+        return ""
+
+    def _build_basic_prompt(self, context: Context) -> str:
+        """Build a basic prompt from context."""
+        parts = [context.specification]
+
+        if context.current_artifact:
+            parts.append(f"\nPrevious attempt:\n{context.current_artifact}")
+
+        if context.feedback_history:
+            feedback_text = "\n".join(
+                f"Attempt {i + 1} feedback: {f}"
+                for i, (_, f) in enumerate(context.feedback_history)
+            )
+            parts.append(f"\nFeedback history:\n{feedback_text}")
+
+        return "\n".join(parts)

atomicguard/infrastructure/llm/mock.py

@@ -5,26 +5,49 @@ Returns predefined responses in sequence.
 """
 
 import uuid
+from dataclasses import dataclass, field
 from datetime import datetime
+from typing import Any
 
 from atomicguard.domain.interfaces import GeneratorInterface
 from atomicguard.domain.models import Artifact, ArtifactStatus, Context, ContextSnapshot
 from atomicguard.domain.prompts import PromptTemplate
 
 
+@dataclass
+class MockGeneratorConfig:
+    """Configuration for MockGenerator.
+
+    This typed config ensures unknown fields are rejected at construction time.
+    """
+
+    responses: list[str] = field(default_factory=list)
+
+
 class MockGenerator(GeneratorInterface):
     """Returns predefined responses for testing."""
 
-    def __init__(self, responses: list[str]):
+    config_class = MockGeneratorConfig
+
+    def __init__(self, config: MockGeneratorConfig | None = None, **kwargs: Any):
         """
         Args:
-            responses: List of response strings to return in sequence
+            config: Typed configuration object (preferred)
+            **kwargs: Legacy kwargs for backward compatibility (deprecated)
         """
-        self._responses = responses
+        # Support both config object and legacy kwargs
+        if config is None:
+            config = MockGeneratorConfig(**kwargs)
+
+        self._responses = config.responses
         self._call_count = 0
 
     def generate(
-        self, _context: Context, _template: PromptTemplate | None = None
+        self,
+        _context: Context,
+        _template: PromptTemplate | None = None,
+        action_pair_id: str = "unknown",
+        workflow_id: str = "unknown",
     ) -> Artifact:
         """Return the next predefined response."""
         if self._call_count >= len(self._responses):
@@ -35,19 +58,22 @@ class MockGenerator(GeneratorInterface):
 
         return Artifact(
             artifact_id=str(uuid.uuid4()),
+            workflow_id=workflow_id,
             content=content,
             previous_attempt_id=None,
-            action_pair_id="mock",
+            parent_action_pair_id=None,
+            action_pair_id=action_pair_id,
             created_at=datetime.now().isoformat(),
             attempt_number=self._call_count,
             status=ArtifactStatus.PENDING,
             guard_result=None,
             feedback="",
             context=ContextSnapshot(
+                workflow_id=workflow_id,
                 specification="",
                 constraints="",
                 feedback_history=(),
-                dependency_ids=(),
+                dependency_artifacts=(),
             ),
         )
 

atomicguard/infrastructure/llm/ollama.py

@@ -6,6 +6,7 @@ Connects to Ollama instances via the OpenAI-compatible API.
 
 import re
 import uuid
+from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, cast
 
@@ -21,36 +22,52 @@ from atomicguard.domain.prompts import PromptTemplate
 DEFAULT_OLLAMA_URL = "http://localhost:11434/v1"
 
 
+@dataclass
+class OllamaGeneratorConfig:
+    """Configuration for OllamaGenerator.
+
+    This typed config ensures unknown fields are rejected at construction time.
+    """
+
+    model: str = "qwen2.5-coder:7b"
+    base_url: str = DEFAULT_OLLAMA_URL
+    timeout: float = 120.0
+
+
 class OllamaGenerator(GeneratorInterface):
     """Connects to Ollama instance using OpenAI-compatible API."""
 
-    def __init__(
-        self,
-        model: str = "qwen2.5-coder:7b",
-        base_url: str = DEFAULT_OLLAMA_URL,
-        timeout: float = 120.0,
-    ):
+    config_class = OllamaGeneratorConfig
+
+    def __init__(self, config: OllamaGeneratorConfig | None = None, **kwargs: Any):
         """
         Args:
-            model: Ollama model name
-            base_url: Ollama API URL
-            timeout: Request timeout in seconds
+            config: Typed configuration object (preferred)
+            **kwargs: Legacy kwargs for backward compatibility (deprecated)
         """
+        # Support both config object and legacy kwargs
+        if config is None:
+            config = OllamaGeneratorConfig(**kwargs)
+
         try:
             from openai import OpenAI
         except ImportError as err:
             raise ImportError("openai library required: pip install openai") from err
 
-        self._model = model
+        self._model = config.model
         self._client = OpenAI(
-            base_url=base_url,
+            base_url=config.base_url,
             api_key="ollama",  # required but unused
-            timeout=timeout,
+            timeout=config.timeout,
         )
         self._version_counter = 0
 
     def generate(
-        self, context: Context, template: PromptTemplate | None = None
+        self,
+        context: Context,
+        template: PromptTemplate | None = None,
+        action_pair_id: str = "unknown",
+        workflow_id: str = "unknown",
     ) -> Artifact:
         """Generate an artifact based on context."""
         # Build prompt
@@ -79,24 +96,30 @@ class OllamaGenerator(GeneratorInterface):
 
         return Artifact(
             artifact_id=str(uuid.uuid4()),
+            workflow_id=workflow_id,
             content=code,
             previous_attempt_id=None,
-            action_pair_id="ollama",
+            parent_action_pair_id=None,
+            action_pair_id=action_pair_id,
             created_at=datetime.now().isoformat(),
             attempt_number=self._version_counter,
             status=ArtifactStatus.PENDING,
             guard_result=None,
             feedback="",
             context=ContextSnapshot(
+                workflow_id=workflow_id,
                 specification=context.specification,
                 constraints=context.ambient.constraints,
                 feedback_history=(),
-                dependency_ids=(),
+                dependency_artifacts=context.dependency_artifacts,
             ),
         )
 
     def _extract_code(self, content: str) -> str:
         """Extract Python code from response."""
+        if not content or content.isspace():
+            return ""
+
         # Try python block
         match = re.search(r"```python\n(.*?)\n```", content, re.DOTALL)
         if match:
@@ -112,8 +135,8 @@ class OllamaGenerator(GeneratorInterface):
         if match:
             return content[match.start() :]
 
-        # Fallback: full content
-        return content
+        # No code block found - return empty to trigger guard validation failure
+        return ""
 
     def _build_basic_prompt(self, context: Context) -> str:
         """Build a basic prompt from context."""

atomicguard/infrastructure/persistence/__init__.py

@@ -1,11 +1,17 @@
 """
-Persistence adapters for the Artifact DAG.
+Persistence adapters for the Artifact and Checkpoint DAGs.
 """
 
+from atomicguard.infrastructure.persistence.checkpoint import (
+    FilesystemCheckpointDAG,
+    InMemoryCheckpointDAG,
+)
 from atomicguard.infrastructure.persistence.filesystem import FilesystemArtifactDAG
 from atomicguard.infrastructure.persistence.memory import InMemoryArtifactDAG
 
 __all__ = [
     "InMemoryArtifactDAG",
     "FilesystemArtifactDAG",
+    "InMemoryCheckpointDAG",
+    "FilesystemCheckpointDAG",
 ]