### Complete LangChain Setup Example

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/reference/overview.mdx

A complete example demonstrating the setup and integration of MaximLangchainTracer with LangChain components.

```javascript
import { MaximLangchainTracer } from "@maximai/maxim-js";
import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";

// Initialize Maxim (standard setup)
const maxim = new Maxim({ apiKey: "your-maxim-api-key" });
const logger = await maxim.logger({ id: "your-log-repository-id" });

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

// Your existing LangChain code remains unchanged
const prompt = ChatPromptTemplate.fromTemplate("What is {topic}?");
const model = new ChatOpenAI({ model: "gpt-3.5-turbo" });
const chain = prompt.pipe(model);

// Step 2: Add tracer to your invoke calls
const result = await chain.invoke({ topic: "AI" }, { callbacks: [maximTracer] });

// Alternative: Attach permanently to the chain
const chainWithTracer = chain.withConfig({ callbacks: [maximTracer] });
const result2 = await chainWithTracer.invoke({ topic: "machine learning" });
```

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

### Project Setup and Dependency Installation

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/openai-realtime.mdx

Initialize a new Node.js project and install necessary dependencies for OpenAI, Maxim, audio handling, and TypeScript.

```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
```

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

### 5-Minute Bifrost Setup

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/contributing/overview.mdx

Follow these steps to quickly set up your Bifrost development environment. This includes cloning the repository, installing dependencies, and verifying the setup.

```bash
# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/bifrost.git
cd bifrost

# 2. Install dependencies
go mod download

# 3. Verify setup
go test ./core/...
cd transports && go build -o bifrost-http

# 4. You're ready! 🎉
```

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

### Install Maxim Go SDK

Source: https://github.com/maximhq/maxim-docs/blob/main/tracing/quickstart.mdx

Install the Maxim Go SDK using go get.

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

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

### Complete Implementation Example

Source: https://github.com/maximhq/maxim-docs/blob/main/evaluate/how-to/trigger-test-runs-using-sdk.mdx

This Python script demonstrates a full test run setup using the Maxim SDK. It includes defining a custom evaluator, configuring data structures, running the test, and handling results and exceptions. Ensure you replace 'YOUR_API_KEY', 'your-workspace-id', and 'your_model.generate_answer' with your actual credentials and model integration.

```Python
from maxim import Maxim, Config
from maxim.evaluators.evaluators import create_custom_evaluator
from maxim.models.dataset import ManualData
from maxim.models.evaluator import LocalEvaluatorResultParameter, LocalEvaluatorReturn, PassFailCriteria, PassFailCriteriaForTestrunOverall, PassFailCriteriaOnEachEntry
import time

maxim = Maxim(Config(api_key="YOUR_API_KEY"))

def apostrophe_checker(result: LocalEvaluatorResultParameter, data: ManualData) -> LocalEvaluatorReturn:
    if "'" in result.output:
        return LocalEvaluatorReturn(
            score=True,
            reasoning="The output contains an apostrophe"
        )
    else:
        return LocalEvaluatorReturn(
            score=False,
            reasoning="The output does not contain an apostrophe"
        )

custom_evaluator = create_custom_evaluator(
    "apostrophe-checker",
    apostrophe_checker,
    PassFailCriteria(
        on_each_entry=PassFailCriteriaOnEachEntry(
            score_should_be="=",
            value=True
        ),
        for_testrun_overall=PassFailCriteriaForTestrunOverall(
            overall_should_be=">=",
            value=80,
            for_result="percentageOfPassedResults"
        )
    )
)

def run(data):
    start_time = time.time()

    # Your model call here
    response = your_model.generate_answer(
        data.question,
        data.context
    )

    latency = (time.time() - start_time) * 1000  # Convert to milliseconds

    return {
        "data": response.answer,
        # Returning a value here will utilize this context for
        # evaluation instead of the CONTEXT_TO_EVALUATE column
        # (in this case, the `context` column)
        "retrieved_context_to_evaluate": response.retrieved_context,
        "meta": {
            "usage": {
                "prompt_tokens": response.tokens.prompt,
                "completion_tokens": response.tokens.completion,
                "total_tokens": response.tokens.total,
                "latency": latency
            },
            "cost": {
                "input_cost": response.cost.prompt,
                "output_cost": response.cost.completion,
                "total_cost": response.cost.total
            }
        }
    }


testData = [] # Assume testData is populated elsewhere

try:
    result = maxim
        .create_test_run(f"QA Evaluation {time.time()}", 'your-workspace-id')
        .with_data_structure({
            "question": "INPUT",
            "expected_answer": "EXPECTED_OUTPUT",
            "context": "CONTEXT_TO_EVALUATE",
            "metadata": "NULLABLE_VARIABLE"
        })
        .with_data(testData)
        .yields_output(lambda data : run(data))
        .with_evaluators(
            custom_evaluator,
            "Faithfulness",
            "Answer Relevance",
            "Human Evaluator"
        )
        .with_human_evaluation_config({
            "emails": ["qa-team@company.com"],
            "instructions": 'Please evaluate the responses for accuracy and completeness. Consider both factual correctness and answer format.'
        })
        .with_concurrency(10)
        .run(30*60); # 30 minutes timeout in seconds

    print("Test Run Link:", result.test_run_result.link);
    print("Failed Entries:", result.failed_entry_indices);
    print("Evaluation Results:", result.test_run_result.result[0]);
except Exception as e:
    print("Test Run Failed:", e)
finally:
    maxim.cleanup();

```

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

### Start Bifrost with Go Binary

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/quickstart/http-transport.mdx

Install the Bifrost HTTP transport binary using Go and run it on port 8080.

```bash
go install github.com/maximhq/bifrost/transports/bifrost-http@latest
bifrost-http -port 8080
```

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

### Initialize Go Module and Install Bifrost Package

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/quickstart/go-package.mdx

Initialize your Go project's module and install the core Bifrost package. Ensure you have Go installed and configured.

```bash
go mod init my-bifrost-app
go get github.com/maximhq/bifrost/core
```

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

### Install Zod for Tool Calling (bun)

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/langchain/langchain.mdx

Installs the Zod library using bun, required for tool calling examples.

```bash
bun add zod
```

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

### Example: Download Maxim CLI for Linux amd64

Source: https://github.com/maximhq/maxim-docs/blob/main/cicd/maxim-cli.mdx

This is a concrete example of downloading the Maxim CLI for a Linux amd64 system.

```bash
wget https://downloads.getmaxim.ai/cli/v1/linux/amd64/maxim
```

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

### Install Maxim SDK for JS/TS, Python, and Go

Source: https://github.com/maximhq/maxim-docs/blob/main/tracing/tracing-via-sdk/metadata.mdx

Install the necessary Maxim SDK package for your project using npm, pip, or go get.

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

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

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

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

### Package Documentation Example

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/contributing/code-conventions.mdx

Illustrates standard Go package documentation, including a description of the package's purpose, its role in the project, and an example of its usage.

```go
// Package providers implements AI model provider integrations for Bifrost.
//
// This package provides a unified interface for communicating with different
// AI providers such as OpenAI, Anthropic, Google Vertex AI, and others.
//
// Each provider implements the Provider interface, which defines standard
// methods for chat completion, text completion, and other AI operations.
// Providers handle the specifics of API communication, request/response
// transformation, and error handling for their respective services.
//
// Example usage:
//
//     provider := providers.NewOpenAIProvider(config, logger)
//     response, err := provider.ChatCompletion(ctx, model, apiKey, messages, params)
//     if err != nil {
//         // Handle error
//     }
//     // Use response
//
// Provider implementations are designed to be:
//   - Thread-safe for concurrent use
//   - Consistent in error handling and response formats
//   - Optimized for performance with connection pooling and retries
//   - Configurable through the ProviderConfig structure
package providers
```

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

### File-Based Configuration Example

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/quickstart/http-transport.mdx

Create a config.json file to define providers and their keys. This example configures an OpenAI provider.

```json
{
  "providers": {
    "openai": {
      "keys": [
        {
          "value": "env.OPENAI_API_KEY",
          "models": ["gpt-4o-mini"],
          "weight": 1.0
        }
      ]
    }
  }
}
```

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

### Running the Financial Advisor Agent with Maxim

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/google-adk/google-adk.mdx

These bash commands guide you through setting up and running the financial advisor agent with Maxim instrumentation. This includes navigating to the directory, installing dependencies, creating the main script, and executing the agent. Optional commands for running tests and evaluations are also provided.

```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

```

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

### Complete Pydantic AI and Maxim Integration Example

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/pydantic-ai/pydantic_ai.mdx

This example demonstrates a full integration of Pydantic AI with Maxim. It includes setting up a Maxim client, instrumenting Pydantic AI for logging, creating a Pydantic AI agent with custom tools, and managing agent runs within a session trace. Ensure you have `dotenv` installed and an OpenAI API key set in your environment variables.

```python
import os
import asyncio
from typing import List
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Import Maxim components
from maxim import Maxim
from maxim.logger.pydantic_ai import instrument_pydantic_ai

# Import Pydantic AI components
from pydantic_ai import Agent, RunContext

def create_simple_agent():
    """Create a simple Pydantic AI agent."""
    # Create an agent with simple tools
    agent = Agent(
        model="openai:gpt-4o-mini",
        name="Simple Agent",
        instructions="You are a helpful assistant that can perform calculations."
    )
    
    @agent.tool
    def add_numbers(ctx: RunContext, a: float, b: float) -> float:
        """Add two numbers together."""
        print(f"[Tool] Adding {a} + {b}")
        return a + b
    
    @agent.tool
    def multiply_numbers(ctx: RunContext, a: float, b: float) -> float:
        """Multiply two numbers together."""
        print(f"[Tool] Multiplying {a} * {b}")
        return a * b
    
    return agent

def run_simple_example_with_session():
    """Run a simple example with session management."""
    print("=== Simple Agent Example with Session Management ===")
    
    # Create and instrument the agent
    agent = create_simple_agent()
    print("Instrumenting Pydantic AI...")
    instrument_pydantic_ai(Maxim().logger(), debug=True)
    print("Instrumentation complete!")
    
    # Start a session trace to group multiple agent runs
    print("Starting session trace...")
    instrument_pydantic_ai.start_session("Math Calculator Session")
    
    try:
        # Run multiple calculations in the same session
        print("Running first calculation...")
        result = agent.run_sync("What is 15 + 27?")
        print(f"Result: {result}")
        
        print("Running second calculation...")
        result = agent.run_sync("Calculate 8 * 12")
        print(f"Result: {result}")
        
        print("Running third calculation...")
        result = agent.run_sync("What is 25 + 17 and then multiply that result by 3?")
        print(f"Result: {result}")
        
    finally:
        # End the session trace
        print("Ending session trace...")
        instrument_pydantic_ai.end_session()

# Set up and run
run_simple_example_with_session()

```

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

### Install Bifrost HTTP Binary

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/http-transport/overview.mdx

Install the Bifrost HTTP transport binary using go install.

```bash
# Install
go install github.com/maximhq/bifrost/transports/bifrost-http@latest
```

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

### Install Maxim SDK

Source: https://github.com/maximhq/maxim-docs/blob/main/tracing/tracing-via-sdk/traces.mdx

Install the Maxim SDK for your project. Choose the package manager and language that suits your development environment.

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

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

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

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

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

### Install Maxim SDK

Source: https://github.com/maximhq/maxim-docs/blob/main/offline-evals/via-sdk/agent-http/quickstart.mdx

Install the Maxim SDK for Python or JavaScript/TypeScript using pip or npm.

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

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

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

### Initialize Maxim SDK in Go

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/overview.mdx

This Go code snippet shows how to initialize the Maxim SDK. You can get the SDK using 'go get github.com/maximhq/maxim-go'.

```go
import "github.com/maximhq/maxim-go"

mx := maxim.Init(&maxim.MaximSDKConfig{ApiKey: ""})
```

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

### Install Project Dependencies

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/elevenlabs.mdx

Install all necessary Python packages for the project using pip and a requirements.txt file.

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

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

### Start Bifrost with File-Based Configuration (Go Binary)

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/quickstart/http-transport.mdx

Run the Bifrost HTTP binary, specifying the application directory and port.

```bash
bifrost-http -app-dir . -port 8080
```

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

### Install Zod for Tool Calling (pnpm)

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/langchain/langchain.mdx

Installs the Zod library using pnpm, required for tool calling examples.

```bash
pnpm add zod
```

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

### Install Zod for Tool Calling (yarn)

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/langchain/langchain.mdx

Installs the Zod library using yarn, required for tool calling examples.

```bash
yarn add zod
```

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

### Bifrost Client Initialization with Custom Plugin

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/overview.mdx

Demonstrates initializing the Bifrost client with a custom plugin, allowing for extended functionality or middleware integration.

```go
client, _ := bifrost.Init(schemas.BifrostConfig{
    Account: &MyAccount{},
    Plugins: []schemas.Plugin{&MyCustomPlugin{}},
})
```

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

### Install Zod for Tool Calling (npm)

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/langchain/langchain.mdx

Installs the Zod library using npm, required for tool calling examples.

```bash
npm install zod
```

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

### Initializing Bifrost Client with Plugins

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/plugins.mdx

Demonstrates how to add custom plugins (logging, rate limiting, caching) to the Bifrost client during initialization. The `defer client.Cleanup()` ensures that all plugins' Cleanup methods are called.

```go
// Add plugins to your Bifrost client
client, initErr := bifrost.Init(schemas.BifrostConfig{
    Account: &MyAccount{},
    Plugins: []schemas.Plugin{
        NewLoggingPlugin(),
        NewRateLimitPlugin(100), // 100 requests per user
        NewCachePlugin(time.Hour), // 1 hour cache
    },
})
deffer client.Cleanup() // Calls Cleanup() on all plugins
```

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

### Register Agents and Start Session

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/livekit.mdx

Register agents in user data and start an AgentSession with LiveKit. This snippet shows the basic setup for an agent-based application.

```python
    # Register all agents in the userdata
    userdata.personas.update(
        {"triage": triage_agent, "sales": sales_agent, "returns": returns_agent}
    )

    # Create session with userdata
    session = AgentSession[UserData](userdata=userdata)

    await session.start(
        agent=triage_agent,  # Start with the Triage agent
        room=ctx.room,
    )
```

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

### Account Interface Implementation

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/schemas.mdx

Provides an example implementation of the Account interface, showing how to configure providers, retrieve API keys, and set provider configurations.

```go
type Account interface {
    GetConfiguredProviders() ([]ModelProvider, error)
    GetKeysForProvider(ModelProvider) ([]Key, error)
    GetConfigForProvider(ModelProvider) (*ProviderConfig, error)
}

// Example implementation pattern
type MyAccount struct {
    // Your configuration data
}

func (a *MyAccount) GetConfiguredProviders() ([]schemas.ModelProvider, error) {
    return []schemas.ModelProvider{
        schemas.OpenAI,
        schemas.Anthropic,
        schemas.Vertex,
    }, nil
}

func (a *MyAccount) GetKeysForProvider(provider schemas.ModelProvider) ([]schemas.Key, error) {
    switch provider {
    case schemas.OpenAI:
        return []schemas.Key{{ Value:  os.Getenv("OPENAI_API_KEY"), Models: []string{"gpt-4o-mini", "gpt-4o"}, Weight: 1.0}},
il
    // ... other providers
    }
    return nil, fmt.Errorf("provider not supported")
}

func (a *MyAccount) GetConfigForProvider(provider schemas.ModelProvider) (*schemas.ProviderConfig, error) {
    return &schemas.ProviderConfig{
        NetworkConfig:            schemas.DefaultNetworkConfig,
        ConcurrencyAndBufferSize: schemas.DefaultConcurrencyAndBufferSize,
        // Provider-specific MetaConfig if needed
    },
    nil
}

```

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

### Get Agent Response with LangGraph Decorator

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/langgraph/langgraph-with-decorator.mdx

This snippet shows how to get a response from an agent using the handle function within a LangGraph setup. Ensure the handle function and necessary imports are defined.

```python
resp = await handle("is there any new iron man movies coming this year?")
print(resp)
```

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

### Dynamic MCP Client Lifecycle Management in Go

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/mcp.mdx

This example demonstrates the complete lifecycle of managing MCP clients dynamically. It shows how to add clients based on runtime conditions, configure their tool access, monitor their connections, and clean them up when no longer needed. Ensure the Bifrost library and necessary schemas are imported.

```go
func manageMCPClients(client *bifrost.Bifrost) {
    // 1. Add clients based on runtime conditions
    if needsFileAccess() {
        fileClientConfig := schemas.MCPClientConfig{
            Name:           "runtime-filesystem",
            ConnectionType: schemas.MCPConnectionTypeSTDIO,
            StdioConfig: &schemas.MCPStdioConfig{
                Command: "npx",
                Args:    []string{"npx", "-y", "@modelcontextprotocol/server-filesystem"},
                Envs:    []string{"FILESYSTEM_ROOT"},
            },
        }
        
        if err := client.AddMCPClient(fileClientConfig); err != nil {
            log.Printf("Failed to add filesystem client: %v", err)
        }
    }

    // 2. Configure tool access based on user permissions
    if isRestrictedUser() {
        // Only allow safe read operations
        safeTools := []string{"read_file", "list_directory"}
        err := client.EditMCPClientTools("runtime-filesystem", safeTools, []string{})
        if err != nil {
            log.Printf("Failed to restrict tools: %v", err)
        }
    }

    // 3. Monitor and maintain connections
    go func() {
        ticker := time.NewTicker(30 * time.Second)
        defer ticker.Stop()
        
        for range ticker.C {
            clients, err := client.GetMCPClients()
            if err != nil {
                continue
            }
            
            for _, mcpClient := range clients {
                if mcpClient.State != schemas.MCPConnectionStateConnected {
                    log.Printf("Detected disconnected client: %s (state: %s)", mcpClient.Name, mcpClient.State)
                    if err := client.ReconnectMCPClient(mcpClient.Name); err != nil {
                        log.Printf("Failed to reconnect %s: %v", mcpClient.Name, err)
                    }
                }
            }
        }
    }()

    // 4. Cleanup when done
    defer func() {
        // Remove temporary clients
        if err := client.RemoveMCPClient("runtime-filesystem"); err != nil {
            log.Printf("Failed to remove temporary client: %v", err)
        }
    }()
}

func needsFileAccess() bool {
    // Your logic to determine if file access is needed
    return true
}

func isRestrictedUser() bool {
    // Your logic to determine user permissions
    return false
}
```

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

### Define a Function Tool for Gemini

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/gemini/gemini.mdx

Define a Python function that can be used as a tool by the Gemini model. This example defines a function to get current weather.

```python
def get_current_weather(location: str) -> str:
    """Get the current weather in a given location.
    Args:
        location: required, The city and state, e.g. San Francisco, CA
    """
    print(f"Called with: {location=}")
    return "23°C, sunny"
```

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

### Initialize OpenTelemetry Tracing

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/livekit/livekit-otel.mdx

Call the setup function at the start of your application to initialize OpenTelemetry tracing. Can be used with or without additional metadata for enriching traces.

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

```python
# 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,
        },
    }
)
```

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

### Environment Variable Management Example

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/key-management.mdx

Demonstrates recommended practices for exporting API keys as environment variables using descriptive naming and avoiding hardcoding. Shows both good and bad examples.

```bash
# Use descriptive naming
export OPENAI_PRIMARY_KEY="sk-..."
export OPENAI_FALLBACK_KEY="sk-..."
export ANTHROPIC_PRODUCTION_KEY="sk-ant-..."

# Avoid hardcoding in config files
# ❌ Bad
# {
#   "value": "sk-actual-key-here"
# }

# ✅ Good
# {
#   "value": "env.OPENAI_API_KEY"
# }
```

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

### System Message Request

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/http-transport/integrations/anthropic-compatible.mdx

Include a system message to guide the AI's behavior. This example sets the assistant's role to a helpful geography expert.

```bash
curl -X POST http://localhost:8080/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1000,
    "system": "You are a helpful assistant that answers questions about geography.",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'
```

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

### Set Up a Virtual Environment

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/elevenlabs.mdx

Create and activate a Python virtual environment to manage project dependencies.

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

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

### Python OpenAI SDK Example

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/http-transport/endpoints.mdx

Use the Python OpenAI SDK to send a chat completion request to a local endpoint. Ensure the SDK is installed and the base URL is correctly configured.

```python
import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/openai",
    api_key="your-openai-key"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

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

### Basic BifrostConfig Initialization

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/schemas.mdx

Example of initializing BifrostConfig with essential account details.

```go
// Basic configuration
config := schemas.BifrostConfig{
    Account: &MyAccount{},
}
```

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

### Example Usage of ChatCompletion

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/contributing/code-conventions.mdx

Demonstrates how to call the ChatCompletion function with sample messages and parameters, including basic error handling for authentication. This shows a typical workflow for getting a response from the OpenAI API.

```go
messages := []schemas.BifrostMessage{
        {Role: "user", Content: schemas.MessageContent{ContentStr: &prompt}},
    }
    params := &schemas.ModelParameters{Temperature: &temp, MaxTokens: &maxTokens}

    response, err := provider.ChatCompletion(ctx, "gpt-4o-mini", apiKey, messages, params)
    if err != nil {
        if err.StatusCode != nil && *err.StatusCode == 401 {
            // Handle authentication error
        }
        return err
    }

    content := response.Choices[0].Message.Content.ContentStr
    fmt.Println(*content)
```

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

### Initializing a Generation Log Entry

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/reference/core/classes/Generation.mdx

This example shows how to create a new Generation log entry using the constructor with specific configuration. Use this when you need to start logging a new LLM interaction.

```typescript
const generation = container.generation({
  id: 'response-gen-001',
  name: 'Customer Query Response',
  provider: 'openai',
  model: 'gpt-4',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'How do I reset my password?' }
  ],
  modelParameters: { temperature: 0.7, max_tokens: 200 }
});
```

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

### Add Filesystem and HTTP MCP Clients at Runtime

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/mcp.mdx

Demonstrates adding new MCP clients, including a filesystem client with stdio configuration and an HTTP client with a connection string, after the MCP client has been initialized.

```go
// Add a new filesystem client
newClientConfig := schemas.MCPClientConfig{
    Name:           "new-filesystem",
    ConnectionType: schemas.MCPConnectionTypeSTDIO,
    StdioConfig: &schemas.MCPStdioConfig{
        Command: "npx",
        Args:    []string{"npx", "-y", "@modelcontextprotocol/server-filesystem"},
        Envs:    []string{"FILESYSTEM_ROOT"},
    },
}

err := client.AddMCPClient(newClientConfig)
if err != nil {
    log.Printf("Failed to add MCP client: %v", err)
}

// Add HTTP client
httpEndpoint := "http://localhost:8080/mcp"
httpClientConfig := schemas.MCPClientConfig{
    Name:             "api-tools",
    ConnectionType:   schemas.MCPConnectionTypeHTTP,
    ConnectionString: &httpEndpoint,
}

err = client.AddMCPClient(httpClientConfig)
if err != nil {
    log.Printf("Failed to add HTTP MCP client: %v", err)
}
```

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

### Load Plugins via Command-line (Go Binary)

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/http-transport/configuration/plugins.mdx

Specify configuration file and plugin names when running the Bifrost HTTP server binary.

```bash
bifrost-http -config config.json -plugins "maxim,custom-plugin"
```

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

### Go Binary Deployment for MCP (All Connection Types)

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/http-transport/configuration/mcp.mdx

Instructions to install and run the Bifrost Go binary, which supports all MCP connection types. Environment variables are automatically picked up.

```bash
# All environment variables are picked up automatically
export OPENAI_API_KEY="your-openai-key"
export SEARCH_API_KEY="your-search-key"

go install github.com/maximhq/bifrost/transports/bifrost-http@latest
bifrost-http -config config.json -port 8080 -plugins maxim
```

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

### TypeScript Example: OpenAI Tool Calling

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/openai/responses.mdx

This snippet shows how to set up the MaximOpenAIClient, define tools for OpenAI, and make a request to get a function call response. Ensure you have MAXIM_API_KEY, MAXIM_LOG_REPO_ID, and OPENAI_API_KEY environment variables set.

```typescript
import OpenAI from "openai";
import { Maxim } from "@maximai/maxim-js";
import { MaximOpenAIClient } from "@maximai/maxim-js/openai";

async function main() {
  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");
  }

  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  const client = new MaximOpenAIClient(openai, logger);

  // Define tools
  const tools: OpenAI.Responses.Tool[] = [
    {
      type: "function",
      name: "get_weather",
      description: "Get the current weather in a given location",
      strict: false,
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g. San Francisco, CA",
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
          },
        },
        required: ["location"],
      },
    },
  ];

  const response = await client.responses.create({
    model: "gpt-4o-mini",
    input: "What's the weather like in San Francisco?",
    tools: tools,
    tool_choice: "required",
  });

  console.log("Response:", JSON.stringify(response.output, null, 2));

  // Check for function calls in the output
  const functionCalls = response.output.filter(
    (item) => item.type === "function_call"
  );

  if (functionCalls.length > 0) {
    console.log("Function calls:", functionCalls);
  }

  await logger.cleanup();
  await maxim.cleanup();
}

main().catch(console.error);

```

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

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

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/langgraph/langgraph.mdx

A minimal example demonstrating how to create a LangGraph agent using ChatOpenAI, a calculator tool, and integrate MaximLangchainTracer for logging. Ensure your .env file is set up correctly.

```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();

```

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

### Complete Example with Custom Metadata

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/reference/overview.mdx

A comprehensive example demonstrating custom trace names, tags, and session linking for a LangChain operation. Includes non-Maxim metadata as well.

```javascript
const result = await chain.invoke(
	{ query: "What is machine learning?" },
	{
		callbacks: [maximTracer],
		metadata: {
			maxim: {
				// Custom names for better organization
				traceName: "ML Question Answering",

				// Custom tags for filtering and analytics
				traceTags: {
					category: "educational",
					priority: "high",
					version: "v2.1",
				},

				// Link to existing session (optional)
				sessionId: "user_session_123",
			},
			// You can also include non-Maxim metadata
			user_id: "user_123",
			request_id: "req_456",
		},
	}
);
```

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

### Complete Personal Shopper Agent Example

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/livekit.mdx

This Python script defines a complete personal shopper agent using LiveKit Agents. It includes setup for LLM, STT, TTS, VAD, customer data management, and agent context transfer.

```python
import logging
from dataclasses import dataclass, field
from typing import Optional

from database import CustomerDatabase
from dotenv import load_dotenv
from livekit.agents import JobContext, WorkerOptions, cli
from livekit.agents.llm import function_tool
from livekit.agents.voice import Agent, AgentSession, RunContext
from livekit.plugins import deepgram, openai, silero
from utils import load_prompt
from maxim import Maxim
from maxim.logger.livekit import instrument_livekit

load_dotenv()

maxim = Maxim()
maxim_logger = maxim.logger()
instrument_livekit(maxim_logger)


# Initialize the customer database
db = CustomerDatabase()


@dataclass
class UserData:
    """Class to store user data and agents during a call."""

    personas: dict[str, Agent] = field(default_factory=dict)
    prev_agent: Optional[Agent] = None
    ctx: Optional[JobContext] = None

    # Customer information
    first_name: Optional[str] = None
    last_name: Optional[str] = None
    customer_id: Optional[str] = None
    current_order: Optional[dict] = None

    def is_identified(self) -> bool:
        """Check if the customer is identified."""
        return self.first_name is not None and self.last_name is not None

    def reset(self) -> None:
        """Reset customer information."""
        self.first_name = None
        self.last_name = None
        self.customer_id = None
        self.current_order = None

    def summarize(self) -> str:
        """Return a summary of the user data."""
        if self.is_identified():
            return (
                f"Customer: {self.first_name} {self.last_name} (ID: {self.customer_id})"
            )
        return "Customer not yet identified."


RunContext_T = RunContext[UserData]


class BaseAgent(Agent):
    async def on_enter(self) -> None:
        agent_name = self.__class__.__name__

        userdata: UserData = self.session.userdata
        if userdata.ctx and userdata.ctx.room:
            await userdata.ctx.room.local_participant.set_attributes(
                {"agent": agent_name}
            )

        # Create a personalized prompt based on customer identification
        custom_instructions = self.instructions
        if userdata.is_identified():
            custom_instructions += (
                f"\n\nYou are speaking with {userdata.first_name} {userdata.last_name}."
            )

        chat_ctx = self.chat_ctx.copy()

        # Copy context from previous agent if it exists
        if userdata.prev_agent:
            items_copy = self._truncate_chat_ctx(
                userdata.prev_agent.chat_ctx.items, keep_function_call=True
            )
            existing_ids = {item.id for item in chat_ctx.items}
            items_copy = [item for item in items_copy if item.id not in existing_ids]
            chat_ctx.items.extend(items_copy)

        chat_ctx.add_message(
            role="system", content=f"You are the {agent_name}. {userdata.summarize()}"
        )
        await self.update_chat_ctx(chat_ctx)
        self.session.generate_reply()

    def _truncate_chat_ctx(
        self,
        items: list,
        keep_last_n_messages: int = 6,
        keep_system_message: bool = False,
        keep_function_call: bool = False,
    ) -> list:
        """Truncate the chat context to keep the last n messages."""

        def _valid_item(item) -> bool:
            if (
                not keep_system_message
                and item.type == "message"
                and item.role == "system"
            ):
                return False
            if not keep_function_call and item.type in [
                "function_call",
                "function_call_output",
            ]:
                return False
            return True

        new_items = []
        for item in reversed(items):
            if _valid_item(item):
                new_items.append(item)
            if len(new_items) >= keep_last_n_messages:
                break
        new_items = new_items[::-1]

        while new_items and new_items[0].type in [
            "function_call",
            "function_call_output",
        ]:
            new_items.pop(0)

        return new_items

    async def _transfer_to_agent(self, name: str, context: RunContext_T) -> Agent:
        """Transfer to another agent while preserving context."""
        userdata = context.userdata
        current_agent = context.session.current_agent
        next_agent = userdata.personas[name]
        userdata.prev_agent = current_agent

        return next_agent


class TriageAgent(BaseAgent):
    def __init__(self) -> None:
        super().__init__(
            instructions=load_prompt("triage_prompt.yaml"),
            stt=deepgram.STT(),
            llm=openai.LLM(model="gpt-4o-mini"),
            tts=openai.TTS(),
            vad=silero.VAD.load(),
        )

```

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

### Initialize MaximGeminiClient with API Key

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/gemini/gemini.mdx

Load environment variables and initialize the Maxim logger and MaximGeminiClient. Ensure GEMINI_API_KEY is set.

```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
)
```

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

### Get Historical Stock Price Data

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/groq.mdx

Retrieves historical stock price data for a given symbol between specified start and end dates. It utilizes the `parse_relative_date` function to handle flexible date inputs and returns data in a list of dictionaries format.

```python
def get_historical_price(symbol: str, start_date: str, end_date: str):
    """Retrieve historical stock price data"""
    try:
        # Parse relative dates
        parsed_start = parse_relative_date(start_date)
        parsed_end = parse_relative_date(end_date)

        print(f"Parsed dates: {start_date} -> {parsed_start}, {end_date} -> {parsed_end}")

        hist = yf.Ticker(symbol).history(start=parsed_start, end=parsed_end).reset_index()
        hist[symbol] = hist['Close']
        return hist[['Date', symbol]].to_dict(orient='records')
    except Exception as e:
        return f"Error retrieving historical data: {str(e)}"

```

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

### Initialize and Use Bifrost Client

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/bifrost-client.mdx

Initializes the Bifrost client with configuration and demonstrates making a chat completion request. Always ensure to defer client cleanup.

```go
// Initialize client
client, initErr := bifrost.Init(schemas.BifrostConfig{
    Account: &MyAccount{},
})
defer client.Cleanup() // Always cleanup!

// Make requests
response, bifrostErr := client.ChatCompletionRequest(ctx, request)
```

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

### Using Prompt Management with Maxim

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/reference/core/classes/Maxim.mdx

Demonstrates how to initialize Maxim with prompt management enabled, retrieve a prompt with specific deployment rules, and run it.

```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);
}
```

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

### Example: Fetch All Prompts

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/setup.mdx

Demonstrates how to retrieve all available prompts using the Maxim SDK. Ensure your API key is configured.

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

const maxim = new Maxim({
  apiKey: process.env.MAXIM_API_KEY,
  promptManagement: true
});

// Example: Get all prompts
async function getAllPrompts() {
  try {
    const prompts = await maxim.getPrompts();
    console.log('Available prompts:', prompts);
    return prompts;
  } catch (error) {
    console.error('Error fetching prompts:', error);
  }
}
```

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

### Basic Bifrost Client Initialization and Request

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/go-package/overview.mdx

Demonstrates the most common usage pattern: initializing the Bifrost client with a simple account implementation and making a chat completion request.

```go
import (
    bifrost "github.com/maximhq/bifrost/core"
    "github.com/maximhq/bifrost/core/schemas"
)

// Simple account implementation
type MyAccount struct{}
// ... implement Account interface

func main() {
    client, _ := bifrost.Init(schemas.BifrostConfig{
        Account: &MyAccount{},
    })
    defer client.Cleanup()

    response, err := client.ChatCompletionRequest(context.Background(), &schemas.BifrostRequest{
        Provider: schemas.OpenAI,
        Model:    "gpt-4o-mini",
        Input: schemas.RequestInput{
            ChatCompletionInput: &[]schemas.BifrostMessage{
                {Role: schemas.ModelChatMessageRoleUser, Content: schemas.MessageContent{ContentStr: &message}},
            },
        },
    })
}
```

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

### Install LangChain Core Package

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/reference/overview.mdx

Install the required LangChain core package for integration.

```bash
npm install @langchain/core
```

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

### Initialize MaximGeminiClient

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/gemini.mdx

Sets up the Gemini client and wraps it with Maxim's tracing capabilities. Requires your Gemini API key and the initialized Maxim logger.

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

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

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

### Basic OpenAI Realtime Setup with Maxim

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/openai/realtime.mdx

This snippet demonstrates the fundamental setup for using OpenAI Realtime with Maxim. It initializes Maxim, creates a logger, wraps the Realtime client, and configures session parameters upon connection. Ensure you have your `MAXIM_API_KEY` and `MAXIM_LOG_REPO_ID` environment variables set.

```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);

```

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

### Install Requirements

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/langchain/langchain.mdx

Ensure you have the necessary Python packages installed for Maxim and LangChain integration.

```bash
maxim-py
langchain-openai>=0.0.1
langchain
python-dotenv
```

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

### Install Fireworks and Maxim SDKs

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/integrations/fireworks/fireworks.mdx

Ensure you have the necessary SDKs installed for Fireworks AI and Maxim.

```bash
"fireworks-ai"
"maxim-py"
```

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

### Create and Navigate Project Directory

Source: https://github.com/maximhq/maxim-docs/blob/main/cookbooks/integrations/livekit.mdx

Commands to create a new project directory and change into it.

```bash
mkdir personal_shopper_agent
cd personal_shopper_agent
```

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

### Install Maxim SDK (JavaScript/TypeScript)

Source: https://github.com/maximhq/maxim-docs/blob/main/offline-evals/via-sdk/prompts/quickstart.mdx

Install the JavaScript/TypeScript version of the Maxim SDK using npm.

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

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

### Configure and Start Maxim Logger Plugin

Source: https://github.com/maximhq/maxim-docs/blob/main/bifrost/usage/http-transport/configuration/plugins.mdx

Set required environment variables for Maxim API key and repository ID, then start Bifrost with the 'maxim' plugin enabled.

```bash
# Environment variables required
export MAXIM_API_KEY="your-maxim-api-key"
export MAXIM_LOG_REPO_ID="your-repo-id"

# Start with Maxim plugin
bifrost-http -config config.json -plugins "maxim"
```

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

### Example: Download Maxim CLI for Windows

Source: https://github.com/maximhq/maxim-docs/blob/main/cicd/maxim-cli.mdx

To download the Maxim CLI for Windows, append the .exe extension to the filename.

```bash
wget https://downloads.getmaxim.ai/cli/v1/windows/amd64/maxim.exe
```

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

### Set up Environment Variables

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/setup.mdx

Configure your API key and repository ID using a .env file for secure access.

```env
MAXIM_API_KEY=your-api-key-here
MAXIM_REPOSITORY_ID=your-repository-id-here
```

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

### Get All Folders

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/python/references/apis/maxim_apis.mdx

Fetches a list of all available folders. Use this to get an overview of all folders in the system.

```python
def get_folders() -> List[Folder]
```

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

### Install LangChain Community Package (bun)

Source: https://github.com/maximhq/maxim-docs/blob/main/sdk/typescript/integrations/langchain/langchain.mdx

Installs the LangChain community package for other integrations using bun.

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