atomicguard 1.1.0__tar.gz → 1.2.0__tar.gz

{atomicguard-1.1.0/src/atomicguard.egg-info → atomicguard-1.2.0}/PKG-INFO

@@ -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 → atomicguard-1.2.0}/README.md

@@ -59,6 +59,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:
@@ -88,15 +149,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 → atomicguard-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atomicguard"
-version = "1.1.0"
+version = "1.2.0"
 description = "A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops"
 readme = "README.md"
 license = { text = "MIT" }
@@ -51,6 +51,7 @@ Changelog = "https://github.com/thompsonson/atomicguard/blob/main/CHANGELOG.md"
 [project.entry-points."atomicguard.generators"]
 # Core generators
 OllamaGenerator = "atomicguard.infrastructure.llm:OllamaGenerator"
+HuggingFaceGenerator = "atomicguard.infrastructure.llm:HuggingFaceGenerator"
 MockGenerator = "atomicguard.infrastructure.llm:MockGenerator"
 
 # Note: Dev dependencies are in [dependency-groups] below, not here.

{atomicguard-1.1.0 → atomicguard-1.2.0}/src/atomicguard/__init__.py

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

{atomicguard-1.1.0 → atomicguard-1.2.0}/src/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-1.2.0/src/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 → atomicguard-1.2.0/src/atomicguard.egg-info}/PKG-INFO

@@ -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 → atomicguard-1.2.0}/src/atomicguard.egg-info/SOURCES.txt

@@ -30,6 +30,7 @@ src/atomicguard/guards/static/syntax.py
 src/atomicguard/infrastructure/__init__.py
 src/atomicguard/infrastructure/registry.py
 src/atomicguard/infrastructure/llm/__init__.py
+src/atomicguard/infrastructure/llm/huggingface.py
 src/atomicguard/infrastructure/llm/mock.py
 src/atomicguard/infrastructure/llm/ollama.py
 src/atomicguard/infrastructure/persistence/__init__.py

{atomicguard-1.1.0 → atomicguard-1.2.0}/src/atomicguard.egg-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