atomicguard 1.1.0

A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops

AtomicGuard

A Dual-State Agent Framework for reliable LLM code generation.

New to AtomicGuard? Start with the Getting Started Guide.

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

# 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

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/ for more detailed usage, including a mock example that works without an LLM.

Benchmarks

Run the simulation from the paper:

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

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.

@article{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)}
}

License

MIT