Config

config

---

Assembly:                Chonky
Filename:                config.py
Author:                  Terry D. Eppler
Created:                 05-31-2022

Last Modified By:        Terry D. Eppler
Last Modified On:        05-01-2025

---

       config.py
       Copyright ©  2022  Terry Eppler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You can contact me at: terryeppler@gmail.com or eppler.terry@epa.gov

Provides centralized runtime configuration for the Chonky Streamlit application. Purpose: Defines environment readers, application paths, logging database settings, provider credentials, model option lists, tab names, and session-state defaults used across the loading, processing, analysis, tokenization, embedding, and vector-database workflows. The module keeps import-time configuration safe by returning caller-provided defaults when optional environment variables are missing or malformed.

---

throw_if

throw_if(name: str, value: object) -> None

Validate a required argument or configuration value.

Purpose

Provides a shared guard for required runtime values used by configuration helpers and source modules. The function raises a deterministic exception when a caller passes a falsy value for a required argument or setting name.

Parameters:

Name	Type	Description	Default
name	str	Name of the argument or configuration value being validated.	required
value	object	Runtime value to validate.	required

Raises:

Type	Description
ValueError	Raised when value is falsy.

Source code in config.py

def throw_if( name: str, value: object ) -> None:
	"""Validate a required argument or configuration value.

	Purpose:
		Provides a shared guard for required runtime values used by configuration helpers
		and source modules. The function raises a deterministic exception when a caller
		passes a falsy value for a required argument or setting name.

	Args:
		name: Name of the argument or configuration value being validated.
		value: Runtime value to validate.

	Raises:
		ValueError: Raised when ``value`` is falsy.
	"""
	if not value:
		raise ValueError( f'Argument "{name}" cannot be empty!' )

get_bool

get_bool(name: str, default: bool = False) -> bool

Read a Boolean environment variable.

Purpose

Converts optional environment-variable text into a Boolean value used by Chonky configuration. Missing variables return the caller-provided default, while common truthy strings are normalized to True and all other defined values are treated as False.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name.	required
default	bool	Boolean value returned when the variable is missing or parsing fails.	False

Returns:

Name	Type	Description
bool	bool	Parsed Boolean value or the supplied default.

Source code in config.py

def get_bool( name: str, default: bool = False ) -> bool:
	"""Read a Boolean environment variable.

	Purpose:
		Converts optional environment-variable text into a Boolean value used by Chonky
		configuration. Missing variables return the caller-provided default, while common
		truthy strings are normalized to ``True`` and all other defined values are treated
		as ``False``.

	Args:
		name: Environment variable name.
		default: Boolean value returned when the variable is missing or parsing fails.

	Returns:
		bool: Parsed Boolean value or the supplied default.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value is None else value.strip( ).lower( ) in (
				'1',
				'true',
				'yes',
				'y',
				'on'
		)
	except Exception:
		return default

get_int

get_int(name: str, default: int) -> int

Read an integer environment variable.

Purpose

Parses optional integer configuration while preserving safe import behavior for local development, Streamlit deployment, and documentation generation. Missing, empty, or malformed values return the supplied default rather than interrupting module import.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name.	required
default	int	Integer value returned when the variable is missing or invalid.	required

Returns:

Name	Type	Description
int	int	Parsed integer value or the supplied default.

Source code in config.py

def get_int( name: str, default: int ) -> int:
	"""Read an integer environment variable.

	Purpose:
		Parses optional integer configuration while preserving safe import behavior for
		local development, Streamlit deployment, and documentation generation. Missing,
		empty, or malformed values return the supplied default rather than interrupting
		module import.

	Args:
		name: Environment variable name.
		default: Integer value returned when the variable is missing or invalid.

	Returns:
		int: Parsed integer value or the supplied default.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value in (None, '') else int( str( value ).strip( ) )
	except Exception:
		return default

get_float

get_float(name: str, default: float) -> float

Read a floating-point environment variable.

Purpose

Parses optional numeric configuration for Chonky without making startup depend on perfect environment state. Missing, empty, or malformed values return the supplied default so downstream modules can import consistently.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name.	required
default	float	Floating-point value returned when the variable is missing or invalid.	required

Returns:

Name	Type	Description
float	float	Parsed floating-point value or the supplied default.

Source code in config.py

def get_float( name: str, default: float ) -> float:
	"""Read a floating-point environment variable.

	Purpose:
		Parses optional numeric configuration for Chonky without making startup depend on
		perfect environment state. Missing, empty, or malformed values return the supplied
		default so downstream modules can import consistently.

	Args:
		name: Environment variable name.
		default: Floating-point value returned when the variable is missing or invalid.

	Returns:
		float: Parsed floating-point value or the supplied default.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value in (None, '') else float( str( value ).strip( ) )
	except Exception:
		return default

get_path

get_path(name: str, default: Path) -> Path

Read a path environment variable.

Purpose

Resolves optional filesystem configuration from the environment for Chonky paths such as logging locations and data directories. Missing or invalid variables fall back to the resolved default path to keep imports and MkDocs builds stable.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name.	required
default	Path	Default path returned when the variable is missing or invalid.	required

Returns:

Name	Type	Description
Path	Path	Resolved environment path or resolved default path.

Source code in config.py

def get_path( name: str, default: Path ) -> Path:
	"""Read a path environment variable.

	Purpose:
		Resolves optional filesystem configuration from the environment for Chonky paths
		such as logging locations and data directories. Missing or invalid variables fall
		back to the resolved default path to keep imports and MkDocs builds stable.

	Args:
		name: Environment variable name.
		default: Default path returned when the variable is missing or invalid.

	Returns:
		Path: Resolved environment path or resolved default path.
	"""
	try:
		throw_if( 'name', name )
		throw_if( 'default', default )
		value = os.getenv( name )
		return Path( value ).resolve( ) if value else default.resolve( )
	except Exception:
		return default.resolve( )

get_text

get_text(name: str, default: str) -> str

Read a text environment variable.

Purpose

Centralizes optional text configuration for paths, provider settings, and runtime values. Missing or empty environment variables return the supplied default so the application and generated documentation can load without complete credentials.

Parameters:

Name	Type	Description	Default
name	str	Environment variable name.	required
default	str	Default text returned when the variable is missing or empty.	required

Returns:

Name	Type	Description
str	str	Environment value or supplied default text.

Source code in config.py

def get_text( name: str, default: str ) -> str:
	"""Read a text environment variable.

	Purpose:
		Centralizes optional text configuration for paths, provider settings, and runtime
		values. Missing or empty environment variables return the supplied default so the
		application and generated documentation can load without complete credentials.

	Args:
		name: Environment variable name.
		default: Default text returned when the variable is missing or empty.

	Returns:
		str: Environment value or supplied default text.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value in (None, '') else str( value )
	except Exception:
		return default