usefluency-workflow-telemetry 0.1.1__py3-none-any.whl

fluency_workflow_telemetry/__init__.py

@@ -0,0 +1,6 @@
+"""Standard OTLP startup configuration for customer workflow telemetry."""
+
+from .configuration import TelemetryHandle, configure
+from .events import AgentEvents
+
+__all__ = ["AgentEvents", "TelemetryHandle", "configure"]

fluency_workflow_telemetry/configuration.py

@@ -0,0 +1,151 @@
+"""Configure standard OTLP export without owning application instrumentation."""
+
+from __future__ import annotations
+
+import math
+import os
+import threading
+from dataclasses import dataclass, field
+from importlib.metadata import version
+from urllib.parse import urlsplit
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http import Compression
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from .events import AgentEvents
+
+_lock = threading.RLock()
+_handles: dict[TracerProvider, TelemetryHandle] = {}
+
+
+@dataclass(frozen=True)
+class _Configuration:
+  endpoint: str
+  api_key: str = field(repr=False)
+  service_name: str | None
+  max_queue_size: int
+  max_export_batch_size: int
+  schedule_delay_millis: int
+  timeout_seconds: float
+
+
+class TelemetryHandle:
+  """Own only the Fluency batch processor; the application's provider stays usable."""
+
+  def __init__(self, provider: TracerProvider, processor: BatchSpanProcessor, config: _Configuration) -> None:
+    self.provider = provider
+    self.events = AgentEvents(provider.get_tracer("usefluency-workflow-telemetry", version("usefluency-workflow-telemetry")))
+    self._processor = processor
+    self._lifecycle_lock = threading.RLock()
+    self._config = config
+    self._closed = False
+
+  @property
+  def closed(self) -> bool:
+    return self._closed
+
+  def flush(self) -> None:
+    """Block while attempting to drain ended spans; no total deadline or delivery acknowledgment."""
+    with self._lifecycle_lock:
+      if not self._closed:
+        self._processor.force_flush()
+
+  def shutdown(self) -> None:
+    """Drain and stop Fluency export without stopping other exporters.
+
+    Uses OTel's shutdown behavior; unsent spans can be lost. Inspect
+    exporter logs for outcomes. Finish active work before shutting down.
+    """
+    with self._lifecycle_lock:
+      if not self._closed:
+        self._closed = True
+        self._processor.shutdown()
+
+
+def configure(
+  *,
+  traces_endpoint: str | None = None,
+  api_key: str | None = None,
+  service_name: str | None = None,
+  provider: TracerProvider | None = None,
+  max_queue_size: int = 2048,
+  max_export_batch_size: int = 512,
+  schedule_delay_millis: int = 5000,
+  timeout_seconds: float = 10,
+) -> TelemetryHandle:
+  """Add batched OTLP/HTTP export to a supplied, existing, or new global provider.
+
+  Endpoint is the full traces URL, used unchanged. Framework instrumentation must
+  be configured separately. Existing resources, sampling and exporters are kept.
+  """
+  endpoint = traces_endpoint if traces_endpoint is not None else os.getenv("FLUENCY_OTLP_TRACES_ENDPOINT", "")
+  key = api_key if api_key is not None else os.getenv("FLUENCY_WORKFLOW_API_KEY", "")
+  url = urlsplit(endpoint)
+  if url.scheme not in {"http", "https"} or not url.hostname or url.username or url.password or url.query or url.fragment:
+    raise ValueError("traces_endpoint must be a full HTTP(S) traces URL without credentials, query or fragment")
+  if url.scheme == "http" and url.hostname not in {"localhost", "127.0.0.1", "::1"}:
+    raise ValueError("Use HTTPS for non-local telemetry endpoints")
+  if not key.strip() or any(c.isspace() for c in key):
+    raise ValueError("Provide api_key or FLUENCY_WORKFLOW_API_KEY without whitespace")
+  if service_name is not None and not service_name.strip():
+    raise ValueError("service_name must not be empty")
+  if any(type(value) is not int for value in (max_queue_size, max_export_batch_size, schedule_delay_millis)):
+    raise ValueError("Batch sizes and delay must be integers")
+  if max_export_batch_size > 1024:
+    raise ValueError("max_export_batch_size must not exceed the receiver's 1024 span limit")
+  if max_queue_size <= 0 or not 0 < max_export_batch_size <= max_queue_size or schedule_delay_millis <= 0:
+    raise ValueError("Batch sizes and delay must be positive; batch size must not exceed queue size")
+  if not math.isfinite(timeout_seconds) or timeout_seconds <= 0:
+    raise ValueError("timeout_seconds must be finite and positive")
+  config = _Configuration(endpoint, key, service_name, max_queue_size, max_export_batch_size, schedule_delay_millis, timeout_seconds)
+
+  with _lock:
+    candidate = provider if provider is not None else trace.get_tracer_provider()
+    new_global = provider is None and isinstance(candidate, trace.ProxyTracerProvider)
+    if new_global:
+      attributes = {"service.name": service_name} if service_name is not None else {}
+      target = TracerProvider(resource=Resource.create(attributes))
+    elif isinstance(candidate, TracerProvider):
+      target = candidate
+    else:
+      raise TypeError("An OpenTelemetry SDK TracerProvider is required; the existing provider will not be replaced")
+
+    existing = _handles.get(target)
+    if existing is not None:
+      if existing._closed:
+        raise RuntimeError("Fluency telemetry has shut down for this provider; configure once at application startup")
+      if existing._config != config:
+        raise ValueError("Fluency export is already configured differently on this provider")
+      return existing
+    if not new_global and service_name is not None and target.resource.attributes.get("service.name") != service_name:
+      raise ValueError("Set service_name on the existing provider's Resource; configure does not replace resources")
+
+    exporter = OTLPSpanExporter(
+      endpoint=endpoint,
+      headers={
+        "Authorization": f"Bearer {key}",
+        "User-Agent": (
+          f"usefluency-workflow-telemetry/{version('usefluency-workflow-telemetry')} "
+          f"OTel-OTLP-Exporter-Python/{version('opentelemetry-exporter-otlp-proto-http')}"
+        ),
+      },
+      timeout=timeout_seconds,
+      compression=Compression.NoCompression,
+    )
+    processor = BatchSpanProcessor(
+      exporter, max_queue_size=max_queue_size, max_export_batch_size=max_export_batch_size, schedule_delay_millis=schedule_delay_millis
+    )
+    if new_global:
+      trace.set_tracer_provider(target)
+      if trace.get_tracer_provider() is not target:
+        processor.shutdown()
+        target.shutdown()
+        raise RuntimeError("Another provider was installed during setup; pass the existing provider explicitly")
+    target.add_span_processor(processor)
+    handle = TelemetryHandle(target, processor, config)
+    _handles[target] = handle
+    return handle

fluency_workflow_telemetry/docs/LICENSE

@@ -0,0 +1,34 @@
+Fluency Workflow Telemetry SDK Proprietary License
+
+Copyright (c) 2026 Fluency. All rights reserved.
+
+This software and its documentation (the "SDK") are proprietary and confidential
+to Fluency.
+
+Subject to a written agreement with Fluency that authorizes access to the Fluency
+services, Fluency grants the customer a limited, non-exclusive, non-transferable,
+non-sublicensable right to install, copy, and use the SDK solely for the customer's
+internal operation of its automated workflows with the Fluency services during the term
+of that agreement.
+
+Except to the extent expressly permitted by that written agreement or applicable
+law, the customer may not:
+
+1. distribute, publish, sublicense, sell, rent, lease, or otherwise make the SDK
+   available to any third party;
+2. modify, adapt, translate, or create derivative works of the SDK;
+3. reverse engineer, decompile, or disassemble the SDK; or
+4. use the SDK to develop or operate a product or service that competes with the
+   Fluency services.
+
+The customer may make a reasonable number of copies of the SDK solely for backup,
+testing, deployment, and disaster recovery connected with its authorized use. All
+copies must retain this license and all proprietary notices.
+
+Third-party software included with or used by the SDK remains subject to its own
+license terms. No rights are granted to Fluency trademarks, service marks, or logos.
+
+The SDK is provided under the warranties, disclaimers, liability limits, and other
+terms in the customer's written agreement with Fluency. If this license conflicts
+with that agreement, the agreement controls. If no such agreement is in effect, no
+license to use the SDK is granted.

fluency_workflow_telemetry/docs/README.md

@@ -0,0 +1,36 @@
+# Workflow telemetry SDKs
+
+Capture the work your agents and automations perform in Fluency. Connect existing OpenTelemetry instrumentation, then add business identifiers and outcomes with the SDK's event helpers.
+
+## Install
+
+```sh
+pip install usefluency-workflow-telemetry
+npm install @usefluency/workflow-telemetry
+```
+
+Python requires 3.12 or later and imports as `fluency_workflow_telemetry`. JavaScript and TypeScript require Node.js 24 or later; ESM and CommonJS are supported.
+
+## Get started
+
+Your Fluency contact provides your organization's regional endpoint and ingestion key. Configure them in your server-side environment:
+
+```sh
+FLUENCY_OTLP_TRACES_ENDPOINT=https://YOUR-REGIONAL-ENDPOINT/ext/otel/v1/traces
+FLUENCY_WORKFLOW_API_KEY=YOUR-ORGANIZATION-API-KEY
+```
+
+Choose the guide for your application:
+
+- [LangChain and LangGraph](https://docs.usefluency.com/fluency-workflow-telemetry-langchain): connect a Python agent, capture its tools, and attach business context.
+- [Vercel AI SDK](https://docs.usefluency.com/fluency-workflow-telemetry-vercel): capture Node.js model calls, tools, and streaming work.
+- [OpenAI](https://docs.usefluency.com/fluency-workflow-telemetry-openai): connect direct Python API calls or Agents SDK workflows while preserving existing tracing.
+- [RPA and custom workflows](https://docs.usefluency.com/fluency-workflow-telemetry-rpa): record steps and outcomes from Python or TypeScript automations.
+- [Existing OpenTelemetry](https://docs.usefluency.com/fluency-workflow-telemetry-opentelemetry): add Fluency while keeping your current telemetry destination.
+- [Business context and capture](https://docs.usefluency.com/fluency-workflow-telemetry-business-context): enrich an operation or record a business action.
+
+After `configure()`, use `telemetry.events` for `enrich`, `capture`, and timed operations. Framework integrations capture the operations they instrument; the exporter alone does not discover agent or bot activity.
+
+Exact methods and lifecycle behavior are in the [SDK reference](SDK.md). [Executable examples](examples/README.md) accompany the guides. Maintainers use [release instructions](https://github.com/farmorsoftware/fluency-monorepo/blob/main/packages/workflow-telemetry/RELEASING.md).
+
+This software is proprietary; see [LICENSE](LICENSE).

fluency_workflow_telemetry/docs/SDK.md

@@ -0,0 +1,248 @@
+# Fluency Workflow Telemetry SDK reference
+
+## Overview
+
+Python and Node.js adapters for standard OpenTelemetry export, plus optional instrumentation helpers. For onboarding, credentials, and Collector setup, use the [customer integration guide](https://docs.usefluency.com/fluency-workflow-telemetry-sdk). For the meaning of spans, span events, and capture, see [business context](https://docs.usefluency.com/fluency-workflow-telemetry-business-context).
+
+## Install
+
+Python requires 3.12 or later; Node.js requires 24 or later. Install the SDK from PyPI or npm:
+
+```sh
+pip install usefluency-workflow-telemetry
+npm install @usefluency/workflow-telemetry
+```
+
+## SDK reference
+
+### Initialize the client
+
+| Python `configure()`    | TypeScript `configure()` | Default                           |
+| ----------------------- | ------------------------ | --------------------------------- |
+| `traces_endpoint`       | `tracesEndpoint`         | `FLUENCY_OTLP_TRACES_ENDPOINT`    |
+| `api_key`               | `apiKey`                 | `FLUENCY_WORKFLOW_API_KEY`        |
+| `service_name`          | `serviceName`            | OTel resource default/environment |
+| `max_queue_size`        | `maxQueueSize`           | 2048                              |
+| `max_export_batch_size` | `maxExportBatchSize`     | 512                               |
+| `schedule_delay_millis` | `scheduleDelayMillis`    | 5000                              |
+| `timeout_seconds`       | `timeoutSeconds`         | 10                                |
+
+The endpoint is a full traces URL. It must use HTTPS except for loopback, and must
+not contain credentials, a query or a fragment. Keys cannot be empty or contain
+whitespace. Batch sizes/delay must be positive integers, batch size cannot exceed
+queue size or 1024, and timeout must be finite and positive.
+
+Python additionally accepts `provider=existing_provider`. TypeScript integrates
+with application-owned providers using `createSpanProcessor(options)`, which
+accepts the same options except `serviceName`; set service metadata on the
+application's resource. Add the returned `processor` to the provider's
+`spanProcessors` constructor option exactly once. See the existing-provider examples below.
+
+Python reuses an existing global SDK provider when `provider` is omitted.
+TypeScript `configure()` requires an unconfigured global provider. Neither replaces
+an application's provider, existing resource, sampler or exporters. Both new-provider
+paths honor OTel resource environment attributes; explicit service name takes precedence.
+
+`configure()` is idempotent for identical configuration and rejects conflicting
+configuration. Configure after worker forking. Framework instrumentation must use
+the same provider; an exporter does not create spans.
+
+### Use an existing OpenTelemetry provider
+
+```python
+from fluency_workflow_telemetry import configure
+
+telemetry = configure(provider=existing_provider)
+```
+
+Use the `TracerProvider` already used by your framework or application. An explicitly supplied provider is not installed globally. Existing exporters, sampling policy, and resource attributes remain in place.
+
+If you omit `provider`, `configure()` reuses an existing global OTel SDK provider or creates one when none has been installed. Initialize it before your framework's instrumentation. If that framework owns provider setup, initialize the framework first and pass its provider explicitly.
+
+Configure `service.name` and other resource attributes on an existing provider itself. Passing a different `service_name` to `configure()` raises an error rather than replacing its resource.
+
+For TypeScript, create the Fluency processor once and include it alongside your existing processors:
+
+```typescript
+import { createSpanProcessor } from '@usefluency/workflow-telemetry';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+
+const telemetry = createSpanProcessor();
+const provider = new NodeTracerProvider({
+  spanProcessors: [existingProcessor, telemetry.processor],
+  // Keep your application's resource and sampler configuration here.
+});
+provider.register();
+```
+
+`existingProcessor` represents your existing exporter pipeline. You can also pass the processor to `NodeSDK` through `spanProcessors`. OpenTelemetry JavaScript accepts processors during provider construction; update your startup configuration if your provider is already running. Each `createSpanProcessor()` call creates an independent export branch.
+
+### Rotate the API key
+
+The credential is fixed at startup. Update your secret configuration and restart with the new key before revoking the old one. The SDK does not refresh tokens or hot-reload keys.
+
+### Lifecycle and adapter methods
+
+| Python handle | TypeScript handle             | Meaning                                                      |
+| ------------- | ----------------------------- | ------------------------------------------------------------ |
+| `provider`    | `provider` from `configure()` | Provider used by application instrumentation                 |
+| —             | `processor`                   | Processor to attach during application provider construction |
+| `flush()`     | `await flush()`               | Attempt to drain ended spans                                 |
+| `shutdown()`  | `await shutdown()`            | Drain and stop Fluency export                                |
+| `closed`      | `closed`                      | Shutdown has started                                         |
+
+### Handle SDK diagnostics
+
+Use the official OpenTelemetry exporter diagnostics through your application's
+logging integration. The SDK does not install a global logger or expose delivery
+counters. HTTP success can include partial rejection: Python's locked exporter
+reports success without inspecting that body, while JavaScript logs partial
+success through OTel `diag` and still reports export success. Neither result is
+a per-span storage receipt. The receiver records authoritative accepted,
+inserted, duplicate and rejected counts after the transaction commits.
+
+Both lifecycle methods return no delivery status (`None` / `Promise<void>`).
+
+### Delivery, flushing, and shutdown
+
+Finish active spans, streams and framework-specific buffers before shutdown.
+Python methods block; async applications should call them on a worker thread.
+The timeout applies to each official export attempt and retry budget, not the full
+drain. Shutdown stops only Fluency's
+processor; the application remains responsible for its provider and other exporters.
+A shut-down handle cannot be restarted.
+
+Queues are in memory. Failed batches are not retained for a later flush. Crashes,
+overflow, sampling and exhausted retries can lose spans. Collector durability is
+an optional deployment choice with its own capacity and recovery limits.
+
+## Record business context
+
+Use native span attributes for facts about an operation and `span.add_event()` / `span.addEvent()` for a milestone within it. Both are retained. A customer agent event is a product concept; it need not be represented by a separate OTel span. The SDK does not extract nested span events into independent business records.
+
+### Optional Fluency attribute conventions
+
+These are Fluency conventions, not OpenTelemetry standard keys or required ingestion fields. All values below are strings. Native OTel calls and the optional helpers produce the same evidence. Existing customer-defined and framework attributes remain intact.
+
+| Attribute                      | Meaning and scope                                                                                                                                |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `fluency.run.id`               | Customer's business execution identifier; may correlate several traces. Set on relevant spans. It does not change deduplication or merge traces. |
+| `fluency.run.name`             | Business operation name, such as `Review supplier invoice`.                                                                                      |
+| `fluency.artifact.source`      | Source namespace, including system/environment where needed, such as `erp:production:invoices`.                                                  |
+| `fluency.artifact.external_id` | Record identifier within that source; attach to the operation touching that record.                                                              |
+| `fluency.artifact.type`        | Customer's record type, such as `invoice`; no automatic KG classification.                                                                       |
+| `fluency.outcome`              | Declared business result, such as `approved`, `declined`, or `escalated`, on the operation reaching that result.                                 |
+
+Absent fields remain unknown. Technical Error/OK is not a business outcome. Conversation/session IDs are retained as correlation evidence, not automatically treated as business run IDs. Declared attributes must take precedence over any future inferred interpretation. Record multiple affected artifacts in separate operation spans or customer-defined attributes; do not overwrite a single artifact field repeatedly and expect a history.
+
+### Optional agent-event helpers
+
+`AgentEvents(tracer)` uses an application-supplied tracer. With no argument, it obtains a tracer from the global provider. It never configures a provider, exporter, sampler, or logger. Configure export separately. With no SDK provider, native OTel no-op behavior applies.
+
+| Python                                   | TypeScript                                        | Behavior                                                                                                                        |
+| ---------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `enrich(attributes, span=...)`           | `enrich(attributes, span?)`                       | Sets attributes on the supplied or active recording span. Returns false if absent, ended, or nonrecording. Creates no span.     |
+| `capture(name, attributes=..., parent=None)`          | `capture(name, attributes?, parent?)`                      | Starts and immediately ends a span with equal start/end timestamps. Returns its `SpanContext`, not a delivery receipt.          |
+| `with events.span(name, attributes=...)` | `await events.trace(name, callback, attributes?)` | Starts an active operation span, ends it on exit, and preserves the operation's exception. TypeScript always returns a Promise. |
+| `with events.context(attributes)`        | `events.withContext(attributes, callback)`        | Scopes attributes to calls through this helper instance. Creates no span and does not establish trace parentage.                |
+
+Python operation helpers use native OTel exception semantics. TypeScript records Error/string exceptions, marks Error, rethrows the original value, and ends in `finally`. Python cancellation ends the span but follows native OTel status behavior. Consume streams inside the block/callback; returning an iterator does not keep it open.
+
+### How capture joins an existing trace
+
+`capture()` uses the **active OTel context at the call site**, unless an explicit parent span is supplied. Selecting the same tracer, passing the same business ID, or constructing `AgentEvents` inside a span does not save a parent for later calls.
+
+| Context at the call                                  | Result with an installed SDK                                                                      |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Valid active parent span                             | Same trace ID; a new span ID; `parent_span_id` is the active parent's span ID.                    |
+| Extracted remote parent activated by instrumentation | Same distributed trace, subject to the provider's sampler.                                        |
+| No valid active parent                               | New root span and a new trace ID.                                                                 |
+| Nonrecording valid parent                            | Parent relationship still comes from context; recording/export depends on the configured sampler. |
+
+Capture ends only its new span. It neither ends nor becomes the customer's active span. Multiple captures under one active parent are siblings. Native `addEvent` instead appends an annotation to the existing span and creates no new span ID. Child capture can be exported before its parent ends; an annotation waits for its containing span to end with standard processors.
+
+```text
+Trace A
+  Review invoice                         existing active span
+    event: invoice.approved              native annotation, no separate span ID
+    Approval notification queued         capture: new child span, ended immediately
+
+Trace B
+  Standalone reconciliation              capture outside any active span
+```
+
+The executable [Python](examples/capture-context.py) and [TypeScript](examples/capture-context.ts) examples assert these IDs, parentage, active-context preservation and coexistence with another exporter.
+
+```python
+from fluency_workflow_telemetry import AgentEvents
+
+events = AgentEvents(tracer)  # tracer from the customer's configured provider
+with tracer.start_as_current_span("Review invoice") as parent:
+    parent.add_event("invoice.approved", {"customer.invoice.id": "INV-123"})
+    child = events.capture("Approval notification queued")
+    assert child.trace_id == parent.get_span_context().trace_id
+# The parent's context has now been restored to its outer context.
+```
+
+```typescript
+import { AgentEvents } from '@usefluency/workflow-telemetry';
+
+const events = new AgentEvents(tracer); // existing configured provider/context manager
+tracer.startActiveSpan('Review invoice', (parent) => {
+  try {
+    parent.addEvent('invoice.approved', { 'customer.invoice.id': 'INV-123' });
+    const child = events.capture('Approval notification queued');
+    // child.traceId === parent.spanContext().traceId
+  } finally {
+    parent.end();
+  }
+});
+```
+
+A span held in a variable is not necessarily active: Python `start_span()` and Node `startSpan()` do not activate it. Prefer your framework's active span or the native active-span APIs above. For an explicit parent, use Python `trace.use_span(parent, end_on_exit=False)` or Node `context.with(trace.setSpan(context.active(), parent), callback)`. The helper has no separate parent/trace-ID argument. Do not put trace IDs in attributes expecting them to change parentage.
+
+### Scoped attributes and async work
+
+Nested helper scopes override outer ones; per-call attributes override scoped attributes. Context restores on exit, including failures. Scoped values do not automatically enrich framework spans, native span events, or outbound baggage. Use `enrich()` on the relevant active span, or native attribute/event calls. Parent attributes do not automatically copy to child spans.
+
+Python contexts work across `await` in async functions. Node requires the application's context manager, normally installed by `NodeSDK` or `NodeTracerProvider.register()`. Await asynchronous work within the active-span scope. Detached work and HTTP/queue boundaries require the application's normal context propagation; the helper cannot reconstruct a missing parent from a run ID. Tasks deliberately started within a context can inherit it even if the parent ends before the task does.
+
+### Sampling and discrete actions
+
+Capture and ordinary spans use the same configured sampler and exporters. Capture does not bypass sampling, recover dropped spans, or create a Fluency-only delivery channel. Its returned context does not prove that a span was recorded or received. Both existing and Fluency destinations can receive helper spans and added attributes. Use destination-specific filtering if their permitted data differs.
+
+### Concurrency and nesting
+
+Use the active operation context to define parentage and helper scopes for repeated attributes. These are independent mechanisms: setting `fluency.run.id` does not start, join, deduplicate, or merge traces. Standard OTel network instrumentation or explicit propagation carries trace context across services. See [OpenTelemetry context and span creation](https://opentelemetry.io/docs/specs/otel/trace/api/).
+
+## Verify the integration
+
+Run the [packaged examples](examples/README.md), inspect exporter diagnostics, and share the region, UTC time and trace/span IDs with Fluency onboarding for receipt confirmation. Flush and shutdown are not acceptance receipts. Internal trace-inspection endpoints are not part of this SDK's customer API.
+
+## Design references
+
+Use the official [OTel tracing API](https://opentelemetry.io/docs/specs/otel/trace/api/) for parentage and span events, the [tracing SDK](https://opentelemetry.io/docs/specs/otel/trace/sdk/) for sampling/export/lifecycle, and the [OTLP exporter specification](https://opentelemetry.io/docs/specs/otel/protocol/exporter/) for endpoint configuration. Optional Fluency helpers preserve those semantics.
+
+<a id="what-appears-in-fluency"></a>
+<a id="what-fluency-provides"></a>
+<a id="choose-an-integration-path"></a>
+<a id="typescript-quick-start"></a>
+<a id="python-quick-start"></a>
+<a id="opentelemetry-and-other-frameworks"></a>
+<a id="send-from-an-existing-collector"></a>
+<a id="stable-ids-and-retries"></a>
+<a id="failed-operations"></a>
+<a id="content-controls"></a>
+<a id="runtime-behavior"></a>
+
+Integration tutorials and receiver limits now live in the [customer guide](https://docs.usefluency.com/fluency-workflow-telemetry-sdk) and [ingestion reference](https://docs.usefluency.com/fluency-workflow-telemetry-api).
+
+## Configured business helpers
+
+Python `configure(...)` returns `telemetry.events` bound to the selected provider. Standalone Node `configure(...)` returns `telemetry.events` bound to the provider it creates. Node `createSpanProcessor()` does not own a provider: construct `new AgentEvents(provider.getTracer('your-application'))` after creating your application provider.
+
+`enrich` updates an active or explicitly supplied recording span. `capture` creates and ends a separate span. Python `capture(name, attributes=..., parent=span)` and TypeScript `capture(name, attributes, span)` accept an explicit parent. When omitted, the active OTel context supplies the parent. Supplying a parent does not activate or end that span. It is useful for framework callback spans, such as LangChain's `get_current_span()`.
+
+A native span event is an annotation on its containing span. Captured action spans have their own identity and use ordinary provider sampling and export. A returned span context is not a delivery receipt.
+
+Choose your framework in the [integration guides](https://docs.usefluency.com/fluency-workflow-telemetry-sdk) for a complete runnable example and existing-provider setup.

fluency_workflow_telemetry/docs/examples/README.md

@@ -0,0 +1,92 @@
+# Workflow telemetry examples
+
+## Overview
+
+Start with the example that matches your application. Customer walkthroughs live in [Fluency's integration guides](https://docs.usefluency.com/fluency-workflow-telemetry-sdk).
+
+## Setup
+
+Install `usefluency-workflow-telemetry` for Python 3.12+, or `@usefluency/workflow-telemetry` for Node.js 24+. Supply `FLUENCY_OTLP_TRACES_ENDPOINT` and `FLUENCY_WORKFLOW_API_KEY` through your application's environment. See [environment.example](environment.example).
+
+TypeScript examples use an ESM application (`"type": "module"` in `package.json`). Install `@opentelemetry/api` and the OTel SDK packages imported by an example when using provider-level examples.
+
+## Choose an example
+
+| Example                                         | What it demonstrates                                                                                                                                                                |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `langchain-agent.py`                            | LangChain's LangGraph-backed agent reviews an invoice. OpenInference captures model/tools; explicit tool parentage attaches business context and approval to the correct operation. |
+| `vercel-agent.ts`                               | Vercel AI SDK model/tool calls, concurrent runs, streaming, and business capture inside a tool.                                                                                     |
+| `openai-agent.py`                               | OpenAI Agents runs and tools, retaining existing Agents tracing processors.                                                                                                         |
+| `openai-client.py`                              | Direct OpenAI Responses calls and streaming, recording business completion only after a completed response.                                                                         |
+| `rpa.py` / `rpa.ts`                             | A custom automation posts an invoice: timed run, ERP step, and successful business action. Replace the demo callback with your ERP operation.                                       |
+| `agent-events.py` / `agent-events.ts`           | Concurrent runs, scoped business attributes, and a handled policy failure.                                                                                                          |
+| `capture-context.py` / `capture-context.ts`     | Native span annotation, child capture, and standalone capture; checks the trace relationships.                                                                                      |
+| `existing-provider.py` / `existing-provider.ts` | Add a Fluency destination while retaining an existing exporter. Python also demonstrates using native OTel without the Fluency SDK.                                                 |
+| `workflow.py` / `workflow.ts`                   | Minimal native OTel root/child instrumentation and an approval annotation.                                                                                                          |
+| `pydantic-agent.py`                             | Existing Pydantic AI example using a deterministic test model, tool instrumentation, and business capture.                                                                          |
+
+The files are included in npm's `examples/` directory and Python's `fluency_workflow_telemetry/docs/examples/` directory. Copy the selected example into your application directory so it resolves your installed dependencies.
+
+## LangChain and LangGraph
+
+```sh
+pip install usefluency-workflow-telemetry openinference-instrumentation-langchain langchain langgraph langchain-openai
+python langchain-agent.py
+```
+
+Set `OPENAI_API_KEY` and `OPENAI_MODEL` for this example. Use a model available to your account that supports tools. The approval function is illustrative: perform actual policy checks before recording approval. Keep your existing model/provider configuration when adding telemetry to a real agent.
+
+The release tests pin LangChain 1.4.6, LangGraph 1.2.15, langchain-openai 1.7.2, OpenAI 3.31.0, and OpenInference LangChain 0.1.79. These dependencies are optional; the core SDK does not install them. See [the customer guide](https://docs.usefluency.com/fluency-workflow-telemetry-langchain) for new/existing provider setup.
+
+## Vercel AI SDK
+
+```sh
+npm install @usefluency/workflow-telemetry ai@^7 @ai-sdk/otel@^1 @ai-sdk/openai@^4 @opentelemetry/api
+npm install --save-dev @types/json-schema
+node vercel-agent.ts
+```
+
+Set `OPENAI_API_KEY` and `OPENAI_MODEL`. The example uses AI SDK 7's `registerTelemetry(new OpenTelemetry())` and a demo approval tool; replace it with actual validation and approval before recording success. Keep existing model/gateway configuration in your application. The release test pins AI SDK 7.0.142, `@ai-sdk/otel` 1.0.142 and `@ai-sdk/openai` 4.0.95. See [the customer guide](https://docs.usefluency.com/fluency-workflow-telemetry-vercel) for existing providers and Next.js startup.
+
+## OpenAI Python
+
+For direct Responses API calls:
+
+```sh
+pip install usefluency-workflow-telemetry openai openinference-instrumentation-openai
+python openai-client.py
+```
+
+For OpenAI Agents SDK:
+
+```sh
+pip install usefluency-workflow-telemetry openai-agents openinference-instrumentation-openai-agents
+python openai-agent.py
+```
+
+Both examples use `OPENAI_API_KEY` and `OPENAI_MODEL`. The Agents bridge uses `exclusive_processor=False` to retain existing Agents tracing processors. Do not also instrument its underlying OpenAI client just for this integration. The direct-client example includes `stream_review`; consume it inside `contextlib.aclosing` so stopping early closes the operation without recording success.
+
+Release tests pin OpenAI 3.31.0, Agents 0.24.0, OpenInference OpenAI 0.1.65 and OpenInference Agents 2.5.3. These remain optional dependencies. The [OpenAI guide](https://docs.usefluency.com/fluency-workflow-telemetry-openai) covers both [direct API calls](https://docs.usefluency.com/fluency-workflow-telemetry-openai#direct-api-calls) and the [Agents SDK](https://docs.usefluency.com/fluency-workflow-telemetry-openai#agents-sdk), each with new/existing tracing setup.
+
+## RPA and custom workflows
+
+```sh
+python rpa.py
+node rpa.ts
+```
+
+These examples need no model credentials. A successful run produces `Post invoice` with `Submit to ERP` and `Invoice posted` children. The release test also injects an ERP failure and verifies that exceptions reach the caller and success is not recorded.
+
+## Other examples
+
+Run `python <example>.py` or `node <example>.ts`. For `pydantic-agent.py`, also install `pydantic-ai-slim==2.55.0`; its `TestModel` makes no paid request.
+
+[collector.yaml](collector.yaml) is a merge fragment for an existing Collector configuration. It has not been tested as a live Collector deployment.
+
+## Lifecycle and verification
+
+Configure once at startup. Keep streaming work inside the operation's scope, await in-flight work, and shut down before a script exits. In an async Python service shutdown hook, use `await asyncio.to_thread(telemetry.shutdown)`. Reusable serverless processes should flush at invocation completion rather than permanently shutting down after each invocation.
+
+The release smoke test installs the npm package, wheel, and source distribution in clean environments. It exercises native examples, helpers, LangChain, Vercel AI, OpenAI and RPA through a local OTLP receiver and decodes the requests to verify business context and parentage. Framework tests use real libraries with deterministic model responses; new and existing providers are exercised in separate processes. They also check that an existing exporter remains usable after Fluency shuts down.
+
+The suite does not establish production receipt, live-model behavior, Collector deployment, Next.js deployment, OpenAI Agents streaming, or distributed HTTP/queue propagation. Use your Fluency contact to confirm a first run against your organization's regional endpoint.

fluency_workflow_telemetry/docs/examples/agent-events.py

@@ -0,0 +1,44 @@
+"""Capture concurrent agent actions and a handled failure using synthetic data."""
+
+import asyncio
+
+from fluency_workflow_telemetry import AgentEvents, configure
+
+
+def check_policy(invoice_id):
+  if invoice_id == "invoice-b":
+    raise ValueError("Synthetic policy lookup failure")
+
+
+async def main():
+  telemetry = configure(service_name="invoice-agent")
+  events = AgentEvents(telemetry.provider.get_tracer("invoice-example"))
+
+  async def review(invoice_id):
+    with events.context({"fluency.run.id": invoice_id}), events.span("Review invoice"):
+      await asyncio.sleep(0)
+      try:
+        with events.span("Check policy"):
+          check_policy(invoice_id)
+      except ValueError:
+        outcome = "escalated"
+      else:
+        outcome = "approved"
+      events.capture(
+        "Invoice decision",
+        attributes={
+          "fluency.artifact.source": "erp:demo:invoices",
+          "fluency.artifact.external_id": invoice_id,
+          "fluency.artifact.type": "invoice",
+          "fluency.outcome": outcome,
+        },
+      )
+
+  try:
+    await asyncio.gather(review("invoice-a"), review("invoice-b"))
+  finally:
+    await asyncio.to_thread(telemetry.shutdown)
+
+
+if __name__ == "__main__":
+  asyncio.run(main())