Utilities

Utilities for Hillstar Orchestrator.

exception utils.HillstarException

Bases: Exception

Base exception for Hillstar Orchestrator.

exception utils.ConfigurationError

Bases: HillstarException

Raised when workflow configuration is invalid.

exception utils.BudgetExceededError

Bases: HillstarException

Raised when workflow cost exceeds budget limits.

exception utils.ModelSelectionError

Bases: HillstarException

Raised when model selection fails.

utils.redact(text)

Convenience function to redact credentials from a string.

Parameters:

text (str | None) – String potentially containing credentials (returns empty string if None)

Returns:

String with credentials redacted

Return type:

str

utils.contains_credentials(text)

Convenience function to check if string contains credentials.

Parameters:

text (str | None) – String to check (returns False if None)

Returns:

True if credentials detected

Return type:

bool

class utils.CredentialRedactor

Bases: object

Detect and redact sensitive credentials from strings.

PATTERNS = {'anthropic_key': 'sk-ant-[a-zA-Z0-9\\-_]{6,}', 'api_key_generic': '(?:api[_-]?key|api[_-]?token)\\s*[=:]\\s*[\'\\"]?([a-zA-Z0-9\\-_\\.]+)[\'\\"]?', 'authorization': '(?:Authorization|X-API-Key)\\s*[=:]\\s*[\'\\"]?([a-zA-Z0-9\\-_\\.]+)[\'\\"]?', 'aws_access_id': '\\b(AKIA|A3T|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{12,}\\b', 'bearer_token': 'Bearer\\s+[a-zA-Z0-9\\-\\._~\\+\\/=]{6,}', 'credentials_json': '"(?:api_key|apiKey|access_token|accessToken|password|secret)"\\s*:\\s*"([^"]+)"', 'env_var_value': '(?:ANTHROPIC_API_KEY|OPENAI_API_KEY|MISTRAL_API_KEY|GOOGLE_API_KEY)\\s*=\\s*([a-zA-Z0-9\\-_\\.]+)', 'firebase_domain': '\\b([a-z0-9-]){1,30}(\\.firebaseapp\\.com)\\b', 'fireworks_key': 'fw_[a-zA-Z0-9]{10,}', 'github_oauth_token': '\\bgho_[A-Za-z0-9_]{36}\\b', 'github_pat_classic': '\\bghp_[A-Za-z0-9_]{36}\\b', 'github_pat_fine_grained': '\\bgithub_pat_[A-Za-z0-9_]{82}\\b', 'github_server_to_server': '\\bghs_[A-Za-z0-9_]{36}\\b', 'github_user_to_server': '\\bghu_[A-Za-z0-9_]{36}\\b', 'google_key': 'AIza[0-9A-Za-z\\-_]{10,}', 'google_oauth_id': '\\b[0-9]+-[0-9A-Za-z_]{32}\\.apps\\.googleusercontent\\.com\\b', 'ipv4_address': '\\b((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}\\b', 'ipv6_address': '\\b((([0-9A-Fa-f]{1,4}:){1,6}:)|(([0-9A-Fa-f]{1,4}:){7}))([0-9A-Fa-f]{1,4})\\b', 'json_web_token': '\\b(ey[a-zA-z0-9_\\-=]{10,}\\.){2}[a-zA-z0-9_\\-=]{10,}\\b', 'mac_address': '\\b((([a-zA-z0-9]{2}[-:]){5}([a-zA-z0-9]{2}))|(([a-zA-z0-9]{2}:){5}([a-zA-z0-9]{2})))\\b', 'openai_key': 'sk-[a-zA-Z0-9\\-_]{10,}', 'phone_number': '\\b(\\+\\d{1,2}\\s)?\\(?\\d{3}\\)?[\\s.-]\\d{3}[\\s.-]\\d{4}\\b', 'slack_app_token': '\\bxapp-[0-9]+-[A-Za-z0-9_]+-[0-9]+-[a-f0-9]+\\b', 'stripe_key': '\\b(?:r|s)k_(test|live)_[0-9a-zA-Z]{24}\\b', 'url_password': '(?:https?://)[^:]+:([a-zA-Z0-9\\-_\\.]+)@'}

static redact(text, include_patterns=None)

Redact all detected credentials from text.

Parameters:

• text (str | None) – String potentially containing credentials (returns empty string if None)

• include_patterns (list | None) – List of pattern names to apply (default: all)

Returns:

TYPE]

Return type:

String with credentials redacted as [REDACTED

Examples

>>> redactor = CredentialRedactor()
>>> redactor.redact("My key is sk-ant-abc123def456")
'My key is [REDACTED:anthropic_key]'

>>> redactor.redact('api_key = "secret-value"')
'api_key = [REDACTED:api_key_generic]'

static contains_credentials(text)

Check if text contains any detected credentials.

Parameters:

text (str | None) – String to check (returns False if None)

Returns:

True if any credentials detected, False otherwise

Return type:

bool

static get_redaction_types(text)

Identify which credential types are present in text.

Parameters:

text (str) – String to analyze

Returns:

List of pattern names detected

Return type:

list

Example

>>> redactor.get_redaction_types("key=sk-ant-123")
['anthropic_key', 'api_key_generic']

utils.credential_redactor

Script

credential_redactor.py

Path

python/hillstar/utils/credential_redactor.py

Purpose

Detect and redact sensitive credentials (API keys, tokens, infrastructure identifiers, PII) from strings, logs, and error messages. Prevents accidental data leakage in output.

Implements comprehensive credential detection covering: API keys, OAuth tokens, AWS credentials, infrastructure identifiers, and PII based on industry standard patterns.

Inputs

String containing potential credentials

Outputs

String with credentials redacted as [REDACTED:TYPE]

Assumptions

• Credentials follow common patterns (API key formats, token types, etc.)

• All potentially sensitive data should be redacted

• Redaction preserves string structure for error clarity

Failure Modes

None - always returns a valid string (worst case: no redactions made)

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created

2026-02-17

Last Edited

2026-02-17

class utils.credential_redactor.CredentialRedactor

Bases: object

Detect and redact sensitive credentials from strings.

PATTERNS = {'anthropic_key': 'sk-ant-[a-zA-Z0-9\\-_]{6,}', 'api_key_generic': '(?:api[_-]?key|api[_-]?token)\\s*[=:]\\s*[\'\\"]?([a-zA-Z0-9\\-_\\.]+)[\'\\"]?', 'authorization': '(?:Authorization|X-API-Key)\\s*[=:]\\s*[\'\\"]?([a-zA-Z0-9\\-_\\.]+)[\'\\"]?', 'aws_access_id': '\\b(AKIA|A3T|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{12,}\\b', 'bearer_token': 'Bearer\\s+[a-zA-Z0-9\\-\\._~\\+\\/=]{6,}', 'credentials_json': '"(?:api_key|apiKey|access_token|accessToken|password|secret)"\\s*:\\s*"([^"]+)"', 'env_var_value': '(?:ANTHROPIC_API_KEY|OPENAI_API_KEY|MISTRAL_API_KEY|GOOGLE_API_KEY)\\s*=\\s*([a-zA-Z0-9\\-_\\.]+)', 'firebase_domain': '\\b([a-z0-9-]){1,30}(\\.firebaseapp\\.com)\\b', 'fireworks_key': 'fw_[a-zA-Z0-9]{10,}', 'github_oauth_token': '\\bgho_[A-Za-z0-9_]{36}\\b', 'github_pat_classic': '\\bghp_[A-Za-z0-9_]{36}\\b', 'github_pat_fine_grained': '\\bgithub_pat_[A-Za-z0-9_]{82}\\b', 'github_server_to_server': '\\bghs_[A-Za-z0-9_]{36}\\b', 'github_user_to_server': '\\bghu_[A-Za-z0-9_]{36}\\b', 'google_key': 'AIza[0-9A-Za-z\\-_]{10,}', 'google_oauth_id': '\\b[0-9]+-[0-9A-Za-z_]{32}\\.apps\\.googleusercontent\\.com\\b', 'ipv4_address': '\\b((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}\\b', 'ipv6_address': '\\b((([0-9A-Fa-f]{1,4}:){1,6}:)|(([0-9A-Fa-f]{1,4}:){7}))([0-9A-Fa-f]{1,4})\\b', 'json_web_token': '\\b(ey[a-zA-z0-9_\\-=]{10,}\\.){2}[a-zA-z0-9_\\-=]{10,}\\b', 'mac_address': '\\b((([a-zA-z0-9]{2}[-:]){5}([a-zA-z0-9]{2}))|(([a-zA-z0-9]{2}:){5}([a-zA-z0-9]{2})))\\b', 'openai_key': 'sk-[a-zA-Z0-9\\-_]{10,}', 'phone_number': '\\b(\\+\\d{1,2}\\s)?\\(?\\d{3}\\)?[\\s.-]\\d{3}[\\s.-]\\d{4}\\b', 'slack_app_token': '\\bxapp-[0-9]+-[A-Za-z0-9_]+-[0-9]+-[a-f0-9]+\\b', 'stripe_key': '\\b(?:r|s)k_(test|live)_[0-9a-zA-Z]{24}\\b', 'url_password': '(?:https?://)[^:]+:([a-zA-Z0-9\\-_\\.]+)@'}

static redact(text, include_patterns=None)

Redact all detected credentials from text.

Parameters:

• text (str | None) – String potentially containing credentials (returns empty string if None)

• include_patterns (list | None) – List of pattern names to apply (default: all)

Returns:

TYPE]

Return type:

String with credentials redacted as [REDACTED

Examples

>>> redactor = CredentialRedactor()
>>> redactor.redact("My key is sk-ant-abc123def456")
'My key is [REDACTED:anthropic_key]'

>>> redactor.redact('api_key = "secret-value"')
'api_key = [REDACTED:api_key_generic]'

static contains_credentials(text)

Check if text contains any detected credentials.

Parameters:

text (str | None) – String to check (returns False if None)

Returns:

True if any credentials detected, False otherwise

Return type:

bool

static get_redaction_types(text)

Identify which credential types are present in text.

Parameters:

text (str) – String to analyze

Returns:

List of pattern names detected

Return type:

list

Example

>>> redactor.get_redaction_types("key=sk-ant-123")
['anthropic_key', 'api_key_generic']

utils.credential_redactor.redact(text)

Convenience function to redact credentials from a string.

Parameters:

text (str | None) – String potentially containing credentials (returns empty string if None)

Returns:

String with credentials redacted

Return type:

str

utils.credential_redactor.contains_credentials(text)

Convenience function to check if string contains credentials.

Parameters:

text (str | None) – String to check (returns False if None)

Returns:

True if credentials detected

Return type:

bool

utils.exceptions

Script

exceptions.py

Path

python/hillstar/exceptions.py

Purpose

Custom exceptions for Hillstar Orchestrator.

Provides domain-specific exceptions for error handling: - BudgetExceededError: Workflow exceeded cost limits - ModelSelectionError: Failed to select valid model - ConfigurationError: Invalid workflow configuration

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created

2026-02-07

Last Edited

2026-02-07

exception utils.exceptions.HillstarException

Bases: Exception

Base exception for Hillstar Orchestrator.

exception utils.exceptions.BudgetExceededError

Bases: HillstarException

Raised when workflow cost exceeds budget limits.

exception utils.exceptions.ModelSelectionError

Bases: HillstarException

Raised when model selection fails.

exception utils.exceptions.ConfigurationError

Bases: HillstarException

Raised when workflow configuration is invalid.

exception utils.exceptions.ExecutionError

Bases: HillstarException

Raised when node execution fails.

utils.json_output_viewer

Script

json_output_viewer.py

Path

python/hillstar/utils/json_output_viewer.py

Purpose

Generic utility to parse, validate, and view JSON output files in full.

Provides CLI and programmatic access to any JSON outputs file with complete untruncated text. Works with any structure containing node outputs, test results, workflow outputs, or similar data requiring full text inspection.

Features

• Load and validate JSON structure

• View individual node/key outputs in full

• Summary statistics (character counts, line counts)

• Line-numbered output for detailed review

• Raw JSON export

• Validation reporting

• File auto-detection or explicit path specification

Usage

View all outputs from file:

python json_output_viewer.py /path/to/outputs.json

View specific node:

python json_output_viewer.py /path/to/outputs.json –key node_name

View with line numbers:

python json_output_viewer.py /path/to/outputs.json –key node_name –lines

View summary only:

python json_output_viewer.py /path/to/outputs.json –summary

View raw JSON:

python json_output_viewer.py /path/to/outputs.json –raw

Validation report:

python json_output_viewer.py /path/to/outputs.json –validate

Programmatic Usage

from json_output_viewer import JSONOutputViewer

viewer = JSONOutputViewer(‘/path/to/outputs.json’) if viewer.load_and_validate():

viewer.print_all_outputs() summary = viewer.get_summary()

# Access data directly all_data = viewer.data

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created

2026-02-22

Last Edited

2026-02-22

class utils.json_output_viewer.JSONOutputViewer

Bases: object

Generic parser and display tool for JSON output files.

__init__(output_file)

Initialize viewer with output file path.

Parameters:

output_file (Path)

load_and_validate()

Load and validate the JSON output file.

Return type:

bool

get_summary()

Get summary statistics about the outputs.

Return type:

Dict[str, Any]

print_summary()

Print summary of all outputs.

Return type:

None

print_all_outputs(with_lines=False)

Print all outputs in full.

Parameters:

with_lines (bool)

Return type:

None

print_key(key, with_lines=False)

Print a specific key’s output in full.

Parameters:

• key (str)

• with_lines (bool)

Return type:

None

print_raw_json()

Print raw JSON with formatting.

Return type:

None

print_validation_report()

Print validation report.

Return type:

None

export_markdown(output_path=None)

Export all outputs to a markdown file.

Parameters:

output_path (Path | None)

Return type:

Path

utils.json_output_viewer.main()

CLI entry point.

utils.report

Workflow Report Generator

Path

python/hillstar/utils/report.py

Purpose

Generate pre-execution and post-execution markdown reports for workflows.

Reports include: - Workflow metadata - DAG visualization (Mermaid) - Node specifications and costs - Model selection strategy - Governance/audit status Inputs —— workflow_path: Path to workflow JSON file trace_path: Optional path to trace file for post-execution metrics

Outputs

Markdown string with formatted report

Assumptions

• Workflow follows python/hillstar/schemas/workflow-schema.json

• Trace file is JSONL format with execution metrics

• Model costs available from ModelPresets

Failure Modes

• Missing workflow file ValueError with clear message

• Missing trace file Skip post-execution metrics gracefully

• Invalid workflow structure Raise with helpful error

Author: Julen Gamboa <julen.gamboa.ds@gmail.com>

Created

2026-02-18

Last Edited

2026-02-18

class utils.report.ReportGenerator

Bases: object

Generate professional workflow execution reports.

__init__(workflow_path)

Initialize with workflow file path.

Parameters:

workflow_path (str)

generate_pre_execution_report()

Generate pre-execution report with estimated costs and metadata.

Returns: Markdown string ready for display or file output

Return type:

str

generate_post_execution_report(trace_path)

Generate post-execution report with actual execution metrics.

Args: trace_path: Path to trace JSONL file from execution

Returns: Markdown string with execution results

Parameters:

trace_path (str)

Return type:

str

utils.report.generate_pre_execution_report(workflow_path)

Generate pre-execution report for a workflow.

Args: workflow_path: Path to workflow JSON file

Returns: Markdown string with report

Parameters:

workflow_path (str)

Return type:

str

utils.report.generate_post_execution_report(workflow_path, trace_path)

Generate post-execution report for a workflow.

Args: workflow_path: Path to workflow JSON file trace_path: Path to trace JSONL file

Returns: Markdown string with report including execution metrics

Parameters:

• workflow_path (str)

• trace_path (str)

Return type:

str