npm package: @suada/sdk
Description: Official Node.js SDK for Suada AI
Author: Suada AI
Latest version: 1.0.0-rc.28

# Suada Node.js SDK

The official Node.js SDK for Suada's Business Analyst API. This SDK allows you to easily integrate Suada's powerful business analysis capabilities into your applications and LangChain agents.

## Installation

```bash
npm install @suada/node
```

## Usage

### Basic Usage

```typescript
import { Suada } from '@suada/node';

const suada = new Suada({
    apiKey: 'your-api-key'
});

// Send a chat message
const response = await suada.chat({
    message: "What's our revenue trend?",
    externalUserIdentifier: 'user-123'
});

console.log(response);
```

### Integration with LangChain

```typescript
import { Suada } from '@suada/node';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatOpenAI } from 'langchain/chat_models/openai';
import { PromptTemplate } from 'langchain/prompts';

// Initialize Suada
const suada = new Suada({
    apiKey: 'your-api-key'
});

// Create Suada tool
const suadaTool = suada.createTool({
    name: 'business_analyst',
    description: 'Use this tool to get business insights and analysis',
    externalUserIdentifier: 'user-123',
    passthroughMode: true // Optional, defaults to false
});

// Create OpenAI agent with Suada tool
const model = new ChatOpenAI({ temperature: 0 });
const tools = [suadaTool];

const agent = await createOpenAIFunctionsAgent({
    llm: model,
    tools,
    prompt: PromptTemplate.fromTemplate(
        `You are a helpful assistant that uses Suada's business analyst capabilities.
         
         Current conversation:
         {chat_history}
         
         Human: {input}
         Assistant: Let me help you with that.`
    )
});

const executor = AgentExecutor.fromAgentAndTools({
    agent,
    tools,
    verbose: true
});

// Use the agent
const result = await executor.invoke({
    input: "What's our revenue trend for the last quarter?",
    chat_history: []
});

console.log(result.output);
```

### Passthrough Mode and User Identification

The SDK supports two modes of operation:

1. **Standard Mode** (`passthroughMode: false`, default): In this mode, Suada's AI analyzes the query and provides structured business insights. The `externalUserIdentifier` is optional.

2. **Passthrough Mode** (`passthroughMode: true`): In this mode, messages are passed directly to the LLM. When using passthrough mode, `externalUserIdentifier` is required for proper user tracking.

```typescript
// Standard mode - externalUserIdentifier is optional
const responseStandard = await suada.chat({
    message: "What's our revenue trend?",
    passthroughMode: false // This is the default
});

// Passthrough mode - externalUserIdentifier is required
const responsePassthrough = await suada.chat({
    message: "What's our revenue trend?",
    externalUserIdentifier: 'user-123',
    passthroughMode: true
});
```

## Response Format

The SDK formats responses from Suada's API into a structured string format that can be easily parsed by LangChain agents. The response includes the following sections:

- \`<metrics>\`: Key performance metrics
- \`<insights>\`: Business insights
- \`<recommendations>\`: Action recommendations
- \`<risks>\`: Potential risks
- \`<reasoning>\`: Analysis reasoning
- \`<response>\`: Main response text

Example response:
```
<metrics>
revenue: $1.2M
growth_rate: 15%
</metrics>

<insights>
Strong growth in enterprise segment
New product adoption exceeding expectations
</insights>

<recommendations>
Increase focus on enterprise sales
Expand product feature set
</recommendations>

<risks>
Market competition intensifying
Supply chain constraints
</risks>

<reasoning>
Analysis shows positive growth trajectory with some areas requiring attention
</reasoning>

<response>
Your revenue has shown strong growth, particularly in the enterprise segment...
</response>
```

## Configuration

The SDK accepts the following configuration options:

```typescript
interface SuadaConfig {
    apiKey: string;
    baseUrl?: string; // Defaults to https://suada.ai/api/public/
}
```

## Error Handling

The SDK throws errors with descriptive messages when API calls fail:

```typescript
try {
    const response = await suada.chat({
        message: "What's our revenue?",
        externalUserIdentifier: 'user-123'
    });
} catch (error) {
    console.error('Error:', error.message);
}
```

## License

MIT