AtomicGuard

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

Why AtomicGuard?

AI agents hallucinate. Worse, those hallucinations compound — each generation builds on the last, and errors propagate through the workflow.

AtomicGuard solves this by combining to aspects - decompose goals into small measurable tasks and through Bounded Indeterminacy: the LLM generates content, but a deterministic state machine controls the logic. Every generation is validated before the workflow advances.

Challenge	Solution
🛡️ Safety	Dual-State Architecture & Atomic Action Pairs
💾 State	Versioned Repository Items & Configuration Snapshots
🌐 Scale	Multi-Agent Coordination via Shared DAG
📈 Improvement	Continuous Learning from Guard Verdicts

→ Learn more about the architecture

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/
│   ├── guide/           # User-facing documentation
│   ├── reference/       # Reference material (glossary, AP catalog, flow diagrams)
│   ├── design/          # Architecture, plans, extensions, decisions
│   ├── theory/          # Formal agent theory and domain definitions
│   └── blog/            # Blog posts
├── examples/            # Usage examples
└── results/             # Generated reports & charts

Web Dashboard

The web dashboard lets you browse experiment results, manage workflow configurations, and inspect per-instance artifact DAGs.

Starting the dashboard

# Auto-detect ./output directory
uv run python -m atomicguard.web --output-dir output/

# Or point to a specific experiment's artifact_dags
uv run python -m atomicguard.web --artifact-dir output/my_experiment/model/artifact_dags/

# Custom host/port
uv run python -m atomicguard.web --output-dir output/ --host 127.0.0.1 --port 3000

Opens at http://localhost:8000 by default. The DAG viewer shows per-instance artifact graphs to review workflow progress, guard feedback, and retries.

Workflow management via database

Import workflow JSON configs and AP context into a SQLite database for editing in the UI:

# Import all workflows and AP context
uv run python -m atomicguard.web import-all \
  --workflows-dir examples/swe_bench_common/workflows/ \
  --ap-context examples/swe_bench_common/ap_context.json

# Export a workflow back to JSON
uv run python -m atomicguard.web export-workflow s1-tdd

# Export all AP context
uv run python -m atomicguard.web export-context

The database defaults to ~/.atomicguard/web.db. Override with --db path/to/db.

For running the dashboard as a persistent background service (systemd, launchd, nginx reverse proxy), see docs/guide/web-dashboard-service.md.

Legacy compatibility

The dashboard is also available via the old entry point:

uv run python -m examples.dashboard --output-dir output/

Development

# Install dependencies
uv sync

# Run unit tests
just test

# Run all tests (unit + architecture)
just test-all

# Lint and format
just lint
just fmt

# Type check
just typecheck

# Full CI pipeline
just ci

See the justfile for all available commands.

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

Metadata

Release files for atomicguard 2.38.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for atomicguard 2.38.0
File	Size	Uploaded
atomicguard-2.38.0.tar.gz	324.2 kB	Sep 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for atomicguard 2.38.0
File	Interpreter	ABI	Platform	Reset
atomicguard-2.38.0-py3-none-any.whl 407.9 kB Sep 21, 2026	Python 3	none	any	Details

Total release size: 732.1 kB

Release files / atomicguard-2.38.0.tar.gz

Download URL	atomicguard-2.38.0.tar.gz
Size	324.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`3734f6056bd6de5fa18797c4d4377ec7c33e92be28d1ab457ecb9775532502bd`
BLAKE2b-256 checksum How to use checksums	`d098c5e9ec92a68762edf3ac7b4da5c835362673d2501f4c397448e988f3b861`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / atomicguard-2.38.0-py3-none-any.whl

Download URL	atomicguard-2.38.0-py3-none-any.whl
Size	407.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c4db754f6a5d6ea532ed45f9fc8c0701439eea0c6455b76ccb1fddf1cebd0996`
BLAKE2b-256 checksum How to use checksums	`bdf536505a97d1abfcce665da98dad0de93b67f830d12e394e482ab348ba7335`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`