agenttel 0.3.0a1__tar.gz

agenttel-0.3.0a1/.gitignore

@@ -0,0 +1,38 @@
+# Gradle
+.gradle/
+build/
+!gradle/wrapper/gradle-wrapper.jar
+
+# IDE
+.idea/
+*.iml
+.vscode/
+.settings/
+.classpath
+.project
+.factorypath
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MkDocs build output
+site/
+
+# Node.js
+node_modules/
+dist/
+
+# Python
+__pycache__/
+*.pyc
+*.py[cod]
+*.egg-info/
+*.egg
+.venv/
+.pytest_cache/
+
+# Secrets
+.env
+*.key
+*.pem

agenttel-0.3.0a1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: agenttel
+Version: 0.3.0a1
+Summary: AgentTel Python SDK — AI-native telemetry for Python services
+Author-email: AgentTel <engineering@agenttel.io>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: agent
+Requires-Dist: aiohttp>=3.9; extra == 'agent'
+Provides-Extra: all
+Requires-Dist: aiohttp>=3.9; extra == 'all'
+Requires-Dist: anthropic>=0.20; extra == 'all'
+Requires-Dist: boto3>=1.28; extra == 'all'
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.28; extra == 'bedrock'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == 'fastapi'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# AgentTel Python SDK
+
+AI-native telemetry SDK for Python services. Full feature parity with the JVM SDK — semantic attributes, baselines, anomaly detection, SLO tracking, GenAI instrumentation, agentic observability, and MCP agent interface.
+
+## Installation
+
+```bash
+pip install agenttel
+
+# With extras
+pip install agenttel[fastapi]       # FastAPI middleware + auto-config
+pip install agenttel[openai]        # OpenAI instrumentation
+pip install agenttel[anthropic]     # Anthropic instrumentation
+pip install agenttel[langchain]     # LangChain instrumentation
+pip install agenttel[bedrock]       # AWS Bedrock instrumentation
+pip install agenttel[agent]         # MCP server (aiohttp)
+pip install agenttel[all]           # Everything
+```
+
+## Quick Start (FastAPI)
+
+### 1. Create `agenttel.yml`
+
+```yaml
+agenttel:
+  enabled: true
+  topology:
+    team: payments
+    tier: critical
+    domain: fintech
+    on-call-channel: "#payments-oncall"
+  dependencies:
+    - name: postgres
+      type: database
+      criticality: required
+      timeout-ms: 3000
+    - name: stripe-api
+      type: external_api
+      criticality: degraded
+      timeout-ms: 5000
+      circuit-breaker: true
+  operations:
+    "[POST /api/transfers]":
+      profile: critical-write
+      expected-latency-p50: "80ms"
+      expected-latency-p99: "300ms"
+      expected-error-rate: 0.002
+      runbook-url: "https://wiki.example.com/runbooks/transfers"
+  profiles:
+    critical-write:
+      retryable: false
+      idempotent: false
+      escalation-level: page_oncall
+      safe-to-restart: false
+  baselines:
+    rolling-window-size: 1000
+    rolling-min-samples: 10
+  anomaly-detection:
+    enabled: true
+    z-score-threshold: 3.0
+```
+
+### 2. Instrument Your App
+
+```python
+from fastapi import FastAPI
+from agenttel.fastapi import instrument_fastapi
+
+app = FastAPI()
+engine = instrument_fastapi(app)
+
+@app.post("/api/transfers")
+async def create_transfer(request: dict):
+    # Your spans automatically get AgentTel enrichment:
+    # - topology attributes (team, tier, domain)
+    # - operation context (retryable, runbook, escalation)
+    # - baseline attributes (P50, P99, error rate)
+    # - anomaly detection on span end
+    # - SLO budget tracking
+    return {"status": "completed"}
+```
+
+### 3. Use the Decorator
+
+```python
+from agenttel.fastapi import agent_operation
+
+@app.get("/api/accounts/{account_id}")
+@agent_operation(
+    expected_latency_p50="10ms",
+    expected_latency_p99="50ms",
+    retryable=True,
+    runbook_url="https://wiki.example.com/runbooks/get-account",
+)
+async def get_account(account_id: str):
+    return {"id": account_id}
+```
+
+## GenAI Instrumentation
+
+```python
+from openai import OpenAI
+from agenttel.genai import instrument_openai
+
+client = instrument_openai(OpenAI())
+
+# All completions are now traced with:
+# - gen_ai.system, gen_ai.request.model
+# - gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
+# - agenttel.genai.cost_usd
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+Anthropic, LangChain, and AWS Bedrock are also supported:
+
+```python
+from anthropic import Anthropic
+from agenttel.genai import instrument_anthropic, instrument_langchain
+
+client = instrument_anthropic(Anthropic())
+instrument_langchain()  # Global LangChain instrumentation
+```
+
+## Agentic Observability
+
+```python
+from agenttel.agentic import AgentTracer
+from agenttel.enums import AgentType, StepType
+
+tracer = (AgentTracer.create()
+    .agent_name("incident-responder")
+    .agent_type(AgentType.SINGLE)
+    .framework("langchain")
+    .build())
+
+with tracer.invoke("diagnose high latency") as invocation:
+    with invocation.step(StepType.THOUGHT, "analyzing metrics"):
+        pass  # reasoning
+
+    with invocation.tool_call("get_service_health") as tool:
+        result = {"status": "degraded"}
+        tool.set_result(result)
+
+    with invocation.task("check dependencies") as task:
+        with task.step(StepType.ACTION, "querying deps"):
+            pass
+
+    invocation.complete(goal_achieved=True)
+```
+
+## Architecture
+
+```
+agenttel-python/
+├── src/agenttel/
+│   ├── attributes.py          # Semantic attribute constants
+│   ├── enums.py               # All enums (ServiceTier, ErrorCategory, etc.)
+│   ├── models.py              # Pydantic data models
+│   ├── config.py              # YAML config loader
+│   ├── processor.py           # OTel SpanProcessor
+│   ├── engine.py              # High-level orchestrator
+│   ├── baseline/              # Static, rolling, composite baselines
+│   ├── anomaly/               # Z-score anomaly detection + pattern matching
+│   ├── slo/                   # SLO tracking with error budgets
+│   ├── error/                 # Error classification
+│   ├── causality/             # Dependency state tracking
+│   ├── topology/              # Service topology registry
+│   ├── fastapi/               # FastAPI middleware + decorators
+│   ├── genai/                 # OpenAI, Anthropic, LangChain, Bedrock wrappers
+│   ├── agent/                 # MCP server, health aggregation, identity
+│   └── agentic/               # AgentTracer, scopes, orchestration patterns
+└── tests/
+```
+
+## Requirements
+
+- Python 3.11+
+- OpenTelemetry SDK 1.20+
+- Pydantic 2.0+

agenttel-0.3.0a1/README.md

@@ -0,0 +1,182 @@
+# AgentTel Python SDK
+
+AI-native telemetry SDK for Python services. Full feature parity with the JVM SDK — semantic attributes, baselines, anomaly detection, SLO tracking, GenAI instrumentation, agentic observability, and MCP agent interface.
+
+## Installation
+
+```bash
+pip install agenttel
+
+# With extras
+pip install agenttel[fastapi]       # FastAPI middleware + auto-config
+pip install agenttel[openai]        # OpenAI instrumentation
+pip install agenttel[anthropic]     # Anthropic instrumentation
+pip install agenttel[langchain]     # LangChain instrumentation
+pip install agenttel[bedrock]       # AWS Bedrock instrumentation
+pip install agenttel[agent]         # MCP server (aiohttp)
+pip install agenttel[all]           # Everything
+```
+
+## Quick Start (FastAPI)
+
+### 1. Create `agenttel.yml`
+
+```yaml
+agenttel:
+  enabled: true
+  topology:
+    team: payments
+    tier: critical
+    domain: fintech
+    on-call-channel: "#payments-oncall"
+  dependencies:
+    - name: postgres
+      type: database
+      criticality: required
+      timeout-ms: 3000
+    - name: stripe-api
+      type: external_api
+      criticality: degraded
+      timeout-ms: 5000
+      circuit-breaker: true
+  operations:
+    "[POST /api/transfers]":
+      profile: critical-write
+      expected-latency-p50: "80ms"
+      expected-latency-p99: "300ms"
+      expected-error-rate: 0.002
+      runbook-url: "https://wiki.example.com/runbooks/transfers"
+  profiles:
+    critical-write:
+      retryable: false
+      idempotent: false
+      escalation-level: page_oncall
+      safe-to-restart: false
+  baselines:
+    rolling-window-size: 1000
+    rolling-min-samples: 10
+  anomaly-detection:
+    enabled: true
+    z-score-threshold: 3.0
+```
+
+### 2. Instrument Your App
+
+```python
+from fastapi import FastAPI
+from agenttel.fastapi import instrument_fastapi
+
+app = FastAPI()
+engine = instrument_fastapi(app)
+
+@app.post("/api/transfers")
+async def create_transfer(request: dict):
+    # Your spans automatically get AgentTel enrichment:
+    # - topology attributes (team, tier, domain)
+    # - operation context (retryable, runbook, escalation)
+    # - baseline attributes (P50, P99, error rate)
+    # - anomaly detection on span end
+    # - SLO budget tracking
+    return {"status": "completed"}
+```
+
+### 3. Use the Decorator
+
+```python
+from agenttel.fastapi import agent_operation
+
+@app.get("/api/accounts/{account_id}")
+@agent_operation(
+    expected_latency_p50="10ms",
+    expected_latency_p99="50ms",
+    retryable=True,
+    runbook_url="https://wiki.example.com/runbooks/get-account",
+)
+async def get_account(account_id: str):
+    return {"id": account_id}
+```
+
+## GenAI Instrumentation
+
+```python
+from openai import OpenAI
+from agenttel.genai import instrument_openai
+
+client = instrument_openai(OpenAI())
+
+# All completions are now traced with:
+# - gen_ai.system, gen_ai.request.model
+# - gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
+# - agenttel.genai.cost_usd
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+Anthropic, LangChain, and AWS Bedrock are also supported:
+
+```python
+from anthropic import Anthropic
+from agenttel.genai import instrument_anthropic, instrument_langchain
+
+client = instrument_anthropic(Anthropic())
+instrument_langchain()  # Global LangChain instrumentation
+```
+
+## Agentic Observability
+
+```python
+from agenttel.agentic import AgentTracer
+from agenttel.enums import AgentType, StepType
+
+tracer = (AgentTracer.create()
+    .agent_name("incident-responder")
+    .agent_type(AgentType.SINGLE)
+    .framework("langchain")
+    .build())
+
+with tracer.invoke("diagnose high latency") as invocation:
+    with invocation.step(StepType.THOUGHT, "analyzing metrics"):
+        pass  # reasoning
+
+    with invocation.tool_call("get_service_health") as tool:
+        result = {"status": "degraded"}
+        tool.set_result(result)
+
+    with invocation.task("check dependencies") as task:
+        with task.step(StepType.ACTION, "querying deps"):
+            pass
+
+    invocation.complete(goal_achieved=True)
+```
+
+## Architecture
+
+```
+agenttel-python/
+├── src/agenttel/
+│   ├── attributes.py          # Semantic attribute constants
+│   ├── enums.py               # All enums (ServiceTier, ErrorCategory, etc.)
+│   ├── models.py              # Pydantic data models
+│   ├── config.py              # YAML config loader
+│   ├── processor.py           # OTel SpanProcessor
+│   ├── engine.py              # High-level orchestrator
+│   ├── baseline/              # Static, rolling, composite baselines
+│   ├── anomaly/               # Z-score anomaly detection + pattern matching
+│   ├── slo/                   # SLO tracking with error budgets
+│   ├── error/                 # Error classification
+│   ├── causality/             # Dependency state tracking
+│   ├── topology/              # Service topology registry
+│   ├── fastapi/               # FastAPI middleware + decorators
+│   ├── genai/                 # OpenAI, Anthropic, LangChain, Bedrock wrappers
+│   ├── agent/                 # MCP server, health aggregation, identity
+│   └── agentic/               # AgentTracer, scopes, orchestration patterns
+└── tests/
+```
+
+## Requirements
+
+- Python 3.11+
+- OpenTelemetry SDK 1.20+
+- Pydantic 2.0+

agenttel-0.3.0a1/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agenttel"
+version = "0.3.0a1"
+description = "AgentTel Python SDK — AI-native telemetry for Python services"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "AgentTel", email = "engineering@agenttel.io" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Framework :: FastAPI",
+]
+dependencies = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0", "opentelemetry-instrumentation-fastapi>=0.41b0"]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.20"]
+langchain = ["langchain-core>=0.1"]
+bedrock = ["boto3>=1.28"]
+agent = ["aiohttp>=3.9"]
+all = ["agenttel[fastapi,openai,anthropic,langchain,bedrock,agent]"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "httpx>=0.24",
+    "respx>=0.20",
+]
+
+[project.entry-points."opentelemetry_traces"]
+agenttel = "agenttel:AgentTelSpanProcessor"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agenttel"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

agenttel-0.3.0a1/src/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-0.3.0a1/src/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-0.3.0a1/src/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