npm package: @ggakila/ionix-framework
Description: TypeScript-based AI agent framework with native LLM integration, workflows, and 15+ built-in integrations (Development Preview)
Author: Gisore Haggai
Latest version: 0.2.0-beta.3

# Ionix Framework

[![npm version](https://badge.fury.io/js/%40ggakila%2Fionix-framework.svg)](https://badge.fury.io/js/%40ggakila%2Fionix-framework)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

---

## ⚠️ Development Status Disclaimer

**This framework is currently under active development and should be considered a beta/preview release.**

- Features may change without notice
- APIs are not yet stable and may have breaking changes
- Some functionality may be incomplete or contain bugs
- Not recommended for production use without thorough testing
- Documentation coming soon. 

We appreciate your patience and feedback as we work toward a stable 1.0 release!

---

TypeScript-based AI agent framework with native LLM integration and workflow automation.

Ionix is a comprehensive framework for building AI-powered automation workflows and autonomous agents. It provides a code-first approach with native LLM integration, 15+ built-in integrations, and enterprise-grade security features.

## ✅ Production Status

**Ionix Framework is production-ready for AI agent development (v0.2.0-beta.2)!**

### Ready for Production
- ✅ CLI tools (`create-ionix`, `ionix add`) work like create-next-app
- ✅ One-liner agent creation with minimal configuration
- ✅ Build system and npm package distribution
- ✅ Core LLM integrations (OpenAI, Anthropic, Google, Ollama)
- ✅ Error handling and security features
- ✅ TypeScript support and comprehensive typing

### Current Limitations
- ⚠️ Storage adapters (Redis, PostgreSQL, MongoDB) are not implemented
- ⚠️ Database tool requires manual driver installation (pg, mysql2, better-sqlite3)
- ⚠️ Email IMAP functionality is not implemented
- ⚠️ Some enterprise features need additional configuration

**These limitations don't affect core AI agent functionality.**

Perfect for building AI agents with just API keys and minimal configuration. Get started in minutes!

## Features

- **Production-Ready LLM Clients** - OpenAI, Anthropic, Google Gemini, Ollama (local models)
- **Atomic Architecture** - Structured Input -> Processing -> Output patterns
- **One-Liner Agents** - Create working agents with a single function call
- **Workflow Engine** - DAG-based workflow execution with parallel processing
- **15+ Integrations** - HTTP, Webhooks, Slack, WhatsApp, Telegram, Google Workspace, Databases, AWS S3
- **Payment Processing** - Stripe, PayPal, and M-Pesa integration
- **Enterprise Security** - RBAC, rate limiting, audit logging, input validation
- **Platform Adapters** - WhatsApp, Telegram, Slack message handling
- **Web Tools** - Search, fetch, and scrape capabilities
- **TypeScript First** - Full type safety and IntelliSense support

## Installation

```bash
npm install @ggakila/ionix-framework
```

## Quick Start

### One-Liner Agents

```typescript
import { 
  createOpenAIAgent, 
  createAnthropicAgent, 
  createOllamaAgent,
  createGeminiAgent,
  BasicChatInputSchema 
} from '@ggakila/ionix-framework/atomic';

// OpenAI Agent
const gptAgent = createOpenAIAgent(process.env.OPENAI_API_KEY!, {
  model: 'gpt-4',
  systemPrompt: 'You are a helpful coding assistant.',
});

// Anthropic Agent
const claudeAgent = createAnthropicAgent(process.env.ANTHROPIC_API_KEY!, {
  model: 'claude-3-5-sonnet-20241022',
  systemPrompt: 'You are a creative writing assistant.',
});

// Local Ollama Agent (no API key needed)
const localAgent = createOllamaAgent({
  model: 'llama3.2',
  systemPrompt: 'You are a privacy-focused assistant.',
});

// Gemini Agent
const geminiAgent = createGeminiAgent(process.env.GOOGLE_API_KEY!, {
  model: 'gemini-pro',
  systemPrompt: 'You are a knowledgeable assistant.',
});

// Use any agent
const input = BasicChatInputSchema.parse({ chat_message: 'Hello!' });
const response = await gptAgent.runAsync(input);
console.log(response.chat_message);
```

### Full Control with AtomicAgent

```typescript
import { 
  AtomicAgent, 
  createOpenAIClient,
  BasicChatInputSchema, 
  BasicChatOutputSchema,
  SystemPromptGenerator,
  ChatHistory 
} from '@ggakila/ionix-framework/atomic';

// Create LLM client
const client = createOpenAIClient({ 
  apiKey: process.env.OPENAI_API_KEY!,
  timeout: 30000,
  maxRetries: 3,
});

// Create agent with full configuration
const agent = new AtomicAgent({
  client,
  model: 'gpt-4',
  inputSchema: BasicChatInputSchema,
  outputSchema: BasicChatOutputSchema,
  systemPromptGenerator: new SystemPromptGenerator({
    background: ['You are an expert TypeScript developer.'],
    steps: ['Think step by step.', 'Provide working code examples.'],
    outputInstructions: ['Format code with proper indentation.'],
  }),
  history: new ChatHistory({ maxMessages: 20 }),
  modelApiParameters: {
    temperature: 0.7,
    maxTokens: 2000,
  },
});

// Run with streaming
const input = BasicChatInputSchema.parse({ chat_message: 'Write a React hook' });
for await (const chunk of agent.runAsyncStream(input)) {
  process.stdout.write(chunk.chat_message || '');
}
```

## Supported LLM Providers

| Provider | Client | Factory Function | API Key Required |
|----------|--------|------------------|------------------|
| OpenAI | `createOpenAIClient()` | `createOpenAIAgent()` | Yes |
| Anthropic | `createAnthropicClient()` | `createAnthropicAgent()` | Yes |
| Google Gemini | `createGeminiClient()` | `createGeminiAgent()` | Yes |
| Ollama (Local) | `createOllamaClient()` | `createOllamaAgent()` | No |

## Architecture

Ionix follows an atomic, developer-centric architecture:

```
Input Schema -> Agent/Tool -> Output Schema
```

### Core Components

- **Schemas** - Zod-validated input/output types with JSON Schema generation
- **Agents** - LLM-powered processors with history and context management
- **Tools** - MCP-compatible function wrappers
- **Pipelines** - Schema-compatible step chaining
- **Gateway** - REST/WebSocket API with authentication
- **Adapters** - Platform-specific message conversion

### Schema System

```typescript
import { BaseIOSchema, Schema } from '@ggakila/ionix-framework/atomic';
import { z } from 'zod';

// Define custom schemas
const MyInputSchemaZ = z.object({
  query: z.string(),
  limit: z.number().optional(),
});

@Schema(MyInputSchemaZ)
class MyInputSchema extends BaseIOSchema {
  readonly query!: string;
  readonly limit?: number;
}

// Use with agent
const agent = new AtomicAgent({
  client,
  model: 'gpt-4',
  inputSchema: MyInputSchema,
  outputSchema: BasicChatOutputSchema,
});
```

### Tool System

```typescript
import { AtomicTool, createTool } from '@ggakila/ionix-framework/atomic';

// Simple function tool
const calculator = createTool({
  name: 'calculator',
  description: 'Performs basic math operations',
  inputSchema: CalculatorInputSchema,
  outputSchema: CalculatorOutputSchema,
  execute: async (input) => {
    const result = eval(input.expression);
    return new CalculatorOutputSchema({ result });
  },
});

// Get MCP-compatible description
const description = calculator.describe();
```

### Pipeline Orchestration

```typescript
import { Pipeline, createPipeline } from '@ggakila/ionix-framework/atomic';

const pipeline = createPipeline()
  .addStep({ name: 'search', processor: searchTool })
  .addStep({ name: 'summarize', processor: summaryAgent })
  .addStep({ name: 'format', processor: formatTool });

const result = await pipeline.execute(input);
```

### API Gateway

```typescript
import { AgentRouter, createRouter } from '@ggakila/ionix-framework/atomic';

const router = createRouter({
  auth: {
    type: 'api_key',
    apiKeys: ['your-api-key'],
  },
  rateLimit: {
    windowMs: 60000,
    maxRequests: 100,
  },
});

router.registerAgent('chat', chatAgent);
router.registerAgent('code', codeAgent);

// Handle requests
const response = await router.handleRequest({
  agentId: 'chat',
  input: { chat_message: 'Hello' },
  headers: { 'x-api-key': 'your-api-key' },
});
```

### Platform Adapters

```typescript
import { 
  WhatsAppAdapter, 
  TelegramAdapter, 
  SlackAdapter 
} from '@ggakila/ionix-framework/atomic';

// WhatsApp
const whatsapp = new WhatsAppAdapter({
  verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
});

// Convert incoming message to agent input
const agentInput = whatsapp.toAgentInput(incomingMessage);
const agentOutput = await agent.runAsync(agentInput);
const reply = whatsapp.fromAgentOutput(agentOutput, sessionId);
```

## Web Tools

```typescript
import { 
  WebSearchTool, 
  WebFetchTool, 
  WebScrapeTool,
  createWebSearchTool,
  createWebFetchTool,
} from '@ggakila/ionix-framework/atomic';

// Search the web
const searchTool = createWebSearchTool({
  provider: 'duckduckgo', // or 'google', 'bing', 'searxng'
});

// Fetch URL content
const fetchTool = createWebFetchTool({
  timeout: 10000,
  maxContentLength: 1000000,
});
```

## Workflow Engine

```typescript
import { WorkflowExecutor } from '@ggakila/ionix-framework';

const workflow = {
  id: 'user-onboarding',
  steps: [
    {
      id: 'fetch-user',
      type: 'tool',
      tool: 'http',
      config: { method: 'GET', url: 'https://api.example.com/users/{{userId}}' }
    },
    {
      id: 'send-welcome',
      type: 'tool', 
      tool: 'email',
      config: { 
        to: '{{user.email}}',
        subject: 'Welcome!',
        body: 'Welcome {{user.name}}!'
      }
    }
  ]
};

const executor = new WorkflowExecutor(toolRegistry);
await executor.execute(workflow, { userId: '123' });
```

## Available Integrations

### Communication ✅
- HTTP/REST - API calls and responses
- Webhooks - Send and receive webhooks
- Slack - Complete Slack API integration
- WhatsApp - WhatsApp Business API
- Telegram - Telegram Bot API
- Email - SMTP email sending

### Data & Storage ⚠️
- SQL Databases - PostgreSQL, MySQL, SQLite *(requires manual driver setup)*
- MongoDB - NoSQL database integration *(adapter not implemented)*
- Redis - Caching and session storage *(adapter not implemented)*
- Amazon S3 - File storage and retrieval
- File System - Local file operations

**Note:** Storage adapters are placeholder implementations. For production use with databases, implement the adapters or use the in-memory/file-system options.

### Productivity ✅
- Google Docs - Document creation and editing
- Google Sheets - Spreadsheet operations
- Google Drive - File management

### Payments ✅
- Stripe - Global card payments and subscriptions
- PayPal - Digital wallet and card processing
- M-Pesa - Kenya mobile money (Safaricom)

### Tool Installation via CLI ✅
```bash
# Add tools like shadcn
ionix add http          # HTTP requests
ionix add slack         # Slack integration  
ionix add email         # SMTP email
ionix add file-system   # File operations
ionix add web-scraper   # Web scraping
ionix add database      # Database queries (requires driver)
```

## Configuration

### Environment Variables

```bash
# LLM Providers
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GOOGLE_API_KEY=your-google-key

# Integrations
SLACK_BOT_TOKEN=xoxb-your-token
DATABASE_URL=postgresql://user:pass@localhost:5432/db
REDIS_URL=redis://localhost:6379
```

## Security

Ionix includes enterprise-grade security features:

- JWT Authentication - Token-based authentication
- API Key Authentication - Secure API access
- RBAC - Role-based access control
- Rate Limiting - Prevent API abuse
- Input Validation - Schema-based validation
- Audit Logging - Security event tracking

## Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage
```

Comprehensive test suite with property-based testing using fast-check.

## CLI Tools

### Create New Project (like create-next-app)

```bash
# Interactive setup
npx @ggakila/ionix-framework create my-agent-app

# Skip prompts with defaults
npx @ggakila/ionix-framework create my-agent-app -y

# Or use the shorter command
npx create-ionix my-agent-app
```

### Add Tools to Existing Project (like shadcn)

```bash
# List available tools
ionix add --list

# Install tools
ionix add http
ionix add slack
ionix add email
ionix add file-system
ionix add web-scraper

# Generate boilerplate code
ionix generate tool my-tool
ionix generate workflow my-workflow
ionix generate agent my-agent
```

### Generated Project Structure

```
my-agent-app/
├── src/
│   ├── tools/      # Custom tools
│   ├── workflows/   # Workflow definitions
│   ├── agents/      # Agent configurations
│   ├── config.ts    # Framework configuration
│   └── index.ts    # Entry point
├── package.json
├── tsconfig.json
├── .env.example    # Environment variables template
└── Dockerfile      # Deployment ready
```

## Deployment

Supports Docker, Kubernetes, AWS Lambda, Vercel, Railway, and systemd.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- X: @gisore_akila
- Instagram: @gisore.io