# Development Principles

Core development principles and philosophy for the Robota SDK v2.0.

## Project Overview

The Robota SDK v2.0 is a unified TypeScript library for building AI agents with:

- **Unified Architecture**: Everything consolidated in `@robota-sdk/agent-core`
- **Type-Safe Design**: `any` prohibited in production code, complete TypeScript safety
- **Multi-Provider Support**: OpenAI, Anthropic, Google AI with seamless switching
- **Plugin-Based Extensibility**: Modular plugin system for extending functionality
- **Performance-First**: Built-in analytics and monitoring

## Core Architecture Principles

### 1. Type Safety First

**Strict Type Safety Policy**: Complete elimination of `any` and unsafe `unknown` types

```typescript
// ✅ Good: Fully typed
interface AgentConfig {
  name: string;
  model: string;
  provider: string;
  aiProviders: IAIProvider[];
  systemMessage?: string;
  tools?: IToolInterface[];
  plugins?: AbstractPlugin[];
}

// ❌ Bad: Using any
interface BadConfig {
  providers: any; // Never use this
  options: any; // Always type explicitly
}
```

### 2. Unified Package Design

**Single Source of Truth**: `@robota-sdk/agent-core` contains all core functionality

- **AbstractAgent**: Foundation for all agent implementations
- **AbstractAIProvider**: Unified provider interface
- **AbstractTool**: Type-safe tool system
- **AbstractPlugin**: Extensible plugin architecture
- **AgentFactory**: Template-based agent creation

### 3. Provider Agnostic Architecture

**Seamless Provider Switching**: No vendor lock-in

```typescript
// Switch providers at runtime
agent.setModel({ provider: 'openai', model: 'gpt-4' });
agent.setModel({ provider: 'anthropic', model: 'claude-3-sonnet' });
agent.setModel({ provider: 'google', model: 'gemini-1.5-flash' });
```

### 4. Plugin-First Extensibility

**Modular Design**: Core functionality extended through plugins

```typescript
const agent = new Robota({
  plugins: [
    new ExecutionAnalyticsPlugin(),
    new ConversationHistoryPlugin(),
    new LoggingPlugin(),
    new ErrorHandlingPlugin(),
  ],
});
```

### 5. Performance and Monitoring

**Built-in Analytics**: Every agent includes performance monitoring

```typescript
// Get comprehensive stats
const stats = agent.getStats();
console.log(`Success rate: ${stats.successRate}`);
console.log(`Average duration: ${stats.averageDuration}ms`);
```

## Development Philosophy

### 1. Developer Experience First

**Intuitive APIs**: Make common tasks simple, complex tasks possible

```typescript
// Simple: Basic agent in 3 lines
const agent = new Robota({
  name: 'SimpleAgent',
  provider: 'openai',
  model: 'gpt-3.5-turbo',
});

// Complex: Full featured agent with all options
const advancedAgent = new Robota({
  name: 'AdvancedAgent',
  provider: 'openai',
  model: 'gpt-4',
  tools: [calculatorTool, weatherTool],
  plugins: [analyticsPlugin, loggingPlugin],
  systemMessage: 'Advanced system prompt',
});
```

### 2. Fail Fast and Safe

**Error Handling**: Catch errors at compile time when possible

```typescript
// TypeScript catches provider mismatches
const agent = new Robota({
  name: 'MyAgent',
  aiProviders: [openaiProvider],
  defaultModel: {
    provider: 'openai',
    model: 'gpt-4',
  },
  // TypeScript ensures provider exists in aiProviders array
});
```

### 3. Resource Management

**Automatic Cleanup**: Prevent memory leaks and resource exhaustion

```typescript
// Always clean up
try {
  const response = await agent.run(input);
  return response;
} finally {
  await agent.destroy(); // Clean up resources
}
```

## Code Quality Standards

### 1. Type Safety Requirements

- **No `any` types**: Use specific types or generic constraints
- **Strict TypeScript**: Enable all strict compiler options
- **Generic patterns**: Use type parameters for reusable components
- **Branded types**: Use for domain-specific values

### 2. Testing Standards

```typescript
// Test all public APIs
describe('Robota Agent', () => {
  it('should handle basic conversation', async () => {
    const agent = createTestAgent();
    const response = await agent.run('Hello');
    expect(response).toBeDefined();
    expect(typeof response).toBe('string');
  });

  it('should clean up resources', async () => {
    const agent = createTestAgent();
    await agent.destroy();
    // Verify cleanup
  });
});
```

### 3. Documentation Requirements

- **API Documentation**: Every public method documented
- **Examples**: Real-world usage examples for all features
- **Type Documentation**: Complex types explained
- **Migration Guides**: Clear upgrade paths

## Architecture Patterns

### 1. Facade Pattern

**Simplified Interfaces**: Hide complexity behind simple APIs

```typescript
// Complex internal implementation hidden behind simple facade
// (example updated: team APIs removed; use agent + assignTask tools instead)
```

### 2. Plugin Pattern

**Extensible Architecture**: Core functionality + optional plugins

```typescript
export abstract class AbstractPlugin<TStats = PluginStats> {
  abstract name: string;
  abstract onAgentStart?(): Promise<void>;
  abstract onAgentStop?(): Promise<void>;
  abstract getStats(): TStats;
}
```

### 3. Factory Pattern

**Template-Based Creation**: Standardized agent creation

```typescript
const factory = new AgentFactory({
  providers: { openai: openaiProvider },
  defaultProvider: 'openai',
});

const agent = await factory.createFromTemplate('helpful-assistant');
```

### 4. Provider Pattern

**Abstraction Layer**: Unified interface across different AI services

```typescript
export abstract class AbstractAIProvider {
  abstract generateResponse(messages: UniversalMessage[]): Promise<string>;
  abstract generateStream(messages: UniversalMessage[]): AsyncIterable<StreamChunk>;
  abstract getSupportedModels(): string[];
}
```

## Performance Principles

### 1. Monitoring First

**Built-in Analytics**: Every operation monitored by default

```typescript
// Automatic performance tracking
const plugin = new ExecutionAnalyticsPlugin({
  maxEntries: 10000,
  trackErrors: true,
  performanceThreshold: 5000,
});
```

### 2. Streaming Support

**Real-time Responses**: Support streaming across all providers

```typescript
const stream = await agent.stream(input);
for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}
```

### 3. Resource Efficiency

**Memory Management**: Prevent leaks and optimize usage

```typescript
// Plugin-specific cleanup
export class ConversationHistoryPlugin extends AbstractPlugin {
  async onAgentStop(): Promise<void> {
    // Clean up conversation history
    this.clearHistory();
  }
}
```

## Security Principles

### 1. Input Validation

**Type-Safe Inputs**: Validate at the type level

```typescript
// Tool parameters are validated by TypeScript
const weatherTool = createFunctionTool(
  'getWeather',
  'Get weather information',
  {
    type: 'object',
    properties: {
      location: { type: 'string' },
      units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
    },
    required: ['location'],
  },
  async (params) => {
    /* implementation */
  },
);
```

### 2. Error Boundaries

**Safe Error Handling**: Prevent error propagation

```typescript
// Plugin errors don't crash the agent
try {
  await plugin.onAgentStart();
} catch (error) {
  console.error(`Plugin ${plugin.name} failed to start:`, error);
  // Continue without this plugin
}
```

## Migration and Compatibility

### 1. Backward Compatibility

**Smooth Migrations**: Clear upgrade paths from v1.x

```typescript
// v1.x (deprecated)
const robota = new Robota({
  systemPrompt: 'You are helpful',
  aiProviders: { openai: provider },
  currentProvider: 'openai',
});

// v2.0 (current)
const robota = new Robota({
  name: 'MyAgent',
  aiProviders: [provider],
  defaultModel: {
    provider: 'openai',
    model: 'gpt-4',
    systemMessage: 'You are helpful',
  },
});
```

### 2. Feature Flags

**Safe Rollouts**: New features behind flags

```typescript
const agent = new Robota({
  features: {
    experimentalStreaming: true,
    betaAnalytics: false,
  },
});
```

## Development References

### Core Documentation

- [Getting Started](../getting-started/README.md) - Quick start guide
- [Core Concepts](../guide/core-concepts.md) - Architecture overview
- [Building Agents](../guide/building-agents.md) - Advanced patterns

### Development Guides

- [TypeScript Standards](./typescript-standards.md) - Type safety requirements
- [Testing Guidelines](./testing-guidelines.md) - Testing strategies
- [Error Handling](./error-handling-guidelines.md) - Error handling patterns
- [Performance Optimization](./performance-optimization.md) - Performance best practices

### Package Information

- [Package Publishing](./package-publishing.md) - Release process
- [Build and Deployment](./build-and-deployment.md) - Build configuration
- [Documentation Guidelines](./documentation-guidelines.md) - Documentation standards
