aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/sentry/sentry.py

@@ -0,0 +1,267 @@
+"""This file contains the Sentry and OpenTelemetry configuration for GL Connectors SDK.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+import inspect
+import os
+from dataclasses import dataclass
+from typing import Any, Optional, Sequence
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from gl_observability.initializer import FastAPIConfig, SentryBackendConfig, TelemetryConfig, init_telemetry
+from gl_observability.traces.instrument.functions import FunctionsInstrumentor
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace.sampling import Decision, ParentBased, Sampler, SamplingResult, TraceIdRatioBased
+from opentelemetry.trace import Link, SpanKind
+from opentelemetry.trace.span import TraceState
+from opentelemetry.util.types import Attributes
+
+from aip_agents.agent import BaseAgent, LangChainAgent, LangGraphAgent
+from aip_agents.utils.logger import get_logger
+
+load_dotenv()
+
+
+logger = get_logger(__name__)
+
+SENTRY_DSN = os.getenv("SENTRY_DSN")
+SENTRY_ENVIRONMENT = os.getenv("SENTRY_ENVIRONMENT", "development")
+SENTRY_PROJECT = os.getenv("SENTRY_PROJECT")
+VERSION_NUMBER = os.getenv("VERSION_NUMBER", "0.0.0")
+BUILD_NUMBER = os.getenv("BUILD_NUMBER", "0")
+USE_OPENTELEMETRY = os.getenv("USE_OPENTELEMETRY", "true").lower() == "true"
+
+# Lazy import of GoogleADKAgent to avoid heavy dependencies when not needed.
+# This is initialized lazily by _get_classes_to_instrument() and can be
+# patched by tests for mocking purposes.
+CLASSES_TO_INSTRUMENT: list[type[Any]] | None = None
+
+
+def _is_optional_google_adk_import_error(error: ImportError) -> bool:
+    """Return True when the import failure is due to missing Google ADK extras."""
+    cause = error.__cause__
+    if isinstance(cause, ModuleNotFoundError) and cause.name and cause.name.startswith("google"):
+        return True
+
+    return "aip-agents[google]" in str(error) or "aip-agents[google-adk]" in str(error)
+
+
+def _get_classes_to_instrument() -> list[type[Any]]:
+    """Get the list of classes to instrument.
+
+    This lazily imports GoogleADKAgent only when telemetry is being set up,
+    avoiding the heavy Google ADK dependencies during module import.
+
+    Returns:
+        List of agent classes to instrument.
+    """
+    global CLASSES_TO_INSTRUMENT
+    if CLASSES_TO_INSTRUMENT is None:
+        classes_to_instrument = [
+            BaseAgent,
+            LangGraphAgent,
+            LangChainAgent,
+        ]
+
+        try:
+            from aip_agents.agent import GoogleADKAgent
+
+            classes_to_instrument.append(GoogleADKAgent)
+        except ImportError as e:
+            if _is_optional_google_adk_import_error(e):
+                logger.debug("Google ADK extra is not installed; skipping GoogleADKAgent instrumentation")
+            else:
+                raise
+
+        CLASSES_TO_INSTRUMENT = classes_to_instrument
+    return CLASSES_TO_INSTRUMENT
+
+
+def get_all_methods(cls: type) -> list:
+    """Get all methods from a class.
+
+    Args:
+        cls: The class to get methods from.
+
+    Returns:
+        list: A list of methods.
+    """
+    methods = []
+    for name, member in inspect.getmembers(cls):
+        if name.startswith("_"):
+            continue  # skip dunder and private
+        if inspect.isfunction(member) or inspect.ismethod(member) or inspect.iscoroutinefunction(member):
+            methods.append(member)
+    return methods
+
+
+def instrument_gl_functions() -> None:
+    """Instrument GL functions."""
+    agent_methods = []
+    for cls in _get_classes_to_instrument():
+        agent_methods.extend(get_all_methods(cls))
+    FunctionsInstrumentor().instrument(methods=agent_methods)
+
+
+@dataclass(frozen=True)
+class EndpointSamplingConfig:
+    """Immutable configuration for endpoint-based trace sampling.
+
+    Maps FastAPI route patterns to sampling rates. Routes not listed
+    use the default rate.
+
+    Attributes:
+        default_rate: Sampling rate for routes not in any set (0.0–1.0).
+        no_sample_routes: Routes that should never be sampled (rate 0.0).
+        no_sample_prefixes: Route prefixes dropped at rate 0.0. A prefix
+            ``/health-check`` matches ``/health-check`` and ``/health-check/*``
+            but not ``/health-checker``.
+        high_priority_routes: Routes sampled at 100% regardless of default.
+    """
+
+    default_rate: float = 1.0
+    no_sample_routes: frozenset[str] = frozenset()
+    no_sample_prefixes: frozenset[str] = frozenset()
+    high_priority_routes: frozenset[str] = frozenset()
+
+    def rate_for(self, route: str | None) -> float:
+        """Return the sampling rate for a given route.
+
+        Normalizes by stripping a trailing slash so variants such as
+        ``/health-check/`` still match the configured route sets/prefixes.
+        """
+        if route is None:
+            return self.default_rate
+        normalized = route.rstrip("/") or "/"
+        if normalized in self.no_sample_routes:
+            return 0.0
+        if any(normalized == prefix or normalized.startswith(prefix + "/") for prefix in self.no_sample_prefixes):
+            return 0.0
+        if normalized in self.high_priority_routes:
+            return 1.0
+        return self.default_rate
+
+
+class EndpointRouteSampler(Sampler):
+    """OpenTelemetry Sampler that varies sampling rate by FastAPI route.
+
+    Inspects the ``http.route`` span attribute and delegates to a
+    fresh ``ParentBased(TraceIdRatioBased(rate))`` per span, following
+    the GL Observability cookbook pattern.
+
+    Args:
+        config: Route-to-rate mapping configuration.
+    """
+
+    def __init__(self, config: EndpointSamplingConfig) -> None:
+        self._config = config
+
+    def should_sample(
+        self,
+        parent_context: Optional[Context],
+        trace_id: int,
+        name: str,
+        kind: SpanKind = None,
+        attributes: Attributes = None,
+        links: Sequence[Link] = None,
+        trace_state: TraceState = None,
+    ) -> SamplingResult:
+        """Compute a sampling decision, dropping configured no-sample routes.
+
+        ``http.route`` (set by FastAPI instrumentation) is preferred; when it
+        is absent on an incoming span, fall back to ``url.path`` and
+        ``http.target`` (stripping any query string) so health-check traces
+        are still filtered.
+        """
+        route = None
+        if attributes:
+            route = (
+                attributes.get("http.route")
+                or attributes.get("url.path")
+                or attributes.get("http.target")
+            )
+            if isinstance(route, str) and "?" in route:
+                route = route.split("?", 1)[0]
+        rate = self._config.rate_for(route)
+        sampler = ParentBased(TraceIdRatioBased(rate))
+        return sampler.should_sample(
+            parent_context, trace_id, name, kind, attributes, links, trace_state
+        )
+
+    def get_description(self) -> str:
+        """Return a human-readable description of this sampler."""
+        return f"EndpointRouteSampler(default={self._config.default_rate})"
+
+
+def _create_telemetry_config(app: FastAPI | None) -> TelemetryConfig:
+    """Build a telemetry configuration for Sentry-backed tracing.
+
+    Args:
+        app: Optional FastAPI application instance for instrumentation.
+
+    Returns:
+        TelemetryConfig instance for initializing telemetry.
+    """
+    backend_config = SentryBackendConfig(
+        dsn=SENTRY_DSN,
+        environment=SENTRY_ENVIRONMENT,
+        release=f"{SENTRY_PROJECT}@{VERSION_NUMBER}+{BUILD_NUMBER}",
+        send_default_pii=True,
+    )
+
+    fastapi_config = FastAPIConfig(app) if app is not None else None
+
+    sampling_config = EndpointSamplingConfig(
+        default_rate=1.0,
+        no_sample_prefixes=frozenset({"/health-check"}),
+    )
+
+    return TelemetryConfig(
+        trace_sampler=EndpointRouteSampler(sampling_config),
+        fastapi_config=fastapi_config,
+        use_langchain=True,
+        backend_config=backend_config,
+    )
+
+
+def setup_sentry_with_open_telemetry(app: FastAPI) -> None:
+    """Configure telemetry with both Sentry and OpenTelemetry.
+
+    Args:
+        app: FastAPI application instance
+    """
+    try:
+        telemetry_config = _create_telemetry_config(app)
+        init_telemetry(telemetry_config)
+        logger.info(f"Telemetry initialized with OpenTelemetry for environment: {SENTRY_ENVIRONMENT}")
+    except Exception as e:
+        logger.error(f"Failed to initialize telemetry with OpenTelemetry: {e}")
+
+
+def setup_sentry_only() -> None:
+    """Configure telemetry with Sentry only (no OpenTelemetry)."""
+    try:
+        telemetry_config = _create_telemetry_config(app=None)
+        init_telemetry(telemetry_config)
+        logger.info(f"Telemetry initialized with Sentry only for environment: {SENTRY_ENVIRONMENT}")
+    except Exception as e:
+        logger.error(f"Failed to initialize telemetry with Sentry only: {e}")
+
+
+def setup_telemetry(app: FastAPI) -> None:
+    """Configure and initialize telemetry based on configuration.
+
+    Args:
+        app: FastAPI application instance
+    """
+    if not SENTRY_DSN:
+        logger.warning("Warning: SENTRY_DSN not set. Sentry will not be enabled.")
+        return
+    if USE_OPENTELEMETRY:
+        setup_sentry_with_open_telemetry(app)
+    else:
+        setup_sentry_only()
+    instrument_gl_functions()

aip_agents/skills/__init__.py

@@ -0,0 +1,30 @@
+"""Skills support for AIP Agents (PR-001 foundation).
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from aip_agents.skills.errors import (
+    SkillError,
+    SkillExecutionError,
+    SkillInstallError,
+    SkillMetadataError,
+    SkillValidationError,
+)
+from aip_agents.skills.installer import SkillInstaller
+from aip_agents.skills.models import ResourceEntry, ResourceManifest, ResourceType, Skill
+
+__all__ = [
+    "SkillError",
+    "SkillInstallError",
+    "SkillMetadataError",
+    "SkillValidationError",
+    "SkillExecutionError",
+    "Skill",
+    "SkillInstaller",
+    "ResourceType",
+    "ResourceEntry",
+    "ResourceManifest",
+]

aip_agents/skills/errors.py

@@ -0,0 +1,110 @@
+"""Skill-related error types.
+
+These errors are intentionally small and human-readable since they are expected to
+surface to SDK users (e.g., during skill installation).
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+SkillSourceStatus = Literal[
+    "missing_dependency",
+    "auth_failure",
+    "invalid_url",
+    "unsupported_local_path",
+    "cache_unavailable",
+]
+
+
+class SkillSourceError(TypedDict):
+    """Structured skill source readiness failure."""
+
+    source: str
+    status: SkillSourceStatus
+    message: str
+    detail: str
+
+
+class SkillError(Exception):
+    """Base error for skill operations."""
+
+
+class SkillInstallError(SkillError):
+    """Raised when a skill cannot be installed (network/auth/archive errors)."""
+
+    def __init__(self, message: str, *, source_errors: list[SkillSourceError] | None = None) -> None:
+        """Create an install error with optional structured source failures."""
+        super().__init__(message)
+        self.source_errors = source_errors or []
+
+
+class SkillValidationError(SkillError):
+    """Raised when a local skill path is invalid (naming, missing files, etc.)."""
+
+
+class SkillMetadataError(SkillError):
+    """Raised when SKILL.md metadata is invalid.
+
+    PR-001 does not parse SKILL.md frontmatter, but later milestones will.
+    """
+
+
+class SkillExecutionError(ValueError):
+    """Raised when a skill execution request is invalid."""
+
+    def __init__(self, message: str, *, denial: dict[str, Any] | None = None) -> None:
+        """Create an execution error with optional structured denial details."""
+        super().__init__(message)
+        self.denial = denial or {}
+
+
+def _iter_causes(error: Exception) -> list[Exception]:
+    causes: list[Exception] = []
+    current: Exception | None = error
+    while current is not None:
+        causes.append(current)
+        current = current.__cause__ or current.__context__
+    return causes
+
+
+def _has_status_code(error: Exception, status_codes: set[int]) -> bool:
+    for cause in _iter_causes(error):
+        response = getattr(cause, "response", None)  # NOSONAR
+        status_code = getattr(response, "status_code", None)
+        if status_code in status_codes:
+            return True
+    return False
+
+
+def classify_skill_source_error(source: str, error: Exception) -> SkillSourceError:
+    """Classify a skill source failure into a structured readiness object."""
+    detail = str(error)
+    causes = _iter_causes(error)
+    messages = " ".join(str(cause) for cause in causes)
+
+    if any(isinstance(cause, ImportError) for cause in causes) or "gl-connectors-tools" in messages:
+        status: SkillSourceStatus = "missing_dependency"
+        message = "Skill installer dependency is missing."
+    elif _has_status_code(error, {401, 403}):
+        status = "auth_failure"
+        message = "Skill source could not be accessed with the current GitHub credentials."
+    elif _has_status_code(error, {404}) or isinstance(error, SkillValidationError) or "Unsupported GitHub" in messages:
+        status = "invalid_url"
+        message = "Skill source URL is invalid or does not point to a supported GitHub skill tree."
+    elif any(isinstance(cause, OSError) for cause in causes):
+        status = "cache_unavailable"
+        message = "Skill source cache or install destination is unavailable."
+    else:
+        status = "cache_unavailable"
+        message = "Skill source could not be installed or refreshed."
+
+    return {
+        "source": source,
+        "status": status,
+        "message": message,
+        "detail": detail,
+    }