agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/savings.py

@@ -0,0 +1,158 @@
+"""Compatible-selection model for combining per-recommendation savings.
+
+Optimization cards (and the findings derived from them) that touch the same
+spans compete for the same work: applying one changes or removes the spans the
+other targeted, so their estimates are alternatives, not additive. A realizable
+plan therefore applies a pairwise span-disjoint subset of the recommendations.
+
+``select_compatible`` picks that subset: latency savings is the primary
+objective and cost savings breaks ties, so both reported totals always come
+from the same subset. Small overlap-connected components are solved exactly.
+Larger components use a deterministic greedy fallback and the returned
+``Selection`` says explicitly that the result is not proven optimal.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterator, Sequence
+
+# Exact maximum-weight independent-set search is exponential in the size of one
+# overlap-connected component. Twenty-four keeps the common path exact while
+# retaining a deterministic bounded fallback for unusually dense plans.
+_EXACT_SEARCH_LIMIT = 24
+
+
+@dataclass(frozen=True)
+class SavingsItem:
+    spans: frozenset[str]
+    latency_ms: float = 0.0
+    cost_usd: float = 0.0
+
+
+@dataclass(frozen=True)
+class Selection:
+    indices: tuple[int, ...]
+    latency_ms: float
+    cost_usd: float
+    optimal: bool = True
+    algorithm: str = "exact_branch_and_bound"
+    exact_component_limit: int = _EXACT_SEARCH_LIMIT
+
+
+def select_compatible(items: Sequence[SavingsItem]) -> Selection:
+    """Return a deterministic compatible subset and its optimality metadata.
+
+    Latency savings is the primary objective and cost savings breaks ties.
+    Components up to ``_EXACT_SEARCH_LIMIT`` are solved exactly. Larger
+    components use a deterministic greedy fallback; in that case ``optimal`` is
+    false so callers cannot accidentally present an approximation as a maximum.
+    Span-free items are always selected.
+    """
+    chosen = [index for index, item in enumerate(items) if not item.spans]
+    spanned = [index for index, item in enumerate(items) if item.spans]
+    neighbor_sets: dict[int, set[int]] = {index: set() for index in spanned}
+    for position, left in enumerate(spanned):
+        for right in spanned[position + 1 :]:
+            if items[left].spans & items[right].spans:
+                neighbor_sets[left].add(right)
+                neighbor_sets[right].add(left)
+    adjacency = {index: frozenset(neighbors) for index, neighbors in neighbor_sets.items()}
+    used_approximation = False
+    for component in _components(spanned, adjacency):
+        if len(component) > _EXACT_SEARCH_LIMIT:
+            chosen.extend(_greedy_pick(items, component))
+            used_approximation = True
+        else:
+            chosen.extend(_exact_pick(items, component, adjacency))
+    chosen.sort()
+    return Selection(
+        indices=tuple(chosen),
+        latency_ms=sum(items[index].latency_ms for index in chosen),
+        cost_usd=sum(items[index].cost_usd for index in chosen),
+        optimal=not used_approximation,
+        algorithm=("hybrid_exact_greedy" if used_approximation else "exact_branch_and_bound"),
+        exact_component_limit=_EXACT_SEARCH_LIMIT,
+    )
+
+
+def _components(nodes: list[int], adjacency: dict[int, frozenset[int]]) -> Iterator[list[int]]:
+    seen: set[int] = set()
+    for start in nodes:
+        if start in seen:
+            continue
+        seen.add(start)
+        stack = [start]
+        component: list[int] = []
+        while stack:
+            node = stack.pop()
+            component.append(node)
+            for neighbor in sorted(adjacency[node], reverse=True):
+                if neighbor not in seen:
+                    seen.add(neighbor)
+                    stack.append(neighbor)
+        yield component
+
+
+def _savings_key(items: Sequence[SavingsItem], index: int) -> tuple[float, float]:
+    return (items[index].latency_ms, items[index].cost_usd)
+
+
+def _exact_pick(
+    items: Sequence[SavingsItem], component: list[int], adjacency: dict[int, frozenset[int]]
+) -> list[int]:
+    order = sorted(
+        component,
+        key=lambda index: (-items[index].latency_ms, -items[index].cost_usd, index),
+    )
+    suffix_latency = [0.0] * (len(order) + 1)
+    for position in range(len(order) - 1, -1, -1):
+        suffix_latency[position] = suffix_latency[position + 1] + items[order[position]].latency_ms
+    best_key = (float("-inf"), float("-inf"))
+    best_tuple: tuple[int, ...] | None = None
+
+    def search(
+        position: int, blocked: frozenset[int], latency: float, cost: float, picked: list[int]
+    ) -> None:
+        nonlocal best_key, best_tuple
+        if latency + suffix_latency[position] < best_key[0]:
+            return
+        if position == len(order):
+            score = (latency, cost)
+            candidate = tuple(sorted(picked))
+            if score > best_key or (
+                score == best_key and (best_tuple is None or candidate < best_tuple)
+            ):
+                best_key = score
+                best_tuple = candidate
+            return
+        index = order[position]
+        if index not in blocked:
+            picked.append(index)
+            search(
+                position + 1,
+                blocked | adjacency[index],
+                latency + items[index].latency_ms,
+                cost + items[index].cost_usd,
+                picked,
+            )
+            picked.pop()
+        search(position + 1, blocked, latency, cost, picked)
+
+    search(0, frozenset(), 0.0, 0.0, [])
+    return list(best_tuple or ())
+
+
+def _greedy_pick(items: Sequence[SavingsItem], component: list[int]) -> list[int]:
+    picked: list[int] = []
+    used_spans: set[str] = set()
+    order = sorted(
+        component,
+        key=lambda index: (-items[index].latency_ms, -items[index].cost_usd, index),
+    )
+    for index in order:
+        if items[index].spans & used_spans:
+            continue
+        picked.append(index)
+        used_spans |= items[index].spans
+    return picked

agentloop/scheduling_plan.py

@@ -0,0 +1,99 @@
+"""Stable DAG planning using current declarations, never historical success."""
+
+from __future__ import annotations
+
+import heapq
+
+from agentloop.context_types import fingerprint
+from agentloop.scheduling_types import ScheduleConfig, SchedulingError, ToolCall
+
+
+def plan_tools(calls, config, *, enforce=True):
+    if (
+        type(config) is not ScheduleConfig
+        or not isinstance(calls, (list, tuple))
+        or not 1 <= len(calls) <= 256
+        or any(type(call) is not ToolCall for call in calls)
+    ):
+        raise SchedulingError("invalid_plan")
+    ordered = tuple(call.call_id for call in calls)
+    by_id = {call.call_id: call for call in calls}
+    if len(by_id) != len(calls):
+        raise SchedulingError("duplicate_call")
+    rank = {identity: index for index, identity in enumerate(ordered)}
+    dependencies = {call.call_id: set(call.depends_on or ()) for call in calls}
+    if sum(map(len, dependencies.values())) > 4096:
+        raise SchedulingError("invalid_plan")
+    if any(not values <= by_id.keys() for values in dependencies.values()):
+        raise SchedulingError("missing_dependency")
+    successors, indegrees = {identity: set() for identity in ordered}, {}
+    for identity, values in dependencies.items():
+        indegrees[identity] = len(values)
+        for source in values:
+            successors[source].add(identity)
+    ready = [rank[identity] for identity in ordered if indegrees[identity] == 0]
+    heapq.heapify(ready)
+    topological = []
+    while ready:
+        identity = ordered[heapq.heappop(ready)]
+        topological.append(identity)
+        for target in successors[identity]:
+            indegrees[target] -= 1
+            if indegrees[target] == 0:
+                heapq.heappush(ready, rank[target])
+    if len(topological) != len(calls):
+        raise SchedulingError("cycle")
+    unknown = [
+        call.call_id
+        for call in calls
+        if call.depends_on is None
+        or call.reads is None
+        or call.writes is None
+        or call.concurrent is None
+        or call.effect == "unknown"
+    ]
+    unsupported = [call.call_id for call in calls if call.concurrent is False]
+    if unknown and config.on_unknown == "error" and enforce:
+        raise SchedulingError("unknown_safety")
+    if any(call.depends_on is None for call in calls):
+        # Unknown dependency semantics permit only the caller's original order.
+        if any(
+            rank[source] >= rank[target]
+            for target, sources in dependencies.items()
+            for source in sources
+        ):
+            raise SchedulingError("unknown_order")
+        topological = list(ordered)
+    effective = {identity: set(values) for identity, values in dependencies.items()}
+    conflicts = []
+    if unknown or unsupported:
+        for previous, following in zip(topological, topological[1:]):
+            effective[following].add(previous)
+    else:
+        access = {
+            identity: (set(by_id[identity].reads), set(by_id[identity].writes))
+            for identity in ordered
+        }
+        for index, before in enumerate(topological):
+            reads, writes = access[before]
+            for after in topological[index + 1 :]:
+                other_reads, other_writes = access[after]
+                shared = (writes & (other_reads | other_writes)) | (other_writes & reads)
+                if shared:
+                    effective[after].add(before)
+                    conflicts.append(
+                        {"before": before, "after": after, "resources": sorted(shared)}
+                    )
+    declaration = {
+        "calls": [call.declaration() for call in calls],
+        "configuration": config.to_dict(),
+        "serial_order": topological,
+        "effective_dependencies": {
+            identity: sorted(effective[identity], key=rank.get) for identity in ordered
+        },
+        "unknown_safety": unknown,
+        "unsupported_concurrency": unsupported,
+        "resource_conflicts": conflicts,
+        "proposed_concurrency": 1 if unknown or unsupported else config.max_concurrency,
+    }
+    return {**declaration, "plan_hash": fingerprint(declaration)}

agentloop/scheduling_types.py

@@ -0,0 +1,169 @@
+"""Explicit tool dependencies, resource contracts and ordered outcomes."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from threading import Event
+from time import monotonic
+from types import MappingProxyType
+from typing import Any, Callable
+
+from agentloop.budget_types import DispatchOptions, ResourceUsage
+from agentloop.context_types import fingerprint, identifier, synchronous
+
+SCHEDULE_KEY = "agentloop.tool_schedule"
+SCHEDULE_VERSION = "1.0"
+
+
+class SchedulingError(ValueError):
+    def __init__(self, reason):
+        allowed = {
+            "invalid_plan",
+            "duplicate_call",
+            "missing_dependency",
+            "duplicate_dependency",
+            "cycle",
+            "unknown_safety",
+            "unknown_order",
+            "already_started",
+            "unsupported_lifecycle",
+            "evidence_limit",
+            "invalid_trace_evidence",
+        }
+        self.reason_code = (
+            reason if isinstance(reason, str) and reason in allowed else "invalid_plan"
+        )
+        super().__init__(f"Tool scheduling failed: {self.reason_code}")
+
+
+@dataclass(frozen=True)
+class ScheduleConfig:
+    policy_id: str
+    version: str
+    branch_id: str
+    max_concurrency: int = 4
+    on_unknown: str = "sequential"
+    on_error: str = "stop"
+
+    def __post_init__(self):
+        for name in ("policy_id", "version", "branch_id"):
+            identifier(getattr(self, name), name)
+        if type(self.max_concurrency) is not int or not 1 <= self.max_concurrency <= 32:
+            raise ValueError("max_concurrency must be 1..32")
+        if self.on_unknown not in {"sequential", "error"} or self.on_error not in {
+            "stop",
+            "continue_independent",
+        }:
+            raise ValueError("unsupported scheduling policy")
+
+    def to_dict(self):
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    call_id: str
+    invoke: Callable[[ToolContext], Any] = field(repr=False, compare=False)
+    depends_on: tuple[str, ...] | None = None
+    reads: tuple[str, ...] | None = None
+    writes: tuple[str, ...] | None = None
+    concurrent: bool | None = None
+    effect: str = "unknown"
+    dispatch: DispatchOptions = field(default_factory=DispatchOptions)
+    usage_reader: Callable[[Any], ResourceUsage | None] | None = field(
+        default=None, repr=False, compare=False
+    )
+    error_usage_reader: Callable[[BaseException], ResourceUsage | None] | None = field(
+        default=None, repr=False, compare=False
+    )
+
+    def __post_init__(self):
+        identifier(self.call_id, "call_id")
+        if not synchronous(self.invoke):
+            raise ValueError("tool callback must be synchronous")
+        for name, maximum in (("depends_on", 256), ("reads", 64), ("writes", 64)):
+            values = getattr(self, name)
+            if values is None:
+                continue
+            if not isinstance(values, (list, tuple)) or len(values) > maximum:
+                raise ValueError("tool declarations must be bounded sequences")
+            for value in values:
+                identifier(value, name)
+            if len(values) != len(set(values)):
+                raise SchedulingError(
+                    "duplicate_dependency" if name == "depends_on" else "invalid_plan"
+                )
+            object.__setattr__(self, name, tuple(values))
+        if self.concurrent is not None and type(self.concurrent) is not bool:
+            raise ValueError("concurrent capability must be boolean or unknown")
+        if self.effect not in {"read_only", "mutating", "unknown"}:
+            raise ValueError("unsupported effect declaration")
+        if self.effect == "read_only" and self.writes:
+            raise ValueError("read-only call cannot declare writes")
+        if self.effect == "mutating" and self.writes == ():
+            raise ValueError("mutating call requires written resource declarations")
+        if type(self.dispatch) is not DispatchOptions:
+            raise ValueError("dispatch must be DispatchOptions")
+        for reader in (self.usage_reader, self.error_usage_reader):
+            if reader is not None and not synchronous(reader):
+                raise ValueError("usage readers must be synchronous")
+
+    def declaration(self):
+        dispatch = asdict(self.dispatch)
+        if dispatch["step"] is not None:
+            dispatch["step"]["step_id"] = "sha256:" + fingerprint(dispatch["step"]["step_id"])
+        if dispatch["reservation"] is not None:
+            dispatch["reservation"]["evidence_refs"] = [
+                "sha256:" + fingerprint(value) for value in dispatch["reservation"]["evidence_refs"]
+            ]
+        return {
+            "call_id": self.call_id,
+            "depends_on": None if self.depends_on is None else list(self.depends_on),
+            "reads": None if self.reads is None else list(self.reads),
+            "writes": None if self.writes is None else list(self.writes),
+            "concurrent": self.concurrent,
+            "effect": self.effect,
+            "dispatch": dispatch,
+        }
+
+
+@dataclass(frozen=True)
+class ToolContext:
+    call_id: str
+    prerequisites: MappingProxyType = field(repr=False)
+    _stop: Event = field(repr=False)
+    _external: Event | None = field(repr=False)
+    deadline: float | None = None
+
+    @property
+    def cancellation_requested(self):
+        return (
+            self._stop.is_set()
+            or (self._external is not None and self._external.is_set())
+            or (self.deadline is not None and monotonic() >= self.deadline)
+        )
+
+    @property
+    def remaining_s(self):
+        return None if self.deadline is None else max(0.0, self.deadline - monotonic())
+
+
+@dataclass(frozen=True)
+class ToolOutcome:
+    call_id: str
+    status: str
+    value: Any = field(default=None, repr=False, compare=False)
+    error: BaseException | None = field(default=None, repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class ScheduledResult:
+    schedule_id: str
+    outcomes: tuple[ToolOutcome, ...]
+    stop_reason: str | None = None
+
+    @property
+    def completed(self):
+        return self.stop_reason is None and all(
+            item.status == "completed" for item in self.outcomes
+        )

agentloop/schema.py

@@ -0,0 +1,257 @@
+"""Native trace schema: versioning, validation, and compatibility policy.
+
+This module is the single source of truth for the serialized AgentLoop trace
+contract. It is imported by the core deserialization path (`AgentTrace.from_dict`
+/ `AgentEvent.from_dict`), which every consumer — CLI import, HTTP ingestion,
+both stores, and the OTLP/Vercel adapters' round-trip tests — shares.
+
+It has no framework dependency: validation failures raise
+:class:`TraceValidationError`, and boundary code (for example the FastAPI server)
+maps that to a structured 4xx response. See ``docs/TRACE_SCHEMA.md`` for the
+published schema and compatibility policy.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+# Native trace schema version. Serialized traces carry this under
+# ``schema_version``. Bump the MAJOR component only for a breaking change to the
+# serialized shape; readers accept an equal-or-lower MAJOR and tolerate a missing
+# value (0.4-era traces predate the field). See ``docs/TRACE_SCHEMA.md``.
+#
+# 1.1 added the optional event field ``token_provenance`` (a backward-compatible
+# addition: 1.0 traces omit it and read back as provenance "unspecified").
+SCHEMA_VERSION = "1.1"
+
+# Statuses AgentLoop records on an event.
+_VALID_STATUSES = frozenset({"ok", "error"})
+
+# Event fields the schema knows about. Unknown structural fields are dropped on
+# read (the documented forward-compatibility policy); use ``metadata`` to carry
+# data that must survive a round trip.
+_KNOWN_EVENT_FIELDS = frozenset(
+    {
+        "event_id",
+        "run_id",
+        "event_type",
+        "name",
+        "started_at",
+        "ended_at",
+        "duration_ms",
+        "parent_id",
+        "model",
+        "input_tokens",
+        "output_tokens",
+        "token_provenance",
+        "input_text",
+        "output_text",
+        "status",
+        "error",
+        "metadata",
+    }
+)
+
+# Event fields that must be present and non-null (they have no dataclass default).
+_REQUIRED_EVENT_FIELDS = (
+    "event_id",
+    "run_id",
+    "event_type",
+    "name",
+    "started_at",
+    "ended_at",
+    "duration_ms",
+)
+
+_REQUIRED_STRING_EVENT_FIELDS = (
+    "event_id",
+    "run_id",
+    "event_type",
+    "name",
+    "started_at",
+    "ended_at",
+)
+
+_OPTIONAL_STRING_EVENT_FIELDS = (
+    "parent_id",
+    "model",
+    "input_text",
+    "output_text",
+    "error",
+    # Deliberately validated as a free string rather than a closed enum: a value
+    # this build does not recognize must not make a trace from a newer MINOR
+    # version unreadable. agentloop.tokens.provenance_grade() grades anything
+    # unrecognized as "unspecified", so an unknown value is never read as exact.
+    "token_provenance",
+)
+
+_NON_NEGATIVE_INT_EVENT_FIELDS = ("input_tokens", "output_tokens")
+
+
+class TraceValidationError(ValueError):
+    """A serialized trace or event failed schema validation.
+
+    Carries the offending ``field`` path and a human ``reason`` so a boundary can
+    surface both in a 4xx response. It subclasses :class:`ValueError` so existing
+    callers that already catch ``ValueError`` (the CLI loaders, for example) keep
+    working.
+    """
+
+    def __init__(self, field: str, reason: str) -> None:
+        self.field = field
+        self.reason = reason
+        super().__init__(f"{field}: {reason}")
+
+
+def schema_major(version: str) -> int:
+    """Return the MAJOR component of a ``schema_version`` string, or 0 if unset."""
+
+    if not version:
+        return 0
+    head = str(version).split(".", 1)[0]
+    try:
+        return int(head)
+    except ValueError:
+        raise TraceValidationError("schema_version", f"is not a valid version: {version!r}")
+
+
+def check_schema_version(version: Any) -> None:
+    """Reject payloads written by a newer, incompatible major schema version."""
+
+    if version is None:
+        return  # 0.4-era traces have no schema_version; tolerate their absence.
+    if not isinstance(version, str):
+        raise TraceValidationError("schema_version", "must be a string")
+    if schema_major(version) > schema_major(SCHEMA_VERSION):
+        raise TraceValidationError(
+            "schema_version",
+            f"trace was written with schema {version}, which is newer than the "
+            f"supported {SCHEMA_VERSION}; upgrade AgentLoop to read it",
+        )
+
+
+def coerce_event_dict(data: Any, *, index: int) -> dict[str, Any]:
+    """Validate one serialized event and return kwargs for :class:`AgentEvent`.
+
+    Unknown fields are ignored (forward-compatibility policy). Raises
+    :class:`TraceValidationError` naming ``events[<index>].<field>`` on any
+    missing required field, wrong type, or out-of-range numeric value.
+    """
+
+    where = f"events[{index}]"
+    if not isinstance(data, dict):
+        raise TraceValidationError(where, "must be an object")
+
+    for name in _REQUIRED_EVENT_FIELDS:
+        if data.get(name) is None:
+            raise TraceValidationError(f"{where}.{name}", "is required")
+
+    clean: dict[str, Any] = {}
+    for name in _REQUIRED_STRING_EVENT_FIELDS:
+        value = data[name]
+        if not isinstance(value, str) or not value:
+            raise TraceValidationError(f"{where}.{name}", "must be a non-empty string")
+        clean[name] = value
+
+    for name in _OPTIONAL_STRING_EVENT_FIELDS:
+        value = data.get(name)
+        if value is not None and not isinstance(value, str):
+            raise TraceValidationError(f"{where}.{name}", "must be a string or null")
+        clean[name] = value
+
+    clean["duration_ms"] = _non_negative_number(data["duration_ms"], f"{where}.duration_ms")
+
+    for name in _NON_NEGATIVE_INT_EVENT_FIELDS:
+        if name in data and data[name] is not None:
+            clean[name] = _non_negative_int(data[name], f"{where}.{name}")
+
+    status = data.get("status", "ok")
+    if not isinstance(status, str) or status not in _VALID_STATUSES:
+        raise TraceValidationError(
+            f"{where}.status",
+            f"must be one of {', '.join(sorted(_VALID_STATUSES))}",
+        )
+    clean["status"] = status
+
+    metadata = data.get("metadata", {})
+    if not isinstance(metadata, dict):
+        raise TraceValidationError(f"{where}.metadata", "must be an object")
+    clean["metadata"] = metadata
+
+    return clean
+
+
+def validate_trace_dict(data: Any) -> None:
+    """Validate a serialized trace envelope before its events are constructed.
+
+    Checks the schema version, required top-level fields, metadata shape, unique
+    event ids, and event-to-trace run-id consistency. Individual event fields are
+    validated by :func:`coerce_event_dict`.
+    """
+
+    if not isinstance(data, dict):
+        raise TraceValidationError("trace", "must be an object")
+
+    check_schema_version(data.get("schema_version"))
+
+    name = data.get("name")
+    if not isinstance(name, str) or not name:
+        raise TraceValidationError("name", "must be a non-empty string")
+
+    run_id = data.get("run_id")
+    if not isinstance(run_id, str) or not run_id:
+        raise TraceValidationError("run_id", "must be a non-empty string")
+
+    metadata = data.get("metadata", {})
+    if not isinstance(metadata, dict):
+        raise TraceValidationError("metadata", "must be an object")
+
+    validate_elapsed_ms(data.get("elapsed_ms"))
+
+    events = data.get("events", [])
+    if not isinstance(events, list):
+        raise TraceValidationError("events", "must be a list")
+
+    seen_ids: set[str] = set()
+    for index, event in enumerate(events):
+        if not isinstance(event, dict):
+            raise TraceValidationError(f"events[{index}]", "must be an object")
+        event_id = event.get("event_id")
+        if isinstance(event_id, str):
+            if event_id in seen_ids:
+                raise TraceValidationError(
+                    f"events[{index}].event_id", f"is not unique within the trace: {event_id}"
+                )
+            seen_ids.add(event_id)
+        event_run_id = event.get("run_id")
+        if isinstance(event_run_id, str) and event_run_id != run_id:
+            raise TraceValidationError(
+                f"events[{index}].run_id",
+                f"does not match the trace run_id {run_id!r}",
+            )
+
+
+def validate_elapsed_ms(value: Any) -> float | None:
+    """Validate optional trace runtime before constructors or HTTP models coerce it."""
+    return None if value is None else _non_negative_number(value, "elapsed_ms")
+
+
+def _non_negative_number(value: Any, field: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TraceValidationError(field, "must be a number")
+    try:
+        number = float(value)
+    except OverflowError:
+        raise TraceValidationError(field, "must be a finite, non-negative number") from None
+    if not math.isfinite(number) or number < 0:
+        raise TraceValidationError(field, "must be a finite, non-negative number")
+    return number
+
+
+def _non_negative_int(value: Any, field: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TraceValidationError(field, "must be an integer")
+    if value < 0:
+        raise TraceValidationError(field, "must be non-negative")
+    return value