Lumenova Beacon SDK

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

pip install lumenova-beacon

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

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

Quick Start

LangChain / LangGraph

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

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:

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 file for details.