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

atomicguard/__init__.py

@@ -73,7 +73,7 @@ from atomicguard.infrastructure.persistence import (
     InMemoryArtifactDAG,
 )
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 __all__ = [
     # Version

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__ = [
+    "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-1.1.0.dist-info → atomicguard-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomicguard
-Version: 1.1.0
+Version: 1.2.0
 Summary: A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops
 Author-email: Matthew Thompson <thompsonson@gmail.com>
 Maintainer-email: Matthew Thompson <thompsonson@gmail.com>
@@ -93,6 +93,67 @@ print(artifact.content)
 
 See [examples/](examples/) for more detailed usage, including a [mock example](examples/basic_mock.py) that works without an LLM.
 
+## LLM Backends
+
+AtomicGuard supports multiple LLM backends. Each generator implements `GeneratorInterface` and can be swapped in with no other code changes.
+
+### Ollama (local or cloud)
+
+Uses the OpenAI-compatible API. Works with any Ollama-served model:
+
+```python
+from atomicguard.infrastructure.llm import OllamaGenerator
+
+# Local instance (default: http://localhost:11434/v1)
+generator = OllamaGenerator(model="qwen2.5-coder:7b")
+```
+
+### HuggingFace Inference API
+
+Connects to HuggingFace Inference Providers via `huggingface_hub`. Supports any model available through the HF Inference API, including third-party providers like Together AI.
+
+```bash
+# Install the optional dependency
+pip install huggingface_hub
+
+# Set your API token
+export HF_TOKEN="hf_your_token_here"
+```
+
+```python
+from atomicguard.infrastructure.llm import HuggingFaceGenerator
+from atomicguard.infrastructure.llm.huggingface import HuggingFaceGeneratorConfig
+
+# Default: Qwen/Qwen2.5-Coder-32B-Instruct
+generator = HuggingFaceGenerator()
+
+# Custom model and provider
+generator = HuggingFaceGenerator(HuggingFaceGeneratorConfig(
+    model="Qwen/Qwen2.5-Coder-32B-Instruct",
+    provider="together",       # or "auto", "hf-inference"
+    temperature=0.7,
+    max_tokens=4096,
+))
+```
+
+Drop-in replacement in any workflow:
+
+```python
+from atomicguard import (
+    SyntaxGuard, TestGuard, CompositeGuard,
+    ActionPair, DualStateAgent, InMemoryArtifactDAG
+)
+from atomicguard.infrastructure.llm import HuggingFaceGenerator
+
+generator = HuggingFaceGenerator()
+guard = CompositeGuard([SyntaxGuard(), TestGuard("assert add(2, 3) == 5")])
+action_pair = ActionPair(generator=generator, guard=guard)
+agent = DualStateAgent(action_pair, InMemoryArtifactDAG(), rmax=3)
+
+artifact = agent.execute("Write a function that adds two numbers")
+print(artifact.content)
+```
+
 ## Benchmarks
 
 Run the simulation from the paper:
@@ -122,15 +183,16 @@ If you use this framework in your research, please cite the paper:
 > Thompson, M. (2025). Managing the Stochastic: Foundations of Learning in Neuro-Symbolic Systems for Software Engineering. arXiv preprint arXiv:2512.20660.
 
 ```bibtex
-@article{thompson2025managing,
+@misc{thompson2025managing,
   title={Managing the Stochastic: Foundations of Learning in Neuro-Symbolic Systems for Software Engineering},
   author={Thompson, Matthew},
-  journal={arXiv preprint arXiv:2512.20660},
   year={2025},
-  url={[https://arxiv.org/abs/2512.20660](https://arxiv.org/abs/2512.20660)}
+  eprint={2512.20660},
+  archivePrefix={arXiv},
+  primaryClass={cs.LG},
+  url={https://arxiv.org/abs/2512.20660}
 }
-
-``` 
+```
 
 ## License
 

{atomicguard-1.1.0.dist-info → atomicguard-1.2.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-atomicguard/__init__.py,sha256=baopCXBSWqGIeKbKuKurOUsxgDNbtHZMzyB1MmXHrNU,3051
+atomicguard/__init__.py,sha256=vW_pYf3hdmq4rgIYWc0319HMUAB-JkeraoqEdFIe--U,3051
 atomicguard/application/__init__.py,sha256=-myJt7VuC1tMjO424NhjY6iZZuUdHGnFCJKFapFCAhw,409
 atomicguard/application/action_pair.py,sha256=JfQH88gTZCMl5qa5frqLJnhebn-KgO_oGAol6sD58ys,2214
 atomicguard/application/agent.py,sha256=ND2_pnRGwcWM5MovM8dnratrMph2gz9UmwXEgTeA59s,5907
@@ -20,7 +20,8 @@ atomicguard/guards/static/imports.py,sha256=nWS3FNNqle7YWU5_tgRgYMRAXwEcWlxee8Q4
 atomicguard/guards/static/syntax.py,sha256=mPVgGDY3pzwtXuulmmuEwYAQG7rNG0fgSGB1puYRI6Y,919
 atomicguard/infrastructure/__init__.py,sha256=Y3Ot6sRgTind-8s5kCnNtRYJGN3uq84QmbAUESx8Pio,581
 atomicguard/infrastructure/registry.py,sha256=XilDY2sUedwm5z1Xrp39HfQ9e3paixyJxL_hwGaVbqs,3662
-atomicguard/infrastructure/llm/__init__.py,sha256=HVOeCf_wVx84h1EVh_OYvajcyn_5lWNIejTDccMJak0,234
+atomicguard/infrastructure/llm/__init__.py,sha256=wQg_FCAHmwbDXWm0bF5WX-9v7sutAS7RabhHCGiZZzo,338
+atomicguard/infrastructure/llm/huggingface.py,sha256=8VpkjuIzxAKOj3C6OBufS394AuDtbhreuPNv1rm-qJg,5756
 atomicguard/infrastructure/llm/mock.py,sha256=883Y7e2Q1yWapvp3rXn03bHEvuRnFwDe0CZsTZziG_E,2639
 atomicguard/infrastructure/llm/ollama.py,sha256=pLSZX_X5U1aPvIxCsF_wsQ_AHsTspqU3xkYHWLbgJQ0,4832
 atomicguard/infrastructure/persistence/__init__.py,sha256=KS95wmO_qVF6It63_884lWDoa-IB0WvRma_nXS2uTq4,483
@@ -28,9 +29,9 @@ atomicguard/infrastructure/persistence/checkpoint.py,sha256=MS4qpJ_jcl6Ibw7h3Knc
 atomicguard/infrastructure/persistence/filesystem.py,sha256=4upoycWCOlWRoSlVm4Ux_Kj8r3hX3Nm8N80x-IfBSLw,11440
 atomicguard/infrastructure/persistence/memory.py,sha256=JTnTwXSKYYDnQEYbjwAFVpklZVAlQlCDIt9zxcQjlz0,2042
 atomicguard/schemas/__init__.py,sha256=9z3gWBHsq8FHD2qE_TPy31wkTa_qXPfVgJrNdIu8p4g,3735
-atomicguard-1.1.0.dist-info/licenses/LICENSE,sha256=ROMMFVruZ18U24pKTNte9AK_YIqoMfXnMzoxqBNmKS4,1073
-atomicguard-1.1.0.dist-info/METADATA,sha256=XFS0IYTNDX_anzgWxUjyv5ha8YE_mdVtHW-GJM5SRJM,5013
-atomicguard-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-atomicguard-1.1.0.dist-info/entry_points.txt,sha256=wjCTsvKRBtbyiAQiGNNytVB3lbZU03Y0NtGvuPTvFLo,151
-atomicguard-1.1.0.dist-info/top_level.txt,sha256=J_6ENELjnacSYJ5N3FGwomp-sVeAJQohPkJBh6pu6iY,12
-atomicguard-1.1.0.dist-info/RECORD,,
+atomicguard-1.2.0.dist-info/licenses/LICENSE,sha256=ROMMFVruZ18U24pKTNte9AK_YIqoMfXnMzoxqBNmKS4,1073
+atomicguard-1.2.0.dist-info/METADATA,sha256=slCf2YR0p3mYoZR2XnP96NUdCiD-qr5tLgMGo-LU4jk,6831
+atomicguard-1.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+atomicguard-1.2.0.dist-info/entry_points.txt,sha256=MMVrkEyWFFCMoNIlpSWRY9FJYlEMGmaauvzMxEjwzTI,226
+atomicguard-1.2.0.dist-info/top_level.txt,sha256=J_6ENELjnacSYJ5N3FGwomp-sVeAJQohPkJBh6pu6iY,12
+atomicguard-1.2.0.dist-info/RECORD,,

{atomicguard-1.1.0.dist-info → atomicguard-1.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{atomicguard-1.1.0.dist-info → atomicguard-1.2.0.dist-info}/entry_points.txt

@@ -1,3 +1,4 @@
 [atomicguard.generators]
+HuggingFaceGenerator = atomicguard.infrastructure.llm:HuggingFaceGenerator
 MockGenerator = atomicguard.infrastructure.llm:MockGenerator
 OllamaGenerator = atomicguard.infrastructure.llm:OllamaGenerator