agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/rules.py

@@ -0,0 +1,396 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Mapping
+from copy import deepcopy
+from dataclasses import dataclass, fields
+from enum import Enum
+from typing import Any
+
+from agentloop.batching import model_batch_groups
+from agentloop.costs import is_cost_evaluable
+from agentloop.estimates import ESTIMATORS, estimate_snapshot
+from agentloop.graph import ExecutionGraph
+from agentloop.parallelism import PARALLELISM_REWRITE
+from agentloop.ranking import requirements
+from agentloop.tokens import UNAVAILABLE
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _safe_error_type(error: Exception) -> str:
+    """Use public categories rather than exposing arbitrary implementation class names."""
+    for kind, label in (
+        (TypeError, "TypeError"),
+        (ValueError, "ValueError"),
+        (LookupError, "LookupError"),
+        (ArithmeticError, "ArithmeticError"),
+    ):
+        if isinstance(error, kind):
+            return label
+    return "RuleError"
+
+
+class RecommendationType(str, Enum):
+    PARALLELIZE_TOOLS = "parallelize_tools"
+    CACHE_CONTEXT = "cache_context"
+    BATCH_MODEL_CALLS = "batch_model_calls"
+    ROUTE_TO_SMALLER_MODEL = "route_to_smaller_model"
+    REMOVE_RETRY_LOOP = "remove_retry_loop"
+    ADD_SCHEMA_VALIDATION = "add_schema_validation"
+    SPLIT_LARGE_STEP = "split_large_step"
+    RUNAWAY_LOOP = "runaway_loop"
+    TOOL_OSCILLATION = "tool_oscillation"
+    SEMANTIC_REDUNDANCY = "semantic_redundancy"
+    LOW_CONTRIBUTION = "low_contribution"
+    SEMANTIC_NO_PROGRESS = "semantic_no_progress"
+    RETRY_USEFULNESS = "retry_usefulness"
+    CONTEXT_RELEVANCE = "context_relevance"
+
+
+@dataclass
+class FindingCandidate:
+    type: RecommendationType
+    title: str
+    why: str
+    rewrite_hint: str
+    confidence: str
+    estimated_latency_savings_ms: float | None = 0.0
+    estimated_cost_savings_usd: float | None = 0.0
+    affected_nodes: list[str] | None = None
+    evidence_level: str | None = None
+    assumptions: list[str] | None = None
+    observations: dict[str, Any] | None = None
+    estimate_formula: str | None = None
+
+    rule_id: str | None = None
+    rule_version: str | None = None
+    estimate: dict[str, Any] | None = None
+    ranking_requirements: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "type": self.type.value,
+            "title": self.title,
+            "why": self.why,
+            "rewrite_hint": self.rewrite_hint,
+            "confidence": self.confidence,
+            "estimated_latency_savings_ms": None
+            if self.estimated_latency_savings_ms is None
+            else round(self.estimated_latency_savings_ms, 3),
+            "estimated_cost_savings_usd": (
+                None
+                if self.estimated_cost_savings_usd is None
+                else round(self.estimated_cost_savings_usd, 6)
+            ),
+            "affected_nodes": self.affected_nodes or [],
+        }
+        if self.evidence_level is not None:
+            result.update(
+                evidence_level=self.evidence_level,
+                assumptions=self.assumptions or [],
+                observations=self.observations or {},
+                estimate_formula=self.estimate_formula,
+            )
+        if self.rule_id is not None:
+            result.update(rule_id=self.rule_id, rule_version=self.rule_version)
+        if self.estimate is not None:
+            result["estimate"] = deepcopy(self.estimate)
+        if self.ranking_requirements:
+            result["ranking_requirements"] = list(self.ranking_requirements)
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FindingCandidate:
+        values = {item.name: deepcopy(data[item.name]) for item in fields(cls) if item.name in data}
+        values["type"] = RecommendationType(values["type"])
+        return cls(**values)
+
+
+@dataclass(frozen=True)
+class AnalysisContext:
+    report: dict[str, Any]
+    graph: ExecutionGraph
+
+
+@dataclass(frozen=True)
+class FindingRule:
+    rule_id: str
+    version: str
+    detect: Callable[[AnalysisContext], list[FindingCandidate]]
+    ranking_requirements: tuple[str, ...] = ()
+
+    def __post_init__(self):
+        object.__setattr__(self, "ranking_requirements", requirements(self.ranking_requirements))
+
+
+def run_rules(
+    context: AnalysisContext, rules: tuple[FindingRule, ...] | None = None
+) -> tuple[list[FindingCandidate], list[dict[str, str]]]:
+    """Run canonical local rules in declared order, retaining failure diagnostics."""
+    candidates: list[FindingCandidate] = []
+    errors = []
+    for rule in BUILTIN_RULES if rules is None else rules:
+        try:
+            detected = list(rule.detect(context))
+            if any(not isinstance(item, FindingCandidate) for item in detected):
+                raise TypeError("rule must return FindingCandidate objects")
+            for item in detected:
+                item.rule_id = rule.rule_id
+                item.rule_version = rule.version
+                item.ranking_requirements = rule.ranking_requirements
+                if rule in BUILTIN_RULES and item.estimate is None:
+                    item.estimate = estimate_snapshot(item, context.report, context.graph.nodes)
+            candidates.extend(detected)
+        except Exception as exc:
+            _LOGGER.debug("Finding rule %s failed", rule.rule_id, exc_info=True)
+            errors.append(
+                {
+                    "rule_id": rule.rule_id,
+                    "rule_version": rule.version,
+                    "error_type": _safe_error_type(exc),
+                    "message": "Rule evaluation failed; see local debug logs.",
+                }
+            )
+    if not is_cost_evaluable(context.report.get("cost_status", "complete")):
+        for candidate in candidates:
+            candidate.estimated_cost_savings_usd = None
+    from agentloop.interoperability.evidence import qualify_candidates
+
+    qualify_candidates(context.report, candidates)
+    return candidates, errors
+
+
+def _parallelization_cards(graph: ExecutionGraph) -> list[FindingCandidate]:
+    cards = []
+    for group in graph.parallelizable_groups():
+        cards.append(
+            FindingCandidate(
+                type=RecommendationType.PARALLELIZE_TOOLS,
+                title=f"Parallelize repeated `{group['name']}` tool calls",
+                why=f"{group['count']} repeated calls. {group['description']}",
+                rewrite_hint=PARALLELISM_REWRITE,
+                confidence=group["confidence"],
+                estimated_latency_savings_ms=group["estimated_savings_ms"],
+                affected_nodes=group["node_ids"],
+                evidence_level=group["evidence_level"],
+                assumptions=group["assumptions"],
+                observations=group["observations"],
+                estimate_formula=group["estimate_formula"],
+            )
+        )
+    return cards
+
+
+def _context_cache_cards(report: dict[str, Any], graph: ExecutionGraph) -> list[FindingCandidate]:
+    ratio = report.get("repeated_context_ratio", 0.0)
+    if ratio is None:
+        return []
+    if ratio < 0.10:
+        return []
+    model_nodes = [node.node_id for node in graph.nodes if node.operation_kind == "model"]
+    if not model_nodes:
+        return []
+    current_cost = report.get("estimated_cost_usd", 0.0)
+    cost_evaluable = is_cost_evaluable(report.get("cost_status", "complete"))
+    return [
+        FindingCandidate(
+            type=RecommendationType.CACHE_CONTEXT,
+            title="Cache repeated prompt/context prefix",
+            why=f"Repeated context ratio is {ratio:.1%}, which suggests stable instructions or source text are being resent.",
+            rewrite_hint="Move stable instructions into cached prefixes, summaries, or framework-level memory instead of resending full text.",
+            confidence="high" if ratio >= 0.20 else "medium",
+            estimated_cost_savings_usd=(
+                current_cost
+                * min(ESTIMATORS["cache_context"].parameter("max_cost_fraction"), ratio)
+                if cost_evaluable
+                else None
+            ),
+            affected_nodes=model_nodes,
+        )
+    ]
+
+
+def _retry_cards(graph: ExecutionGraph) -> list[FindingCandidate]:
+    retry_nodes = [node for node in graph.nodes if node.operation_kind == "retry"]
+    if not retry_nodes:
+        return []
+    retry_time = sum(node.duration_ms for node in retry_nodes)
+    return [
+        FindingCandidate(
+            type=RecommendationType.ADD_SCHEMA_VALIDATION,
+            title="Reduce retry loop with structured outputs",
+            why=f"Observed {len(retry_nodes)} retry span(s), costing {retry_time / 1000:.2f}s.",
+            rewrite_hint="Add schema validation, JSON mode, constrained decoding, or a cheap repair prompt before rerunning a full step.",
+            confidence="high",
+            estimated_latency_savings_ms=retry_time
+            * ESTIMATORS["add_schema_validation"].parameter("latency_fraction"),
+            affected_nodes=[node.node_id for node in retry_nodes],
+        )
+    ]
+
+
+def _batch_model_cards(graph: ExecutionGraph) -> list[FindingCandidate]:
+    cards = []
+    for name, nodes in model_batch_groups(graph):
+        duration = sum(node.duration_ms for node in nodes)
+        cards.append(
+            FindingCandidate(
+                type=RecommendationType.BATCH_MODEL_CALLS,
+                title=f"Batch repeated `{name}` model calls",
+                why=f"{len(nodes)} `{name}` calls have the same role and may be batchable.",
+                rewrite_hint="Batch documents/items into one prompt or use map-reduce only when outputs truly need independent reasoning.",
+                confidence="medium",
+                estimated_latency_savings_ms=duration
+                * ESTIMATORS["batch_model_calls"].parameter("latency_fraction"),
+                affected_nodes=[node.node_id for node in nodes],
+            )
+        )
+    return cards
+
+
+def _routing_cards(graph: ExecutionGraph) -> list[FindingCandidate]:
+    cards = []
+    for node in graph.nodes:
+        if node.operation_kind != "model" or not node.model:
+            continue
+        if node.token_provenance == UNAVAILABLE or (
+            isinstance(node.metadata, Mapping) and node.metadata.get("usage_available") is False
+        ):
+            continue
+        if "mini" in node.model.lower():
+            continue
+        if node.output_tokens <= 400 and node.input_tokens <= 2500:
+            cards.append(
+                FindingCandidate(
+                    type=RecommendationType.ROUTE_TO_SMALLER_MODEL,
+                    title=f"Route `{node.name}` to a cheaper model",
+                    why=f"`{node.name}` is a relatively small model step using {node.total_tokens} tokens on {node.model}.",
+                    rewrite_hint="Try a smaller model for planning, summarization, extraction, or verification steps and keep the larger model for final synthesis.",
+                    confidence="low",
+                    estimated_latency_savings_ms=node.duration_ms
+                    * ESTIMATORS["route_to_smaller_model"].parameter("latency_fraction"),
+                    affected_nodes=[node.node_id],
+                )
+            )
+    return cards[:3]
+
+
+def _split_large_step_cards(graph: ExecutionGraph) -> list[FindingCandidate]:
+    cards = []
+    for node in graph.nodes:
+        if node.operation_kind == "model" and node.total_tokens >= 4000:
+            cards.append(
+                FindingCandidate(
+                    type=RecommendationType.SPLIT_LARGE_STEP,
+                    title=f"Split or compress `{node.name}`",
+                    why=f"`{node.name}` used {node.total_tokens} tokens, making it a large and fragile step.",
+                    rewrite_hint="Split into retrieve-filter-summarize or compress the context before the final reasoning call.",
+                    confidence="medium",
+                    estimated_latency_savings_ms=node.duration_ms
+                    * ESTIMATORS["split_large_step"].parameter("latency_fraction"),
+                    affected_nodes=[node.node_id],
+                )
+            )
+    return cards
+
+
+def _runaway_loop_cards(graph: ExecutionGraph) -> list[FindingCandidate]:
+    if graph.execution is not None:
+        return []  # Repeated pipeline stages do not establish an agent loop.
+    cards = []
+    groups: dict[tuple[str, str], list[Any]] = {}
+    for node in graph.nodes:
+        groups.setdefault((node.operation_kind, node.name), []).append(node)
+
+    for (event_type, name), nodes in groups.items():
+        if len(nodes) < 8:
+            continue
+        duration = sum(node.duration_ms for node in nodes)
+        cards.append(
+            FindingCandidate(
+                type=RecommendationType.RUNAWAY_LOOP,
+                title=f"Add a loop guardrail around `{name}`",
+                why=f"`{name}` ran {len(nodes)} times in one trace, which suggests an unbounded or weakly bounded agent loop.",
+                rewrite_hint="Add max-iteration, max-cost, and unchanged-state guards before the workflow can keep looping.",
+                confidence="high" if len(nodes) >= 12 else "medium",
+                estimated_latency_savings_ms=duration
+                * ESTIMATORS["runaway_loop"].parameter("latency_fraction"),
+                affected_nodes=[node.node_id for node in nodes],
+            )
+        )
+    return cards[:3]
+
+
+def _tool_oscillation_cards(graph: ExecutionGraph) -> list[FindingCandidate]:
+    if graph.execution is not None:
+        return []  # Generic workflow ordering is not evidence of agent oscillation.
+    tool_nodes = [node for node in graph.nodes if node.operation_kind == "tool"]
+    if len(tool_nodes) < 4:
+        return []
+
+    cards = []
+    index = 0
+    while index <= len(tool_nodes) - 4:
+        first = tool_nodes[index].name
+        second = tool_nodes[index + 1].name
+        if first == second:
+            index += 1
+            continue
+
+        window = tool_nodes[index : index + 4]
+        if [node.name for node in window] != [first, second, first, second]:
+            index += 1
+            continue
+
+        end = index + 4
+        while end < len(tool_nodes) and tool_nodes[end].name == (
+            first if (end - index) % 2 == 0 else second
+        ):
+            end += 1
+        oscillating = tool_nodes[index:end]
+        duration = sum(node.duration_ms for node in oscillating)
+        cards.append(
+            FindingCandidate(
+                type=RecommendationType.TOOL_OSCILLATION,
+                title=f"Stop `{first}`/`{second}` tool oscillation",
+                why=f"Observed {len(oscillating)} alternating `{first}` and `{second}` tool calls.",
+                rewrite_hint="Add a state-change check or decision memo so the agent does not repeat equivalent tool transitions.",
+                confidence="medium",
+                estimated_latency_savings_ms=duration
+                * ESTIMATORS["tool_oscillation"].parameter("latency_fraction"),
+                affected_nodes=[node.node_id for node in oscillating],
+            )
+        )
+        index = end
+
+    return sorted(cards, key=lambda card: card.estimated_latency_savings_ms, reverse=True)[:3]
+
+
+def _semantic_cards(context, family):
+    if not context.report.get("semantic_waste"):
+        return []
+    from agentloop.semantic_rules import semantic_candidates
+
+    return semantic_candidates(context, family)
+
+
+BUILTIN_RULES = (
+    FindingRule("parallelize_tools", "1.1", lambda ctx: _parallelization_cards(ctx.graph)),
+    FindingRule("cache_context", "1.1", lambda ctx: _context_cache_cards(ctx.report, ctx.graph)),
+    FindingRule("add_schema_validation", "1.1", lambda ctx: _retry_cards(ctx.graph)),
+    FindingRule("batch_model_calls", "1.2", lambda ctx: _batch_model_cards(ctx.graph)),
+    FindingRule("route_to_smaller_model", "1.2", lambda ctx: _routing_cards(ctx.graph)),
+    FindingRule("split_large_step", "1.1", lambda ctx: _split_large_step_cards(ctx.graph)),
+    FindingRule("runaway_loop", "1.1", lambda ctx: _runaway_loop_cards(ctx.graph)),
+    FindingRule("tool_oscillation", "1.1", lambda ctx: _tool_oscillation_cards(ctx.graph)),
+    FindingRule(
+        "semantic_redundancy", "1.0", lambda ctx: _semantic_cards(ctx, "semantic_redundancy")
+    ),
+    FindingRule("low_contribution", "1.0", lambda ctx: _semantic_cards(ctx, "low_contribution")),
+    FindingRule(
+        "semantic_no_progress", "1.0", lambda ctx: _semantic_cards(ctx, "semantic_no_progress")
+    ),
+    FindingRule("retry_usefulness", "1.0", lambda ctx: _semantic_cards(ctx, "retry_usefulness")),
+    FindingRule("context_relevance", "1.0", lambda ctx: _semantic_cards(ctx, "context_relevance")),
+)

agentloop/runtime.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from agentloop.retention import RetentionSession
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+
+class _ClearSentinel:
+    """Sentinel passed to :func:`init` to explicitly clear an optional value.
+
+    ``init(api_key=None)`` means "keep the current value" (so environment and
+    prior configuration survive a reconfigure). Passing ``CLEAR`` instead sets
+    the value back to ``None``.
+    """
+
+    def __repr__(self) -> str:
+        return "CLEAR"
+
+
+CLEAR = _ClearSentinel()
+
+
+class FinalizationError(RuntimeError):
+    """Raised by :func:`finalize_trace` when a destination fails and
+    ``fail_silently`` is ``False``.
+
+    ``result`` holds the partial finalization result for destinations that
+    completed before the failure, so already-completed work is not lost.
+    ``errors`` lists the destination-tagged failures.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        result: dict[str, Any],
+        errors: list[dict[str, str]],
+    ) -> None:
+        super().__init__(message)
+        self.result = result
+        self.errors = errors
+
+
+@dataclass
+class AgentLoopRuntimeConfig:
+    api_url: str = "http://127.0.0.1:8000"
+    api_key: str | None = None
+    project_id: str = "default"
+    auto_upload: bool = False
+    auto_store: bool = False
+    fail_silently: bool = True
+    export_dir: Path | None = None
+    retention: RetentionSession | None = None
+
+
+_runtime = AgentLoopRuntimeConfig()
+_last_error: str | None = None
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.lower() in _TRUE_VALUES
+
+
+def init(
+    *,
+    api_url: str | None = None,
+    api_key: str | _ClearSentinel | None = None,
+    project_id: str | None = None,
+    auto_upload: bool | None = None,
+    auto_store: bool | None = None,
+    fail_silently: bool | None = None,
+    export_dir: str | Path | _ClearSentinel | None = None,
+    retention: RetentionSession | _ClearSentinel | None = None,
+) -> AgentLoopRuntimeConfig:
+    """Configure AgentLoop once at process startup.
+
+    Examples:
+
+    ```python
+    import agentloop
+
+    agentloop.init(api_key="al_xxx", project_id="demo", auto_upload=True)
+    ```
+
+    Environment variables are also supported:
+    - `AGENTLOOP_API_URL`
+    - `AGENTLOOP_API_KEY`
+    - `AGENTLOOP_PROJECT_ID`
+    - `AGENTLOOP_AUTO_UPLOAD`
+    - `AGENTLOOP_AUTO_STORE`
+    - `AGENTLOOP_FAIL_SILENTLY`
+    - `AGENTLOOP_EXPORT_DIR`
+
+    Optional values (`api_key`, `export_dir`) treat ``None`` as "keep the current
+    value". Pass :data:`CLEAR` to reset one of them back to ``None``.
+    """
+
+    global _runtime
+
+    from agentloop.retention import RetentionSession
+
+    if (
+        retention is not None
+        and retention is not CLEAR
+        and not isinstance(retention, RetentionSession)
+    ):
+        raise TypeError("retention must be RetentionSession, CLEAR or None")
+
+    if api_key is CLEAR:
+        resolved_api_key: str | None = None
+    elif api_key is not None:
+        resolved_api_key = api_key  # type: ignore[assignment]
+    else:
+        resolved_api_key = os.getenv("AGENTLOOP_API_KEY", _runtime.api_key)
+
+    if export_dir is CLEAR:
+        resolved_export_dir: Path | None = None
+    elif export_dir is not None:
+        resolved_export_dir = Path(export_dir)  # type: ignore[arg-type]
+    else:
+        env_export_dir = os.getenv("AGENTLOOP_EXPORT_DIR")
+        resolved_export_dir = Path(env_export_dir) if env_export_dir else _runtime.export_dir
+
+    _runtime = AgentLoopRuntimeConfig(
+        api_url=api_url or os.getenv("AGENTLOOP_API_URL", _runtime.api_url),
+        api_key=resolved_api_key,
+        project_id=project_id or os.getenv("AGENTLOOP_PROJECT_ID", _runtime.project_id),
+        auto_upload=auto_upload
+        if auto_upload is not None
+        else _env_bool("AGENTLOOP_AUTO_UPLOAD", _runtime.auto_upload),
+        auto_store=auto_store
+        if auto_store is not None
+        else _env_bool("AGENTLOOP_AUTO_STORE", _runtime.auto_store),
+        fail_silently=fail_silently
+        if fail_silently is not None
+        else _env_bool("AGENTLOOP_FAIL_SILENTLY", _runtime.fail_silently),
+        export_dir=resolved_export_dir,
+        retention=None
+        if retention is CLEAR
+        else retention
+        if retention is not None
+        else _runtime.retention,
+    )
+    return _runtime
+
+
+def configure_from_env() -> AgentLoopRuntimeConfig:
+    return init()
+
+
+def get_runtime_config() -> AgentLoopRuntimeConfig:
+    return _runtime
+
+
+def get_last_error() -> str | None:
+    return _last_error
+
+
+def reset_runtime() -> None:
+    global _runtime, _last_error
+    _runtime = AgentLoopRuntimeConfig()
+    _last_error = None
+
+
+def should_auto_export() -> bool:
+    return bool(_runtime.auto_upload or _runtime.auto_store or _runtime.export_dir)
+
+
+def finalize_trace(trace: Any) -> dict[str, Any]:
+    """Apply configured end-of-run side effects.
+
+    Depending on runtime config, this exports a JSON file, saves to the local
+    persistent store, and/or uploads to the configured API. Each destination runs
+    in its own error boundary in a deterministic order (export, store, upload), so
+    a failure in one cannot prevent the others from running.
+
+    When ``fail_silently`` is ``True`` (the default), every configured destination
+    is attempted and failures are collected in ``result["errors"]``, each tagged
+    with its ``destination``. When ``fail_silently`` is ``False``, the first failing
+    destination raises :class:`FinalizationError` (fail-fast); its ``result``
+    attribute still carries the destinations that completed before the failure.
+
+    A finalization in which every attempted destination succeeds clears any stale
+    process-global error so :func:`get_last_error` reflects the latest outcome.
+    """
+
+    global _last_error
+    result: dict[str, Any] = {
+        "exported_path": None,
+        "stored": False,
+        "uploaded": False,
+        "errors": [],
+    }
+    if _runtime.retention is not None:
+        try:
+            trace = _runtime.retention.retain(trace)
+            result["retention"] = {
+                "retained": trace is not None,
+                "sampling": _runtime.retention.summary(),
+            }
+        except Exception as exc:
+            # Never fall back to raw export after a privacy/retention failure.
+            errors = [
+                {
+                    "destination": "retention",
+                    "error": "Retention failed; no destinations attempted.",
+                }
+            ]
+            result["errors"] = errors
+            _last_error = errors[0]["error"]
+            if not _runtime.fail_silently:
+                raise FinalizationError(_last_error, result=result, errors=errors) from exc
+            return result
+        if trace is None:
+            _last_error = None
+            return result
+
+    def _do_export() -> None:
+        export_dir = _runtime.export_dir
+        if export_dir is None:  # pragma: no cover - guarded before registration
+            return
+        export_dir.mkdir(parents=True, exist_ok=True)
+        out = export_dir / f"{trace.run_id}.json"
+        trace.export_json(out)
+        result["exported_path"] = str(out)
+
+    def _do_store() -> None:
+        from agentloop.store import get_store
+
+        db = get_store()
+        db.init()
+        db.save_trace(trace, project_id=_runtime.project_id)
+        result["stored"] = True
+
+    def _do_upload() -> None:
+        from agentloop.client import AgentLoopClient
+
+        client = AgentLoopClient(base_url=_runtime.api_url, api_key=_runtime.api_key)
+        result["upload_response"] = client.upload_trace(trace)
+        result["uploaded"] = True
+
+    destinations: list[tuple[str, Any]] = []
+    if _runtime.export_dir is not None:
+        destinations.append(("export", _do_export))
+    if _runtime.auto_store:
+        destinations.append(("store", _do_store))
+    if _runtime.auto_upload:
+        destinations.append(("upload", _do_upload))
+
+    errors: list[dict[str, str]] = []
+    for destination, action in destinations:
+        try:
+            action()
+        except Exception as exc:
+            errors.append({"destination": destination, "error": str(exc)})
+            if not _runtime.fail_silently:
+                result["errors"] = errors
+                _last_error = f"{destination}: {exc}"
+                raise FinalizationError(
+                    f"{destination} finalization failed: {exc}",
+                    result=result,
+                    errors=errors,
+                ) from exc
+
+    result["errors"] = errors
+    if errors:
+        last = errors[-1]
+        _last_error = f"{last['destination']}: {last['error']}"
+    elif destinations:
+        # Every attempted destination succeeded; drop any stale error state.
+        _last_error = None
+
+    return result
+
+
+# Load env-driven defaults on import without forcing users to call init().
+configure_from_env()