Skip to content

monte-carlo-data/mc-agent-toolkit / skills/instrument-agent

monte-carlo-instrument-agent

Flagged

Instrument a new AI agent in a Python codebase for Monte Carlo Agent Observability. Detects AI libraries, installs the Monte Carlo OpenTelemetry SDK, and proposes tracing setup and decorator placements as diffs. Asks before editing any file.

FileKindSize
SKILL.mdskill md12.0 KB
references/decorator-placement.mdmarkdown7.9 KB
references/library-detection.mdmarkdown14.4 KB
references/redaction.mdmarkdown13.6 KB
references/setup-template.mdmarkdown21.5 KB
references/troubleshooting.mdmarkdown10.8 KB
references/verify-traces.mdmarkdown8.1 KB
references/workflow.mdmarkdown18.6 KB
scripts/detect_libraries.pyexecutablescript19.1 KB
scripts/fetch_sdk_docs.pyscript11.8 KB
tests/fixtures/boto3-only/requirements.txtmanifest31 B
tests/fixtures/existing-setup/requirements.txtmanifest17 B
tests/fixtures/existing-setup/src/tracing.pyscript140 B
tests/fixtures/existing-setup/src/tracing_alias.pyscript146 B
tests/fixtures/existing-setup/src/tracing_direct.pyscript162 B
tests/fixtures/mixed-requirements-pyproject/pyproject.tomlmanifest299 B
tests/fixtures/mixed-requirements-pyproject/requirements.txtmanifest12 B
tests/fixtures/no-deps/README.mdmarkdown225 B
tests/fixtures/pep621-pyproject/pyproject.tomlmanifest317 B
tests/fixtures/pipfile/Pipfilemanifest194 B
tests/fixtures/poetry-pyproject/pyproject.tomlmanifest345 B
tests/fixtures/requirements/requirements.txtmanifest194 B
tests/fixtures/sample_agent/agent.pyscript1.4 KB
tests/fixtures/sample_agent/requirements.txtmanifest74 B
tests/fixtures/sample_agent/traced_entrypoint.pyscript109 B
tests/fixtures/sample_serverless_agent/agent.pyscript1.5 KB
tests/fixtures/sample_serverless_agent/requirements.txtmanifest104 B
tests/fixtures/sample_serverless_agent/serverless.ymlconfig358 B
tests/fixtures/serverless/app.pyscript50 B
tests/fixtures/serverless/requirements.txtmanifest17 B
tests/fixtures/serverless/serverless.ymlconfig32 B
tests/test_detect_libraries.pyscript11.4 KB
tests/test_fetch_sdk_docs.pyscript14.1 KB

scripts/detect_libraries.py

View on GitHub
#!/usr/bin/env python3
"""
Detect runtime classification, dependency surface, and any existing Monte
Carlo OpenTelemetry setup in a Python codebase.

The script is intentionally a thin discovery layer. It walks dependency
manifests (requirements.txt, pyproject.toml, Pipfile), serverless deployment
markers, and existing `mc.setup()` calls — then emits a JSON document the
skill consumes. The script does **not** classify AI libraries or pick
instrumentor packages; that is the LLM's job, working from `dependencies[]`
plus the live PyPI list from `fetch_sdk_docs.py`.

Usage:
    python3 detect_libraries.py [TARGET_PATH]

TARGET_PATH defaults to the current working directory. Output is JSON
on stdout. Exit code is 0 on success and 1 on hard errors (missing or
unreadable target path).
"""

from __future__ import annotations

import argparse
import ast
import json
import os
import re
import sys
from pathlib import Path
from typing import Iterable

# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------

MAX_FILE_BYTES = 5 * 1024 * 1024  # 5 MB per-file cap

SKIP_DIRS = {
    ".venv",
    "venv",
    "node_modules",
    "__pycache__",
    ".git",
    "dist",
    "build",
    "target",
    ".tox",
    ".pytest_cache",
    ".mypy_cache",
}

SERVERLESS_FILES = {
    "serverless.yml",
    "serverless.yaml",
    "template.yaml",
    "template.yml",
    "vercel.json",
    "netlify.toml",
    "wrangler.toml",
    "zappa_settings.json",
    "modal.toml",
}

SERVERLESS_DEPS = {
    "aws-lambda-powertools",
    "mangum",
    "chalice",
    "zappa",
    "aws-cdk-lib",
    "aws-sam-cli",
    "modal",
    "sst",
}

SERVERLESS_CODE_PATTERNS = [
    re.compile(r"def\s+lambda_handler\s*\("),
    re.compile(r"from\s+chalice\s+import\s+Chalice"),
    re.compile(r"from\s+mangum\s+import\s+Mangum"),
    re.compile(r"app\s*=\s*Chalice\s*\("),
]

# Existing-setup detection requires BOTH an import of montecarlo_opentelemetry
# AND an actual setup() call in the same file. Matching on imports alone
# false-positives any file that uses the SDK's decorators (e.g. handler.py
# importing `montecarlo_opentelemetry as mc` to use `@mc.trace_with_workflow`)
# but doesn't actually call setup().
EXISTING_SETUP_IMPORT_PATTERNS = [
    "import montecarlo_opentelemetry",
    "from montecarlo_opentelemetry",
]
EXISTING_SETUP_FALLBACK_CALL_PATTERN = re.compile(
    r"\b(?:mc|montecarlo_opentelemetry)\.setup\s*\("
)


# ---------------------------------------------------------------------------
# TOML loader (stdlib tomllib in 3.11+, fall back to tomli, else None)
# ---------------------------------------------------------------------------


def _load_toml_module():
    try:
        import tomllib  # type: ignore[import-not-found]

        return tomllib
    except ImportError:
        pass
    try:
        import tomli  # type: ignore[import-not-found]

        return tomli
    except ImportError:
        return None


_TOML = _load_toml_module()


# ---------------------------------------------------------------------------
# Filesystem helpers
# ---------------------------------------------------------------------------


def _is_within(path: Path, root: Path) -> bool:
    """True if `path` (resolved) is inside `root` (resolved)."""
    try:
        resolved = path.resolve()
    except OSError:
        return False
    try:
        resolved.relative_to(root)
        return True
    except ValueError:
        return False


def _safe_read_text(path: Path) -> str | None:
    """Read a file as UTF-8 text, skipping if too large or unreadable."""
    try:
        size = path.stat().st_size
    except OSError as exc:
        print(f"warning: cannot stat {path}: {exc}", file=sys.stderr)
        return None
    if size > MAX_FILE_BYTES:
        print(
            f"warning: skipping {path} ({size} bytes exceeds {MAX_FILE_BYTES})",
            file=sys.stderr,
        )
        return None
    try:
        return path.read_text(encoding="utf-8", errors="replace")
    except OSError as exc:
        print(f"warning: cannot read {path}: {exc}", file=sys.stderr)
        return None


def _walk_files(root: Path) -> Iterable[Path]:
    """Yield files under root, skipping noise dirs and out-of-tree symlinks."""
    root_resolved = root.resolve()
    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
        # Filter directories in-place so os.walk doesn't descend into them.
        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]

        # Drop any dir that resolves outside the target tree (symlink escape).
        kept: list[str] = []
        for d in dirnames:
            full = Path(dirpath) / d
            if _is_within(full, root_resolved):
                kept.append(d)
        dirnames[:] = kept

        for name in filenames:
            full = Path(dirpath) / name
            if full.is_symlink() and not _is_within(full, root_resolved):
                continue
            yield full


# ---------------------------------------------------------------------------
# Dependency parsing
# ---------------------------------------------------------------------------

# PEP 508 / requirements line — captures the project name only.
# Allowed name characters per PEP 508: letters, digits, ., -, _
_REQ_NAME_RE = re.compile(r"^([A-Za-z0-9][A-Za-z0-9._-]*)")
_EGG_RE = re.compile(r"[#&]egg=([A-Za-z0-9][A-Za-z0-9._-]*)")


def _normalize_dep(name: str) -> str:
    return name.strip().lower()


def _parse_requirements_line(line: str) -> str | None:
    """Extract a package name from a single requirements.txt line, or None."""
    raw = line.strip()
    if not raw:
        return None
    # Strip inline comments — preserve URLs that contain '#egg=' first.
    if "#egg=" not in raw and "#" in raw:
        raw = raw.split("#", 1)[0].strip()
    if not raw:
        return None

    lowered = raw.lower()

    # Skip include directives and pip flags.
    if (
        lowered.startswith("-r ")
        or lowered.startswith("--requirement ")
        or lowered.startswith("-c ")
        or lowered.startswith("--constraint ")
        or lowered.startswith("--index-url")
        or lowered.startswith("--extra-index-url")
        or lowered.startswith("--find-links")
        or lowered.startswith("--no-")
        or lowered.startswith("--pre")
        or lowered.startswith("--trusted-host")
    ):
        return None

    # Editable / VCS / URL specs — name comes from #egg=<name>.
    # Note: bare "-e ./local_pkg" without #egg= yields no package name and is skipped.
    if (
        lowered.startswith("-e ")
        or lowered.startswith("--editable ")
        or lowered.startswith("git+")
        or lowered.startswith("hg+")
        or lowered.startswith("svn+")
        or lowered.startswith("bzr+")
        or lowered.startswith("http://")
        or lowered.startswith("https://")
        or lowered.startswith("file://")
    ):
        m = _EGG_RE.search(raw)
        return _normalize_dep(m.group(1)) if m else None

    # Drop any "[extras]" segment, then match the leading package name.
    bracket = raw.find("[")
    if bracket > 0:
        candidate = raw[:bracket]
    else:
        candidate = raw
    m = _REQ_NAME_RE.match(candidate)
    return _normalize_dep(m.group(1)) if m else None


def _parse_requirements_file(path: Path) -> list[str]:
    text = _safe_read_text(path)
    if text is None:
        return []
    deps: list[str] = []
    try:
        for line in text.splitlines():
            name = _parse_requirements_line(line)
            if name:
                deps.append(name)
    except Exception as exc:  # noqa: BLE001 — tolerate any parse glitch
        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
    return deps


def _pep508_name(spec: str) -> str | None:
    """Pull the project name from a PEP 508 requirement string."""
    candidate = spec.strip()
    if not candidate:
        return None
    bracket = candidate.find("[")
    if bracket > 0:
        candidate = candidate[:bracket]
    m = _REQ_NAME_RE.match(candidate)
    return _normalize_dep(m.group(1)) if m else None


def _parse_pyproject(path: Path) -> list[str]:
    if _TOML is None:
        print(
            f"warning: skipping {path} — no TOML parser available "
            "(install tomli or use Python 3.11+)",
            file=sys.stderr,
        )
        return []
    text = _safe_read_text(path)
    if text is None:
        return []
    try:
        data = _TOML.loads(text)
    except Exception as exc:  # noqa: BLE001
        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
        return []

    deps: list[str] = []

    # PEP 621: [project] dependencies + optional-dependencies.
    project = data.get("project") if isinstance(data, dict) else None
    if isinstance(project, dict):
        for spec in project.get("dependencies", []) or []:
            if isinstance(spec, str):
                name = _pep508_name(spec)
                if name:
                    deps.append(name)
        opt = project.get("optional-dependencies") or {}
        if isinstance(opt, dict):
            for group in opt.values():
                if not isinstance(group, list):
                    continue
                for spec in group:
                    if isinstance(spec, str):
                        name = _pep508_name(spec)
                        if name:
                            deps.append(name)

    # Poetry: [tool.poetry.dependencies] + [tool.poetry.group.<g>.dependencies]
    tool = data.get("tool") if isinstance(data, dict) else None
    poetry = tool.get("poetry") if isinstance(tool, dict) else None
    if isinstance(poetry, dict):
        poetry_deps = poetry.get("dependencies") or {}
        if isinstance(poetry_deps, dict):
            for name in poetry_deps.keys():
                if isinstance(name, str) and name.lower() != "python":
                    deps.append(_normalize_dep(name))
        groups = poetry.get("group") or {}
        if isinstance(groups, dict):
            for group in groups.values():
                if not isinstance(group, dict):
                    continue
                gdeps = group.get("dependencies") or {}
                if isinstance(gdeps, dict):
                    for name in gdeps.keys():
                        if isinstance(name, str) and name.lower() != "python":
                            deps.append(_normalize_dep(name))

    return deps


def _parse_pipfile(path: Path) -> list[str]:
    if _TOML is None:
        print(
            f"warning: skipping {path} — no TOML parser available "
            "(install tomli or use Python 3.11+)",
            file=sys.stderr,
        )
        return []
    text = _safe_read_text(path)
    if text is None:
        return []
    try:
        data = _TOML.loads(text)
    except Exception as exc:  # noqa: BLE001
        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
        return []

    deps: list[str] = []
    for section in ("packages", "dev-packages"):
        section_data = data.get(section) if isinstance(data, dict) else None
        if isinstance(section_data, dict):
            for name in section_data.keys():
                if isinstance(name, str):
                    deps.append(_normalize_dep(name))
    return deps


def _scan_tree(target: Path) -> dict:
    """Walk *target* once and bucket files by role.

    Returns a dict with:
    - ``dep_files``: paths to dependency manifests (requirements*.txt,
      pyproject.toml, Pipfile).
    - ``serverless_files``: paths whose filename matches SERVERLESS_FILES.
    - ``py_files``: paths to ``*.py`` source files.
    - ``py_contents``: ``{path: text}`` — eagerly read content of each Python
      file (None values are omitted; callers treat a missing key as unreadable).
    """
    dep_files: list[Path] = []
    serverless_files: list[Path] = []
    py_files: list[Path] = []
    py_contents: dict[Path, str] = {}

    serverless_names_lower = {n.lower() for n in SERVERLESS_FILES}

    for path in _walk_files(target):
        name = path.name
        lower = name.lower()
        suffix = path.suffix.lower()

        if lower == "requirements.txt" or (
            lower.startswith("requirements") and lower.endswith(".txt")
        ):
            dep_files.append(path)
        elif lower == "pyproject.toml":
            dep_files.append(path)
        elif lower == "pipfile":
            dep_files.append(path)

        if lower in serverless_names_lower:
            serverless_files.append(path)

        if suffix == ".py":
            py_files.append(path)
            text = _safe_read_text(path)
            if text is not None:
                py_contents[path] = text

    return {
        "dep_files": dep_files,
        "serverless_files": serverless_files,
        "py_files": py_files,
        "py_contents": py_contents,
    }


def _collect_dependencies(scan: dict) -> set[str]:
    """Collect normalized dep names from pre-scanned manifest files."""
    found: set[str] = set()
    for path in scan["dep_files"]:
        lower = path.name.lower()
        if lower == "requirements.txt" or (
            lower.startswith("requirements") and lower.endswith(".txt")
        ):
            found.update(_parse_requirements_file(path))
        elif lower == "pyproject.toml":
            found.update(_parse_pyproject(path))
        elif lower == "pipfile":
            found.update(_parse_pipfile(path))
    return found


# ---------------------------------------------------------------------------
# Runtime detection
# ---------------------------------------------------------------------------


def _detect_serverless(scan: dict, deps: set[str]) -> list[str]:
    """Return the list of serverless signals observed."""
    signals: list[str] = []

    # File-level markers — check anywhere in the walked tree; this catches
    # monorepo subprojects too.
    seen_files: set[str] = set()
    for path in scan["serverless_files"]:
        if path.name not in seen_files:
            signals.append(path.name)
            seen_files.add(path.name)

    # Dependency markers.
    for dep in sorted(deps):
        if dep in SERVERLESS_DEPS:
            signals.append(dep)

    # Code patterns — only meaningful tokens, not which file they came from.
    code_signals: set[str] = set()
    code_signal_labels = {
        SERVERLESS_CODE_PATTERNS[0]: "lambda_handler",
        SERVERLESS_CODE_PATTERNS[1]: "chalice_import",
        SERVERLESS_CODE_PATTERNS[2]: "mangum_import",
        SERVERLESS_CODE_PATTERNS[3]: "chalice_app",
    }
    py_contents = scan["py_contents"]
    for path in scan["py_files"]:
        text = py_contents.get(path)
        if text is None:
            continue
        for pattern, label in code_signal_labels.items():
            if label in code_signals:
                continue
            if pattern.search(text):
                code_signals.add(label)
        if len(code_signals) == len(code_signal_labels):
            break
    signals.extend(sorted(code_signals))

    return signals


# ---------------------------------------------------------------------------
# Existing setup detection
# ---------------------------------------------------------------------------


def _has_existing_setup_call(text: str) -> bool:
    try:
        tree = ast.parse(text)
    except SyntaxError:
        has_import = any(pat in text for pat in EXISTING_SETUP_IMPORT_PATTERNS)
        return has_import and bool(EXISTING_SETUP_FALLBACK_CALL_PATTERN.search(text))

    module_aliases: set[str] = set()
    setup_names: set[str] = set()

    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                if alias.name == "montecarlo_opentelemetry":
                    module_aliases.add(alias.asname or alias.name)
        elif isinstance(node, ast.ImportFrom):
            if node.module != "montecarlo_opentelemetry":
                continue
            for alias in node.names:
                if alias.name == "setup":
                    setup_names.add(alias.asname or alias.name)
                elif alias.name == "*":
                    setup_names.add("setup")

    if not module_aliases and not setup_names:
        return False

    for node in ast.walk(tree):
        if not isinstance(node, ast.Call):
            continue
        func = node.func
        if (
            isinstance(func, ast.Attribute)
            and func.attr == "setup"
            and isinstance(func.value, ast.Name)
            and func.value.id in module_aliases
        ):
            return True
        if isinstance(func, ast.Name) and func.id in setup_names:
            return True

    return False


def _detect_existing_setup(scan: dict, target: Path) -> dict:
    files: list[str] = []
    target_resolved = target.resolve()
    py_contents = scan["py_contents"]
    for path in scan["py_files"]:
        text = py_contents.get(path)
        if text is None:
            continue
        if not _has_existing_setup_call(text):
            continue
        try:
            rel = path.resolve().relative_to(target_resolved)
            files.append(str(rel))
        except ValueError:
            files.append(str(path))
    files.sort()
    return {"found": bool(files), "files": files}


# ---------------------------------------------------------------------------
# Entry point
# ---------------------------------------------------------------------------


def detect(target: Path) -> dict:
    scan = _scan_tree(target)
    deps = _collect_dependencies(scan)

    serverless_signals = _detect_serverless(scan, deps)
    if serverless_signals:
        runtime = "serverless"
    elif scan["dep_files"]:
        runtime = "long_running"
    else:
        runtime = "unknown"

    existing_setup = _detect_existing_setup(scan, target)

    return {
        "dependencies": sorted(deps),
        "runtime": runtime,
        "serverless_signals": serverless_signals,
        "existing_setup": existing_setup,
    }


def main() -> None:
    parser = argparse.ArgumentParser(
        description=(
            "Detect runtime style, Python dependencies, and any existing "
            "Monte Carlo OpenTelemetry setup in a codebase. AI-library "
            "matching is the LLM's job; this script just emits the raw "
            "discovery surface."
        )
    )
    parser.add_argument(
        "target",
        nargs="?",
        default=".",
        help="Path to the codebase to scan (defaults to the current directory).",
    )
    args = parser.parse_args()

    target = Path(args.target)
    if not target.exists():
        print(
            json.dumps({"error": f"Target path does not exist: {target}"}, indent=2)
        )
        sys.exit(1)
    if not target.is_dir():
        print(
            json.dumps({"error": f"Target path is not a directory: {target}"}, indent=2)
        )
        sys.exit(1)
    if not os.access(target, os.R_OK):
        print(
            json.dumps({"error": f"Target path is not readable: {target}"}, indent=2)
        )
        sys.exit(1)

    try:
        result = detect(target)
    except OSError as exc:
        print(json.dumps({"error": f"Filesystem error: {exc}"}, indent=2))
        sys.exit(1)

    print(json.dumps(result, indent=2))


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall