Package Exports

@bonginkan/maria
@bonginkan/maria/package.json
@bonginkan/maria/services/internal-mode
@bonginkan/maria/services/internal-mode-v2

Readme

🎯 MARIA v3.1.9

AI Orchestration Documentation & Reference - Enterprise AI platform with comprehensive orchestration specs, security guidelines, and multi-tenant architecture patterns. Features 3 core services plus advanced telemetry and complete production documentation.

🌐 Homepage: https://bonginkan.ai/

🎨 Beautiful CLI Experience

When you run maria, you'll see:

╔══════════════════════════════════════════════════════════╗
║  ███╗   ███╗ █████╗ ██████╗ ██╗ █████╗                  ║
║  ████╗ ████║██╔══██╗██╔══██╗██║██╔══██╗                 ║
║  ██╔████╔██║███████║██████╔╝██║███████║                 ║
║  ██║╚██╔╝██║██╔══██║██╔══██╗██║██╔══██║                 ║
║  ██║ ╚═╝ ██║██║  ██║██║  ██║██║██║  ██║                 ║
║  ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝                 ║
║        AI-Powered Development Platform                   ║
║         (c) 2025 Bonginkan Inc.                          ║
╚══════════════════════════════════════════════════════════╝

MARIA CODE v3.1.9 — Ready
/help for commands | Providers: 8/8 OK

Available AI Providers:
☁️  Cloud AI: OpenAI, Anthropic, Google, Groq, xAI
💻 Local AI: Ollama, LM Studio, vLLM

⚡ Installation

# Global installation (recommended)
npm install -g @bonginkan/maria

# Or with pnpm
pnpm add -g @bonginkan/maria

📊 Quick Start - Telemetry (v3.1.6+)

# Start monitoring stack (optional)
docker-compose -f docker-compose.monitoring.yml up -d

# Access dashboards
open http://localhost:3000  # Grafana (admin/admin)
open http://localhost:9091  # Prometheus

🎯 What is MARIA?

MARIA revolutionizes AI development with 3 powerful services, advanced telemetry, and beautiful CLI experience:

Core Services

🧠 IntelligentRouterService - Smart command routing and analysis
🧩 DualMemoryEngine - System 1 & System 2 cognitive memory
📁 FileSystemService - Safe, atomic file operations

🆕 Telemetry System (v3.1.6+)

📈 Prometheus/Grafana Integration - Real-time metrics & dashboards
🤖 ML Anomaly Detection - Isolation Forest, Autoencoder, LSTM models
📊 Predictive Analytics - ARIMA, Prophet, Transformer forecasting
🎯 Custom Metrics Framework - Flexible metric collection & alerts

📚 AI Orchestration Docs (v3.1.9+)

📖 Reference Specifications - Complete technical documentation
🔐 Security Guidelines - Authentication, authorization, multi-tenant
📊 Metrics Schema - Standardized telemetry format
🧪 Golden Test Standards - Production-ready test criteria
🗺️ Implementation Roadmap - Prioritized feature planning

💻 Programmatic API

Core Services Example

import { 
  IntelligentRouterService, 
  DualMemoryEngine, 
  FileSystemService 
} from '@bonginkan/maria';

// 🧠 Intelligent Routing
const router = new IntelligentRouterService({
  confidenceThreshold: 0.85,
  enableLearning: true,
  enableConfirmation: false
});

const result = await router.route('optimize my database queries');
console.log('Route:', result.command);
console.log('Confidence:', result.confidence);

// 🧩 Dual Memory System
const memory = new DualMemoryEngine({
  system1: { maxKnowledgeNodes: 1000, accessDecayRate: 0.01 },
  system2: { maxReasoningTraces: 100, qualityThreshold: 0.7 },
  coordinator: { 
    syncInterval: 1000, 
    conflictResolutionStrategy: 'balanced',
    learningRate: 0.1
  }
});

await memory.store('project_context', {
  language: 'typescript',
  framework: 'react',
  patterns: ['hooks', 'components']
});

const insights = await memory.query('best practices for React hooks');

// 📁 Safe File Operations
const fs = new FileSystemService({
  enableBackup: true,
  enableSafeMode: true
});

🆕 Telemetry Example (v3.1.6+)

import { startTelemetry } from '@bonginkan/maria';

// Initialize advanced telemetry
const telemetry = await startTelemetry({
  prometheusPort: 9090,
  enableAnomalyDetection: true,
  enablePredictiveAnalytics: true,
  enableCustomMetrics: true,
  alertWebhook: process.env.SLACK_WEBHOOK_URL
});

// Record telemetry
await telemetry.recordTelemetry({
  provider: 'openai',
  intent: 'CODE_REQUEST',
  latency: 342,
  satisfaction: 0.95,
  tokens: { input: 100, output: 200 }
});

// Get ML-powered insights
const insights = await telemetry.generateInsights();
console.log('Anomalies:', insights.anomalies);
console.log('Forecasts:', insights.forecasts);
console.log('Trends:', insights.trends);

await fs.writeFile('/path/to/file.ts', content);
await fs.copy('/src', '/backup');

🏗️ Architecture

Minimal API Philosophy

MARIA v3.0.0 follows Minimal API, Maximum Power:

┌─────────────────────────────────────────┐
│           MARIA v3.0.0                  │
├─────────────────────────────────────────┤
│ 🧠 IntelligentRouterService             │
│   ├── Smart command routing             │
│   ├── Context-aware analysis            │
│   └── Learning capabilities             │
├─────────────────────────────────────────┤
│ 🧩 DualMemoryEngine                     │
│   ├── System 1: Fast, intuitive        │
│   ├── System 2: Deliberate, analytical │
│   └── Cross-session learning            │
├─────────────────────────────────────────┤
│ 📁 FileSystemService                    │
│   ├── Atomic operations                 │
│   ├── Backup management                 │
│   └── Safety validation                 │
└─────────────────────────────────────────┘

Key Features

Feature	Description	Status
Beautiful CLI	Professional startup with AI provider selection	✅
Dynamic Version	Auto-sourced from package.json	✅
3 Core Services	Essential AI development capabilities	✅
Type Safety	100% TypeScript with strict mode	✅
Zero Config	Works out of the box	✅
8 AI Providers	OpenAI, Anthropic, Google, Groq, xAI, Ollama, LM Studio, vLLM	✅

🚀 Performance

Metrics

Startup Time: < 1000ms cold start
Memory Usage: < 256MB heap maximum
Bundle Size: 192KB (optimized)
API Response: < 100ms for core operations

Benchmarks

# Run performance benchmarks
pnpm perf:bench

🛠️ Development

Requirements

Node.js 20.10.0+
pnpm v10.10.0 (recommended)
TypeScript 5.0+

Build Commands

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

# Type checking
pnpm type-check

# Lint code
pnpm lint

Command Registry

MARIA v3.0.0 includes a revolutionary command registry with:

68+ Commands: Full enterprise command suite
Type Safety: Runtime validation with TypeScript support
Fuzzy Search: Smart typo tolerance (/hlp → /help)
Auto-Generation: Automated type generation
7 Categories: From core commands to AI coding agent

# Generate command types
pnpm gen:cmd-types

# Test registry integrity  
pnpm test:registry

📱 AI Provider Support

Cloud Providers

OpenAI - GPT models with vision and reasoning
Anthropic - Claude models with advanced reasoning
Google - Gemini models with multimodal capabilities
Groq - Ultra-fast inference
xAI - Grok models with real-time data

Local Providers

Ollama - Local LLM runner
LM Studio - Local model management
vLLM - High-performance inference server

🌍 Multi-Language Support

MARIA supports development in multiple languages:

🇺🇸 English - Primary language
🇯🇵 Japanese - 日本語サポート
🇨🇳 Chinese - 中文支持
🇰🇷 Korean - 한국어 지원
🇻🇳 Vietnamese - Hỗ trợ tiếng Việt

📚 Documentation

API Documentation

IntelligentRouterService: API Reference
DualMemoryEngine: API Reference
FileSystemService: API Reference

Guides

Quick Start: Getting Started Guide
CLI Usage: Command Line Interface
Configuration: Configuration Guide

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/bonginkan/maria.git
cd maria

# Install dependencies
pnpm install

# Run development build
pnpm dev

# Run tests
pnpm test

# Submit pull request

📄 License

Dual License Model:

Personal Use: MIT License - Free for individual developers
Enterprise Use: Commercial License - Contact for enterprise pricing

See LICENSE for full details.

🔗 Links

NPM Package: https://www.npmjs.com/package/@bonginkan/maria
GitHub Repository: https://github.com/bonginkan/maria
Documentation: https://docs.maria-ai.dev
Support: https://github.com/bonginkan/maria/issues

🎉 What's New in v3.1.9

📚 AI Orchestration Documentation

Reference Specification: 396-line comprehensive technical reference
Security Guidelines: Multi-tenant, authentication, authorization specs
Metrics Standard Schema: 7 required categories, extensible format
Golden Test Standards: Coverage requirements and performance criteria
Implementation Roadmap: P0-P4 prioritized features with estimates

🔐 Security & Multi-Tenant Architecture

API Key Management: Rotating keys with configurable expiry
JWT Authentication: RS256 signed tokens with refresh
Tenant Isolation: Per-tenant circuit breakers and quotas
Audit Logging: Complete request/response tracking
RBAC Support: Role-based access control patterns

📊 Production-Ready Specifications

Component Responsibility Matrix: Clear separation of concerns
Terminology Clarity: Decision Table vs Model Router explained
Performance Benchmarks: P95 < 2.5s, error rate < 2%
Test Coverage Requirements: Unit 90%+, Integration 80%+

📝 Previous Releases

v3.1.8 - Zero Hardcoding

Centralized Configuration: All defaults in config/defaults.ts
Dynamic Version Management: Auto-pulled from package.json
Simplified Environment: Just .env and .env.example

v3.1.6 - Advanced Telemetry

Prometheus/Grafana: Real-time metrics & dashboards
ML Anomaly Detection: Isolation Forest, Autoencoder, LSTM
Predictive Analytics: ARIMA, Prophet, Transformer models
Custom Metrics: Flexible collection framework

✨ Core Features

3 Core Services: Router, Memory, FileSystem
8 AI Providers: Cloud & Local support
Beautiful CLI: Professional experience

🚨 Breaking Changes from v2.x

API Simplification: Many internal services no longer exposed
New CLI Interface: Updated startup and provider selection flow
Configuration Changes: Streamlined config format

🔄 Migration Guide

# Update to v3.0.0
npm update @bonginkan/maria

# Update imports
// Before (v2.x)
import { ComplexService, InternalAPI } from '@bonginkan/maria';

// After (v3.0.0) 
import { IntelligentRouterService, DualMemoryEngine } from '@bonginkan/maria';

Experience the power of minimal design. Experience MARIA v3.0.0.