Configuration¶

HBIA's configuration system provides a global Settings object with multiple sources and a clear priority chain.

Settings Object¶

from honey_badgeria.conf import Settings, get_settings, configure

settings = Settings(
    CACHE_ENABLED=True,
    PARALLEL_ENABLED=True,
    ASYNC_ENABLED=False,
    MAX_WORKERS=8,
    CACHE_DIR=".hbia_cache",
    MAX_CACHE_ENTRIES=500,
    GRAPH_FILE="flows/",
    HANDLER_MODULES=["vertices"],
    ALLOWED_HANDLER_PREFIXES=("myproject.vertices",),
    API_PREFIX="/api/v1",
    MAX_PAGE_SIZE=100,
)

# Set as global configuration
configure(settings)

# Retrieve global configuration
current = get_settings()

All Settings¶

Setting	Type	Default	Description
`GRAPH_FILE`	`str`	`"graph.yaml"`	Default graph file or directory
`HANDLER_MODULES`	`list[str]`	`[]`	Python modules to scan for handlers
`CACHE_DIR`	`str`	`".hbia_cache"`	Directory for cache files
`MAX_WORKERS`	`int`	`4`	Thread pool size for parallel execution
`CACHE_ENABLED`	`bool`	`False`	Enable SHA-256 hash-based caching
`PARALLEL_ENABLED`	`bool`	`False`	Enable parallel execution of stages
`ASYNC_ENABLED`	`bool`	`False`	Enable native async handler support
`MAX_CACHE_ENTRIES`	`int`	`500`	Maximum cached results
`ALLOWED_HANDLER_PREFIXES`	`tuple[str]`	`()`	Whitelist for handler import paths
`API_PREFIX`	`str`	`"/api/v1"`	FastAPI route prefix
`MAX_PAGE_SIZE`	`int`	`100`	Maximum items per page (FastAPI)

Loading Configuration¶

From Constructor¶

settings = Settings(CACHE_ENABLED=True, MAX_WORKERS=8)

From Environment Variables¶

All settings can be set via environment variables prefixed with HBIA_:

export HBIA_CACHE_ENABLED=true
export HBIA_PARALLEL_ENABLED=true
export HBIA_MAX_WORKERS=8
export HBIA_CACHE_DIR=".my_cache"
export HBIA_API_PREFIX="/api/v2"

settings = Settings.from_env()

From Python Module¶

settings = Settings.from_module("myproject.hbia_settings")

The module should define settings as module-level constants:

# myproject/hbia_settings.py
CACHE_ENABLED = True
PARALLEL_ENABLED = True
MAX_WORKERS = 8

Priority Chain¶

Settings are resolved in this order (highest priority first):

Per-call arguments — run_flow(..., cache_enabled=True)
Explicit Settings object — Settings(CACHE_ENABLED=True)
Environment variables — HBIA_CACHE_ENABLED=true
Built-in defaults — Defined in honey_badgeria.conf.defaults

This means you can set defaults via environment variables (e.g., in a .env file or CI configuration), override globally via configure(), and override per-call when needed.

Defaults¶

All defaults are defined in honey_badgeria.conf.defaults:

DEFAULT_GRAPH_FILE = "graph.yaml"
DEFAULT_CACHE_DIR = ".hbia_cache"
DEFAULT_MAX_WORKERS = 4
DEFAULT_MAX_CACHE_ENTRIES = 500
DEFAULT_API_PREFIX = "/api/v1"
DEFAULT_MAX_PAGE_SIZE = 100
MODULE_MAX_LINES = 300           # Health check threshold
MODULE_MAX_VERTICES = 20         # Health check threshold
SCHEMA_VERSION = "1"