src.core.resilience module#

Resilience patterns for Marcus enhanced features.

Provides decorators and utilities for graceful degradation, circuit breakers, and retry logic to ensure Marcus continues working even when components fail.

class src.core.resilience.RetryConfig[source]#

Bases: object

Configuration for retry behavior.

max_attempts: int = 3#

base_delay: float = 1.0#

max_delay: float = 60.0#

exponential_base: float = 2.0#

jitter: bool = True#

__init__(max_attempts=3, base_delay=1.0, max_delay=60.0, exponential_base=2.0, jitter=True)#

Parameters:

max_attempts (int)
base_delay (float)
max_delay (float)
exponential_base (float)
jitter (bool)

Return type:

None

class src.core.resilience.CircuitBreakerConfig[source]#

Bases: object

Configuration for circuit breaker behavior.

failure_threshold: int = 5#

recovery_timeout: float = 60.0#

expected_exception#: alias of Exception

__init__(failure_threshold=5, recovery_timeout=60.0, expected_exception=<class 'Exception'>)#

Parameters:

failure_threshold (int)
recovery_timeout (float)
expected_exception (type)

Return type:

None

class src.core.resilience.CircuitBreaker[source]#

Bases: object

Circuit breaker pattern implementation.

__init__(name, config)[source]#

Parameters:

name (str)
config (CircuitBreakerConfig)

last_failure_time: datetime | None#

is_open()[source]#

Check if circuit is open (failing).

Return type:: bool

record_success()[source]#

Record successful call.

Return type:: None

record_failure()[source]#

Record failed call.

Return type:: None

src.core.resilience.with_fallback(fallback_func, log_errors=True)[source]#

Add graceful degradation with fallback function.

Example

@with_fallback(use_memory_storage) async def store_to_database(data):

await db.store(data)

Return type:

Callable[[Callable[..., Any]], Callable[..., Any]]

Parameters:

fallback_func (Callable[[...], Any])
log_errors (bool)

src.core.resilience.with_retry(config=None)[source]#

Add retry logic with exponential backoff.

Example

@with_retry(RetryConfig(max_attempts=5)) async def call_external_api():

return await api.call()

Return type:: Callable[[Callable[..., Any]], Callable[..., Any]]
Parameters:: config (RetryConfig | None)

src.core.resilience.with_circuit_breaker(name, config=None)[source]#

Add circuit breaker pattern.

Example

@with_circuit_breaker(“external_api”) async def call_external_api():

return await api.call()

Return type:

Callable[[Callable[..., Any]], Callable[..., Any]]

Parameters:

name (str)
config (CircuitBreakerConfig | None)

class src.core.resilience.GracefulDegradation[source]#

Bases: object

Context manager for graceful degradation.

Example

async with GracefulDegradation(fallback=use_cache) as gd:: result = await gd.try_primary(fetch_from_database) if not result:

result = await gd.fallback()

__init__(primary=None, fallback=None, log_errors=True)[source]#

Parameters:

primary (Callable[[...], Any] | None)
fallback (Callable[[...], Any] | None)
log_errors (bool)

async __aenter__()[source]#

Enter async context manager.

Return type:: GracefulDegradation

async __aexit__(exc_type, exc_val, exc_tb)[source]#

Exit async context manager.

Return type:

bool

Parameters:

exc_type (Any)
exc_val (Any)
exc_tb (Any)

async try_primary(func=None, *args, **kwargs)[source]#

Try the primary function.

Return type:

Any

Parameters:

func (Callable[[...], Any] | None)
args (Any)
kwargs (Any)

async use_fallback(*args, **kwargs)[source]#

Use the fallback function.

Return type:

Any

Parameters:

args (Any)
kwargs (Any)

src.core.resilience.resilient_persistence(func)#

Return type:: Callable[..., Any]
Parameters:: func (Callable[[...], Any])

src.core.resilience.resilient_external_call(func)#

Return type:: Callable[..., Any]
Parameters:: func (Callable[[...], Any])

src.core.resilience.resilient_ai_call(func)#

Return type:: Callable[..., Any]
Parameters:: func (Callable[[...], Any])