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

fluency_workflow_telemetry/docs/examples/agent-events.ts

@@ -0,0 +1,31 @@
+import { AgentEvents, configure } from '@usefluency/workflow-telemetry';
+
+const telemetry = configure({ serviceName: 'invoice-agent' });
+const events = new AgentEvents(telemetry.provider.getTracer('invoice-example'));
+try {
+  await Promise.all(
+    ['invoice-a', 'invoice-b'].map((invoiceId) =>
+      events.withContext({ 'fluency.run.id': invoiceId }, () =>
+        events.trace('Review invoice', async () => {
+          await Promise.resolve();
+          let outcome = 'approved';
+          try {
+            await events.trace('Check policy', () => {
+              if (invoiceId === 'invoice-b') throw new Error('Synthetic policy lookup failure');
+            });
+          } catch {
+            outcome = 'escalated';
+          }
+          events.capture('Invoice decision', {
+            'fluency.artifact.source': 'erp:demo:invoices',
+            'fluency.artifact.external_id': invoiceId,
+            'fluency.artifact.type': 'invoice',
+            'fluency.outcome': outcome,
+          });
+        })
+      )
+    )
+  );
+} finally {
+  await telemetry.shutdown();
+}

fluency_workflow_telemetry/docs/examples/capture-context.py

@@ -0,0 +1,41 @@
+"""Compare a native span event, a captured child, and capture without a parent."""
+
+from fluency_workflow_telemetry import AgentEvents, configure
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+
+def main():
+  existing = InMemorySpanExporter()
+  provider = TracerProvider(resource=Resource.create({"service.name": "existing-invoice-agent"}))
+  provider.add_span_processor(SimpleSpanProcessor(existing))
+  telemetry = configure(provider=provider)
+  tracer = provider.get_tracer("customer-instrumentation")
+  events = AgentEvents(tracer)
+  try:
+    with tracer.start_as_current_span("Review invoice") as parent:
+      parent.set_attribute("customer.invoice.id", "invoice-context")
+      parent.add_event("invoice.approved", {"customer.invoice.id": "invoice-context"})
+      child = events.capture("Approval notification queued", attributes={"customer.invoice.id": "invoice-context"})
+      assert child.trace_id == parent.get_span_context().trace_id
+      assert child.span_id != parent.get_span_context().span_id
+      assert trace.get_current_span() is parent
+      # A child is already ended; the parent and its annotation are still open.
+      assert len(existing.get_finished_spans()) == 1
+
+    standalone = events.capture("Standalone reconciliation")
+    assert standalone.trace_id != child.trace_id
+    spans = {span.name: span for span in existing.get_finished_spans()}
+    assert spans["Approval notification queued"].parent.span_id == parent.get_span_context().span_id
+    assert spans["Standalone reconciliation"].parent is None
+    assert spans["Review invoice"].events[0].name == "invoice.approved"
+  finally:
+    telemetry.shutdown()
+    provider.shutdown()
+
+
+if __name__ == "__main__":
+  main()

fluency_workflow_telemetry/docs/examples/capture-context.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { trace } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { AgentEvents, createSpanProcessor } from '@usefluency/workflow-telemetry';
+
+const existing = new InMemorySpanExporter();
+const telemetry = createSpanProcessor();
+const provider = new NodeTracerProvider({
+  resource: resourceFromAttributes({ 'service.name': 'existing-invoice-agent' }),
+  spanProcessors: [new SimpleSpanProcessor(existing), telemetry.processor],
+});
+provider.register();
+const tracer = provider.getTracer('customer-instrumentation');
+const events = new AgentEvents(tracer);
+try {
+  const child = await tracer.startActiveSpan('Review invoice', async (parent) => {
+    try {
+      await Promise.resolve();
+      parent.setAttribute('customer.invoice.id', 'invoice-context');
+      parent.addEvent('invoice.approved', { 'customer.invoice.id': 'invoice-context' });
+      const captured = events.capture('Approval notification queued', { 'customer.invoice.id': 'invoice-context' });
+      assert.equal(captured.traceId, parent.spanContext().traceId);
+      assert.notEqual(captured.spanId, parent.spanContext().spanId);
+      assert.equal(trace.getActiveSpan(), parent);
+      // The captured child ends without ending the customer's active operation.
+      assert.equal(existing.getFinishedSpans().length, 1);
+      return captured;
+    } finally {
+      parent.end();
+    }
+  });
+  const standalone = events.capture('Standalone reconciliation');
+  assert.notEqual(standalone.traceId, child.traceId);
+  const spans = existing.getFinishedSpans();
+  const parent = spans.find((span) => span.name === 'Review invoice')!;
+  assert.equal(
+    spans.find((span) => span.name === 'Approval notification queued')!.parentSpanContext?.spanId,
+    parent.spanContext().spanId
+  );
+  assert.equal(spans.find((span) => span.name === 'Standalone reconciliation')!.parentSpanContext, undefined);
+  assert.equal(parent.events[0].name, 'invoice.approved');
+} finally {
+  await telemetry.shutdown();
+  await provider.shutdown();
+}

fluency_workflow_telemetry/docs/examples/collector.yaml

@@ -0,0 +1,9 @@
+# Merge this exporter into the customer's existing Collector configuration.
+exporters:
+  otlp_http/fluency:
+    traces_endpoint: ${env:FLUENCY_OTLP_TRACES_ENDPOINT}
+    headers:
+      Authorization: Bearer ${env:FLUENCY_WORKFLOW_API_KEY}
+# Append otlp_http/fluency to the existing service.pipelines.traces.exporters list.
+# Keep the existing destinations. Use a separate traces pipeline if Fluency needs
+# its own filtering or redaction; do not apply it to the customer's other exports.

fluency_workflow_telemetry/docs/examples/environment.example

@@ -0,0 +1,2 @@
+FLUENCY_OTLP_TRACES_ENDPOINT=https://YOUR-REGIONAL-ENDPOINT/ext/otel/v1/traces
+FLUENCY_WORKFLOW_API_KEY=

fluency_workflow_telemetry/docs/examples/existing-provider.py

@@ -0,0 +1,35 @@
+"""Native OTel only: keep an existing destination and add Fluency export."""
+
+import os
+
+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, SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+
+def main():
+  # This setup represents the customer's existing provider and exporter.
+  existing = InMemorySpanExporter()
+  provider = TracerProvider(resource=Resource.create({"service.name": "existing-invoice-agent"}))
+  provider.add_span_processor(SimpleSpanProcessor(existing))
+  provider.add_span_processor(
+    BatchSpanProcessor(
+      OTLPSpanExporter(
+        endpoint=os.environ["FLUENCY_OTLP_TRACES_ENDPOINT"], headers={"Authorization": f"Bearer {os.environ['FLUENCY_WORKFLOW_API_KEY']}"}
+      )
+    )
+  )
+  try:
+    with provider.get_tracer("existing-instrumentation").start_as_current_span("Native invoice action") as span:
+      span.set_attribute("fluency.artifact.external_id", "invoice-native")
+      span.set_attribute("fluency.outcome", "approved")
+    provider.force_flush()
+    assert len(existing.get_finished_spans()) == 1
+  finally:
+    provider.shutdown()
+
+
+if __name__ == "__main__":
+  main()

fluency_workflow_telemetry/docs/examples/existing-provider.ts

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { AgentEvents, createSpanProcessor } from '@usefluency/workflow-telemetry';
+
+// Add the Fluency processor where the application constructs its provider.
+const existing = new InMemorySpanExporter();
+const fluency = createSpanProcessor();
+const provider = new NodeTracerProvider({
+  resource: resourceFromAttributes({ 'service.name': 'existing-invoice-agent' }),
+  spanProcessors: [new SimpleSpanProcessor(existing), fluency.processor],
+});
+provider.register();
+try {
+  const tracer = provider.getTracer('existing-instrumentation');
+  const events = new AgentEvents(tracer);
+  tracer.startActiveSpan('Native invoice action', (span) => {
+    events.enrich({ 'fluency.artifact.external_id': 'invoice-native', 'fluency.outcome': 'approved' });
+    span.end();
+  });
+  await fluency.shutdown();
+  assert.equal(existing.getFinishedSpans().length, 1);
+  tracer.startSpan('Existing destination still active').end();
+  assert.equal(existing.getFinishedSpans().length, 2);
+} finally {
+  await provider.shutdown();
+}

fluency_workflow_telemetry/docs/examples/langchain-agent.py

@@ -0,0 +1,37 @@
+"""Capture a LangChain/LangGraph invoice agent and its business outcome."""
+
+import asyncio
+import os
+
+from fluency_workflow_telemetry import configure
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+from openinference.instrumentation.langchain import LangChainInstrumentor, get_current_span
+
+
+async def review_invoice(model, events, invoice_id):
+  def approve_invoice() -> str:
+    """Approve the invoice after validating its purchase order."""
+    # LangChain's callback span is not necessarily the active OTel span.
+    tool_span = get_current_span()
+    events.enrich({"fluency.artifact.external_id": invoice_id, "fluency.artifact.source": "erp:invoices"}, span=tool_span)
+    events.capture("Invoice approved", parent=tool_span, attributes={"fluency.outcome": "approved", "fluency.artifact.external_id": invoice_id})
+    return "Approved"
+
+  agent = create_agent(model, tools=[approve_invoice])
+  with events.span("Review invoice", attributes={"fluency.run.id": invoice_id, "fluency.artifact.external_id": invoice_id}):
+    return await agent.ainvoke({"messages": [{"role": "user", "content": f"Approve invoice {invoice_id} using the approval tool."}]})
+
+
+async def main():
+  telemetry = configure(service_name="invoice-agent")
+  LangChainInstrumentor().instrument(tracer_provider=telemetry.provider)
+  try:
+    model = ChatOpenAI(model=os.environ["OPENAI_MODEL"])
+    await review_invoice(model, telemetry.events, "INV-1042")
+  finally:
+    telemetry.shutdown()
+
+
+if __name__ == "__main__":
+  asyncio.run(main())

fluency_workflow_telemetry/docs/examples/openai-agent.py

@@ -0,0 +1,35 @@
+"""Capture OpenAI Agents runs alongside their existing tracing processors."""
+
+import asyncio
+import os
+
+from agents import Agent, Runner, function_tool
+from fluency_workflow_telemetry import configure
+from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
+
+
+async def review_invoice(model, events, invoice_id):
+  @function_tool
+  def approve_invoice() -> str:
+    """Approve the invoice after validating its purchase order."""
+    events.enrich({"fluency.artifact.external_id": invoice_id})
+    events.capture("Invoice approved", attributes={"fluency.artifact.external_id": invoice_id, "fluency.outcome": "approved"})
+    return "Approved"
+
+  agent = Agent(name="Invoice reviewer", instructions="Use the approval tool to approve the invoice.", model=model, tools=[approve_invoice])
+  with events.span("Review invoice", attributes={"fluency.run.id": invoice_id, "fluency.artifact.external_id": invoice_id}):
+    return await Runner.run(agent, f"Approve invoice {invoice_id}")
+
+
+async def main():
+  telemetry = configure(service_name="invoice-agent")
+  # The instrumentor defaults to replacing existing Agents tracing processors.
+  OpenAIAgentsInstrumentor().instrument(tracer_provider=telemetry.provider, exclusive_processor=False)
+  try:
+    await review_invoice(os.environ["OPENAI_MODEL"], telemetry.events, "INV-1042")
+  finally:
+    await asyncio.to_thread(telemetry.shutdown)
+
+
+if __name__ == "__main__":
+  asyncio.run(main())

fluency_workflow_telemetry/docs/examples/openai-client.py

@@ -0,0 +1,43 @@
+"""Capture direct OpenAI Responses API calls inside an invoice workflow."""
+
+import asyncio
+import os
+
+from fluency_workflow_telemetry import configure
+from openai import AsyncOpenAI
+from openinference.instrumentation.openai import OpenAIInstrumentor
+
+
+async def review_invoice(client, events, model, invoice_id):
+  with events.span("Review invoice", attributes={"fluency.artifact.external_id": invoice_id}):
+    response = await client.responses.create(model=model, input="Summarize the checks needed before approving this invoice.")
+    if response.status != "completed":
+      raise RuntimeError(f"Invoice review did not complete: {response.status}")
+    events.capture("Invoice review prepared", attributes={"fluency.artifact.external_id": invoice_id, "fluency.outcome": "ready_for_review"})
+    return response.output_text
+
+
+async def stream_review(client, events, model, invoice_id):
+  with events.span("Review invoice", attributes={"fluency.artifact.external_id": invoice_id}):
+    async with client.responses.stream(model=model, input="Summarize the checks needed before approving this invoice.") as stream:
+      async for event in stream:
+        if event.type == "response.output_text.delta":
+          yield event.delta
+      response = await stream.get_final_response()
+      if response.status != "completed":
+        raise RuntimeError(f"Invoice review did not complete: {response.status}")
+    events.capture("Invoice review prepared", attributes={"fluency.artifact.external_id": invoice_id, "fluency.outcome": "ready_for_review"})
+
+
+async def main():
+  telemetry = configure(service_name="invoice-agent")
+  OpenAIInstrumentor().instrument(tracer_provider=telemetry.provider)
+  try:
+    async with AsyncOpenAI() as client:
+      await review_invoice(client, telemetry.events, os.environ["OPENAI_MODEL"], "INV-1042")
+  finally:
+    await asyncio.to_thread(telemetry.shutdown)
+
+
+if __name__ == "__main__":
+  asyncio.run(main())

fluency_workflow_telemetry/docs/examples/pydantic-agent.py

@@ -0,0 +1,40 @@
+"""Pydantic AI integration without model credentials; TestModel exercises a real tool."""
+
+from fluency_workflow_telemetry import AgentEvents, configure
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from pydantic_ai import Agent
+from pydantic_ai.capabilities import Instrumentation
+from pydantic_ai.models.instrumented import InstrumentationSettings
+from pydantic_ai.models.test import TestModel
+
+
+def main():
+  existing = InMemorySpanExporter()
+  provider = TracerProvider(resource=Resource.create({"service.name": "invoice-agent-pydantic"}))
+  provider.add_span_processor(SimpleSpanProcessor(existing))
+  telemetry = configure(provider=provider)
+  events = AgentEvents(provider.get_tracer("invoice-example"))
+  agent = Agent(TestModel(), capabilities=[Instrumentation(settings=InstrumentationSettings(tracer_provider=provider, include_content=False))])
+
+  @agent.tool_plain
+  def approve_invoice() -> str:
+    events.enrich({"fluency.artifact.source": "erp:demo:invoices", "fluency.artifact.external_id": "invoice-pydantic"})
+    events.capture("Invoice approved", attributes={"fluency.outcome": "approved"})
+    return "approved"
+
+  try:
+    with events.context({"fluency.run.id": "run-pydantic"}):
+      agent.run_sync("Approve the synthetic invoice")
+    telemetry.flush()
+    assert any(span.attributes.get("gen_ai.operation.name") == "execute_tool" for span in existing.get_finished_spans())
+    assert any(span.name == "Invoice approved" for span in existing.get_finished_spans())
+  finally:
+    telemetry.shutdown()
+    provider.shutdown()
+
+
+if __name__ == "__main__":
+  main()

fluency_workflow_telemetry/docs/examples/rpa.py

@@ -0,0 +1,20 @@
+"""Record an ERP posting workflow without an AI framework or model credentials."""
+
+from fluency_workflow_telemetry import configure
+
+
+def post_invoice(events, invoice_id, post_to_erp):
+  with events.span("Post invoice", attributes={"fluency.run.id": invoice_id, "fluency.artifact.external_id": invoice_id}):
+    with events.span("Submit to ERP"):
+      erp_id = post_to_erp(invoice_id)
+    events.capture("Invoice posted", attributes={"fluency.outcome": "posted", "erp.document_id": erp_id})
+    return erp_id
+
+
+if __name__ == "__main__":
+  telemetry = configure(service_name="invoice-rpa")
+  try:
+    # Replace this demo callback with your bot's existing ERP operation.
+    post_invoice(telemetry.events, "INV-1042", lambda invoice_id: f"ERP-{invoice_id}")
+  finally:
+    telemetry.shutdown()

fluency_workflow_telemetry/docs/examples/rpa.ts

@@ -0,0 +1,25 @@
+import { pathToFileURL } from 'node:url';
+import { configure } from '@usefluency/workflow-telemetry';
+import type { AgentEvents } from '@usefluency/workflow-telemetry';
+
+export async function postInvoice(events: AgentEvents, invoiceId: string, postToErp: (id: string) => Promise<string>) {
+  return events.trace(
+    'Post invoice',
+    async () => {
+      const erpId = await events.trace('Submit to ERP', () => postToErp(invoiceId));
+      events.capture('Invoice posted', { 'fluency.outcome': 'posted', 'erp.document_id': erpId });
+      return erpId;
+    },
+    { 'fluency.run.id': invoiceId, 'fluency.artifact.external_id': invoiceId }
+  );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const telemetry = configure({ serviceName: 'invoice-rpa' });
+  try {
+    // Replace the demo callback with your bot's existing ERP operation.
+    await postInvoice(telemetry.events, 'INV-1042', async (id) => `ERP-${id}`);
+  } finally {
+    await telemetry.shutdown();
+  }
+}

fluency_workflow_telemetry/docs/examples/vercel-agent.ts

@@ -0,0 +1,65 @@
+import { pathToFileURL } from 'node:url';
+import { openai } from '@ai-sdk/openai';
+import { OpenTelemetry } from '@ai-sdk/otel';
+import { generateText, registerTelemetry, stepCountIs, streamText, tool, jsonSchema } from 'ai';
+import type { LanguageModel } from 'ai';
+import { configure } from '@usefluency/workflow-telemetry';
+import type { AgentEvents } from '@usefluency/workflow-telemetry';
+
+export async function reviewInvoice(model: LanguageModel, events: AgentEvents, invoiceId: string) {
+  return events.trace(
+    'Review invoice',
+    async () => {
+      const result = await generateText({
+        model,
+        prompt: `Approve invoice ${invoiceId} using the approval tool.`,
+        stopWhen: stepCountIs(3),
+        tools: {
+          approveInvoice: tool({
+            description: 'Approve the invoice after checking its purchase order.',
+            inputSchema: jsonSchema<Record<string, never>>({
+              type: 'object',
+              properties: {},
+              additionalProperties: false,
+            }),
+            execute: () => {
+              events.enrich({ 'fluency.artifact.external_id': invoiceId });
+              events.capture('Invoice approved', {
+                'fluency.artifact.external_id': invoiceId,
+                'fluency.outcome': 'approved',
+              });
+              return { approved: true };
+            },
+          }),
+        },
+      });
+      return result.text;
+    },
+    { 'fluency.run.id': invoiceId, 'fluency.artifact.external_id': invoiceId }
+  );
+}
+
+export async function summarizeInvoice(model: LanguageModel, events: AgentEvents, invoiceId: string) {
+  return events.trace(
+    'Summarize invoice',
+    async () => {
+      const result = streamText({ model, prompt: `Summarize the review for invoice ${invoiceId}.` });
+      let text = '';
+      // Consume the stream before ending the operation or flushing telemetry.
+      for await (const chunk of result.textStream) text += chunk;
+      return text;
+    },
+    { 'fluency.artifact.external_id': invoiceId }
+  );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const telemetry = configure({ serviceName: 'invoice-agent' });
+  registerTelemetry(new OpenTelemetry());
+  try {
+    if (!process.env.OPENAI_MODEL) throw new Error('Set OPENAI_MODEL to a model available to your account');
+    await reviewInvoice(openai(process.env.OPENAI_MODEL), telemetry.events, 'INV-1042');
+  } finally {
+    await telemetry.shutdown();
+  }
+}

fluency_workflow_telemetry/docs/examples/workflow.py

@@ -0,0 +1,19 @@
+"""Emit synthetic workflow evidence with standard OpenTelemetry APIs."""
+
+from fluency_workflow_telemetry import configure
+
+
+def main() -> None:
+  telemetry = configure(service_name="invoice-worker")
+  tracer = telemetry.provider.get_tracer("invoice-workflow-example")
+  try:
+    with tracer.start_as_current_span("Process invoice", attributes={"customer.invoice.id": "invoice-example"}) as workflow:
+      with tracer.start_as_current_span("Validate invoice"):
+        pass
+      workflow.add_event("approval", {"outcome": "approved"})
+  finally:
+    telemetry.shutdown()
+
+
+if __name__ == "__main__":
+  main()

fluency_workflow_telemetry/docs/examples/workflow.ts

@@ -0,0 +1,20 @@
+import { configure } from '@usefluency/workflow-telemetry';
+
+const telemetry = configure({ serviceName: 'invoice-worker' });
+const tracer = telemetry.provider.getTracer('invoice-workflow-example');
+try {
+  tracer.startActiveSpan(
+    'Process invoice',
+    { attributes: { 'customer.invoice.id': 'invoice-example' } },
+    (workflow) => {
+      try {
+        tracer.startActiveSpan('Validate invoice', (step) => step.end());
+        workflow.addEvent('approval', { outcome: 'approved' });
+      } finally {
+        workflow.end();
+      }
+    }
+  );
+} finally {
+  await telemetry.shutdown();
+}

fluency_workflow_telemetry/events.py

@@ -0,0 +1,59 @@
+"""Optional agent-event instrumentation using the application's OpenTelemetry tracer."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from importlib.metadata import version
+from time import time_ns
+from typing import TYPE_CHECKING
+
+from opentelemetry import trace
+
+if TYPE_CHECKING:
+  from collections.abc import Iterator, Mapping
+
+  from opentelemetry.trace import Span, SpanContext, Tracer
+  from opentelemetry.util.types import AttributeValue
+
+
+class AgentEvents:
+  """Capture spans without installing or replacing a provider, sampler or exporter."""
+
+  def __init__(self, tracer: Tracer | None = None) -> None:
+    self._tracer = tracer if tracer is not None else trace.get_tracer("usefluency-workflow-telemetry", version("usefluency-workflow-telemetry"))
+    self._context: ContextVar[Mapping[str, AttributeValue] | None] = ContextVar("fluency.agent-events.attributes", default=None)
+
+  def _attributes(self, attributes: Mapping[str, AttributeValue] | None) -> dict[str, AttributeValue]:
+    return {**(self._context.get() or {}), **(attributes or {})}
+
+  @contextmanager
+  def context(self, attributes: Mapping[str, AttributeValue]) -> Iterator[None]:
+    """Scope attributes to this helper instance; never add them to outbound baggage."""
+    token = self._context.set(self._attributes(attributes))
+    try:
+      yield
+    finally:
+      self._context.reset(token)
+
+  def enrich(self, attributes: Mapping[str, AttributeValue], *, span: Span | None = None) -> bool:
+    """Return False if no recording span exists; never create a replacement span."""
+    target = span if span is not None else trace.get_current_span()
+    if not target.is_recording():
+      return False
+    target.set_attributes(self._attributes(attributes))
+    return True
+
+  def capture(self, name: str, *, attributes: Mapping[str, AttributeValue] | None = None, parent: Span | None = None) -> SpanContext:
+    """Record a point-in-time action as a completed span under the current parent."""
+    timestamp = time_ns()
+    context = trace.set_span_in_context(parent) if parent is not None else None
+    span = self._tracer.start_span(name, context=context, attributes=self._attributes(attributes), start_time=timestamp)
+    span.end(end_time=timestamp)
+    return span.get_span_context()
+
+  @contextmanager
+  def span(self, name: str, *, attributes: Mapping[str, AttributeValue] | None = None) -> Iterator[Span]:
+    """Use inside sync or async functions; keep streaming work inside the block."""
+    with self._tracer.start_as_current_span(name, attributes=self._attributes(attributes)) as span:
+      yield span

usefluency_workflow_telemetry-0.1.1.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: usefluency-workflow-telemetry
+Version: 0.1.1
+License: Proprietary
+Classifier: License :: Other/Proprietary License
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api<2,>=1.42
+Requires-Dist: opentelemetry-sdk<2,>=1.42
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.42
+Dynamic: license-file
+
+# 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).