agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/otel_ids.py

@@ -0,0 +1,81 @@
+"""Map arbitrary AgentLoop identifiers to valid OpenTelemetry trace/span ids.
+
+OTLP requires trace ids to be 32 lowercase hex characters and span ids 16, with
+a non-zero value. AgentLoop lets callers (and the API/local constructors) pick
+custom run/event ids that may contain a prefix, non-hex characters, separators,
+or all-zero values — the smoke script even uses a hyphenated run id. Exporting
+those verbatim produced invalid ids that conforming OTLP consumers reject.
+
+These helpers produce a valid, deterministic id for any native identifier while
+leaving an already-valid id untouched, so:
+
+- a valid OTLP id (correct width, non-zero lowercase hex) is preserved exactly,
+  including one imported into AgentLoop, so it round-trips back out unchanged;
+- every other id — non-hex, wrong width (including the tracer's 16-hex run id
+  that is too short for a 32-char trace id), empty, or all-zero — is hashed with
+  SHA-256, which keeps distinct native ids distinct. In particular short hex ids
+  are NOT left-zero-padded: padding would map ``"a"`` and ``"0a"`` to the same
+  value and break within-trace uniqueness / parent linkage.
+
+The exporters keep the original native id in span attributes so a remapped id
+stays diagnosable.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+_HEX_DIGITS = frozenset("0123456789abcdef")
+_TRACE_WIDTH = 32
+_SPAN_WIDTH = 16
+_TRACE_PREFIXES = ("run_", "trace_")
+_SPAN_PREFIXES = ("span_", "evt_")
+
+
+def is_valid_trace_id(value: str) -> bool:
+    """True if ``value`` is a valid OTLP trace id (32 lowercase hex, non-zero)."""
+    return _is_valid(value, _TRACE_WIDTH)
+
+
+def is_valid_span_id(value: str) -> bool:
+    """True if ``value`` is a valid OTLP span id (16 lowercase hex, non-zero)."""
+    return _is_valid(value, _SPAN_WIDTH)
+
+
+def to_trace_id(native: str) -> str:
+    """Return a valid 32-char lowercase-hex OTLP trace id for ``native``."""
+    return _to_otel_id(native, _TRACE_WIDTH, _TRACE_PREFIXES)
+
+
+def to_span_id(native: str) -> str:
+    """Return a valid 16-char lowercase-hex OTLP span id for ``native``."""
+    return _to_otel_id(native, _SPAN_WIDTH, _SPAN_PREFIXES)
+
+
+def _is_valid(value: str, width: int) -> bool:
+    return len(value) == width and _HEX_DIGITS.issuperset(value) and set(value) != {"0"}
+
+
+def _to_otel_id(native: str, width: int, prefixes: tuple[str, ...]) -> str:
+    stripped = _strip_prefix(str(native), prefixes).lower()
+    # An already-valid id (e.g. a real OTLP id, or one round-tripped through
+    # import) is preserved exactly. Everything else — non-hex, wrong width,
+    # empty, or all-zero — is hashed so distinct native ids stay distinct.
+    # Note: short hex ids are deliberately NOT zero-padded, because padding maps
+    # "a" and "0a" (and any leading-zero variants) to the same value.
+    if _is_valid(stripped, width):
+        return stripped
+    return _hash_id(native, width)
+
+
+def _strip_prefix(value: str, prefixes: tuple[str, ...]) -> str:
+    for prefix in prefixes:
+        if value.startswith(prefix):
+            return value[len(prefix) :]
+    return value
+
+
+def _hash_id(native: str, width: int) -> str:
+    digest = hashlib.sha256(str(native).encode("utf-8")).hexdigest()[:width]
+    # SHA-256 can't realistically be all-zero, but OTLP forbids it, so guard.
+    return ("1" + digest[1:]) if set(digest) == {"0"} else digest

agentloop/otel_semantics.py

@@ -0,0 +1,134 @@
+"""Normalized fields for pinned GenAI, OpenInference, and MCP conventions."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from agentloop.schema import TraceValidationError
+
+INPUT_USAGE = ("gen_ai.usage.input_tokens", "llm.token_count.prompt", "llm.usage.prompt_tokens")
+OUTPUT_USAGE = (
+    "gen_ai.usage.output_tokens",
+    "llm.token_count.completion",
+    "llm.usage.completion_tokens",
+)
+_OI_KINDS = {
+    "LLM": "model",
+    "EMBEDDING": "model",
+    "CHAIN": "workflow",
+    "AGENT": "agent",
+    "TOOL": "tool",
+    "RETRIEVER": "retriever",
+    "RERANKER": "reranker",
+    "GUARDRAIL": "guardrail",
+    "EVALUATOR": "evaluator",
+}
+_MEMORY_OPERATIONS = {
+    "create_memory",
+    "create_memory_store",
+    "delete_memory",
+    "delete_memory_store",
+    "search_memory",
+    "update_memory",
+    "upsert_memory",
+}
+
+
+def extended_kind(attrs: dict[str, Any]) -> str | None:
+    operation = attrs.get("gen_ai.operation.name")
+    if isinstance(operation, str) and operation in _MEMORY_OPERATIONS:
+        return "memory"
+    if isinstance(operation, str) and operation in {"plan", "fetch_response"}:
+        return "unknown"
+    if operation:
+        return None
+    if "openinference.span.kind" in attrs:
+        return _OI_KINDS.get(str(attrs["openinference.span.kind"]).upper(), "unknown")
+    if "mcp.method.name" in attrs:
+        return {"tools/call": "tool", "resources/read": "retriever"}.get(
+            str(attrs["mcp.method.name"]), "unknown"
+        )
+    if any(key in attrs for key in ("http.request.method", "http.method", "rpc.system")):
+        return "unknown"
+    return None
+
+
+def usage_count(attrs: dict[str, Any], keys: tuple[str, ...]) -> int:
+    for key in keys:
+        if key not in attrs:
+            continue
+        value = attrs[key]
+        if isinstance(value, bool) or not isinstance(value, int | str):
+            raise TraceValidationError(key, "usage must be a nonnegative integer")
+        try:
+            result = int(value)
+        except ValueError as exc:
+            raise TraceValidationError(key, "usage must be a nonnegative integer") from exc
+        if result < 0:
+            raise TraceValidationError(key, "usage must be a nonnegative integer")
+        return result
+    return 0
+
+
+def normalize_metadata(attrs: dict[str, Any], metadata: dict[str, Any]) -> None:
+    aliases = {
+        "provider": ("gen_ai.provider.name", "gen_ai.system", "llm.provider"),
+        "conversation_id": ("gen_ai.conversation.id",),
+        "session_id": ("session.id", "mcp.session.id"),
+        "tool_call_id": ("gen_ai.tool.call.id", "tool.id", "tool_call.id"),
+        "error_type": ("error.type", "exception.type"),
+    }
+    for target, keys in aliases.items():
+        for key in keys:
+            if isinstance(attrs.get(key), str):
+                metadata.setdefault(target, attrs[key])
+                break
+    for target, keys in {
+        "cached_input_tokens": (
+            "gen_ai.usage.cache_read.input_tokens",
+            "llm.token_count.prompt_details.cache_read",
+        ),
+        "cache_write_input_tokens": (
+            "gen_ai.usage.cache_write.input_tokens",
+            "llm.token_count.prompt_details.cache_write",
+        ),
+        "reasoning_output_tokens": (
+            "gen_ai.usage.reasoning.output_tokens",
+            "llm.token_count.completion_details.reasoning",
+        ),
+    }.items():
+        if any(key in attrs for key in keys):
+            metadata.setdefault(target, usage_count(attrs, keys))
+    reported_cost = attrs.get("llm.cost.total")
+    if (
+        not isinstance(reported_cost, bool)
+        and isinstance(reported_cost, int | float)
+        and math.isfinite(reported_cost)
+        and reported_cost >= 0
+    ):
+        metadata.setdefault("provider_reported_cost_usd", reported_cost)
+
+
+def evaluation_result(attrs: dict[str, Any], *, source: str) -> dict[str, Any] | None:
+    families = (
+        (
+            "gen_ai.evaluation.name",
+            "gen_ai.evaluation.score.value",
+            "gen_ai.evaluation.score.label",
+            "gen_ai.evaluation.explanation",
+        ),
+        ("evaluation.name", "evaluation.score", "evaluation.label", "evaluation.explanation"),
+        ("annotation.name", "annotation.score", "annotation.label", "annotation.explanation"),
+    )
+    for name, score, label, explanation in families:
+        if name in attrs:
+            return {
+                "source": source,
+                "name": attrs[name],
+                "score": attrs.get(score),
+                "label": attrs.get(label),
+                "explanation": attrs.get(explanation),
+                "interpretation": "external evaluation; scale and acceptance criteria are source-defined",
+            }
+    return None

agentloop/parallelism.py

@@ -0,0 +1,141 @@
+"""Conservative concurrency candidates shared by reports and execution graphs."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from agentloop.operations import operation_kind
+from agentloop.timing import duration_ms, event_interval_ms
+from agentloop.workflow_types import stage_summary
+
+PARALLELISM_NOTICE = (
+    "Repeated tool calls may be candidates for concurrent execution. "
+    "Verify output independence and shared-state safety before changing them."
+)
+PARALLELISM_REWRITE = (
+    "After verifying output independence and shared-state safety, use asyncio.gather "
+    "or ThreadPoolExecutor and validate the change with replay."
+)
+PARALLELISM_FORMULA = (
+    "sum(tool durations) - max(tool duration), assuming the calls can run concurrently"
+)
+_ASSUMPTIONS = (
+    "No call consumes another call's output.",
+    "Calls do not conflict through shared mutable state.",
+    "Calls are on the runtime-limiting path and scheduling adds no overhead.",
+)
+
+
+def parallelization_candidates(
+    events: Iterable[Any], *, dependency_edges: Iterable[tuple[str, str]] = ()
+) -> list[dict[str, Any]]:
+    """Return hypotheses, never proof of independence or verified savings.
+
+    Optional metadata: ``parallel_safe`` is a boolean declaration, ``depends_on``
+    is a list of span IDs. Explicit relationships take precedence over declarations.
+    Inferred sequence edges must not be passed as causal dependencies.
+    """
+    by_id = {}
+    groups: dict[tuple[str, str | None], list[str]] = {}
+    dependencies: dict[str, set[str]] = {}
+    invalid_dependencies: set[str] = set()
+    unsafe: set[str] = set()
+    declarations: set[str] = set()
+    for index, event in enumerate(events):
+        span_id = (
+            getattr(event, "event_id", None) or getattr(event, "node_id", None) or f"node_{index}"
+        )
+        if span_id in by_id:
+            return []  # Ambiguous span identity cannot support dependency analysis.
+        by_id[span_id] = event
+        metadata = getattr(event, "metadata", None)
+        metadata = metadata if isinstance(metadata, Mapping) else {}
+        required = metadata.get("depends_on", [])
+        if not isinstance(required, list) or any(
+            not isinstance(value, str) or not value for value in required
+        ):
+            invalid_dependencies.add(span_id)
+            required = []
+        dependencies[span_id] = set(required)
+        stage = stage_summary(event)
+        if stage is not None and (
+            stage.get("schema_status") != "supported" or stage.get("dependency_status") == "invalid"
+        ):
+            invalid_dependencies.add(span_id)
+        if "parallel_safe" in metadata:
+            if metadata["parallel_safe"] is True:
+                declarations.add(span_id)
+            else:
+                unsafe.add(span_id)
+        if operation_kind(event) == "tool":
+            groups.setdefault((event.name, getattr(event, "parent_id", None)), []).append(span_id)
+    for span_id, event in by_id.items():
+        parent_id = getattr(event, "parent_id", None)
+        if parent_id in by_id:
+            dependencies[span_id].add(parent_id)
+    for source, target in dependency_edges:
+        if target in dependencies:
+            dependencies[target].add(source)
+
+    candidates = []
+    for (name, _), span_ids in groups.items():
+        members = set(span_ids)
+        if len(members) < 3 or members & unsafe or members & invalid_dependencies:
+            continue
+        pending = [ancestor for member in members for ancestor in dependencies[member]]
+        visited = set()
+        blocked = False
+        while pending:
+            ancestor = pending.pop()
+            if ancestor in members or ancestor not in by_id or ancestor in invalid_dependencies:
+                blocked = True
+                break
+            if ancestor not in visited:
+                visited.add(ancestor)
+                pending.extend(dependencies[ancestor])
+        if blocked:
+            continue
+
+        intervals = [event_interval_ms(by_id[span_id]) for span_id in span_ids]
+        known = sorted(interval for interval in intervals if interval is not None)
+        if any(previous[1] > current[0] for previous, current in zip(known, known[1:])):
+            continue  # Observed overlap already invalidates the serial-savings model.
+        complete_timing = len(known) == len(span_ids)
+        durations = [duration_ms(by_id[span_id]) for span_id in span_ids]
+        sequential, parallel = sum(durations), max(durations)
+        if sequential <= parallel:
+            continue
+        declared = members <= declarations
+        assumptions = list(_ASSUMPTIONS)
+        if not complete_timing:
+            assumptions.append("Calls ran serially; timing is incomplete or inconsistent.")
+        candidates.append(
+            {
+                "name": name,
+                "event_type": "tool_call",
+                "count": len(span_ids),
+                "node_ids": sorted(span_ids),
+                "sequential_time_ms": round(sequential, 3),
+                "estimated_parallel_time_ms": round(parallel, 3),
+                "estimated_savings_ms": round(sequential - parallel, 3),
+                "evidence_level": "declared" if declared else "inferred",
+                "confidence": "medium" if declared and complete_timing else "low",
+                "assumptions": assumptions,
+                "observations": {
+                    "evidence_level": "observed",
+                    "tool_call_count": len(span_ids),
+                    "cumulative_span_time_ms": round(sequential, 3),
+                    "timing": "non_overlapping" if complete_timing else "unavailable",
+                },
+                "description": (
+                    "The integration declares these calls safe to run concurrently; validate with replay."
+                    if declared
+                    else PARALLELISM_NOTICE
+                ),
+                "estimate_formula": PARALLELISM_FORMULA,
+            }
+        )
+    return sorted(
+        candidates, key=lambda item: (-item["estimated_savings_ms"], item["name"], item["node_ids"])
+    )