atomicguard 0.1.0__tar.gz

atomicguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Thompson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atomicguard-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: atomicguard
+Version: 0.1.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>
+License: MIT
+Project-URL: Homepage, https://github.com/thompsonson/atomicguard
+Project-URL: Repository, https://github.com/thompsonson/atomicguard
+Project-URL: Documentation, https://github.com/thompsonson/atomicguard#readme
+Project-URL: Issues, https://github.com/thompsonson/atomicguard/issues
+Project-URL: Changelog, https://github.com/thompsonson/atomicguard/blob/main/CHANGELOG.md
+Keywords: llm,agents,code-generation,neuro-symbolic,guards,ai,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+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"
+Dynamic: license-file
+
+# AtomicGuard
+
+[![CI](https://github.com/thompsonson/atomicguard/actions/workflows/ci.yml/badge.svg)](https://github.com/thompsonson/atomicguard/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/thompsonson/atomicguard/branch/main/graph/badge.svg)](https://codecov.io/gh/thompsonson/atomicguard)
+[![PyPI version](https://badge.fury.io/py/atomicguard.svg)](https://badge.fury.io/py/atomicguard)
+[![Python versions](https://img.shields.io/pypi/pyversions/atomicguard.svg)](https://pypi.org/project/atomicguard/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Dual-State Agent Framework for reliable LLM code generation.
+
+> **New to AtomicGuard?** Start with the [Getting Started Guide](docs/getting-started.md).
+
+**Paper:** *Managing the Stochastic: Foundations of Learning in Neuro-Symbolic Systems for Software Engineering* (Thompson, 2025)
+
+## Overview
+
+AtomicGuard implements guard-validated generation loops that dramatically improve LLM reliability. The core abstraction is the **Atomic Action Pair** ⟨agen, G⟩ — coupling each generation action with a validation guard.
+
+Key results (Yi-Coder 9B, n=50):
+
+| Task | Baseline | Guarded | Improvement |
+|------|----------|---------|-------------|
+| Template | 35% | 90% | +55pp |
+| Password | 82% | 98% | +16pp |
+| LRU Cache | 94% | 100% | +6pp |
+
+## Installation
+
+```bash
+# From PyPI
+pip install atomicguard
+
+# From source
+git clone https://github.com/thompsonson/atomicguard.git
+cd atomicguard
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev,test]"
+```
+
+## Quick Start
+
+```python
+from atomicguard import (
+    OllamaGenerator, SyntaxGuard, TestGuard,
+    CompositeGuard, ActionPair, DualStateAgent,
+    InMemoryArtifactDAG
+)
+
+# Setup
+generator = OllamaGenerator(model="qwen2.5-coder:7b")
+guard = CompositeGuard([SyntaxGuard(), TestGuard("assert add(2, 3) == 5")])
+action_pair = ActionPair(generator=generator, guard=guard)
+agent = DualStateAgent(action_pair, InMemoryArtifactDAG(), rmax=3)
+
+# Execute
+artifact = agent.execute("Write a function that adds two numbers")
+print(artifact.content)
+```
+
+See [examples/](examples/) for more detailed usage, including a [mock example](examples/basic_mock.py) that works without an LLM.
+
+## Benchmarks
+
+Run the simulation from the paper:
+
+```bash
+python -m benchmarks.simulation --model yi-coder:9b --trials 50 --task all --output results/results.db --format sqlite
+
+# Generate report
+python -m benchmarks.simulation --visualize --output results/results.db --format sqlite
+```
+
+## Project Structure
+
+```
+atomicguard/
+├── src/atomicguard/     # Core library
+├── benchmarks/          # Simulation code
+├── docs/design/         # Design documents
+├── examples/            # Usage examples
+└── results/             # Generated reports & charts
+```
+
+## Citation
+
+```bibtex
+@article{thompson2025managing,
+  title={Managing the Stochastic: Foundations of Learning in Neuro-Symbolic Systems for Software Engineering},
+  author={Thompson, Matthew},
+  year={2025}
+}
+```
+
+## License
+
+MIT

atomicguard-0.1.0/README.md

@@ -0,0 +1,96 @@
+# AtomicGuard
+
+[![CI](https://github.com/thompsonson/atomicguard/actions/workflows/ci.yml/badge.svg)](https://github.com/thompsonson/atomicguard/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/thompsonson/atomicguard/branch/main/graph/badge.svg)](https://codecov.io/gh/thompsonson/atomicguard)
+[![PyPI version](https://badge.fury.io/py/atomicguard.svg)](https://badge.fury.io/py/atomicguard)
+[![Python versions](https://img.shields.io/pypi/pyversions/atomicguard.svg)](https://pypi.org/project/atomicguard/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Dual-State Agent Framework for reliable LLM code generation.
+
+> **New to AtomicGuard?** Start with the [Getting Started Guide](docs/getting-started.md).
+
+**Paper:** *Managing the Stochastic: Foundations of Learning in Neuro-Symbolic Systems for Software Engineering* (Thompson, 2025)
+
+## Overview
+
+AtomicGuard implements guard-validated generation loops that dramatically improve LLM reliability. The core abstraction is the **Atomic Action Pair** ⟨agen, G⟩ — coupling each generation action with a validation guard.
+
+Key results (Yi-Coder 9B, n=50):
+
+| Task | Baseline | Guarded | Improvement |
+|------|----------|---------|-------------|
+| Template | 35% | 90% | +55pp |
+| Password | 82% | 98% | +16pp |
+| LRU Cache | 94% | 100% | +6pp |
+
+## Installation
+
+```bash
+# From PyPI
+pip install atomicguard
+
+# From source
+git clone https://github.com/thompsonson/atomicguard.git
+cd atomicguard
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev,test]"
+```
+
+## Quick Start
+
+```python
+from atomicguard import (
+    OllamaGenerator, SyntaxGuard, TestGuard,
+    CompositeGuard, ActionPair, DualStateAgent,
+    InMemoryArtifactDAG
+)
+
+# Setup
+generator = OllamaGenerator(model="qwen2.5-coder:7b")
+guard = CompositeGuard([SyntaxGuard(), TestGuard("assert add(2, 3) == 5")])
+action_pair = ActionPair(generator=generator, guard=guard)
+agent = DualStateAgent(action_pair, InMemoryArtifactDAG(), rmax=3)
+
+# Execute
+artifact = agent.execute("Write a function that adds two numbers")
+print(artifact.content)
+```
+
+See [examples/](examples/) for more detailed usage, including a [mock example](examples/basic_mock.py) that works without an LLM.
+
+## Benchmarks
+
+Run the simulation from the paper:
+
+```bash
+python -m benchmarks.simulation --model yi-coder:9b --trials 50 --task all --output results/results.db --format sqlite
+
+# Generate report
+python -m benchmarks.simulation --visualize --output results/results.db --format sqlite
+```
+
+## Project Structure
+
+```
+atomicguard/
+├── src/atomicguard/     # Core library
+├── benchmarks/          # Simulation code
+├── docs/design/         # Design documents
+├── examples/            # Usage examples
+└── results/             # Generated reports & charts
+```
+
+## Citation
+
+```bibtex
+@article{thompson2025managing,
+  title={Managing the Stochastic: Foundations of Learning in Neuro-Symbolic Systems for Software Engineering},
+  author={Thompson, Matthew},
+  year={2025}
+}
+```
+
+## License
+
+MIT

atomicguard-0.1.0/pyproject.toml

@@ -0,0 +1,186 @@
+[project]
+name = "atomicguard"
+version = "0.1.0"
+description = "A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Matthew Thompson", email = "thompsonson@gmail.com" }
+]
+maintainers = [
+    { name = "Matthew Thompson", email = "thompsonson@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = [
+    "llm",
+    "agents",
+    "code-generation",
+    "neuro-symbolic",
+    "guards",
+    "ai",
+    "validation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Code Generators",
+    "Typing :: Typed",
+]
+dependencies = [
+    "click>=8.3.1",
+    "matplotlib>=3.10.0",
+    "openai>=2.12.0",
+    "rich>=14.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/thompsonson/atomicguard"
+Repository = "https://github.com/thompsonson/atomicguard"
+Documentation = "https://github.com/thompsonson/atomicguard#readme"
+Issues = "https://github.com/thompsonson/atomicguard/issues"
+Changelog = "https://github.com/thompsonson/atomicguard/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.13.0",
+    "pre-commit>=4.5.0",
+    "ruff>=0.14.0",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-cov>=6.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=75.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# =============================================================================
+# Semantic Release
+# =============================================================================
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/atomicguard/__init__.py:__version__"]
+branch = "main"
+commit_message = "chore(release): bump version to {version}"
+build_command = "pip install build && python -m build"
+upload_to_pypi = true
+upload_to_release = true
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"
+exclude_commit_patterns = [
+    "^chore\\(release\\):",
+    "^Merge",
+]
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.remote]
+type = "github"
+token = { env = "GH_TOKEN" }
+
+# =============================================================================
+# Testing
+# =============================================================================
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_functions = ["test_*"]
+addopts = [
+    "-ra",
+    "-q",
+    "--strict-markers",
+    "--strict-config",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+]
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["src/atomicguard"]
+branch = true
+omit = [
+    "*/__pycache__/*",
+    "*/tests/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+fail_under = 70
+show_missing = true
+
+# =============================================================================
+# Linting & Formatting
+# =============================================================================
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # Pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "UP",   # pyupgrade
+    "ARG",  # flake8-unused-arguments
+    "SIM",  # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # do not perform function calls in argument defaults
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["atomicguard"]
+
+# =============================================================================
+# Type Checking
+# =============================================================================
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+show_error_codes = true
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false

atomicguard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

atomicguard-0.1.0/src/atomicguard/__init__.py

@@ -0,0 +1,116 @@
+"""
+AtomicGuard: Dual-State Framework for LLM Output Management.
+
+A framework for managing stochastic LLM outputs through deterministic
+control flow, implementing the formal model from Thompson (2025).
+
+Example:
+    from atomicguard import Workflow, ActionPair
+    from atomicguard.guards import SyntaxGuard
+    from atomicguard.infrastructure import OllamaGenerator
+
+    generator = OllamaGenerator(model="qwen2.5-coder:7b")
+    guard = SyntaxGuard()
+    action_pair = ActionPair(generator=generator, guard=guard)
+
+    workflow = Workflow(rmax=3)
+    workflow.add_step('g_code', action_pair=action_pair)
+    result = workflow.execute("Write a function that adds two numbers")
+"""
+
+# Domain models (most commonly used)
+# Application layer (orchestration)
+from atomicguard.application.action_pair import ActionPair
+from atomicguard.application.agent import DualStateAgent
+from atomicguard.application.workflow import Workflow, WorkflowStep
+
+# Domain exceptions
+from atomicguard.domain.exceptions import RmaxExhausted
+
+# Domain interfaces (for type hints and custom implementations)
+from atomicguard.domain.interfaces import (
+    ArtifactDAGInterface,
+    GeneratorInterface,
+    GuardInterface,
+)
+from atomicguard.domain.models import (
+    AmbientEnvironment,
+    Artifact,
+    ArtifactStatus,
+    Context,
+    ContextSnapshot,
+    FeedbackEntry,
+    GuardResult,
+    WorkflowResult,
+    WorkflowState,
+)
+
+# Prompts and tasks (structures only - content defined by calling applications)
+from atomicguard.domain.prompts import (
+    PromptTemplate,
+    StepDefinition,
+    TaskDefinition,
+)
+
+# Guards (commonly composed)
+from atomicguard.guards import (
+    CompositeGuard,
+    DynamicTestGuard,
+    HumanReviewGuard,
+    SyntaxGuard,
+    TestGuard,
+)
+from atomicguard.infrastructure.llm import (
+    MockGenerator,
+    OllamaGenerator,
+)
+
+# Infrastructure (explicit import encouraged for dependency injection)
+from atomicguard.infrastructure.persistence import (
+    FilesystemArtifactDAG,
+    InMemoryArtifactDAG,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Domain models
+    "Artifact",
+    "ArtifactStatus",
+    "ContextSnapshot",
+    "FeedbackEntry",
+    "Context",
+    "AmbientEnvironment",
+    "GuardResult",
+    "WorkflowState",
+    "WorkflowResult",
+    # Prompts and tasks (structures only)
+    "PromptTemplate",
+    "StepDefinition",
+    "TaskDefinition",
+    # Domain interfaces
+    "GeneratorInterface",
+    "GuardInterface",
+    "ArtifactDAGInterface",
+    # Domain exceptions
+    "RmaxExhausted",
+    # Application layer
+    "ActionPair",
+    "DualStateAgent",
+    "Workflow",
+    "WorkflowStep",
+    # Infrastructure - Persistence
+    "InMemoryArtifactDAG",
+    "FilesystemArtifactDAG",
+    # Infrastructure - LLM
+    "OllamaGenerator",
+    "MockGenerator",
+    # Guards
+    "CompositeGuard",
+    "SyntaxGuard",
+    "TestGuard",
+    "DynamicTestGuard",
+    "HumanReviewGuard",
+]

atomicguard-0.1.0/src/atomicguard/application/__init__.py

@@ -0,0 +1,16 @@
+"""
+Application layer for the Dual-State Framework.
+
+Contains use cases and orchestration logic that coordinates domain objects.
+"""
+
+from atomicguard.application.action_pair import ActionPair
+from atomicguard.application.agent import DualStateAgent
+from atomicguard.application.workflow import Workflow, WorkflowStep
+
+__all__ = [
+    "ActionPair",
+    "DualStateAgent",
+    "Workflow",
+    "WorkflowStep",
+]

atomicguard-0.1.0/src/atomicguard/application/action_pair.py

@@ -0,0 +1,65 @@
+"""
+ActionPair: Atomic generation-verification transaction.
+
+Paper Definition 6: A = ⟨a_gen, G⟩
+Precondition ρ is handled at the Workflow level.
+"""
+
+from atomicguard.domain.interfaces import GeneratorInterface, GuardInterface
+from atomicguard.domain.models import Artifact, Context, GuardResult
+from atomicguard.domain.prompts import PromptTemplate
+
+
+class ActionPair:
+    """
+    Atomic generation-verification transaction.
+
+    Couples a generator with a guard to form an indivisible unit.
+    The precondition ρ is handled at the Workflow level.
+    """
+
+    def __init__(
+        self,
+        generator: GeneratorInterface,
+        guard: GuardInterface,
+        prompt_template: PromptTemplate | None = None,
+    ):
+        """
+        Args:
+            generator: The artifact generator
+            guard: The validator for generated artifacts
+            prompt_template: Optional structured prompt template
+        """
+        self._generator = generator
+        self._guard = guard
+        self._prompt_template = prompt_template
+
+    @property
+    def generator(self) -> GeneratorInterface:
+        """Access the generator (read-only)."""
+        return self._generator
+
+    @property
+    def guard(self) -> GuardInterface:
+        """Access the guard (read-only)."""
+        return self._guard
+
+    def execute(
+        self,
+        context: Context,
+        dependencies: dict[str, Artifact] | None = None,
+    ) -> tuple[Artifact, GuardResult]:
+        """
+        Execute the atomic generate-then-validate transaction.
+
+        Args:
+            context: Generation context
+            dependencies: Artifacts from prior workflow steps
+
+        Returns:
+            Tuple of (generated artifact, guard result)
+        """
+        dependencies = dependencies or {}
+        artifact = self._generator.generate(context, self._prompt_template)
+        result = self._guard.validate(artifact, **dependencies)
+        return artifact, result