npm package: @orchestree/conductor
Description: Conductor module — AI agent routing, workflow orchestration, memory systems, fleet management
Author: Orchestree
Latest version: 1.4.0

# @orchestree/conductor

Workflow orchestration and agent management for Orchestree. Create, execute, and monitor complex workflows with intelligent agent routing and distributed execution.

## Installation

```bash
npm install @orchestree/conductor
```

## Quick Start

```javascript
const { WorkflowClient } = require('@orchestree/conductor');

const client = new WorkflowClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.orchestree.io',
});

// Create a workflow
const workflow = await client.createWorkflow({
  name: 'DataProcessingPipeline',
  steps: [
    {
      id: 'step1',
      name: 'Validate Data',
      type: 'validation',
      config: { schema: 'data-schema-v1' },
    },
    {
      id: 'step2',
      name: 'Process Data',
      type: 'processing',
      config: { processor: 'standard' },
    },
  ],
  metadata: { version: '1.0' },
});

// Execute the workflow
const execution = await client.runWorkflow(workflow.id, {
  data: { /* input data */ },
});

// Monitor execution
const logs = await client.getExecutionLogs(execution.executionId);
console.log(logs);
```

## Core Concepts

### Workflows
Workflows are sequences of steps that define complex processes. Each workflow can be versioned, monitored, and triggered by various events.

### Agents
Agents are distributed executors that handle task execution. Register agents to expand the conductor's capabilities.

### Memory Store
A distributed key-value store for sharing state across workflow executions.

### Fleet Management
Monitor and manage multiple agents as a unified fleet with health checks and load balancing.

## API Reference

### WorkflowClient

#### Constructor

```javascript
new WorkflowClient(config)
```

**Config Options:**
- `apiKey` (string, required): Your Orchestree API key
- `baseURL` (string, optional): API base URL (default: `https://api.orchestree.io`)

#### Methods

##### createWorkflow(workflowDef)

Create a new workflow.

```javascript
const workflow = await client.createWorkflow({
  name: 'MyWorkflow',
  steps: [/* steps */],
  metadata: { /* optional */ },
});
```

**Parameters:**
- `workflowDef.name` (string): Workflow name
- `workflowDef.steps` (array): Array of workflow steps
- `workflowDef.metadata` (object, optional): Additional metadata

**Returns:** Promise<Workflow>

---

##### runWorkflow(workflowId, input, options)

Execute a workflow.

```javascript
const execution = await client.runWorkflow('workflow-123', {
  userId: 'user-456',
  action: 'process',
});
```

**Parameters:**
- `workflowId` (string): ID of workflow to execute
- `input` (object, optional): Input parameters
- `options` (object, optional): Execution options

**Returns:** Promise<ExecutionContext>

---

##### listWorkflows(filters)

List all workflows.

```javascript
const workflows = await client.listWorkflows({
  status: 'active',
  limit: 20,
  offset: 0,
});
```

**Parameters:**
- `filters.status` (string): Filter by status
- `filters.limit` (number): Maximum results
- `filters.offset` (number): Pagination offset
- `filters.tags` (array): Filter by tags

**Returns:** Promise<Workflow[]>

---

##### getExecutionLogs(executionId, options)

Retrieve execution logs.

```javascript
const logs = await client.getExecutionLogs('exec-123', {
  limit: 100,
});
```

**Parameters:**
- `executionId` (string): Execution ID
- `options` (object, optional): Log retrieval options

**Returns:** Promise<ExecutionLog[]>

---

##### registerAgent(agentDef)

Register a new agent.

```javascript
const agent = await client.registerAgent({
  name: 'DataProcessor',
  endpoint: 'https://agent.example.com',
  capabilities: ['process', 'validate'],
  timeout: 30000,
});
```

**Parameters:**
- `agentDef.name` (string): Agent name
- `agentDef.endpoint` (string): Agent endpoint URL
- `agentDef.capabilities` (array): List of capabilities
- `agentDef.metadata` (object, optional): Additional metadata
- `agentDef.timeout` (number, optional): Request timeout

**Returns:** Promise<Agent>

---

##### routeTask(task, options)

Route a task to an appropriate agent.

```javascript
const result = await client.routeTask({
  type: 'data-process',
  payload: { data: [1, 2, 3] },
}, {
  priority: 'high',
  timeout: 60000,
});
```

**Parameters:**
- `task.type` (string): Task type
- `task.payload` (object): Task payload
- `options.timeout` (number, optional): Timeout in milliseconds
- `options.retryCount` (number, optional): Number of retries
- `options.priority` (string, optional): Task priority

**Returns:** Promise<any>

---

##### getMemory(key, scope)

Get value from memory store.

```javascript
const value = await client.getMemory('session-123', 'global');
```

**Parameters:**
- `key` (string): Memory key
- `scope` (string, optional): Memory scope (default: 'global')

**Returns:** Promise<any>

---

##### setMemory(key, value, scope, options)

Set value in memory store.

```javascript
await client.setMemory('session-123', { user: 'john' }, 'global', {
  ttl: 3600,
  encrypted: true,
});
```

**Parameters:**
- `key` (string): Memory key
- `value` (any): Value to store
- `scope` (string, optional): Memory scope (default: 'global')
- `options.ttl` (number, optional): Time to live in seconds
- `options.encrypted` (boolean, optional): Enable encryption

**Returns:** Promise<any>

---

##### getFleetStatus(fleetId)

Get fleet status.

```javascript
const status = await client.getFleetStatus('fleet-123');
```

**Parameters:**
- `fleetId` (string, optional): Fleet ID

**Returns:** Promise<FleetStatus>

---

##### listAgents(filters)

List all registered agents.

```javascript
const agents = await client.listAgents({
  status: 'active',
});
```

**Parameters:**
- `filters` (object, optional): Filter options

**Returns:** Promise<Agent[]>

---

##### getExecutionStatus(executionId)

Get execution status.

```javascript
const status = await client.getExecutionStatus('exec-123');
```

**Parameters:**
- `executionId` (string): Execution ID

**Returns:** Promise<ExecutionContext>

---

##### cancelExecution(executionId)

Cancel a running execution.

```javascript
await client.cancelExecution('exec-123');
```

**Parameters:**
- `executionId` (string): Execution ID

**Returns:** Promise<any>

---

## Error Handling

```javascript
try {
  const result = await client.runWorkflow('workflow-123', {});
} catch (error) {
  console.error('Execution failed:', error.message);
}
```

## License

MIT