npm package: @spyglass_ai/sdk
Description: TypeScript SDK for shipping telemetry data to the Spyglass AI platform
Author: Spyglass AI Team
Latest version: 0.1.0

# Spyglass TypeScript SDK

TypeScript SDK for shipping telemetry data to the Spyglass AI platform.

## Installation

```bash
npm install @spyglass-ai/sdk
```

or

```bash
yarn add @spyglass-ai/sdk
```

## Configuration

Set the following environment variables:

### Required
- `SPYGLASS_API_KEY`: Your Spyglass API key
- `SPYGLASS_DEPLOYMENT_ID`: Unique identifier for your deployment

### Optional
- `SPYGLASS_OTEL_EXPORTER_OTLP_ENDPOINT`: Custom endpoint for development

### Example Configuration

```bash
export SPYGLASS_API_KEY="your-api-key"
export SPYGLASS_DEPLOYMENT_ID="user-service-v1.2.0"
```

## Usage

### Basic Function Tracing

Use `spyglassTrace` to wrap functions:

```typescript
import { spyglassTrace } from '@spyglass-ai/sdk';

const calculateTotal = spyglassTrace()((price: number, taxRate: number) => {
  return price * (1 + taxRate);
});

const result = calculateTotal(100, 0.08);
```

With a custom span name:

```typescript
const processPayment = spyglassTrace({ name: 'payment_processing' })(
  (amount: number, cardInfo: any) => {
    return { status: 'success', transactionId: 'tx_123' };
  }
);
```

### Async Function Tracing

Async functions work the same way:

```typescript
const fetchUser = spyglassTrace()(async (userId: string) => {
  const response = await fetch(`/api/users/${userId}`);
  return response.json();
});
```

### OpenAI Integration

Wrap your OpenAI client to trace API calls:

```typescript
import OpenAI from 'openai';
import { spyglassOpenai } from '@spyglass-ai/sdk';

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

const tracedClient = spyglassOpenai(client);

const response = await tracedClient.chat.completions.create({
  model: 'gpt-3.5-turbo',
  messages: [{ role: 'user', content: 'Hello!' }],
  max_tokens: 100,
});
```

### Complete Example

```typescript
import OpenAI from 'openai';
import { spyglassTrace, spyglassOpenai } from '@spyglass-ai/sdk';

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

const haveConversation = spyglassTrace({ name: 'ai_conversation' })(
  async (userMessage: string) => {
    const response = await client.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: userMessage }],
      max_tokens: 150,
    });
    return response.choices[0].message.content;
  }
);

const answer = await haveConversation('What is the capital of France?');
console.log(answer);
```

## What Gets Traced

### Function Tracing (`spyglassTrace`)
- Function name and qualified name
- Input arguments
- Return values
- Execution time
- Exceptions

### OpenAI Integration (`spyglassOpenai`)
- Model used
- Number of messages
- Request parameters (max_tokens, temperature, etc.)
- Token usage (prompt, completion, total)
- Response model
- API errors

## Development

### Install Dependencies

```bash
npm install
```

### Build

```bash
npm run build
```

### Run Tests

```bash
npm test
```

### Run Tests with Coverage

```bash
npm run test:coverage
```

### Lint

```bash
npm run lint
```

### Format

```bash
npm run format
```

## TypeScript Support

Full TypeScript definitions included.

## License

MIT