Metadata-Version: 2.3
Name: nexus-platform
Version: 0.1.4
Summary: The Ultimate Plugin-Based Application Platform - Build modular, scalable applications with ease
License: MIT
Keywords: framework,plugin-system,modular,fastapi,async,microservices,api,rest,websocket,cli,application-platform,enterprise
Author: Nexus Team
Author-email: team@nexus.dev
Maintainer: Nexus Team
Maintainer-email: team@nexus.dev
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Provides-Extra: all-databases
Provides-Extra: email
Provides-Extra: full
Provides-Extra: mariadb
Provides-Extra: messaging
Provides-Extra: mongodb
Provides-Extra: mysql
Provides-Extra: postgresql
Provides-Extra: redis
Provides-Extra: sqlite
Provides-Extra: task-scheduler
Requires-Dist: aiofiles (>=23.2.1,<24.0.0)
Requires-Dist: aiomysql (>=0.2.0,<0.3.0) ; extra == "mysql" or extra == "mariadb" or extra == "all-databases" or extra == "full"
Requires-Dist: aioredis (>=2.0.1,<3.0.0) ; extra == "redis" or extra == "all-databases" or extra == "full"
Requires-Dist: aiosqlite (>=0.19.0,<0.20.0) ; extra == "sqlite" or extra == "all-databases" or extra == "full"
Requires-Dist: apscheduler (>=3.10.4,<4.0.0) ; extra == "task-scheduler" or extra == "full"
Requires-Dist: asyncpg (>=0.29.0,<0.30.0) ; extra == "postgresql" or extra == "all-databases" or extra == "full"
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: croniter (>=2.0.1,<3.0.0) ; extra == "task-scheduler" or extra == "full"
Requires-Dist: email-validator (>=2.1.0,<3.0.0)
Requires-Dist: emails (>=0.6,<0.7) ; extra == "email" or extra == "full"
Requires-Dist: fastapi (>=0.109.0,<0.110.0)
Requires-Dist: jinja2 (>=3.1.2,<4.0.0) ; extra == "email" or extra == "full"
Requires-Dist: motor (>=3.3.2,<4.0.0) ; extra == "mongodb" or extra == "all-databases" or extra == "full"
Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
Requires-Dist: psutil (>=5.9.0,<6.0.0)
Requires-Dist: psycopg2-binary (>=2.9.9,<3.0.0) ; extra == "postgresql" or extra == "all-databases" or extra == "full"
Requires-Dist: pydantic (>=2.5.3,<3.0.0)
Requires-Dist: pydantic-settings (>=2.1.0,<3.0.0)
Requires-Dist: pymongo (>=4.6.1,<5.0.0) ; extra == "mongodb" or extra == "all-databases" or extra == "full"
Requires-Dist: pymysql (>=1.1.0,<2.0.0) ; extra == "mysql" or extra == "mariadb" or extra == "all-databases" or extra == "full"
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Requires-Dist: python-jose[cryptography] (>=3.3.0,<4.0.0)
Requires-Dist: python-json-logger (>=2.0.7,<3.0.0)
Requires-Dist: python-multipart (>=0.0.6,<0.0.7)
Requires-Dist: python-socketio (>=5.11.0,<6.0.0) ; extra == "messaging" or extra == "full"
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: redis (>=5.0.1,<6.0.0) ; extra == "redis" or extra == "all-databases" or extra == "full"
Requires-Dist: sqlalchemy[asyncio] (>=2.0.25,<3.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Requires-Dist: uvicorn (>=0.27.0,<0.28.0)
Requires-Dist: websockets (>=12.0,<13.0) ; extra == "messaging" or extra == "full"
Project-URL: Bug Tracker, https://github.com/dnviti/nexus-platform/issues
Project-URL: Changelog, https://github.com/dnviti/nexus-platform/blob/main/CHANGELOG.md
Project-URL: Documentation, https://docs.nexus.dev
Project-URL: Discussions, https://github.com/dnviti/nexus-platform/discussions
Project-URL: Discord, https://discord.gg/nexus
Project-URL: Funding, https://github.com/sponsors/dnviti
Project-URL: Homepage, https://nexus.dev
Project-URL: Repository, https://github.com/dnviti/nexus-platform
Project-URL: Twitter, https://twitter.com/nexus_dev
Description-Content-Type: text/markdown

# Nexus

[![PyPI version](https://badge.fury.io/py/nexus.svg)](https://badge.fury.io/py/nexus)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI/CD](https://github.com/dnviti/nexus-platform/actions/workflows/main.yml/badge.svg)](https://github.com/dnviti/nexus-platform/actions/workflows/main.yml)
[![Documentation](https://github.com/dnviti/nexus-platform/actions/workflows/docs.yml/badge.svg)](https://github.com/dnviti/nexus-platform/actions/workflows/docs.yml)
[![Codecov](https://codecov.io/gh/dnviti/nexus-platform/branch/main/graph/badge.svg)](https://codecov.io/gh/dnviti/nexus-platform)
[![Code style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**The Ultimate Plugin-Based Application Platform** - Build modular, scalable applications with ease.

Nexus revolutionizes application development by making **everything a plugin**. Create applications as collections of focused, reusable plugins that work together seamlessly.

## ✨ Key Features

- **🔌 Pure Plugin Architecture** - Every feature is a plugin, ensuring complete modularity
- **🔥 Hot-Reload Support** - Add, update, or remove plugins without restarting
- **🎯 FastAPI Integration** - Modern async web framework with automatic OpenAPI docs
- **🛡️ Built-in Authentication** - JWT-based auth with role-based access control
- **📊 Multi-Database Support** - SQLAlchemy integration with PostgreSQL, MySQL, SQLite
- **🌐 API-First Design** - Automatic REST API generation with Swagger UI
- **⚡ High Performance** - Async/await throughout with optimized request handling
- **📈 Monitoring & Metrics** - Health checks, metrics collection, and observability
- **🔧 CLI Tools** - Powerful command-line interface for development and deployment

## 🚀 Quick Start

### Installation

```bash
pip install nexus-platform
```

### Create Your First Application

```python
from nexus import create_nexus_app

app = create_nexus_app(
    title="My App",
    description="Built with Nexus",
    version="1.0.0"
)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

Your application runs at `http://localhost:8000` with:

- **API Docs**: `http://localhost:8000/docs`
- **Health Check**: `http://localhost:8000/health`

### Create Your First Plugin

```bash
nexus plugin create my_plugin
```

```python
from nexus import BasePlugin
from fastapi import APIRouter

class MyPlugin(BasePlugin):
    def __init__(self):
        super().__init__()
        self.name = "my_plugin"
        self.version = "1.0.0"

    async def initialize(self) -> bool:
        self.logger.info("Plugin initialized!")
        return True

    def get_api_routes(self):
        router = APIRouter(prefix="/my-plugin", tags=["my-plugin"])

        @router.get("/")
        async def get_info():
            return {"plugin": self.name, "status": "active"}

        return [router]

def create_plugin():
    return MyPlugin()
```

## 📚 Documentation

### 🚀 Getting Started

- **[Installation](docs/getting-started/installation.md)** - Install Nexus in 2 minutes
- **[Quick Start](docs/getting-started/quickstart.md)** - Build your first app in 5 minutes
- **[First Plugin](docs/getting-started/first-plugin.md)** - Create your first plugin
- **[Configuration](docs/getting-started/configuration.md)** - Configure your application

### 🏗️ Architecture & Development

- **[Architecture Overview](docs/architecture/overview.md)** - System design and principles
- **[Plugin Basics](docs/plugins/basics.md)** - Build powerful plugins
- **[API Routes](docs/plugins/api-routes.md)** - Create REST endpoints
- **[Database Integration](docs/plugins/database.md)** - Data persistence

### 📚 Complete Documentation

- **[Documentation Index](docs/README.md)** - Full documentation structure
- **[API Reference](docs/api/README.md)** - Complete framework reference
- **[Deployment Guide](docs/deployment/README.md)** - Production deployment

## 🏗️ Architecture

```mermaid
graph TD
    A[Nexus App] --> B[Plugin Manager]
    A --> C[Event Bus]
    A --> D[Service Registry]
    A --> E[FastAPI Core]

    B --> F[Plugin 1]
    B --> G[Plugin 2]
    B --> H[Plugin N...]

    F --> C
    G --> C
    H --> C

    F --> D
    G --> D
    H --> D
```

## 🔧 CLI Tools

```bash
# Application management
nexus run --host 0.0.0.0 --port 8000
nexus init
nexus status
nexus health

# Plugin management
nexus plugin create <name>
nexus plugin list
nexus plugin info <name>

# Admin tools
nexus-admin system info
nexus-admin user create <username>
nexus-admin plugin status
```

## 📁 Project Structure

```
my-nexus-app/
├── main.py                    # Application entry point
├── nexus_config.yaml          # Configuration file
├── nexus/                     # Nexus framework core
├── plugins/                   # Plugin directory
├── plugin_template/           # Plugin development template
├── config/                    # Configuration files
└── pyproject.toml            # Package configuration
```

## 🌟 Core Components

### Plugin Manager

Handles plugin lifecycle, loading, and dependency management with hot-reload support.

### Event Bus

Asynchronous publish-subscribe system for loose coupling between plugins.

### Service Registry

Dependency injection container for sharing services between plugins.

### Authentication Manager

JWT-based authentication with role-based access control.

### Database Adapter

Multi-database support with connection pooling and transaction management.

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### Development Setup

```bash
# Clone repository
git clone https://github.com/dnviti/nexus-platform.git
cd nexus

# Set up development environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
poetry install --with dev,test

# Set up git hooks for quality assurance (RECOMMENDED)
python scripts/pre_push_check.py

# Verify setup
python scripts/test_ci_locally.py --fast
```

### Quality Assurance

**⚠️ IMPORTANT**: Contributors should use git hooks to ensure code quality and reduce CI failures.

**Automatic Setup (Recommended):**

```bash
python scripts/pre_push_check.py  # Sets up pre-commit hooks automatically
```

**Manual Setup:**

```bash
git config core.hooksPath .githooks
chmod +x .githooks/*
```

**What the hooks validate on each commit:**

- ✅ Code formatting (Black)
- ✅ Import sorting (isort)
- ✅ Linting (Flake8)
- ✅ Type checking (MyPy)
- ✅ Security scanning (Bandit)
- ✅ Full test suite (496 unit + 16 integration tests)
- ✅ Code coverage analysis
- ✅ Build validation

### Development Workflow

```bash
# Quick development validation
python scripts/pre_push_check.py --fast

# Make changes, then commit (triggers full validation)
git add .
git commit -m "Your meaningful commit message"

# Push after successful validation
git push
```

**Note**: Git hooks ensure every commit meets the same quality standards as our CI pipeline, significantly reducing development friction and CI failures.

See [`.githooks/README.md`](.githooks/README.md) for detailed hook documentation.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **PyPI Package**: https://pypi.org/project/nexus/
- **GitHub Repository**: https://github.com/dnviti/nexus-platform
- **Issue Tracker**: https://github.com/dnviti/nexus-platform/issues
- **Discussions**: https://github.com/dnviti/nexus-platform/discussions

## 🙏 Acknowledgments

- Built with [FastAPI](https://fastapi.tiangolo.com/)
- Powered by [SQLAlchemy](https://www.sqlalchemy.org/)
- CLI built with [Click](https://click.palletsprojects.com/)

---

**Made with ❤️ by the Nexus Team**

_Start building your next great application with Nexus today!_

