diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14458c274..8be1a261d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,3 +8,298 @@ Add Cell framework example using C++23 modules ``` Commit messages like "Applying previous commit" should be avoided. +# Contributing to Abi AI Framework + +Please write clear commit messages that briefly describe the changes. +For example: + +``` +Add Cell framework example using C++23 modules +``` + +## πŸ§ͺ **Testing Requirements** + +### **Test Coverage Requirements** + +- **New Features**: 100% test coverage required +- **Bug Fixes**: Include regression tests +- **Performance Changes**: Include benchmark tests +- **API Changes**: Include integration tests + +### **Test Structure** + +```zig +// Test file structure +const std = @import("std"); + +test "feature: basic functionality" { + const allocator = std.testing.allocator; + + // Test setup + var instance = try createInstance(allocator); + defer instance.deinit(); + + // Test execution + const result = try instance.performOperation("test"); + + // Assertions + try std.testing.expectEqualStrings("expected", result); +} + +test "feature: error handling" { + const allocator = std.testing.allocator; + + // Test error conditions + const result = createInstance(allocator); + try std.testing.expectError(error.InvalidInput, result); +} + +test "feature: memory safety" { + const allocator = std.testing.allocator; + + // Test memory management + var instance = try createInstance(allocator); + defer instance.deinit(); + + // Verify no memory leaks + const stats = allocator.getStats(); + try std.testing.expectEqual(@as(usize, 0), stats.active_allocations); +} +``` + +### **Performance Testing** + +```zig +test "performance: within baseline" { + const allocator = std.testing.allocator; + + // Measure performance + const start_time = std.time.nanoTimestamp(); + try performOperation(allocator); + const end_time = std.time.nanoTimestamp(); + + const duration = @as(u64, @intCast(end_time - start_time)); + + // Assert performance within acceptable range + try std.testing.expectLessThan(duration, MAX_ALLOWED_TIME); +} +``` + +## πŸ“š **Documentation** + +### **Documentation Requirements** + +- **Public APIs**: All public functions must be documented +- **Examples**: Include usage examples for complex APIs +- **README Updates**: Update README for significant features +- **API Reference**: Keep API documentation current + +### **Documentation Standards** + +```zig +/// # Neural Network Layer +/// +/// Represents a single layer in a neural network with configurable +/// activation functions and weight initialization. +/// +/// ## Features +/// - Configurable input/output dimensions +/// - Multiple activation functions (ReLU, Sigmoid, Tanh) +/// - Automatic weight initialization +/// - Memory-efficient operations +/// +/// ## Example +/// ```zig +/// var layer = try Layer.init(allocator, .{ +/// .input_size = 784, +/// .output_size = 128, +/// .activation = .ReLU, +/// }); +/// defer layer.deinit(); +/// +/// const output = try layer.forward(&input, allocator); +/// ``` +pub const Layer = struct { + // Implementation... +}; +``` + +### **README Updates** + +When adding significant features, update the README: + +- **Features section**: Add new capabilities +- **Examples section**: Include usage examples +- **Performance section**: Update benchmarks if applicable +- **Installation**: Update if new dependencies are added + +## πŸ”€ **Pull Request Process** + +### **PR Template** + +```markdown +## Description +Brief description of changes made + +## Type of Change +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update + +## Testing +- [ ] All tests pass +- [ ] New tests added for new functionality +- [ ] Performance tests included if applicable +- [ ] Memory safety verified + +## Checklist +- [ ] Code follows project style guidelines +- [ ] Self-review of code completed +- [ ] Code is commented, particularly in hard-to-understand areas +- [ ] Documentation updated +- [ ] No breaking changes (or breaking changes documented) + +## Related Issues +Closes #123 +``` + +### **Review Process** + +1. **Automated Checks**: CI must pass all tests +2. **Code Review**: At least one maintainer must approve +3. **Testing**: All tests must pass on all platforms +4. **Documentation**: Documentation must be updated +5. **Performance**: No performance regressions allowed + +### **Merging Criteria** + +- **Tests Pass**: All automated tests must pass +- **Code Review**: At least one approval from maintainers +- **Documentation**: Documentation must be complete +- **Performance**: Performance must be maintained or improved +- **Memory Safety**: No memory leaks or safety issues + +## 🎯 **Areas for Contribution** + +### **High Priority** + +#### **πŸš€ Performance Optimizations** +- **SIMD Operations**: Optimize vector operations for different architectures +- **Memory Management**: Improve allocation strategies and reduce fragmentation +- **Algorithm Optimization**: Optimize core algorithms for better performance +- **GPU Acceleration**: Enhance GPU backend implementations + +#### **🧠 AI/ML Features** +- **Neural Networks**: Add new layer types and activation functions +- **Training Algorithms**: Implement advanced training methods +- **Model Formats**: Add support for more model formats +- **Embedding Models**: Implement state-of-the-art embedding techniques + +#### **πŸ—„οΈ Database Enhancements** +- **Indexing**: Implement advanced indexing algorithms (HNSW, IVF) +- **Compression**: Add vector compression techniques +- **Distributed**: Add distributed database capabilities +- **Query Optimization**: Optimize search and query performance + +### **Medium Priority** + +#### **πŸ”Œ Plugin System** +- **Plugin Interfaces**: Enhance plugin system capabilities +- **Plugin Examples**: Create more example plugins +- **Plugin Testing**: Improve plugin testing infrastructure +- **Plugin Documentation**: Enhance plugin development guides + +#### **🌐 Network Infrastructure** +- **Protocol Support**: Add more network protocols +- **Load Balancing**: Implement load balancing capabilities +- **Security**: Add authentication and authorization +- **Monitoring**: Enhance network monitoring and metrics + +### **Good First Issues** + +- **Documentation**: Fix typos, improve examples, add missing docs +- **Tests**: Add missing tests, improve test coverage +- **Examples**: Create new examples, improve existing ones +- **CI/CD**: Improve build scripts, add new platforms +- **Benchmarks**: Add new benchmarks, improve existing ones + +## 🌍 **Community** + +### **Communication Channels** + +- **GitHub Issues**: Bug reports and feature requests +- **GitHub Discussions**: General questions and discussions +- **Discord Server**: Real-time chat and collaboration +- **Email**: support@abi-framework.org + +### **Community Guidelines** + +- **Be Helpful**: Help others learn and grow +- **Share Knowledge**: Share your expertise and experiences +- **Be Patient**: Everyone learns at their own pace +- **Celebrate Success**: Acknowledge and celebrate contributions + +### **Recognition** + +- **Contributors**: All contributors are listed in CONTRIBUTORS.md +- **Hall of Fame**: Special recognition for significant contributions +- **Badges**: Earn badges for different types of contributions +- **Mentorship**: Opportunity to mentor new contributors + +## πŸ†˜ **Support** + +### **Getting Help** + +- **Documentation**: Check the docs first +- **Issues**: Search existing issues for solutions +- **Discussions**: Ask questions in GitHub Discussions +- **Discord**: Get real-time help in our Discord server + +### **Reporting Issues** + +When reporting issues, please include: + +- **Environment**: OS, Zig version, hardware details +- **Steps to Reproduce**: Clear, step-by-step instructions +- **Expected vs Actual**: What you expected vs what happened +- **Logs**: Relevant error messages and logs +- **Minimal Example**: Minimal code to reproduce the issue + +### **Feature Requests** + +For feature requests: + +- **Use Case**: Describe the problem you're trying to solve +- **Proposed Solution**: Suggest how it could be implemented +- **Alternatives**: Consider if existing features could solve your need +- **Priority**: Indicate how important this is to you + +## πŸŽ‰ **Getting Started Checklist** + +- [ ] Fork and clone the repository +- [ ] Set up development environment +- [ ] Build and test the project +- [ ] Read the contributing guidelines +- [ ] Pick an issue to work on +- [ ] Create a feature branch +- [ ] Make your changes +- [ ] Write tests for your changes +- [ ] Update documentation +- [ ] Run all tests +- [ ] Commit your changes +- [ ] Create a pull request +- [ ] Participate in code review +- [ ] Celebrate your contribution! 🎊 + +--- + +**πŸš€ Ready to contribute? Pick an issue and start coding!** + +**🀝 Together, we're building the future of high-performance AI development.** + +**πŸ’‘ Questions? Join our Discord or open a GitHub Discussion.** + +--- + +**Thank you for contributing to Abi AI Framework!** diff --git a/README.md b/README.md index fbf5b071b..d701f0153 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,37 @@ -
- -# ABI Framework - -Zig 0.16 -Status -License - -
- -Build -Tests -Coverage - -

- -**A modern Zig 0.16 framework for AI services, vector search, and high-performance systems** - -[Quick Start](#-quick-start) Β· [Documentation](https://donaldfilimon.github.io/abi/) Β· [Examples](#-examples) Β· [Contributing](CONTRIBUTING.md) - -
- -``` - ╔═══════════════════════════════════════════════════════════════╗ - β•‘ LLM Inference Β· Vector Database Β· GPU Acceleration β•‘ - β•‘ Agent Runtime Β· Distributed Compute Β· Training Pipelinesβ•‘ - β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• -``` - -
- -## Why ABI? - - - - - - - -
- -### Lightning Fast -Built with Zig for zero-cost abstractions, comptime optimization, and bare-metal performance. SIMD-accelerated operations throughout. - - - -### Production Ready -Battle-tested with 1296 tests (1290 passing, 6 skip), comprehensive error handling, graceful degradation, and circuit breakers for resilience. - - - -### Fully Modular -Enable only what you need. Every feature is toggleable at compile-time with zero overhead for disabled modules. - -
+# πŸš€ Abi AI Framework ---- - -## Highlights - -| Feature | Description | Status | -|:--------|:------------|:------:| -| **AI Runtime** | LLM inference with Llama-CPP parity, agent runtime, training pipelines | ![Ready](https://img.shields.io/badge/-Ready-success) | -| **Vector Database** | WDBX with HNSW/IVF-PQ indexing, hybrid search, real-time analytics | ![Ready](https://img.shields.io/badge/-Ready-success) | -| **GPU Acceleration** | CUDA, Vulkan, Metal (Accelerate/AMX), WebGPU, FPGA with unified API | ![Ready](https://img.shields.io/badge/-Ready-success) | -| **Compute Engine** | Work-stealing scheduler, NUMA-aware, lock-free primitives | ![Ready](https://img.shields.io/badge/-Ready-success) | -| **Distributed Network** | Raft consensus, node discovery, load balancing | ![Ready](https://img.shields.io/badge/-Ready-success) | -| **Observability** | Metrics, tracing, profiling, circuit breakers | ![Ready](https://img.shields.io/badge/-Ready-success) | -| **Interactive CLI** | TUI launcher, GPU dashboard, training monitor | ![Ready](https://img.shields.io/badge/-Ready-success) | -| **Streaming API** | SSE/WebSocket inference, circuit breakers, session recovery | ![Ready](https://img.shields.io/badge/-Ready-success) | - ---- - -## Quick Start - -### Installation - -```bash -git clone https://github.com/donaldfilimon/abi.git -cd abi -zig build -zig build run -- --help -``` - -### Requirements - -| Dependency | Version | Required | -|:-----------|:--------|:--------:| -| Zig | 0.16.0-dev.2682+02142a54d | Yes | -| Git | Any | Yes | -| GPU Drivers | Latest | Optional | - -### Hello World - -```zig -const std = @import("std"); -const abi = @import("abi"); - -pub fn main() !void { - var gpa = std.heap.GeneralPurposeAllocator(.{}){}; - defer _ = gpa.deinit(); - const allocator = gpa.allocator(); +var agent = try abi.ai.agent.Agent.init(allocator, .{ + .name = "Assistant", + .max_retries = 3, +}); +defer agent.deinit(); - var app = try abi.App.initDefault(allocator); - defer app.deinit(); +[![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)]() - std.debug.print("ABI v{s} ready!\n", .{abi.version()}); -} -``` - ---- - -## API Migration (v2 Surface) - -ABI now exposes canonical v2 entrypoints only: - -- Use `abi.App` / `abi.AppBuilder` as the runtime types. -- Use `abi.features.` for feature modules and `abi.services.` for service modules. -- Use `abi.App.init(...)`, `abi.App.initDefault(...)`, and `abi.App.builder(...)` for app bootstrap. -- Legacy aliases (`abi.Framework`, `abi.init*`, top-level `abi.`) are removed. - ---- - -## Examples + -
-AI Agent Chat +
+Vector Database ```zig -const abi = @import("abi"); - -pub fn main() !void { - var gpa = std.heap.GeneralPurposeAllocator(.{}){}; - const allocator = gpa.allocator(); - defer _ = gpa.deinit(); - - var agent = try abi.features.ai.Agent.init(allocator, .{ - .name = "assistant", - .temperature = 0.7, - .enable_history = true, - }); - defer agent.deinit(); +const gpu = abi.gpu; - const response = try agent.chat("Explain Zig's comptime in one sentence.", allocator); - defer allocator.free(response); +var backend = try gpu.selectBackend(allocator); +defer backend.deinit(); - std.debug.print("Agent: {s}\n", .{response}); -} -``` +### **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) -
+## 🀝 Contributing -
-Vector Database - -```zig -const abi = @import("abi"); +We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. pub fn main() !void { var gpa = std.heap.GeneralPurposeAllocator(.{}){}; @@ -204,8 +81,9 @@ pub fn main() !void { const result = try gpu.createBuffer(4 * @sizeOf(f32), .{}); defer { gpu.destroyBuffer(a); gpu.destroyBuffer(b); gpu.destroyBuffer(result); } - // Executes on GPU with automatic SIMD/scalar fallback - _ = try gpu.vectorAdd(a, b, result); +// Add embeddings +const embedding = [_]f32{0.1, 0.2, 0.3, /* ... */}; +const row_id = try db.addEmbedding(&embedding); var output: [4]f32 = undefined; try result.read(f32, &output); @@ -484,6 +362,44 @@ zig build benchmarks zig build lint ``` +### **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](CONTRIBUTING.md) 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** + +This project is licensed under the MIT License - see the [LICENSE](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](https://github.com/donaldfilimon/abi/issues) +- **Discussions**: [GitHub Discussions](https://github.com/donaldfilimon/abi/discussions) +- **Documentation**: [docs/](docs/) + +--- + +**Built with ❀️ using Zig 0.16** + ### Cell Framework Example This repository now includes a demonstration of the Cell framework using modern C++23 modules. See `cell_framework/README.md` for build instructions. +**πŸš€ Ready to build the future of AI with Zig? Get started with Abi AI Framework today!**