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

atomicguard/schemas/__init__.py

@@ -0,0 +1,142 @@
+"""AtomicGuard JSON Schema definitions and validation utilities.
+
+This module provides JSON Schema definitions for AtomicGuard configuration files,
+aligned with the formal framework defined in the paper.
+
+Schemas:
+    - workflow.schema.json: Workflow definition (action pairs, guards, preconditions)
+    - prompts.schema.json: Prompt templates for generators
+    - artifact.schema.json: Artifact storage format in DAG
+
+Usage:
+    from atomicguard.schemas import validate_workflow, validate_prompts
+
+    # Validate a workflow configuration
+    with open("workflow.json") as f:
+        data = json.load(f)
+    validate_workflow(data)  # Raises jsonschema.ValidationError if invalid
+"""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import types
+
+try:
+    import jsonschema as _jsonschema
+
+    jsonschema: types.ModuleType | None = _jsonschema
+except ImportError:
+    jsonschema = None
+
+
+def _load_schema(name: str) -> dict[str, Any]:
+    """Load a JSON schema from the schemas package.
+
+    Args:
+        name: Schema filename (e.g., 'workflow.schema.json')
+
+    Returns:
+        Parsed JSON schema as a dictionary
+    """
+    schema_text = files("atomicguard.schemas").joinpath(name).read_text()
+    result: dict[str, Any] = json.loads(schema_text)
+    return result
+
+
+def get_workflow_schema() -> dict[str, Any]:
+    """Get the workflow.json schema.
+
+    Returns:
+        JSON Schema for workflow configuration
+    """
+    return _load_schema("workflow.schema.json")
+
+
+def get_prompts_schema() -> dict[str, Any]:
+    """Get the prompts.json schema.
+
+    Returns:
+        JSON Schema for prompt templates
+    """
+    return _load_schema("prompts.schema.json")
+
+
+def get_artifact_schema() -> dict[str, Any]:
+    """Get the artifact.json schema.
+
+    Returns:
+        JSON Schema for artifact storage
+    """
+    return _load_schema("artifact.schema.json")
+
+
+def validate_workflow(data: dict[str, Any]) -> None:
+    """Validate a workflow configuration against the schema.
+
+    Args:
+        data: Workflow configuration dictionary
+
+    Raises:
+        jsonschema.ValidationError: If validation fails
+        ImportError: If jsonschema is not installed
+    """
+    if jsonschema is None:
+        raise ImportError(
+            "jsonschema is required for validation. "
+            "Install it with: pip install jsonschema"
+        )
+    schema = get_workflow_schema()
+    jsonschema.validate(data, schema)
+
+
+def validate_prompts(data: dict[str, Any]) -> None:
+    """Validate prompt templates against the schema.
+
+    Args:
+        data: Prompts configuration dictionary
+
+    Raises:
+        jsonschema.ValidationError: If validation fails
+        ImportError: If jsonschema is not installed
+    """
+    if jsonschema is None:
+        raise ImportError(
+            "jsonschema is required for validation. "
+            "Install it with: pip install jsonschema"
+        )
+    schema = get_prompts_schema()
+    jsonschema.validate(data, schema)
+
+
+def validate_artifact(data: dict[str, Any]) -> None:
+    """Validate an artifact against the schema.
+
+    Args:
+        data: Artifact dictionary
+
+    Raises:
+        jsonschema.ValidationError: If validation fails
+        ImportError: If jsonschema is not installed
+    """
+    if jsonschema is None:
+        raise ImportError(
+            "jsonschema is required for validation. "
+            "Install it with: pip install jsonschema"
+        )
+    schema = get_artifact_schema()
+    jsonschema.validate(data, schema)
+
+
+__all__ = [
+    "get_workflow_schema",
+    "get_prompts_schema",
+    "get_artifact_schema",
+    "validate_workflow",
+    "validate_prompts",
+    "validate_artifact",
+]

{atomicguard-0.1.0.dist-info → atomicguard-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomicguard
-Version: 0.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>
@@ -26,17 +26,10 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: click>=8.3.1
 Requires-Dist: matplotlib>=3.10.0
-Requires-Dist: openai>=2.12.0
-Requires-Dist: rich>=14.0.0
-Provides-Extra: dev
-Requires-Dist: mypy>=1.13.0; extra == "dev"
-Requires-Dist: pre-commit>=4.5.0; extra == "dev"
-Requires-Dist: ruff>=0.14.0; extra == "dev"
-Provides-Extra: test
-Requires-Dist: pytest>=8.0.0; extra == "test"
-Requires-Dist: pytest-cov>=6.0.0; extra == "test"
+Requires-Dist: openhands-ai>=0.27.0
+Requires-Dist: pydantic-ai>=1.0.0
+Requires-Dist: pytestarch>=4.0.1
 Dynamic: license-file
 
 # AtomicGuard
@@ -100,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:
@@ -124,11 +178,19 @@ atomicguard/
 
 ## Citation
 
+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},
-  year={2025}
+  year={2025},
+  eprint={2512.20660},
+  archivePrefix={arXiv},
+  primaryClass={cs.LG},
+  url={https://arxiv.org/abs/2512.20660}
 }
 ```
 

atomicguard-1.2.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+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
+atomicguard/application/workflow.py,sha256=mfWz2pdBqQsGC5rBZ5S1x_jaNe2aLvqoG20TvWyAsnM,23309
+atomicguard/domain/__init__.py,sha256=BRmYKYFU-kLG1wPpRrXKxZ2jb4QgMea83r0gbDX_Da0,1149
+atomicguard/domain/exceptions.py,sha256=Zj1iz31AiksyWnyKR8KfnNLRGhZdetrYhCIwFOapBtY,1376
+atomicguard/domain/interfaces.py,sha256=73vRiPzTLkVAiBc2srn-EUNFSQfleooQNx6r3odIQFM,6574
+atomicguard/domain/models.py,sha256=sVuHzuP98pgHefTz1mk1bYptgoeAySekRyBG2zMz7TE,8496
+atomicguard/domain/prompts.py,sha256=SMGcP0kYc9azCbGku5EG0JZZs83D80WkJO-DWiuFV58,2785
+atomicguard/guards/__init__.py,sha256=OzpOjwmyHGpTQSDVSDeGEuXUJNOyiNpZxZVnTVMIOyg,956
+atomicguard/guards/composite/__init__.py,sha256=AedlMBxFw4uTFExVWL6RJRR7vRwMOK3sgjhutkXz838,217
+atomicguard/guards/composite/base.py,sha256=VGydlOD4gmXdiDHvWXF5jSppXcJAoJYSCyDj7Lrbng0,1213
+atomicguard/guards/dynamic/__init__.py,sha256=pjBBeD_yYavvn-I7s5I3nTDOlZtPTq1Hqmim_RgW5cE,321
+atomicguard/guards/dynamic/test_runner.py,sha256=d5cPb5cCM-UnfZjTYGOHn4XoS-N66nr5EBHqPoDGwNM,7196
+atomicguard/guards/interactive/__init__.py,sha256=PlP5LNB4CMZ4fJ7Xr8gjjpn8VwLnB3zs5M2Em9xyVCc,226
+atomicguard/guards/interactive/human.py,sha256=G8SstAEdcMpHR2b8ugyG9drk9aBjw4_pE6E4UrTtcUo,2960
+atomicguard/guards/static/__init__.py,sha256=KANeEg_yhrKGzSmA0yf2SewOE9qkUwnJly4mWkBzsm4,305
+atomicguard/guards/static/imports.py,sha256=nWS3FNNqle7YWU5_tgRgYMRAXwEcWlxee8Q4MdomN5w,6292
+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=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
+atomicguard/infrastructure/persistence/checkpoint.py,sha256=MS4qpJ_jcl6Ibw7h3KncWgDqz7CEIlFJdrpFcu2vEgs,13966
+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.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-0.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.2.0.dist-info/entry_points.txt

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

atomicguard/guards/test_runner.py

@@ -1,176 +0,0 @@
-"""
-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-0.1.0.dist-info/RECORD

@@ -1,27 +0,0 @@
-atomicguard/__init__.py,sha256=kiNxqjbVSlSf6Z0U7wpus3o_eMTB7M5-Dj41qgcgUwI,2927
-atomicguard/application/__init__.py,sha256=-myJt7VuC1tMjO424NhjY6iZZuUdHGnFCJKFapFCAhw,409
-atomicguard/application/action_pair.py,sha256=pa9gw4cTb8HaZLT_VqjQaKVMGGllo0BcDf6YzqsJlnA,1959
-atomicguard/application/agent.py,sha256=uzwhrn43JkrK1xxuw8ETvjL4IAiVZ1_Jeik4tMY_2ZE,4254
-atomicguard/application/workflow.py,sha256=CPnLVaten4hN4fiC_gGMvN9-BCJIVVwYsQb3HtRTlJg,4902
-atomicguard/domain/__init__.py,sha256=z7CWqBs21XsZPLeuqLD1fNQVtl9VxIs3zkrK_1n4uD0,1061
-atomicguard/domain/exceptions.py,sha256=3L1acckIcf0XewBy8QJpzgCRBaKyYdossbIAikt1Xkw,770
-atomicguard/domain/interfaces.py,sha256=3kPXRof0a-4c225d1DgZ_66_5A6P8H1XZK-gTp9YkCI,2935
-atomicguard/domain/models.py,sha256=p9FqB9MdriV7djaGUkREGEgkcWyhGvpYmHYrLq2VX-w,4483
-atomicguard/domain/prompts.py,sha256=SMGcP0kYc9azCbGku5EG0JZZs83D80WkJO-DWiuFV58,2785
-atomicguard/guards/__init__.py,sha256=pd4H3sfnrN76vKBX3KrXWsoe27V5vNacSEUKW9uIbmM,548
-atomicguard/guards/base.py,sha256=VGydlOD4gmXdiDHvWXF5jSppXcJAoJYSCyDj7Lrbng0,1213
-atomicguard/guards/human.py,sha256=G8SstAEdcMpHR2b8ugyG9drk9aBjw4_pE6E4UrTtcUo,2960
-atomicguard/guards/syntax.py,sha256=mPVgGDY3pzwtXuulmmuEwYAQG7rNG0fgSGB1puYRI6Y,919
-atomicguard/guards/test_runner.py,sha256=dIFtyOXxu_dxKDlrsBl_G7kCR5oy5gLQESQtYGslKO4,5538
-atomicguard/infrastructure/__init__.py,sha256=98eYKEgEIzJ05Z5r82M7tB0S0QGD2PrfPR_8wapzfHA,465
-atomicguard/infrastructure/llm/__init__.py,sha256=lmr-cYVeaiAsMi_DWcoM7G1wEs6Y6GS02RZeOs4GI-U,234
-atomicguard/infrastructure/llm/mock.py,sha256=OVumDkWYe9xU8KQHdt79evpHzIJIRRxXIqeC9fgI-hQ,1840
-atomicguard/infrastructure/llm/ollama.py,sha256=jtE3SXfMSsYUDocuKXDH3H4NrR8cMwjvCpSFkn99Xlg,4019
-atomicguard/infrastructure/persistence/__init__.py,sha256=DdoD0V-uCetJDo_RJRPiCfjae3xAX5yofnQWbalBrJw,285
-atomicguard/infrastructure/persistence/filesystem.py,sha256=LpdExc9FAwB2Od8eM5zSEMx4hC4Lx2AaztJdba8_MD0,8638
-atomicguard/infrastructure/persistence/memory.py,sha256=gZo2hcpi5VOu60nscxPnyQBDg8P87MI9ZXBdaW0eebQ,1339
-atomicguard-0.1.0.dist-info/licenses/LICENSE,sha256=ROMMFVruZ18U24pKTNte9AK_YIqoMfXnMzoxqBNmKS4,1073
-atomicguard-0.1.0.dist-info/METADATA,sha256=yJlnBW1n_-4ORhWkIjTOykpD9vf6N9OHzO4mJIh39lc,4919
-atomicguard-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-atomicguard-0.1.0.dist-info/top_level.txt,sha256=J_6ENELjnacSYJ5N3FGwomp-sVeAJQohPkJBh6pu6iY,12
-atomicguard-0.1.0.dist-info/RECORD,,