traceAI Python SDK

The Python SDK for traceAI provides OpenTelemetry-native instrumentation for AI applications.

Installation

Install the core instrumentation library and your framework of choice:

# Core library (required)
pip install fi-instrumentation

# Framework-specific instrumentation
pip install traceai-openai        # For OpenAI
pip install traceai-anthropic     # For Anthropic
pip install traceai-langchain     # For LangChain
pip install traceai-llamaindex    # For LlamaIndex
# ... see full list below

Quick Start

import os
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_openai import OpenAIInstrumentor
import openai

# Set environment variables
os.environ["FI_API_KEY"] = "<your-api-key>"
os.environ["FI_SECRET_KEY"] = "<your-secret-key>"

# Register tracer provider
trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="my_app"
)

# Instrument your framework
OpenAIInstrumentor().instrument(tracer_provider=trace_provider)

# Use as normal - tracing happens automatically
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Core Concepts

Project Types

• ProjectType.OBSERVE: For production monitoring. Cannot use eval tags.
• ProjectType.EXPERIMENT: For development/testing. Supports eval tags for AI evaluations.

TraceConfig (Privacy Controls)

Control what data gets captured:

from fi_instrumentation.instrumentation.config import TraceConfig

config = TraceConfig(
    hide_inputs=False,              # Hide all input values
    hide_outputs=False,             # Hide all output values
    hide_input_messages=False,      # Hide input messages only
    hide_output_messages=False,     # Hide output messages only
    hide_input_images=False,        # Hide images in inputs
    hide_embedding_vectors=False,   # Hide embedding vectors
    base64_image_max_length=32000,  # Truncate large images
)

Or use environment variables:

• FI_HIDE_INPUTS=true
• FI_HIDE_OUTPUTS=true
• FI_HIDE_INPUT_MESSAGES=true
• FI_HIDE_OUTPUT_MESSAGES=true
• FI_HIDE_INPUT_IMAGES=true
• FI_HIDE_EMBEDDING_VECTORS=true

Context Managers

Add metadata to spans:

from fi_instrumentation import using_attributes

with using_attributes(
    session_id="session-123",
    user_id="user-456",
    metadata={"environment": "production"},
    tags=["chat", "support"]
):
    response = client.chat.completions.create(...)

Available context managers:

• using_session(session_id) - Track session
• using_user(user_id) - Track user
• using_metadata(dict) - Add custom metadata
• using_tags(list) - Add categorical tags
• using_prompt_template(template, version, variables) - Track prompt variants
• using_attributes(...) - Combined context manager
• suppress_tracing() - Temporarily disable tracing

Evaluation Tags (Experiments Only)

Run automated evaluations on spans:

from fi_instrumentation import register
from fi_instrumentation.fi_types import (
    ProjectType, EvalTag, EvalTagType,
    EvalSpanKind, EvalName, ModelChoices
)

eval_tags = [
    EvalTag(
        type=EvalTagType.OBSERVATION_SPAN,
        value=EvalSpanKind.LLM,
        eval_name=EvalName.CONTEXT_ADHERENCE,
        custom_eval_name="my_context_check",
        mapping={
            "context": "raw.input",
            "output": "raw.output"
        },
        model=ModelChoices.TURING_SMALL
    )
]

trace_provider = register(
    project_type=ProjectType.EXPERIMENT,
    project_name="my_experiment",
    eval_tags=eval_tags
)

Available Evaluations (60+):

Supported Frameworks

LLM Providers

Agent Frameworks

Tools & Integrations

Vector Databases

Environment Variables

Authentication

• FI_API_KEY - API key for Future AGI
• FI_SECRET_KEY - Secret key for Future AGI

Endpoints

• FI_BASE_URL - HTTP collector endpoint (default: https://api.futureagi.com)
• FI_GRPC_URL - gRPC collector endpoint (default: https://grpc.futureagi.com)

Project

• FI_PROJECT_NAME - Default project name
• FI_PROJECT_VERSION_NAME - Default version name

Performance

• OTEL_BSP_SCHEDULE_DELAY - Batch export delay (ms)
• OTEL_BSP_MAX_QUEUE_SIZE - Max queue size
• OTEL_BSP_MAX_EXPORT_BATCH_SIZE - Max batch size
• OTEL_BSP_EXPORT_TIMEOUT - Export timeout (ms)

Advanced Usage

Custom TracerProvider

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from traceai_openai import OpenAIInstrumentor

# Create custom provider
provider = TracerProvider()
trace.set_tracer_provider(provider)

# Add custom exporter
exporter = OTLPSpanExporter(
    endpoint="https://your-collector.com/v1/traces",
    headers={"Authorization": "Bearer your-token"}
)
provider.add_span_processor(BatchSpanProcessor(exporter))

# Instrument
OpenAIInstrumentor().instrument(tracer_provider=provider)

Semantic Conventions

traceAI supports multiple semantic conventions:

from fi_instrumentation import register
from fi_instrumentation.fi_types import SemanticConvention

trace_provider = register(
    project_name="my_app",
    semantic_convention=SemanticConvention.FI  # Default
    # Or: SemanticConvention.OTEL_GENAI
    # Or: SemanticConvention.OPENINFERENCE
    # Or: SemanticConvention.OPENLLMETRY
)

Transport Options

from fi_instrumentation import register
from fi_instrumentation.fi_types import Transport

# HTTP (default)
trace_provider = register(
    project_name="my_app",
    transport=Transport.HTTP
)

# gRPC (requires grpc extras)
trace_provider = register(
    project_name="my_app",
    transport=Transport.GRPC
)

Examples

See framework-specific examples in each package:

• OpenAI Examples
• Anthropic Examples
• LangChain Examples
• CrewAI Examples

Documentation

• Full Documentation
• API Reference
• Cookbooks

License

GPL-3.0 License