Maxim AI

https://www.getmaxim.ai/docs
Admin
Maxim AI is an end-to-end platform for the simulation, evaluation, and observability of AI agents...
Tokens:406,923
Snippets:4,107
Trust Score:9.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Project Setup and Dependency Installation

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/openai-realtime

Initializes a new Node.js project and installs necessary dependencies for OpenAI, Maxim, dotenv, audio handling, and TypeScript development.

```bash
mkdir openai-realtime-audio
cd openai-realtime-audio
npm init -y
npm install openai @maximai/maxim-js dotenv node-record-lpcm16 speaker
npm install -D typescript ts-node @types/node
```

--------------------------------

### Complete Example with All Features

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/pydantic

A comprehensive example that orchestrates calls to simple, advanced, streaming, and additional agent examples. This serves as a main entry point to test all integrated features.

```python
async def main():
    """Main function to run all examples."""
    print("Pydantic AI Integration with Maxim - Complete Example")
    print("=" * 55)
    
    # Run simple agent example
    await run_simple_example()
    
    print("\n" + "=" * 55)
    
    # Run advanced agent example
    await run_advanced_example()
    
    print("\n" + "=" * 55)
    
    # Run streaming example
    await run_streaming_example()
    
    print("\n" + "=" * 55)
    
    # Run additional example
    await run_additional_example()
    
    print("\n=== All Examples Completed ===")
    print("Check your Maxim dashboard to see:")
    print("- Agent traces with tool calls")
    print("- Model generations")
    print("- Performance metrics")
    print("- Streaming responses")

# Run all examples
await main()
```

--------------------------------

### Run Financial Advisor Example

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/google-adk/google-adk

Commands to set up and run the financial advisor agent example.

```bash
# Navigate to the financial advisor directory
cd financial-advisor

# Install dependencies
uv sync

# Create run_with_maxim.py with the code above
# Make sure to import from 'financial_advisor' instead of 'your_agent'

# Run the agent with Maxim instrumentation
python3 run_with_maxim.py

# Optional: Run tests
uv run pytest tests

# Optional: Run evaluations
uv run pytest eval
```

--------------------------------

### Basic OpenAI Realtime Session with Maxim Tracing

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/openai/realtime

A minimal example demonstrating the setup of OpenAI Realtime with Maxim tracing. It includes initializing Maxim, wrapping the client, configuring session parameters on connection, and handling session events and errors.

```typescript
import { OpenAIRealtimeWS } from "openai/realtime/ws";
import { Maxim } from "@maximai/maxim-js";
import { wrapOpenAIRealtime } from "@maximai/maxim-js/openai";

async function main() {
  // Initialize Maxim
  const maxim = new Maxim({ apiKey: process.env.MAXIM_API_KEY });
  const logger = await maxim.logger({ id: process.env.MAXIM_LOG_REPO_ID });

  if (!logger) {
    throw new Error("Failed to create logger");
  }

  // Create and wrap the Realtime client
  const rt = new OpenAIRealtimeWS({ model: "gpt-4o-realtime-preview-2024-12-17" });
  const wrapper = wrapOpenAIRealtime(rt, logger, {
    "maxim-session-name": "Realtime Audio Chat",
    "maxim-session-tags": { mode: "audio", tools: "enabled" },
  });

  // Configure session on connection
  rt.socket.on("open", () => {
    rt.send({
      type: "session.update",
      session: {
        output_modalities: ["audio"],
        instructions: "You are a helpful voice assistant.",
        audio: {
          input: {
            transcription: { model: "gpt-4o-mini-transcribe" },
            turn_detection: {
              type: "server_vad",
              threshold: 0.5,
              prefix_padding_ms: 300,
              silence_duration_ms: 500,
            },
          },
          output: {
            voice: "coral",
          },
        },
      },
    });
  });

  // Handle events
  rt.on("session.updated", () => {
    console.log("Session ready!");
  });

  rt.on("error", (err) => {
    console.error("Error:", err);
  });
}

main().catch(console.error);
```

--------------------------------

### Multi-Modal Agent Example

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/llamaindex/llamaindex

Creates a multi-modal agent capable of handling text and images using OpenAI's vision-capable models. Ensure 'llama-index' and 'llama-index-llms-openai' are installed.

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.llms import ChatMessage, ImageBlock, TextBlock
from llama_index.llms.openai import OpenAI

# Multi-modal tools
def describe_image_content(description: str) -> str:
    """Analyze and describe what's in an image."""
    return f"Image analysis complete: {description}"

def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

# Create multi-modal agent
multimodal_llm = OpenAI(model="gpt-4o-mini")  # Vision-capable model

multimodal_agent = FunctionAgent(
    tools=[add, describe_image_content],
    llm=multimodal_llm,
    system_prompt="You are a helpful assistant that can analyze images and perform calculations."
)

# Use with images
async def analyze_image():
    msg = ChatMessage(
        role="user",
        blocks=[
            TextBlock(text="What do you see in this image? If there are numbers, perform calculations."),
            ImageBlock(url="path/to/your/image.jpg"),
        ],
    )
    response = await multimodal_agent.run(msg)
    print(f"Multi-modal response: {response}")

await analyze_image()
```

--------------------------------

### Install Maxim SDK

Source: https://www.getmaxim.ai/docs/offline-evals/via-sdk/agent-http/quickstart

Install the required package for your development environment.

```bash
pip install maxim-py
```

```bash
npm install @maximai/maxim-js
```

--------------------------------

### Quick Start: Basic LangGraph Agent with Maxim Tracer

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/langgraph/langgraph

A minimal example demonstrating how to initialize Maxim, create a logger, set up a Langchain tracer, define a tool, and create a LangGraph agent. This snippet shows how to invoke the agent with tracing enabled.

```typescript
import { tool } from "@langchain/core/tools";
import { MemorySaver } from "@langchain/langgraph";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { ChatOpenAI } from "@langchain/openai";
import { Maxim } from "@maximai/maxim-js";
import { MaximLangchainTracer } from "@maximai/maxim-js/langchain";
import { z } from "zod";

// Initialize Maxim
const maxim = new Maxim({
  apiKey: process.env.MAXIM_API_KEY,
});
const logger = await maxim.logger({
  id: process.env.MAXIM_LOG_REPO_ID,
});

if (!logger) {
  throw new Error("logger is not available");
}

// Create the tracer
const maximTracer = new MaximLangchainTracer(logger);

// Create a simple tool
const calculatorTool = tool(
  async ({ operation, a, b }) => {
    switch (operation) {
      case "add":
        return a + b;
      case "multiply":
        return a * b;
      case "subtract":
        return a - b;
      case "divide":
        return b !== 0 ? a / b : "Cannot divide by zero";
      default:
        return "Unknown operation";
    }
  },
  {
    name: "calculator",
    schema: z.object({
      operation: z.enum(["add", "multiply", "subtract", "divide"]),
      a: z.number(),
      b: z.number(),
    }),
    description: "Performs basic arithmetic operations",
  }
);

// Create your LangGraph components
const model = new ChatOpenAI({
  openAiapiKey: process.env.OPENAI_API_KEY,
  modelName: "gpt-4o-mini",
});
const agent = createReactAgent({
  llm: model,
  tools: [calculatorTool],
  checkpointSaver: new MemorySaver(),
});

// Use with automatic tracing
const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's 25 * 4 + 10?" }] },
  {
    callbacks: [maximTracer],
    configurable: { thread_id: "quick-start-example" },
  }
);

console.log(result.messages[result.messages.length - 1].content);

// Clean up resources
await maxim.cleanup();

```

--------------------------------

### Install Maxim SDK

Source: https://www.getmaxim.ai/docs/tracing/tracing-via-sdk/traces

Install the Maxim SDK for your project. Available for JavaScript/TypeScript, Python, Go, and Java/Scala/Kotlin.

```package-install JS/TS
npm install @maximai/maxim-js
```

```bash Python
pip install maxim-py
```

```bash Go
go get github.com/maximhq/maxim-go
```

```groovy Java/Scala/Kotlin
implementation("ai.getmaxim:sdk:0.1.3")
```

--------------------------------

### Install Dependencies

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/elevenlabs

Install project dependencies using pip from a requirements.txt file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Required Dependencies

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/groq

Install the necessary packages for Groq inference, data handling, and Maxim observability.

```python
pip install groq yfinance pandas plotly maxim-py
```

--------------------------------

### Install Maxim SDK for Node.js

Source: https://www.getmaxim.ai/docs/sdk/typescript/setup

Use npm to install the SDK. This is the first step for both Node.js and React Native projects.

```bash
npm install @maximai/maxim-js
```

--------------------------------

### Initialize Maxim Logger

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/mistral/mistral

Setup the Maxim logger instance.

```python
from maxim import Maxim

logger = Maxim().logger()
```

--------------------------------

### Install Maxim AI SDK

Source: https://www.getmaxim.ai/docs/tracing/tracing-via-sdk/metadata

Install the required SDK package for your specific programming language.

```bash
npm install @maximai/maxim-js
```

```bash
pip install maxim-py
```

```bash
go get github.com/maximhq/maxim-go
```

--------------------------------

### Install Maxim SDK

Source: https://www.getmaxim.ai/docs/tracing/quickstart

Install the required SDK package for your specific programming language.

```bash
npm install @maximai/maxim-js
```

```bash
pip install maxim-py
```

```bash
go get github.com/maximhq/maxim-go
```

```groovy
compileOnly("ai.getmaxim:sdk:0.1.3")
```

--------------------------------

### Install Maxim and Together AI dependencies

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/together

Install the required Python packages for the integration.

```bash
pip install maxim-py together python-dotenv
```

--------------------------------

### Install Maxim SDK packages

Source: https://www.getmaxim.ai/docs/sdk/overview

Use these commands to install the necessary SDK packages for your preferred programming language.

```bash
pip install maxim-py
```

```bash
npm install @maximai/maxim-js
```

```bash
npm install @maximai/maxim-js-langchain
```

```bash
go get github.com/maximhq/maxim-go
```

```bash
implementation("ai.getmaxim:sdk:0.1.3")
```

--------------------------------

### Install Maxim and LangChain dependencies

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/langchain/langchain

Install the core Maxim and LangChain packages required for observability.

```bash
npm install @maximai/maxim-js @langchain/core
```

--------------------------------

### Install Maxim and OpenAI SDKs

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/openai/agents-sdk

Install the necessary Python packages for Maxim and OpenAI integration.

```bash
"openai>=1.65.4"
"maxim-py>=3.5.0"
```

--------------------------------

### Maxim Constructor Example (Environment Variables)

Source: https://www.getmaxim.ai/docs/library/how-to/datasets/add-new-entries-using-sdk

Example of initializing the Maxim SDK using environment variables for the API key and debug mode. This is a common practice for managing sensitive information and environment-specific configurations.

```typescript
const maxim = new Maxim({
  apiKey: process.env.MAXIM_API_KEY,
  promptManagement: true,
  debug: process.env.NODE_ENV === 'development'
});
```

--------------------------------

### Install Maxim Python SDK

Source: https://www.getmaxim.ai/docs/sdk/python/overview

Use these commands to install the SDK package in your Python environment.

```pip
pip install maxim-py
```

```uv
uv add maxim-py
```

--------------------------------

### Run Additional Agent Example

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/pydantic

Shows how to perform multiple sequential operations using the agent, such as running two separate calculations. This example is useful for batch processing or multi-step tasks.

```python
async def run_additional_example():
    """Run an additional agent example."""
    print("=== Additional Agent Example ===")
    
    agent = create_streaming_agent()
    
    # Run multiple operations
    print("Running first calculation...")
    result = await agent.run("What is 12 + 18?")
    print(f"Result: {result}")
    
    print("Running second calculation...")
    result = await agent.run("Calculate 6 * 9")
    print(f"Result: {result}")
    
    print("Example completed!")

# Run example
await run_additional_example()
```

--------------------------------

### Start Microphone Recording

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/openai-realtime

Initiates microphone recording with specified audio parameters. Handles errors during recording setup and streams audio data for processing. Ensure the 'record' library is installed and configured.

```typescript
let isRecording = false;
let recordingStream: any = null;

function startRecording() {
  if (isRecording) return;
  isRecording = true;
  console.log("\n🔴 Recording... (press [r] or release space to stop)");

  try {
    recordingStream = record.record({
      sampleRate: 24000,
      channels: 1,
      audioType: "raw",
      recorder: "sox",
    });

    recordingStream.stream().on("data", (chunk: Buffer) => {
      // Convert to base64 and send to OpenAI
      const base64Audio = chunk.toString("base64");
      rt.send({
        type: "input_audio_buffer.append",
        audio: base64Audio,
      });
    });

    recordingStream.stream().on("error", (err: Error) => {
      console.error("Recording error:", err.message);
      stopRecording();
    });
  } catch (e) {
    console.error("Failed to start recording:", e);
    isRecording = false;
  }
}
```

--------------------------------

### Initialize Comprehensive Project Setup

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/together

Configures environment variables and imports necessary libraries for an instrumented Together AI workflow.

```python
import os
import asyncio
from together import Together, AsyncTogether
from dotenv import load_dotenv
from maxim import Maxim
from maxim.logger.together import instrument_together

# Setup
load_dotenv()
TOGETHER_API_KEY = os.getenv('TOGETHER_API_KEY')
```

--------------------------------

### Install Maxim AI SDK and Vercel AI SDK Dependencies

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/vercel

Install the necessary packages for Maxim AI observability and the Vercel AI SDK. Ensure Node.js 18+ is used.

```bash
npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google @maximai/maxim-js ai
```

--------------------------------

### Load Data from Excel File Example

Source: https://www.getmaxim.ai/docs/cookbooks/sdk/sdk_test_run_local_dataset

Loads data from an Excel file using the pandas library and converts it into a list of dictionaries. Requires pandas to be installed.

```python
import pandas as pd

def load_excel_data(filepath: str):
    """
    Example function to load data from Excel
    """
    df = pd.read_excel(filepath)
    return df.to_dict('records')
```

--------------------------------

### Set Up SQL Database

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/smolagents

Create an in-memory SQLite database, define the receipts table, and populate it with sample data.

```python
# Create SQLite engine
engine = create_engine("sqlite:///:memory:")
metadata_obj = MetaData()

# Create receipts SQL table
table_name = "receipts"
receipts = Table(
    table_name,
    metadata_obj,
    Column("receipt_id", Integer, primary_key=True),
    Column("customer_name", String(16), primary_key=True),
    Column("price", Float),
    Column("tip", Float),
)
metadata_obj.create_all(engine)

# Insert sample data
rows = [
    {"receipt_id": 1, "customer_name": "Alan Payne", "price": 12.06, "tip": 1.20},
    {"receipt_id": 2, "customer_name": "Alex Mason", "price": 23.86, "tip": 0.24},
    {"receipt_id": 3, "customer_name": "Woodrow Wilson", "price": 53.43, "tip": 5.43},
    {"receipt_id": 4, "customer_name": "Margaret James", "price": 21.11, "tip": 1.00},
]

for row in rows:
    stmt = insert(receipts).values(**row)
    with engine.begin() as connection:
        connection.execute(stmt)

# Display table schema
inspector = inspect(engine)
columns_info = [(col["name"], col["type"]) for col in inspector.get_columns("receipts")]
table_description = "Columns:\n" + "\n".join([f"  - {name}: {col_type}" for name, col_type in columns_info])
print(table_description)
```

--------------------------------

### Simple FunctionAgent Example

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/llamaindex/llamaindex

Creates a basic calculator agent using FunctionAgent and FunctionTool. The agent's execution is automatically traced by Maxim. Ensure 'llama-index' and 'llama-index-llms-openai' are installed.

```python
from llama_index.core.agent import FunctionAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI

# Define calculator tools
def add_numbers(a: float, b: float) -> float:
    """Add two numbers together."""
    return a + b

def multiply_numbers(a: float, b: float) -> float:
    """Multiply two numbers together."""
    return a * b

def divide_numbers(a: float, b: float) -> float:
    """Divide first number by second number."""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

# Create function tools
add_tool = FunctionTool.from_defaults(fn=add_numbers)
multiply_tool = FunctionTool.from_defaults(fn=multiply_numbers)
divide_tool = FunctionTool.from_defaults(fn=divide_numbers)

# Initialize LLM and agent
llm = OpenAI(model="gpt-4o-mini", temperature=0)

agent = FunctionAgent(
    tools=[add_tool, multiply_tool, divide_tool],
    llm=llm,
    verbose=True,
    system_prompt="""You are a helpful calculator assistant.
    Use the provided tools to perform mathematical calculations.
    Always explain your reasoning step by step."""
)

# Run the agent (automatically traced by Maxim)
async def run_calculation():
    query = "What is (15 + 25) multiplied by 2, then divided by 8?"
    response = await agent.run(query)
    print(f"Response: {response}")

await run_calculation()
```

--------------------------------

### Set Up Virtual Environment

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/elevenlabs

Create and activate a Python virtual environment for the project.

```bash
python3 -m venv venv
source venv/bin/activate
```

--------------------------------

### Quality Evaluator Prompt Example

Source: https://www.getmaxim.ai/docs/cookbooks/sdk/sdk_custom_evaluator

This prompt guides an AI to rate a model output on a scale of 1-5 based on how well it answers the input prompt. It requires the input and should return JSON with 'score' and 'reasoning'.

```text
You are a quality evaluator. Rate the following model output based on how well it answers the given prompt.

Input: {{input}}

Rate the output on a scale of 1-5 where:
- 1: Very poor response, doesn't address the prompt
- 2: Poor response, partially addresses the prompt
- 3: Average response, addresses most of the prompt
- 4: Good response, addresses the prompt well
- 5: Excellent response, perfectly addresses the prompt with high quality

Respond with JSON only:
{
    "score": <1-5>,
    "reasoning": "<explanation of the score>"
}
```

--------------------------------

### Initialize SDK for Streaming

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/anthropic/anthropic

Setup environment and clients for streaming support.

```python
import os
import dotenv
from uuid import uuid4
from anthropic import Anthropic
from maxim import Maxim
from maxim.logger.anthropic import MaximAnthropicClient

# Load environment variables
dotenv.load_dotenv()
MODEL_NAME = "claude-3-5-sonnet-20241022"
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

# Initialize Maxim logger
logger = Maxim().logger()

# Initialize MaximAnthropicClient
client = MaximAnthropicClient(Anthropic(api_key=ANTHROPIC_API_KEY), logger)
```

--------------------------------

### Initialize MaximGeminiClient

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/gemini/gemini

Setup the client by providing the Gemini client instance and the Maxim logger.

```python
client = MaximGeminiClient(
    client=genai.Client(api_key=GEMINI_API_KEY), 
    logger=logger
)
```

--------------------------------

### Initialize Client for Function Calling

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/gemini/gemini

Setup the client with environment variables and logger for advanced use cases.

```python
import os
import dotenv
from google import genai
from maxim import Maxim
from maxim.logger.gemini import MaximGeminiClient

# Load environment variables
dotenv.load_dotenv()
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

# Initialize Maxim logger
logger = Maxim().logger()

# Initialize MaximGeminiClient
client = MaximGeminiClient(
    client=genai.Client(api_key=GEMINI_API_KEY), 
    logger=logger
)
```

--------------------------------

### Install Maxim and Google ADK Dependencies

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/google-adk/google-adk

Install the necessary Python packages for Maxim and Google ADK integration. Ensure you have Python 3.10+ installed.

```bash
pip install maxim-py google-adk python-dotenv
```

--------------------------------

### Install Required Packages

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/litellm/litellm-sdk

Ensure these versions or higher are installed in your environment.

```text
litellm>=1.25.0
maxim-py>=3.5.0
```

--------------------------------

### Initialize MaximGeminiClient

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/gemini/gemini

Setup the MaximGeminiClient using the Google GenAI client.

```python
from google import genai
from maxim.logger.gemini import MaximGeminiClient

client = MaximGeminiClient(
    client=genai.Client(api_key=GEMINI_API_KEY), 
    logger=logger
)
```

--------------------------------

### Invoke Setup Function

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/livekit/livekit-otel

Initializes the tracer provider with optional metadata for trace enrichment.

```python
# Basic setup
trace_provider = setup_maxim_otel()

# With metadata for enriching traces
trace_provider = setup_maxim_otel(
    metadata={
        "maxim-trace-tags": {
            "environment": "production",
            "service": "livekit-agent",
        },
        "maxim-trace-metrics": {
            "version": 1.0,
        },
    }
)
```

--------------------------------

### Run Streaming Agent Example

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/pydantic

Demonstrates how to use the streaming agent for detailed explanations and calculations. It shows how to initiate and manage streaming responses using an async context manager.

```python
async def run_streaming_example():
    """Run the streaming agent example."""
    print("=== Streaming Agent Example ===")
    
    # Create the agent
    agent = create_streaming_agent()
    
    # Use streaming mode for detailed explanations
    print("Running streaming explanation...")
    async with agent.run_stream("Explain what is 2 + 2 in detail and then calculate 5 * 6") as stream:
        print("Streaming in progress...")
        # The stream will complete automatically when the context manager exits
        print("Streaming completed")
    
    # Run another streaming example
    print("Running streaming concept explanation...")
    async with agent.run_stream("Explain the concept of machine learning and then add 10 + 15") as stream:
        print("Streaming concept explanation in progress...")
        print("Streaming concept explanation completed")
    
    # Run a simple calculation without blocking the event loop
    print("Running calculation for comparison...")
    result = await agent.run("What is 7 * 8?")
    print(f"Result: {result}")
    
    print("Streaming agent example completed!")

# Run the streaming example
await run_streaming_example()
```

--------------------------------

### Get Evaluation Container

Source: https://www.getmaxim.ai/docs/observe/how-to/evaluate-logs/node-level-evaluation

Call the evaluate() method on a component to get an EvaluateContainer.

```python
evaluation_container = generation.evaluate()
```

--------------------------------

### Set Up Maxim Logger and OpenAI Client

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/react-agent

Initializes the Maxim client and logger, and configures the OpenAI client. Requires MAXIM_API_KEY and MAXIM_LOG_REPO_ID from environment variables.

```python
from maxim.maxim import Maxim, Config, LoggerConfig
from maxim.logger.components.session import SessionConfig
from maxim.logger.components.trace import TraceConfig
from maxim.logger.components.span import Span, SpanConfig
from maxim.logger.components.generation import GenerationConfig
from uuid import uuid4
import openai
from openai import OpenAI

maxim = Maxim(Config(api_key=os.environ["MAXIM_API_KEY"]))
logger = maxim.logger(LoggerConfig(id=os.environ["MAXIM_LOG_REPO_ID"]))
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
```

--------------------------------

### Maxim Class Initialization

Source: https://www.getmaxim.ai/docs/library/how-to/datasets/add-new-entries-using-sdk

Demonstrates how to initialize the Maxim SDK with basic and full configurations.

```APIDOC
## POST /api/users

### Description
This endpoint is used to create a new user in the system.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - The API key for authentication.

#### Request Body
- **username** (string) - Required - The desired username.
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "johndoe",
  "email": "john.doe@example.com",
  "password": "securepassword123"
}
```

### Response
#### Success Response (200)
- **userId** (string) - The unique identifier for the newly created user.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "userId": "user-12345",
  "message": "User created successfully."
}
```
```

--------------------------------

### Initialize Maxim and Groq Client

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/groq

Configure the Maxim logger and instrument the Groq client to enable observability.

```python
import os
from maxim import Config, Maxim
from maxim.logger import LoggerConfig
from maxim.logger.groq import instrument_groq
from groq import Groq

# Initialize Maxim for AI observability
maxim = Maxim(Config(api_key=os.getenv("MAXIM_API_KEY")))
logger = maxim.logger(LoggerConfig(id=os.getenv("MAXIM_LOG_REPO_ID")))

# Set up Groq client with logging instrumentation
instrument_groq(logger)
client = Groq()
```

--------------------------------

### Initialize SDK for Multiple Calls

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/anthropic/anthropic

Setup for capturing multiple LLM calls within a single trace.

```python
from anthropic import Anthropic
from maxim import Maxim
from maxim.logger.anthropic import MaximAnthropicClient

# Make sure MAXIM_API_KEY and MAXIM_LOG_REPO_ID are set in env variables
logger = Maxim().logger()
```

--------------------------------

### Multi-turn Conversation Examples

Source: https://www.getmaxim.ai/docs/offline-evals/via-ui/agents-via-http-endpoint/quickstart

Example interaction patterns for testing multi-turn conversation context.

```text
User: "How old is the universe?"
AI: "The universe is estimated to be around 13.8 billion years old..."
```

```text
User: "What's the Big Bang theory?"
AI: "The Big Bang theory explains the origin of the universe..."
```

--------------------------------

### Run the Simple Math Agent Example

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/pydantic

Instantiate the simple agent and run multiple calculations by providing natural language prompts. The agent will use its tools to compute the results.

```python
import asyncio

async def run_simple_example():
    """Run the simple agent example."""
    print("=== Simple Math Agent Example ===")
    
    # Create the agent
    agent = create_simple_agent()
    
    # Run multiple calculations
    print("Running first calculation...")
    result = await agent.run("What is 15 + 27?")
    print(f"Result: {result}")
    
    print("Running second calculation...")
    result = await agent.run("Calculate 8 * 12")
    print(f"Result: {result}")
    
    print("Running third calculation...")
    result = await agent.run("What is 25 + 17 and then multiply that result by 3?")
    print(f"Result: {result}")
    
    print("Simple agent example completed!")

# Run the example
await run_simple_example()
```

--------------------------------

### Install Zod for tool calling

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/langgraph/langgraph

Install Zod as a dependency for handling tool definitions in LangGraph.

```bash
npm install zod
```

```bash
yarn add zod
```

```bash
pnpm add zod
```

```bash
bun add zod
```

--------------------------------

### Environment Variables Setup

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/agno/agno

Configure your Maxim API key, log repository ID, and optionally, your LLM provider's API key by creating a `.env` file in your project root.

```env
### Environment Variables Setup

# Create a `.env` file in your project root:

# Maxim API Configuration
MAXIM_API_KEY=your_api_key_here
MAXIM_LOG_REPO_ID=your_repo_id_here
OPENAI_API_KEY=your_openai_api_key
# You can also choose another LLM Provider (Gemini, Groq, Anthropic etc.)
```

--------------------------------

### Install LLM provider packages

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/langgraph/langgraph

Install specific LangChain packages for supported LLM providers.

```bash
# For OpenAI
npm install @langchain/openai

# For Anthropic
npm install @langchain/anthropic

# For other integrations
npm install @langchain/community
```

```bash
# For OpenAI
yarn add @langchain/openai

# For Anthropic
yarn add @langchain/anthropic

# For other integrations
yarn add @langchain/community
```

```bash
# For OpenAI
pnpm add @langchain/openai

# For Anthropic
pnpm add @langchain/anthropic

# For other integrations
pnpm add @langchain/community
```

```bash
# For OpenAI
bun add @langchain/openai

# For Anthropic
bun add @langchain/anthropic

# For other integrations
bun add @langchain/community
```

--------------------------------

### Install Zod for tool calling

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/langchain/langchain

Install Zod if your application requires tool calling functionality.

```bash
npm install zod
```

--------------------------------

### Install LLM provider packages

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/langchain/langchain

Install specific packages for OpenAI, Anthropic, or community integrations.

```bash
# For OpenAI
npm install @langchain/openai

# For Anthropic
npm install @langchain/anthropic

# For other integrations
npm install @langchain/community
```

--------------------------------

### Initialize Maxim SDK

Source: https://www.getmaxim.ai/docs/offline-evals/via-sdk/agent-http/quickstart

Configure the SDK with your API key to enable communication with the Maxim platform.

```python
from maxim import Maxim

# Initialize Maxim SDK

maxim = Maxim({"api_key": "your-api-key"})
```

```typescript
import { Maxim } from '@maximai/maxim-js';

// Initialize Maxim SDK
const maxim = new Maxim({
  apiKey: 'your-api-key',
});
```

--------------------------------

### Set up Maxim and OpenAI API keys

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/pydantic

Create a .env file in your project root to store your Maxim API key, repository ID, and OpenAI API key.

```env
MAXIM_API_KEY=your_maxim_api_key_here
MAXIM_LOG_REPO_ID=your_repo_id_here
OPENAI_API_KEY=your_openai_api_key_here
```

--------------------------------

### Create Project Directory

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/elevenlabs

Create a new directory for the voice agent project and navigate into it.

```bash
mkdir elevenlabs_voice_agent
cd elevenlabs_voice_agent
```

--------------------------------

### Initialize Maxim SDK and Gemini Client

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/gemini/gemini

Full initialization sequence for the Maxim SDK and Gemini client, requiring environment variables for API keys and repository IDs.

```python
from google import genai
from maxim import Maxim
from maxim.logger.gemini import MaximGeminiClient

# Make sure MAXIM_API_KEY and MAXIM_LOG_REPO_ID are set in env variables
logger = Maxim().logger()

# Initialize MaximGeminiClient
client = MaximGeminiClient(
    client=genai.Client(api_key=GEMINI_API_KEY), 
    logger=logger
)
```

--------------------------------

### TestRunLogger Usage Examples

Source: https://www.getmaxim.ai/docs/sdk/typescript/reference/core/interfaces/TestRunLogger

Examples demonstrating how to implement and use the TestRunLogger interface with the maxim.js library.

```APIDOC
## Examples

```ts theme={null}
import { TestRunLogger } from '@maximai/maxim-js';

const customLogger: TestRunLogger = {
  info: (message) => console.log(`[INFO] ${message}`),
  error: (message) => console.error(`[ERROR] ${message}`),
  processed: (message) => console.log(`[PROCESSED] ${message}`),
};
```

```ts theme={null}
// Using custom logger with test run
maxim.createTestRun("my-test", "workspace-id")
  .withLogger(customLogger)
  .withData(testData)
  .run();
```

### Example Usage for error()

```ts theme={null}
// Called automatically when errors occur
logger.error("Failed to evaluate entry 42: timeout");
logger.error("API rate limit exceeded, retrying...");
```

### Example Usage for info()

```ts theme={null}
// Called automatically during test run
logger.info("Starting test run with 100 entries");
logger.info("Test run completed successfully");
```

### Example Usage for processed()

```ts theme={null}
// Called automatically after each entry
logger.processed("Entry 1 processed successfully", {
  datasetEntry: { input: "Hello", expectedOutput: "Hi there!" },
  output: { data: "Hi there!" },
  evaluationResults: [
    { name: "accuracy", result: { score: 0.95, reasoning: "Excellent match" } }
  ]
});
```
```

--------------------------------

### Verify Agent Startup and Imports

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/google-adk/google-adk

Ensure that environment variables are correctly configured and that your agent can be imported successfully after instrumentation.

```bash
# Verify environment variables
cat .env

# Check Python path and imports
python3 -c "from your_agent import root_agent; print('Agent imported successfully')"
```

--------------------------------

### Initialize Customer Database

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/livekit

Instantiate the global customer database handler.

```python
db = CustomerDatabase()
```

--------------------------------

### Install Maxim and LangGraph dependencies

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/langgraph/langgraph

Install the core packages required for Maxim observability and LangGraph functionality.

```bash
npm install @maximai/maxim-js @langchain/core @langchain/langgraph
```

```bash
yarn add @maximai/maxim-js @langchain/core @langchain/langgraph
```

```bash
pnpm add @maximai/maxim-js @langchain/core @langchain/langgraph
```

```bash
bun add @maximai/maxim-js @langchain/core @langchain/langgraph
```

--------------------------------

### Install Maxim AI dependencies

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/pydantic-ai/pydantic_ai

Install the necessary packages via pip or add them to your requirements file.

```bash
pip install maxim-py pydantic-ai python-dotenv
```

```text
maxim-py
pydantic-ai
python-dotenv
```

--------------------------------

### Initialize Maxim SDK (Full Configuration)

Source: https://www.getmaxim.ai/docs/library/how-to/datasets/add-new-entries-using-sdk

Initialize the Maxim SDK with a full configuration, including API key, base URL, prompt management, debugging, and a custom cache implementation. Replace 'your-api-key' with your actual key.

```typescript
// Full configuration
const maxim = new Maxim({
  apiKey: 'your-api-key',
  baseUrl: 'https://app.getmaxim.ai',
  promptManagement: true,
  debug: true,
  cache: new CustomCacheImplementation()
});
```

--------------------------------

### Install Maxim SDK

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/crewai/crewai

Install the required Python package via pip or add it to your requirements file.

```python
pip install maxim-py
```

```text
maxim-py
```

--------------------------------

### Initialize MaximGeminiClient

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/gemini

Wraps the standard Google GenAI client with Maxim's tracing capabilities.

```python
import os
from google import genai

client = MaximGeminiClient(
    client=genai.Client(api_key=os.getenv("GEMINI_API_KEY")),
    logger=logger
)
```

--------------------------------

### Using Prompt Management with Maxim

Source: https://www.getmaxim.ai/docs/library/how-to/datasets/add-new-entries-using-sdk

Demonstrates how to retrieve and run a prompt using the Maxim SDK's prompt management feature. Requires an API key and prompt management enabled during initialization. The example shows building deployment rules and executing a prompt.

```typescript
// Using prompt management
const maxim = new Maxim({
  apiKey: 'your-api-key',
  promptManagement: true
});

// Get a prompt with deployment rules
const rule = new QueryBuilder()
  .deploymentVar('environment', 'production')
  .tag('version', 'v2.0')
  .build();

const prompt = await maxim.getPrompt('prompt-id', rule);
if (prompt) {
  const response = await prompt.run('Hello world');
  console.log(response.choices[0].message.content);
}
```

--------------------------------

### TEXT Data Type Examples

Source: https://www.getmaxim.ai/docs/sdk/typescript/reference/core/enumerations/VariableType

Provides examples of string values suitable for the TEXT variable type.

```text
"Hello world", "user input text", "response content"
```

--------------------------------

### Initialize Maxim and Instrument LlamaIndex

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/llamaindex

Loads environment variables, initializes the Maxim SDK, and instruments LlamaIndex for observability. Set debug=True for detailed development logs.

```python
# Load environment variables from .env file
load_dotenv()

# Initialize Maxim logger
maxim = Maxim(Config(api_key=os.getenv("MAXIM_API_KEY")))
logger = maxim.logger(LoggerConfig(id=os.getenv("MAXIM_LOG_REPO_ID")))

# Instrument LlamaIndex with Maxim observability
# Set debug=True to see detailed logs during development
instrument_llamaindex(logger, debug=True)

print("✅ Maxim instrumentation enabled for LlamaIndex")
```

--------------------------------

### Install Dependencies for Maxim Vercel Integration

Source: https://www.getmaxim.ai/docs/sdk/typescript/integrations/vercel/vercel

Ensure these packages are installed for Maxim integration with Vercel AI SDK.

```bash
"ai"
"@ai-sdk/openai"
"@ai-sdk/anthropic"
"@ai-sdk/google"
"@maximai/maxim-js"
```

--------------------------------

### Configure Together and Maxim instrumentation

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/together

Initialize the environment and apply the instrumentation wrapper to the Together AI client.

```python
# Load environment variables from .env file
load_dotenv()

# Get API keys from environment
TOGETHER_API_KEY = os.getenv('TOGETHER_API_KEY')
MAXIM_API_KEY = os.getenv('MAXIM_API_KEY')
MAXIM_LOG_REPO_ID = os.getenv('MAXIM_LOG_REPO_ID')

# Instrument Together AI with Maxim
instrument_together(Maxim().logger())
```

--------------------------------

### Configure Production Environment

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/smolagents

Initialize Maxim configuration and logging for production deployments.

```python
import os
from maxim import Config, Maxim
from maxim.logger import LoggerConfig

# Production-ready Maxim setup
maxim = Maxim(Config(api_key=os.getenv("MAXIM_API_KEY")))
logger = maxim.logger(LoggerConfig(id=os.getenv("MAXIM_LOG_REPO_ID")))

# Instrument with debug logging for development
instrument_smolagents(logger, debug=True)
```

--------------------------------

### Implementing Custom Cache (Python)

Source: https://www.getmaxim.ai/docs/offline-evals/via-ui/agents-via-no-code-builder/querying-prompt-chains

Example of initializing the Maxim SDK with a custom cache implementation in Python.

```python
from maxim import Maxim, Config

maxim = Maxim(Config(apiKey=apiKey, baseUrl=baseUrl, cache=CustomCache()))
```

--------------------------------

### Install Maxim, Pydantic AI, and python-dotenv

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/pydantic

Install the necessary Python packages using pip. Ensure you have Python 3.10+.

```bash
pip install maxim-py pydantic-ai python-dotenv
```

--------------------------------

### Install Maxim SDK

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/crewai

Install the Maxim Python SDK using pip. This is required to add observability to your CrewAI project.

```bash
pip install maxim-py
```

--------------------------------

### Full Gemini Tracing Integration Example

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/gemini

A complete script combining initialization, tool definition, and content generation with Maxim tracing.

```python
import dotenv
import os
from maxim import Maxim
from maxim.logger.gemini import MaximGeminiClient
from google import genai

dotenv.load_dotenv()

logger = Maxim().logger()
client = MaximGeminiClient(
    client=genai.Client(api_key=os.getenv("GEMINI_API_KEY")),
    logger=logger
)

def get_current_weather(location: str) -> str:
    print(f"Called with: {location=}")
    return "23C"

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="What's the temp in SF?",
    config={
        "tools": [get_current_weather],
        "system_instruction": "You are a helpful assistant",
        "temperature": 0.8,
    },
)
print(response)
```

--------------------------------

### CSV File Format Example

Source: https://www.getmaxim.ai/docs/cookbooks/sdk/sdk_test_run_local_dataset

Example structure for a CSV file used as a data source, with 'Input' and 'Expected_Output' columns.

```csv
Input,Expected_Output
"Doctor: Hi, what brings you in today?...","Chief complaint: Sore throat..."
"Doctor: Good morning! How's the blood pressure?...","Chief complaint: Elevated BP..."
```

--------------------------------

### Check Maxim Installation and API Key

Source: https://www.getmaxim.ai/docs/sdk/python/integrations/google-adk/google-adk

Verify that the Maxim Python package is installed and that your API key is correctly set in the environment.

```bash
# Check Maxim installation
pip show maxim-py

# Verify API key
echo $MAXIM_API_KEY

# Check debug logs
export MAXIM_DEBUG=true
```

--------------------------------

### Prompt Partial Version Strategy

Source: https://www.getmaxim.ai/docs/cookbooks/platform-features/prompt-partials

This example outlines a version control strategy for prompt partials, distinguishing between initial releases, minor updates, and major changes. Use this to manage evolution of your partials.

```text
Version Strategy:
v1.0 - Initial release
v1.1 - Minor updates (typos, small improvements)
v2.0 - Major changes (structural modifications)
```

--------------------------------

### Multi-Modal Agent Setup Imports

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/llamaindex

Imports necessary classes for setting up a multi-modal agent, including chat messages, image blocks, text blocks, and utilities for handling image data.

```python
from llama_index.core.llms import ChatMessage, ImageBlock, TextBlock
import requests
from PIL import Image
import io
import base64
```

--------------------------------

### Install Maxim Python SDK with uv

Source: https://www.getmaxim.ai/docs/integrations/overview

Install the Maxim Python SDK using uv. Ensure your Python version is 3.9 or higher.

```bash
uv add maxim-py
```

--------------------------------

### Trace Initialization and Usage

Source: https://www.getmaxim.ai/docs/sdk/typescript/reference/core/classes/Trace

Demonstrates how to initialize a Trace object and add various components like generations, retrievals, and tool calls.

```APIDOC
## Trace Class

Represents a trace (a single turn interaction).

Traces capture the complete execution flow of operations, including generations,
tool calls, retrievals, spans, and errors happening within one user interaction
turn. They provide detailed timing and hierarchical organization of activities
within a session or standalone operation.

### Constructor

> **new Trace**(`config`, `writer`): `Trace`

Creates a new trace log entry.

#### Parameters

##### config

[`TraceConfig`](../overview#traceconfig)

Configuration object defining the trace

##### writer

[`LogWriter`](./LogWriter)

Log writer instance for persisting trace data

#### Returns

`Trace`

#### Example

```ts theme={null}
const trace = new Trace({
  id: 'recommendation-trace',
  name: 'Product Recommendation Flow',
  sessionId: 'shopping-session-456',
});
```

## Example Usage

```ts theme={null}
const trace = logger.trace({
  id: 'query-processing-trace',
  name: 'User Query Processing',
  sessionId: 'chat-session-001', // optional
});

// Add input
trace.input('Find information about machine learning');

// Adding components to trace
const generation = trace.generation({
  id: 'llm-generation-001',
  provider: 'openai',
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain ML' }],
  modelParameters: { temperature: 0.7 }
});

const retrieval = trace.retrieval({
  id: 'vector-search-001',
  name: 'Knowledge Base Search'
});

const toolCall = trace.toolCall({
  id: 'search-tool-001',
  name: 'external_search',
  description: 'Search external knowledge base',
  args: JSON.stringify({ query: 'machine learning' })
});

// Add output
trace.output('Machine learning is a subset of artificial intelligence...');
```
```

--------------------------------

### Install Dependencies for OTLP Traces

Source: https://www.getmaxim.ai/docs/cookbooks/integrations/otel

Install the necessary Python packages for OpenTelemetry, OTLP export, OpenAI instrumentation, and environment variable management.

```bash
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-openai openai python-dotenv
```

--------------------------------

### Define YieldedOutput Examples

Source: https://www.getmaxim.ai/docs/sdk/typescript/reference/core/overview

Examples demonstrating how to structure output data for test runs, including simple strings and complex objects with metadata.

```ts
// Simple output
const output: YieldedOutput = {
  data: "The weather in San Francisco is sunny and 72°F"
};
```

```ts
// Output with full metadata
const output: YieldedOutput = {
  data: "Based on the provided documents, the answer is...",
  retrievedContextToEvaluate: [
    "Document 1: Weather data shows...",
    "Document 2: Historical trends indicate..."
  ],
  meta: {
    usage: {
      promptTokens: 150,
      completionTokens: 45,
      totalTokens: 195,
      latency: 1200
    },
    cost: {
      input: 0.0015,
      output: 0.0045,
      total: 0.006
    }
  }
};
```

```ts
// Using in yieldsOutput function
maxim.createTestRun("accuracy-test", "workspace-id")
  .yieldsOutput(async (data) => {
    const response = await callLLM(data.input);
    return {
      data: response.text,
      meta: {
        usage: response.usage,
        cost: response.cost
      }
    };
  });
```

--------------------------------

### Example TestRunResult Object

Source: https://www.getmaxim.ai/docs/sdk/typescript/reference/core/overview

An example of how a TestRunResult object might be structured, showing detailed metrics for individual evaluators, usage, cost, and latency.

```typescript
const testResult: TestRunResult = {
  link: "https://app.getmaxim.ai/workspace/123/test-runs/456",
  result: [{
    name: "Accuracy Test Run",
    individualEvaluatorMeanScore: {
      "bias": { score: 0.87, pass: true, outOf: 1.0 },
      "toxicity": { score: 0.92, pass: true, outOf: 1.0 },
      "custom-programmatic-evaluator": { score: 1.0, pass: true }
    },
    usage: {
      total: 15420,
      input: 12300,
      completion: 3120
    },
    cost: {
      total: 0.0234,
      input: 0.0123,
      completion: 0.0111
    },
    latency: {
      min: 890,
      max: 2340,
      p50: 1200,
      p90: 1800,
      p95: 2100,
      p99: 2300,
      mean: 1350,
      standardDeviation: 320,
      total: 135000
    }
  }]
};
```

--------------------------------

### Configure Maxim SDK in Node.js

Source: https://www.getmaxim.ai/docs/sdk/typescript/setup

Initialize the Maxim SDK with your API key and optional base URL. Ensure 'promptManagement' is set if needed.

```javascript
import { Maxim } from '@maximai/maxim-js';

const maxim = new Maxim({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.getmaxim.ai', // Optional
  promptManagement: true, // Optional, default: true
  debug: false // Optional, default: false
});
```

--------------------------------

### Install Node.js Polyfills for React Native

Source: https://www.getmaxim.ai/docs/sdk/typescript/setup

Install necessary Node.js polyfills required for the Maxim SDK to function correctly within a React Native environment.

```bash
npm install react-native-fs react-native-os react-native-path crypto-js stream-browserify https-browserify http-browserify events inherits url util buffer process querystring punycode assert constants mime-types @types/mime-types
```
Tokens:
Raw