# Lyzr SDK for TypeScript/JavaScript

Official TypeScript/JavaScript SDK for the Lyzr AI Agent Platform.

## Installation

```bash
npm install @lyzr/sdk
```

## Quick Start

```typescript
import { Studio } from '@lyzr/sdk';

// Initialize SDK
const studio = new Studio({
  apiKey: 'sk-your-api-key'
  // or use LYZR_API_KEY environment variable
});

// Create an agent
const agent = await studio.createAgent({
  name: 'Assistant',
  provider: 'gpt-4o',
  role: 'Helpful assistant',
  goal: 'Answer user questions',
  instructions: 'Be concise and friendly'
});

// Run the agent
const response = await agent.run('Hello! What is machine learning?');
console.log(response.response);

// Delete when done
await agent.delete();
```

## Features

- **Smart Agents**: Create and manage AI agents with custom instructions
- **Knowledge Bases**: Build RAG systems with multiple data sources
- **Tools**: Register local functions for agent execution
- **Structured Outputs**: Type-safe responses with Zod schemas
- **Memory**: Conversation context with external providers
- **Streaming**: Real-time agent responses
- **RAI Guardrails**: Safety and compliance checks
- **Contexts**: Global background information
- **Image Models**: Generate images with DALL-E, Stability AI

## Supported Providers

### LLM Models
- **OpenAI**: GPT-4o, GPT-4o-mini, O3
- **Anthropic**: Claude Sonnet 4.5, Claude Opus 4.5
- **Google**: Gemini 2.0, Gemini 2.5, Gemini 3.0
- **Groq**: Llama 3.1/3.3/4
- **Perplexity**: Sonar, Sonar Pro
- **AWS Bedrock**: Nova, Claude, Llama, Mistral

### Vector Stores
- Qdrant
- Weaviate
- PostgreSQL (PG-Vector)
- Milvus
- Amazon Neptune

## API Reference

### Studio

```typescript
const studio = new Studio({
  apiKey: 'sk-xxx',
  env: 'prod',          // 'prod', 'dev', 'local'
  logLevel: 'warning',  // 'debug', 'info', 'warning', 'error'
  timeout: 30000,
  retries: 3
});

// Agent methods
await studio.createAgent(config);
await studio.getAgent(agentId);
await studio.listAgents();
await studio.updateAgent(agentId, config);
await studio.deleteAgent(agentId);

// Knowledge base methods
await studio.createKnowledgeBase(config);
await studio.getKnowledgeBase(kbId);
await studio.listKnowledgeBases();
await studio.deleteKnowledgeBase(kbId);

// Context methods
await studio.createContext(name, value);
await studio.getContext(contextId);
await studio.listContexts();
await studio.deleteContext(contextId);

// RAI methods
await studio.createRAIPolicy(config);
await studio.getRAIPolicy(policyId);
await studio.listRAIPolicies();
await studio.deleteRAIPolicy(policyId);

// Memory methods
await studio.createMemoryCredential(provider, name, credentials);
await studio.listMemoryProviders();
```

### Agent

```typescript
// Core
await agent.run('message', { sessionId: 'user_1', stream: false });
await agent.update({ temperature: 0.5 });
await agent.delete();
await agent.clone('New Name');

// Tools
await agent.addTool(myFunction);
await agent.removeTool('toolName');
agent.listTools();

// Memory
agent.addMemory(30);
agent.removeMemory();
agent.hasMemory();

// Context
await agent.addContext(context);
await agent.removeContext(contextId);
await agent.listContexts();

// RAI
agent.addRaiPolicy(policy);
agent.removeRaiPolicy();
agent.hasRaiPolicy();

// File & Image Output
agent.enableFileOutput();
agent.disableFileOutput();
agent.setImageModel(config);

// Features
agent.enableReflection();
agent.enableBiasCheck();
agent.enableLLMJudge();
agent.addGroundednessFacts(['fact1', 'fact2']);
```

### KnowledgeBase

```typescript
// Training
await kb.addPdf('path/to/file.pdf');
await kb.addDocx('path/to/file.docx');
await kb.addTxt('path/to/file.txt');
await kb.addWebsite(['https://docs.example.com']);
await kb.addText('text content', 'source');

// Query
const results = await kb.query('question', { topK: 5 });

// Management
await kb.listDocuments();
await kb.deleteDocuments(['doc_id']);
await kb.reset();
await kb.delete();
```

### Memory

```typescript
const memory = await studio.createMemoryCredential(
  'mem0',
  'My Memory',
  {
    mem0_api_key: 'key',
    // ... other provider-specific fields
  }
);

await memory.validate();
await memory.getStatus();
await memory.delete();
```

### Tools

```typescript
// Define a local tool (just a function!)
function calculateSum(a: number, b: number): number {
  return a + b;
}

// Register with agent
await agent.addTool(calculateSum);

// Or create a Tool explicitly
import { Tool } from '@lyzr/sdk';

const myTool = new Tool(
  calculateSum,
  'calculate_sum',
  'Calculate the sum of two numbers'
);
await agent.addTool(myTool);
```

## Structured Outputs with Zod

```typescript
import { z } from 'zod';

const AnalysisSchema = z.object({
  sentiment: z.enum(['positive', 'negative', 'neutral']),
  confidence: z.number().min(0).max(1),
  summary: z.string()
});

const agent = await studio.createAgent({
  name: 'Analyzer',
  provider: 'gpt-4o',
  role: 'Sentiment analyzer',
  goal: 'Analyze sentiment',
  instructions: 'Provide detailed analysis',
  responseModel: AnalysisSchema
});

const result = await agent.run('I love this product!');
// result is fully typed: { sentiment: 'positive', confidence: 0.95, summary: '...' }
console.log(result.sentiment);  // Full IDE autocomplete!
```

## Error Handling

```typescript
import {
  LyzrError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  APIError
} from '@lyzr/sdk';

try {
  const agent = await studio.createAgent(config);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid configuration:', error.message);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
  } else {
    throw error;
  }
}
```

## Examples

Check the `examples/` directory for comprehensive examples:

- `00-power-example.ts` - Complete real-world example
- `01-quickstart.ts` - Basic agent operations
- `02-structured-outputs.ts` - Zod schemas
- `03-knowledge-bases.ts` - RAG functionality
- `04-memory.ts` - Conversation context
- `05-local-tools.ts` - Function tools
- `06-complete-workflow.ts` - All features
- `07-contexts.ts` - Background information
- `08-file-output.ts` - File generation
- `09-rai-guardrails.ts` - Safety features
- `10-advanced-features.ts` - Advanced patterns
- `11-streaming.ts` - Streaming responses

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Lint
npm run lint

# Format
npm run format

# Type check
npm run typecheck
```

## Requirements

- Node.js 16+
- TypeScript 5.0+ (if using TypeScript)

## Best Practices

### Session Management

```typescript
import { v4 as uuidv4 } from 'uuid';

// Generate unique session ID per user
const sessionId = uuidv4();

// Maintain conversation context
const response1 = await agent.run('My name is Alice', { sessionId });
const response2 = await agent.run("What's my name?", { sessionId });
// Remembers "Alice"
```

### Streaming Responses

```typescript
// Stream responses for real-time output
for await (const chunk of await agent.run('Tell a story', { stream: true })) {
  process.stdout.write(chunk.content);
}
```

## Migration from Python

The TypeScript SDK maintains API compatibility with the Python SDK:

```python
# Python
agent = studio.create_agent(name='Bot', provider='gpt-4o', ...)
response = agent.run('message')
agent.add_tool(my_function)
```

```typescript
// TypeScript
const agent = await studio.createAgent({ name: 'Bot', provider: 'gpt-4o', ... });
const response = await agent.run('message');
await agent.addTool(myFunction);
```

Key differences:
- All methods are async in TypeScript
- Use camelCase for property names (vs snake_case in Python)
- Zod schemas instead of Pydantic models
- AsyncIterable for streaming vs Python generators

## Support

- **Documentation**: [docs.lyzr.ai](https://docs.lyzr.ai)
- **GitHub**: [github.com/lyzr-ai/sdk](https://github.com/lyzr-ai/sdk)
- **Discord**: [discord.gg/lyzr](https://discord.gg/lyzr)
- **Email**: support@lyzr.ai

## License

MIT License - see [LICENSE](../../LICENSE)