botanu 0.1.dev60__py3-none-any.whl

botanu/__init__.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Botanu SDK - OpenTelemetry-native cost attribution for AI workflows.
+
+Quick Start::
+
+    from botanu import enable, botanu_workflow, emit_outcome
+
+    enable()  # reads config from OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT env vars
+
+    @botanu_workflow(name="Customer Support")
+    async def handle_request(data):
+        result = await process(data)
+        emit_outcome("success", value_type="tickets_resolved", value_amount=1)
+        return result
+"""
+
+from __future__ import annotations
+
+from botanu._version import __version__
+
+# Run context model
+from botanu.models.run_context import RunContext, RunOutcome, RunStatus
+
+# Bootstrap
+from botanu.sdk.bootstrap import (
+    disable,
+    enable,
+    is_enabled,
+)
+
+# Configuration
+from botanu.sdk.config import BotanuConfig
+
+# Context helpers  (core — no SDK dependency)
+from botanu.sdk.context import (
+    get_baggage,
+    get_current_span,
+    get_run_id,
+    get_workflow,
+    set_baggage,
+)
+
+# Decorators  (primary integration point)
+from botanu.sdk.decorators import botanu_workflow, run_botanu, workflow
+
+# Span helpers
+from botanu.sdk.span_helpers import emit_outcome, set_business_context
+
+__all__ = [
+    "__version__",
+    # Bootstrap
+    "enable",
+    "disable",
+    "is_enabled",
+    # Configuration
+    "BotanuConfig",
+    # Decorators / context managers
+    "botanu_workflow",
+    "run_botanu",
+    "workflow",
+    # Span helpers
+    "emit_outcome",
+    "set_business_context",
+    "get_current_span",
+    # Context
+    "get_run_id",
+    "get_workflow",
+    "set_baggage",
+    "get_baggage",
+    # Run context
+    "RunContext",
+    "RunStatus",
+    "RunOutcome",
+]

botanu/_version.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Dynamic version from package metadata (set by hatch-vcs at build time)."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version
+
+    __version__: str = version("botanu")
+except Exception:
+    __version__ = "0.0.0.dev0"

botanu/integrations/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Botanu integrations with third-party libraries."""

botanu/integrations/tenacity.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tenacity retry integration — automatic attempt tracking for LLM calls.
+
+Stamps ``botanu.request.attempt`` on every span created inside a tenacity
+retry loop so the collector and cost engine can see how many attempts an
+event required.
+
+Usage::
+
+    from tenacity import retry, stop_after_attempt, wait_exponential
+    from botanu.integrations.tenacity import botanu_before, botanu_after_all
+    from botanu.tracking.llm import track_llm_call
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(min=1, max=10),
+        before=botanu_before,
+        after=botanu_after_all,   # optional — resets attempt counter
+    )
+    def call_llm():
+        with track_llm_call("openai", "gpt-4") as tracker:
+            response = openai.chat.completions.create(...)
+            tracker.set_tokens(
+                input_tokens=response.usage.prompt_tokens,
+                output_tokens=response.usage.completion_tokens,
+            )
+            return response
+
+The ``track_llm_call`` context manager reads the attempt number
+automatically — no need to call ``tracker.set_attempt()`` manually.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from botanu.tracking.llm import _retry_attempt
+
+
+def botanu_before(retry_state: Any) -> None:
+    """Tenacity ``before`` callback — sets the current attempt number.
+
+    Use as ``@retry(before=botanu_before)`` so that every
+    ``track_llm_call`` inside the retried function automatically
+    gets the correct attempt number on its span.
+    """
+    _retry_attempt.set(retry_state.attempt_number)
+
+
+def botanu_after_all(retry_state: Any) -> None:
+    """Tenacity ``after`` callback — resets the attempt counter.
+
+    Optional but recommended. Prevents a stale attempt number from
+    leaking into subsequent non-retried calls on the same thread.
+
+    Use as ``@retry(after=botanu_after_all)``.
+    """
+    _retry_attempt.set(0)

botanu/models/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Botanu data models."""
+
+from __future__ import annotations
+
+from botanu.models.run_context import RunContext, RunOutcome, RunStatus
+
+__all__ = ["RunContext", "RunOutcome", "RunStatus"]

botanu/models/run_context.py

@@ -0,0 +1,328 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Run Context - The core data model for Botanu runs.
+
+A "Run" is orthogonal to tracing:
+- Trace context (W3C): ties distributed spans together (trace_id, span_id)
+- Run context (Botanu): ties business execution together (run_id, workflow, outcome)
+
+Invariant: A run can span multiple traces (retries, async fanout).
+The run_id must remain stable across those boundaries.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Dict, Optional, Union
+
+
+def generate_run_id() -> str:
+    """Generate a UUIDv7-style sortable run ID.
+
+    UUIDv7 provides:
+    - Sortable by time (first 48 bits are millisecond timestamp)
+    - Globally unique
+    - Compatible with UUID format
+
+    Uses ``os.urandom()`` for ~2x faster generation than ``secrets``.
+    """
+    timestamp_ms = int(time.time() * 1000)
+
+    uuid_bytes = bytearray(16)
+    uuid_bytes[0] = (timestamp_ms >> 40) & 0xFF
+    uuid_bytes[1] = (timestamp_ms >> 32) & 0xFF
+    uuid_bytes[2] = (timestamp_ms >> 24) & 0xFF
+    uuid_bytes[3] = (timestamp_ms >> 16) & 0xFF
+    uuid_bytes[4] = (timestamp_ms >> 8) & 0xFF
+    uuid_bytes[5] = timestamp_ms & 0xFF
+
+    random_bytes = os.urandom(10)
+    uuid_bytes[6] = 0x70 | (random_bytes[0] & 0x0F)
+    uuid_bytes[7] = random_bytes[1]
+    uuid_bytes[8] = 0x80 | (random_bytes[2] & 0x3F)
+    uuid_bytes[9:16] = random_bytes[3:10]
+
+    hex_str = uuid_bytes.hex()
+    return f"{hex_str[:8]}-{hex_str[8:12]}-{hex_str[12:16]}-{hex_str[16:20]}-{hex_str[20:]}"
+
+
+class RunStatus(str, Enum):
+    """Run outcome status."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PARTIAL = "partial"
+    TIMEOUT = "timeout"
+    CANCELED = "canceled"
+
+
+@dataclass
+class RunOutcome:
+    """Outcome attached at run completion."""
+
+    status: RunStatus
+    reason_code: Optional[str] = None
+    error_class: Optional[str] = None
+    value_type: Optional[str] = None
+    value_amount: Optional[float] = None
+    confidence: Optional[float] = None
+
+
+@dataclass
+class RunContext:
+    """Canonical run context data model.
+
+    Propagated via W3C Baggage and stored as span attributes.
+
+    Retry model:
+        Each attempt gets a NEW run_id for clean cost accounting.
+        ``root_run_id`` stays stable across all attempts.
+    """
+
+    run_id: str
+    workflow: str
+    event_id: str
+    customer_id: str
+    environment: str
+    workflow_version: Optional[str] = None
+    tenant_id: Optional[str] = None
+    parent_run_id: Optional[str] = None
+    root_run_id: Optional[str] = None
+    attempt: int = 1
+    retry_of_run_id: Optional[str] = None
+    start_time: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    deadline: Optional[float] = None
+    cancelled: bool = False
+    cancelled_at: Optional[float] = None
+    outcome: Optional[RunOutcome] = None
+
+    def __post_init__(self) -> None:
+        if self.root_run_id is None:
+            object.__setattr__(self, "root_run_id", self.run_id)
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def create(
+        cls,
+        workflow: str,
+        event_id: str,
+        customer_id: str,
+        workflow_version: Optional[str] = None,
+        environment: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        parent_run_id: Optional[str] = None,
+        root_run_id: Optional[str] = None,
+        attempt: int = 1,
+        retry_of_run_id: Optional[str] = None,
+        deadline_seconds: Optional[float] = None,
+    ) -> RunContext:
+        """Create a new RunContext with auto-generated run_id."""
+        env = environment or os.getenv("BOTANU_ENVIRONMENT") or os.getenv("DEPLOYMENT_ENVIRONMENT") or "production"
+        run_id = generate_run_id()
+        deadline = None
+        if deadline_seconds is not None:
+            deadline = time.time() + deadline_seconds
+
+        return cls(
+            run_id=run_id,
+            workflow=workflow,
+            event_id=event_id,
+            customer_id=customer_id,
+            environment=env,
+            workflow_version=workflow_version,
+            tenant_id=tenant_id,
+            parent_run_id=parent_run_id,
+            root_run_id=root_run_id or run_id,
+            attempt=attempt,
+            retry_of_run_id=retry_of_run_id,
+            deadline=deadline,
+        )
+
+    @classmethod
+    def create_retry(cls, previous: RunContext) -> RunContext:
+        """Create a new RunContext for a retry attempt."""
+        return cls.create(
+            workflow=previous.workflow,
+            event_id=previous.event_id,
+            customer_id=previous.customer_id,
+            workflow_version=previous.workflow_version,
+            environment=previous.environment,
+            tenant_id=previous.tenant_id,
+            parent_run_id=previous.parent_run_id,
+            root_run_id=previous.root_run_id,
+            attempt=previous.attempt + 1,
+            retry_of_run_id=previous.run_id,
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def is_past_deadline(self) -> bool:
+        if self.deadline is None:
+            return False
+        return time.time() > self.deadline
+
+    def is_cancelled(self) -> bool:
+        return self.cancelled or self.is_past_deadline()
+
+    def request_cancellation(self, reason: str = "user") -> None:
+        self.cancelled = True
+        self.cancelled_at = time.time()
+
+    def remaining_time_seconds(self) -> Optional[float]:
+        if self.deadline is None:
+            return None
+        return max(0.0, self.deadline - time.time())
+
+    def complete(
+        self,
+        status: RunStatus,
+        reason_code: Optional[str] = None,
+        error_class: Optional[str] = None,
+        value_type: Optional[str] = None,
+        value_amount: Optional[float] = None,
+        confidence: Optional[float] = None,
+    ) -> None:
+        self.outcome = RunOutcome(
+            status=status,
+            reason_code=reason_code,
+            error_class=error_class,
+            value_type=value_type,
+            value_amount=value_amount,
+            confidence=confidence,
+        )
+
+    @property
+    def duration_ms(self) -> Optional[float]:
+        if self.outcome is None:
+            return None
+        return (datetime.now(timezone.utc) - self.start_time).total_seconds() * 1000
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def to_baggage_dict(self, lean_mode: Optional[bool] = None) -> Dict[str, str]:
+        """Convert to dict for W3C Baggage propagation."""
+        if lean_mode is None:
+            env_mode = os.getenv("BOTANU_PROPAGATION_MODE", "lean")
+            lean_mode = env_mode != "full"
+
+        baggage: Dict[str, str] = {
+            "botanu.run_id": self.run_id,
+            "botanu.workflow": self.workflow,
+            "botanu.event_id": self.event_id,
+            "botanu.customer_id": self.customer_id,
+        }
+        if lean_mode:
+            return baggage
+
+        baggage["botanu.environment"] = self.environment
+        if self.tenant_id:
+            baggage["botanu.tenant_id"] = self.tenant_id
+        if self.parent_run_id:
+            baggage["botanu.parent_run_id"] = self.parent_run_id
+        if self.root_run_id and self.root_run_id != self.run_id:
+            baggage["botanu.root_run_id"] = self.root_run_id
+        if self.attempt > 1:
+            baggage["botanu.attempt"] = str(self.attempt)
+        if self.retry_of_run_id:
+            baggage["botanu.retry_of_run_id"] = self.retry_of_run_id
+        if self.deadline is not None:
+            baggage["botanu.deadline"] = str(int(self.deadline * 1000))
+        if self.cancelled:
+            baggage["botanu.cancelled"] = "true"
+        return baggage
+
+    def to_span_attributes(self) -> Dict[str, Union[str, float, int, bool]]:
+        """Convert to dict for span attributes."""
+        attrs: Dict[str, Union[str, float, int, bool]] = {
+            "botanu.run_id": self.run_id,
+            "botanu.workflow": self.workflow,
+            "botanu.event_id": self.event_id,
+            "botanu.customer_id": self.customer_id,
+            "botanu.environment": self.environment,
+            "botanu.run.start_time": self.start_time.isoformat(),
+        }
+        if self.workflow_version:
+            attrs["botanu.workflow.version"] = self.workflow_version
+        if self.tenant_id:
+            attrs["botanu.tenant_id"] = self.tenant_id
+        if self.parent_run_id:
+            attrs["botanu.parent_run_id"] = self.parent_run_id
+        attrs["botanu.root_run_id"] = self.root_run_id or self.run_id
+        attrs["botanu.attempt"] = self.attempt
+        if self.retry_of_run_id:
+            attrs["botanu.retry_of_run_id"] = self.retry_of_run_id
+        if self.deadline is not None:
+            attrs["botanu.run.deadline_ts"] = self.deadline
+        if self.cancelled:
+            attrs["botanu.run.cancelled"] = True
+            if self.cancelled_at:
+                attrs["botanu.run.cancelled_at"] = self.cancelled_at
+        if self.outcome:
+            attrs["botanu.outcome.status"] = self.outcome.status.value
+            if self.outcome.reason_code:
+                attrs["botanu.outcome.reason_code"] = self.outcome.reason_code
+            if self.outcome.error_class:
+                attrs["botanu.outcome.error_class"] = self.outcome.error_class
+            if self.outcome.value_type:
+                attrs["botanu.outcome.value_type"] = self.outcome.value_type
+            if self.outcome.value_amount is not None:
+                attrs["botanu.outcome.value_amount"] = self.outcome.value_amount
+            if self.outcome.confidence is not None:
+                attrs["botanu.outcome.confidence"] = self.outcome.confidence
+            if self.duration_ms is not None:
+                attrs["botanu.run.duration_ms"] = self.duration_ms
+        return attrs
+
+    @classmethod
+    def from_baggage(cls, baggage: Dict[str, str]) -> Optional[RunContext]:
+        """Reconstruct RunContext from baggage dict."""
+        run_id = baggage.get("botanu.run_id")
+        workflow = baggage.get("botanu.workflow")
+        if not run_id or not workflow:
+            return None
+
+        attempt_str = baggage.get("botanu.attempt", "1")
+        try:
+            attempt = int(attempt_str)
+        except ValueError:
+            attempt = 1
+
+        deadline: Optional[float] = None
+        deadline_str = baggage.get("botanu.deadline")
+        if deadline_str:
+            try:
+                deadline = float(deadline_str) / 1000.0
+            except ValueError:
+                pass
+
+        cancelled = baggage.get("botanu.cancelled", "").lower() == "true"
+
+        event_id = baggage.get("botanu.event_id", "")
+        customer_id = baggage.get("botanu.customer_id", "")
+
+        return cls(
+            run_id=run_id,
+            workflow=workflow,
+            event_id=event_id,
+            customer_id=customer_id,
+            environment=baggage.get("botanu.environment", "unknown"),
+            tenant_id=baggage.get("botanu.tenant_id"),
+            parent_run_id=baggage.get("botanu.parent_run_id"),
+            root_run_id=baggage.get("botanu.root_run_id") or run_id,
+            attempt=attempt,
+            retry_of_run_id=baggage.get("botanu.retry_of_run_id"),
+            deadline=deadline,
+            cancelled=cancelled,
+        )

botanu/processors/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Botanu span processors.
+
+Only :class:`RunContextEnricher` is needed in the SDK.
+All other processing should happen in the OTel Collector.
+"""
+
+from botanu.processors.enricher import RunContextEnricher
+
+__all__ = ["RunContextEnricher"]

botanu/processors/enricher.py

@@ -0,0 +1,84 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""RunContextEnricher — the only span processor needed in the SDK.
+
+Why this MUST be in SDK (not collector):
+- Baggage is process-local (not sent over the wire).
+- Only the SDK can read baggage and write it to span attributes.
+- The collector only sees spans after they're exported.
+
+All heavy processing should happen in the OTel Collector:
+- PII redaction → ``redactionprocessor``
+- Cardinality limits → ``attributesprocessor``
+- Vendor detection → ``transformprocessor``
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar, List, Optional
+
+from opentelemetry import baggage, context
+from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
+from opentelemetry.trace import Span
+
+logger = logging.getLogger(__name__)
+
+
+class RunContextEnricher(SpanProcessor):
+    """Enriches ALL spans with run context from baggage.
+
+    This ensures that every span (including auto-instrumented ones)
+    gets ``botanu.run_id``, ``botanu.workflow``, etc. attributes.
+
+    Without this processor, only the root ``botanu.run`` span would
+    have these attributes.
+
+    In ``lean_mode`` (default), only ``run_id`` and ``workflow`` are
+    propagated to minimise per-span overhead.
+    """
+
+    BAGGAGE_KEYS_FULL: ClassVar[List[str]] = [
+        "botanu.run_id",
+        "botanu.workflow",
+        "botanu.event_id",
+        "botanu.customer_id",
+        "botanu.environment",
+        "botanu.tenant_id",
+        "botanu.parent_run_id",
+    ]
+
+    BAGGAGE_KEYS_LEAN: ClassVar[List[str]] = [
+        "botanu.run_id",
+        "botanu.workflow",
+        "botanu.event_id",
+        "botanu.customer_id",
+    ]
+
+    def __init__(self, lean_mode: bool = True) -> None:
+        self._lean_mode = lean_mode
+        self._baggage_keys = self.BAGGAGE_KEYS_LEAN if lean_mode else self.BAGGAGE_KEYS_FULL
+
+    def on_start(
+        self,
+        span: Span,
+        parent_context: Optional[context.Context] = None,
+    ) -> None:
+        """Called when a span starts — enrich with run context from baggage."""
+        ctx = parent_context or context.get_current()
+
+        for key in self._baggage_keys:
+            value = baggage.get_baggage(key, ctx)
+            if value:
+                if not span.attributes or key not in span.attributes:
+                    span.set_attribute(key, value)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True

botanu/resources/__init__.py

@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Resource detection using official OTel community detectors.
+
+Instead of a custom reimplementation, we try to import the official
+OpenTelemetry resource detector packages.  Each one is a lightweight
+pip package that auto-detects environment attributes (K8s, AWS, GCP,
+Azure, container).  If a package isn't installed, we gracefully skip it.
+
+Install detectors for your environment::
+
+    pip install botanu[aws]       # AWS EC2/ECS/EKS/Lambda
+    pip install botanu[gcp]       # GCE/GKE/Cloud Run/Cloud Functions
+    pip install botanu[azure]     # Azure VMs/App Service/Functions
+    pip install botanu[cloud]     # All cloud detectors
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from typing import Any, Dict, List, Tuple
+
+logger = logging.getLogger(__name__)
+
+# (module_path, class_name) — tried in order.
+# Each entry corresponds to a pip package from opentelemetry-python-contrib.
+_DETECTOR_REGISTRY: List[Tuple[str, str]] = [
+    # Built-in (opentelemetry-sdk — always available)
+    ("opentelemetry.sdk.resources", "ProcessResourceDetector"),
+    # opentelemetry-resource-detector-aws
+    ("opentelemetry.resource.detector.aws.ec2", "AwsEc2ResourceDetector"),
+    ("opentelemetry.resource.detector.aws.ecs", "AwsEcsResourceDetector"),
+    ("opentelemetry.resource.detector.aws.eks", "AwsEksResourceDetector"),
+    ("opentelemetry.resource.detector.aws.lambda_", "AwsLambdaResourceDetector"),
+    # opentelemetry-resource-detector-gcp
+    ("opentelemetry.resource.detector.gcp", "GoogleCloudResourceDetector"),
+    # opentelemetry-resource-detector-azure
+    ("opentelemetry.resource.detector.azure.vm", "AzureVMResourceDetector"),
+    ("opentelemetry.resource.detector.azure.app_service", "AzureAppServiceResourceDetector"),
+    # opentelemetry-resource-detector-container
+    ("opentelemetry.resource.detector.container", "ContainerResourceDetector"),
+]
+
+
+def collect_detectors() -> list:
+    """Return instances of all importable OTel resource detectors.
+
+    Each detector implements ``opentelemetry.sdk.resources.ResourceDetector``.
+    Missing packages are silently skipped.
+    """
+    detectors: list = []
+    for module_path, class_name in _DETECTOR_REGISTRY:
+        try:
+            mod = importlib.import_module(module_path)
+            cls = getattr(mod, class_name)
+            detectors.append(cls())
+        except (ImportError, AttributeError):
+            pass
+
+    if detectors:
+        names = [type(d).__name__ for d in detectors]
+        logger.debug("Available resource detectors: %s", names)
+
+    return detectors
+
+
+def detect_resource_attrs() -> Dict[str, Any]:
+    """Detect environment attributes using available OTel detectors.
+
+    Returns a flat dict of resource attributes.  This is a convenience
+    wrapper for callers that just need a dict (like bootstrap.py).
+    """
+    attrs: Dict[str, Any] = {}
+    for detector in collect_detectors():
+        try:
+            resource = detector.detect()
+            attrs.update(dict(resource.attributes))
+        except Exception:
+            # Community detectors may raise on network timeouts, missing
+            # metadata endpoints, etc.  Never let detection break SDK init.
+            logger.debug("Resource detector %s failed", type(detector).__name__, exc_info=True)
+    return attrs
+
+
+__all__ = ["collect_detectors", "detect_resource_attrs"]