vega-framework 0.1.0__tar.gz

vega_framework-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vega Framework Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vega_framework-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.3
+Name: vega-framework
+Version: 0.1.0
+Summary: Lightweight Python framework for Clean Architecture with automatic dependency injection
+License: MIT
+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: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: click (>=8.0,<9.0)
+Requires-Dist: pydantic (>=2.0,<3.0)
+Requires-Dist: pydantic-settings (>=2.0,<3.0)
+Project-URL: Documentation, https://vega-framework.readthedocs.io
+Project-URL: Homepage, https://github.com/your-org/vega-framework
+Project-URL: Repository, https://github.com/your-org/vega-framework
+Description-Content-Type: text/markdown
+
+# Vega Framework
+
+A lightweight Python framework for building applications with **Clean Architecture** principles.
+
+## Features
+
+- ✅ **Automatic Dependency Injection** - Zero boilerplate, type-safe DI
+- ✅ **Clean Architecture Patterns** - Interactor, Mediator, Repository, Service
+- ✅ **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
+- ✅ **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
+
+### Initialize Project
+
+```bash
+vega init <project_name> [--template basic|fastapi|ai-rag] [--path .]
+```
+
+Creates a new Vega project with Clean Architecture structure:
+
+- `domain/` - Entities, repositories, services, interactors
+- `application/` - Mediators and workflows
+- `infrastructure/` - Repository and service implementations
+- `config.py` - DI container setup
+- `settings.py` - Application configuration
+
+### Generate Components
+
+```bash
+vega generate entity <Name>
+vega generate repository <Name> [--impl memory|sql]
+vega generate service <Name>
+vega generate interactor <Name>
+vega generate mediator <Name>
+vega generate web fastapi
+```
+
+### Validate Project
+
+```bash
+vega doctor [--path .]
+```
+
+Validates project structure, DI configuration, and architecture compliance.
+
+## 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.
+

vega_framework-0.1.0/README.md

@@ -0,0 +1,89 @@
+# Vega Framework
+
+A lightweight Python framework for building applications with **Clean Architecture** principles.
+
+## Features
+
+- ✅ **Automatic Dependency Injection** - Zero boilerplate, type-safe DI
+- ✅ **Clean Architecture Patterns** - Interactor, Mediator, Repository, Service
+- ✅ **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
+- ✅ **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
+
+### Initialize Project
+
+```bash
+vega init <project_name> [--template basic|fastapi|ai-rag] [--path .]
+```
+
+Creates a new Vega project with Clean Architecture structure:
+
+- `domain/` - Entities, repositories, services, interactors
+- `application/` - Mediators and workflows
+- `infrastructure/` - Repository and service implementations
+- `config.py` - DI container setup
+- `settings.py` - Application configuration
+
+### Generate Components
+
+```bash
+vega generate entity <Name>
+vega generate repository <Name> [--impl memory|sql]
+vega generate service <Name>
+vega generate interactor <Name>
+vega generate mediator <Name>
+vega generate web fastapi
+```
+
+### Validate Project
+
+```bash
+vega doctor [--path .]
+```
+
+Validates project structure, DI configuration, and architecture compliance.
+
+## 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.

vega_framework-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[tool.poetry]
+name = "vega-framework"
+version = "0.1.0"
+description = "Lightweight Python framework for Clean Architecture with automatic dependency injection"
+authors = ["Roberto Ferro"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/your-org/vega-framework"
+repository = "https://github.com/your-org/vega-framework"
+documentation = "https://vega-framework.readthedocs.io"
+keywords = [
+    "clean-architecture",
+    "dependency-injection",
+    "framework",
+    "python",
+    "async",
+    "vega",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+packages = [{ include = "vega", from = "." }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+pydantic = "^2.0"
+pydantic-settings = "^2.0"
+click = "^8.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.0"
+pytest-asyncio = "^0.21"
+pytest-cov = "^4.0"
+black = "^23.0"
+isort = "^5.0"
+mypy = "^1.0"
+ruff = "^0.1"
+
+[tool.poetry.scripts]
+vega = "vega.cli.main:cli"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 100
+target-version = ['py310']
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

vega_framework-0.1.0/vega/__init__.py

@@ -0,0 +1,43 @@
+"""
+CleanArch Framework
+
+A lightweight Python framework for building applications with Clean Architecture.
+
+Features:
+- Automatic Dependency Injection
+- Clean Architecture patterns (Interactor, Mediator, Repository)
+- Type-safe with Python type hints
+- Scoped dependency management (Singleton, Scoped, Transient)
+- CLI scaffolding tools
+
+Example:
+    from vega.patterns import Interactor
+    from vega.di import bind
+
+    class CreateUser(Interactor[User]):
+        def __init__(self, name: str, email: str):
+            self.name = name
+            self.email = email
+
+        @bind
+        async def call(self, repository: UserRepository) -> User:
+            user = User(name=self.name, email=self.email)
+            return await repository.save(user)
+"""
+
+__version__ = "0.1.0"
+__author__ = "CleanArch Contributors"
+
+from vega.di import bind, injectable, Scope, scope_context
+from vega.patterns import Interactor, Mediator, Repository, Service
+
+__all__ = [
+    "bind",
+    "injectable",
+    "Scope",
+    "scope_context",
+    "Interactor",
+    "Mediator",
+    "Repository",
+    "Service",
+]

vega_framework-0.1.0/vega/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Vega Framework CLI tools"""
+
+from vega.cli.main import cli
+
+__all__ = ["cli"]

vega_framework-0.1.0/vega/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands"""

vega_framework-0.1.0/vega/cli/commands/generate.py

@@ -0,0 +1,337 @@
+"""Generate command - Create components in Vega project"""
+import click
+import re
+from pathlib import Path
+
+from vega.cli.templates import (
+    render_entity,
+    render_infrastructure_repository,
+    render_infrastructure_service,
+    render_interactor,
+    render_mediator,
+    render_repository_interface,
+    render_service_interface,
+)
+from vega.cli.scaffolds import create_fastapi_scaffold
+
+
+
+def to_snake_case(name: str) -> str:
+    """Convert CamelCase to snake_case"""
+    name = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
+    return re.sub('([a-z0-9])([A-Z])', r'\1_\2', name).lower()
+
+
+def to_pascal_case(name: str) -> str:
+    """Convert strings to PascalCase, handling separators and camelCase input"""
+    cleaned = name.strip()
+    if not cleaned:
+        return ""
+
+    # Normalize common separators to spaces
+    normalized = cleaned.replace('-', ' ').replace('_', ' ')
+    if ' ' in normalized:
+        parts = normalized.split()
+    else:
+        parts = re.findall(r'[A-Z]+(?=$|[A-Z][a-z0-9])|[A-Z]?[a-z0-9]+|[0-9]+', cleaned)
+        if not parts:
+            parts = [cleaned]
+
+    def _pascal_piece(piece: str) -> str:
+        return piece if piece.isupper() else piece[:1].upper() + piece[1:].lower()
+
+    return ''.join(_pascal_piece(part) for part in parts if part)
+
+
+def _resolve_implementation_names(class_name: str, implementation: str) -> tuple[str, str]:
+    """Derive implementation class and file names from flag input."""
+    impl_pascal = to_pascal_case(implementation) or "Impl"
+    base = class_name
+
+    if impl_pascal.lower() in {"impl", "implementation"}:
+        impl_class = f"{base}{impl_pascal}"
+    elif base.lower().startswith(impl_pascal.lower()):
+        impl_class = base
+    else:
+        impl_class = f"{impl_pascal}{base}"
+
+    impl_file = to_snake_case(impl_class)
+    return impl_class, impl_file
+
+
+def generate_component(
+    component_type: str,
+    name: str,
+    project_path: str,
+    implementation: str | None = None,
+):
+    """Generate a component in the Vega project"""
+
+    project_root = Path(project_path).resolve()
+
+    # Check if we're in a Vega project
+    if not (project_root / "config.py").exists():
+        click.echo(click.style("ERROR: Error: Not a Vega project (config.py not found)", fg='red'))
+        click.echo("   Run this command from your project root, or use --path option")
+        return
+
+    # Get project name from directory
+    project_name = project_root.name
+
+    class_name = to_pascal_case(name)
+    implementation = implementation.strip() if implementation else None
+    if component_type == "web":
+        _generate_fastapi_web(project_root, project_name, name)
+        return
+
+
+    suffixes = {
+        "repository": "Repository",
+        "service": "Service",
+        "mediator": "Mediator",
+    }
+
+    if implementation and component_type not in {'repository', 'service'}:
+        click.echo(
+            click.style(
+                "WARNING: Implementation option is only supported for repositories and services",
+                fg='yellow',
+            )
+        )
+        implementation = None
+
+    if component_type in suffixes:
+        suffix = suffixes[component_type]
+        if class_name.lower().endswith(suffix.lower()):
+            class_name = f"{class_name[:-len(suffix)]}{suffix}"
+        else:
+            class_name = f"{class_name}{suffix}"
+
+    file_name = to_snake_case(class_name)
+
+    if component_type == 'entity':
+        _generate_entity(project_root, project_name, class_name, file_name)
+    elif component_type == 'repository':
+        _generate_repository(project_root, project_name, class_name, file_name, implementation)
+    elif component_type == 'service':
+        _generate_service(project_root, project_name, class_name, file_name, implementation)
+    elif component_type == 'interactor':
+        _generate_interactor(project_root, project_name, class_name, file_name)
+    elif component_type == 'mediator':
+        _generate_mediator(project_root, project_name, class_name, file_name)
+
+
+def _generate_entity(project_root: Path, project_name: str, class_name: str, file_name: str):
+    """Generate domain entity"""
+
+    file_path = project_root / "domain" / "entities" / f"{file_name}.py"
+
+    if file_path.exists():
+        click.echo(click.style(f"ERROR: Error: {file_path} already exists", fg='red'))
+        return
+
+    content = render_entity(class_name)
+
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+
+def _generate_repository(
+    project_root: Path,
+    project_name: str,
+    class_name: str,
+    file_name: str,
+    implementation: str | None = None,
+):
+    """Generate repository interface"""
+
+    # Remove 'Repository' suffix if present to get entity name
+    entity_name = class_name[:-len('Repository')] if class_name.endswith('Repository') else class_name
+    entity_file = to_snake_case(entity_name)
+
+    file_path = project_root / "domain" / "repositories" / f"{file_name}.py"
+
+    if file_path.exists():
+        click.echo(click.style(f"ERROR: Error: {file_path} already exists", fg='red'))
+        return
+
+    # Check if entity exists
+    entity_path = project_root / "domain" / "entities" / f"{entity_file}.py"
+    if not entity_path.exists():
+        click.echo(
+            click.style(
+                f"⚠️  Warning: Entity {entity_name} does not exist at {entity_path.relative_to(project_root)}",
+                fg='yellow',
+            )
+        )
+
+        if click.confirm(f"Do you want to create the entity {entity_name}?", default=True):
+            _generate_entity(project_root, project_name, entity_name, entity_file)
+            click.echo()  # Empty line for readability
+        else:
+            click.echo(click.style(f"ERROR: Cannot create repository without entity {entity_name}", fg='red'))
+            return
+
+    content = render_repository_interface(class_name, entity_name, entity_file)
+
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+    # Suggest next steps
+    click.echo(f"\n💡 Next steps:")
+    click.echo(f"   1. Create entity: vega generate entity {entity_name}")
+    click.echo(f"   2. Implement repository in infrastructure/repositories/")
+    click.echo(f"   3. Register in config.py SERVICES dict")
+
+    if implementation:
+        _generate_infrastructure_repository(
+            project_root,
+            class_name,
+            file_name,
+            entity_name,
+            entity_file,
+            implementation,
+        )
+
+
+def _generate_service(
+    project_root: Path,
+    project_name: str,
+    class_name: str,
+    file_name: str,
+    implementation: str | None = None,
+):
+    """Generate service interface"""
+
+    file_path = project_root / "domain" / "services" / f"{file_name}.py"
+
+    if file_path.exists():
+        click.echo(click.style(f"ERROR: Error: {file_path} already exists", fg='red'))
+        return
+
+    content = render_service_interface(class_name)
+
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+    click.echo(f"\n💡 Next steps:")
+    click.echo(f"   1. Implement service in infrastructure/services/")
+    click.echo(f"   2. Register in config.py SERVICES dict")
+
+    if implementation:
+        _generate_infrastructure_service(
+            project_root,
+            class_name,
+            file_name,
+            implementation,
+        )
+
+
+def _generate_interactor(project_root: Path, project_name: str, class_name: str, file_name: str):
+    """Generate interactor (use case)"""
+
+    # Try to infer entity from name (e.g., CreateUser -> User)
+    entity_name = class_name
+    for prefix in ['Create', 'Update', 'Delete', 'Get', 'List', 'Find']:
+        if class_name.startswith(prefix):
+            entity_name = class_name[len(prefix):]
+            break
+
+    entity_file = to_snake_case(entity_name)
+
+    file_path = project_root / "domain" / "interactors" / f"{file_name}.py"
+
+    if file_path.exists():
+        click.echo(click.style(f"ERROR: Error: {file_path} already exists", fg='red'))
+        return
+
+    content = render_interactor(class_name, entity_name, entity_file)
+
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+    click.echo(f"\n💡 Usage:")
+    click.echo(f"   result = await {class_name}(param=value)")
+
+
+def _generate_mediator(project_root: Path, project_name: str, class_name: str, file_name: str):
+    """Generate mediator (workflow)"""
+
+    file_path = project_root / "application" / "mediators" / f"{file_name}.py"
+
+    if file_path.exists():
+        click.echo(click.style(f"ERROR: Error: {file_path} already exists", fg='red'))
+        return
+
+    content = render_mediator(class_name)
+
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+    click.echo(f"\n💡 Usage:")
+    click.echo(f"   result = await {class_name}(param=value)")
+
+
+def _generate_infrastructure_repository(
+    project_root: Path,
+    interface_class_name: str,
+    interface_file_name: str,
+    entity_name: str,
+    entity_file: str,
+    implementation: str,
+) -> None:
+    """Generate infrastructure repository implementation extending the domain interface."""
+    impl_class, impl_file = _resolve_implementation_names(interface_class_name, implementation)
+    file_path = project_root / "infrastructure" / "repositories" / f"{impl_file}.py"
+
+    if file_path.exists():
+        click.echo(click.style(f"WARNING: Implementation {file_path} already exists", fg='yellow'))
+        return
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    content = render_infrastructure_repository(
+        impl_class,
+        interface_class_name,
+        interface_file_name,
+        entity_name,
+        entity_file,
+    )
+
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+
+def _generate_infrastructure_service(
+    project_root: Path,
+    interface_class_name: str,
+    interface_file_name: str,
+    implementation: str,
+) -> None:
+    """Generate infrastructure service implementation extending the domain interface."""
+    impl_class, impl_file = _resolve_implementation_names(interface_class_name, implementation)
+    file_path = project_root / "infrastructure" / "services" / f"{impl_file}.py"
+
+    if file_path.exists():
+        click.echo(click.style(f"WARNING: Implementation {file_path} already exists", fg='yellow'))
+        return
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    content = render_infrastructure_service(
+        impl_class,
+        interface_class_name,
+        interface_file_name,
+    )
+
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+def _generate_fastapi_web(project_root: Path, project_name: str, name: str) -> None:
+    """Generate FastAPI web scaffold"""
+    if name.lower() not in {"fastapi", "fast-api"}:
+        click.echo(click.style("ERROR: Unsupported web scaffold. Use: vega generate web fastapi", fg='red'))
+        return
+
+    create_fastapi_scaffold(project_root, project_name)
+