atomicguard 2.0.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.

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:

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.

# Install the optional dependency
pip install huggingface_hub

# Set your API token
export HF_TOKEN="hf_your_token_here"

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:

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:

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.

@misc{thompson2025managing,
  title={Managing the Stochastic: Foundations of Learning in Neuro-Symbolic Systems for Software Engineering},
  author={Thompson, Matthew},
  year={2025},
  eprint={2512.20660},
  archivePrefix={arXiv},
  primaryClass={cs.LG},
  url={https://arxiv.org/abs/2512.20660}
}

License

MIT