botanu 0.1.dev63__tar.gz → 0.1.dev77__tar.gz

{botanu-0.1.dev63 → botanu-0.1.dev77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: botanu
-Version: 0.1.dev63
+Version: 0.1.dev77
 Summary: OpenTelemetry-native run-level cost attribution for AI workflows
 Project-URL: Homepage, https://github.com/botanu-ai/botanu-sdk-python
 Project-URL: Documentation, https://docs.botanu.ai
@@ -98,6 +98,9 @@ Requires-Dist: ruff>=0.4.0; extra == 'dev'
 Requires-Dist: starlette<0.30.0,>=0.27.0; extra == 'dev'
 Provides-Extra: gcp
 Requires-Dist: opentelemetry-resource-detector-gcp>=0.1b0; extra == 'gcp'
+Provides-Extra: pii-nlp
+Requires-Dist: presidio-analyzer>=2.2; extra == 'pii-nlp'
+Requires-Dist: presidio-anonymizer>=2.2; extra == 'pii-nlp'
 Description-Content-Type: text/markdown
 
 # botanu SDK for Python
@@ -110,6 +113,14 @@ This SDK is built on [OpenTelemetry](https://opentelemetry.io/) for event-level
 
 ## Getting Started
 
+An **event** is one business transaction — resolving a support ticket, processing an order, generating a report. Each event may involve multiple **runs** (LLM calls, retries, sub-workflows) across multiple services. By correlating every run to a stable `event_id`, Botanu gives you per-event cost attribution and outcome tracking without sampling artefacts.
+
+## Install
+
+```bash
+pip install botanu
+```
+
 An **event** is one business transaction — resolving a support ticket, processing
 an order, generating a report. Each event may involve multiple **runs** (LLM calls,
 retries, sub-workflows) across multiple services. By correlating every run to a
@@ -117,91 +128,104 @@ stable `event_id`, botanu gives you per-event cost attribution and outcome
 tracking without sampling artifacts.
 
 ```bash
-pip install botanu
+export BOTANU_API_KEY=<your-api-key>
 ```
 
-One install. Includes OTel SDK, OTLP exporter, and auto-instrumentation for
-50+ libraries.
+Wrap your agent:
 
 ```python
-from botanu import enable, botanu_workflow, emit_outcome
+import botanu
+
+with botanu.event(event_id=ticket.id, customer_id=user.id, workflow="Support"):
+    agent.run(ticket)
+```
 
-enable()  # reads config from environment variables
+That single wrap captures every LLM call, HTTP call, and DB call inside and stamps them with `event_id`, `customer_id`, and `workflow`.
 
-@botanu_workflow("my-workflow", event_id="evt-001", customer_id="cust-42")
-async def do_work():
-    result = await do_something()
-    emit_outcome("success")
-    return result
+### Decorator form
+
+```python
+import botanu
+
+@botanu.event(
+    workflow="Support",
+    event_id=lambda ticket: ticket.id,
+    customer_id=lambda ticket: ticket.user_id,
+)
+def handle_ticket(ticket):
+    return agent.run(ticket)
 ```
 
-Entry points use `@botanu_workflow`. Every other service only needs `enable()`.
-All configuration is via environment variables — zero hardcoded values in code.
+Works for both sync and `async def` functions.
+
+### Multi-phase workflows
+
+```python
+with botanu.event(event_id=ticket.id, customer_id=user.id, workflow="Support"):
+    with botanu.step("retrieval"):
+        docs = vector_db.query(ticket.query)
+    with botanu.step("generation"):
+        response = llm.complete(docs)
+```
 
-See the [Quick Start](./docs/getting-started/quickstart.md) guide for a full walkthrough.
+See the [Quickstart](./docs/getting-started/quickstart.md) for the full five-minute walkthrough.
 
 ## Documentation
 
-| Topic | Description |
-|-------|-------------|
-| [Installation](./docs/getting-started/installation.md) | Install and configure the SDK |
-| [Quick Start](./docs/getting-started/quickstart.md) | Get up and running in 5 minutes |
-| [Configuration](./docs/getting-started/configuration.md) | Environment variables and options |
-| [Core Concepts](./docs/concepts/) | Events, runs, context propagation, architecture |
-| [LLM Tracking](./docs/tracking/llm-tracking.md) | Track model calls and token usage |
-| [Data Tracking](./docs/tracking/data-tracking.md) | Database, storage, and messaging |
-| [Outcomes](./docs/tracking/outcomes.md) | Record business outcomes for ROI |
-| [Auto-Instrumentation](./docs/integration/auto-instrumentation.md) | Supported libraries and frameworks |
+| Topic | |
+| --- | --- |
+| [Installation](./docs/getting-started/installation.md) | Install and configure |
+| [Quickstart](./docs/getting-started/quickstart.md) | Zero-to-first-trace in five minutes |
+| [Configuration](./docs/getting-started/configuration.md) | Env vars, YAML, trusted-host auth |
+| [Run Context](./docs/concepts/run-context.md) | Events, runs, retries, baggage |
+| [Context Propagation](./docs/concepts/context-propagation.md) | Cross-service and queue propagation |
+| [Architecture](./docs/concepts/architecture.md) | SDK + collector split |
+| [LLM Tracking](./docs/tracking/llm-tracking.md) | Manual LLM instrumentation (usually not needed) |
+| [Data Tracking](./docs/tracking/data-tracking.md) | DB, storage, messaging (usually not needed) |
+| [Content Capture](./docs/tracking/content-capture.md) | Prompt/response capture for eval, with PII scrubbing |
+| [Outcomes](./docs/tracking/outcomes.md) | Diagnostic annotations and server-side resolution |
+| [Auto-Instrumentation](./docs/integration/auto-instrumentation.md) | Supported libraries |
 | [Kubernetes](./docs/integration/kubernetes.md) | Zero-code instrumentation at scale |
-| [API Reference](./docs/api/) | Decorators, tracking API, configuration |
-| [Best Practices](./docs/patterns/best-practices.md) | Recommended patterns |
+| [Existing OTel / Datadog](./docs/integration/existing-otel.md) | Brownfield coexistence |
+| [`event` / `step` API](./docs/api/event.md) | Primary API reference |
+| [Best Practices](./docs/patterns/best-practices.md) | Patterns that work |
+| [Anti-Patterns](./docs/patterns/anti-patterns.md) | Patterns that break cost attribution |
 
 ## Requirements
 
-- Python 3.9+
-- OpenTelemetry Collector (recommended for production)
+- Python 3.9 or newer
+- An OpenTelemetry Collector (Botanu Cloud runs one for you; self-hosted is supported too)
 
 ## Contributing
 
-We welcome contributions from the community. Please read our
-[Contributing Guide](./CONTRIBUTING.md) before submitting a pull request.
+Contributions are welcome. Read the [Contributing Guide](./CONTRIBUTING.md) before opening a pull request.
 
-This project requires [DCO sign-off](https://developercertificate.org/) on all
-commits:
+All commits require [DCO sign-off](https://developercertificate.org/):
 
 ```bash
 git commit -s -m "Your commit message"
 ```
 
-Looking for a place to start? Check the
-[good first issues](https://github.com/botanu-ai/botanu-sdk-python/labels/good%20first%20issue).
+Looking for a place to start? See the [good first issues](https://github.com/botanu-ai/botanu-sdk-python/labels/good%20first%20issue).
 
 ## Community
 
 - [GitHub Discussions](https://github.com/botanu-ai/botanu-sdk-python/discussions) — questions, ideas, show & tell
-- [GitHub Issues](https://github.com/botanu-ai/botanu-sdk-python/issues) — bug reports and feature requests
+- [GitHub Issues](https://github.com/botanu-ai/botanu-sdk-python/issues) — bugs and feature requests
 
 ## Governance
 
-See [GOVERNANCE.md](./GOVERNANCE.md) for details on roles, decision-making,
-and the contributor ladder.
-
-Current maintainers are listed in [MAINTAINERS.md](./MAINTAINERS.md).
+See [GOVERNANCE.md](./GOVERNANCE.md) for roles, decision-making, and the contributor ladder. Current maintainers are in [MAINTAINERS.md](./MAINTAINERS.md).
 
 ## Security
 
-To report a security vulnerability, please use
-[GitHub Security Advisories](https://github.com/botanu-ai/botanu-sdk-python/security/advisories/new)
-or see [SECURITY.md](./SECURITY.md) for full details. **Do not file a public issue.**
+Report security vulnerabilities via [GitHub Security Advisories](https://github.com/botanu-ai/botanu-sdk-python/security/advisories/new) or see [SECURITY.md](./SECURITY.md). **Do not file a public issue.**
 
 
 ## Code of Conduct
 
-This project follows the
-[LF Projects Code of Conduct](https://lfprojects.org/policies/code-of-conduct/).
-See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+This project follows the [LF Projects Code of Conduct](https://lfprojects.org/policies/code-of-conduct/). See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
 
 ## License
 
 [Apache License 2.0](./LICENSE)
-

botanu-0.1.dev77/README.md

@@ -0,0 +1,126 @@
+# botanu SDK for Python
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
+
+[botanu](https://botanu.ai/) is platform that helps AI companies understand the real cost of their AI features per customer, enabling outcome-based pricing and smarter scaling.
+This SDK is built on [OpenTelemetry](https://opentelemetry.io/) for event-level cost attribution for AI workflow. For more email- deborah@botanu.ai
+
+
+## Getting Started
+
+An **event** is one business transaction — resolving a support ticket, processing an order, generating a report. Each event may involve multiple **runs** (LLM calls, retries, sub-workflows) across multiple services. By correlating every run to a stable `event_id`, Botanu gives you per-event cost attribution and outcome tracking without sampling artefacts.
+
+## Install
+
+```bash
+pip install botanu
+```
+
+An **event** is one business transaction — resolving a support ticket, processing
+an order, generating a report. Each event may involve multiple **runs** (LLM calls,
+retries, sub-workflows) across multiple services. By correlating every run to a
+stable `event_id`, botanu gives you per-event cost attribution and outcome
+tracking without sampling artifacts.
+
+```bash
+export BOTANU_API_KEY=<your-api-key>
+```
+
+Wrap your agent:
+
+```python
+import botanu
+
+with botanu.event(event_id=ticket.id, customer_id=user.id, workflow="Support"):
+    agent.run(ticket)
+```
+
+That single wrap captures every LLM call, HTTP call, and DB call inside and stamps them with `event_id`, `customer_id`, and `workflow`.
+
+### Decorator form
+
+```python
+import botanu
+
+@botanu.event(
+    workflow="Support",
+    event_id=lambda ticket: ticket.id,
+    customer_id=lambda ticket: ticket.user_id,
+)
+def handle_ticket(ticket):
+    return agent.run(ticket)
+```
+
+Works for both sync and `async def` functions.
+
+### Multi-phase workflows
+
+```python
+with botanu.event(event_id=ticket.id, customer_id=user.id, workflow="Support"):
+    with botanu.step("retrieval"):
+        docs = vector_db.query(ticket.query)
+    with botanu.step("generation"):
+        response = llm.complete(docs)
+```
+
+See the [Quickstart](./docs/getting-started/quickstart.md) for the full five-minute walkthrough.
+
+## Documentation
+
+| Topic | |
+| --- | --- |
+| [Installation](./docs/getting-started/installation.md) | Install and configure |
+| [Quickstart](./docs/getting-started/quickstart.md) | Zero-to-first-trace in five minutes |
+| [Configuration](./docs/getting-started/configuration.md) | Env vars, YAML, trusted-host auth |
+| [Run Context](./docs/concepts/run-context.md) | Events, runs, retries, baggage |
+| [Context Propagation](./docs/concepts/context-propagation.md) | Cross-service and queue propagation |
+| [Architecture](./docs/concepts/architecture.md) | SDK + collector split |
+| [LLM Tracking](./docs/tracking/llm-tracking.md) | Manual LLM instrumentation (usually not needed) |
+| [Data Tracking](./docs/tracking/data-tracking.md) | DB, storage, messaging (usually not needed) |
+| [Content Capture](./docs/tracking/content-capture.md) | Prompt/response capture for eval, with PII scrubbing |
+| [Outcomes](./docs/tracking/outcomes.md) | Diagnostic annotations and server-side resolution |
+| [Auto-Instrumentation](./docs/integration/auto-instrumentation.md) | Supported libraries |
+| [Kubernetes](./docs/integration/kubernetes.md) | Zero-code instrumentation at scale |
+| [Existing OTel / Datadog](./docs/integration/existing-otel.md) | Brownfield coexistence |
+| [`event` / `step` API](./docs/api/event.md) | Primary API reference |
+| [Best Practices](./docs/patterns/best-practices.md) | Patterns that work |
+| [Anti-Patterns](./docs/patterns/anti-patterns.md) | Patterns that break cost attribution |
+
+## Requirements
+
+- Python 3.9 or newer
+- An OpenTelemetry Collector (Botanu Cloud runs one for you; self-hosted is supported too)
+
+## Contributing
+
+Contributions are welcome. Read the [Contributing Guide](./CONTRIBUTING.md) before opening a pull request.
+
+All commits require [DCO sign-off](https://developercertificate.org/):
+
+```bash
+git commit -s -m "Your commit message"
+```
+
+Looking for a place to start? See the [good first issues](https://github.com/botanu-ai/botanu-sdk-python/labels/good%20first%20issue).
+
+## Community
+
+- [GitHub Discussions](https://github.com/botanu-ai/botanu-sdk-python/discussions) — questions, ideas, show & tell
+- [GitHub Issues](https://github.com/botanu-ai/botanu-sdk-python/issues) — bugs and feature requests
+
+## Governance
+
+See [GOVERNANCE.md](./GOVERNANCE.md) for roles, decision-making, and the contributor ladder. Current maintainers are in [MAINTAINERS.md](./MAINTAINERS.md).
+
+## Security
+
+Report security vulnerabilities via [GitHub Security Advisories](https://github.com/botanu-ai/botanu-sdk-python/security/advisories/new) or see [SECURITY.md](./SECURITY.md). **Do not file a public issue.**
+
+
+## Code of Conduct
+
+This project follows the [LF Projects Code of Conduct](https://lfprojects.org/policies/code-of-conduct/). See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+
+## License
+
+[Apache License 2.0](./LICENSE)

{botanu-0.1.dev63 → botanu-0.1.dev77}/pyproject.toml

@@ -139,6 +139,14 @@ cloud = [
     "opentelemetry-resource-detector-azure >= 0.1b0",
     "opentelemetry-resource-detector-container >= 0.1b0",
 ]
+
+# NER-based PII scrubbing on top of the built-in regex pass. Regex covers
+# structured tokens (emails, card numbers, API keys); Presidio adds names,
+# addresses, and medical terms. Heavy (~200MB with spaCy model) — opt-in only.
+pii-nlp = [
+    "presidio-analyzer >= 2.2",
+    "presidio-anonymizer >= 2.2",
+]
 dev = [
     "pytest >= 7.4.0",
     "pytest-asyncio >= 0.21.0",

{botanu-0.1.dev63 → botanu-0.1.dev77}/src/botanu/__init__.py

@@ -5,15 +5,22 @@
 
 Quick Start::
 
-    from botanu import enable, botanu_workflow, emit_outcome
+    import botanu
 
-    enable()  # reads config from OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT env vars
+    botanu.enable()  # reads 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
+    # One wrap around the agent entrypoint captures every LLM/HTTP/DB call.
+    with botanu.event(event_id=ticket.id, customer_id=user.id, workflow="Support"):
+        agent.run(ticket)
+
+    # Or as a decorator, with lambda extractors from the function args:
+    @botanu.event(
+        workflow="Support",
+        event_id=lambda t: t.id,
+        customer_id=lambda t: t.user_id,
+    )
+    def handle_ticket(ticket):
+        ...
 """
 
 from __future__ import annotations
@@ -23,6 +30,9 @@ from botanu._version import __version__
 # Run context model
 from botanu.models.run_context import RunContext, RunOutcome, RunStatus
 
+# Processors
+from botanu.processors import RunContextEnricher, SampledSpanProcessor
+
 # Bootstrap
 from botanu.sdk.bootstrap import (
     disable,
@@ -42,11 +52,11 @@ from botanu.sdk.context import (
     set_baggage,
 )
 
-# Decorators  (primary integration point)
-from botanu.sdk.decorators import botanu_workflow, run_botanu, workflow
+# Primary integration API
+from botanu.sdk.decorators import event, step
 
 # Span helpers
-from botanu.sdk.span_helpers import emit_outcome, set_business_context
+from botanu.sdk.span_helpers import emit_outcome, set_business_context, set_correlation
 
 __all__ = [
     "__version__",
@@ -56,13 +66,13 @@ __all__ = [
     "is_enabled",
     # Configuration
     "BotanuConfig",
-    # Decorators / context managers
-    "botanu_workflow",
-    "run_botanu",
-    "workflow",
+    # Primary API
+    "event",
+    "step",
     # Span helpers
     "emit_outcome",
     "set_business_context",
+    "set_correlation",
     "get_current_span",
     # Context
     "get_run_id",
@@ -73,4 +83,7 @@ __all__ = [
     "RunContext",
     "RunStatus",
     "RunOutcome",
+    # Processors
+    "RunContextEnricher",
+    "SampledSpanProcessor",
 ]

{botanu-0.1.dev63 → botanu-0.1.dev77}/src/botanu/models/run_context.py

@@ -89,6 +89,7 @@ class RunContext:
     event_id: str
     customer_id: str
     environment: str
+    step: Optional[str] = None
     workflow_version: Optional[str] = None
     tenant_id: Optional[str] = None
     parent_run_id: Optional[str] = None
@@ -211,22 +212,30 @@ class RunContext:
     # 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"
+    def to_baggage_dict(self) -> Dict[str, str]:
+        """Convert to dict for W3C Baggage propagation.
 
+        Always present: ``botanu.run_id``, ``botanu.workflow``,
+        ``botanu.event_id``, ``botanu.customer_id``, ``botanu.environment``.
+
+        Included when set on the context: ``botanu.tenant_id``,
+        ``botanu.parent_run_id``, ``botanu.root_run_id`` (if non-root),
+        ``botanu.attempt`` (if > 1), ``botanu.retry_of_run_id``,
+        ``botanu.deadline``, ``botanu.cancelled``.
+
+        The :class:`RunContextEnricher` stamps only the first seven
+        (run_id, workflow, event_id, customer_id, environment, tenant_id,
+        parent_run_id) on downstream spans. The remaining keys are for
+        :meth:`from_baggage` to reconstruct retry/deadline state on the
+        receiving side of cross-process propagation (e.g. message queues).
+        """
         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,
+            "botanu.environment": self.environment,
         }
-        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:
@@ -270,7 +279,6 @@ class RunContext:
             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:

{botanu-0.1.dev63 → botanu-0.1.dev77}/src/botanu/processors/__init__.py

@@ -8,5 +8,7 @@ All other processing should happen in the OTel Collector.
 """
 
 from botanu.processors.enricher import RunContextEnricher
+from botanu.processors.resource_enricher import ResourceEnricher
+from botanu.processors.sampled import SampledSpanProcessor
 
-__all__ = ["RunContextEnricher"]
+__all__ = ["RunContextEnricher", "ResourceEnricher", "SampledSpanProcessor"]

{botanu-0.1.dev63 → botanu-0.1.dev77}/src/botanu/processors/enricher.py

@@ -8,10 +8,13 @@ Why this MUST be in SDK (not collector):
 - 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``
+Heavy non-content processing happens in the OTel Collector:
 - Cardinality limits → ``attributesprocessor``
 - Vendor detection → ``transformprocessor``
+- Belt-and-suspenders PII regex → ``redactionprocessor``
+
+In-process PII scrubbing of content-capture attributes is handled by
+:mod:`botanu.sdk.pii` at the tracker methods, not by a span processor.
 """
 
 from __future__ import annotations
@@ -29,17 +32,18 @@ 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.
+    This ensures that every span (including auto-instrumented ones) gets
+    ``botanu.run_id``, ``botanu.workflow``, ``botanu.event_id``,
+    ``botanu.customer_id``, ``botanu.environment``, ``botanu.tenant_id``,
+    and ``botanu.parent_run_id`` attributes when those baggage keys are
+    present on the active OTel context.
 
-    In ``lean_mode`` (default), only ``run_id`` and ``workflow`` are
-    propagated to minimise per-span overhead.
+    Without this processor, only the root ``botanu.run`` span would carry
+    these attributes; downstream auto-instrumented spans (LLM, HTTP, DB)
+    would not.
     """
 
-    BAGGAGE_KEYS_FULL: ClassVar[List[str]] = [
+    BAGGAGE_KEYS: ClassVar[List[str]] = [
         "botanu.run_id",
         "botanu.workflow",
         "botanu.event_id",
@@ -49,17 +53,6 @@ class RunContextEnricher(SpanProcessor):
         "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,
@@ -68,7 +61,7 @@ class RunContextEnricher(SpanProcessor):
         """Called when a span starts — enrich with run context from baggage."""
         ctx = parent_context or context.get_current()
 
-        for key in self._baggage_keys:
+        for key in self.BAGGAGE_KEYS:
             value = baggage.get_baggage(key, ctx)
             if value:
                 if not span.attributes or key not in span.attributes: