models

models

Data models for the global learning store.

This module contains all dataclasses and enums used by the GlobalLearningStore. These models represent the various records stored in the SQLite database for cross-workspace pattern persistence and learning.

Extracted from global_store.py as part of the modularization effort.

Classes

QuarantineStatus

Bases: str, Enum

Status of a pattern in the quarantine lifecycle.

v19 Evolution: Pattern Quarantine & Provenance - patterns transition through these states as they are validated through successful applications:

• PENDING: New patterns start here, awaiting initial validation
• QUARANTINED: Explicitly marked for review due to concerns
• VALIDATED: Proven effective through repeated successful applications
• RETIRED: No longer active, kept for historical reference

Attributes

PENDING class-attribute instance-attribute

PENDING = 'pending'

New pattern awaiting validation through application.

QUARANTINED class-attribute instance-attribute

QUARANTINED = 'quarantined'

Pattern under review - may have caused issues or needs investigation.

VALIDATED class-attribute instance-attribute

VALIDATED = 'validated'

Pattern has proven effective and is trusted for autonomous application.

RETIRED class-attribute instance-attribute

RETIRED = 'retired'

Pattern no longer in active use, retained for history.

SuccessFactors dataclass

SuccessFactors(validation_types=list(), error_categories=list(), prior_sheet_status=None, time_of_day_bucket=None, retry_iteration=0, escalation_was_pending=False, grounding_confidence=None, occurrence_count=1, success_rate=1.0)

Captures WHY a pattern succeeded - the context conditions and factors.

v22 Evolution: Metacognitive Pattern Reflection - patterns now capture not just WHAT happened but WHY it worked. This enables better pattern selection by understanding causality, not just correlation.

Success factors include: - Context conditions: validation types, error categories, execution phase - Timing factors: time of day, retry iteration, prior sheet outcomes - Prerequisite states: prior sheet completion, escalation status

Attributes

validation_types class-attribute instance-attribute

validation_types = field(default_factory=list)

Validation types that were active: file, regex, artifact, etc.

error_categories class-attribute instance-attribute

error_categories = field(default_factory=list)

Error categories present in the execution: rate_limit, auth, validation, etc.

prior_sheet_status class-attribute instance-attribute

prior_sheet_status = None

Status of the immediately prior sheet: completed, failed, skipped.

time_of_day_bucket class-attribute instance-attribute

time_of_day_bucket = None

Time bucket: morning, afternoon, evening, night.

retry_iteration class-attribute instance-attribute

retry_iteration = 0

Which retry attempt this success occurred on (0 = first attempt).

escalation_was_pending class-attribute instance-attribute

escalation_was_pending = False

Whether an escalation was pending when pattern succeeded.

grounding_confidence class-attribute instance-attribute

grounding_confidence = None

Grounding confidence score if external validation was present.

occurrence_count class-attribute instance-attribute

occurrence_count = 1

How often this factor combination has been observed.

success_rate class-attribute instance-attribute

success_rate = 1.0

Success rate when these factors are present (0.0-1.0).

Functions

__post_init__

__post_init__()

Clamp success_rate and occurrence_count to valid bounds.

Source code in src/marianne/learning/store/models.py

def __post_init__(self) -> None:
    """Clamp success_rate and occurrence_count to valid bounds."""
    self.success_rate = max(0.0, min(1.0, self.success_rate))
    self.occurrence_count = max(1, self.occurrence_count)

to_dict

to_dict()

Serialize to dictionary for JSON storage.

Source code in src/marianne/learning/store/models.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to dictionary for JSON storage."""
    return {
        "validation_types": self.validation_types,
        "error_categories": self.error_categories,
        "prior_sheet_status": self.prior_sheet_status,
        "time_of_day_bucket": self.time_of_day_bucket,
        "retry_iteration": self.retry_iteration,
        "escalation_was_pending": self.escalation_was_pending,
        "grounding_confidence": self.grounding_confidence,
        "occurrence_count": self.occurrence_count,
        "success_rate": self.success_rate,
    }

from_dict classmethod

from_dict(data)

Deserialize from dictionary.

Source code in src/marianne/learning/store/models.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "SuccessFactors":
    """Deserialize from dictionary."""
    return cls(
        validation_types=data.get("validation_types", []),
        error_categories=data.get("error_categories", []),
        prior_sheet_status=data.get("prior_sheet_status"),
        time_of_day_bucket=data.get("time_of_day_bucket"),
        retry_iteration=data.get("retry_iteration", 0),
        escalation_was_pending=data.get("escalation_was_pending", False),
        grounding_confidence=data.get("grounding_confidence"),
        occurrence_count=data.get("occurrence_count", 1),
        success_rate=data.get("success_rate", 1.0),
    )

get_time_bucket staticmethod

get_time_bucket(hour)

Get time bucket for an hour (0-23).

Source code in src/marianne/learning/store/models.py

@staticmethod
def get_time_bucket(hour: int) -> str:
    """Get time bucket for an hour (0-23)."""
    if 5 <= hour < 12:
        return "morning"
    elif 12 <= hour < 17:
        return "afternoon"
    elif 17 <= hour < 21:
        return "evening"
    else:
        return "night"

ExecutionRecord dataclass

ExecutionRecord(id, workspace_hash, job_hash, sheet_num, started_at, completed_at, duration_seconds, status, retry_count, success_without_retry, validation_pass_rate, confidence_score, model, error_codes=list())

A record of a sheet execution stored in the global database.

Functions

__post_init__

__post_init__()

Clamp fields to valid ranges.

Source code in src/marianne/learning/store/models.py

def __post_init__(self) -> None:
    """Clamp fields to valid ranges."""
    self.duration_seconds = max(0.0, self.duration_seconds)
    self.retry_count = max(0, self.retry_count)
    self.validation_pass_rate = max(0.0, min(1.0, self.validation_pass_rate))
    self.confidence_score = max(0.0, min(1.0, self.confidence_score))

PatternRecord dataclass

PatternRecord(id, pattern_type, pattern_name, description, occurrence_count, first_seen, last_seen, last_confirmed, led_to_success_count, led_to_failure_count, effectiveness_score, variance, suggested_action, context_tags, priority_score, quarantine_status=PENDING, provenance_job_hash=None, provenance_sheet_num=None, quarantined_at=None, validated_at=None, quarantine_reason=None, trust_score=0.5, trust_calculation_date=None, success_factors=None, success_factors_updated_at=None, active=True, content_hash=None, instrument_name=None)

A pattern record stored in the global database.

v19 Evolution: Extended with quarantine_status, provenance, and trust_score fields to support the Pattern Quarantine & Provenance and Pattern Trust Scoring evolutions.

Attributes

quarantine_status class-attribute instance-attribute

quarantine_status = PENDING

Current status in the quarantine lifecycle.

provenance_job_hash class-attribute instance-attribute

provenance_job_hash = None

Hash of the job that first created this pattern.

provenance_sheet_num class-attribute instance-attribute

provenance_sheet_num = None

Sheet number where this pattern was first observed.

quarantined_at class-attribute instance-attribute

quarantined_at = None

When the pattern was moved to QUARANTINED status.

validated_at class-attribute instance-attribute

validated_at = None

When the pattern was moved to VALIDATED status.

quarantine_reason class-attribute instance-attribute

quarantine_reason = None

Reason for quarantine (if quarantined).

trust_score class-attribute instance-attribute

trust_score = 0.5

Trust score (0.0-1.0). 0.5 is neutral, >0.7 is high trust.

trust_calculation_date class-attribute instance-attribute

trust_calculation_date = None

When trust_score was last calculated.

success_factors class-attribute instance-attribute

success_factors = None

WHY this pattern succeeds - captured context conditions and factors.

success_factors_updated_at class-attribute instance-attribute

success_factors_updated_at = None

When success_factors were last updated.

active class-attribute instance-attribute

active = True

Whether this pattern is active (False = soft-deleted).

content_hash class-attribute instance-attribute

content_hash = None

SHA-256 hash of pattern content for cross-name deduplication.

instrument_name class-attribute instance-attribute

instrument_name = None

Backend instrument that produced this pattern (e.g., 'claude_cli').

Functions

__post_init__

__post_init__()

Clamp scored fields to valid ranges.

Source code in src/marianne/learning/store/models.py

def __post_init__(self) -> None:
    """Clamp scored fields to valid ranges."""
    self.trust_score = max(0.0, min(1.0, self.trust_score))
    self.effectiveness_score = max(0.0, min(1.0, self.effectiveness_score))
    self.variance = max(0.0, self.variance)
    self.priority_score = max(0.0, self.priority_score)

ErrorRecoveryRecord dataclass

ErrorRecoveryRecord(id, error_code, suggested_wait, actual_wait, recovery_success, recorded_at, model, time_of_day)

A record of error recovery timing for learning adaptive waits.

RateLimitEvent dataclass

RateLimitEvent(id, error_code, model, recorded_at, expires_at, source_job_hash, duration_seconds)

A rate limit event for cross-workspace coordination.

Evolution #8: Tracks rate limit events across workspaces so that parallel jobs can coordinate and avoid hitting the same rate limits.

EscalationDecisionRecord dataclass

EscalationDecisionRecord(id, job_hash, sheet_num, confidence, action, guidance, validation_pass_rate, retry_count, outcome_after_action=None, recorded_at=(lambda: now(tz=UTC))(), model=None)

A record of a human/AI escalation decision.

Evolution v11: Escalation Learning Loop - records escalation decisions to learn from feedback over time and potentially suggest actions for similar future escalations.

Attributes

id instance-attribute

id

Unique identifier for this escalation decision.

job_hash instance-attribute

job_hash

Hash of the job that triggered escalation.

sheet_num instance-attribute

sheet_num

Sheet number that triggered escalation.

confidence instance-attribute

confidence

Aggregate confidence score at time of escalation (0.0-1.0).

action instance-attribute

action

Action taken: retry, skip, abort, modify_prompt.

guidance instance-attribute

guidance

Optional guidance/notes from the escalation handler.

validation_pass_rate instance-attribute

validation_pass_rate

Pass percentage of validations at escalation time.

retry_count instance-attribute

retry_count

Number of retries attempted before escalation.

outcome_after_action class-attribute instance-attribute

outcome_after_action = None

What happened after the action: success, failed, aborted, skipped.

recorded_at class-attribute instance-attribute

recorded_at = field(default_factory=lambda: now(tz=UTC))

When the escalation decision was recorded.

model class-attribute instance-attribute

model = None

Model used for execution (if relevant).

PatternDiscoveryEvent dataclass

PatternDiscoveryEvent(id, pattern_id, pattern_name, pattern_type, source_job_hash, recorded_at, expires_at, effectiveness_score, context_tags=list())

A pattern discovery event for cross-job broadcasting.

v14 Evolution: Real-time Pattern Broadcasting - enables jobs to share newly discovered patterns with other concurrent jobs, so knowledge propagates across the ecosystem without waiting for aggregation.

Attributes

id instance-attribute

id

Unique identifier for this discovery event.

pattern_id instance-attribute

pattern_id

ID of the pattern that was discovered.

pattern_name instance-attribute

pattern_name

Human-readable name of the pattern.

pattern_type instance-attribute

pattern_type

Type of pattern (validation_failure, retry_pattern, etc.).

source_job_hash instance-attribute

source_job_hash

Hash of the job that discovered the pattern.

recorded_at instance-attribute

recorded_at

When the discovery was recorded.

expires_at instance-attribute

expires_at

When this broadcast expires (TTL-based).

effectiveness_score instance-attribute

effectiveness_score

Effectiveness score at time of discovery.

context_tags class-attribute instance-attribute

context_tags = field(default_factory=list)

Context tags for pattern matching.

DriftMetrics dataclass

DriftMetrics(pattern_id, pattern_name, window_size, effectiveness_before, effectiveness_after, grounding_confidence_avg, drift_magnitude, drift_direction, applications_analyzed, threshold_exceeded=False)

Metrics for pattern effectiveness drift detection.

v12 Evolution: Goal Drift Detection - tracks how pattern effectiveness changes over time to detect drifting patterns that may need attention.

Attributes

pattern_id instance-attribute

pattern_id

Pattern ID being analyzed.

pattern_name instance-attribute

pattern_name

Human-readable pattern name.

window_size instance-attribute

window_size

Number of applications in each comparison window.

effectiveness_before instance-attribute

effectiveness_before

Effectiveness score in the older window (applications N-2W to N-W).

effectiveness_after instance-attribute

effectiveness_after

Effectiveness score in the recent window (applications N-W to N).

grounding_confidence_avg instance-attribute

grounding_confidence_avg

Average grounding confidence across all applications in analysis.

drift_magnitude instance-attribute

drift_magnitude

Absolute magnitude of drift: |effectiveness_after - effectiveness_before|.

drift_direction instance-attribute

drift_direction

Direction of drift: 'positive', 'negative', or 'stable'.

applications_analyzed instance-attribute

applications_analyzed

Total number of applications analyzed (should be 2 × window_size).

threshold_exceeded class-attribute instance-attribute

threshold_exceeded = False

Whether drift_magnitude exceeds the alert threshold.

EpistemicDriftMetrics dataclass

EpistemicDriftMetrics(pattern_id, pattern_name, window_size, confidence_before, confidence_after, belief_change, belief_entropy, applications_analyzed, threshold_exceeded=False, drift_direction='stable')

Metrics for epistemic drift detection - tracking belief changes about patterns.

v21 Evolution: Epistemic Drift Detection - tracks how confidence/belief in patterns changes over time, complementing effectiveness drift. While effectiveness drift measures outcome changes, epistemic drift measures belief evolution.

This enables detection of belief degradation before effectiveness actually declines.

Attributes

pattern_id instance-attribute

pattern_id

Pattern ID being analyzed.

pattern_name instance-attribute

pattern_name

Human-readable pattern name.

window_size instance-attribute

window_size

Number of applications in each comparison window.

confidence_before instance-attribute

confidence_before

Average grounding confidence in the older window (applications N-2W to N-W).

confidence_after instance-attribute

confidence_after

Average grounding confidence in the recent window (applications N-W to N).

belief_change instance-attribute

belief_change

Change in belief/confidence: confidence_after - confidence_before.

belief_entropy instance-attribute

belief_entropy

Entropy of confidence values (0 = consistent beliefs, 1 = high variance).

applications_analyzed instance-attribute

applications_analyzed

Total number of applications analyzed (should be 2 × window_size).

threshold_exceeded class-attribute instance-attribute

threshold_exceeded = False

Whether belief_change magnitude exceeds the alert threshold.

drift_direction class-attribute instance-attribute

drift_direction = 'stable'

Direction of belief drift: 'strengthening', 'weakening', or 'stable'.

EvolutionEntryInput dataclass

EvolutionEntryInput(cycle, evolutions_completed, evolutions_deferred, issue_classes, cv_avg, implementation_loc, test_loc, loc_accuracy, research_candidates_resolved=0, research_candidates_created=0, notes='')

Input parameters for recording an evolution trajectory entry.

Bundles the 11 parameters of record_evolution_entry() into a single object for cleaner API usage. The method still accepts individual kwargs for backward compatibility.

Attributes

cycle instance-attribute

cycle

Evolution cycle number (e.g., 16 for v16).

evolutions_completed instance-attribute

evolutions_completed

Number of evolutions completed in this cycle.

evolutions_deferred instance-attribute

evolutions_deferred

Number of evolutions deferred in this cycle.

issue_classes instance-attribute

issue_classes

Issue classes addressed (e.g., ['infrastructure_activation']).

cv_avg instance-attribute

cv_avg

Average Consciousness Volume of selected evolutions.

implementation_loc instance-attribute

implementation_loc

Total implementation LOC for this cycle.

test_loc instance-attribute

test_loc

Total test LOC for this cycle.

loc_accuracy instance-attribute

loc_accuracy

LOC estimation accuracy (actual/estimated as ratio).

research_candidates_resolved class-attribute instance-attribute

research_candidates_resolved = 0

Number of research candidates resolved.

research_candidates_created class-attribute instance-attribute

research_candidates_created = 0

Number of new research candidates created.

notes class-attribute instance-attribute

notes = ''

Optional notes about this evolution cycle.

EvolutionTrajectoryEntry dataclass

EvolutionTrajectoryEntry(id, cycle, recorded_at, evolutions_completed, evolutions_deferred, issue_classes, cv_avg, implementation_loc, test_loc, loc_accuracy, research_candidates_resolved=0, research_candidates_created=0, notes='')

A record of a single evolution cycle in Marianne's self-improvement trajectory.

v16 Evolution: Evolution Trajectory Tracking - enables Marianne to track its own evolution history, identifying recurring issue classes and measuring improvement over time.

Attributes

id instance-attribute

id

Unique identifier for this trajectory entry.

cycle instance-attribute

cycle

Evolution cycle number (e.g., 16 for v16).

recorded_at instance-attribute

recorded_at

When this entry was recorded.

evolutions_completed instance-attribute

evolutions_completed

Number of evolutions completed in this cycle.

evolutions_deferred instance-attribute

evolutions_deferred

Number of evolutions deferred in this cycle.

issue_classes instance-attribute

issue_classes

Issue classes addressed (e.g., 'infrastructure_activation', 'epistemic_drift').

cv_avg instance-attribute

cv_avg

Average Consciousness Volume of selected evolutions.

implementation_loc instance-attribute

implementation_loc

Total implementation LOC for this cycle.

test_loc instance-attribute

test_loc

Total test LOC for this cycle.

loc_accuracy instance-attribute

loc_accuracy

LOC estimation accuracy (actual/estimated as ratio).

research_candidates_resolved class-attribute instance-attribute

research_candidates_resolved = 0

Number of research candidates resolved in this cycle.

research_candidates_created class-attribute instance-attribute

research_candidates_created = 0

Number of new research candidates created in this cycle.

notes class-attribute instance-attribute

notes = ''

Optional notes about this evolution cycle.

PatternEntropyMetrics dataclass

PatternEntropyMetrics(calculated_at, shannon_entropy, max_possible_entropy, diversity_index, unique_pattern_count, effective_pattern_count, total_applications, dominant_pattern_share, threshold_exceeded=False)

Metrics for pattern population Shannon entropy analysis.

Used by the patterns-entropy CLI command to monitor pattern diversity. Shannon entropy measures how evenly patterns are used across the population: high entropy indicates healthy diversity, low entropy signals collapse risk.

Attributes

calculated_at instance-attribute

calculated_at

When this entropy measurement was calculated.

shannon_entropy instance-attribute

shannon_entropy

Shannon entropy in bits: -sum(p * log2(p)) for each pattern probability.

max_possible_entropy instance-attribute

max_possible_entropy

Maximum possible entropy: log2(unique_pattern_count).

diversity_index instance-attribute

diversity_index

Normalized diversity: shannon_entropy / max_possible_entropy (0.0-1.0).

unique_pattern_count instance-attribute

unique_pattern_count

Total number of unique patterns in the population.

effective_pattern_count instance-attribute

effective_pattern_count

Number of patterns with at least one application.

total_applications instance-attribute

total_applications

Total number of pattern applications across all patterns.

dominant_pattern_share instance-attribute

dominant_pattern_share

Fraction of applications held by the most-used pattern (0.0-1.0).

threshold_exceeded class-attribute instance-attribute

threshold_exceeded = False

Whether diversity_index fell below the alert threshold (set by caller).

ExplorationBudgetRecord dataclass

ExplorationBudgetRecord(id, job_hash, recorded_at, budget_value, entropy_at_time, adjustment_type, adjustment_reason=None)

A record of exploration budget state over time.

v23 Evolution: Exploration Budget Maintenance - tracks the dynamic exploration budget to prevent convergence to zero. The budget adjusts based on pattern entropy observations.

Attributes

id instance-attribute

id

Unique identifier for this budget record.

job_hash instance-attribute

job_hash

Hash of the job this budget adjustment belongs to.

recorded_at instance-attribute

recorded_at

When this budget state was recorded.

budget_value instance-attribute

budget_value

Current budget value (0.0-1.0).

entropy_at_time instance-attribute

entropy_at_time

Pattern entropy at time of recording (if measured).

adjustment_type instance-attribute

adjustment_type

Type of adjustment: 'initial', 'decay', 'boost', 'floor_enforced'.

adjustment_reason class-attribute instance-attribute

adjustment_reason = None

Human-readable reason for this adjustment.

EntropyResponseRecord dataclass

EntropyResponseRecord(id, job_hash, recorded_at, entropy_at_trigger, threshold_used, actions_taken, budget_boosted=False, quarantine_revisits=0, patterns_revisited=list())

A record of an automatic entropy response event.

v23 Evolution: Automatic Entropy Response - records when the system automatically responded to low entropy conditions by injecting diversity.

Attributes

id instance-attribute

id

Unique identifier for this response record.

job_hash instance-attribute

job_hash

Hash of the job that triggered this response.

recorded_at instance-attribute

recorded_at

When this response was triggered.

entropy_at_trigger instance-attribute

entropy_at_trigger

The entropy value that triggered this response.

threshold_used instance-attribute

threshold_used

The threshold that was crossed.

actions_taken instance-attribute

actions_taken

List of actions taken: 'budget_boost', 'quarantine_revisit', etc.

budget_boosted class-attribute instance-attribute

budget_boosted = False

Whether the exploration budget was boosted.

quarantine_revisits class-attribute instance-attribute

quarantine_revisits = 0

Number of quarantined patterns revisited.

patterns_revisited class-attribute instance-attribute

patterns_revisited = field(default_factory=list)

IDs of patterns that were marked for revisit.