Metadata-Version: 2.4
Name: aquilia
Version: 1.0.1b1
Summary: Async-native Python web framework with flow-first routing
Home-page: https://github.com/axiomchronicles/Aquilia
Author: Pawan Kumar
Author-email: Pawan Kumar <aegis.invincible@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/axiomchronicles/Aquilia
Project-URL: Documentation, https://github.com/axiomchronicles/Aquilia#readme
Project-URL: Repository, https://github.com/axiomchronicles/Aquilia
Project-URL: Issues, https://github.com/axiomchronicles/Aquilia/issues
Project-URL: Changelog, https://github.com/axiomchronicles/Aquilia/blob/main/CHANGELOG.md
Keywords: web,framework,async,asgi,http,api,routing,middleware,dependency-injection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: AsyncIO
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: templates
Requires-Dist: jinja2>=3.1.0; extra == "templates"
Requires-Dist: markupsafe>=2.1.0; extra == "templates"
Provides-Extra: auth
Requires-Dist: cryptography>=42.0.0; extra == "auth"
Requires-Dist: argon2-cffi>=23.1.0; extra == "auth"
Provides-Extra: db
Requires-Dist: aiosqlite>=0.20.0; extra == "db"
Provides-Extra: files
Requires-Dist: aiofiles>=23.0.0; extra == "files"
Provides-Extra: multipart
Requires-Dist: python-multipart>=0.0.9; extra == "multipart"
Provides-Extra: redis
Requires-Dist: redis[asyncio]>=5.0.0; extra == "redis"
Provides-Extra: mail
Requires-Dist: aiosmtplib>=3.0.0; extra == "mail"
Provides-Extra: mail-ses
Requires-Dist: aiobotocore>=2.9.0; extra == "mail-ses"
Provides-Extra: mail-sendgrid
Requires-Dist: httpx>=0.27.0; extra == "mail-sendgrid"
Provides-Extra: server
Requires-Dist: gunicorn>=22.0.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "server"
Provides-Extra: mlops
Requires-Dist: numpy>=1.24.0; extra == "mlops"
Provides-Extra: mlops-onnx
Requires-Dist: onnxruntime>=1.16.0; extra == "mlops-onnx"
Requires-Dist: onnx>=1.14.0; extra == "mlops-onnx"
Provides-Extra: mlops-torch
Requires-Dist: torch>=2.0.0; extra == "mlops-torch"
Provides-Extra: mlops-s3
Requires-Dist: boto3>=1.28.0; extra == "mlops-s3"
Provides-Extra: mlops-bento
Requires-Dist: bentoml>=1.2.0; extra == "mlops-bento"
Provides-Extra: mlops-explain
Requires-Dist: shap>=0.42.0; extra == "mlops-explain"
Requires-Dist: lime>=1.0.0; extra == "mlops-explain"
Provides-Extra: mlops-all
Requires-Dist: aquilia[mlops,mlops-bento,mlops-explain,mlops-onnx,mlops-s3,mlops-torch]; extra == "mlops-all"
Provides-Extra: full
Requires-Dist: aquilia[auth,db,files,mail,mail-sendgrid,mail-ses,multipart,redis,server,templates]; extra == "full"
Provides-Extra: all
Requires-Dist: aquilia[full,mlops-all]; extra == "all"
Provides-Extra: testing
Requires-Dist: pytest>=8.0.0; extra == "testing"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "testing"
Requires-Dist: pytest-cov>=4.1.0; extra == "testing"
Requires-Dist: httpx>=0.27.0; extra == "testing"
Provides-Extra: dev
Requires-Dist: aquilia[testing]; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<div align="center">
  <img src="aqdocx/public/logo.png" alt="Aquilia Logo" width="200" />
  <h1>Aquilia</h1>
  <p><strong>The speed of a microframework. The reliability of an enterprise engine.</strong></p>

  [![Version](https://img.shields.io/badge/version-1.0.1b1-orange.svg)](https://aquilia.tubox.cloud)
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
  [![Tests](https://img.shields.io/badge/tests-5085%20passing-brightgreen.svg)](#-testing)
</div>

---

**Aquilia** is a Manifest-First, async-native Python framework designed to bridge the gap between developer velocity and production-grade stability. It removes routing and deployment boilerplate, auto-generates infrastructure manifests (Docker/K8s), and comes with built-in MLOps capabilities.

## 🚀 Why Aquilia?

Current frameworks force a trade-off: use a microframework for speed but spend months on infrastructure, or use a "batteries-included" monolith that's hard to scale and deploy. Aquilia changes the game:

- **Manifest-First Architecture**: Your code defines its own infrastructure. No more manual Dockerfile or K8s YAML maintenance.
- **Scoped Dependency Injection**: Built-in, enterprise-grade DI that handles complex lifecycles and provides deep observability.
- **Async-Native Core**: Built for modern, high-concurrency workloads from the ground up.
- **Integrated MLOps**: Native support for artifact versioning, lineage tracking, and model deployment.
- **Structured Fault System**: First-class typed error handling with domains, severity, and recovery strategies — no raw exceptions.
- **Production Security**: HMAC-verified caches, path traversal protection, CSRF/CORS/CSP guards, and sandboxed templates out of the box.

## 📦 Installation

```bash
pip install aquilia
```

Or use the CLI to initialize a new project:

```bash
aq init my-awesome-app
```

## ⚡ Quick Start

Create a controller in `app/controllers.py`:

```python
from aquilia import Controller, GET, RequestCtx

class HelloWorld(Controller):
    @GET("/")
    async def hello(self, ctx: RequestCtx):
        return {"message": "Hello from Aquilia!"}
```

Register it in your `manifest.py`:

```python
from aquilia import AppManifest, ServiceConfig

class MyManifest(AppManifest):
    name = "main"
    version = "1.0.0"
    controllers = ["app.controllers:HelloWorld"]
```

## 🏛️ Core Pillars

### 1. The Manifest System
The `AppManifest` is the single source of truth for your application's requirements. It declares controllers, services, middleware, and database configurations. Aquilia uses this manifest to auto-generate:
- **Dockerfiles** tailored to your dependencies.
- **Kubernetes Manifests** for production-ready deployments.
- **OpenAPI Documentation** for your APIs.

### 2. Scoped Dependency Injection
Forget globals. Aquilia provides a hierarchical DI system:
- **Singleton**: Service lives for the app lifecycle.
- **App**: Scoped to the module level.
- **Request**: Fresh instance for every incoming HTTP request.

### 3. Structured Fault System
Aquilia treats errors as first-class data, not surprises:
- **Typed Faults**: Every error has a stable code, domain, severity, and recovery strategy.
- **12+ Domains**: CONFIG, REGISTRY, DI, ROUTING, FLOW, EFFECT, IO, SECURITY, SYSTEM, MODEL, CACHE, STORAGE, TASKS, TEMPLATE.
- **No Raw Exceptions**: All subsystems use `Fault` subclasses with metadata and serialization support.

### 4. Integrated MLOps
Aquilia treats machine learning as a first-class citizen:
- **Artifact Registry**: Version and track data/model assets.
- **Lineage Tracing**: Know exactly which code produced which model.
- **Shadow Deployments**: Test new models in production without affecting real traffic.

## 🛠️ Subsystems

Aquilia is composed of several deeply integrated subsystems:

| Subsystem | Description |
|-----------|-------------|
| **Aquilary** | Core registry and manifest loader |
| **Flow** | Typed routing and composable request pipelines |
| **Faults** | Structured error handling with 14 fault domains |
| **Auth** | JWT/session auth, MFA, OAuth, RBAC, guards |
| **DI** | Hierarchical dependency injection with lifecycle scopes |
| **Controller** | Aquilia-native controllers with filters, pagination, and typed routing |
| **Sessions** | Pluggable session backends (cookie, Redis, memory) |
| **Cache** | Multi-backend caching with middleware integration |
| **Storage** | Async file storage (local, S3, GCS, Azure, SFTP, memory) |
| **Tasks** | Background job system with priority queues and scheduling |
| **Templates** | Sandboxed Jinja2 with bytecode caching and HMAC integrity |
| **Models/ORM** | Async ORM with query builder, migrations, transactions |
| **Mail** | Multi-provider email (SMTP, SES, SendGrid) |
| **Admin** | Full-featured admin dashboard with audit logging |
| **MLOps** | Model registry, inference, monitoring, deployment |

## 🔒 Security

Aquilia takes security seriously across every subsystem:

- **Auth**: Argon2 password hashing, JWT with rotation, CSRF tokens, rate limiting
- **Templates**: Sandboxed Jinja2 execution, autoescape by default, HMAC-verified bytecode cache
- **Storage**: Path traversal protection, null byte rejection, path length limits
- **Tasks**: Registered-task-only execution (no arbitrary func_ref resolution)
- **Admin**: Role-based permissions, comprehensive audit logging, session security
- **ORM**: Parameterized queries, field name validation, SQL injection prevention

## 🧪 Testing

Run the full unit test suite (5,085 tests):

```bash
python -m pytest tests/ -v
```

Run with coverage:

```bash
python -m pytest tests/ --cov=aquilia --cov-report=html
```

## 🌐 Learn More

- **Documentation**: [https://aquilia.tubox.cloud](https://aquilia.tubox.cloud)
- **Architecture Guide**: [Architecture](https://aquilia.tubox.cloud/docs/architecture)
- **Quick Start**: [Get Started](https://aquilia.tubox.cloud/docs/quickstart)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
- **Security**: [SECURITY.md](SECURITY.md)
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)

---

<p align="center">Built with ❤️ by the Aquilia Team</p>
