@gftdcojp/actor-sdk/README.md

Comprehensive TypeScript SDK for GFTD Actor Platform with Well-becoming Agent as default - Supporting mental wellness and personal growth through AI

# Actor SDK

A comprehensive TypeScript/JavaScript SDK for building AI-powered applications with the GFTD Actor Platform.

## 🌟 Default Actor: Well-becoming Agent

The Actor SDK comes pre-configured with the **Well-becoming Agent** as the default actor. This compassionate AI companion is dedicated to supporting mental wellness and personal growth.

### Well-becoming Agent Features

- **Emotional Support**: Provides empathetic, non-judgmental listening and guidance
- **Mindfulness Guidance**: Offers evidence-based mindfulness and meditation techniques
- **Goal Setting**: Helps users create and achieve meaningful personal goals
- **Habit Formation**: Supports the development of sustainable wellness habits
- **Stress Management**: Provides strategies for managing stress and anxiety
- **Life Balance**: Guides users in finding balance between productivity and rest
- **Positive Psychology**: Incorporates research-backed approaches to wellbeing

### Default Configuration

```typescript
// Default actor configuration
{
  id: 'default',
  organizationId: 'anon',
  repositoryUrl: 'https://gitlab-gftd-ai.fly.dev/actors/anon/default',
  name: 'Well-being Agent',
  type: 'wellbeing',
  capabilities: [
    'wellbeing-coaching',
    'mindfulness-guidance', 
    'emotional-support',
    'goal-setting',
    'habit-formation',
    'stress-management',
    'positive-psychology',
    'life-balance'
  ]
}
```

## Quick Start

```typescript
import { createActorSDK } from '@gftd/actor-sdk'

// Initialize with default Well-being Agent
const sdk = createActorSDK()
await sdk.initialize()

// Start a wellness conversation
const response = await sdk.chat("I'm feeling stressed about work lately")
console.log(response.content) // Compassionate, helpful response
```

## Installation

```bash
npm install @gftd/actor-sdk
# or
yarn add @gftd/actor-sdk
# or
pnpm add @gftd/actor-sdk
```

## Core Features

- **🎭 Actor Management**: Create, configure, and manage AI actors
- **💬 Session Management**: Handle conversation sessions and context
- **🌊 Streaming Support**: Real-time streaming responses
- **🔗 Git Integration**: Version control for actor configurations
- **📊 Embedding & Vector Search**: Semantic search capabilities
- **📈 Monitoring**: Performance tracking and analytics
- **🎨 UI Components**: Pre-built React components

## Configuration

### Custom Actor Templates

While the Well-being Agent is the default, you can create custom actors:

```typescript
import { SDKConfigManager } from '@gftd/actor-sdk'

// Create a custom actor
await SDKConfigManager.createDefaultActor('code-generator')

// Or create from scratch
const customConfig = {
  name: 'Custom Assistant',
  type: 'custom',
  description: 'Your custom AI assistant'
}
```

### Environment Configuration

```typescript
// Use different actor configurations
const sdk = createActorSDK({
  defaultActor: {
    id: 'my-custom-actor',
    organizationId: 'my-org',
    repositoryUrl: 'https://gitlab.example.com/my-org/my-actor'
  }
})
```

## Advanced Usage

### Using GFTD Chat Hook

```typescript
import { useGFTDChat } from '@gftd/actor-sdk'

function WellnessChat() {
  const { messages, sendMessage, isLoading } = useGFTDChat({
    systemPrompt: "Focus on stress management techniques"
  })

  return (
    <div>
      {messages.map(msg => <div key={msg.id}>{msg.content}</div>)}
      <button onClick={() => sendMessage("Help me relax")}>
        Get Relaxation Tips
      </button>
    </div>
  )
}
```

### Session Management

```typescript
// Create a wellbeing session
const session = await sdk.createSession({
  actorId: 'default',
  message: {
    role: 'user',
    content: 'I want to improve my work-life balance'
  }
})

// Continue the conversation
const response = await sdk.continueSession({
  sessionId: session.session.id,
  message: {
    role: 'user',
    content: 'What specific steps can I take?'
  }
})
```

## Repository Structure

The Well-being Agent repository (`/actors/anon/default`) contains:

- **Actor Configuration**: Core behavior and capabilities
- **System Prompts**: Wellness-focused conversation templates
- **Session Templates**: Pre-configured conversation flows
- **Documentation**: Usage guidelines and best practices

## Development

```bash
# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build the SDK
pnpm build

# Run tests
pnpm test
```

## Contributing

We welcome contributions to improve the Well-being Agent and the Actor SDK. Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

**🌱 Empowering wellness through AI** - The Actor SDK with Well-being Agent is designed to support human flourishing and mental wellness in our digital age.