judgment

judgment

Judgment client for Recursive Light integration.

Provides JudgmentQuery/JudgmentResponse protocol for consulting Recursive Light on execution decisions, plus LocalJudgmentClient fallback for offline operation.

Phase 4 of AGI Evolution: Judgment Integration

Attributes

Classes

JudgmentQuery dataclass

JudgmentQuery(job_id, sheet_num, validation_results, execution_history, error_patterns, retry_count, confidence)

Query sent to Recursive Light for execution judgment.

Contains all relevant context about the current sheet execution state needed for RL to provide informed judgment.

Attributes

job_id instance-attribute

job_id

Unique identifier for the job.

sheet_num instance-attribute

sheet_num

Current sheet number being executed.

validation_results instance-attribute

validation_results

Serialized validation results from the sheet.

execution_history instance-attribute

execution_history

History of previous execution attempts for this sheet.

error_patterns instance-attribute

error_patterns

Detected error patterns from previous attempts.

retry_count instance-attribute

retry_count

Number of retry attempts already made.

confidence instance-attribute

confidence

Current aggregate confidence score (0.0-1.0).

JudgmentResponse dataclass

JudgmentResponse(recommended_action, confidence, reasoning, prompt_modifications=None, escalation_urgency=None, human_question=None, patterns_learned=list())

Response from Recursive Light with execution judgment.

Provides recommended action, reasoning, and optional modifications for how to proceed with sheet execution.

Attributes

recommended_action instance-attribute

recommended_action

Recommended action: - proceed: Continue to next sheet (current succeeded) - retry: Retry the current sheet - completion: Run completion prompt for partial success - escalate: Escalate to human for decision - abort: Stop the entire job

confidence instance-attribute

confidence

RL's confidence in this recommendation (0.0-1.0).

reasoning instance-attribute

reasoning

Explanation of why this action is recommended.

prompt_modifications class-attribute instance-attribute

prompt_modifications = None

Optional modifications to apply to prompt on retry.

escalation_urgency class-attribute instance-attribute

escalation_urgency = None

Urgency level if action is 'escalate'.

human_question class-attribute instance-attribute

human_question = None

Specific question to ask human if escalating.

patterns_learned class-attribute instance-attribute

patterns_learned = field(default_factory=list)

New patterns identified by RL from this execution.

JudgmentClient

JudgmentClient(endpoint, timeout=30.0)

HTTP client for Recursive Light judgment API.

Connects to Recursive Light's /api/marianne/judgment endpoint to get TDF-aligned execution decisions with accumulated wisdom.

Falls back to default "retry" action on connection errors for graceful degradation.

Attributes:

Name	Type	Description
endpoint		Base URL for the Recursive Light API.
timeout		Request timeout in seconds.

Initialize the judgment client.

Parameters:

Name	Type	Description	Default
endpoint	str	Base URL for the Recursive Light API server.	required
timeout	float	Request timeout in seconds. Defaults to 30.0.	30.0

Source code in src/marianne/learning/judgment.py

def __init__(
    self,
    endpoint: str,
    timeout: float = 30.0,
) -> None:
    """Initialize the judgment client.

    Args:
        endpoint: Base URL for the Recursive Light API server.
        timeout: Request timeout in seconds. Defaults to 30.0.
    """
    self.endpoint = endpoint.rstrip("/")
    self.timeout = timeout
    self._client: httpx.AsyncClient | None = None

Functions

get_judgment async

get_judgment(query)

Get execution judgment from Recursive Light.

Posts the query to RL's /api/marianne/judgment endpoint and parses the response. On errors, returns a default "retry" action for graceful degradation.

Parameters:

Name	Type	Description	Default
query	JudgmentQuery	Full context about the sheet execution state.	required

Returns:

Type	Description
JudgmentResponse	JudgmentResponse with recommended action. On connection
JudgmentResponse	errors, returns default retry action with low confidence.

Source code in src/marianne/learning/judgment.py

async def get_judgment(self, query: JudgmentQuery) -> JudgmentResponse:
    """Get execution judgment from Recursive Light.

    Posts the query to RL's /api/marianne/judgment endpoint and
    parses the response. On errors, returns a default "retry"
    action for graceful degradation.

    Args:
        query: Full context about the sheet execution state.

    Returns:
        JudgmentResponse with recommended action. On connection
        errors, returns default retry action with low confidence.
    """
    try:
        client = await self._get_client()

        # Build request payload from JudgmentQuery
        payload = {
            "job_id": query.job_id,
            SHEET_NUM_KEY: query.sheet_num,
            "validation_results": query.validation_results,
            "execution_history": query.execution_history,
            "error_patterns": query.error_patterns,
            "retry_count": query.retry_count,
            "confidence": query.confidence,
        }

        # POST to RL judgment endpoint
        response = await client.post("/api/marianne/judgment", json=payload)

        if response.status_code != 200:
            # API error - fall back to retry
            return self._default_retry_response(
                f"RL API error: {response.status_code}"
            )

        # Parse response JSON
        data = response.json()
        return self._parse_judgment_response(data)

    except httpx.ConnectError as e:
        return self._default_retry_response(f"Connection error: {e}")

    except httpx.TimeoutException as e:
        return self._default_retry_response(f"Timeout: {e}")

    except httpx.HTTPStatusError as e:
        if e.response.status_code < 500:
            # 4xx client errors are permanent — retrying won't help.
            _logger.warning(
                "judgment_client_error: HTTP %s — not retrying",
                e.response.status_code,
            )
            return JudgmentResponse(
                recommended_action="retry",
                confidence=0.1,
                reasoning=f"RL client error (HTTP {e.response.status_code}), unavailable",
            )
        return self._default_retry_response(f"HTTP server error: {e}")

    except (ValueError, KeyError, TypeError) as e:
        return self._default_retry_response(f"Response parsing error: {e}")

    except (httpx.HTTPError, OSError, OverflowError) as e:
        _logger.warning("judgment_unexpected_error: %s", e, exc_info=True)
        return self._default_retry_response(f"Unexpected error: {e}")
    except ExceptionGroup as eg:
        _logger.warning("judgment_exception_group: %s", eg, exc_info=True)
        return self._default_retry_response(f"Connection error group: {eg}")

close async

close()

Close the HTTP client connection.

Should be called when done using the client to clean up resources.

Source code in src/marianne/learning/judgment.py

async def close(self) -> None:
    """Close the HTTP client connection.

    Should be called when done using the client to clean up resources.
    """
    if self._client is not None and not self._client.is_closed:
        await self._client.aclose()
        self._client = None

__aenter__ async

__aenter__()

Async context manager entry.

Source code in src/marianne/learning/judgment.py

async def __aenter__(self) -> "JudgmentClient":
    """Async context manager entry."""
    return self

__aexit__ async

__aexit__(exc_type, exc_val, exc_tb)

Async context manager exit - closes client.

Source code in src/marianne/learning/judgment.py

async def __aexit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: types.TracebackType | None,
) -> None:
    """Async context manager exit - closes client."""
    await self.close()

LocalJudgmentClient

LocalJudgmentClient(proceed_threshold=0.7, retry_threshold=0.4, max_retries=3)

Local fallback judgment client using simple heuristics.

Provides judgment without network calls for offline operation or when Recursive Light is unavailable. Uses confidence thresholds and pass rate heuristics to determine actions.

This is a simpler, always-available alternative that makes reasonable decisions based on local metrics alone.

Attributes:

Name	Type	Description
proceed_threshold		Confidence above which to proceed (default 0.7).
retry_threshold		Confidence above which to retry (default 0.4).
max_retries		Maximum retries before escalating (default 3).

Initialize the local judgment client.

Parameters:

Name	Type	Description	Default
proceed_threshold	float	Confidence >= this proceeds to next sheet.	0.7
retry_threshold	float	Confidence >= this (but < proceed) retries. Below this, escalates or aborts.	0.4
max_retries	int	Maximum retry count before escalating.	3

Source code in src/marianne/learning/judgment.py

def __init__(
    self,
    proceed_threshold: float = 0.7,
    retry_threshold: float = 0.4,
    max_retries: int = 3,
) -> None:
    """Initialize the local judgment client.

    Args:
        proceed_threshold: Confidence >= this proceeds to next sheet.
        retry_threshold: Confidence >= this (but < proceed) retries.
            Below this, escalates or aborts.
        max_retries: Maximum retry count before escalating.
    """
    self.proceed_threshold = proceed_threshold
    self.retry_threshold = retry_threshold
    self.max_retries = max_retries

Functions

get_judgment async

get_judgment(query)

Get execution judgment using local heuristics.

Decision logic: 1. High confidence (>= proceed_threshold) -> proceed 2. Medium confidence (>= retry_threshold) -> retry (unless max retries) 3. Low confidence (< retry_threshold) -> escalate 4. Max retries exceeded -> completion or escalate based on pass rate

Parameters:

Name	Type	Description	Default
query	JudgmentQuery	Full context about the sheet execution state.	required

Returns:

Type	Description
JudgmentResponse	JudgmentResponse with recommended action based on heuristics.

Source code in src/marianne/learning/judgment.py

async def get_judgment(self, query: JudgmentQuery) -> JudgmentResponse:
    """Get execution judgment using local heuristics.

    Decision logic:
    1. High confidence (>= proceed_threshold) -> proceed
    2. Medium confidence (>= retry_threshold) -> retry (unless max retries)
    3. Low confidence (< retry_threshold) -> escalate
    4. Max retries exceeded -> completion or escalate based on pass rate

    Args:
        query: Full context about the sheet execution state.

    Returns:
        JudgmentResponse with recommended action based on heuristics.
    """
    confidence = query.confidence
    retry_count = query.retry_count

    # Calculate validation pass rate
    pass_rate = self._calculate_pass_rate(query.validation_results)

    # High confidence: proceed to next sheet
    if confidence >= self.proceed_threshold:
        return JudgmentResponse(
            recommended_action="proceed",
            confidence=0.8,
            reasoning=f"Confidence {confidence:.1%} >= {self.proceed_threshold:.1%} threshold",
            patterns_learned=[],
        )

    # Max retries exceeded
    if retry_count >= self.max_retries:
        # If pass rate is decent, try completion
        if pass_rate >= 0.5:
            return JudgmentResponse(
                recommended_action="completion",
                confidence=0.6,
                reasoning=(
                    f"Max retries ({self.max_retries}) exceeded but pass rate "
                    f"{pass_rate:.1%} suggests partial success - trying completion"
                ),
                patterns_learned=["max_retries_with_partial_success"],
            )
        # Otherwise escalate
        return JudgmentResponse(
            recommended_action="escalate",
            confidence=0.7,
            reasoning=(
                f"Max retries ({self.max_retries}) exceeded with low pass rate "
                f"{pass_rate:.1%} - human decision needed"
            ),
            escalation_urgency="medium",
            human_question=(
                f"Sheet {query.sheet_num} failed {retry_count} times with "
                f"{pass_rate:.0%} validation pass rate. Continue, skip, or abort?"
            ),
            patterns_learned=["max_retries_exceeded"],
        )

    # Medium confidence: retry
    if confidence >= self.retry_threshold:
        return JudgmentResponse(
            recommended_action="retry",
            confidence=0.6,
            reasoning=(
                f"Confidence {confidence:.1%} in retry range "
                f"[{self.retry_threshold:.1%}, {self.proceed_threshold:.1%})"
            ),
            patterns_learned=[],
        )

    # Low confidence: escalate
    urgency: Literal["low", "medium", "high"] = "low"
    if confidence < 0.2:
        urgency = "high"
    elif confidence < 0.3:
        urgency = "medium"

    return JudgmentResponse(
        recommended_action="escalate",
        confidence=0.5,
        reasoning=(
            f"Confidence {confidence:.1%} < {self.retry_threshold:.1%} "
            f"threshold - escalating for human decision"
        ),
        escalation_urgency=urgency,
        human_question=(
            f"Sheet {query.sheet_num} has low confidence ({confidence:.0%}) "
            f"after {retry_count} attempts. How should we proceed?"
        ),
        patterns_learned=["low_confidence_escalation"],
    )