agenttel 0.3.0a1__py3-none-any.whl

agenttel/__init__.py

@@ -0,0 +1,13 @@
+"""AgentTel Python SDK — AI-native telemetry for Python services."""
+
+from agenttel.config import AgentTelConfig
+from agenttel.engine import AgentTelEngine
+from agenttel.processor import AgentTelSpanProcessor
+
+__all__ = [
+    "AgentTelConfig",
+    "AgentTelEngine",
+    "AgentTelSpanProcessor",
+]
+
+__version__ = "0.3.0-alpha"

agenttel/agent/__init__.py

@@ -0,0 +1,18 @@
+"""Agent interface for AgentTel (MCP server, health, identity, incident)."""
+
+from agenttel.agent.auth import (
+    AuthConfig,
+    ToolPermission,
+    ToolPermissionRegistry as AuthPermissionRegistry,
+)
+from agenttel.agent.health import ServiceHealthAggregator
+from agenttel.agent.identity import AgentIdentity, ToolPermissionRegistry
+
+__all__ = [
+    "AuthConfig",
+    "AuthPermissionRegistry",
+    "ServiceHealthAggregator",
+    "AgentIdentity",
+    "ToolPermission",
+    "ToolPermissionRegistry",
+]

agenttel/agent/auth.py

@@ -0,0 +1,134 @@
+"""API key authentication and role-based permissions for the MCP server.
+
+Opt-in: when no AuthConfig is provided, all checks are skipped
+and the server behaves as before (backward compatible).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable
+
+
+class ToolPermission(Enum):
+    """Permission levels for MCP tool access."""
+
+    READ = "read"
+    DIAGNOSE = "diagnose"
+    REMEDIATE = "remediate"
+    ADMIN = "admin"
+
+
+@dataclass
+class AgentIdentity:
+    """Identifies an authenticated agent making MCP requests."""
+
+    agent_id: str
+    role: str
+    session_id: str | None = None
+
+
+@dataclass
+class AuthConfig:
+    """Configuration for API key authentication.
+
+    Provide either a static api_keys map, a custom validate_key function,
+    or both. When both are provided, the static map is checked first.
+    """
+
+    api_keys: dict[str, AgentIdentity] | None = None
+    validate_key: Callable[[str], AgentIdentity | None] | None = None
+
+    def resolve_key(self, key: str) -> AgentIdentity | None:
+        """Resolve a bearer token to an agent identity.
+
+        Returns None if the key is invalid or not found.
+        """
+        trimmed = key.strip()
+        if not trimmed:
+            return None
+
+        if self.api_keys:
+            identity = self.api_keys.get(trimmed)
+            if identity is not None:
+                return identity
+
+        if self.validate_key:
+            return self.validate_key(trimmed)
+
+        return None
+
+
+# Default role-to-permission mappings
+_DEFAULT_ROLE_PERMISSIONS: dict[str, set[ToolPermission]] = {
+    "observer": {ToolPermission.READ},
+    "diagnostician": {ToolPermission.READ, ToolPermission.DIAGNOSE},
+    "remediator": {ToolPermission.READ, ToolPermission.DIAGNOSE, ToolPermission.REMEDIATE},
+    "admin": {ToolPermission.READ, ToolPermission.DIAGNOSE, ToolPermission.REMEDIATE, ToolPermission.ADMIN},
+}
+
+# Default tool-to-required-permission mappings
+_DEFAULT_TOOL_PERMISSIONS: dict[str, ToolPermission] = {
+    # READ tools
+    "get_service_health": ToolPermission.READ,
+    "get_operation_baselines": ToolPermission.READ,
+    "get_anomalies": ToolPermission.READ,
+    "get_slo_status": ToolPermission.READ,
+    "get_dependency_health": ToolPermission.READ,
+    "get_topology": ToolPermission.READ,
+    "get_incident_context": ToolPermission.READ,
+    "get_error_classification": ToolPermission.READ,
+    "get_deployment_info": ToolPermission.READ,
+    "get_slo_report": ToolPermission.READ,
+    "get_executive_summary": ToolPermission.READ,
+    "get_trend_analysis": ToolPermission.READ,
+    "get_playbook": ToolPermission.READ,
+    "get_session": ToolPermission.READ,
+    # DIAGNOSE tools
+    "verify_remediation_effect": ToolPermission.DIAGNOSE,
+    "create_session": ToolPermission.DIAGNOSE,
+    "add_session_entry": ToolPermission.DIAGNOSE,
+    "suggest_remediation": ToolPermission.DIAGNOSE,
+    "get_change_correlation": ToolPermission.DIAGNOSE,
+    # REMEDIATE tools
+    "execute_remediation": ToolPermission.REMEDIATE,
+    "list_remediation_actions": ToolPermission.REMEDIATE,
+}
+
+
+class ToolPermissionRegistry:
+    """Maps roles to granted permissions and tools to required permission levels.
+
+    Pre-populated with sensible defaults:
+        observer     -> [READ]
+        diagnostician -> [READ, DIAGNOSE]
+        remediator   -> [READ, DIAGNOSE, REMEDIATE]
+        admin        -> [READ, DIAGNOSE, REMEDIATE, ADMIN]
+    """
+
+    def __init__(self) -> None:
+        self._role_permissions: dict[str, set[ToolPermission]] = {
+            k: set(v) for k, v in _DEFAULT_ROLE_PERMISSIONS.items()
+        }
+        self._tool_permissions: dict[str, ToolPermission] = dict(_DEFAULT_TOOL_PERMISSIONS)
+
+    def set_role_permissions(self, role: str, perms: list[ToolPermission]) -> None:
+        """Set the permissions granted to a role, replacing any existing mapping."""
+        self._role_permissions[role.lower()] = set(perms)
+
+    def set_tool_permission(self, tool_name: str, perm: ToolPermission) -> None:
+        """Set the required permission level for a specific tool."""
+        self._tool_permissions[tool_name] = perm
+
+    def is_allowed(self, identity: AgentIdentity, tool_name: str) -> bool:
+        """Check whether the given identity has permission to invoke the named tool.
+
+        Unknown tools default to READ. Unknown roles get observer permissions.
+        """
+        role = identity.role.lower()
+        granted = self._role_permissions.get(
+            role, self._role_permissions.get("observer", {ToolPermission.READ})
+        )
+        required = self._tool_permissions.get(tool_name, ToolPermission.READ)
+        return required in granted

agenttel/agent/context.py

@@ -0,0 +1,86 @@
+"""Agent context provider for LLM consumption."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agenttel.agent.health import ServiceHealthAggregator
+from agenttel.anomaly.detector import AnomalyDetector
+from agenttel.baseline.composite import CompositeBaselineProvider
+from agenttel.causality.tracker import CausalityTracker
+from agenttel.slo.tracker import SloTracker
+from agenttel.topology.registry import TopologyRegistry
+
+
+class AgentContextProvider:
+    """Provides structured context for AI agent consumption."""
+
+    def __init__(
+        self,
+        topology: TopologyRegistry,
+        health_aggregator: ServiceHealthAggregator,
+        baseline_provider: CompositeBaselineProvider,
+        anomaly_detector: AnomalyDetector,
+        slo_tracker: SloTracker,
+        causality_tracker: CausalityTracker,
+    ) -> None:
+        self._topology = topology
+        self._health = health_aggregator
+        self._baselines = baseline_provider
+        self._anomaly = anomaly_detector
+        self._slo = slo_tracker
+        self._causality = causality_tracker
+
+    def get_full_context(self) -> dict[str, Any]:
+        """Get full service context for incident diagnosis."""
+        summary = self._health.get_summary()
+        return {
+            "service": {
+                "name": summary.service_name,
+                "status": summary.status,
+                "team": self._topology.team,
+                "tier": self._topology.tier,
+                "domain": self._topology.domain,
+                "on_call_channel": self._topology.on_call_channel,
+            },
+            "operations": [
+                {
+                    "name": op.operation_name,
+                    "request_count": op.request_count,
+                    "error_count": op.error_count,
+                    "error_rate": op.error_count / op.request_count
+                    if op.request_count > 0
+                    else 0,
+                    "latency_p50_ms": op.latency_p50_ms,
+                    "latency_p99_ms": op.latency_p99_ms,
+                }
+                for op in summary.operations
+            ],
+            "dependencies": [
+                {
+                    "name": d.name,
+                    "type": d.type.value,
+                    "criticality": d.criticality.value,
+                    "state": d.state.value,
+                    "latency_ms": d.latency_ms,
+                    "error_rate": d.error_rate,
+                }
+                for d in summary.dependencies
+            ],
+            "slo_statuses": [
+                {
+                    "name": s.name,
+                    "target": s.target,
+                    "budget_remaining": s.budget_remaining,
+                    "burn_rate": s.burn_rate,
+                    "alert_level": s.alert_level.value,
+                }
+                for s in self._slo.get_all_statuses()
+            ],
+            "causality": None,
+        }
+
+        # Add causal chain if available
+        chain = self._causality.build_causal_chain()
+        if chain:
+            pass

agenttel/agent/health.py

@@ -0,0 +1,142 @@
+"""Service health aggregation from span data."""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+
+from agenttel.enums import DependencyState
+from agenttel.models import (
+    DependencyHealth,
+    OperationStats,
+    ServiceHealthSummary,
+)
+
+
+class ServiceHealthAggregator:
+    """Aggregates per-operation and dependency health from span data.
+
+    Called from the SpanProcessor on_end callback.
+    """
+
+    def __init__(self, service_name: str = "", window_size: int = 1000) -> None:
+        self._service_name = service_name
+        self._window_size = window_size
+        self._lock = threading.Lock()
+
+        # Per-operation tracking
+        self._op_latencies: dict[str, deque[float]] = {}
+        self._op_request_count: dict[str, int] = {}
+        self._op_error_count: dict[str, int] = {}
+
+        # Dependency tracking
+        self._dep_health: dict[str, DependencyHealth] = {}
+
+    def record_operation(
+        self,
+        operation_name: str,
+        latency_ms: float,
+        is_error: bool = False,
+    ) -> None:
+        """Record an operation execution."""
+        with self._lock:
+            if operation_name not in self._op_latencies:
+                self._op_latencies[operation_name] = deque(maxlen=self._window_size)
+                self._op_request_count[operation_name] = 0
+                self._op_error_count[operation_name] = 0
+
+            self._op_latencies[operation_name].append(latency_ms)
+            self._op_request_count[operation_name] += 1
+            if is_error:
+                self._op_error_count[operation_name] += 1
+
+    def record_dependency_health(self, health: DependencyHealth) -> None:
+        """Update dependency health status."""
+        with self._lock:
+            self._dep_health[health.name] = health
+
+    def update_dependency_state(
+        self,
+        name: str,
+        state: DependencyState,
+        latency_ms: float = 0.0,
+        error_rate: float = 0.0,
+    ) -> None:
+        """Update a dependency's state."""
+        with self._lock:
+            existing = self._dep_health.get(name)
+            if existing:
+                existing.state = state
+                existing.latency_ms = latency_ms
+                existing.error_rate = error_rate
+                existing.last_check = time.time()
+
+    def get_summary(self) -> ServiceHealthSummary:
+        """Get the current service health summary."""
+        with self._lock:
+            operations = []
+            for op_name in self._op_latencies:
+                latencies = sorted(self._op_latencies[op_name])
+                n = len(latencies)
+                if n == 0:
+                    continue
+
+                mean = sum(latencies) / n
+                operations.append(
+                    OperationStats(
+                        operation_name=op_name,
+                        request_count=self._op_request_count.get(op_name, 0),
+                        error_count=self._op_error_count.get(op_name, 0),
+                        latency_p50_ms=_percentile(latencies, 0.50),
+                        latency_p95_ms=_percentile(latencies, 0.95),
+                        latency_p99_ms=_percentile(latencies, 0.99),
+                        latency_mean_ms=mean,
+                    )
+                )
+
+            dependencies = list(self._dep_health.values())
+
+            # Determine overall status
+            status = "HEALTHY"
+            has_errors = any(
+                op.error_count > op.request_count * 0.1
+                for op in operations
+                if op.request_count > 0
+            )
+            has_failing_deps = any(
+                d.state == DependencyState.FAILING for d in dependencies
+            )
+            if has_failing_deps or has_errors:
+                status = "CRITICAL"
+            elif any(d.state == DependencyState.DEGRADED for d in dependencies):
+                status = "DEGRADED"
+
+            return ServiceHealthSummary(
+                service_name=self._service_name,
+                status=status,
+                operations=operations,
+                dependencies=dependencies,
+            )
+
+    def reset(self) -> None:
+        """Reset all aggregated data."""
+        with self._lock:
+            self._op_latencies.clear()
+            self._op_request_count.clear()
+            self._op_error_count.clear()
+            self._dep_health.clear()
+
+
+def _percentile(sorted_data: list[float], p: float) -> float:
+    """Calculate percentile using linear interpolation."""
+    n = len(sorted_data)
+    if n == 0:
+        return 0.0
+    if n == 1:
+        return sorted_data[0]
+    idx = p * (n - 1)
+    lower = int(idx)
+    upper = min(lower + 1, n - 1)
+    frac = idx - lower
+    return sorted_data[lower] + frac * (sorted_data[upper] - sorted_data[lower])

agenttel/agent/identity.py

@@ -0,0 +1,104 @@
+"""Agent identity and permission management."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from agenttel.enums import AgentRole
+
+
+@dataclass
+class AgentIdentity:
+    """Represents an AI agent's identity for MCP access."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    role: AgentRole = AgentRole.OBSERVER
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    name: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_headers(cls, headers: dict[str, str]) -> AgentIdentity:
+        """Extract agent identity from HTTP request headers."""
+        return cls(
+            id=headers.get("x-agent-id", str(uuid.uuid4())),
+            role=AgentRole(headers.get("x-agent-role", "observer")),
+            session_id=headers.get("x-agent-session-id", str(uuid.uuid4())),
+            name=headers.get("x-agent-name", ""),
+        )
+
+
+# Default tool permissions per role
+_DEFAULT_PERMISSIONS: dict[AgentRole, set[str]] = {
+    AgentRole.OBSERVER: {
+        "get_service_health",
+        "get_operation_baselines",
+        "get_anomalies",
+        "get_slo_status",
+        "get_dependency_health",
+        "get_topology",
+        "get_error_classification",
+        "get_deployment_info",
+    },
+    AgentRole.DIAGNOSTICIAN: {
+        "get_service_health",
+        "get_operation_baselines",
+        "get_anomalies",
+        "get_slo_status",
+        "get_dependency_health",
+        "get_topology",
+        "get_incident_context",
+        "get_error_classification",
+        "get_deployment_info",
+        "get_change_correlation",
+        "get_slo_report",
+        "get_trend_analysis",
+        "get_executive_summary",
+        "suggest_remediation",
+    },
+    AgentRole.REMEDIATOR: {
+        "get_service_health",
+        "get_operation_baselines",
+        "get_anomalies",
+        "get_slo_status",
+        "get_dependency_health",
+        "get_topology",
+        "get_incident_context",
+        "get_error_classification",
+        "get_deployment_info",
+        "get_change_correlation",
+        "get_slo_report",
+        "get_trend_analysis",
+        "get_executive_summary",
+        "suggest_remediation",
+        "execute_remediation",
+    },
+    AgentRole.ADMIN: set(),  # Empty = all tools allowed
+}
+
+
+class ToolPermissionRegistry:
+    """Manages role-based tool access for MCP."""
+
+    def __init__(self) -> None:
+        self._permissions: dict[AgentRole, set[str]] = dict(_DEFAULT_PERMISSIONS)
+
+    def is_allowed(self, role: AgentRole, tool_name: str) -> bool:
+        """Check if a role has permission to use a tool."""
+        allowed = self._permissions.get(role)
+        if allowed is not None and len(allowed) == 0:
+            return True  # Empty set for admin = all allowed
+        return tool_name in (allowed or set())
+
+    def grant(self, role: AgentRole, tool_name: str) -> None:
+        """Grant a tool permission to a role."""
+        if role not in self._permissions:
+            self._permissions[role] = set()
+        self._permissions[role].add(tool_name)
+
+    def revoke(self, role: AgentRole, tool_name: str) -> None:
+        """Revoke a tool permission from a role."""
+        if role in self._permissions:
+            self._permissions[role].discard(tool_name)

agenttel/agent/incident.py

@@ -0,0 +1,146 @@
+"""Incident context builder for AI agent diagnosis."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from agenttel.agent.health import ServiceHealthAggregator
+from agenttel.causality.tracker import CausalityTracker
+from agenttel.models import AnomalyResult, SloStatus
+
+
+@dataclass
+class IncidentContext:
+    """Full incident context for AI agent consumption."""
+
+    service_name: str
+    status: str
+    timestamp: float = field(default_factory=time.time)
+    anomalies: list[dict[str, Any]] = field(default_factory=list)
+    slo_violations: list[dict[str, Any]] = field(default_factory=list)
+    failing_dependencies: list[str] = field(default_factory=list)
+    causal_chain: dict[str, Any] | None = None
+    recent_changes: list[dict[str, Any]] = field(default_factory=list)
+    suggested_actions: list[str] = field(default_factory=list)
+
+
+class IncidentContextBuilder:
+    """Builds comprehensive incident context from system state."""
+
+    def __init__(
+        self,
+        health_aggregator: ServiceHealthAggregator,
+        causality_tracker: CausalityTracker,
+    ) -> None:
+        self._health = health_aggregator
+        self._causality = causality_tracker
+
+    def build(
+        self,
+        anomalies: list[AnomalyResult] | None = None,
+        slo_statuses: list[SloStatus] | None = None,
+    ) -> IncidentContext:
+        """Build incident context from current state."""
+        summary = self._health.get_summary()
+
+        # Build anomaly list
+        anomaly_list = []
+        if anomalies:
+            for a in anomalies:
+                if a.is_anomaly:
+                    anomaly_list.append({
+                        "score": a.score,
+                        "z_score": a.z_score,
+                        "pattern": a.pattern.value if a.pattern else "unknown",
+                    })
+
+        # Build SLO violations
+        slo_violations = []
+        if slo_statuses:
+            for s in slo_statuses:
+                if s.alert_level.value != "ok":
+                    slo_violations.append({
+                        "name": s.name,
+                        "target": s.target,
+                        "budget_remaining": s.budget_remaining,
+                        "burn_rate": s.burn_rate,
+                        "alert_level": s.alert_level.value,
+                    })
+
+        # Get failing dependencies
+        failing = self._causality.get_failing_dependencies()
+
+        # Get causal chain
+        chain = self._causality.build_causal_chain()
+        causal_data = None
+        if chain:
+            causal_data = {
+                "root_cause": chain.root_cause,
+                "cause_category": chain.cause_category.value,
+                "affected_dependencies": chain.affected_dependencies,
+                "business_impact": chain.business_impact.value,
+                "impact_scope": chain.impact_scope.value,
+            }
+
+        return IncidentContext(
+            service_name=summary.service_name,
+            status=summary.status,
+            anomalies=anomaly_list,
+            slo_violations=slo_violations,
+            failing_dependencies=failing,
+            causal_chain=causal_data,
+        )
+
+
+class ContextFormatter:
+    """Formats incident context as structured text for LLM consumption."""
+
+    @staticmethod
+    def format_for_llm(context: IncidentContext) -> str:
+        """Format incident context as readable text for LLM."""
+        lines = [
+            f"# Incident Context: {context.service_name}",
+            f"Status: {context.status}",
+            f"Timestamp: {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(context.timestamp))}",
+            "",
+        ]
+
+        if context.anomalies:
+            lines.append("## Anomalies Detected")
+            for a in context.anomalies:
+                lines.append(f"- Pattern: {a['pattern']}, Score: {a['score']:.2f}, Z-Score: {a['z_score']:.2f}")
+            lines.append("")
+
+        if context.slo_violations:
+            lines.append("## SLO Violations")
+            for s in context.slo_violations:
+                lines.append(
+                    f"- {s['name']}: target={s['target']}, "
+                    f"budget_remaining={s['budget_remaining']:.1%}, "
+                    f"alert={s['alert_level']}"
+                )
+            lines.append("")
+
+        if context.failing_dependencies:
+            lines.append("## Failing Dependencies")
+            for dep in context.failing_dependencies:
+                lines.append(f"- {dep}")
+            lines.append("")
+
+        if context.causal_chain:
+            c = context.causal_chain
+            lines.append("## Causal Analysis")
+            lines.append(f"Root Cause: {c['root_cause']}")
+            lines.append(f"Category: {c['cause_category']}")
+            lines.append(f"Impact: {c['business_impact']} ({c['impact_scope']})")
+            lines.append(f"Affected: {', '.join(c['affected_dependencies'])}")
+            lines.append("")
+
+        if context.suggested_actions:
+            lines.append("## Suggested Actions")
+            for i, action in enumerate(context.suggested_actions, 1):
+                lines.append(f"{i}. {action}")
+
+        return "\n".join(lines)