semantica/docs/reference/utils.md

title, description, icon

title	description	icon
Utils Module	Shared utilities for logging, validation, error handling, progress tracking, and common operations.	wrench

semantica.utils provides shared infrastructure used throughout Semantica. Most users won't call it directly, but its APIs are available when you need fine-grained control over logging, validation, progress tracking, or error handling.

What You Get

• Logging — structured logging with @log_performance decorator and quality metrics
• Validation — validate_entity, validate_config with a typed ValidationError
• Progress tracking — track_progress wraps any iterable with console, Jupyter, or file output
• Helper functions — clean_text, hash_data, safe_filename
• Exception hierarchy — SemanticaError → ValidationError, ProcessingError

Logging

from semantica.utils import setup_logging, get_logger, log_performance

setup_logging(level="INFO")   # "DEBUG" | "INFO" | "WARNING" | "ERROR"
logger = get_logger(__name__)

@log_performance
def process_data(data):
    logger.info(f"Processing {len(data)} items")
    # Decorator automatically logs function name, duration, and any exception

Configure via environment variables:

export SEMANTICA_LOG_LEVEL=DEBUG
export SEMANTICA_LOG_FORMAT=json     # "json" | "text"
export SEMANTICA_PROGRESS_BAR=true

Validation

from semantica.utils import validate_entity, validate_config, ValidationError

# Validate an entity dict
try:
    validate_entity({"id": "1", "type": "PERSON", "text": "Alice"})
except ValidationError as e:
    print(f"Invalid entity: {e.message}")
    print(f"  Field:   {e.field}")
    print(f"  Value:   {e.value}")

# Validate a configuration dict
try:
    validate_config(config)
except ValidationError as e:
    print(f"Invalid config: {e}")

Function	Description
validate_entity(data)	Check entity dict has required fields and correct types
validate_config(cfg)	Check configuration dict against schema

Progress Tracking

from semantica.utils import track_progress

# Wraps any iterable — auto-detects console vs Jupyter
for item in track_progress(items, desc="Processing documents"):
    process(item)

Supports:

• Console — tqdm progress bar with ETA
• Jupyter — notebook-compatible widget
• File — write progress to a log file

Helper Functions

from semantica.utils import clean_text, hash_data, safe_filename

# Normalize whitespace and strip control characters
clean  = clean_text("  Hello   World  ")   # → "Hello World"

# Deterministic SHA-256 hash of any serializable object
uid    = hash_data({"key": "value"})        # → hex digest string

# Sanitize a string for use as a filename
fname  = safe_filename("My File?.txt")      # → "My_File_.txt"

Exception Hierarchy

from semantica.utils import SemanticaError, ValidationError, ProcessingError

try:
    run_pipeline(data)
except ValidationError as e:
    # Input data did not pass schema validation
    logger.error(f"Validation failed: {e}")
except ProcessingError as e:
    # Failure during extraction or graph construction
    logger.error(f"Processing failed at step {e.step}: {e}")
except SemanticaError as e:
    # Catch-all for all Semantica framework errors
    logger.error(f"Framework error: {e}")

Exception	When Raised
SemanticaError	Base class — all framework errors inherit from this
ValidationError	Input data failed schema or type validation
ProcessingError	Failure during extraction, graph build, or pipeline step

Framework orchestration that uses Utils internally. Uses ProgressTracker for per-step tracking.