agentloop-profiler 0.4.0__py3-none-any.whl

agentloop/__init__.py

@@ -0,0 +1,68 @@
+from agentloop.autoinstrument import (
+    DetectionResult,
+    InstrumentationResult,
+    auto_instrument,
+    detect_integrations,
+)
+from agentloop.client import AgentLoopClient, AgentLoopClientError
+from agentloop.decorators import trace_model, trace_tool, traceable
+from agentloop.doctor import run_doctor
+from agentloop.findings import build_diagnosis
+from agentloop.otel import trace_from_otel, trace_to_otel
+from agentloop.patches import build_patch_plan
+from agentloop.replay import ReplayGates, build_replay_report
+from agentloop.runtime import (
+    CLEAR,
+    FinalizationError,
+    get_last_error,
+    get_runtime_config,
+    init,
+    reset_runtime,
+)
+from agentloop.tracer import (
+    AgentTrace,
+    current_trace,
+    record_model_call,
+    record_tool_call,
+    trace_agent,
+    trace_model_call,
+    trace_retry,
+    trace_tool_call,
+)
+from agentloop.value import build_value_report
+from agentloop.version import __version__
+
+__all__ = [
+    "AgentLoopClient",
+    "AgentLoopClientError",
+    "AgentTrace",
+    "CLEAR",
+    "FinalizationError",
+    "DetectionResult",
+    "InstrumentationResult",
+    "ReplayGates",
+    "auto_instrument",
+    "detect_integrations",
+    "build_value_report",
+    "build_diagnosis",
+    "build_patch_plan",
+    "build_replay_report",
+    "current_trace",
+    "get_last_error",
+    "get_runtime_config",
+    "init",
+    "record_model_call",
+    "record_tool_call",
+    "reset_runtime",
+    "run_doctor",
+    "trace_agent",
+    "trace_from_otel",
+    "trace_model",
+    "trace_model_call",
+    "trace_tool",
+    "trace_tool_call",
+    "trace_retry",
+    "traceable",
+    "trace_to_otel",
+    "__version__",
+]

agentloop/audit.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from agentloop.exporters import export_report_markdown
+from agentloop.tracer import AgentTrace
+
+
+@dataclass
+class AuditResult:
+    report: dict[str, Any]
+    markdown_path: Path | None = None
+
+
+def run_audit(trace_path: str | Path, out_path: str | Path | None = None) -> AuditResult:
+    trace = AgentTrace.from_json(trace_path)
+    report = trace.report()
+    md_path = export_report_markdown(report, out_path) if out_path else None
+    return AuditResult(report=report, markdown_path=md_path)
+
+
+def estimate_improvement(report: dict[str, Any]) -> dict[str, float]:
+    latency_savings = 0.0
+    for item in report.get("parallelism_opportunities", []):
+        latency_savings += item.get("estimated_savings_ms", 0.0)
+    retry_savings = report.get("retry_time_ms", 0.0) * 0.8
+    repeated_ratio = report.get("repeated_context_ratio", 0.0)
+    cost_savings = report.get("estimated_cost_usd", 0.0) * min(0.5, repeated_ratio)
+    return {
+        "estimated_latency_savings_ms": round(latency_savings + retry_savings, 3),
+        "estimated_cost_savings_usd": round(cost_savings, 6),
+    }

agentloop/autoinstrument.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import importlib.util
+import warnings
+from dataclasses import dataclass, field
+from typing import Any
+
+# Framework integrations AgentLoop ships helpers for, mapped to the import name
+# used to detect whether that framework's SDK is installed.
+_DETECTABLE_INTEGRATIONS: dict[str, str] = {
+    "openai": "openai",
+    "langgraph": "langgraph",
+    "crewai": "crewai",
+}
+
+# Integrations that are not detectable as an installed Python package because
+# instrumentation happens outside this process, mapped to guidance.
+_NON_PYTHON_INTEGRATIONS: dict[str, str] = {
+    "vercel_ai_sdk": "JavaScript-side; call trace_from_vercel_ai_events(...) on exported telemetry",
+}
+
+
+@dataclass
+class DetectionResult:
+    """Which framework integrations are available in the current environment.
+
+    This is a *detection* result. It reports whether each integration's SDK is
+    importable in this process; it does not wrap, patch, or register anything.
+    Instrument an application by applying the helpers in
+    :mod:`agentloop.integrations` (or the generic decorator SDK) from that
+    application's own startup.
+    """
+
+    available: list[str] = field(default_factory=list)
+    unavailable: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return bool(self.available)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"ok": self.ok, "available": self.available, "unavailable": self.unavailable}
+
+
+def _module_available(module_name: str) -> bool:
+    """Return True if ``module_name`` is importable, without importing it."""
+    try:
+        return importlib.util.find_spec(module_name) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def detect_integrations() -> DetectionResult:
+    """Detect which AgentLoop framework integrations are available here.
+
+    Detection only checks package availability with
+    :func:`importlib.util.find_spec` and never imports the framework, so it is
+    cheap and side-effect free and safe to run at application startup. The result
+    is deterministic for a given environment, so repeated calls return equal
+    results.
+
+    This function does not enable instrumentation. To record traces, apply the
+    helpers in :mod:`agentloop.integrations` (for example
+    ``instrument_openai_client``) or the generic decorator SDK from the
+    application process you want to trace.
+    """
+
+    result = DetectionResult()
+
+    for name, module_name in _DETECTABLE_INTEGRATIONS.items():
+        if _module_available(module_name):
+            result.available.append(name)
+        else:
+            result.unavailable[name] = "package not installed"
+
+    result.unavailable.update(_NON_PYTHON_INTEGRATIONS)
+    return result
+
+
+# Backwards-compatible aliases. The previous names implied that calling this
+# enabled instrumentation, which it never did.
+InstrumentationResult = DetectionResult
+
+
+def auto_instrument(**kwargs: Any) -> DetectionResult:
+    """Deprecated alias for :func:`detect_integrations`.
+
+    The old name and its ``enabled`` field wrongly implied that calling it
+    activated instrumentation; it only ever detected installed frameworks. Use
+    :func:`detect_integrations` instead and apply
+    :mod:`agentloop.integrations` helpers from your application startup. Any
+    keyword arguments are ignored and were never used.
+    """
+
+    warnings.warn(
+        "auto_instrument() never enabled instrumentation; it only detects "
+        "installed frameworks. It is deprecated: use detect_integrations() and "
+        "apply agentloop.integrations helpers from your application startup.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return detect_integrations()

agentloop/ci.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agentloop.findings import build_diagnosis
+from agentloop.markdown import markdown_table_cell, markdown_text
+from agentloop.replay import ReplayGates, build_replay_report
+
+
+def build_ci_report(
+    baseline_trace: Any,
+    candidate_trace: Any,
+    *,
+    gates: ReplayGates | None = None,
+    quality_report: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the PR-facing AgentLoop performance report."""
+    replay = build_replay_report(
+        baseline_trace, candidate_trace, gates=gates, quality_report=quality_report
+    )
+    diagnosis = build_diagnosis(candidate_trace)
+    summary = _summary(replay, diagnosis)
+    return {
+        "passed": replay["gates"]["passed"],
+        "status": "passed" if replay["gates"]["passed"] else "failed",
+        "summary": summary,
+        "replay": replay,
+        "diagnosis": diagnosis,
+    }
+
+
+def ci_report_to_markdown(report: dict[str, Any]) -> str:
+    summary = report["summary"]
+    replay = report["replay"]
+    diagnosis = report["diagnosis"]
+    gate_status = "passed" if replay["gates"]["passed"] else "failed"
+
+    lines = [
+        "# AgentLoop CI Report",
+        "",
+        f"- Status: {gate_status}",
+        f"- Replay: {markdown_text(replay['summary'])}",
+        f"- Merge recommendation: {markdown_text(summary['merge_recommendation'])}",
+        (
+            f"- Findings: {summary['finding_count']} total, "
+            f"{summary['high_severity_count']} high severity, "
+            f"{summary['patchable_count']} patchable"
+        ),
+        "",
+        "## Performance Gates",
+        "",
+        "| Gate | Status | Detail |",
+        "|---|---|---|",
+    ]
+    for gate in replay["gates"]["results"]:
+        status = "pass" if gate["passed"] else "fail"
+        lines.append(
+            f"| {markdown_table_cell(gate['name'])} | {status} | "
+            f"{markdown_table_cell(gate['detail'])} |"
+        )
+
+    lines.extend(
+        [
+            "",
+            "## Metric Impact",
+            "",
+            "| Metric | Impact |",
+            "|---|---:|",
+            f"| Latency improvement | {summary['latency_improvement_pct']:.2f}% |",
+            f"| Cost improvement | {summary['cost_improvement_pct']:.2f}% |",
+            f"| Retry delta | {summary['retry_count_delta']} |",
+            f"| Candidate schema validity | {summary['candidate_schema_validity']} |",
+            f"| Candidate quality score | {summary['candidate_quality_score']} |",
+            "",
+            "## Top Findings",
+            "",
+        ]
+    )
+
+    findings = diagnosis.get("findings", [])
+    if not findings:
+        lines.append("No machine-actionable optimization findings detected.")
+    else:
+        lines.extend(
+            [
+                "| Finding | Severity | Type | Rewrite |",
+                "|---|---|---|---|",
+            ]
+        )
+        for finding in findings[:5]:
+            lines.append(
+                "| "
+                f"{markdown_table_cell(finding['finding_id'])}: "
+                f"{markdown_table_cell(finding['title'])} | "
+                f"{markdown_table_cell(finding['severity'])} | "
+                f"{markdown_table_cell(finding['type'])} | "
+                f"{markdown_table_cell(finding['rewrite']['hint'])} |"
+            )
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _summary(replay: dict[str, Any], diagnosis: dict[str, Any]) -> dict[str, Any]:
+    deltas = replay["deltas"]
+    diagnosis_summary = diagnosis["summary"]
+    candidate = replay["candidate"]
+    gates_passed = replay["gates"]["passed"]
+    merge_recommendation = (
+        "safe to merge by configured AgentLoop gates"
+        if gates_passed and diagnosis_summary["high_severity_count"] == 0
+        else "review before merge; configured gates or high-severity findings need attention"
+    )
+    return {
+        "latency_improvement_pct": deltas["latency_improvement_pct"],
+        "cost_improvement_pct": deltas["cost_improvement_pct"],
+        "retry_count_delta": deltas["retry_count_delta"],
+        "candidate_schema_validity": _format_optional(
+            candidate.get("schema_validity_pct"), suffix="%"
+        )
+        if candidate.get("schema_validity_pct") is not None
+        else _format_optional(candidate.get("schema_valid")),
+        "candidate_quality_score": _format_optional(candidate.get("quality_score")),
+        "finding_count": diagnosis_summary["finding_count"],
+        "high_severity_count": diagnosis_summary["high_severity_count"],
+        "patchable_count": diagnosis_summary["patchable_count"],
+        "merge_recommendation": merge_recommendation,
+    }
+
+
+def _format_optional(value: Any, suffix: str = "") -> str:
+    if value is None:
+        return "not provided"
+    if isinstance(value, float):
+        return f"{value:.4f}{suffix}"
+    return f"{value}{suffix}"