Metadata-Version: 2.5
Name: lumenova-beacon
Version: 2.18.0
Summary: Lumenova Beacon SDK - A Python SDK for observability tracing with OpenTelemetry-compatible span export
Project-URL: Homepage, https://lumenova.ai
Author-email: Lumenova AI <support@lumenova.ai>
Maintainer-email: Lumenova AI <support@lumenova.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,langchain,llm,monitoring,observability,opentelemetry,sdk,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: tenacity>=8.1.0
Provides-Extra: aws
Requires-Dist: boto3>=1.20.0; extra == 'aws'
Provides-Extra: crewai
Requires-Dist: crewai>=0.28.0; extra == 'crewai'
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'crewai'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'crewai'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'crewai'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: ipython>=8.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
Provides-Extra: examples
Requires-Dist: anthropic>=0.40.0; extra == 'examples'
Requires-Dist: boto3>=1.20.0; extra == 'examples'
Requires-Dist: crewai>=0.28.0; extra == 'examples'
Requires-Dist: faiss-cpu>=1.13.1; extra == 'examples'
Requires-Dist: fastapi>=0.115.0; extra == 'examples'
Requires-Dist: fastmcp<4,>=3.0; extra == 'examples'
Requires-Dist: google-genai>=1.0.0; extra == 'examples'
Requires-Dist: langchain-anthropic>=0.3.0; extra == 'examples'
Requires-Dist: langchain-community>=0.4.1; extra == 'examples'
Requires-Dist: langchain-core>=0.3.0; extra == 'examples'
Requires-Dist: langchain-openai>=1.1.5; extra == 'examples'
Requires-Dist: langchain>=1.0.0; extra == 'examples'
Requires-Dist: langgraph>=1.0.5; extra == 'examples'
Requires-Dist: litellm>=1.50.0; extra == 'examples'
Requires-Dist: llama-index-core>=0.12.3; extra == 'examples'
Requires-Dist: llama-index-embeddings-azure-openai>=0.3.0; extra == 'examples'
Requires-Dist: llama-index-llms-azure-openai>=0.3.0; extra == 'examples'
Requires-Dist: openai>=1.0.0; extra == 'examples'
Requires-Dist: openinference-instrumentation-google-genai>=0.1.0; extra == 'examples'
Requires-Dist: openinference-instrumentation-llama-index>=4.3.8; extra == 'examples'
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'examples'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'examples'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation-anthropic>=0.1.0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation-fastapi<1.0,>=0.59b0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation-httpx<1.0,>=0.59b0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation-openai>=0.1.0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation-redis<1.0,>=0.59b0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation-requests<1.0,>=0.59b0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation<1.0,>=0.59b0; extra == 'examples'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'examples'
Requires-Dist: python-dotenv>=1.0.0; extra == 'examples'
Requires-Dist: redis>=5.0.0; extra == 'examples'
Requires-Dist: requests>=2.31.0; extra == 'examples'
Requires-Dist: strands-agents-tools>=0.2.0; extra == 'examples'
Requires-Dist: strands-agents>=1.15.0; extra == 'examples'
Requires-Dist: temporalio<2,>=1.26; extra == 'examples'
Provides-Extra: fastapi
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'fastapi'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'fastapi'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'fastapi'
Requires-Dist: opentelemetry-instrumentation-fastapi<1.0,>=0.59b0; extra == 'fastapi'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'fastapi'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'langchain'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'langchain'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'langchain'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'langchain'
Provides-Extra: litellm
Requires-Dist: litellm>=1.50.0; extra == 'litellm'
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'litellm'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'litellm'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'litellm'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'litellm'
Provides-Extra: mcp
Requires-Dist: fastmcp<4,>=3.0; extra == 'mcp'
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'mcp'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'mcp'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'mcp'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'mcp'
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'opentelemetry'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'opentelemetry'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'opentelemetry'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'opentelemetry'
Provides-Extra: strands
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'strands'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'strands'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'strands'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'strands'
Requires-Dist: strands-agents>=1.15.0; extra == 'strands'
Provides-Extra: temporal
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'temporal'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'temporal'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'temporal'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'temporal'
Requires-Dist: temporalio<2,>=1.26; extra == 'temporal'
Provides-Extra: test
Requires-Dist: boto3>=1.20.0; extra == 'test'
Requires-Dist: crewai>=0.28.0; extra == 'test'
Requires-Dist: fastmcp<4,>=3.0; extra == 'test'
Requires-Dist: ipython>=8.0.0; extra == 'test'
Requires-Dist: langchain-core>=0.3.0; extra == 'test'
Requires-Dist: mypy>=1.0.0; extra == 'test'
Requires-Dist: opentelemetry-api<2.0,>=1.38.0; extra == 'test'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.38.0; extra == 'test'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.38.0; extra == 'test'
Requires-Dist: opentelemetry-instrumentation-fastapi<1.0,>=0.59b0; extra == 'test'
Requires-Dist: opentelemetry-sdk<2.0,>=1.38.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: respx>=0.20.0; extra == 'test'
Requires-Dist: ruff<0.16,>=0.15; extra == 'test'
Requires-Dist: strands-agents>=1.15.0; extra == 'test'
Requires-Dist: temporalio<2,>=1.26; extra == 'test'
Description-Content-Type: text/markdown

# Lumenova Beacon SDK

[![PyPI version](https://img.shields.io/pypi/v/lumenova-beacon.svg)](https://pypi.org/project/lumenova-beacon/)
[![Python Versions](https://img.shields.io/pypi/pyversions/lumenova-beacon.svg)](https://pypi.org/project/lumenova-beacon/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> A Python observability SDK for AI/LLM applications — trace agentic frameworks (LangChain, LangGraph, CrewAI, Strands, MCP, Temporal), LLM calls, and custom code with OpenTelemetry-compatible spans.

## Features

- **LangChain/LangGraph Integration** - Automatic tracing for chains, agents, tools, retrievers, with interrupt/resume and agent handoff support
- **Strands Agents Integration** - Hook provider (recommended) or legacy callback handler for AWS Strands agent tracing
- **CrewAI Integration** - Event listener for CrewAI crew tracing
- **MCP Server and Client Integration** - FastMCP middleware that traces an MCP server (tools, resources, prompts) independently of any agent, plus a client that carries the caller's trace into it
- **LiteLLM Integration** - Callback logger for LiteLLM proxy tracing
- **Temporal Integration** - Replay-safe plugin that traces workflows, activities, signals, queries and updates
- **FastAPI Integration** - Instrumentation that verifies it took effect, drops ASGI noise, and flushes on shutdown
- **Agentic Governance** - Real-time policy enforcement for AI agent tool calls and LLM invocations
- **Guardrails** - Apply Beacon content guardrails, pinned to a configuration version
- **System Probes** - Run autonomous AI agents that probe your HTTP system locally (private APIs, custom auth) and produce scored markdown reports
- **OpenTelemetry Integration** - Automatic instrumentation for Anthropic, OpenAI, FastAPI, Redis, HTTPX, and more
- **Manual & Decorator Tracing** - Create spans manually or use `@trace` decorator
- **Context Propagation** - One trace across Beacon and OpenTelemetry spans, load balancers, and queues
- **Trace Querying & Export** - Query, search, and filter the traces you sent to Beacon — and download complete traces back out for archiving or offline analysis
- **Agent Registry & Insights** - Register the agents traces are attributed to, read Beacon's AI-generated insights and recommendations, and trigger/monitor analysis runs
- **Dataset Management** - ActiveRecord-style API for managing test datasets
- **Prompt Management** - Version-controlled prompt templates with labels (staging, production)
- **Experiment & Evaluation Management** - Run experiments over datasets and evaluate results
- **Human Annotations** - Enqueue traces/spans/sessions for human review, push external feedback, read annotation summaries back
- **Data Masking** - Deterministic PII floor plus Beacon Guardrails detection, applied to every exported span
- **Span Noise Control** - Drop the spans you don't want (name globs, ASGI plumbing, orphan background work) before they leave the process
- **Flexible Transport** - HTTP or file-based span export
- **Full Async Support** - Async/await throughout

## Requirements

- Python 3.10+

## Installation

```bash
pip install lumenova-beacon
```

The core install depends only on `httpx` and `tenacity`. Integrations are optional extras:

| Extra | Adds |
|---|---|
| `opentelemetry` | OpenTelemetry SDK + OTLP exporters (for OTel instrumentors) |
| `langchain` | LangChain / LangGraph tracing and governance |
| `litellm` | LiteLLM callback logger |
| `strands` | AWS Strands Agents tracing |
| `crewai` | CrewAI tracing |
| `mcp` | FastMCP server middleware and client |
| `temporal` | Temporal plugin |
| `fastapi` | FastAPI instrumentation |
| `aws` | AWS Secrets Manager API-key resolution |

```bash
pip install 'lumenova-beacon[langchain,opentelemetry]'
```

## Quick Start

### LangChain / LangGraph

```python
from lumenova_beacon import BeaconClient, BeaconLangGraphHandler
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Initialize client
client = BeaconClient(
    endpoint="https://your-beacon-endpoint.lumenova.ai",
    api_key="your-api-key",
)

# Create a tracing handler
handler = BeaconLangGraphHandler(session_id="session-123")

# All LangChain operations are now traced automatically
llm = ChatOpenAI(model="gpt-4")
prompt = ChatPromptTemplate.from_template("Tell me about {topic}")
chain = prompt | llm

response = chain.invoke(
    {"topic": "AI agents"},
    config={"callbacks": [handler]}
)
```

### Basic Tracing

```python
from lumenova_beacon import BeaconClient, trace

client = BeaconClient(
    endpoint="https://your-beacon-endpoint.lumenova.ai",
    api_key="your-api-key",
    session_id="my-session"
)

@trace
def my_function(x, y):
    return x + y

result = my_function(10, 20)  # Automatically traced
```

> No endpoint? Pass `file_directory='./traces'` instead of `endpoint` to write spans as JSON locally — useful for development and tests.

### Configuration

Set `BEACON_ENDPOINT` and `BEACON_API_KEY` and `BeaconClient()` needs no arguments;
constructor parameters override environment variables. `BEACON_ENABLED=false` (or
`enabled=False`) turns tracing off completely. The full list of settings is in the
configuration page of the guide.

## Documentation

The full usage guide ships **inside the package**, at `lumenova_beacon/docs/`, so every
install carries the copy that matches its version. Start at `lumenova_beacon/docs/README.md`.
To find it in your environment:

```bash
python -c "import lumenova_beacon, pathlib; print(pathlib.Path(lumenova_beacon.__file__).parent / 'docs')"
```

Paths below are relative to `lumenova_beacon/docs/`.

### Core

- **Configuration** — `configuration.md`. Environment variables and constructor options,
  project routing for workspace API keys, TLS/proxy settings, the off switch, file
  transport, errors and retries.
- **Tracing** — `tracing.md`. `@trace`, `client.trace()` and `client.create_span()`;
  sessions; `set_session()` / `set_agent()` to name a trace's session and agent from
  inside a request; multimodal images; the span API and enums.
- **Context propagation** — `context-propagation.md`. One trace across Beacon and
  OpenTelemetry spans; the `inbound_context` policy for Cloud Run / GCLB / ELB;
  `inject_trace_context()` / `start_consumer_span()` across queues and topics.
- **Data masking** — `masking.md`. A masking function (custom, or backed by Beacon
  Guardrails) plus a deterministic PII floor on every exported span; fail-closed behavior
  and the Guardrails call limits.
- **Span noise control** — `span-filtering.md`. `SpanFilter` rules, predicates, and when
  `drop_parentless` is safe.
- **Agentic governance** — `governance.md`. `@governance`, the LangChain governance
  handler and `wrap()`, `BeaconLangGraphAgent`, `GovernanceConfig`, streaming, the payload
  ceiling, and violation handling.
- **Guardrails** — `guardrails.md`. `Guardrail.apply()`, grounding metadata, version
  pinning, end-user attribution, version history.
- **System probes** — `probes.md`. Run a probe configured in the Beacon UI against a
  private HTTP API, with the built-in dispatcher or your own callable.

### Integrations

- **LangChain / LangGraph** — `integrations/langchain.md`. `BeaconLangGraphHandler` for
  chains and one-shot agents; `BeaconLangGraphConfig` for checkpointed agents that
  interrupt and resume; per-invocation identity.
- **Strands Agents** — `integrations/strands.md`. `BeaconStrandsHooks` (recommended) and
  the legacy `BeaconStrandsHandler`; per-request identity via `invocation_state`.
- **CrewAI** — `integrations/crewai.md`. `BeaconCrewAIListener`.
- **MCP** — `integrations/mcp.md`. `BeaconMCPMiddleware` for FastMCP servers (span per
  request method, trace topology, noise defaults) and `BeaconMCPClient` for callers.
- **LiteLLM** — `integrations/litellm.md`. `BeaconLiteLLMLogger` or
  `auto_instrument_litellm=True`.
- **Temporal** — `integrations/temporal.md`. `BeaconTemporalPlugin`: replay-safe tracing
  of workflows, activities and messages; sessions from the starter or workflow memo.
- **FastAPI** — `integrations/fastapi.md`. `instrument_fastapi()` and
  `verify_fastapi_instrumentation()`.
- **OpenTelemetry instrumentors** — `integrations/opentelemetry.md`. Anthropic, OpenAI,
  HTTPX, Redis and other instrumentors reporting to Beacon; sharing a process with another
  OTel pipeline.

### Data APIs

ActiveRecord-style classes with sync and async (`a`-prefixed) methods.

- **Datasets** — `data/datasets.md`. `Dataset` and `DatasetRecord`.
- **Prompts** — `data/prompts.md`. Versioned text and chat prompts, labels, tags and
  categories, bulk fetch, LangChain conversion.
- **Experiments** — `data/experiments.md`. Runs, variables and sweeps, macro-graph stages,
  external agents.
- **Evaluations** — `data/evaluations.md`. Trace- and dataset-based evaluations, runs,
  extraction engines, statistics, evaluator versions, result export, environment
  promotion, clusters.
- **Traces** — `data/traces.md`. Query, filter and export traces already in Beacon.
- **Agents & insights** — `data/agents.md`. Agent registry, usage, findings, analysis runs.
- **Human annotations** — `data/annotations.md`. Annotation queues and summaries.
- **LLM configs** — `data/llm-configs.md`. `LLMConfig`.

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
