Skip to content

cold_start

cold_start

Cold start detection and bootstrap for the distillation subsystem.

Day one: no traces, no benchmark. The system must not crash and must give the user a clear message about what's needed. This module provides readiness checks and the bootstrap logic.

See spec §13.

Classes

ReadinessResult dataclass 

ReadinessResult(ready: bool, message: str, trace_count: int = 0, high_feedback_count: int = 0)

Result of a readiness check.

Functions

check_readiness 

check_readiness(trace_store: Any, min_traces: int = 20) -> ReadinessResult

Check if there are enough traces to run a learning session.

PARAMETER DESCRIPTION
trace_store

TraceStore instance.

TYPE: Any

min_traces

Minimum total trace count required.

TYPE: int DEFAULT: 20

RETURNS DESCRIPTION
ReadinessResult

ready is True if there are enough traces.
Source code in src/openjarvis/learning/distillation/gate/cold_start.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def check_readiness(
    trace_store: Any,
    min_traces: int = 20,
) -> ReadinessResult:
    """Check if there are enough traces to run a learning session.

    Parameters
    ----------
    trace_store :
        TraceStore instance.
    min_traces :
        Minimum total trace count required.

    Returns
    -------
    ReadinessResult
        ``ready`` is True if there are enough traces.
    """
    count = trace_store.count()
    if count < min_traces:
        return ReadinessResult(
            ready=False,
            message=(
                f"Not enough traces yet to learn from. "
                f"Have {count}, need at least {min_traces}. "
                f"Use OpenJarvis for a while and try again."
            ),
            trace_count=count,
        )
    return ReadinessResult(
        ready=True,
        message=f"Ready: {count} traces available.",
        trace_count=count,
    )

check_benchmark_ready 

check_benchmark_ready(trace_store: Any, min_feedback: float = 0.7, min_samples: int = 10) -> ReadinessResult

Check if there are enough high-feedback traces for a benchmark.

The bootstrap benchmark needs at least min_samples traces with feedback >= min_feedback.

PARAMETER DESCRIPTION
trace_store

TraceStore instance.

TYPE: Any

min_feedback

Minimum feedback score for benchmark-quality traces.

TYPE: float DEFAULT: 0.7

min_samples

Minimum number of high-feedback traces needed.

TYPE: int DEFAULT: 10

Source code in src/openjarvis/learning/distillation/gate/cold_start.py 
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def check_benchmark_ready(
    trace_store: Any,
    min_feedback: float = 0.7,
    min_samples: int = 10,
) -> ReadinessResult:
    """Check if there are enough high-feedback traces for a benchmark.

    The bootstrap benchmark needs at least ``min_samples`` traces with
    feedback >= ``min_feedback``.

    Parameters
    ----------
    trace_store :
        TraceStore instance.
    min_feedback :
        Minimum feedback score for benchmark-quality traces.
    min_samples :
        Minimum number of high-feedback traces needed.
    """
    # Query traces with high feedback
    traces = trace_store.list_traces(limit=min_samples * 2)
    high_feedback = [
        t
        for t in traces
        if getattr(t, "feedback", None) is not None and t.feedback >= min_feedback
    ]
    count = len(high_feedback)

    if count < min_samples:
        return ReadinessResult(
            ready=False,
            message=(
                f"Personal benchmark needs at least {min_samples} "
                f"high-feedback traces (feedback >= {min_feedback}). "
                f"Have {count} so far. Will be populated automatically."
            ),
            trace_count=trace_store.count(),
            high_feedback_count=count,
        )
    return ReadinessResult(
        ready=True,
        message=f"Benchmark ready: {count} high-feedback traces available.",
        trace_count=trace_store.count(),
        high_feedback_count=count,
    )