create-ailab 0.1.0__py3-none-any.whl

create_ai/__init__.py

@@ -0,0 +1,13 @@
+"""create-ai: the Vite-style project scaffolder for AI/ML engineering.
+
+The public surface is intentionally small.  Most consumers only need
+:data:`__version__` and the CLI entrypoint in :mod:`create_ai.cli.app`.
+Programmatic users can build a :class:`~create_ai.core.configuration.ProjectConfig`
+and hand it to :class:`~create_ai.core.generator.GenerationEngine`.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

create_ai/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m create_ai`` as an alias for the ``create-ai`` command."""
+
+from __future__ import annotations
+
+from create_ai.cli.app import app
+
+if __name__ == "__main__":  # pragma: no cover - thin shim
+    app()

create_ai/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface - a thin adapter over :mod:`create_ai.core`."""

create_ai/cli/app.py

@@ -0,0 +1,82 @@
+"""Typer application wiring.
+
+``create-ai`` behaves like ``npm create vite``:
+
+* ``create-ai``                 -> interactive project creation
+* ``create-ai my-project``      -> ``create-ai new my-project``
+* ``create-ai new my-project``  -> same, explicit
+* ``create-ai doctor`` / ``list`` / ``add``
+
+The "bare name is really ``new``" behaviour is a tiny ``TyperGroup`` subclass
+that rewrites the argument list *before* command resolution, so there is exactly
+one implementation of project creation and no dependency on click internals.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from typer.core import TyperGroup
+
+from create_ai import __version__
+from create_ai.cli.commands.add import add
+from create_ai.cli.commands.doctor import doctor
+from create_ai.cli.commands.list_types import list_types
+from create_ai.cli.commands.new import new, run_default
+
+_DEFAULT_COMMAND = "new"
+
+
+class DefaultCommandGroup(TyperGroup):
+    """Route an unknown first token to ``new`` (so ``create-ai <name>`` works)."""
+
+    def resolve_command(self, ctx: Any, args: list[str]) -> Any:
+        if args and not args[0].startswith("-") and args[0] not in self.commands:
+            args = [_DEFAULT_COMMAND, *args]
+        return super().resolve_command(ctx, args)
+
+
+app = typer.Typer(
+    cls=DefaultCommandGroup,
+    add_completion=False,
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    help="Scaffold production-ready AI/ML projects - the Vite experience for AI.",
+)
+
+app.command("new")(new)
+app.command("doctor")(doctor)
+app.command("list")(list_types)
+app.command("add")(add)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"create-ai {__version__}")
+        raise typer.Exit
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the create-ai version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    if ctx.invoked_subcommand is None:
+        # Bare `create-ai` -> interactive `new` (with all-default arguments).
+        run_default()
+
+
+def main() -> None:  # pragma: no cover - console-script shim
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

create_ai/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Sub-command implementations for the ``create-ai`` CLI."""

create_ai/cli/commands/add.py

@@ -0,0 +1,28 @@
+"""``create-ai add`` - placeholder for the v0.2 "extend an existing project" flow.
+
+The command exists now so the CLI surface is stable and discoverable; the
+implementation lands with the plugin architecture in v0.2.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from create_ai.cli.console import console
+
+
+def add(
+    component: str | None = typer.Argument(
+        None, help="Component to add (e.g. mlflow, docker, robotics)."
+    ),
+) -> None:
+    """Add a component to an existing project (coming in v0.2)."""
+
+    console.print(
+        "[yellow]`create-ai add` is planned for v0.2.[/yellow]\n"
+        "It will layer integrations (MLflow, Docker, W&B) and new domains "
+        "(Robotics, ROS 2, RL) onto an existing project."
+    )
+    if component:
+        console.print(f"[dim]Requested component: {component}[/dim]")
+    raise typer.Exit(code=0)

create_ai/cli/commands/doctor.py

@@ -0,0 +1,62 @@
+"""``create-ai doctor`` - report on the external tools create-ai can use."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from create_ai.cli.console import console
+from create_ai.integrations import docker as docker_integration
+from create_ai.integrations import git as git_integration
+from create_ai.integrations import python as python_integration
+from create_ai.utils.shell import tool_version
+
+
+@dataclass(frozen=True)
+class Check:
+    """One environment probe.  ``probe`` returns a version string or ``None``."""
+
+    label: str
+    probe: Callable[[], str | None]
+    required: bool = False
+
+
+# Ordered; add new probes here - the command body never changes.
+CHECKS: tuple[Check, ...] = (
+    Check("Python", lambda: python_integration.current_version(), required=True),
+    Check("Git", git_integration.version),
+    Check("uv", lambda: tool_version("uv")),
+    Check("Docker", docker_integration.version),
+)
+
+
+def _clean(value: str, label: str) -> str:
+    """Trim a redundant leading ``"<tool> version"`` from a version string."""
+
+    text = value.strip()
+    for prefix in (f"{label.lower()} version", label.lower(), "version"):
+        if text.lower().startswith(prefix):
+            text = text[len(prefix) :].strip()
+    return text or "(version unknown)"
+
+
+def doctor() -> None:
+    """Check for Python, Git, uv and Docker and print a short report."""
+
+    console.print("[bold]create-ai doctor[/bold]\n")
+    missing_required = False
+    for check in CHECKS:
+        version = check.probe()
+        if version:
+            console.print(f"[green]✔[/green] {check.label} {_clean(version, check.label)}")
+        elif check.required:
+            missing_required = True
+            console.print(f"[red]✗[/red] {check.label} not found (required)")
+        else:
+            console.print(f"[dim]○ {check.label} not installed[/dim]")
+
+    console.print()
+    if missing_required:
+        console.print("[red]Some required tools are missing.[/red]")
+        raise SystemExit(1)
+    console.print("[green]All required tools are available.[/green]")

create_ai/cli/commands/list_types.py

@@ -0,0 +1,28 @@
+"""``create-ai list`` - show the registered project types."""
+
+from __future__ import annotations
+
+from rich.table import Table
+
+from create_ai.cli.console import console
+from create_ai.generators import generator_registry
+
+
+def list_types() -> None:
+    """List every project type create-ai can scaffold."""
+
+    table = Table(title="Available project types", title_justify="left")
+    table.add_column("key", style="bold cyan")
+    table.add_column("name")
+    table.add_column("frameworks", style="dim")
+    table.add_column("description")
+
+    for key, generator_cls in generator_registry.items():
+        frameworks = ", ".join(sorted(f.value for f in generator_cls.supported_frameworks))
+        table.add_row(
+            key,
+            generator_cls.project_type.label,
+            frameworks,
+            generator_cls.summary,
+        )
+    console.print(table)

create_ai/cli/commands/new.py

@@ -0,0 +1,346 @@
+"""``create-ai new`` - create a project (also the default, bare ``create-ai``)."""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import TypeVar
+
+import typer
+from rich.panel import Panel
+
+from create_ai.cli.console import console, err_console, print_error, summary_table
+from create_ai.cli.prompts import run_questionnaire, stdin_is_interactive
+from create_ai.cli.reporters import RichReporter
+from create_ai.core.configuration import (
+    DEFAULT_PYTHON_VERSION,
+    EnvironmentManager,
+    ExperimentTracking,
+    Framework,
+    Linting,
+    ProjectConfig,
+    ProjectType,
+    Testing,
+)
+from create_ai.core.generator import GenerationEngine, GenerationResult
+from create_ai.core.project import Project
+from create_ai.core.validation import validate_config
+from create_ai.errors import CreateAIError
+from create_ai.generators import generator_registry
+from create_ai.integrations import resolve_environment_manager
+from create_ai.utils.filesystem import is_empty_dir
+from create_ai.utils.validation import resolve_destination
+
+_E = TypeVar("_E", bound=Enum)
+
+
+def _coerce(enum_cls: type[_E], value: str, flag: str) -> _E:
+    try:
+        return enum_cls(value)
+    except ValueError:
+        allowed = ", ".join(m.value for m in enum_cls)
+        raise CreateAIError(
+            f"Invalid value {value!r} for {flag}.", hint=f"Choose one of: {allowed}."
+        ) from None
+
+
+def _config_from_flags(
+    *,
+    name: str,
+    project_type: str | None,
+    python_version: str | None,
+    framework: str | None,
+    manager: str | None,
+    testing: str | None,
+    linting: str | None,
+    tracking: str | None,
+    docker: bool | None,
+    jupyter: bool | None,
+    git: bool | None,
+) -> ProjectConfig:
+    ptype = _coerce(ProjectType, project_type or ProjectType.MACHINE_LEARNING.value, "--type")
+    if project_type is None:
+        console.print("[dim]No --type given; defaulting to Machine Learning.[/dim]")
+    fw_value = framework or generator_registry.get(ptype.value).default_framework.value
+    return ProjectConfig(
+        name=name,
+        project_type=ptype,
+        python_version=python_version or DEFAULT_PYTHON_VERSION,
+        framework=_coerce(Framework, fw_value, "--framework"),
+        environment_manager=_coerce(EnvironmentManager, manager or "uv", "--manager"),
+        testing=_coerce(Testing, testing or "pytest", "--testing"),
+        linting=_coerce(Linting, linting or "ruff", "--linting"),
+        experiment_tracking=_coerce(ExperimentTracking, tracking or "none", "--tracking"),
+        docker=False if docker is None else docker,
+        jupyter=False if jupyter is None else jupyter,
+        git=True if git is None else git,
+    )
+
+
+def _resolve_existing_directory(config: ProjectConfig, parent: Path) -> tuple[Path, ProjectConfig]:
+    """Interactively deal with a non-empty target directory (never deletes)."""
+
+    import questionary
+
+    while True:
+        destination, _ = resolve_destination(config.name, parent=parent)
+        if is_empty_dir(destination):
+            return destination, config
+        choice = questionary.select(
+            f'Directory "{destination}" already exists and is not empty.',
+            choices=["Cancel", "Choose another name"],
+            qmark="?",
+        ).ask()
+        if choice != "Choose another name":
+            raise CreateAIError("Cancelled - existing directory left untouched.")
+        new_name = questionary.text("New project name:", qmark="?").ask()
+        if not new_name:
+            raise CreateAIError("Cancelled.")
+        config = config.model_copy(update={"name": new_name.strip()})
+
+
+def _print_next_steps(result: GenerationResult, *, installed: bool, dry_run: bool) -> None:
+    project = result.project
+    lines: list[str] = []
+    rel = project.destination.name
+    lines.append(f"  cd {rel}")
+    if installed:
+        manager = resolve_environment_manager(project.destination, project.config)
+        lines.append(f"  {manager.activation_hint()}")
+    else:
+        setup = (
+            "uv sync"
+            if project.config.environment_manager is EnvironmentManager.UV
+            else ("python -m venv .venv && source .venv/bin/activate && pip install -e .")
+        )
+        lines.append(f"  {setup}")
+    entry = project.generator.entrypoints[0]
+    lines.append(f"  {project.config.run_prefix}python {entry}")
+
+    if result.warnings:
+        for warning in result.warnings:
+            console.print(f"[yellow]![/yellow] {warning}")
+
+    header = (
+        "[bold]Dry run complete[/bold] - no files were written."
+        if dry_run
+        else "[bold green]🎉 Project created successfully![/bold green]"
+    )
+    body = "\n".join([header, "", "Next steps:", *lines])
+    console.print()
+    console.print(Panel(body, border_style="green", expand=False))
+
+
+def _run(
+    name: str | None,
+    *,
+    project_type: str | None,
+    python_version: str | None,
+    framework: str | None,
+    manager: str | None,
+    testing: str | None,
+    linting: str | None,
+    tracking: str | None,
+    docker: bool | None,
+    jupyter: bool | None,
+    git: bool | None,
+    yes: bool,
+    install: bool,
+    force: bool,
+    dry_run: bool,
+    output_dir: Path | None,
+) -> None:
+    parent = (output_dir or Path.cwd()).resolve()
+    interactive = not yes and stdin_is_interactive()
+
+    if interactive and _needs_prompt(name, project_type):
+        config = run_questionnaire(
+            name=name,
+            project_type=project_type,
+            python_version=python_version,
+            framework=framework,
+            environment_manager=manager,
+            testing=testing,
+            linting=linting,
+            experiment_tracking=tracking,
+            docker=docker,
+            jupyter=jupyter,
+            git=git,
+        )
+    else:
+        if name is None:
+            raise CreateAIError(
+                "A project name is required.",
+                hint="Run `create-ai <name> --type <type>` or use interactive mode.",
+            )
+        config = _config_from_flags(
+            name=name,
+            project_type=project_type,
+            python_version=python_version,
+            framework=framework,
+            manager=manager,
+            testing=testing,
+            linting=linting,
+            tracking=tracking,
+            docker=docker,
+            jupyter=jupyter,
+            git=git,
+        )
+
+    validate_config(config)
+
+    if interactive:
+        destination, config = _resolve_existing_directory(config, parent)
+    else:
+        destination, _ = resolve_destination(config.name, parent=parent)
+
+    project = Project.build(config, destination=destination)
+
+    if interactive and not yes:
+        console.print()
+        plan = Panel(summary_table(config.summary_rows()), title="Project plan", expand=False)
+        console.print(plan)
+        import questionary
+
+        if not questionary.confirm("Create this project?", default=True, qmark="?").ask():
+            raise CreateAIError("Cancelled.")
+        console.print()
+
+    engine = GenerationEngine(
+        project,
+        reporter=RichReporter(console),
+        install=install and not dry_run,
+        init_git=config.git,
+        force=force,
+        dry_run=dry_run,
+    )
+    result = engine.run()
+    _print_next_steps(
+        result,
+        installed=install and not dry_run and _env_created(result),
+        dry_run=dry_run,
+    )
+
+
+def _env_created(result: GenerationResult) -> bool:
+    return any(
+        title == "Creating environment" and outcome.ok and not outcome.skipped
+        for title, outcome in result.steps
+    )
+
+
+def _needs_prompt(name: str | None, project_type: str | None) -> bool:
+    return name is None or project_type is None
+
+
+def _guarded(
+    name: str | None,
+    *,
+    project_type: str | None = None,
+    python_version: str | None = None,
+    framework: str | None = None,
+    manager: str | None = None,
+    testing: str | None = None,
+    linting: str | None = None,
+    tracking: str | None = None,
+    docker: bool | None = None,
+    jupyter: bool | None = None,
+    git: bool | None = None,
+    yes: bool = False,
+    install: bool = True,
+    force: bool = False,
+    dry_run: bool = False,
+    output_dir: Path | None = None,
+    debug: bool = False,
+) -> None:
+    """Run the create flow, converting expected errors into a clean exit."""
+
+    try:
+        _run(
+            name,
+            project_type=project_type,
+            python_version=python_version,
+            framework=framework,
+            manager=manager,
+            testing=testing,
+            linting=linting,
+            tracking=tracking,
+            docker=docker,
+            jupyter=jupyter,
+            git=git,
+            yes=yes,
+            install=install,
+            force=force,
+            dry_run=dry_run,
+            output_dir=output_dir,
+        )
+    except CreateAIError as exc:
+        print_error(exc)
+        raise typer.Exit(code=1) from None
+    except typer.Exit:
+        raise
+    except Exception as exc:  # pragma: no cover - safety net
+        if debug:
+            raise
+        err_console.print(
+            f"[red]✗ unexpected error:[/red] {exc}\n[dim]Re-run with --debug for a traceback.[/dim]"
+        )
+        raise typer.Exit(code=1) from None
+
+
+def run_default() -> None:
+    """Entry point for bare ``create-ai`` (no subcommand): interactive creation."""
+
+    _guarded(None)
+
+
+def new(
+    name: str | None = typer.Argument(None, help="Project name / directory to create."),
+    project_type: str | None = typer.Option(
+        None, "--type", "-t", help="ml | deep-learning | llm | computer-vision"
+    ),
+    python_version: str | None = typer.Option(None, "--python", help="CPython version, e.g. 3.12"),
+    framework: str | None = typer.Option(
+        None, "--framework", "-f", help="pytorch | tensorflow | sklearn | none"
+    ),
+    manager: str | None = typer.Option(None, "--manager", "-m", help="uv | venv"),
+    testing: str | None = typer.Option(None, "--testing", help="pytest | none"),
+    linting: str | None = typer.Option(None, "--linting", help="ruff | ruff+black | none"),
+    tracking: str | None = typer.Option(None, "--tracking", help="mlflow | wandb | none"),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker", help="Generate Docker files."),
+    jupyter: bool | None = typer.Option(
+        None, "--jupyter/--no-jupyter", help="Add notebooks/ and Jupyter deps."
+    ),
+    git: bool | None = typer.Option(None, "--git/--no-git", help="Run git init."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip prompts; accept defaults."),
+    install: bool = typer.Option(
+        True, "--install/--no-install", help="Create the environment and install deps."
+    ),
+    force: bool = typer.Option(False, "--force", help="Allow writing into a non-empty directory."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Report actions without writing files."),
+    output_dir: Path | None = typer.Option(
+        None, "--output-dir", "-o", help="Parent directory for the new project."
+    ),
+    debug: bool = typer.Option(False, "--debug", help="Show full tracebacks on error."),
+) -> None:
+    """Scaffold a new AI/ML project."""
+
+    _guarded(
+        name,
+        project_type=project_type,
+        python_version=python_version,
+        framework=framework,
+        manager=manager,
+        testing=testing,
+        linting=linting,
+        tracking=tracking,
+        docker=docker,
+        jupyter=jupyter,
+        git=git,
+        yes=yes,
+        install=install,
+        force=force,
+        dry_run=dry_run,
+        output_dir=output_dir,
+        debug=debug,
+    )

create_ai/cli/console.py

@@ -0,0 +1,36 @@
+"""Shared Rich consoles and small rendering helpers.
+
+Kept deliberately spare: a couple of consoles, an error panel, a key/value
+table.  No animations, no banners bigger than a single line.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from create_ai.errors import CreateAIError
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def print_error(exc: CreateAIError) -> None:
+    """Render a typed error as a compact red panel with an optional hint."""
+
+    body = Text(exc.message)
+    if exc.hint:
+        body.append("\n\n")
+        body.append(exc.hint, style="dim")
+    err_console.print(Panel(body, title="[bold red]✗ error", border_style="red", expand=False))
+
+
+def summary_table(rows: list[tuple[str, str]], *, title: str | None = None) -> Table:
+    table = Table(show_header=False, box=None, pad_edge=False, title=title)
+    table.add_column(style="dim")
+    table.add_column(style="bold")
+    for label, value in rows:
+        table.add_row(label, value)
+    return table