<div align="center">
<img src="assets/onyx-octopus-avatar.png" alt="Graphite Gator" width="300">
# Eventuali (Onyx Octopus): High-performance event sourcing library for Python, powered by Rust.
</div>
## Why Eventuali?
**Problem**: Pure Python event sourcing hits performance walls at scale. Complex financial calculations, high-throughput IoT streams, and real-time analytics demand more than Python alone can deliver.
**Solution**: Eventuali delivers **Rust-level performance with Python-level simplicity** - the only event sourcing library giving you 10-60x speed improvements without sacrificing developer experience.
```python
# Same familiar Python code...
user.apply(UserRegistered(name="John", email="john@example.com"))
await store.save(user)
# ...but with 79,000+ events/second throughput
# 18.3x faster snapshot reconstruction
# 186,000+ RBAC operations/second
```
## Who Needs This?
### 🏦 **Fintech & Banking**
- **Regulatory compliance** requiring immutable audit trails (SOX, PCI DSS)
- **High-frequency trading** with microsecond-sensitive operations
- **Real-time fraud detection** processing millions of transactions
- **Financial reporting** with historical state reconstruction
### 🏢 **Enterprise SaaS**
- **Multi-tenant systems** requiring strict data isolation
- **Real-time analytics dashboards** with streaming updates
- **CQRS at scale** with complex read model projections
- **Audit trails** for compliance and security monitoring
### 📡 **IoT & Analytics**
- **High-volume event ingestion** from thousands of devices
- **Time-series analysis** with historical event replay
- **Real-time monitoring** of industrial systems
- **Edge computing** with performance-critical processing
### 🔄 **Microservices**
- **Event-driven architecture** requiring reliable event ordering
- **Distributed transactions** with saga pattern coordination
- **Service decoupling** through event-based communication
- **System observability** with comprehensive event trails
## Alternatives & Trade-offs
### Pure Python Solutions
| Library | Pros | Cons | Best For |
|---------|------|------|----------|
| **pyeventsourcing** | Mature, comprehensive Python ecosystem | 10-60x slower, memory-intensive | Simple applications, prototypes |
| **Custom implementation** | Full control, tailored to needs | High development cost, maintenance burden | Specific niche requirements |
### Enterprise Platforms
| Solution | Pros | Cons | Best For |
|----------|------|------|----------|
| **EventStore DB** | Proven at scale, rich querying | Separate infrastructure, operational complexity | Large enterprises with dedicated ops teams |
| **Axon Framework** | Battle-tested, mature ecosystem | Java-only, steep learning curve | Java shops, complex domains |
| **Apache Kafka** | Massive scale, proven reliability | Stream-only (not event sourcing), complex setup | Event streaming, not full event sourcing |
### **Eventuali's Sweet Spot**
✅ **Python teams** needing enterprise performance
✅ **Single-library solution** - no external infrastructure
✅ **Multi-database support** - PostgreSQL, SQLite built-in
✅ **Production-ready** - security, compliance, multi-tenancy included
✅ **Performance critical** - 79K+ events/sec, 1M+ encryption ops/sec
## When NOT to Use Eventuali
**❌ Skip if you have:**
- **Simple CRUD applications** - Traditional databases are simpler and sufficient
- **Early MVP/prototype stage** - Event sourcing adds complexity during rapid iteration
- **Pure I/O bound workloads** - Database bottlenecks limit Rust performance benefits
- **No event sourcing experience** - Steep learning curve for teams new to the pattern
- **Extreme simplicity requirements** - Event sourcing inherently adds architectural complexity
**✅ Perfect if you need:**
- **Performance at Python scale** (10K+ events/second)
- **Regulatory compliance** with immutable audit trails
- **Complex domain logic** with rich business rules
- **Historical analysis** and temporal querying
- **Multi-tenant isolation** with enterprise security
## Performance vs Complexity Trade-off
```
High Performance
▲
Eventuali │ EventStore DB
● │ ●
│ Axon Framework
│ ●
│
Custom ●────┼────● pyeventsourcing
│
│
└──────────────────►
Simple Complex
Implementation
```
**Eventuali occupies the optimal position**: High performance with manageable complexity for Python teams.
## Overview
Eventuali combines the performance and memory safety of Rust with the developer experience of Python to create a powerful event sourcing library. It provides:
- **10-60x performance improvement** over pure Python implementations
- **8-20x better memory efficiency**
- **Multi-database support** (PostgreSQL, SQLite)
- **Seamless Python integration** with Pydantic models
- **Async/await support** throughout
- **Type safety** with full type hints
## Architecture
- **Rust Core** (`eventuali-core`): High-performance event storage, serialization, and projections
- **Python Bindings** (`eventuali-python`): PyO3-based bindings with Pythonic APIs
- **Multi-Database**: Unified interface supporting PostgreSQL and SQLite
## Installation
### Production Installation
```bash
# Install from PyPI (when available)
uv add eventuali
```
### Development Installation
```bash
# Clone the repository
git clone git@github.com:primevalai/eventuali.git
cd eventuali/eventuali-python
# Install with development dependencies
uv sync
# Install required tools
uv tool install maturin
uv tool install patchelf
# Build Python bindings
uv run maturin develop
# Verify installation
uv run python ../examples/01_basic_event_store_simple.py
```
## Quick Start
```python
import asyncio
from eventuali import EventStore, Aggregate, Event
from pydantic import BaseModel
# Define your events
class UserRegistered(Event):
name: str
email: str
class UserEmailChanged(Event):
new_email: str
# Define your aggregate
class User(Aggregate):
name: str = ""
email: str = ""
def apply_user_registered(self, event: UserRegistered) -> None:
self.name = event.name
self.email = event.email
def apply_user_email_changed(self, event: UserEmailChanged) -> None:
self.email = event.new_email
async def main():
# Initialize the event store (SQLite for development)
store = await EventStore.create("sqlite://events.db")
# Create and save an aggregate
user = User()
user.apply(UserRegistered(name="John Doe", email="john@example.com"))
await store.save(user)
# Load and update the aggregate
loaded_user = await store.load(User, user.id)
loaded_user.apply(UserEmailChanged(new_email="john.doe@example.com"))
await store.save(loaded_user)
asyncio.run(main())
```
## Features
### Multi-Database Support
```python
# PostgreSQL for production
store = await EventStore.create(
"postgresql://user:password@localhost/events"
)
# SQLite for development/testing
store = await EventStore.create("sqlite://events.db")
```
### High-Performance Serialization
- Protocol Buffers for maximum performance
- JSON fallback for development and debugging
- Automatic schema evolution support
### Async Throughout
Built from the ground up with async/await support using Tokio (Rust) and asyncio (Python).
## Development
This project uses a Rust/Python hybrid approach with **UV as the mandated Python toolchain**:
1. **Rust workspace** with `eventuali-core` and `eventuali-python`
2. **Maturin** for building Python wheels with embedded Rust
3. **PyO3** for seamless Rust-Python integration
4. **UV** for all Python dependency management, tool installation, and script execution
### UV Requirements
**⚠️ IMPORTANT: This project exclusively uses UV for Python operations.**
UV provides faster, more reliable Python dependency management and ensures consistent environments across development and CI/CD:
- **Faster installs**: 10-100x faster than pip
- **Dependency resolution**: More reliable than pip-tools
- **Tool management**: Built-in support for development tools
- **Environment isolation**: Better virtual environment handling
### Building from Source
**⚠️ Use UV for all Python operations as per project standards**
```bash
# Install required tools using UV
uv tool install maturin
uv tool install patchelf
# Install project dependencies
cd eventuali-python
uv sync
# Build and install in development mode
uv run maturin develop
# Run tests
uv run pytest
# Format code
uv run black ../examples/
uv run ruff check ../examples/ --fix
```
### Testing Your Build
After building, verify everything works by running the examples using **UV**:
```bash
# Test the Rust core (fastest way to verify the build)
cargo run --package eventuali-core --example rust_streaming_demo
# Test Python bindings compilation
cargo build --package eventuali-python
# Run Python examples using UV (required)
cd eventuali-python
uv run python ../examples/01_basic_event_store_simple.py
uv run python ../examples/02_aggregate_lifecycle.py
uv run python ../examples/03_error_handling.py
uv run python ../examples/04_performance_testing.py
# Advanced examples
uv run python ../examples/05_multi_aggregate_simple.py
uv run python ../examples/06_event_versioning.py
uv run python ../examples/07_saga_patterns.py
uv run python ../examples/08_projections.py
```
See the [Examples](#examples) section for comprehensive documentation on running and understanding each example.
## Performance
Benchmarks show significant performance improvements over pure Python event sourcing:
- **Serialization**: 20-30x faster
- **Database operations**: 2-10x faster
- **Memory usage**: 8-20x more efficient
- **Concurrent throughput**: 2x better under load
## Examples
This section provides comprehensive examples demonstrating Eventuali's capabilities, from basic event sourcing concepts to high-performance streaming.
### 📖 Quick Example Navigation
#### 📚 Basic Examples (01-04) - Learn the Fundamentals
- **[01 - Basic Event Store Simple](examples/01_basic_event_store_simple.py)** - Event persistence, aggregate reconstruction
- **[02 - Aggregate Lifecycle](examples/02_aggregate_lifecycle.py)** - Complex business logic, state transitions
- **[03 - Error Handling](examples/03_error_handling.py)** - Domain exceptions, validation patterns
- **[04 - Performance Testing](examples/04_performance_testing.py)** - Benchmarking (64k+ events/sec)
#### 🔄 Intermediate Examples (05-08) - Production Patterns
- **[05 - Multi-Aggregate Coordination](examples/05_multi_aggregate_simple.py)** - Cross-aggregate workflows
- **[06 - Event Versioning](examples/06_event_versioning.py)** - Schema evolution, backward compatibility
- **[07 - Saga Patterns](examples/07_saga_patterns.py)** - Distributed transactions (~214ms avg)
- **[08 - Projections](examples/08_projections.py)** - Real-time analytics (78k+ events/sec)
#### 🚀 Advanced Examples (09-16) - Enterprise Scale
- **[09 - CQRS Patterns](examples/09_cqrs_patterns.py)** - Command-Query separation, multiple read models
- **[10 - Event Replay](examples/10_event_replay.py)** - Historical state reconstruction, time travel
- **[11 - Distributed Events](examples/11_distributed_events.py)** - Multi-node coordination, 100% availability
- **[12 - Microservices Integration](examples/12_microservices_integration.py)** - 4 services, event-driven communication
- **[13 - Real-time Dashboards](examples/13_realtime_dashboards.py)** - Live data visualization, streaming updates
- **[14 - Production Monitoring](examples/14_production_monitoring.py)** - Health checks, SLA monitoring (99.9% uptime)
- **[15 - Advanced Patterns](examples/15_advanced_patterns.py)** - Snapshots, temporal queries, multi-tenancy
- **[16 - Enterprise Features](examples/16_enterprise_features.py)** - Security, compliance, HA/DR
#### 🔧 CLI Examples (17-20) - Production Tooling
- **[17 - CLI Basic Operations](examples/17_cli_basic_operations.py)** - CLI fundamentals, configuration management
- **[18 - CLI Database Management](examples/18_cli_database_management.py)** - Database workflows, migrations (100% success)
- **[19 - CLI Performance Monitoring](examples/19_cli_performance_monitoring.py)** - Performance analysis via CLI
- **[20 - CLI Production Workflow](examples/20_cli_production_workflow.py)** - End-to-end production deployment
📋 **[Complete Examples Documentation →](examples/README.md)** - Detailed guides, expected outputs, and performance metrics
### Prerequisites
Before running examples, ensure you have the required dependencies:
```bash
# Install Rust (required for all examples)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install Protocol Buffers compiler (for Rust examples)
# Ubuntu/Debian:
sudo apt install protobuf-compiler
# macOS:
brew install protobuf
# Build the project
cargo build --release
# For Python examples, compile Python bindings
cargo build --package eventuali-python
```
### Rust Examples
#### High-Performance Streaming Demo
**Location**: `eventuali-core/examples/rust_streaming_demo.rs`
This comprehensive example demonstrates the full power of Eventuali's Rust core, showcasing real-world event sourcing and streaming scenarios.
```bash
# Run the complete streaming demonstration
cargo run --package eventuali-core --example rust_streaming_demo
```
**What it demonstrates:**
- ✅ **High-performance event store** with SQLite backend
- ✅ **Real-time event streaming** with broadcast channels
- ✅ **Projection system** building read models from events
- ✅ **Position tracking** for reliable exactly-once processing
- ✅ **Event sourcing** with full event replay capabilities
- ✅ **Batch processing** demonstrating high throughput
- ✅ **Complete async workflow** with Tokio
**Expected Performance:**
- **10,000+ events/second** throughput
- Real-time streaming with < 1ms latency
- Memory-efficient processing of large event batches
- Demonstrates the 10-60x performance improvements over Python
**Sample Output:**
```
=== Eventuali Rust Streaming Demo ===
1. Setting up SQLite event store...
✓ Event store ready
2. Creating high-performance event streamer...
✓ Event streamer connected to store
3. Setting up user projection...
✓ Projection subscribed to User events
...
10. Performance demonstration...
✓ Saved 100 events in 9.309ms (10742.08 events/sec)
✓ Projection now contains 103 users
=== Demo completed successfully! ===
Key achievements:
✓ High-performance event store with SQLite backend
✓ Real-time event streaming with broadcast channels
✓ Projection system building read models from events
✓ Position tracking for reliable exactly-once processing
✓ Event sourcing with full event replay capabilities
✓ Batch processing demonstrating high throughput
✓ Production-ready Rust implementation complete
```
### Python Examples
#### Basic Event Sourcing
**Location**: `examples/basic_usage.py`
Learn the fundamentals of event sourcing with this comprehensive introduction.
```bash
cd eventuali-python
uv run python ../examples/basic_usage.py
```
**What you'll learn:**
- Creating domain events with Pydantic models
- Building aggregates that apply events
- Event serialization and deserialization
- Event replay to reconstruct state
- State consistency verification
**Key Concepts Covered:**
- Domain events (`UserRegistered`, `UserEmailChanged`, `UserDeactivated`)
- Aggregate root pattern with the `User` aggregate
- Business methods that generate and apply events
- Event sourcing state reconstruction
#### Advanced Streaming Example
**Location**: `examples/streaming_example.py`
Explore real-time event streaming and projection building.
```bash
cd eventuali-python
uv run python ../examples/streaming_example.py
```
**What you'll learn:**
- Setting up event stores with different backends
- Creating high-performance event streamers
- Building real-time projections from event streams
- Event filtering by aggregate and event type
- Position tracking for reliable processing
- Integration between EventStore and EventStreamer
**Features Demonstrated:**
- Real-time event subscriptions
- Background event processing
- Projection-based read models
- Event type filtering
- Stream position management
#### Unit Tests and Testing Patterns
**Location**: `eventuali-python/tests/test_basic.py`
Learn how to test event sourcing applications effectively.
```bash
cd eventuali-python
uv run pytest tests/test_basic.py -v
```
**Testing Patterns Covered:**
- Event creation and serialization testing
- Aggregate behavior verification
- Business method testing
- Event replay testing
- Async event store operations (when available)
### Running the Examples
#### Quick Start - Rust Demo
The fastest way to see Eventuali in action:
```bash
# Clone and build
git clone git@github.com:primevalai/eventuali.git
cd eventuali
cargo build --release
# Run the high-performance demo
cargo run --package eventuali-core --example rust_streaming_demo
```
#### Python Examples Setup
**All Python examples use UV for dependency management:**
```bash
# Setup development environment
cd eventuali/eventuali-python
uv sync
uv tool install maturin
uv tool install patchelf
# Build Python bindings
uv run maturin develop
# Test CLI functionality (now available)
uv run eventuali --help
uv run eventuali config --list
uv run eventuali init --database-url "sqlite://:memory:" --force
uv run eventuali query --limit 5
# Quick start examples (basic)
uv run python ../examples/01_basic_event_store_simple.py # Basic event sourcing
uv run python ../examples/02_aggregate_lifecycle.py # Complex aggregates
uv run python ../examples/03_error_handling.py # Error patterns
uv run python ../examples/04_performance_testing.py # Performance benchmarks (64k+ events/sec)
# Production patterns (intermediate)
uv run python ../examples/05_multi_aggregate_simple.py # Multi-aggregate coordination
uv run python ../examples/06_event_versioning.py # Schema evolution
uv run python ../examples/07_saga_patterns.py # Distributed transactions (~214ms avg)
uv run python ../examples/08_projections.py # Real-time projections (78k+ events/sec)
# Enterprise scale (advanced)
uv run python ../examples/09_cqrs_patterns.py # CQRS with multiple read models
uv run python ../examples/10_event_replay.py # Historical state reconstruction
uv run python ../examples/11_distributed_events.py # Multi-node coordination (100% availability)
uv run python ../examples/12_microservices_integration.py # 4-service event-driven architecture
uv run python ../examples/13_realtime_dashboards.py # Live streaming dashboards
uv run python ../examples/14_production_monitoring.py # Health checks, SLA monitoring (99.9% uptime)
uv run python ../examples/15_advanced_patterns.py # Snapshots, temporal queries, multi-tenancy
uv run python ../examples/16_enterprise_features.py # Security, compliance, HA/DR
# CLI tooling examples
uv run python ../examples/17_cli_basic_operations.py # CLI fundamentals
uv run python ../examples/18_cli_database_management.py # Database workflows (100% success)
uv run python ../examples/19_cli_performance_monitoring.py # CLI performance analysis
uv run python ../examples/20_cli_production_workflow.py # Production deployment pipeline
# Run tests
uv run pytest tests/ -v
# Code quality
uv run black ../examples/
uv run ruff check ../examples/ --fix
```
### Example Progression
We recommend exploring the examples in this order:
1. **Start with Rust Demo** - See the full system in action
2. **Basic Python Usage** - Learn event sourcing fundamentals
3. **Python Streaming** - Understand real-time event processing
4. **Unit Tests** - Learn testing patterns
Each example builds on concepts from the previous ones, providing a comprehensive learning path from basic event sourcing to production-ready streaming applications.
### Performance Insights from Examples
The Rust streaming demo consistently demonstrates:
- **10,000+ events/second** sustained throughput
- **Sub-millisecond** event processing latency
- **Memory efficiency** with large event volumes
- **Reliable processing** with position tracking
- **Real-time projections** with immediate consistency
This showcases the core value proposition: **Rust-level performance with Python-level usability**.
## License
This project is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your preference.
Raw data
{
"_id": null,
"home_page": null,
"name": "eventuali",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "event-sourcing, cqrs, rust, python, performance",
"author": null,
"author_email": "PrimevalAI <info@primeval.ai>",
"download_url": null,
"platform": null,
"description": "<div align=\"center\">\n <img src=\"assets/onyx-octopus-avatar.png\" alt=\"Graphite Gator\" width=\"300\">\n \n # Eventuali (Onyx Octopus): High-performance event sourcing library for Python, powered by Rust.\n</div>\n\n## Why Eventuali?\n\n**Problem**: Pure Python event sourcing hits performance walls at scale. Complex financial calculations, high-throughput IoT streams, and real-time analytics demand more than Python alone can deliver.\n\n**Solution**: Eventuali delivers **Rust-level performance with Python-level simplicity** - the only event sourcing library giving you 10-60x speed improvements without sacrificing developer experience.\n\n```python\n# Same familiar Python code...\nuser.apply(UserRegistered(name=\"John\", email=\"john@example.com\"))\nawait store.save(user)\n\n# ...but with 79,000+ events/second throughput\n# 18.3x faster snapshot reconstruction \n# 186,000+ RBAC operations/second\n```\n\n## Who Needs This?\n\n### \ud83c\udfe6 **Fintech & Banking** \n- **Regulatory compliance** requiring immutable audit trails (SOX, PCI DSS)\n- **High-frequency trading** with microsecond-sensitive operations\n- **Real-time fraud detection** processing millions of transactions\n- **Financial reporting** with historical state reconstruction\n\n### \ud83c\udfe2 **Enterprise SaaS**\n- **Multi-tenant systems** requiring strict data isolation\n- **Real-time analytics dashboards** with streaming updates\n- **CQRS at scale** with complex read model projections\n- **Audit trails** for compliance and security monitoring\n\n### \ud83d\udce1 **IoT & Analytics**\n- **High-volume event ingestion** from thousands of devices\n- **Time-series analysis** with historical event replay\n- **Real-time monitoring** of industrial systems\n- **Edge computing** with performance-critical processing\n\n### \ud83d\udd04 **Microservices**\n- **Event-driven architecture** requiring reliable event ordering\n- **Distributed transactions** with saga pattern coordination\n- **Service decoupling** through event-based communication\n- **System observability** with comprehensive event trails\n\n## Alternatives & Trade-offs\n\n### Pure Python Solutions\n| Library | Pros | Cons | Best For |\n|---------|------|------|----------|\n| **pyeventsourcing** | Mature, comprehensive Python ecosystem | 10-60x slower, memory-intensive | Simple applications, prototypes |\n| **Custom implementation** | Full control, tailored to needs | High development cost, maintenance burden | Specific niche requirements |\n\n### Enterprise Platforms\n| Solution | Pros | Cons | Best For |\n|----------|------|------|----------|\n| **EventStore DB** | Proven at scale, rich querying | Separate infrastructure, operational complexity | Large enterprises with dedicated ops teams |\n| **Axon Framework** | Battle-tested, mature ecosystem | Java-only, steep learning curve | Java shops, complex domains |\n| **Apache Kafka** | Massive scale, proven reliability | Stream-only (not event sourcing), complex setup | Event streaming, not full event sourcing |\n\n### **Eventuali's Sweet Spot**\n\u2705 **Python teams** needing enterprise performance \n\u2705 **Single-library solution** - no external infrastructure \n\u2705 **Multi-database support** - PostgreSQL, SQLite built-in \n\u2705 **Production-ready** - security, compliance, multi-tenancy included \n\u2705 **Performance critical** - 79K+ events/sec, 1M+ encryption ops/sec \n\n## When NOT to Use Eventuali\n\n**\u274c Skip if you have:**\n- **Simple CRUD applications** - Traditional databases are simpler and sufficient\n- **Early MVP/prototype stage** - Event sourcing adds complexity during rapid iteration \n- **Pure I/O bound workloads** - Database bottlenecks limit Rust performance benefits\n- **No event sourcing experience** - Steep learning curve for teams new to the pattern\n- **Extreme simplicity requirements** - Event sourcing inherently adds architectural complexity\n\n**\u2705 Perfect if you need:**\n- **Performance at Python scale** (10K+ events/second)\n- **Regulatory compliance** with immutable audit trails\n- **Complex domain logic** with rich business rules\n- **Historical analysis** and temporal querying\n- **Multi-tenant isolation** with enterprise security\n\n## Performance vs Complexity Trade-off\n\n```\n High Performance\n \u25b2\n Eventuali \u2502 EventStore DB\n \u25cf \u2502 \u25cf\n \u2502 Axon Framework \n \u2502 \u25cf\n \u2502\n Custom \u25cf\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u25cf pyeventsourcing\n \u2502\n \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25ba \n Simple Complex\n Implementation\n```\n\n**Eventuali occupies the optimal position**: High performance with manageable complexity for Python teams.\n\n## Overview\n\nEventuali combines the performance and memory safety of Rust with the developer experience of Python to create a powerful event sourcing library. It provides:\n\n- **10-60x performance improvement** over pure Python implementations\n- **8-20x better memory efficiency** \n- **Multi-database support** (PostgreSQL, SQLite)\n- **Seamless Python integration** with Pydantic models\n- **Async/await support** throughout\n- **Type safety** with full type hints\n\n## Architecture\n\n- **Rust Core** (`eventuali-core`): High-performance event storage, serialization, and projections\n- **Python Bindings** (`eventuali-python`): PyO3-based bindings with Pythonic APIs\n- **Multi-Database**: Unified interface supporting PostgreSQL and SQLite\n\n## Installation\n\n### Production Installation\n```bash\n# Install from PyPI (when available)\nuv add eventuali\n```\n\n### Development Installation\n```bash\n# Clone the repository\ngit clone git@github.com:primevalai/eventuali.git\ncd eventuali/eventuali-python\n\n# Install with development dependencies \nuv sync\n\n# Install required tools\nuv tool install maturin\nuv tool install patchelf\n\n# Build Python bindings\nuv run maturin develop\n\n# Verify installation\nuv run python ../examples/01_basic_event_store_simple.py\n```\n\n## Quick Start\n\n```python\nimport asyncio\nfrom eventuali import EventStore, Aggregate, Event\nfrom pydantic import BaseModel\n\n# Define your events\nclass UserRegistered(Event):\n name: str\n email: str\n\nclass UserEmailChanged(Event):\n new_email: str\n\n# Define your aggregate\nclass User(Aggregate):\n name: str = \"\"\n email: str = \"\"\n \n def apply_user_registered(self, event: UserRegistered) -> None:\n self.name = event.name\n self.email = event.email\n \n def apply_user_email_changed(self, event: UserEmailChanged) -> None:\n self.email = event.new_email\n\nasync def main():\n # Initialize the event store (SQLite for development)\n store = await EventStore.create(\"sqlite://events.db\")\n \n # Create and save an aggregate\n user = User()\n user.apply(UserRegistered(name=\"John Doe\", email=\"john@example.com\"))\n await store.save(user)\n \n # Load and update the aggregate\n loaded_user = await store.load(User, user.id)\n loaded_user.apply(UserEmailChanged(new_email=\"john.doe@example.com\"))\n await store.save(loaded_user)\n\nasyncio.run(main())\n```\n\n## Features\n\n### Multi-Database Support\n\n```python\n# PostgreSQL for production\nstore = await EventStore.create(\n \"postgresql://user:password@localhost/events\"\n)\n\n# SQLite for development/testing\nstore = await EventStore.create(\"sqlite://events.db\")\n```\n\n### High-Performance Serialization\n\n- Protocol Buffers for maximum performance\n- JSON fallback for development and debugging\n- Automatic schema evolution support\n\n### Async Throughout\n\nBuilt from the ground up with async/await support using Tokio (Rust) and asyncio (Python).\n\n## Development\n\nThis project uses a Rust/Python hybrid approach with **UV as the mandated Python toolchain**:\n\n1. **Rust workspace** with `eventuali-core` and `eventuali-python`\n2. **Maturin** for building Python wheels with embedded Rust\n3. **PyO3** for seamless Rust-Python integration\n4. **UV** for all Python dependency management, tool installation, and script execution\n\n### UV Requirements\n\n**\u26a0\ufe0f IMPORTANT: This project exclusively uses UV for Python operations.**\n\nUV provides faster, more reliable Python dependency management and ensures consistent environments across development and CI/CD:\n\n- **Faster installs**: 10-100x faster than pip\n- **Dependency resolution**: More reliable than pip-tools\n- **Tool management**: Built-in support for development tools\n- **Environment isolation**: Better virtual environment handling\n\n### Building from Source\n\n**\u26a0\ufe0f Use UV for all Python operations as per project standards**\n\n```bash\n# Install required tools using UV\nuv tool install maturin\nuv tool install patchelf\n\n# Install project dependencies\ncd eventuali-python\nuv sync\n\n# Build and install in development mode\nuv run maturin develop\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run black ../examples/\nuv run ruff check ../examples/ --fix\n```\n\n### Testing Your Build\n\nAfter building, verify everything works by running the examples using **UV**:\n\n```bash\n# Test the Rust core (fastest way to verify the build)\ncargo run --package eventuali-core --example rust_streaming_demo\n\n# Test Python bindings compilation\ncargo build --package eventuali-python\n\n# Run Python examples using UV (required)\ncd eventuali-python\nuv run python ../examples/01_basic_event_store_simple.py\nuv run python ../examples/02_aggregate_lifecycle.py\nuv run python ../examples/03_error_handling.py\nuv run python ../examples/04_performance_testing.py\n\n# Advanced examples\nuv run python ../examples/05_multi_aggregate_simple.py\nuv run python ../examples/06_event_versioning.py\nuv run python ../examples/07_saga_patterns.py\nuv run python ../examples/08_projections.py\n```\n\nSee the [Examples](#examples) section for comprehensive documentation on running and understanding each example.\n\n## Performance\n\nBenchmarks show significant performance improvements over pure Python event sourcing:\n\n- **Serialization**: 20-30x faster\n- **Database operations**: 2-10x faster\n- **Memory usage**: 8-20x more efficient\n- **Concurrent throughput**: 2x better under load\n\n## Examples\n\nThis section provides comprehensive examples demonstrating Eventuali's capabilities, from basic event sourcing concepts to high-performance streaming.\n\n### \ud83d\udcd6 Quick Example Navigation\n\n#### \ud83d\udcda Basic Examples (01-04) - Learn the Fundamentals\n- **[01 - Basic Event Store Simple](examples/01_basic_event_store_simple.py)** - Event persistence, aggregate reconstruction\n- **[02 - Aggregate Lifecycle](examples/02_aggregate_lifecycle.py)** - Complex business logic, state transitions \n- **[03 - Error Handling](examples/03_error_handling.py)** - Domain exceptions, validation patterns\n- **[04 - Performance Testing](examples/04_performance_testing.py)** - Benchmarking (64k+ events/sec)\n\n#### \ud83d\udd04 Intermediate Examples (05-08) - Production Patterns\n- **[05 - Multi-Aggregate Coordination](examples/05_multi_aggregate_simple.py)** - Cross-aggregate workflows\n- **[06 - Event Versioning](examples/06_event_versioning.py)** - Schema evolution, backward compatibility\n- **[07 - Saga Patterns](examples/07_saga_patterns.py)** - Distributed transactions (~214ms avg)\n- **[08 - Projections](examples/08_projections.py)** - Real-time analytics (78k+ events/sec)\n\n#### \ud83d\ude80 Advanced Examples (09-16) - Enterprise Scale\n- **[09 - CQRS Patterns](examples/09_cqrs_patterns.py)** - Command-Query separation, multiple read models\n- **[10 - Event Replay](examples/10_event_replay.py)** - Historical state reconstruction, time travel\n- **[11 - Distributed Events](examples/11_distributed_events.py)** - Multi-node coordination, 100% availability\n- **[12 - Microservices Integration](examples/12_microservices_integration.py)** - 4 services, event-driven communication\n- **[13 - Real-time Dashboards](examples/13_realtime_dashboards.py)** - Live data visualization, streaming updates\n- **[14 - Production Monitoring](examples/14_production_monitoring.py)** - Health checks, SLA monitoring (99.9% uptime)\n- **[15 - Advanced Patterns](examples/15_advanced_patterns.py)** - Snapshots, temporal queries, multi-tenancy\n- **[16 - Enterprise Features](examples/16_enterprise_features.py)** - Security, compliance, HA/DR\n\n#### \ud83d\udd27 CLI Examples (17-20) - Production Tooling\n- **[17 - CLI Basic Operations](examples/17_cli_basic_operations.py)** - CLI fundamentals, configuration management\n- **[18 - CLI Database Management](examples/18_cli_database_management.py)** - Database workflows, migrations (100% success)\n- **[19 - CLI Performance Monitoring](examples/19_cli_performance_monitoring.py)** - Performance analysis via CLI\n- **[20 - CLI Production Workflow](examples/20_cli_production_workflow.py)** - End-to-end production deployment\n\n\ud83d\udccb **[Complete Examples Documentation \u2192](examples/README.md)** - Detailed guides, expected outputs, and performance metrics\n\n### Prerequisites\n\nBefore running examples, ensure you have the required dependencies:\n\n```bash\n# Install Rust (required for all examples)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Install Protocol Buffers compiler (for Rust examples)\n# Ubuntu/Debian:\nsudo apt install protobuf-compiler\n# macOS:\nbrew install protobuf\n\n# Build the project\ncargo build --release\n\n# For Python examples, compile Python bindings\ncargo build --package eventuali-python\n```\n\n### Rust Examples\n\n#### High-Performance Streaming Demo\n\n**Location**: `eventuali-core/examples/rust_streaming_demo.rs`\n\nThis comprehensive example demonstrates the full power of Eventuali's Rust core, showcasing real-world event sourcing and streaming scenarios.\n\n```bash\n# Run the complete streaming demonstration\ncargo run --package eventuali-core --example rust_streaming_demo\n```\n\n**What it demonstrates:**\n- \u2705 **High-performance event store** with SQLite backend\n- \u2705 **Real-time event streaming** with broadcast channels \n- \u2705 **Projection system** building read models from events\n- \u2705 **Position tracking** for reliable exactly-once processing\n- \u2705 **Event sourcing** with full event replay capabilities\n- \u2705 **Batch processing** demonstrating high throughput\n- \u2705 **Complete async workflow** with Tokio\n\n**Expected Performance:**\n- **10,000+ events/second** throughput\n- Real-time streaming with < 1ms latency\n- Memory-efficient processing of large event batches\n- Demonstrates the 10-60x performance improvements over Python\n\n**Sample Output:**\n```\n=== Eventuali Rust Streaming Demo ===\n\n1. Setting up SQLite event store...\n \u2713 Event store ready\n\n2. Creating high-performance event streamer...\n \u2713 Event streamer connected to store\n\n3. Setting up user projection...\n \u2713 Projection subscribed to User events\n\n...\n\n10. Performance demonstration...\n \u2713 Saved 100 events in 9.309ms (10742.08 events/sec)\n \u2713 Projection now contains 103 users\n\n=== Demo completed successfully! ===\nKey achievements:\n\u2713 High-performance event store with SQLite backend\n\u2713 Real-time event streaming with broadcast channels\n\u2713 Projection system building read models from events\n\u2713 Position tracking for reliable exactly-once processing\n\u2713 Event sourcing with full event replay capabilities\n\u2713 Batch processing demonstrating high throughput\n\u2713 Production-ready Rust implementation complete\n```\n\n### Python Examples\n\n#### Basic Event Sourcing\n\n**Location**: `examples/basic_usage.py`\n\nLearn the fundamentals of event sourcing with this comprehensive introduction.\n\n```bash\ncd eventuali-python\nuv run python ../examples/basic_usage.py\n```\n\n**What you'll learn:**\n- Creating domain events with Pydantic models\n- Building aggregates that apply events\n- Event serialization and deserialization\n- Event replay to reconstruct state\n- State consistency verification\n\n**Key Concepts Covered:**\n- Domain events (`UserRegistered`, `UserEmailChanged`, `UserDeactivated`)\n- Aggregate root pattern with the `User` aggregate\n- Business methods that generate and apply events\n- Event sourcing state reconstruction\n\n#### Advanced Streaming Example\n\n**Location**: `examples/streaming_example.py`\n\nExplore real-time event streaming and projection building.\n\n```bash\ncd eventuali-python \nuv run python ../examples/streaming_example.py\n```\n\n**What you'll learn:**\n- Setting up event stores with different backends\n- Creating high-performance event streamers\n- Building real-time projections from event streams\n- Event filtering by aggregate and event type\n- Position tracking for reliable processing\n- Integration between EventStore and EventStreamer\n\n**Features Demonstrated:**\n- Real-time event subscriptions\n- Background event processing\n- Projection-based read models\n- Event type filtering\n- Stream position management\n\n#### Unit Tests and Testing Patterns\n\n**Location**: `eventuali-python/tests/test_basic.py`\n\nLearn how to test event sourcing applications effectively.\n\n```bash\ncd eventuali-python\nuv run pytest tests/test_basic.py -v\n```\n\n**Testing Patterns Covered:**\n- Event creation and serialization testing\n- Aggregate behavior verification\n- Business method testing\n- Event replay testing\n- Async event store operations (when available)\n\n### Running the Examples\n\n#### Quick Start - Rust Demo\n\nThe fastest way to see Eventuali in action:\n\n```bash\n# Clone and build\ngit clone git@github.com:primevalai/eventuali.git\ncd eventuali\ncargo build --release\n\n# Run the high-performance demo\ncargo run --package eventuali-core --example rust_streaming_demo\n```\n\n#### Python Examples Setup\n\n**All Python examples use UV for dependency management:**\n\n```bash\n# Setup development environment\ncd eventuali/eventuali-python\nuv sync\nuv tool install maturin\nuv tool install patchelf\n\n# Build Python bindings\nuv run maturin develop\n\n# Test CLI functionality (now available)\nuv run eventuali --help\nuv run eventuali config --list\nuv run eventuali init --database-url \"sqlite://:memory:\" --force\nuv run eventuali query --limit 5\n\n# Quick start examples (basic)\nuv run python ../examples/01_basic_event_store_simple.py # Basic event sourcing\nuv run python ../examples/02_aggregate_lifecycle.py # Complex aggregates\nuv run python ../examples/03_error_handling.py # Error patterns\nuv run python ../examples/04_performance_testing.py # Performance benchmarks (64k+ events/sec)\n\n# Production patterns (intermediate)\nuv run python ../examples/05_multi_aggregate_simple.py # Multi-aggregate coordination\nuv run python ../examples/06_event_versioning.py # Schema evolution\nuv run python ../examples/07_saga_patterns.py # Distributed transactions (~214ms avg)\nuv run python ../examples/08_projections.py # Real-time projections (78k+ events/sec)\n\n# Enterprise scale (advanced)\nuv run python ../examples/09_cqrs_patterns.py # CQRS with multiple read models\nuv run python ../examples/10_event_replay.py # Historical state reconstruction\nuv run python ../examples/11_distributed_events.py # Multi-node coordination (100% availability)\nuv run python ../examples/12_microservices_integration.py # 4-service event-driven architecture\nuv run python ../examples/13_realtime_dashboards.py # Live streaming dashboards\nuv run python ../examples/14_production_monitoring.py # Health checks, SLA monitoring (99.9% uptime)\nuv run python ../examples/15_advanced_patterns.py # Snapshots, temporal queries, multi-tenancy\nuv run python ../examples/16_enterprise_features.py # Security, compliance, HA/DR\n\n# CLI tooling examples\nuv run python ../examples/17_cli_basic_operations.py # CLI fundamentals\nuv run python ../examples/18_cli_database_management.py # Database workflows (100% success)\nuv run python ../examples/19_cli_performance_monitoring.py # CLI performance analysis\nuv run python ../examples/20_cli_production_workflow.py # Production deployment pipeline\n\n# Run tests\nuv run pytest tests/ -v\n\n# Code quality\nuv run black ../examples/\nuv run ruff check ../examples/ --fix\n```\n\n### Example Progression\n\nWe recommend exploring the examples in this order:\n\n1. **Start with Rust Demo** - See the full system in action\n2. **Basic Python Usage** - Learn event sourcing fundamentals \n3. **Python Streaming** - Understand real-time event processing\n4. **Unit Tests** - Learn testing patterns\n\nEach example builds on concepts from the previous ones, providing a comprehensive learning path from basic event sourcing to production-ready streaming applications.\n\n### Performance Insights from Examples\n\nThe Rust streaming demo consistently demonstrates:\n\n- **10,000+ events/second** sustained throughput\n- **Sub-millisecond** event processing latency \n- **Memory efficiency** with large event volumes\n- **Reliable processing** with position tracking\n- **Real-time projections** with immediate consistency\n\nThis showcases the core value proposition: **Rust-level performance with Python-level usability**.\n\n## License\n\nThis project is licensed under either of\n\n- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your preference.\n",
"bugtrack_url": null,
"license": "MIT OR Apache-2.0",
"summary": "High-performance event sourcing library combining Rust performance with Python ease of use",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/primevalai/onyx-octopus/releases",
"Documentation": "https://github.com/primevalai/onyx-octopus",
"Homepage": "https://github.com/primevalai/onyx-octopus",
"Issues": "https://github.com/primevalai/onyx-octopus/issues",
"Repository": "https://github.com/primevalai/onyx-octopus"
},
"split_keywords": [
"event-sourcing",
" cqrs",
" rust",
" python",
" performance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "66a84282bf24764bafdaf4041e2ef973beef6a444a55f69ec75974712b312529",
"md5": "19fb53d28375b7787d41e22ae6cf39c3",
"sha256": "7dd63dfb1e846379fe2a8bf9dacfbc5a9bdfa841bcc3d290536b85b9ad5c74d7"
},
"downloads": -1,
"filename": "eventuali-0.1.1-cp38-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "19fb53d28375b7787d41e22ae6cf39c3",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 4318849,
"upload_time": "2025-08-14T02:12:20",
"upload_time_iso_8601": "2025-08-14T02:12:20.634669Z",
"url": "https://files.pythonhosted.org/packages/66/a8/4282bf24764bafdaf4041e2ef973beef6a444a55f69ec75974712b312529/eventuali-0.1.1-cp38-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f63e5dd6575a99d261eae1202e4120a241b710f250ac11a8a36fb41f6564e739",
"md5": "409ec7472408ec0588082025ac5fc87e",
"sha256": "066a8880e216a6a1b5a8b6b6901dd6ab1570e50c8b8d401788d2e20de1db2bf0"
},
"downloads": -1,
"filename": "eventuali-0.1.1-cp38-abi3-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "409ec7472408ec0588082025ac5fc87e",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 7332484,
"upload_time": "2025-08-14T02:12:23",
"upload_time_iso_8601": "2025-08-14T02:12:23.248319Z",
"url": "https://files.pythonhosted.org/packages/f6/3e/5dd6575a99d261eae1202e4120a241b710f250ac11a8a36fb41f6564e739/eventuali-0.1.1-cp38-abi3-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e8de24d64e0f9025124d003b51d4d80b11bb7952248412f63d66d3a5035620c",
"md5": "8bd86086ac15ef55385748aa45a8746a",
"sha256": "d576c11be68fa66b267c41e6278e7fce0dffe84489b76d26476c482c0928d809"
},
"downloads": -1,
"filename": "eventuali-0.1.1-cp38-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "8bd86086ac15ef55385748aa45a8746a",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 4659099,
"upload_time": "2025-08-14T02:12:24",
"upload_time_iso_8601": "2025-08-14T02:12:24.937795Z",
"url": "https://files.pythonhosted.org/packages/4e/8d/e24d64e0f9025124d003b51d4d80b11bb7952248412f63d66d3a5035620c/eventuali-0.1.1-cp38-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 02:12:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "primevalai",
"github_project": "onyx-octopus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "eventuali"
}
JSON
