botanu 0.1.dev60__py3-none-any.whl

botanu/sdk/decorators.py

@@ -0,0 +1,407 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Decorators for automatic run span creation and context propagation.
+
+The ``@botanu_workflow`` decorator is the primary integration point.
+It creates a "run span" that:
+- Generates a UUIDv7 run_id
+- Emits ``run.started`` and ``run.completed`` events
+- Propagates run context via W3C Baggage
+- Records outcome at completion
+"""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import hashlib
+import inspect
+from collections.abc import Mapping
+from contextlib import asynccontextmanager, contextmanager
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Generator, Optional, TypeVar, Union
+
+from opentelemetry import baggage as otel_baggage
+from opentelemetry import trace
+from opentelemetry.context import attach, detach, get_current
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+from botanu.models.run_context import RunContext, RunStatus
+from botanu.sdk.context import get_baggage
+
+T = TypeVar("T")
+
+tracer = trace.get_tracer("botanu_sdk")
+
+
+def _compute_workflow_version(func: Callable[..., Any]) -> str:
+    try:
+        source = inspect.getsource(func)
+        code_hash = hashlib.sha256(source.encode()).hexdigest()
+        return f"v:{code_hash[:12]}"
+    except (OSError, TypeError):
+        return "v:unknown"
+
+
+def _get_parent_run_id() -> Optional[str]:
+    return get_baggage("botanu.run_id")
+
+
+def botanu_workflow(
+    name: str,
+    *,
+    event_id: Union[str, Callable[..., str]],
+    customer_id: Union[str, Callable[..., str]],
+    environment: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    auto_outcome_on_success: bool = True,
+    span_kind: SpanKind = SpanKind.SERVER,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator to create a run span with automatic context propagation.
+
+    This is the primary integration point. It:
+
+    1. Creates a UUIDv7 ``run_id`` (sortable, globally unique)
+    2. Creates a ``botanu.run`` span as the root of the run
+    3. Emits ``run.started`` event
+    4. Propagates run context via W3C Baggage
+    5. On completion: emits ``run.completed`` event with outcome
+
+    Args:
+        name: Workflow name (low cardinality, e.g. ``"Customer Support"``).
+        event_id: Business unit of work (e.g. ticket ID). Required.
+            Can be a static string or a callable that receives the same
+            ``(*args, **kwargs)`` as the decorated function and returns a string.
+        customer_id: End-customer being served (e.g. org ID). Required.
+            Can be a static string or a callable (same signature as *event_id*).
+        environment: Deployment environment.
+        tenant_id: Tenant identifier for multi-tenant apps.
+        auto_outcome_on_success: Emit ``"success"`` if no exception.
+        span_kind: OpenTelemetry span kind (default: ``SERVER``).
+
+    Examples::
+
+        # Static values (known at decoration time):
+        @botanu_workflow("Support", event_id="ticket-123", customer_id="acme-corp")
+        async def handle_ticket(): ...
+
+        # Dynamic values (extracted from function arguments at call time):
+        @botanu_workflow(
+            "Support",
+            event_id=lambda request: request.workflow_id,
+            customer_id=lambda request: request.customer_id,
+        )
+        async def handle_ticket(request: TicketRequest): ...
+    """
+    if isinstance(event_id, str) and not event_id:
+        raise ValueError("event_id is required and must be a non-empty string")
+    if isinstance(customer_id, str) and not customer_id:
+        raise ValueError("customer_id is required and must be a non-empty string")
+    if not callable(event_id) and not isinstance(event_id, str):
+        raise ValueError("event_id must be a non-empty string or a callable")
+    if not callable(customer_id) and not isinstance(customer_id, str):
+        raise ValueError("customer_id must be a non-empty string or a callable")
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        workflow_version = _compute_workflow_version(func)
+        is_async = inspect.iscoroutinefunction(func)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
+            resolved_event_id = event_id(*args, **kwargs) if callable(event_id) else event_id
+            resolved_customer_id = customer_id(*args, **kwargs) if callable(customer_id) else customer_id
+            parent_run_id = _get_parent_run_id()
+            run_ctx = RunContext.create(
+                workflow=name,
+                event_id=resolved_event_id,
+                customer_id=resolved_customer_id,
+                workflow_version=workflow_version,
+                environment=environment,
+                tenant_id=tenant_id,
+                parent_run_id=parent_run_id,
+            )
+
+            with tracer.start_as_current_span(
+                name=f"botanu.run/{name}",
+                kind=span_kind,
+            ) as span:
+                for key, value in run_ctx.to_span_attributes().items():
+                    span.set_attribute(key, value)
+
+                span.add_event(
+                    "botanu.run.started",
+                    attributes={
+                        "run_id": run_ctx.run_id,
+                        "workflow": run_ctx.workflow,
+                    },
+                )
+
+                ctx = get_current()
+                for key, value in run_ctx.to_baggage_dict().items():
+                    ctx = otel_baggage.set_baggage(key, value, context=ctx)
+                baggage_token = attach(ctx)
+
+                try:
+                    result = await func(*args, **kwargs)
+
+                    span_attrs = getattr(span, "attributes", None)
+                    existing_outcome = (
+                        span_attrs.get("botanu.outcome.status") if isinstance(span_attrs, Mapping) else None
+                    )
+
+                    if existing_outcome is None and auto_outcome_on_success:
+                        run_ctx.complete(RunStatus.SUCCESS)
+
+                    span.set_status(Status(StatusCode.OK))
+                    _emit_run_completed(span, run_ctx, RunStatus.SUCCESS)
+                    return result
+
+                except Exception as exc:
+                    span.set_status(Status(StatusCode.ERROR, str(exc)))
+                    span.record_exception(exc)
+                    run_ctx.complete(RunStatus.FAILURE, error_class=exc.__class__.__name__)
+                    _emit_run_completed(
+                        span,
+                        run_ctx,
+                        RunStatus.FAILURE,
+                        error_class=exc.__class__.__name__,
+                    )
+                    raise
+                finally:
+                    detach(baggage_token)
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
+            resolved_event_id = event_id(*args, **kwargs) if callable(event_id) else event_id
+            resolved_customer_id = customer_id(*args, **kwargs) if callable(customer_id) else customer_id
+            parent_run_id = _get_parent_run_id()
+            run_ctx = RunContext.create(
+                workflow=name,
+                event_id=resolved_event_id,
+                customer_id=resolved_customer_id,
+                workflow_version=workflow_version,
+                environment=environment,
+                tenant_id=tenant_id,
+                parent_run_id=parent_run_id,
+            )
+
+            with tracer.start_as_current_span(
+                name=f"botanu.run/{name}",
+                kind=span_kind,
+            ) as span:
+                for key, value in run_ctx.to_span_attributes().items():
+                    span.set_attribute(key, value)
+
+                span.add_event(
+                    "botanu.run.started",
+                    attributes={
+                        "run_id": run_ctx.run_id,
+                        "workflow": run_ctx.workflow,
+                    },
+                )
+
+                ctx = get_current()
+                for key, value in run_ctx.to_baggage_dict().items():
+                    ctx = otel_baggage.set_baggage(key, value, context=ctx)
+                baggage_token = attach(ctx)
+
+                try:
+                    result = func(*args, **kwargs)
+
+                    span_attrs = getattr(span, "attributes", None)
+                    existing_outcome = (
+                        span_attrs.get("botanu.outcome.status") if isinstance(span_attrs, Mapping) else None
+                    )
+
+                    if existing_outcome is None and auto_outcome_on_success:
+                        run_ctx.complete(RunStatus.SUCCESS)
+
+                    span.set_status(Status(StatusCode.OK))
+                    _emit_run_completed(span, run_ctx, RunStatus.SUCCESS)
+                    return result
+
+                except Exception as exc:
+                    span.set_status(Status(StatusCode.ERROR, str(exc)))
+                    span.record_exception(exc)
+                    run_ctx.complete(RunStatus.FAILURE, error_class=exc.__class__.__name__)
+                    _emit_run_completed(
+                        span,
+                        run_ctx,
+                        RunStatus.FAILURE,
+                        error_class=exc.__class__.__name__,
+                    )
+                    raise
+                finally:
+                    detach(baggage_token)
+
+        if is_async:
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def _emit_run_completed(
+    span: trace.Span,
+    run_ctx: RunContext,
+    status: RunStatus,
+    error_class: Optional[str] = None,
+) -> None:
+    duration_ms = (datetime.now(timezone.utc) - run_ctx.start_time).total_seconds() * 1000
+
+    event_attrs: Dict[str, Union[str, float]] = {
+        "run_id": run_ctx.run_id,
+        "workflow": run_ctx.workflow,
+        "status": status.value,
+        "duration_ms": duration_ms,
+    }
+    if error_class:
+        event_attrs["error_class"] = error_class
+    if run_ctx.outcome and run_ctx.outcome.value_type:
+        event_attrs["value_type"] = run_ctx.outcome.value_type
+    if run_ctx.outcome and run_ctx.outcome.value_amount is not None:
+        event_attrs["value_amount"] = run_ctx.outcome.value_amount
+
+    span.add_event("botanu.run.completed", attributes=event_attrs)
+
+    span.set_attribute("botanu.outcome.status", status.value)
+    span.set_attribute("botanu.run.duration_ms", duration_ms)
+
+
+workflow = botanu_workflow
+
+
+def botanu_outcome(
+    success: Optional[str] = None,
+    partial: Optional[str] = None,
+    failed: Optional[str] = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator to automatically emit outcomes based on function result.
+
+    This is a convenience decorator for sub-functions within a workflow.
+    It does NOT create a new run — use ``@botanu_workflow`` for that.
+    """
+    from botanu.sdk.span_helpers import emit_outcome
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        is_async = inspect.iscoroutinefunction(func)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
+            try:
+                result = await func(*args, **kwargs)
+                span = trace.get_current_span()
+                if not span.attributes or "botanu.outcome.status" not in span.attributes:
+                    emit_outcome("success")
+                return result
+            except Exception as exc:
+                emit_outcome("failed", reason=exc.__class__.__name__)
+                raise
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
+            try:
+                result = func(*args, **kwargs)
+                span = trace.get_current_span()
+                if not span.attributes or "botanu.outcome.status" not in span.attributes:
+                    emit_outcome("success")
+                return result
+            except Exception as exc:
+                emit_outcome("failed", reason=exc.__class__.__name__)
+                raise
+
+        if is_async:
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+@contextmanager
+def run_botanu(
+    name: str,
+    *,
+    event_id: str,
+    customer_id: str,
+    environment: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    auto_outcome_on_success: bool = True,
+    span_kind: SpanKind = SpanKind.SERVER,
+) -> Generator[RunContext, None, None]:
+    """Context manager to create a run span — non-decorator alternative to ``@botanu_workflow``.
+
+    Use this when you can't decorate a function (dynamic workflows, simple scripts,
+    or when the workflow name is determined at runtime).
+
+    Args:
+        name: Workflow name (low cardinality, e.g. ``"Customer Support"``).
+        event_id: Business unit of work (e.g. ticket ID).
+        customer_id: End-customer being served (e.g. org ID).
+        environment: Deployment environment.
+        tenant_id: Tenant identifier for multi-tenant apps.
+        auto_outcome_on_success: Emit ``"success"`` if no exception.
+        span_kind: OpenTelemetry span kind (default: ``SERVER``).
+
+    Yields:
+        RunContext with the generated run_id and metadata.
+
+    Example::
+
+        with run_botanu("Support", event_id="ticket-42", customer_id="acme") as run:
+            result = call_llm(...)
+            emit_outcome("success", value_type="tickets_resolved", value_amount=1)
+    """
+    parent_run_id = _get_parent_run_id()
+    run_ctx = RunContext.create(
+        workflow=name,
+        event_id=event_id,
+        customer_id=customer_id,
+        environment=environment,
+        tenant_id=tenant_id,
+        parent_run_id=parent_run_id,
+    )
+
+    with tracer.start_as_current_span(
+        name=f"botanu.run/{name}",
+        kind=span_kind,
+    ) as span:
+        for key, value in run_ctx.to_span_attributes().items():
+            span.set_attribute(key, value)
+
+        span.add_event(
+            "botanu.run.started",
+            attributes={"run_id": run_ctx.run_id, "workflow": run_ctx.workflow},
+        )
+
+        ctx = get_current()
+        for key, value in run_ctx.to_baggage_dict().items():
+            ctx = otel_baggage.set_baggage(key, value, context=ctx)
+        baggage_token = attach(ctx)
+
+        try:
+            yield run_ctx
+
+            span_attrs = getattr(span, "attributes", None)
+            existing_outcome = (
+                span_attrs.get("botanu.outcome.status")
+                if isinstance(span_attrs, Mapping)
+                else None
+            )
+
+            if existing_outcome is None and auto_outcome_on_success:
+                run_ctx.complete(RunStatus.SUCCESS)
+
+            span.set_status(Status(StatusCode.OK))
+            _emit_run_completed(span, run_ctx, RunStatus.SUCCESS)
+
+        except Exception as exc:
+            span.set_status(Status(StatusCode.ERROR, str(exc)))
+            span.record_exception(exc)
+            run_ctx.complete(RunStatus.FAILURE, error_class=exc.__class__.__name__)
+            _emit_run_completed(
+                span, run_ctx, RunStatus.FAILURE, error_class=exc.__class__.__name__,
+            )
+            raise
+        finally:
+            detach(baggage_token)

botanu/sdk/middleware.py

@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""FastAPI / Starlette middleware for span enrichment.
+
+This middleware works alongside OpenTelemetry's FastAPIInstrumentor to enrich
+spans with Botanu-specific context.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Optional
+
+from opentelemetry import baggage as otel_baggage
+from opentelemetry import trace
+from opentelemetry.context import attach, detach, get_current
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class BotanuMiddleware(BaseHTTPMiddleware):
+    """FastAPI middleware to enrich spans with Botanu context.
+
+    This middleware should be used **after** OpenTelemetry's
+    ``FastAPIInstrumentor``.  It extracts Botanu context from incoming
+    requests and enriches the current span with Botanu attributes.
+
+    Example::
+
+        from fastapi import FastAPI
+        from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+        from botanu.sdk.middleware import BotanuMiddleware
+
+        app = FastAPI()
+        FastAPIInstrumentor.instrument_app(app)
+        app.add_middleware(
+            BotanuMiddleware,
+            workflow="customer_support",
+        )
+    """
+
+    def __init__(
+        self,
+        app: object,
+        *,
+        workflow: str,
+        auto_generate_run_id: bool = True,
+    ) -> None:
+        super().__init__(app)  # type: ignore[arg-type]
+        self.workflow = workflow
+        self.auto_generate_run_id = auto_generate_run_id
+
+    async def dispatch(self, request: Request, call_next: object) -> Response:  # type: ignore[override]
+        """Process request and enrich span with Botanu context."""
+        span = trace.get_current_span()
+
+        run_id = otel_baggage.get_baggage("botanu.run_id")
+        if not run_id:
+            run_id = request.headers.get("x-botanu-run-id")
+
+        if not run_id and self.auto_generate_run_id:
+            run_id = str(uuid.uuid4())
+
+        workflow = (
+            otel_baggage.get_baggage("botanu.workflow") or request.headers.get("x-botanu-workflow") or self.workflow
+        )
+        customer_id = otel_baggage.get_baggage("botanu.customer_id") or request.headers.get("x-botanu-customer-id")
+
+        if run_id:
+            span.set_attribute("botanu.run_id", run_id)
+        span.set_attribute("botanu.workflow", workflow)
+        if customer_id:
+            span.set_attribute("botanu.customer_id", customer_id)
+
+        span.set_attribute("http.route", request.url.path)
+        span.set_attribute("http.method", request.method)
+
+        ctx = get_current()
+        if run_id:
+            ctx = otel_baggage.set_baggage("botanu.run_id", run_id, context=ctx)
+        ctx = otel_baggage.set_baggage("botanu.workflow", workflow, context=ctx)
+        if customer_id:
+            ctx = otel_baggage.set_baggage("botanu.customer_id", customer_id, context=ctx)
+
+        baggage_token = attach(ctx)
+        try:
+            response = await call_next(request)  # type: ignore[misc]
+        finally:
+            detach(baggage_token)
+
+        if run_id:
+            response.headers["x-botanu-run-id"] = run_id
+        response.headers["x-botanu-workflow"] = workflow
+
+        return response

botanu/sdk/span_helpers.py

@@ -0,0 +1,143 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Helper functions for working with OpenTelemetry spans.
+
+These functions add Botanu-specific attributes to the current span.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from opentelemetry import trace
+
+from botanu.sdk.context import get_baggage
+
+logger = logging.getLogger(__name__)
+
+VALID_OUTCOME_STATUSES = {
+    "success", "partial", "failed", "timeout", "canceled", "abandoned",
+}
+
+
+def emit_outcome(
+    status: str,
+    *,
+    value_type: Optional[str] = None,
+    value_amount: Optional[float] = None,
+    confidence: Optional[float] = None,
+    reason: Optional[str] = None,
+    error_type: Optional[str] = None,
+    metadata: Optional[dict[str, str]] = None,
+) -> None:
+    """Emit an outcome for the current span.
+
+    Sets span attributes for outcome tracking and ROI calculation.
+    Also emits an OTel log record to trigger collector flush.
+
+    Args:
+        status: Outcome status. Must be one of ``"success"``, ``"partial"``,
+            ``"failed"``, ``"timeout"``, ``"canceled"``, ``"abandoned"``.
+        value_type: Type of business value (e.g., ``"tickets_resolved"``).
+        value_amount: Quantified value amount.
+        confidence: Confidence score (0.0–1.0).
+        reason: Optional reason for the outcome.
+        error_type: Error classification (e.g., ``"ValidationError"``).
+        metadata: Additional key-value metadata to attach to the outcome.
+
+    Raises:
+        ValueError: If *status* is not a recognised outcome status.
+
+    Example::
+
+        >>> emit_outcome("success", value_type="tickets_resolved", value_amount=1)
+        >>> emit_outcome("failed", error_type="TimeoutError", reason="LLM took >30s")
+    """
+    if status not in VALID_OUTCOME_STATUSES:
+        raise ValueError(
+            f"Invalid outcome status '{status}'. "
+            f"Must be one of: {', '.join(sorted(VALID_OUTCOME_STATUSES))}"
+        )
+
+    span = trace.get_current_span()
+
+    span.set_attribute("botanu.outcome.status", status)
+
+    if value_type:
+        span.set_attribute("botanu.outcome.value_type", value_type)
+
+    if value_amount is not None:
+        span.set_attribute("botanu.outcome.value_amount", value_amount)
+
+    if confidence is not None:
+        span.set_attribute("botanu.outcome.confidence", confidence)
+
+    if reason:
+        span.set_attribute("botanu.outcome.reason", reason)
+
+    if error_type:
+        span.set_attribute("botanu.outcome.error_type", error_type)
+
+    if metadata:
+        for key, value in metadata.items():
+            span.set_attribute(f"botanu.outcome.metadata.{key}", value)
+
+    event_attrs: dict[str, object] = {"status": status}
+    if value_type:
+        event_attrs["value_type"] = value_type
+    if value_amount is not None:
+        event_attrs["value_amount"] = value_amount
+    if error_type:
+        event_attrs["error_type"] = error_type
+
+    span.add_event("botanu.outcome_emitted", event_attrs)
+
+    # Emit OTel log record for collector flush trigger
+    event_id = get_baggage("botanu.event_id")
+    if event_id:
+        try:
+            from opentelemetry._logs import get_logger_provider
+
+            logger_provider = get_logger_provider()
+            otel_logger = logger_provider.get_logger("botanu.outcome")
+            otel_logger.emit(
+                body=f"outcome:{status}",
+                attributes={
+                    "botanu.event_id": event_id,
+                    "botanu.outcome.status": status,
+                },
+            )
+        except Exception:
+            pass  # Don't break user's code if logs not configured
+
+
+def set_business_context(
+    *,
+    customer_id: Optional[str] = None,
+    team: Optional[str] = None,
+    cost_center: Optional[str] = None,
+    region: Optional[str] = None,
+) -> None:
+    """Set business context attributes on the current span.
+
+    Args:
+        customer_id: Customer identifier for multi-tenant attribution.
+        team: Team or department.
+        cost_center: Cost centre for financial tracking.
+        region: Geographic region.
+    """
+    span = trace.get_current_span()
+
+    if customer_id:
+        span.set_attribute("botanu.customer_id", customer_id)
+
+    if team:
+        span.set_attribute("botanu.team", team)
+
+    if cost_center:
+        span.set_attribute("botanu.cost_center", cost_center)
+
+    if region:
+        span.set_attribute("botanu.region", region)

botanu/tracking/__init__.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Botanu tracking components.
+
+Provides tracking for different operation types:
+- LLM/GenAI model calls
+- Database, storage, and messaging operations
+"""
+
+from __future__ import annotations
+
+from botanu.tracking.data import (
+    DBOperation,
+    MessagingOperation,
+    StorageOperation,
+    set_data_metrics,
+    set_warehouse_metrics,
+    track_db_operation,
+    track_messaging_operation,
+    track_storage_operation,
+)
+from botanu.tracking.llm import (
+    BotanuAttributes,
+    GenAIAttributes,
+    LLMTracker,
+    ModelOperation,
+    ToolTracker,
+    set_llm_attributes,
+    set_token_usage,
+    track_llm_call,
+    track_tool_call,
+)
+
+__all__ = [
+    # LLM tracking
+    "track_llm_call",
+    "track_tool_call",
+    "set_llm_attributes",
+    "set_token_usage",
+    "ModelOperation",
+    "GenAIAttributes",
+    "BotanuAttributes",
+    "LLMTracker",
+    "ToolTracker",
+    # Data tracking
+    "track_db_operation",
+    "track_storage_operation",
+    "track_messaging_operation",
+    "set_data_metrics",
+    "set_warehouse_metrics",
+    "DBOperation",
+    "StorageOperation",
+    "MessagingOperation",
+]