Synthra

Production-ready conversational AI agent framework with advanced context management and enterprise-grade reliability

Website • Documentation • Twitter • GitHub

---

📋 Table of Contents

• Features
• Installation
• Quick Start
• Architecture
• Core Capabilities
• Configuration
• Performance
• Documentation
• Examples
• Development
• Technology Stack
• Security
• Contributing
• Roadmap
• License
• Support

---

✨ Features

• Session Management - Isolated conversation contexts with automatic lifecycle management
• Context Compression - Token-aware compression with multiple retention strategies (FIFO, priority, semantic)
• Rate Limiting - Token bucket and sliding window algorithms with per-key tracking
• Error Handling - Comprehensive error hierarchy with detailed context and retry logic
• Type Safety - Full TypeScript support with strict typing and exported interfaces
• Performance Monitoring - Built-in metrics collection and performance optimization utilities
• Structured Logging - Configurable logging with JSON and text formats
• HTTP Client - Axios-based client with automatic retry and exponential backoff
• Input Validation - Comprehensive validation and sanitization for all inputs
• Extensible Architecture - Modular design supporting custom implementations

---

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0 or yarn >= 1.22.0

Install via npm

npm install @synthra/core

Install via yarn

yarn add @synthra/core

---

🚀 Quick Start

import { SynthraAgent } from '@synthra/core';

// Initialize agent
const agent = new SynthraAgent({
  apiKey: process.env.SYNTHRA_API_KEY,
  endpoint: 'https://api.synthra.ai',
  timeout: 10000
});

// Create session
const session = agent.createSession('user_123');

// Send message
const response = await agent.sendMessage(
  session.id,
  'Hello, Synthra!'
);

console.log(response.message.content);
console.log(`Tokens: ${response.usage.totalTokens}`);
console.log(`Latency: ${response.latency}ms`);

---

🏗️ Architecture

Synthra is built on a modular architecture with four primary layers:

┌─────────────────────────────────────────┐
│        Application Layer                │
│  SynthraAgent | Sessions | Context      │
├─────────────────────────────────────────┤
│         Core Services                   │
│  HTTP Client | Rate Limiter | Logger    │
├─────────────────────────────────────────┤
│         Utility Layer                   │
│  Validation | Helpers | Errors          │
├─────────────────────────────────────────┤
│        Infrastructure                   │
│  Network | Memory | Storage             │
└─────────────────────────────────────────┘

---

💡 Core Capabilities

Session Management

// Create isolated conversation context
const session = agent.createSession('user_123');

// Send multiple messages
await agent.sendMessage(session.id, 'First message');
await agent.sendMessage(session.id, 'Second message');

// Check session state
const updatedSession = agent.getSession(session.id);
console.log(`Messages: ${updatedSession?.messageCount}`);

// Clear or delete session
agent.clearSession(session.id);
agent.deleteSession(session.id);

Context Management

// Configure context window
agent.setContextConfig({
  maxTokens: 8192,
  windowSize: 20,
  compressionEnabled: true,
  retentionPolicy: 'semantic'
});

// Automatic compression when approaching limits
const response = await agent.sendMessage(sessionId, longMessage);

Rate Limiting

import { RateLimiter } from '@synthra/core';

const limiter = new RateLimiter({
  maxRequests: 100,
  windowMs: 60000 // 100 requests per minute
});

await limiter.checkLimit(userId);

Error Handling

import { 
  RateLimitError,
  ContextOverflowError,
  NetworkError
} from '@synthra/core';

try {
  await agent.sendMessage(sessionId, content);
} catch (error) {
  if (error instanceof RateLimitError) {
    await delay(error.retryAfter * 1000);
    // Retry
  } else if (error instanceof ContextOverflowError) {
    agent.clearSession(sessionId);
  } else if (error instanceof NetworkError) {
    // Handle network error
  }
}

---

⚙️ Configuration

Basic Configuration

const agent = new SynthraAgent({
  apiKey: 'your_api_key',
  endpoint: 'https://api.synthra.ai',
  timeout: 10000
});

Advanced Configuration

const agent = new SynthraAgent({
  apiKey: process.env.SYNTHRA_API_KEY,
  endpoint: 'https://api.synthra.ai',
  timeout: 15000,
  retries: 5,
  retryDelay: 2000,
  debug: true
});

agent.setContextConfig({
  maxTokens: 8192,
  windowSize: 50,
  compressionEnabled: true,
  retentionPolicy: 'semantic'
});

---

⚡ Performance

Benchmarks

Operation	Average Latency	Throughput
Message Processing	<100ms	10,000 msg/s
Context Compression	<50ms	1,000 contexts/s
Rate Limit Check	<1ms	100,000 checks/s
Session Creation	<5ms	20,000 sessions/s

Optimization Features

• Token-aware context compression
• Lazy resource loading
• Memory-efficient circular buffers
• Memoization for expensive operations
• Batch processing capabilities

Development

Setup

git clone https://github.com/synthra/synthra.git
cd synthra
npm install

Running Tests

npm test                    # Run all tests
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests
npm run test:coverage      # With coverage report

Building

npm run build              # Production build
npm run build:watch        # Watch mode
npm run type-check         # TypeScript validation

Code Quality

npm run lint               # Run linter
npm run lint:fix           # Fix linting issues
npm run format             # Format code

---

📚 Documentation

• Quickstart Guide - Get started in 5 minutes
• API Reference - Complete API documentation
• Architecture - System design and patterns
• Examples - Working code examples
• Contributing - Contribution guidelines
• Security - Security policy

---

📖 Examples

Basic Usage

import { SynthraAgent } from '@synthra/core';

const agent = new SynthraAgent({
  apiKey: process.env.SYNTHRA_API_KEY
});

const session = agent.createSession('user_001');

const response = await agent.sendMessage(
  session.id,
  'What can you help me with?'
);

console.log(response.message.content);

Advanced Patterns

import { 
  SynthraAgent,
  RateLimiter,
  ContextManager
} from '@synthra/core';

const agent = new SynthraAgent({
  apiKey: process.env.SYNTHRA_API_KEY,
  timeout: 15000,
  retries: 5,
  debug: true
});

const rateLimiter = new RateLimiter({
  maxRequests: 10,
  windowMs: 60000
});

const contextManager = new ContextManager({
  maxTokens: 8192,
  windowSize: 50,
  compressionEnabled: true,
  retentionPolicy: 'semantic'
});

// Use with rate limiting
await rateLimiter.checkLimit(userId);
const response = await agent.sendMessage(sessionId, content);

See examples/ for complete working examples.

Technology Stack

Component	Technology
Runtime	Node.js 18+
Language	TypeScript 5.3+
HTTP Client	Axios
Validation	Zod
Testing	Vitest
Build	tsup
Linting	ESLint + Prettier
CI/CD	GitHub Actions

Security

• Input validation and sanitization
• API key authentication
• Rate limiting to prevent abuse
• No sensitive data in logs
• Secure session management
• Regular dependency audits

See SECURITY.md for security policy and vulnerability reporting.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Commit your changes (git commit -m 'feat: add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Roadmap

• Core agent implementation
• Session management
• Context compression
• Rate limiting
• Comprehensive error handling
• Performance monitoring
• WebSocket streaming support
• Multi-model support (GPT-4, Claude, LLaMA)
• Plugin system
• Distributed session storage
• GraphQL API layer

Changelog

See CHANGELOG.md for version history and release notes.

License

This project is licensed under the MIT License - see LICENSE file for details.

Acknowledgments

• Built with Axios for HTTP requests
• Testing with Vitest
• Type validation with Zod

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@synthra.ai

Citation

If you use Synthra in your research or production application, please cite:

@software{synthra,
  author = {Synthra Team},
  title = {Synthra: Production-ready Conversational AI Agent Framework},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/synthra/synthra}
}

---

Built with precision for developers who demand reliability.

---

📁 Project Structure

synthra/
├── .github/
│   ├── workflows/
│   │   └── ci.yml                    # CI/CD pipeline
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── FUNDING.yml
│   └── dependabot.yml
├── .vscode/
│   ├── settings.json                 # VS Code settings
│   └── extensions.json               # Recommended extensions
├── docs/
│   ├── architecture.md               # System architecture
│   ├── api-reference.md              # Complete API docs
│   ├── quickstart.md                 # Getting started guide
│   ├── deployment.md                 # Deployment guide
│   └── faq.md                        # FAQ
├── examples/
│   ├── basic-usage.ts                # Basic examples
│   ├── advanced-patterns.ts          # Advanced examples
│   └── README.md
├── src/
│   ├── core/
│   │   ├── agent.ts                  # Main agent class
│   │   ├── context-manager.ts        # Context management
│   │   ├── rate-limiter.ts           # Rate limiting
│   │   ├── http-client.ts            # HTTP client
│   │   └── logger.ts                 # Structured logging
│   ├── errors/
│   │   └── index.ts                  # Error hierarchy
│   ├── types/
│   │   └── index.ts                  # TypeScript types
│   ├── utils/
│   │   ├── validation.ts             # Input validation
│   │   ├── helpers.ts                # Helper functions
│   │   └── performance.ts            # Performance utilities
│   ├── constants.ts                  # Global constants
│   └── index.ts                      # Main exports
├── tests/
│   ├── unit/
│   │   ├── agent.test.ts
│   │   ├── validation.test.ts
│   │   └── helpers.test.ts
│   └── integration/
│       └── agent-flow.test.ts
├── public/
│   └── Frame 18.png                  # Banner image
├── .editorconfig                     # Editor configuration
├── .eslintrc.json                    # ESLint rules
├── .gitignore                        # Git ignore rules
├── .node-version                     # Node version
├── .npmignore                        # NPM ignore rules
├── .nvmrc                            # NVM configuration
├── .prettierrc                       # Prettier configuration
├── CHANGELOG.md                      # Version history
├── CONTRIBUTING.md                   # Contribution guidelines
├── LICENSE                           # MIT License
├── package.json                      # Package configuration
├── README.md                         # This file
├── SECURITY.md                       # Security policy
├── tsconfig.json                     # TypeScript configuration
└── vitest.config.ts                  # Test configuration

---

Built with ❤️ by the Synthra Team

Website • Docs • Twitter • GitHub

_{Empowering developers to build intelligent conversational experiences}