<div align="center">

```
██████╗  █████╗ ████████╗ █████╗ ██╗   ██╗ ██████╗ ██╗  ██╗███████╗██╗     
██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗██║   ██║██╔═══██╗╚██╗██╔╝██╔════╝██║     
██║  ██║███████║   ██║   ███████║██║   ██║██║   ██║ ╚███╔╝ █████╗  ██║     
██║  ██║██╔══██║   ██║   ██╔══██║╚██╗ ██╔╝██║   ██║ ██╔██╗ ██╔══╝  ██║     
██████╔╝██║  ██║   ██║   ██║  ██║ ╚████╔╝ ╚██████╔╝██╔╝ ██╗███████╗███████╗
╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝  ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝
```

### 🗄️ *Type-Safe Modern ORM* 🗄️

<p align="center">
  <strong>Data in 3D - Where Database Queries Feel Like Magic</strong>
</p>

[![PyPI version](https://img.shields.io/pypi/v/datavoxel?color=blue&style=for-the-badge)](https://pypi.org/project/datavoxel/)
[![Python Versions](https://img.shields.io/pypi/pyversions/datavoxel?style=for-the-badge)](https://pypi.org/project/datavoxel/)
[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/pypi/dm/datavoxel?style=for-the-badge&color=orange)](https://pepy.tech/project/datavoxel)

[![Type Checked](https://img.shields.io/badge/type%20checked-mypy-blue?style=for-the-badge)](http://mypy-lang.org/)
[![Async Ready](https://img.shields.io/badge/async-ready-brightgreen?style=for-the-badge)]()
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](https://github.com/psf/black)

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#-examples">Examples</a> •
  <a href="#-documentation">Documentation</a>
</p>

![Separator](https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif)

</div>

## 🌟 What is DATAVOXEL?

**DATAVOXEL** is a revolutionary ORM that thinks in **3 dimensions**: **Type Safety**, **Developer Experience**, and **Performance**. Built on SQLAlchemy but with a modern twist, it makes database operations feel **natural** and **intuitive**.

```python
from datavoxel import Model, Query

class User(Model):
    __table__ = "users"
    
    id: int
    name: str
    email: str
    created_at: datetime

# Type-safe queries with IDE autocomplete!
users = Query(User).where(User.age > 18).order_by(User.name).limit(10).all()
# 🎯 Your IDE knows exactly what type 'users' is!
```

---

## ✨ Key Features

<table>
<tr>
<td width="50%">

### 🎯 Type Safety
- ✅ **Full Type Hints** - IDE autocomplete everywhere
- 🔍 **Mypy Compatible** - Catch errors before runtime
- 📝 **IntelliSense** - See available fields instantly
- 🛡️ **Compile-Time Checks** - No more typos

</td>
<td width="50%">

### ⚡ Performance
- 🚀 **Async First** - Built for async/await
- 🔄 **Connection Pooling** - Reuse connections
- 💾 **Query Caching** - Automatic optimization
- 📊 **Lazy Loading** - Load data when needed

</td>
</tr>
<tr>
<td width="50%">

### 🎨 Developer Experience
- 💡 **Intuitive API** - Reads like English
- 🔗 **Method Chaining** - Build queries naturally
- 🏗️ **Auto Migrations** - Schema changes made easy
- 📚 **Rich Documentation** - Examples for everything

</td>
<td width="50%">

### 🏗️ Production Ready
- ✅ **Battle Tested** - Built on SQLAlchemy
- 🔒 **SQL Injection Safe** - Parameterized queries
- 🌍 **Multi-DB Support** - Postgres, MySQL, SQLite
- 📈 **Scalable** - From MVP to millions of rows

</td>
</tr>
</table>

---

## 📦 Installation

```bash
# Basic installation (SQLite support)
pip install datavoxel

# With PostgreSQL support
pip install datavoxel[postgres]

# With MySQL support  
pip install datavoxel[mysql]

# With all database drivers
pip install datavoxel[all]
```

---

## 🎯 Quick Start

### Define Your Models

```python
from datavoxel import Model
from datetime import datetime
from typing import Optional

class User(Model):
    __table__ = "users"
    __database__ = "myapp"
    
    id: int
    username: str
    email: str
    is_active: bool = True
    created_at: datetime = datetime.now()
    bio: Optional[str] = None
```

### Simple CRUD Operations

```python
# Create
user = User(username="john_doe", email="john@example.com")
await user.save()

# Read
user = await User.get(id=1)
users = await User.filter(is_active=True).all()

# Update
user.email = "newemail@example.com"
await user.save()

# Delete
await user.delete()
```

### Advanced Queries

```python
from datavoxel import Query, Q

# Complex WHERE clauses
active_users = await Query(User).where(
    (User.is_active == True) & 
    (User.created_at > datetime(2024, 1, 1))
).all()

# Joins
class Post(Model):
    __table__ = "posts"
    user_id: int
    title: str
    content: str

posts_with_users = await Query(Post).join(
    User, Post.user_id == User.id
).select(Post.title, User.username).all()

# Aggregations
from datavoxel import Count, Avg

user_count = await Query(User).aggregate(Count(User.id))
avg_age = await Query(User).aggregate(Avg(User.age))
```

---

## 🏗️ Architecture

```mermaid
graph TB
    A[Your Application] --> B[DATAVOXEL ORM]
    
    B --> C{Query Builder}
    B --> D{Model Manager}
    B --> E{Migration Engine}
    
    C --> F[Type Checker]
    C --> G[SQL Generator]
    
    D --> H[CRUD Operations]
    D --> I[Relationships]
    
    E --> J[Schema Diff]
    E --> K[Auto Migrate]
    
    F --> L[SQLAlchemy Core]
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    
    L --> M{Database Driver}
    M --> N[PostgreSQL]
    M --> O[MySQL]
    M --> P[SQLite]
    
    style B fill:#2196F3
    style L fill:#4CAF50
```

---

## 🔥 Advanced Features

### Relationships

```python
class Author(Model):
    __table__ = "authors"
    id: int
    name: str

class Book(Model):
    __table__ = "books"
    id: int
    title: str
    author_id: int
    
    # Define relationship
    author = Relation(Author, foreign_key="author_id")

# Use relationships
book = await Book.get(id=1)
author = await book.author  # Automatically fetches author
print(f"{book.title} by {author.name}")
```

### Transactions

```python
from datavoxel import transaction

async with transaction():
    user = User(username="alice")
    await user.save()
    
    post = Post(title="First Post", user_id=user.id)
    await post.save()
    
    # Both saved or both rolled back together!
```

### Query Optimization

```python
# Eager loading (N+1 query prevention)
books = await Query(Book).prefetch(Book.author).all()
# Only 2 queries instead of N+1!

# Select only needed fields
users = await Query(User).only(User.id, User.username).all()
# Smaller result set = faster queries

# Bulk operations
await User.bulk_create([
    User(username="user1", email="user1@example.com"),
    User(username="user2", email="user2@example.com"),
])
```

### Custom Queries

```python
# Raw SQL when needed
results = await Query.raw("""
    SELECT users.name, COUNT(posts.id) as post_count
    FROM users
    LEFT JOIN posts ON users.id = posts.user_id
    GROUP BY users.id
    HAVING post_count > 10
""")
```

---

## 📊 Comparison with Other ORMs

| Feature | DATAVOXEL | SQLAlchemy | Django ORM | Peewee | Tortoise |
|---------|-----------|------------|------------|--------|----------|
| Type Safety | ✅ Full | ⚠️ Partial | ❌ No | ❌ No | ⚠️ Partial |
| Async Support | ✅ Native | ✅ Yes | ⚠️ Limited | ❌ No | ✅ Yes |
| Learning Curve | 🟢 Easy | 🔴 Hard | 🟢 Easy | 🟢 Easy | 🟡 Medium |
| Auto Migrations | ✅ Built-in | ⚠️ Alembic | ✅ Yes | ❌ No | ✅ Yes |
| IDE Support | ⚡⚡⚡⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡⚡ |
| Performance | ⚡⚡⚡⚡ | ⚡⚡⚡⚡⚡ | ⚡⚡⚡ | ⚡⚡⚡⚡ | ⚡⚡⚡⚡ |

---

## 🎨 Real-World Examples

### FastAPI Integration

```python
from fastapi import FastAPI, Depends
from datavoxel import Model, Query

app = FastAPI()

class User(Model):
    __table__ = "users"
    id: int
    username: str
    email: str

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = await User.get(id=user_id)
    return user.dict()  # Automatic serialization!

@app.get("/users")
async def list_users(skip: int = 0, limit: int = 10):
    users = await Query(User).offset(skip).limit(limit).all()
    return [user.dict() for user in users]
```

### Data Pipeline

```python
from datavoxel import Model, transaction
import asyncio

class RawData(Model):
    __table__ = "raw_data"
    id: int
    data: str

class ProcessedData(Model):
    __table__ = "processed_data"
    id: int
    result: str

async def process_data():
    raw_items = await Query(RawData).filter(processed=False).all()
    
    async with transaction():
        for item in raw_items:
            # Process data
            result = transform(item.data)
            
            # Save result
            processed = ProcessedData(result=result)
            await processed.save()
            
            # Mark as processed
            item.processed = True
            await item.save()
```

### Multi-Tenant App

```python
from datavoxel import Model, set_schema

class Tenant(Model):
    __table__ = "tenants"
    id: int
    schema_name: str

class User(Model):
    __table__ = "users"
    __schema_bound__ = True  # Uses current schema
    id: int
    name: str

async def get_tenant_users(tenant_id: int):
    tenant = await Tenant.get(id=tenant_id)
    
    # Switch to tenant schema
    set_schema(tenant.schema_name)
    
    # Query tenant-specific data
    users = await Query(User).all()
    return users
```

---

## 📚 Documentation

- 📖 [Full API Reference](https://datavoxel.readthedocs.io)
- 🚀 [Quick Start Guide](https://datavoxel.readthedocs.io/quickstart)
- 🎓 [Tutorial](https://datavoxel.readthedocs.io/tutorial)
- 🏗️ [Migrations Guide](https://datavoxel.readthedocs.io/migrations)
- 🎯 [Best Practices](https://datavoxel.readthedocs.io/best-practices)

---

## 🗺️ Roadmap

### ✅ Version 0.1.0 (Current)
- [x] Type-safe models
- [x] Basic CRUD operations
- [x] Query builder
- [x] Async support

### 🚧 Version 0.2.0 (Coming Soon)
- [ ] Auto migrations
- [ ] Relationship support
- [ ] Connection pooling
- [ ] Query caching

### 🔮 Version 0.3.0 (Planned)
- [ ] Advanced relationships (M2M, polymorphic)
- [ ] Full-text search
- [ ] Database sharding
- [ ] Performance monitoring
- [ ] GraphQL integration

---

## 🤝 Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📜 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 👤 Author

<div align="center">

### **Juste Elysée MALANDILA**

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://linkedin.com/in/juste-elysee-malandila)
[![Email](https://img.shields.io/badge/Email-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:justech4dev@gmail.com)
[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/jdevsky)

*"Making databases feel like magic."* 🗄️

</div>

---

<div align="center">

### Made with ❤️ by [Juste Elysée MALANDILA](https://linkedin.com/in/juste-elysee-malandila)

**DATAVOXEL** - *Data in 3D* 🗄️

![Footer](https://capsule-render.vercel.app/api?type=waving&color=gradient&height=100&section=footer)

</div>
