agentdag

agentdag is a coordinator that runs a small graph of AI-agent nodes with bounded spend, mechanical gates and journaled state. This is the pristine project scaffold; it currently carries the bitranox CLI template's own CLI, configuration and logging demo commands, which later tasks replace with the DAG kernel.

• CLI entry point styled with rich-click (rich output + click ergonomics).
• Layered configuration system with lib_layered_config (defaults → app → host → user → .env → env).
• Rich structured logging with lib_log_rich (console, journald, eventlog, Graylog/GELF).
• Exit-code and messaging helpers powered by lib_cli_exit_tools.
• Metadata helpers ready for packaging, testing, and release automation.

Python 3.12+ Baseline

• The project targets Python 3.12 and newer.
• Runtime dependencies require current stable releases (rich-click>=1.9.6 and lib_cli_exit_tools>=2.2.4). Dev dependencies (pytest, ruff, pyright, bandit, etc.) specify minimum version constraints to ensure compatibility.
• CI workflows exercise GitHub's rolling runner images (ubuntu-latest, macos-latest, windows-latest) and cover CPython 3.12 through 3.14 alongside the latest available 3.x release provided by Actions.

Install - recommended via uv

uv is an ultrafast Python package manager written in Rust (10-20x faster than pip/poetry).

Install uv (if not already installed)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Copy the actual binaries
cp /root/.local/bin/uv /usr/local/bin/uv
cp /root/.local/bin/uvx /usr/local/bin/uvx

# Ensure world-executable
chmod 755 /usr/local/bin/uv /usr/local/bin/uvx

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

One-shot run (no install needed)

uvx agentdag@latest --help

Persistent install as CLI tool

# Install latest python
install_latest_python_gcc.sh
# pin uv to the latest python
uv python pin /opt/python-latest/bin/python3
# One-time install, persists from the git repo
uv tool install --python /opt/python-latest/bin/python3 --from "git+https://github.com/bitranox/agentdag.git" agentdag
# or One-time install, persists from PyPi
uv tool install --python /opt/python-latest/bin/python3 agentdag
# Update (requires network)
uv tool upgrade agentdag
# Run
agentdag --help

Persistent install as CLI tool

# install the CLI tool (isolated environment, added to PATH)
uv tool install agentdag

# upgrade to latest
uv tool upgrade agentdag

Install as project dependency

uv venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
uv pip install agentdag

For alternative install paths (pip, pipx, source builds, etc.), see INSTALL.md. All supported methods register the agentdag command on your PATH.

Configuration

See CONFIG.md for detailed documentation on the layered configuration system, including precedence rules, profile support, and customization best practices.

Quick Start

# Install
uv tool install agentdag

# Verify
agentdag --version

# deploy config files
agentdag deploy-config --target app

# Try it out
agentdag hello
agentdag info
agentdag config

Usage

The CLI leverages rich-click so help output, validation errors, and prompts render with Rich styling while keeping the familiar click ergonomics.

Available Commands

# Display package information
agentdag info

# Greeting and error-handling demos
agentdag hello
agentdag fail
agentdag --traceback fail

# Configuration management
agentdag config                         # Show current configuration
agentdag config --format json           # Show as JSON
agentdag config --section lib_log_rich  # Show specific section
agentdag config --profile production    # Use a named profile

# Deploy configuration templates to target directories
# Without profile:
agentdag config-deploy --target app    # → /etc/xdg/{slug}/config.toml
agentdag config-deploy --target host   # → /etc/xdg/{slug}/hosts/{hostname}.toml
agentdag config-deploy --target user   # → ~/.config/{slug}/config.toml

# With profile:
agentdag config-deploy --target app --profile production   # → /etc/xdg/{slug}/profile/production/config.toml
agentdag config-deploy --target host --profile production  # → /etc/xdg/{slug}/profile/production/hosts/{hostname}.toml
agentdag config-deploy --target user --profile production  # → ~/.config/{slug}/profile/production/config.toml

# With custom permissions (POSIX only):
agentdag config-deploy --target user --file-mode 640       # Files with rw-r----- (640)
agentdag config-deploy --target user --dir-mode 750        # Directories with rwxr-x--- (750)
agentdag config-deploy --target app --no-permissions       # Skip permission setting (use umask)

# Profile names: alphanumeric, hyphens, underscores; max 64 chars; must start with letter/digit
# See CONFIG.md for full validation rules

# Deploy configuration examples
agentdag config-generate-examples --destination ./examples

# Load configuration from an explicit .env file (skips upward directory search)
agentdag --env-file /path/to/.env config
agentdag --env-file ./environments/production.env send-notification ...

# Override configuration at runtime (repeatable --set)
agentdag --set lib_log_rich.console_level=DEBUG config
agentdag --set email.smtp_hosts='["smtp.example.com:587"]' config --format json

# Logging demo
agentdag logdemo
agentdag --set lib_log_rich.console_level=DEBUG logdemo

# Send email
agentdag send-email \
    --to recipient@example.com \
    --subject "Test Email" \
    --body "Hello from bitranox!"

# Send email with HTML body and attachments
agentdag send-email \
    --to recipient@example.com \
    --subject "Monthly Report" \
    --body "See attached." \
    --body-html "<h1>Report</h1><p>Details in the PDF.</p>" \
    --attachment report.pdf

# Send plain-text notification
agentdag send-notification \
    --to ops@example.com \
    --subject "Deploy OK" \
    --message "Application deployed successfully"

# All commands work with any entry point
python -m agentdag info
uvx agentdag info

Email Sending

The application includes email sending capabilities via btx-lib-mail, supporting both simple notifications and rich HTML emails with attachments.

Email Configuration

Configure email settings via environment variables, .env file, or configuration files:

Environment Variables:

Environment variables use the format: <PREFIX>___<SECTION>__<KEY>=value

• Triple underscore (___) separates PREFIX from SECTION
• Double underscore (__) separates SECTION from KEY

export AGENTDAG___EMAIL__SMTP_HOSTS="smtp.gmail.com:587,smtp.backup.com:587"
export AGENTDAG___EMAIL__FROM_ADDRESS="alerts@myapp.com"
export AGENTDAG___EMAIL__SMTP_USERNAME="your-email@gmail.com"
export AGENTDAG___EMAIL__SMTP_PASSWORD="your-app-password"
export AGENTDAG___EMAIL__USE_STARTTLS="true"
export AGENTDAG___EMAIL__TIMEOUT="60.0"

Configuration File:

[email]
smtp_hosts = ["smtp.gmail.com:587", "smtp.backup.com:587"]  # Fallback to backup if primary fails
from_address = "alerts@myapp.com"
smtp_username = "myuser@gmail.com"
smtp_password = "secret_password"  # Consider using environment variables for sensitive data
use_starttls = true
timeout = 60.0

.env File:

# Email configuration for local testing
AGENTDAG___EMAIL__SMTP_HOSTS=smtp.gmail.com:587
AGENTDAG___EMAIL__FROM_ADDRESS=noreply@example.com

Gmail Configuration Example

For Gmail, create an App Password instead of using your account password:

AGENTDAG___EMAIL__SMTP_HOSTS=smtp.gmail.com:587
AGENTDAG___EMAIL__FROM_ADDRESS=your-email@gmail.com
AGENTDAG___EMAIL__SMTP_USERNAME=your-email@gmail.com
AGENTDAG___EMAIL__SMTP_PASSWORD=your-16-char-app-password

Send Simple Email

# Send basic email to one recipient
agentdag send-email \
    --to recipient@example.com \
    --subject "Test Email" \
    --body "Hello from bitranox!"

# Send to multiple recipients
agentdag send-email \
    --to user1@example.com \
    --to user2@example.com \
    --subject "Team Update" \
    --body "Please review the latest changes"

Send HTML Email with Attachments

agentdag send-email \
    --to recipient@example.com \
    --subject "Monthly Report" \
    --body "Please find the monthly report attached." \
    --body-html "<h1>Monthly Report</h1><p>See attached PDF for details.</p>" \
    --attachment report.pdf \
    --attachment data.csv

Send Notifications

For simple plain-text notifications, use the convenience command:

# Single recipient
agentdag send-notification \
    --to ops@example.com \
    --subject "Deployment Success" \
    --message "Application deployed successfully to production at $(date)"

# Multiple recipients
agentdag send-notification \
    --to admin1@example.com \
    --to admin2@example.com \
    --subject "System Alert" \
    --message "Database backup completed successfully"

Programmatic Email Usage

from agentdag.adapters.email.sender import EmailConfig
from agentdag.composition import send_email, send_notification

# Configure email
config = EmailConfig(
    smtp_hosts=["smtp.gmail.com:587"],
    from_address="alerts@myapp.com",
    smtp_username="myuser@gmail.com",
    smtp_password="app-password",
    timeout=60.0,
)

# Send simple email
send_email(
    config=config,
    recipients="recipient@example.com",
    subject="Test Email",
    body="Hello from Python!",
)

# Send email with HTML and attachments
from pathlib import Path

send_email(
    config=config,
    recipients=["user1@example.com", "user2@example.com"],
    subject="Report",
    body="See attached report",
    body_html="<h1>Report</h1><p>Details in attachment</p>",
    attachments=[Path("report.pdf")],
)

# Send notification
send_notification(
    config=config,
    recipients="ops@example.com",
    subject="Deployment Complete",
    message="Production deployment finished successfully",
)

Email Troubleshooting

Connection Failures:

• Verify SMTP hostname and port are correct
• Check firewall allows outbound connections on SMTP port
• Test connectivity: telnet smtp.gmail.com 587

Authentication Errors:

• For Gmail: Use App Password, not account password
• Ensure username/password are correct
• Check for 2FA requirements

Emails Not Arriving:

• Check recipient's spam folder
• Verify from_address is valid and not blacklisted
• Review SMTP server logs for delivery status

Further Documentation

• Install Guide
• Development Handbook
• Contributor Guide
• Changelog
• Module Reference
• License