Metadata-Version: 2.4
Name: vega-framework
Version: 0.1.20
Summary: Enterprise-ready Python framework that enforces Clean Architecture for building maintainable and scalable applications.
License: MIT
License-File: LICENSE
Keywords: clean-architecture,dependency-injection,framework,python,async,vega
Author: Roberto Ferro
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: click (>=8.0,<9.0)
Requires-Dist: jinja2 (>=3.1,<4.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: pydantic-settings (>=2.0,<3.0)
Requires-Dist: toml (>=0.10,<0.11)
Project-URL: Documentation, https://vega-framework.readthedocs.io
Project-URL: Homepage, https://github.com/RobyFerro/vega-framework
Project-URL: Repository, https://github.com/RobyFerro/vega-framework
Description-Content-Type: text/markdown

# Vega Framework

An enterprise-ready Python framework that enforces Clean Architecture for building maintainable and scalable applications.

## Features

- ✅ **Automatic Dependency Injection** - Zero boilerplate, type-safe DI
- ✅ **Clean Architecture Patterns** - Interactor, Mediator, Repository, Service
- ✅ **Async/Await Support** - Full async support for CLI and web
- ✅ **Scope Management** - Singleton, Scoped, Transient lifetimes
- ✅ **Type-Safe** - Full type hints support
- ✅ **Framework-Agnostic** - Works with any domain (web, AI, IoT, fintech, etc.)
- ✅ **CLI Scaffolding** - Generate projects and components instantly
- ✅ **FastAPI Integration** - Built-in web scaffold with routing and middleware
- ✅ **SQLAlchemy Support** - Database management with async support and migrations
- ✅ **Lightweight** - No unnecessary dependencies

## Installation

```bash
pip install vega-framework
```

## Quick Start

```bash
# Create new project
vega init my-app

# Generate components
vega generate entity User
vega generate repository UserRepository
vega generate interactor CreateUser

# Create FastAPI project
vega init my-api --template fastapi
```

## CLI Commands

Vega Framework provides a comprehensive CLI for scaffolding and managing Clean Architecture projects.

### Project Management

#### `vega init` - Initialize New Project

Create a new Vega project with Clean Architecture structure.

```bash
vega init <project_name> [OPTIONS]
```

**Options:**
- `--template <type>` - Project template (default: `basic`)
  - `basic` - Standard Clean Architecture project with CLI support
  - `fastapi` - Project with FastAPI web scaffold included
  - `ai-rag` - AI/RAG application template (coming soon)
- `--path <directory>` - Parent directory for project (default: current directory)

**Examples:**
```bash
vega init my-app
vega init my-api --template fastapi
vega init my-ai --template ai-rag --path ./projects
```

**Creates:**
- `domain/` - Entities, repositories, services, interactors
- `application/` - Mediators and workflows
- `infrastructure/` - Repository and service implementations
- `presentation/` - CLI and web interfaces
- `config.py` - DI container configuration
- `settings.py` - Application settings
- `pyproject.toml` - Dependencies and project metadata

---

#### `vega doctor` - Validate Project

Validate your Vega project structure and architecture compliance.

```bash
vega doctor [--path .]
```

**Options:**
- `--path <directory>` - Project path to validate (default: current directory)

**Checks:**
- Correct folder structure
- DI container configuration
- Import dependencies
- Architecture violations

**Example:**
```bash
vega doctor
vega doctor --path ./my-app
```

---

#### `vega update` - Update Framework

Update Vega Framework to the latest version.

```bash
vega update [OPTIONS]
```

**Options:**
- `--check` - Check for updates without installing
- `--force` - Force reinstall even if up to date

**Examples:**
```bash
vega update              # Update to latest version
vega update --check      # Check for updates only
vega update --force      # Force reinstall
```

---

### Code Generation

#### `vega generate` - Generate Components

Generate Clean Architecture components in your project.

```bash
vega generate <component_type> <name> [OPTIONS]
```

**Component Types:**

##### Domain Layer

**`entity`** - Domain Entity (dataclass)
```bash
vega generate entity Product
```
Creates a domain entity in `domain/entities/`

**`repository`** - Repository Interface
```bash
vega generate repository ProductRepository
vega generate repository Product --impl memory    # With in-memory implementation
vega generate repository Product --impl sql       # With SQL implementation
```
Creates repository interface in `domain/repositories/` and optionally an implementation in `infrastructure/repositories/`

**Alias:** `repo` can be used instead of `repository`

**`service`** - Service Interface
```bash
vega generate service EmailService
vega generate service Email --impl smtp          # With SMTP implementation
```
Creates service interface in `domain/services/` and optionally an implementation in `infrastructure/services/`

**`interactor`** - Use Case / Interactor
```bash
vega generate interactor CreateProduct
vega generate interactor GetUserById
```
Creates interactor (use case) in `domain/interactors/`

##### Application Layer

**`mediator`** - Workflow / Mediator
```bash
vega generate mediator CheckoutFlow
vega generate mediator OrderProcessing
```
Creates mediator (workflow orchestrator) in `application/mediators/`

##### Infrastructure Layer

**`model`** - SQLAlchemy Model *(requires SQLAlchemy)*
```bash
vega generate model User
vega generate model ProductCategory
```
Creates SQLAlchemy model in `infrastructure/models/` and registers it in Alembic

##### Presentation Layer

**`router`** - FastAPI Router *(requires FastAPI)*
```bash
vega generate router Product
vega generate router User
```
Creates FastAPI router in `presentation/web/routes/` and auto-registers it

**`middleware`** - FastAPI Middleware *(requires FastAPI)*
```bash
vega generate middleware Logging
vega generate middleware Authentication
```
Creates FastAPI middleware in `presentation/web/middleware/` and auto-registers it

**`command`** - CLI Command
```bash
vega generate command CreateUser                 # Async command (default)
vega generate command ListUsers --impl sync      # Synchronous command
```
Creates CLI command in `presentation/cli/commands/`

The generator will prompt for:
- Command description
- Options and arguments
- Whether it will use interactors

**Options:**
- `--path <directory>` - Project root path (default: current directory)
- `--impl <type>` - Generate infrastructure implementation
  - For `repository`: `memory`, `sql`, or custom name
  - For `service`: custom implementation name
  - For `command`: `sync` or `async` (default: async)

**Examples:**
```bash
# Domain layer
vega generate entity Product
vega generate repository ProductRepository --impl memory
vega generate service EmailService --impl smtp
vega generate interactor CreateProduct

# Application layer
vega generate mediator CheckoutFlow

# Presentation layer (web)
vega generate router Product
vega generate middleware Logging

# Presentation layer (CLI)
vega generate command CreateUser
vega generate command ListUsers --impl sync

# Infrastructure layer
vega generate model User
```

---

### Feature Management

#### `vega add` - Add Features to Project

Add additional features to an existing Vega project.

```bash
vega add <feature> [OPTIONS]
```

**Features:**

**`web`** - Add FastAPI Web Scaffold
```bash
vega add web
```
Adds FastAPI web scaffold to your project:
- `presentation/web/` - Web application structure
- `presentation/web/routes/` - API routes
- `presentation/web/middleware/` - Middleware components
- `presentation/web/app.py` - FastAPI app factory

**`sqlalchemy` / `db`** - Add SQLAlchemy Database Support
```bash
vega add sqlalchemy
vega add db              # Alias
```
Adds SQLAlchemy database support:
- `infrastructure/database_manager.py` - Database connection manager
- `infrastructure/models/` - SQLAlchemy models directory
- `alembic/` - Database migration system
- `alembic.ini` - Alembic configuration

**Options:**
- `--path <directory>` - Path to Vega project (default: current directory)

**Examples:**
```bash
vega add web
vega add sqlalchemy
vega add db --path ./my-project
```

---

### Database Management

#### `vega migrate` - Database Migration Commands

Manage database schema migrations with Alembic *(requires SQLAlchemy)*.

**`init`** - Initialize Database
```bash
vega migrate init
```
Creates all database tables based on current models. Use this for initial setup.

**`create`** - Create New Migration
```bash
vega migrate create -m "migration message"
```
Generates a new migration file by auto-detecting model changes.

**Options:**
- `-m, --message <text>` - Migration description (required)

**`upgrade`** - Apply Migrations
```bash
vega migrate upgrade [--revision head]
```
Apply pending migrations to the database.

**Options:**
- `--revision <id>` - Target revision (default: `head` - latest)

**`downgrade`** - Rollback Migrations
```bash
vega migrate downgrade [--revision -1]
```
Rollback database migrations.

**Options:**
- `--revision <id>` - Target revision (default: `-1` - previous)

**`current`** - Show Current Revision
```bash
vega migrate current
```
Display the current database migration revision.

**`history`** - Show Migration History
```bash
vega migrate history
```
Display complete migration history with details.

**Examples:**
```bash
# Initialize database
vega migrate init

# Create migration after changing models
vega migrate create -m "Add user table"
vega migrate create -m "Add email field to users"

# Apply all pending migrations
vega migrate upgrade

# Apply migrations up to specific revision
vega migrate upgrade --revision abc123

# Rollback last migration
vega migrate downgrade

# Rollback to specific revision
vega migrate downgrade --revision xyz789

# Check current status
vega migrate current

# View history
vega migrate history
```

---

### Getting Help

**Show Version:**
```bash
vega --version
```

**Show Help:**
```bash
vega --help                    # Main help
vega <command> --help          # Command-specific help
vega generate --help           # Generate command help
vega migrate --help            # Migrate command help
```

**Examples:**
```bash
vega init --help
vega generate --help
vega add --help
vega migrate upgrade --help
```

## Async CLI Commands

Vega provides seamless async/await support in CLI commands, allowing you to execute interactors directly.

### Generate a CLI Command

```bash
# Generate an async command (default)
vega generate command CreateUser

# Generate a synchronous command
vega generate command ListUsers --impl sync
```

The generator will prompt you for:
- Command description
- Options and arguments
- Whether it will use interactors

### Manual Command Example

```python
import click
from vega.cli.utils import async_command

@click.command()
@click.option('--name', required=True)
@async_command
async def create_user(name: str):
    """Create a user using an interactor"""
    import config  # Initialize DI container
    from domain.interactors.create_user import CreateUser

    user = await CreateUser(name=name)
    click.echo(f"Created: {user.name}")
```

This enables the same async business logic to work in both CLI and web (FastAPI) contexts.

## Use Cases

Perfect for:

- AI/RAG applications
- E-commerce platforms
- Fintech systems
- Mobile backends
- Microservices
- CLI tools
- Any Python application requiring clean architecture

## License

MIT

## Contributing

Contributions welcome! This framework is extracted from production code and battle-tested.

