Nexus

Ultimate Simplicity, Uncompromising Power.

Nexus is a next-generation Python framework built from the ground up to unify Web, Data, and AI applications into a single, cohesive developer experience.

⚡ The Philosophy

1. Magical for Beginners, Unrestricted for Experts
   • 3 levels of API for every feature:
     • Level 1 (Magical): One-liner convention defaults (from nexus import Nexus; app = Nexus()).
     • Level 2 (Configured): Explicit dependency injection, custom routers, middleware configuration, settings.
     • Level 3 (Raw): Full low-level control (direct ASGI scope, raw receive/send, and stream control) with zero overhead.
2. Enterprise Grade from Day Zero
   • Clean Architecture: strict Separation of Concerns (SoC).
   • core has zero external dependencies.
   • Fully typed with mypy --strict compliance across all source files and test suites.
   • Comprehensive unit test coverage with strict CI threshold (currently 92.35%).
3. No Compromises
   • Built custom where identity matters (e.g., the high-speed NX Template Engine — zero external template dependencies).
   • Async-first internally, seamless for synchronous handlers.

📊 Development Progress & Roadmap Status

📦 Architecture Layers

nexus/
├── nexus/
│   ├── core/           # Pure Python, 0 external dependencies (Protocols, Entities, Exceptions)
│   ├── config/         # pydantic-settings type-safe configuration
│   ├── logging/        # structlog structured logger
│   ├── magic/          # DI and auto-wiring engine
│   ├── web/            # ASGI adapter, Router, Middleware, StaticFiles, Validation, Session, NX Template Engine
│   ├── db/             # Unified Database Layer (Phase 5)
│   ├── data/           # High-speed data processing (Phase 6)
│   └── ai/             # Agentic AI & LLM runtime (Phase 8)

🚀 Quick Example

from nexus import Nexus, NexusRequest, UploadFile
from pydantic import BaseModel, Field

app = Nexus(title="My Nexus App")


class Item(BaseModel):
    name: str
    price: float = Field(gt=0)


# Level 1 Magic Route with automatic Pydantic validation
@app.post("/items")
def create_item(item: Item) -> dict[str, object]:
    return {"status": "created", "item": item.model_dump()}


# Path parameter with automatic type coercion
@app.get("/items/{id:int}")
def get_item(id: int) -> dict[str, object]:
    return {"item_id": id, "name": "Sample Item"}


# Mount static files with path traversal security & range streaming
app.mount_static("/static", "./public")

🧪 Developer Setup & Testing

Requires Python 3.11+.

# Clone the repository
git clone https://github.com/nexus-framework/nexus.git
cd nexus

# Install development & web extras
pip install -e ".[dev,web]"

# Run Ruff linter and formatter checks
ruff check .

# Run strict type checking
mypy nexus tests

# Run full test suite with coverage
pytest --cov=nexus --cov-report=term-missing

🗺️ Detailed Roadmap

For the exhaustive 13-phase development specification, refer to ROADMAP.md.