agentbible 0.6.0

One-shot correct infrastructure for AI agents working on scientific code

AgentBible

One-shot correct infrastructure for AI agents working on scientific code.

Why AgentBible Exists

When AI generates scientific code, how do you know it's numerically correct? When you run an experiment, how do you reproduce it 6 months later?

AgentBible solves both problems:

• Core validators catch numerical bugs at runtime (@validate_finite, @validate_probability, etc.)
• Domain plugins add field-specific validation (quantum: @validate_unitary, @validate_density_matrix)
• Automatic provenance captures everything needed for reproducibility (git SHA, random seeds, package versions, hardware info)

Result: Research code you can trust and reproduce.

Install Now

pip install agentbible

Note: The package name is agentbible (no hyphen). If pip install agent-bible, you'll get an error.

# With HDF5 provenance support
pip install agentbible[hdf5]

# With semantic context retrieval
pip install agentbible[context]

# Full development install
pip install agentbible[all]

Troubleshooting: If bible command is not found after install:

# Check if it's in your PATH
python -m agentbible.cli.main --version

# On Linux/macOS, ensure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Or use pipx for isolated CLI tools
pipx install agentbible

The Problem AgentBible Solves

# WITHOUT AgentBible - silent bug, hours of debugging
def calculate_probability(logits):
    return np.exp(logits)  # Bug: forgot normalization
    # This returns values > 1. You won't catch it until your
    # model produces nonsense results and you spend hours debugging.

probs = calculate_probability(np.array([2.0, 1.0]))  # No error - bug silently propagates

# WITH AgentBible - catches it immediately
from agentbible import validate_finite, validate_probabilities

@validate_finite
@validate_probabilities
def calculate_probability(logits):
    return np.exp(logits)  # Same bug

probs = calculate_probability(np.array([2.0, 1.0]))
# ProbabilityBoundsError: Value not in [0, 1]
#   Expected: 0 <= p <= 1 (probability must be in unit interval)
#   Got: max = 7.389...
#   Function: calculate_probability
#
#   Reference: Kolmogorov, 'Foundations of Probability Theory'
#   Guidance: Probability must be in [0, 1]. Common causes:
#       - Forgot normalization (softmax)
#       - Numerical overflow

The bug is caught immediately, with an educational error message.

Quick Start

Create a New Project

bible init my-simulation --template python-scientific
cd my-simulation
source .venv/bin/activate
pip install -e ".[dev]"
pytest  # Tests pass immediately

Use Core Validators (Any Scientific Code)

from agentbible import (
    validate_finite,
    validate_positive,
    validate_probability,
    validate_normalized,
)
import numpy as np

@validate_finite
@validate_positive
def calculate_energy(mass: float, velocity: np.ndarray) -> float:
    """Kinetic energy must be finite and positive."""
    return 0.5 * mass * np.dot(velocity, velocity)

@validate_finite
@validate_normalized()
def softmax(logits: np.ndarray) -> np.ndarray:
    """Softmax must be finite and sum to 1."""
    exp_logits = np.exp(logits - np.max(logits))
    return exp_logits / exp_logits.sum()

# Validation happens automatically on return
energy = calculate_energy(2.0, np.array([1, 2, 3]))  # OK
probs = softmax(np.array([2.0, 1.0, 0.1]))           # OK - sums to 1

Use Domain Validators (Quantum Computing)

# Quantum validators are in the domains subpackage
from agentbible.domains.quantum import (
    validate_unitary,
    validate_hermitian,
    validate_density_matrix,
)
import numpy as np

@validate_unitary
def create_hadamard():
    """Returns Hadamard gate - validated as unitary."""
    return np.array([[1, 1], [1, -1]], dtype=complex) / np.sqrt(2)

@validate_density_matrix
def create_mixed_state():
    """Returns maximally mixed state - validated as density matrix."""
    return np.eye(2, dtype=complex) / 2

# Validation happens automatically on return
H = create_hadamard()      # OK - unitary
rho = create_mixed_state() # OK - trace=1, Hermitian, positive semi-definite

Validate Data Files

# Validate a numpy matrix
bible validate state.npy --check unitarity

# Validate HDF5 with all checks
bible validate results.h5 --check all

# Multiple specific checks
bible validate matrix.npy -c hermiticity -c trace -c positivity

Save Data with Provenance

from agentbible.provenance import save_with_metadata, load_with_metadata
import numpy as np

# Save with full reproducibility metadata
save_with_metadata(
    "results.h5",
    {"density_matrix": rho, "eigenvalues": np.linalg.eigvalsh(rho)},
    description="Ground state calculation",
)

# Load with metadata
data, metadata = load_with_metadata("results.h5")
print(metadata["git_sha"])      # "a1b2c3d..."
print(metadata["timestamp"])    # "2026-01-01T12:00:00+00:00"
print(metadata["packages"])     # {"numpy": "1.26.0", ...}
print(metadata["pip_freeze"])   # Full pip freeze for exact reproduction
print(metadata["hardware"])     # CPU model, GPU info, memory

Physics-Aware Testing

from agentbible.testing import physics_test, deterministic_seed
import numpy as np

@physics_test(checks=["unitarity", "hermiticity"])
def test_pauli_x():
    """Automatically validates return value."""
    return np.array([[0, 1], [1, 0]], dtype=complex)

def test_reproducible(deterministic_seed):
    """Seeds are set to 42 for reproducibility."""
    random_value = np.random.rand()
    assert random_value == 0.3745401188473625  # Always the same

Who This Is For

AgentBible is for:

• Researchers using AI agents (Claude, Copilot, Cursor) to write scientific code
• ML/Physics/HPC developers who care about correctness and reproducibility
• Quantum computing developers who need physics validation
• PhD students who want rigorous software from day one
• Anyone who has lost hours debugging a subtle numerical bug

AgentBible is NOT for:

• Enterprise web applications
• Frontend/GUI projects
• Code that doesn't involve numerical computation

Features

Core Validators (Always Available)

Decorator	Validates
@validate_finite	No NaN or Inf
@validate_positive	Value > 0
@validate_non_negative	Value >= 0
@validate_range(min, max)	Value in [min, max]
@validate_probability	Value in [0, 1]
@validate_probabilities	Array of probabilities
@validate_normalized	Sum or norm = 1

Quantum Domain (agentbible.domains.quantum)

Decorator	Validates
@validate_unitary	U @ U.H = I
@validate_hermitian	A = A.H
@validate_density_matrix	Hermitian, trace=1, positive semi-definite

ML Domain (agentbible.domains.ml)

Function/Decorator	Validates
check_no_leakage(features, forbidden)	No forbidden features (data leakage)
check_coverage(y_true, y_lower, y_upper)	Prediction interval coverage
check_exchangeability(residuals)	Conformal prediction assumptions
@validate_cv_strategy	Warn if random CV inappropriate

Atmospheric Domain (agentbible.domains.atmospheric)

Function	Validates
check_cloud_base_height(arr)	CBH in valid range (0-12000m)
check_boundary_layer_height(arr)	BLH in valid range (10-5000m)
check_cloud_layer_consistency(base, top)	Cloud base < cloud top
check_relative_humidity(arr)	RH in [0, 100]%

Validation Pipeline

from agentbible.validators import ValidationPipeline, check_finite, check_positive

# Compose validators
pipeline = ValidationPipeline([check_finite, check_positive], name="energy")
pipeline(energy_array)  # Runs all checks

All validators:

• Check for NaN/Inf before domain-specific checks
• Support both rtol and atol tolerances
• Provide educational error messages with academic references

CLI Commands

bible init <name>                     # Create project from template (+ AGENTS.md)
bible scaffold <file>                 # Generate module stubs with tests
bible retrofit                        # Add AgentBible to existing project
bible validate <file>                 # Validate physics constraints
bible audit code <path>              # Check code against AgentBible principles
bible audit context [file]           # Score AGENTS.md / .cursorrules tightness
bible generate-agents-md             # Generate minimal evidence-based AGENTS.md
bible context --query "topic"        # Retrieve task-specific AI context
bible ci status                       # Show CI/CD workflow status
bible info                            # Show installation info

Context audit scores your AGENTS.md against arxiv:2602.11988 findings — that broad context files hurt agent performance. Score ≥ 70 passes; use --json for CI integration.

bible audit context AGENTS.md        # Score: 95/100 ✓
bible generate-agents-md --domain quantum --stdout  # Preview output

Configuration

Control validation behavior via environment variable:

# Full validation (default) - catches all physics errors
export AGENTBIBLE_VALIDATION_LEVEL=debug

# Lite mode - only NaN/Inf checks (faster)
export AGENTBIBLE_VALIDATION_LEVEL=lite

# Off - skip all validation (for benchmarking only!)
export AGENTBIBLE_VALIDATION_LEVEL=off

Or per-decorator:

@validate_unitary(level="lite")  # Override for this function
def my_gate():
    ...

Check current level with bible info.

Provenance Metadata

save_with_metadata() automatically captures:

• Git SHA, branch, dirty status, and diff (if uncommitted changes)
• UTC timestamp (ISO 8601)
• Random seeds (numpy, python, torch)
• Hostname, platform, Python version
• Package versions (numpy, scipy, h5py, torch, etc.)
• Full pip freeze output for exact environment reproduction
• Hardware info (CPU model, core count, memory, GPU details)

Testing Fixtures

Fixture	Purpose
deterministic_seed	Sets numpy/random to seed 42
tolerance	Returns {"rtol": 1e-10, "atol": 1e-12}
quantum_tolerance	Returns {"rtol": 1e-6, "atol": 1e-8}

Project Templates

Python Scientific (python-scientific)

Pre-configured with:

• ruff for linting (strict rules)
• mypy in strict mode
• pytest with 80% coverage minimum
• Physics validation helpers
• AGENTS.md + .cursorrules for AI agents (minimal context, arxiv:2602.11988)

bible init my-project --template python-scientific

C++ HPC/CUDA (cpp-hpc-cuda)

Pre-configured with:

• CMake with zero-warning policy
• GoogleTest for testing
• CUDA support (optional)
• Physical validation functions

bible init my-project --template cpp-hpc-cuda

The 5 Principles

1. Correctness First - Physical accuracy is non-negotiable
2. Specification Before Code - Tests define the contract
3. Fail Fast with Clarity - Validate inputs, descriptive errors
4. Simplicity by Design - Functions <= 50 lines, single responsibility
5. Infrastructure Enables Speed - CI, tests, linting from day one

Status

v0.6.0 (Alpha) - Evidence-based minimal context tooling. API stable, ready for real use.

• Core validators work for any scientific code
• Quantum domain validators via agentbible.domains.quantum
• ML domain validators via agentbible.domains.ml
• Atmospheric domain validators via agentbible.domains.atmospheric
• ValidationPipeline for composing multiple checks
• bible audit context — scores AGENTS.md tightness (arxiv:2602.11988)
• bible generate-agents-md — generates minimal ≤20-line AGENTS.md
• bible init generates AGENTS.md alongside .cursorrules

See the full ROADMAP.md for what's coming next.

Documentation

Full documentation: rylanmalarchick.github.io/research-code-principles

• Getting Started
• Validators Guide
• Provenance Guide
• API Reference
• Philosophy - Why good code matters
• Style Guide - Coding conventions
• CHANGELOG - Release history

Getting Help

• Questions? Open a GitHub Issue
• Found a bug? Report it here
• Want to contribute? See CONTRIBUTING.md
• Security issues? See SECURITY.md
• Email: [e-mail]

Development

# Clone and setup
git clone https://github.com/rylanmalarchick/research-code-principles
cd research-code-principles
./bootstrap.sh

# Or manually
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,hdf5]"

# Run tests
pytest tests/ -v

# Lint and type check
ruff check agentbible/
mypy agentbible/

License

MIT - Use and adapt freely.

Author

Rylan Malarchick - [e-mail]

---

v0.6.0 - Evidence-based minimal context tooling (February 2026)