Ionix Framework

⚠️ 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

npm install @ggakila/ionix-framework

Quick Start

One-Liner Agents

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

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

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

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

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

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

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

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

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 ✅

# 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

# 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

# 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)

# 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)

# 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 file for details.

Support

• X: @gisore_akila
• Instagram: @gisore.io