entity.core package

Entity core module - Agent and batch processing functionality.

exception entity.core.PipelineError(stage, plugin, context, original_error, severity=ErrorSeverity.MEDIUM, category=ErrorCategory.UNKNOWN, recoverable=True)[source]

Bases: Exception

Enhanced pipeline error with rich debugging context.

This error type provides comprehensive debugging information including plugin stack traces, execution context, and recovery strategies.

Parameters:

  • stage (str)

  • plugin (str | None)

  • context (ErrorContext)

  • original_error (Exception)

  • severity (ErrorSeverity)

  • category (ErrorCategory)

  • recoverable (bool)

Return type:

None

__init__(stage, plugin, context, original_error, severity=ErrorSeverity.MEDIUM, category=ErrorCategory.UNKNOWN, recoverable=True)
Parameters:

  • stage (str)

  • plugin (str | None)

  • context (ErrorContext)

  • original_error (Exception)

  • severity (ErrorSeverity)

  • category (ErrorCategory)

  • recoverable (bool)

Return type:

None

__post_init__()[source]

Initialize error message and parent exception.

__str__()[source]

Generate detailed error message with context.

Return type:

str

category: ErrorCategory = 'unknown'
recoverable: bool = True
severity: ErrorSeverity = 'medium'
to_dict()[source]

Convert error to dictionary for logging/serialization.

Return type:

Dict[str, Any]

stage: str
plugin: str | None
context: ErrorContext
original_error: Exception
exception entity.core.PluginError(plugin_name, stage, context, original_error, plugin_config=None)[source]

Bases: PipelineError

Error specific to plugin execution failures.

Parameters:

  • plugin_name (str)

  • stage (str)

  • context (ErrorContext)

  • original_error (Exception)

  • plugin_config (Optional[Dict[str, Any]])

__init__(plugin_name, stage, context, original_error, plugin_config=None)[source]
Parameters:
exception entity.core.ValidationError(field_errors, context, original_error)[source]

Bases: PipelineError

Error for validation failures with detailed field information.

Parameters:

  • field_errors (Dict[str, List[str]])

  • context (ErrorContext)

  • original_error (Exception)

__init__(field_errors, context, original_error)[source]
Parameters:
exception entity.core.ResourceError(resource_type, resource_id, context, original_error)[source]

Bases: PipelineError

Error for resource-related failures (memory, database, etc).

Parameters:

  • resource_type (str)

  • resource_id (Optional[str])

  • context (ErrorContext)

  • original_error (Exception)

__init__(resource_type, resource_id, context, original_error)[source]
Parameters:

  • resource_type (str)

  • resource_id (str | None)

  • context (ErrorContext)

  • original_error (Exception)

exception entity.core.SandboxError(sandbox_type, context, original_error, security_violation=False)[source]

Bases: PipelineError

Error for sandbox execution failures.

Parameters:

  • sandbox_type (str)

  • context (ErrorContext)

  • original_error (Exception)

  • security_violation (bool)

__init__(sandbox_type, context, original_error, security_violation=False)[source]
Parameters:

  • sandbox_type (str)

  • context (ErrorContext)

  • original_error (Exception)

  • security_violation (bool)

class entity.core.RateLimiter(max_requests, time_window=60.0, algorithm=RateLimitAlgorithm.SLIDING_WINDOW, burst_size=None, leak_rate=None)[source]

Bases: object

Unified rate limiter with multiple algorithm support.

Parameters:

  • max_requests (int)

  • time_window (float)

  • algorithm (RateLimitAlgorithm)

  • burst_size (Optional[int])

  • leak_rate (Optional[float])

__init__(max_requests, time_window=60.0, algorithm=RateLimitAlgorithm.SLIDING_WINDOW, burst_size=None, leak_rate=None)[source]

Initialize rate limiter.

Parameters:

  • max_requests (int) – Maximum number of requests allowed

  • time_window (float) – Time window in seconds (default 60)

  • algorithm (RateLimitAlgorithm) – Rate limiting algorithm to use

  • burst_size (int | None) – Maximum burst size for token bucket

  • leak_rate (float | None) – Leak rate for leaky bucket (requests per second)

async allow_request(identifier=None)[source]

Check if request is allowed under rate limit.

Parameters:

identifier (str | None) – Optional identifier for per-key rate limiting

Returns:

True if request is allowed, False otherwise

Return type:

bool

allow_request_sync(identifier=None)[source]

Synchronous version of allow_request.

Parameters:

identifier (str | None)

Return type:

bool

get_metrics()[source]

Get rate limiter metrics.

Return type:

Dict[str, Any]

reset()[source]

Reset the rate limiter state.

Return type:

None

async wait_if_needed(identifier=None)[source]

Wait until request can be made without exceeding rate limit.

Parameters:

identifier (str | None) – Optional identifier for per-key rate limiting

Return type:

None

entity.core.create_api_rate_limiter()[source]

Create rate limiter for API endpoints (100 requests per minute).

Return type:

RateLimiter

entity.core.create_database_rate_limiter()[source]

Create rate limiter for database operations (1000 per minute with bursts).

Return type:

RateLimiter

class entity.core.IdentifierValidator[source]

Bases: object

Validator for various types of identifiers.

ENV_VAR_PATTERN = re.compile('^[A-Z][A-Z0-9_]*$')
PYTHON_IDENTIFIER_PATTERN = re.compile('^[a-zA-Z_][a-zA-Z0-9_]*$')
SAFE_IDENTIFIER_PATTERN = re.compile('^[a-zA-Z_][a-zA-Z0-9_]*$')
TABLE_NAME_PATTERN = re.compile('^[a-zA-Z_][a-zA-Z0-9_]*(\\.[a-zA-Z_][a-zA-Z0-9_]*)?$')
URL_SAFE_PATTERN = re.compile('^[a-z][a-z0-9-]*$')
classmethod validate_column_name(column_name)[source]

Validate a database column name.

Parameters:

column_name (str)

Return type:

bool

classmethod validate_env_var(var_name)[source]

Validate an environment variable name.

Parameters:

var_name (str)

Return type:

bool

classmethod validate_identifier(identifier, pattern=None)[source]

Validate an identifier against a pattern.

Parameters:

  • identifier (str) – The identifier to validate

  • pattern (Pattern | None) – Optional regex pattern to use (defaults to SAFE_IDENTIFIER_PATTERN)

Returns:

True if valid, False otherwise

Return type:

bool

classmethod validate_python_identifier(identifier)[source]

Validate a Python identifier.

Parameters:

identifier (str)

Return type:

bool

classmethod validate_table_name(table_name)[source]

Validate a database table name.

Parameters:

table_name (str)

Return type:

bool

classmethod validate_url_safe(identifier)[source]

Validate a URL-safe identifier.

Parameters:

identifier (str)

Return type:

bool

class entity.core.SQLValidator[source]

Bases: object

Validator for SQL queries and components.

INJECTION_PATTERNS = [';\\s*(DROP|DELETE|TRUNCATE|ALTER|CREATE|INSERT|UPDATE)', '--\\s*', '/\\*.*\\*/', '\\bUNION\\b.*\\bSELECT\\b', '\\bEXEC\\b|\\bEXECUTE\\b', 'xp_cmdshell', '\\bINTO\\s+OUTFILE\\b', '\\bLOAD_FILE\\b', '(0x[0-9a-fA-F]+|CHAR\\([0-9]+\\))', 'WAITFOR\\s+DELAY', 'BENCHMARK\\s*\\(', 'pg_sleep']
SAFE_FUNCTIONS = {'ABS', 'AVG', 'CAST', 'CEIL', 'COALESCE', 'COUNT', 'DATE', 'DAY', 'FLOOR', 'LENGTH', 'LOWER', 'MAX', 'MIN', 'MONTH', 'NOW', 'ROUND', 'SUBSTR', 'SUBSTRING', 'SUM', 'TIME', 'TRIM', 'UPPER', 'YEAR'}
__init__()[source]

Initialize compiled patterns.

sanitize_value(value)[source]

Sanitize a value for SQL insertion (for logging/display only).

Note: Always use parameterized queries for actual SQL execution.

Parameters:

value (Any)

Return type:

str

validate_column_names(column_names)[source]

Validate multiple column names.

Parameters:

column_names (List[str]) – List of column names to validate

Returns:

Tuple of (all_valid, list_of_invalid_names)

Return type:

Tuple[bool, List[str]]

validate_query_safe(query)[source]

Validate a SQL query for injection attempts.

Parameters:

query (str) – The SQL query to validate

Returns:

Tuple of (is_safe, list_of_detected_patterns)

Return type:

Tuple[bool, List[str]]

validate_table_name(table_name)[source]

Validate a table name for SQL safety.

Parameters:

table_name (str)

Return type:

bool

class entity.core.JSONYAMLValidator[source]

Bases: object

Validator for JSON and YAML data.

static validate_json(data)[source]

Validate JSON string.

Parameters:

data (str) – JSON string to validate

Returns:

Tuple of (is_valid, error_message, parsed_data)

Return type:

Tuple[bool, str | None, Dict | None]

static validate_schema(data, schema_model)[source]

Validate data against a Pydantic schema.

Parameters:

  • data (Dict) – Dictionary to validate

  • schema_model (type[BaseModel]) – Pydantic model class to validate against

Returns:

ValidationResult with success status and any errors

Return type:

ValidationResult

static validate_yaml(data)[source]

Validate YAML string.

Parameters:

data (str) – YAML string to validate

Returns:

Tuple of (is_valid, error_message, parsed_data)

Return type:

Tuple[bool, str | None, Dict | None]

class entity.core.TypeValidator[source]

Bases: object

Validator for Python types and type hints.

static validate_dict_schema(data, schema, allow_extra=False)[source]

Validate dictionary against a simple type schema.

Parameters:

  • data (Dict) – Dictionary to validate

  • schema (Dict[str, type]) – Dictionary mapping keys to expected types

  • allow_extra (bool) – Whether to allow extra keys not in schema

Returns:

Tuple of (is_valid, list_of_errors)

Return type:

Tuple[bool, List[str]]

static validate_list_types(data, expected_type)[source]

Validate all items in a list are of expected type.

Parameters:

  • data (List) – List to validate

  • expected_type (type) – Expected type for all items

Returns:

Tuple of (all_valid, list_of_invalid_indices)

Return type:

Tuple[bool, List[int]]

static validate_type(value, expected_type)[source]

Validate that a value matches expected type.

Parameters:

  • value (Any) – Value to check

  • expected_type (type) – Expected type

Returns:

True if type matches, False otherwise

Return type:

bool

Submodules