<<<<<<< HEAD

🚀 Abi AI Framework

=======

Abi Framework

Modern, modular Zig framework for AI/ML experiments and production workloads

🎯 What is Abi?

Abi is an experimental framework that provides a curated set of feature modules for building high-performance AI/ML applications in Zig. It emphasizes:

• 🚀 Performance: Zero-cost abstractions, SIMD optimizations, and minimal overhead
• 🔧 Modularity: Composable features with compile-time selection
• 🛡️ Type Safety: Leveraging Zig's compile-time guarantees
• 🧪 Testability: Built with testing in mind from the ground up
• 📊 Observability: Comprehensive monitoring and diagnostics

✨ Features

Core Capabilities

Feature	Description	Status
AI/ML	Agent system, neural networks, transformers, RL	✅ Production
Vector Database	High-performance vector storage and retrieval	✅ Production
GPU Acceleration	Multi-backend GPU compute (CUDA, Vulkan, Metal)	🔄 In Progress
Web Server	HTTP server and client	✅ Production
Monitoring	Metrics, logging, and distributed tracing	✅ Production
Plugin System	Dynamic plugin loading and management	🔄 In Progress

New in 0.2.0

• ✅ Modular Build System - Feature flags for conditional compilation
• ✅ I/O Abstraction Layer - Testable, composable I/O operations
• ✅ Comprehensive Error Handling - Rich error context and diagnostics
• ✅ Improved Testing - Separate unit and integration test suites
• ✅ Better Documentation - Architecture guides and API references
• ✅ Mega Refactor Complete - Clean architecture with zero duplication
• ✅ Modern Patterns - Zig 0.16 best practices throughout

🏗️ New Architecture (v0.2.0)

The ABI Framework has been completely refactored with a clean, modern architecture:

abi/
├── lib/                    # Primary library source
│   ├── core/              # Core utilities (I/O, diagnostics, collections)
│   ├── features/          # Feature modules (AI, GPU, Database, Web)
│   ├── framework/         # Framework infrastructure
│   └── shared/            # Shared utilities
├── tools/                 # Development tools and CLI
├── examples/             # Standalone examples
├── tests/                # Comprehensive test suite
└── benchmarks/           # Performance tests

Key Improvements

• Zero Duplication: Single source of truth in lib/ directory
• Modern I/O: Injectable writer pattern for better testing
• Rich Diagnostics: Comprehensive error reporting with context
• Clean Exports: Explicit module exports (no usingnamespace)
• Modular Build: Feature flags for conditional compilation

🚀 Quick Start

Prerequisites

• Zig 0.16.0-dev.254+6dd0270a1 or later
• A C++ compiler (for some dependencies)

Installation

git clone https://github.com/donaldfilimon/abi.git
cd abi
zig build

Basic Usage

const std = @import("std");
const abi = @import("abi");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Initialize the framework
    var framework = try abi.init(allocator, .{});
    defer abi.shutdown(&framework);

    // Create an AI agent
    const Agent = abi.ai.agent.Agent;
    var agent = try Agent.init(allocator, .{ .name = "Assistant" });
    defer agent.deinit();

    // Process a query
    const response = try agent.process("Hello, world!", allocator);
    defer allocator.free(@constCast(response));

    std.debug.print("Agent response: {s}\n", .{response});
}

Building with Feature Flags

# Build with specific features
zig build -Denable-ai=true -Denable-gpu=true -Dgpu-cuda=true

# Build and run tests
zig build test              # Unit tests
zig build test-integration  # Integration tests
zig build test-all          # All tests

# Build examples
zig build examples          # All examples
zig build run-ai_demo       # Run specific example

# Build benchmarks
zig build bench
zig build run-bench

# Generate documentation
zig build docs
zig build docs-auto

📖 Documentation

User Guides

• Getting Started - Your first Abi application
• Architecture - System design and principles
• API Reference - Complete API documentation
• Examples - Practical code examples

Development

• Contributing - How to contribute
• Redesign Plan - Framework redesign details
• Redesign Summary - What's new in 0.2.0

🏗️ Architecture

High-Level Overview

┌─────────────────────────────────────────────┐
│          Application Layer                   │
│        (CLI, User Code, Tools)              │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│          Framework Layer                     │
│    Runtime · Features · Plugins             │
└───────────────────┬─────────────────────────┘
                    │
┌───────────────────▼─────────────────────────┐
│          Core Infrastructure                 │
│    I/O · Errors · Diagnostics · Types       │
└─────────────────────────────────────────────┘

Module Organization

lib/
├── core/              # Core infrastructure
│   ├── io.zig         # I/O abstractions
│   ├── errors.zig     # Error definitions
│   ├── diagnostics.zig # Diagnostics system
│   └── ...
├── features/          # Feature modules
│   ├── ai/            # AI/ML capabilities
│   ├── database/      # Vector database
│   ├── gpu/           # GPU acceleration
│   └── ...
└── framework/         # Framework runtime
    ├── runtime.zig    # Lifecycle management
    └── ...

🔧 CLI Usage

The Abi CLI provides comprehensive access to all framework features:

# Show help
./zig-out/bin/abi --help

# Feature management
./zig-out/bin/abi features list
./zig-out/bin/abi features status

# AI operations
./zig-out/bin/abi agent run --name "MyAgent"
./zig-out/bin/abi agent list

# Database operations
./zig-out/bin/abi db create --name vectors
./zig-out/bin/abi db query --vector "..."

# GPU benchmarks
./zig-out/bin/abi gpu bench
./zig-out/bin/abi gpu info

# Version information
./zig-out/bin/abi version

🧪 Testing

Running Tests

# Unit tests
zig build test

# Integration tests
zig build test-integration

# All tests
zig build test-all

# With coverage
zig build test -- --coverage

Test Organization

tests/
├── unit/              # Unit tests (mirrors lib/)
├── integration/       # Integration tests
│   ├── ai_pipeline_test.zig
│   ├── database_ops_test.zig
│   └── framework_lifecycle_test.zig
└── fixtures/          # Test utilities

Writing Tests

const std = @import("std");
const abi = @import("abi");
const testing = std.testing;

test "AI agent processes input correctly" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();
    
    var framework = try abi.init(allocator, .{});
    defer abi.shutdown(&framework);
    
    const Agent = abi.ai.agent.Agent;
    var agent = try Agent.init(allocator, .{ .name = "Test" });
    defer agent.deinit();
    
    const response = try agent.process("test", allocator);
    defer allocator.free(@constCast(response));
    
    try testing.expect(response.len > 0);
}

📊 Examples

AI Agent

const abi = @import("abi");
>>>>>>> 08cbda559b270a4426611f5b6c970439485a216a

var agent = try abi.ai.agent.Agent.init(allocator, .{
    .name = "Assistant",
    .max_retries = 3,
});
defer agent.deinit();

<<<<<<< HEAD
[![Zig Version](https://img.shields.io/badge/Zig-0.16.0--dev.1225%2Bbf9082518-orange.svg)](https://ziglang.org/) • [Docs](https://donaldfilimon.github.io/abi/) • [CI: Pages](.github/workflows/deploy_docs.yml)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Cross--platform-green.svg)](https://github.com/yourusername/abi)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)]()
[![Tests](https://img.shields.io/badge/Tests-Passing-brightgreen.svg)]()
[![Performance](https://img.shields.io/badge/Performance-2,777+%20ops%2Fsec-brightgreen.svg)]()
=======
const response = try agent.process("Explain quantum computing", allocator);
defer allocator.free(@constCast(response));

08cbda559b270a4426611f5b6c970439485a216a

Vector Database

const db = abi.database;

var vector_db = try db.VectorDB.init(allocator, .{
    .dimension = 128,
    .metric = .cosine,
});
defer vector_db.deinit();

try vector_db.insert("doc1", embedding);
const results = try vector_db.search(query, 10);

GPU Compute

const gpu = abi.gpu;

var backend = try gpu.selectBackend(allocator);
defer backend.deinit();

<<<<<<< HEAD
### **Prerequisites**
- **Zig 0.16.0-dev.1225+bf9082518** (GitHub Actions uses `mlugg/setup-zig@v2` pinned to this version)
- GPU drivers (optional, for acceleration)
- OpenAI API key (for AI agent features)
=======
const kernel = try gpu.loadKernel("matrix_mul");
try backend.execute(kernel, .{ .a = a, .b = b, .result = result });

08cbda559b270a4426611f5b6c970439485a216a

🤝 Contributing

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

Development Setup

# Clone the repository
git clone https://github.com/donaldfilimon/abi.git
cd abi

# Run tests
zig build test-all

# Format code
zig fmt .

# Build all examples
zig build examples

Code Guidelines

• Follow Zig 0.16 best practices
• Add tests for new features
• Update documentation
• Use the provided error handling infrastructure
• Inject dependencies (especially I/O)

🗺️ Roadmap

Current (v0.2.0)

Modular build system
I/O abstraction layer
Comprehensive error handling
Improved testing infrastructure

Next (v0.3.0)

Complete GPU backend implementations
Advanced monitoring and tracing
Plugin system v2
Performance optimizations

Future

Distributed computing support
Advanced ML model formats
Production deployment guides
Cloud provider integrations

<<<<<<< HEAD // Add embeddings const embedding = [_]f32{0.1, 0.2, 0.3, /* ... */}; const row_id = try db.addEmbedding(&embedding);

// Search for similar vectors const query = [_]f32{0.15, 0.25, 0.35, /* ... */}; const matches = try db.search(&query, 10, allocator); defer abi.features.database.database.Db.freeResults(matches, allocator);

> **Note:** Always release search metadata with `Db.freeResults` when you're done to reclaim allocator-backed resources.

### **WDBX Vector Database Features**

The ABI vector database provides enterprise-grade performance with:

- **High Performance**: SIMD-optimized vector operations and efficient file I/O
- **Vector Operations**: Add, query, and k-nearest neighbor search
- **Multiple APIs**: Command-line interface, HTTP REST API, TCP binary protocol, WebSocket
- **Security**: JWT authentication and rate limiting
- **Monitoring**: Comprehensive statistics and performance metrics
- **Production Ready**: Error handling, graceful degradation, and comprehensive testing

#### **Command Line Usage**

```bash
# Query k-nearest neighbors
./zig-out/bin/abi wdbx knn "1.1,2.1,3.1,4.1,5.1,6.1,7.1,8.1" 5

# Query nearest neighbor
./zig-out/bin/abi wdbx query "1.1,2.1,3.1,4.1,5.1,6.1,7.1,8.1"

# Add vector to database
./zig-out/bin/abi wdbx add "1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0"

# Start HTTP REST API server
./zig-out/bin/abi wdbx http 8080

HTTP REST API

Start the server and access endpoints:

./zig-out/bin/abi wdbx http 8080

API Endpoints:

• GET /health - Health check
• GET /stats - Database statistics
• POST /add - Add vector (requires admin token)
• GET /query?vec=1.0,2.0,3.0 - Query nearest neighbor
• GET /knn?vec=1.0,2.0,3.0&k=5 - Query k-nearest neighbors

📊 Performance Benchmarks

Component	Performance	Hardware
Text Processing	3.2 GB/s	SIMD-accelerated with alignment safety
Vector Operations	15 GFLOPS	SIMD dot product with memory tracking
Neural Networks	<1ms inference	32x32 network with memory safety
LSP Completions	<10ms response	Sub-10ms completion responses
GPU Rendering	500+ FPS	Terminal UI with GPU acceleration
Lock-free Queue	10M ops/sec	Single producer, minimal contention
WDBX Database	2,777+ ops/sec	Production-validated performance

🛠️ Command Line Interface

# AI Chat (Interactive)
abi chat --persona creative --backend openai --interactive

# AI Chat (Single Message)
abi chat "Hello, how can you help me?" --persona analytical

# Model Training
abi llm train --data training_data.csv --output model.bin --epochs 100 --lr 0.001

# Model Training with GPU
abi llm train --data data.csv --gpu --threads 8 --batch-size 64

# Vector Database Operations
abi llm embed --db vectors.wdbx --text "Sample text for embedding"
abi llm query --db vectors.wdbx --text "Query text" --k 5

# Web Server
abi web --port 8080

# Performance Benchmarking
abi benchmark --iterations 1000 --memory-track

# Memory Profiling
abi --memory-profile benchmark

⚙️ Build Options

Configure features and targets via command-line flags:

GPU & Acceleration

• -Denable_cuda=true|false (default: true) - Enable NVIDIA CUDA support
• -Denable_spirv=true|false (default: true) - Enable Vulkan/SPIRV compilation
• -Denable_wasm=true|false (default: true) - Enable WebAssembly compilation

Optimization & Targets

• -Dtarget=<triple> - Cross-compilation target (e.g., x86_64-linux-gnu, aarch64-macos)
• -Doptimize=Debug|ReleaseSafe|ReleaseFast|ReleaseSmall (default: Debug)

Development Features

• -Denable_cross_compilation=true|false (default: true) - Enable cross-compilation support
• -Denable_heavy_tests=true|false (default: false) - Run heavy database/HNSW tests

Examples

# Production build with CUDA acceleration
zig build -Dtarget=x86_64-linux-gnu -Doptimize=ReleaseFast -Denable_cuda=true

# Cross-compile for ARM64 macOS
zig build -Dtarget=aarch64-macos -Doptimize=ReleaseSmall

# Run with all tests including heavy ones
zig build test-all -Denable_heavy_tests=true

# Minimal build without GPU support
zig build -Denable_cuda=false -Denable_spirv=false

Runtime Configuration

Build options are available at compile-time via the options module:

const options = @import("options");

pub fn main() void {
    std.log.info("CUDA: {}, SPIRV: {}", .{ options.enable_cuda, options.enable_spirv });
    std.log.info("Target: {}", .{ options.target });
}

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                    Abi AI Framework                               │
├─────────────────────────────────────────────────────────────────────┤
│  🤖 AI Agents    🧠 Neural Nets    🗄️ Vector Database               │
├─────────────────────────────────────────────────────────────────────┤
│  🚀 SIMD Ops     🔒 Lock-free      🌐 Network Servers              │
├─────────────────────────────────────────────────────────────────────┤
│  📊 Monitoring   🔍 Profiling      🧪 Testing Suite                 │
├─────────────────────────────────────────────────────────────────────┤
│  🔌 Plugin Sys   📱 CLI Interface  🌍 Platform Ops                 │
└─────────────────────────────────────────────────────────────────────┘

📚 Further Reading

• Documentation Portal - Landing page that links to generated and manual guides
• Module Organization - Current source tree and dependency overview
• GPU Acceleration Guide - Feature deep dive for GPU-backed workloads
• Testing Strategy - Quality gates, coverage expectations, and tooling
• Production Deployment - Deployment runbooks and environment guidance
• API Reference - Hand-authored API summary with links to generated docs
• Generated Documentation - Auto-generated API, module, and example references

🧪 Testing & Quality

Quick commands

• Build: zig build
• Test: zig build test
• Bench: zig build bench-all
• Docs: zig build docs
• Static analysis: zig build analyze
• Cross-platform: zig build cross-platform

Comprehensive Test Suite

# Run all tests
zig build test

# Memory management tests
zig test tests/test_memory_management.zig

# Performance regression tests
zig test tests/test_performance_regression.zig

# CLI integration tests
zig test tests/test_cli_integration.zig

Quality Metrics

• Memory Safety: Zero memory leaks with comprehensive tracking
• Performance Stability: <5% performance regression tolerance
• Test Coverage: 95%+ code coverage with memory and performance tests
• Build Success Rate: 99%+ successful builds across all platforms

Test Categories

• Memory Management: Memory safety and leak detection (100% coverage)
• Performance Regression: Performance stability monitoring (95% coverage)
• CLI Integration: Command-line interface validation (90% coverage)
• Database Operations: Vector database functionality (95% coverage)
• SIMD Operations: SIMD acceleration validation (90% coverage)
• Network Infrastructure: Server stability and error handling (95% coverage)

🌐 Web API

Start the web server and access REST endpoints:

abi web --port 8080

Available Endpoints:

• GET /health - Health check
• GET /api/status - System status
• POST /api/agent/query - Query AI agent (JSON: {"message": "your question"})
• POST /api/database/search - Search vectors
• GET /api/database/info - Database information
• WebSocket /ws - Real-time chat with AI agent

🔌 Plugin Development

Create custom plugins for the framework:

// Example plugin
pub const ExamplePlugin = struct {
    pub const name = "example_plugin";
    pub const version = "1.0.0";

    pub fn init(allocator: std.mem.Allocator) !*@This() {
        // Plugin initialization
    }

    pub fn deinit(self: *@This()) void {
        // Plugin cleanup
    }
};

See the Module Organization guide and generated module reference for plugin entry points.

🚀 Production Deployment

The framework includes production-ready deployment configurations:

• Kubernetes Manifests: Complete staging and production deployments
• Monitoring Stack: Prometheus + Grafana with validated thresholds
• Performance Validation: 2,777+ ops/sec with 99.98% uptime
• Automated Scripts: Windows (PowerShell) and Linux deployment scripts

See Production Deployment Guide for complete deployment instructions.

🌍 Cross-Platform Guide (Zig 0.16.0-dev.1225+bf9082518)

Targets

# Examples
zig build -Dtarget=x86_64-linux-gnu
zig build -Dtarget=aarch64-linux-gnu
zig build -Dtarget=x86_64-macos
zig build -Dtarget=aarch64-macos
zig build -Dtarget=wasm32-wasi

Conditional Compilation

const builtin = @import("builtin");

pub fn main() void {
    if (comptime builtin.os.tag == .windows) {
        // Windows-specific code
    } else if (comptime builtin.os.tag == .linux) {
        // Linux-specific code
    } else if (comptime builtin.os.tag == .macos) {
        // macOS-specific code
    }
}

Cross-Platform Build Step

zig build cross-platform   # builds CLI for multiple targets into zig-out/cross/

Windows Networking Notes

• Windows networking paths use Winsock on Windows to avoid ReadFile edge cases
• Diagnostic tool: zig build test-network (Windows only)
• PowerShell fixes: fix_windows_networking.ps1

🤝 Contributing

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

Development Workflow

1. Fork and Clone: Create a feature branch
2. Run Tests: Ensure all tests pass with monitoring
3. Memory Safety: Verify no leaks in your changes
4. Performance: Run performance tests to ensure no regressions
5. Documentation: Update docs for new features
6. Submit PR: Create pull request with comprehensive coverage

📄 License

=======

📝 License

08cbda559b270a4426611f5b6c970439485a216a

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

🙏 Acknowledgments

• The Zig team for creating an amazing language
• All contributors to this project
• The AI/ML and systems programming communities

📞 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

---

Built with ❤️ using Zig 0.16

<<<<<<< HEAD 🚀 Ready to build the future of AI with Zig? Get started with Abi AI Framework today!

Last Updated: October 8, 2025

08cbda559b270a4426611f5b6c970439485a216a