augint-shell 0.1.0__py3-none-any.whl

ai_shell/__init__.py

@@ -0,0 +1,7 @@
+"""augint-shell (ai-shell) - Launch AI coding tools and local LLMs in Docker containers."""
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+]

ai_shell/cli/__main__.py

@@ -0,0 +1,46 @@
+"""ai-shell CLI entry point."""
+
+import sys
+
+import click
+
+from ai_shell import __version__
+from ai_shell.cli.commands.llm import llm_group
+from ai_shell.cli.commands.manage import manage_group
+from ai_shell.cli.commands.tools import aider, claude, claude_x, codex, opencode, shell
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="ai-shell")
+@click.option("--project", default=None, help="Override project name for container naming.")
+@click.pass_context
+def cli(ctx, project):
+    """AI Shell - Launch AI coding tools and local LLMs in Docker containers."""
+    ctx.ensure_object(dict)
+    ctx.obj["project"] = project
+
+
+# Tool subcommands
+cli.add_command(claude)
+cli.add_command(claude_x, "claude-x")
+cli.add_command(codex)
+cli.add_command(opencode)
+cli.add_command(aider)
+cli.add_command(shell)
+
+# Command groups
+cli.add_command(llm_group, "llm")
+cli.add_command(manage_group, "manage")
+
+
+def main():
+    """Main entry point."""
+    try:
+        cli()
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ai_shell/cli/commands/llm.py

@@ -0,0 +1,204 @@
+"""LLM stack management commands: up, down, pull, setup, status, logs, shell."""
+
+import time
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ai_shell.config import load_config
+from ai_shell.container import ContainerManager
+from ai_shell.defaults import OLLAMA_CONTAINER, WEBUI_CONTAINER
+
+console = Console(stderr=True)
+
+
+def _get_manager(ctx) -> ContainerManager:
+    """Create ContainerManager from Click context."""
+    project = ctx.obj.get("project") if ctx.obj else None
+    config = load_config(project_override=project, project_dir=Path.cwd())
+    return ContainerManager(config)
+
+
+@click.group("llm")
+@click.pass_context
+def llm_group(ctx):
+    """Manage the local LLM stack (Ollama + Open WebUI)."""
+
+
+@llm_group.command("up")
+@click.pass_context
+def llm_up(ctx):
+    """Start the LLM stack (Ollama + Open WebUI)."""
+    manager = _get_manager(ctx)
+    console.print("[bold]Starting LLM stack...[/bold]")
+
+    manager.ensure_ollama()
+    console.print(f"  Ollama API:  http://localhost:{manager.config.ollama_port}")
+
+    manager.ensure_webui()
+    console.print(f"  Open WebUI:  http://localhost:{manager.config.webui_port}")
+
+    console.print("\n[bold green]LLM stack is running.[/bold green]")
+    console.print("If this is your first time, run: [bold]ai-shell llm setup[/bold]")
+
+
+@llm_group.command("down")
+@click.pass_context
+def llm_down(ctx):
+    """Stop the LLM stack."""
+    manager = _get_manager(ctx)
+    console.print("[bold]Stopping LLM stack...[/bold]")
+
+    for name in [WEBUI_CONTAINER, OLLAMA_CONTAINER]:
+        status = manager.container_status(name)
+        if status == "running":
+            manager.stop_container(name)
+            console.print(f"  Stopped: {name}")
+        elif status is not None:
+            console.print(f"  Already stopped: {name}")
+        else:
+            console.print(f"  Not found: {name}")
+
+    console.print("[bold green]LLM stack stopped.[/bold green]")
+
+
+@llm_group.command("pull")
+@click.pass_context
+def llm_pull(ctx):
+    """Pull LLM models into Ollama."""
+    manager = _get_manager(ctx)
+    config = manager.config
+
+    console.print(f"[bold]Pulling primary model: {config.primary_model}...[/bold]")
+    output = manager.exec_in_ollama(["ollama", "pull", config.primary_model])
+    console.print(output)
+
+    console.print(f"\n[bold]Pulling fallback model: {config.fallback_model}...[/bold]")
+    output = manager.exec_in_ollama(["ollama", "pull", config.fallback_model])
+    console.print(output)
+
+    console.print("\n[bold]Available models:[/bold]")
+    output = manager.exec_in_ollama(["ollama", "list"])
+    console.print(output)
+
+
+@llm_group.command("setup")
+@click.pass_context
+def llm_setup(ctx):
+    """First-time setup: start stack, pull models, configure context window."""
+    manager = _get_manager(ctx)
+    config = manager.config
+
+    # Start the stack
+    console.print("[bold]Starting LLM stack...[/bold]")
+    manager.ensure_ollama()
+    manager.ensure_webui()
+
+    # Wait for Ollama to be ready
+    console.print("[bold]Waiting for Ollama to be ready...[/bold]")
+    for i in range(10):
+        try:
+            output = manager.exec_in_ollama(["ollama", "list"])
+            if output is not None:
+                break
+        except Exception:
+            pass
+        console.print(f"  Waiting... ({i + 1}/10)")
+        time.sleep(2)
+    else:
+        console.print("[bold red]Ollama failed to start after 20s[/bold red]")
+        raise click.Abort()
+
+    # Pull models
+    console.print(f"\n[bold]Pulling primary model: {config.primary_model}...[/bold]")
+    output = manager.exec_in_ollama(["ollama", "pull", config.primary_model])
+    console.print(output)
+
+    console.print(f"\n[bold]Pulling fallback model: {config.fallback_model}...[/bold]")
+    output = manager.exec_in_ollama(["ollama", "pull", config.fallback_model])
+    console.print(output)
+
+    # Configure context window
+    console.print(f"\n[bold]Configuring context window ({config.context_size} tokens)...[/bold]")
+    for model in [config.primary_model, config.fallback_model]:
+        modelfile = f"FROM {model}\nPARAMETER num_ctx {config.context_size}\n"
+        # Write modelfile and create model
+        manager.exec_in_ollama(
+            [
+                "sh",
+                "-c",
+                f'printf "{modelfile}" > /tmp/Modelfile && '
+                f"ollama create {model} -f /tmp/Modelfile && rm -f /tmp/Modelfile",
+            ]
+        )
+
+    console.print("\n[bold green]============================================[/bold green]")
+    console.print("[bold green] Setup complete![/bold green]")
+    console.print(f"\n  Open WebUI:  http://localhost:{config.webui_port}")
+    console.print(f"  Ollama API:  http://localhost:{config.ollama_port}")
+    console.print(f"\n  Primary model:  {config.primary_model}")
+    console.print(f"  Fallback model: {config.fallback_model}")
+    console.print(f"  Context window: {config.context_size} tokens")
+    console.print("[bold green]============================================[/bold green]")
+
+
+@llm_group.command("status")
+@click.pass_context
+def llm_status(ctx):
+    """Show status of LLM stack and loaded models."""
+    manager = _get_manager(ctx)
+
+    console.print("[bold]Container status:[/bold]")
+    for name in [OLLAMA_CONTAINER, WEBUI_CONTAINER]:
+        status = manager.container_status(name)
+        if status == "running":
+            console.print(f"  {name}: [green]{status}[/green]")
+        elif status is not None:
+            console.print(f"  {name}: [yellow]{status}[/yellow]")
+        else:
+            console.print(f"  {name}: [red]not found[/red]")
+
+    # Show models if ollama is running
+    if manager.container_status(OLLAMA_CONTAINER) == "running":
+        console.print("\n[bold]Available models:[/bold]")
+        output = manager.exec_in_ollama(["ollama", "list"])
+        console.print(output)
+
+
+@llm_group.command("logs")
+@click.option("--follow", "-f", is_flag=True, help="Follow log output.")
+@click.pass_context
+def llm_logs(ctx, follow):
+    """Tail logs from the LLM stack."""
+    manager = _get_manager(ctx)
+    if follow:
+        # Use docker CLI for multi-container following
+        import os
+        import sys
+
+        sys.stdout.flush()
+        sys.stderr.flush()
+        os.execvp(
+            "docker",
+            ["docker", "logs", "-f", OLLAMA_CONTAINER],
+        )
+    else:
+        for name in [OLLAMA_CONTAINER, WEBUI_CONTAINER]:
+            status = manager.container_status(name)
+            if status is not None:
+                console.print(f"\n[bold]--- {name} ---[/bold]")
+                manager.container_logs(name, follow=False, tail=50)
+
+
+@llm_group.command("shell")
+@click.pass_context
+def llm_shell(ctx):
+    """Open a bash shell in the Ollama container."""
+    manager = _get_manager(ctx)
+    status = manager.container_status(OLLAMA_CONTAINER)
+    if status != "running":
+        console.print("[red]Ollama is not running. Run: ai-shell llm up[/red]")
+        raise click.Abort()
+    console.print("[bold]Opening shell in Ollama container...[/bold]")
+    manager.exec_interactive(OLLAMA_CONTAINER, ["/bin/bash"])

ai_shell/cli/commands/manage.py

@@ -0,0 +1,98 @@
+"""Container management commands: status, stop, clean, logs, pull."""
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ai_shell.config import load_config
+from ai_shell.container import ContainerManager
+from ai_shell.defaults import dev_container_name
+from ai_shell.exceptions import ContainerNotFoundError
+
+console = Console(stderr=True)
+
+
+def _get_manager(ctx) -> ContainerManager:
+    """Create ContainerManager from Click context."""
+    project = ctx.obj.get("project") if ctx.obj else None
+    config = load_config(project_override=project, project_dir=Path.cwd())
+    return ContainerManager(config)
+
+
+@click.group("manage")
+@click.pass_context
+def manage_group(ctx):
+    """Manage dev containers."""
+
+
+@manage_group.command("status")
+@click.pass_context
+def manage_status(ctx):
+    """Show dev container status for current project."""
+    manager = _get_manager(ctx)
+    name = dev_container_name(manager.config.project_name)
+    status = manager.container_status(name)
+
+    if status is None:
+        console.print(
+            f"[yellow]No container found for project: {manager.config.project_name}[/yellow]"
+        )
+    elif status == "running":
+        console.print(f"[green]{name}: running[/green]")
+    else:
+        console.print(f"[yellow]{name}: {status}[/yellow]")
+
+
+@manage_group.command("stop")
+@click.pass_context
+def manage_stop(ctx):
+    """Stop the dev container for current project."""
+    manager = _get_manager(ctx)
+    name = dev_container_name(manager.config.project_name)
+
+    try:
+        manager.stop_container(name)
+        console.print(f"[green]Stopped: {name}[/green]")
+    except ContainerNotFoundError:
+        console.print(f"[yellow]No container found: {name}[/yellow]")
+
+
+@manage_group.command("clean")
+@click.option("--force", "-f", is_flag=True, help="Force remove even if running.")
+@click.pass_context
+def manage_clean(ctx, force):
+    """Remove the dev container for current project."""
+    manager = _get_manager(ctx)
+    name = dev_container_name(manager.config.project_name)
+
+    try:
+        manager.remove_container(name, force=force)
+        console.print(f"[green]Removed: {name}[/green]")
+    except ContainerNotFoundError:
+        console.print(f"[yellow]No container found: {name}[/yellow]")
+
+
+@manage_group.command("logs")
+@click.option("--follow", "-f", is_flag=True, help="Follow log output.")
+@click.pass_context
+def manage_logs(ctx, follow):
+    """Tail dev container logs."""
+    manager = _get_manager(ctx)
+    name = dev_container_name(manager.config.project_name)
+
+    try:
+        manager.container_logs(name, follow=follow)
+    except ContainerNotFoundError:
+        console.print(f"[yellow]No container found: {name}[/yellow]")
+
+
+@manage_group.command("pull")
+@click.pass_context
+def manage_pull(ctx):
+    """Pull the latest Docker image."""
+    manager = _get_manager(ctx)
+    image = manager.config.full_image
+    console.print(f"[bold]Pulling {image}...[/bold]")
+    manager._pull_image_if_needed(image)
+    console.print(f"[green]Image ready: {image}[/green]")

ai_shell/cli/commands/tools.py

@@ -0,0 +1,94 @@
+"""AI tool subcommands: claude, codex, opencode, aider, shell."""
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ai_shell.config import load_config
+from ai_shell.container import ContainerManager
+
+console = Console(stderr=True)
+
+
+def _get_manager(ctx) -> tuple[ContainerManager, str]:
+    """Create ContainerManager from Click context and ensure dev container."""
+    project = ctx.obj.get("project") if ctx.obj else None
+    config = load_config(project_override=project, project_dir=Path.cwd())
+    manager = ContainerManager(config)
+    container_name = manager.ensure_dev_container()
+    return manager, container_name
+
+
+@click.command()
+@click.argument("extra_args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def claude(ctx, extra_args):
+    """Launch Claude Code in the dev container."""
+    manager, name = _get_manager(ctx)
+    cmd = ["claude", *extra_args]
+    console.print(f"[bold]Launching Claude Code in {name}...[/bold]")
+    manager.exec_interactive(name, cmd)
+
+
+@click.command("claude-x")
+@click.argument("extra_args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def claude_x(ctx, extra_args):
+    """Launch Claude Code with --dangerously-skip-permissions."""
+    manager, name = _get_manager(ctx)
+    cmd = ["claude", "--dangerously-skip-permissions", "-c", *extra_args]
+    console.print(f"[bold]Launching Claude Code (skip-permissions) in {name}...[/bold]")
+    manager.exec_interactive(name, cmd)
+
+
+@click.command()
+@click.argument("extra_args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def codex(ctx, extra_args):
+    """Launch Codex in the dev container."""
+    manager, name = _get_manager(ctx)
+    cmd = ["codex", "--dangerously-bypass-approvals-and-sandbox", "--search", *extra_args]
+    console.print(f"[bold]Launching Codex in {name}...[/bold]")
+    manager.exec_interactive(name, cmd)
+
+
+@click.command()
+@click.pass_context
+def opencode(ctx):
+    """Launch opencode in the dev container."""
+    manager, name = _get_manager(ctx)
+    cmd = ["/root/.opencode/bin/opencode"]
+    console.print(f"[bold]Launching opencode in {name}...[/bold]")
+    manager.exec_interactive(name, cmd)
+
+
+@click.command()
+@click.argument("extra_args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def aider(ctx, extra_args):
+    """Launch aider with local LLM in the dev container."""
+    project = ctx.obj.get("project") if ctx.obj else None
+    config = load_config(project_override=project, project_dir=Path.cwd())
+    manager = ContainerManager(config)
+    name = manager.ensure_dev_container()
+    cmd = [
+        "aider",
+        "--model",
+        config.aider_model,
+        "--yes-always",
+        "--restore-chat-history",
+        *extra_args,
+    ]
+    extra_env = {"OLLAMA_API_BASE": "http://host.docker.internal:11434"}
+    console.print(f"[bold]Launching aider ({config.aider_model}) in {name}...[/bold]")
+    manager.exec_interactive(name, cmd, extra_env=extra_env)
+
+
+@click.command()
+@click.pass_context
+def shell(ctx):
+    """Open a bash shell in the dev container."""
+    manager, name = _get_manager(ctx)
+    console.print(f"[bold]Opening shell in {name}...[/bold]")
+    manager.exec_interactive(name, ["/bin/bash"])

ai_shell/config.py

@@ -0,0 +1,155 @@
+"""Configuration loading for ai-shell.
+
+Priority (highest wins): CLI flags > env vars > project ai-shell.toml > global config > defaults.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ai_shell import __version__
+from ai_shell.defaults import (
+    DEFAULT_CONTEXT_SIZE,
+    DEFAULT_FALLBACK_MODEL,
+    DEFAULT_IMAGE,
+    DEFAULT_OLLAMA_PORT,
+    DEFAULT_PRIMARY_MODEL,
+    DEFAULT_WEBUI_PORT,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AiShellConfig:
+    """Configuration for ai-shell."""
+
+    # Container
+    image: str = DEFAULT_IMAGE
+    image_tag: str = __version__
+    project_name: str = ""
+    project_dir: Path = field(default_factory=Path.cwd)
+
+    # LLM
+    primary_model: str = DEFAULT_PRIMARY_MODEL
+    fallback_model: str = DEFAULT_FALLBACK_MODEL
+    context_size: int = DEFAULT_CONTEXT_SIZE
+    ollama_port: int = DEFAULT_OLLAMA_PORT
+    webui_port: int = DEFAULT_WEBUI_PORT
+
+    # Aider
+    aider_model: str = f"ollama_chat/{DEFAULT_PRIMARY_MODEL}"
+
+    # Extra configuration
+    extra_env: dict[str, str] = field(default_factory=dict)
+    extra_volumes: list[str] = field(default_factory=list)
+
+    @property
+    def full_image(self) -> str:
+        """Return the full image reference with tag."""
+        return f"{self.image}:{self.image_tag}"
+
+
+def load_config(
+    project_override: str | None = None,
+    project_dir: Path | None = None,
+) -> AiShellConfig:
+    """Load configuration from all sources.
+
+    Priority: CLI overrides > env vars > project toml > global toml > defaults.
+    """
+    config = AiShellConfig()
+
+    if project_dir:
+        config.project_dir = project_dir
+
+    # Load global config
+    global_config_path = Path.home() / ".config" / "ai-shell" / "config.toml"
+    if global_config_path.exists():
+        _apply_toml(config, global_config_path)
+
+    # Load project config
+    project_config_path = config.project_dir / "ai-shell.toml"
+    if project_config_path.exists():
+        _apply_toml(config, project_config_path)
+
+    # Apply environment variable overrides
+    _apply_env_vars(config)
+
+    # Apply CLI overrides
+    if project_override:
+        config.project_name = project_override
+
+    # Auto-derive project name from CWD if not set
+    if not config.project_name:
+        from ai_shell.defaults import sanitize_project_name
+
+        config.project_name = sanitize_project_name(config.project_dir)
+
+    return config
+
+
+def _apply_toml(config: AiShellConfig, path: Path) -> None:
+    """Apply settings from a TOML config file."""
+    try:
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError) as e:
+        logger.warning("Failed to load config from %s: %s", path, e)
+        return
+
+    logger.debug("Loading config from %s", path)
+
+    # [container] section
+    container = data.get("container", {})
+    if "image" in container:
+        config.image = container["image"]
+    if "image_tag" in container:
+        config.image_tag = container["image_tag"]
+    if "extra_env" in container:
+        config.extra_env.update(container["extra_env"])
+    if "extra_volumes" in container:
+        config.extra_volumes.extend(container["extra_volumes"])
+
+    # [llm] section
+    llm = data.get("llm", {})
+    if "primary_model" in llm:
+        config.primary_model = llm["primary_model"]
+    if "fallback_model" in llm:
+        config.fallback_model = llm["fallback_model"]
+    if "context_size" in llm:
+        config.context_size = int(llm["context_size"])
+    if "ollama_port" in llm:
+        config.ollama_port = int(llm["ollama_port"])
+    if "webui_port" in llm:
+        config.webui_port = int(llm["webui_port"])
+
+    # [aider] section
+    aider = data.get("aider", {})
+    if "model" in aider:
+        config.aider_model = aider["model"]
+
+
+def _apply_env_vars(config: AiShellConfig) -> None:
+    """Apply AI_SHELL_* environment variable overrides."""
+    env_map: dict[str, tuple[str, type]] = {
+        "AI_SHELL_IMAGE": ("image", str),
+        "AI_SHELL_IMAGE_TAG": ("image_tag", str),
+        "AI_SHELL_PROJECT": ("project_name", str),
+        "AI_SHELL_PRIMARY_MODEL": ("primary_model", str),
+        "AI_SHELL_FALLBACK_MODEL": ("fallback_model", str),
+        "AI_SHELL_CONTEXT_SIZE": ("context_size", int),
+        "AI_SHELL_OLLAMA_PORT": ("ollama_port", int),
+        "AI_SHELL_WEBUI_PORT": ("webui_port", int),
+        "AI_SHELL_AIDER_MODEL": ("aider_model", str),
+    }
+
+    for env_key, (attr, type_fn) in env_map.items():
+        value = os.environ.get(env_key)
+        if value is not None:
+            setattr(config, attr, type_fn(value))
+            logger.debug("Config override from env: %s=%s", env_key, value)

ai_shell/container.py

@@ -0,0 +1,326 @@
+"""Docker container lifecycle management.
+
+Replaces docker-compose.yml by using Docker SDK to create and manage containers
+with the exact same configuration.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import TYPE_CHECKING, NoReturn
+
+from docker.errors import APIError, ImageNotFound, NotFound
+from docker.types import DeviceRequest, Mount
+
+import docker
+from ai_shell.defaults import (
+    OLLAMA_CONTAINER,
+    OLLAMA_DATA_VOLUME,
+    OLLAMA_IMAGE,
+    SHM_SIZE,
+    WEBUI_CONTAINER,
+    WEBUI_DATA_VOLUME,
+    WEBUI_IMAGE,
+    build_dev_environment,
+    build_dev_mounts,
+    dev_container_name,
+)
+from ai_shell.exceptions import (
+    ContainerNotFoundError,
+    DockerNotAvailableError,
+    ImagePullError,
+)
+from ai_shell.gpu import detect_gpu
+
+if TYPE_CHECKING:
+    from docker.models.containers import Container
+
+    from ai_shell.config import AiShellConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ContainerManager:
+    """Manages Docker containers for ai-shell.
+
+    Handles the dev container (per-project) and LLM stack (host-level singletons).
+    """
+
+    def __init__(self, config: AiShellConfig) -> None:
+        self.config = config
+        try:
+            self.client = docker.from_env()  # type: ignore[attr-defined]
+            self.client.ping()
+        except docker.errors.DockerException as e:
+            raise DockerNotAvailableError(
+                f"Docker is not available. Is the Docker daemon running?\n  Error: {e}"
+            ) from e
+
+    # =========================================================================
+    # Dev container (per-project)
+    # =========================================================================
+
+    def ensure_dev_container(self) -> str:
+        """Get or create the dev container for the current project.
+
+        If the container exists but is stopped, it is started.
+        If it doesn't exist, it is created with the full configuration.
+
+        Returns the container name.
+        """
+        name = dev_container_name(self.config.project_name)
+        container = self._get_container(name)
+
+        if container is not None:
+            if container.status != "running":
+                logger.info("Starting existing container: %s", name)
+                container.start()
+            return name
+
+        logger.info("Creating dev container: %s", name)
+        self._pull_image_if_needed(self.config.full_image)
+        self._create_dev_container(name)
+        return name
+
+    def _create_dev_container(self, name: str) -> Container:
+        """Create the dev container with all docker-compose config."""
+        mounts = build_dev_mounts(self.config.project_dir, self.config.project_name)
+        environment = build_dev_environment(self.config.extra_env)
+
+        # Add any extra volumes from config
+        for vol_spec in self.config.extra_volumes:
+            parts = vol_spec.split(":")
+            if len(parts) >= 2:
+                source, target = parts[0], parts[1]
+                read_only = len(parts) > 2 and parts[2] == "ro"
+                mounts.append(
+                    Mount(
+                        target=target,
+                        source=source,
+                        type="bind",
+                        read_only=read_only,
+                    )
+                )
+
+        container: Container = self.client.containers.run(
+            image=self.config.full_image,
+            name=name,
+            mounts=mounts,
+            environment=environment,
+            working_dir=f"/root/projects/{self.config.project_name}",
+            command="tail -f /dev/null",
+            stdin_open=True,
+            tty=True,
+            shm_size=SHM_SIZE,
+            init=True,
+            extra_hosts={"host.docker.internal": "host-gateway"},
+            ports={"5678/tcp": None, "8000/tcp": None},
+            detach=True,
+        )
+        logger.info("Container created: %s", name)
+        return container
+
+    def exec_interactive(
+        self,
+        container_name: str,
+        command: list[str],
+        extra_env: dict[str, str] | None = None,
+    ) -> NoReturn:
+        """Replace the current process with docker exec -it.
+
+        This uses os.execvp to hand off to docker CLI for proper TTY support.
+        The Python process is replaced and never returns.
+        """
+        args = ["docker", "exec", "-it"]
+
+        if extra_env:
+            for key, value in extra_env.items():
+                args.extend(["-e", f"{key}={value}"])
+
+        args.append(container_name)
+        args.extend(command)
+
+        logger.debug("exec: %s", " ".join(args))
+
+        # Flush output before replacing process
+        sys.stdout.flush()
+        sys.stderr.flush()
+
+        os.execvp("docker", args)
+
+    # =========================================================================
+    # LLM stack (host-level singletons)
+    # =========================================================================
+
+    def ensure_ollama(self) -> str:
+        """Get or create the Ollama container with GPU auto-detection.
+
+        Returns the container name.
+        """
+        container = self._get_container(OLLAMA_CONTAINER)
+
+        if container is not None:
+            if container.status != "running":
+                logger.info("Starting existing Ollama container")
+                container.start()
+            return OLLAMA_CONTAINER
+
+        logger.info("Creating Ollama container")
+        self._pull_image_if_needed(OLLAMA_IMAGE)
+
+        # GPU auto-detection
+        gpu_available = detect_gpu()
+        device_requests = None
+        if gpu_available:
+            device_requests = [DeviceRequest(count=1, capabilities=[["gpu"]])]
+            logger.info("GPU detected - Ollama will use NVIDIA GPU")
+        else:
+            logger.warning("No GPU detected - Ollama will run on CPU (slower inference)")
+
+        kwargs: dict = {
+            "image": OLLAMA_IMAGE,
+            "name": OLLAMA_CONTAINER,
+            "ports": {"11434/tcp": ("0.0.0.0", self.config.ollama_port)},  # nosec B104
+            "mounts": [
+                Mount(
+                    target="/root/.ollama",
+                    source=OLLAMA_DATA_VOLUME,
+                    type="volume",
+                )
+            ],
+            "restart_policy": {"Name": "unless-stopped"},
+            "detach": True,
+        }
+
+        if device_requests:
+            kwargs["device_requests"] = device_requests
+
+        self.client.containers.run(**kwargs)
+        logger.info("Ollama container created on port %d", self.config.ollama_port)
+        return OLLAMA_CONTAINER
+
+    def ensure_webui(self) -> str:
+        """Get or create the Open WebUI container.
+
+        Returns the container name.
+        """
+        container = self._get_container(WEBUI_CONTAINER)
+
+        if container is not None:
+            if container.status != "running":
+                logger.info("Starting existing WebUI container")
+                container.start()
+            return WEBUI_CONTAINER
+
+        logger.info("Creating Open WebUI container")
+        self._pull_image_if_needed(WEBUI_IMAGE)
+
+        self.client.containers.run(
+            image=WEBUI_IMAGE,
+            name=WEBUI_CONTAINER,
+            ports={"8080/tcp": ("0.0.0.0", self.config.webui_port)},  # nosec B104
+            environment={
+                "OLLAMA_BASE_URL": f"http://{OLLAMA_CONTAINER}:11434",
+                "WEBUI_AUTH": "false",
+            },
+            mounts=[
+                Mount(
+                    target="/app/backend/data",
+                    source=WEBUI_DATA_VOLUME,
+                    type="volume",
+                )
+            ],
+            restart_policy={"Name": "unless-stopped"},
+            detach=True,
+            # Link to ollama via Docker network
+            network_mode=f"container:{OLLAMA_CONTAINER}",
+        )
+
+        logger.info("Open WebUI container created on port %d", self.config.webui_port)
+        return WEBUI_CONTAINER
+
+    def exec_in_ollama(self, command: list[str]) -> str:
+        """Run a command in the Ollama container and return stdout.
+
+        Used for: ollama pull, ollama list, ollama create.
+        """
+        container = self._get_container(OLLAMA_CONTAINER)
+        if container is None or container.status != "running":
+            raise ContainerNotFoundError(OLLAMA_CONTAINER)
+
+        exit_code, output = container.exec_run(
+            cmd=command,
+            stdout=True,
+            stderr=True,
+        )
+        decoded: str = output.decode("utf-8", errors="replace")
+        if exit_code != 0:
+            logger.error("Command failed in ollama: %s\n%s", " ".join(command), decoded)
+        return decoded
+
+    # =========================================================================
+    # Container lifecycle
+    # =========================================================================
+
+    def stop_container(self, name: str) -> None:
+        """Stop a container by name."""
+        container = self._get_container(name)
+        if container is None:
+            raise ContainerNotFoundError(name)
+        if container.status == "running":
+            container.stop()
+            logger.info("Stopped container: %s", name)
+
+    def remove_container(self, name: str, force: bool = False) -> None:
+        """Remove a container by name."""
+        container = self._get_container(name)
+        if container is None:
+            raise ContainerNotFoundError(name)
+        container.remove(force=force)
+        logger.info("Removed container: %s", name)
+
+    def container_status(self, name: str) -> str | None:
+        """Get the status of a container, or None if it doesn't exist."""
+        container = self._get_container(name)
+        if container is None:
+            return None
+        return container.status  # type: ignore[no-any-return]
+
+    def container_logs(self, name: str, follow: bool = False, tail: int = 100) -> None:
+        """Print container logs. If follow=True, streams via docker CLI."""
+        if follow:
+            # Use docker CLI for streaming
+            args = ["docker", "logs", "-f", name]
+            os.execvp("docker", args)
+        else:
+            container = self._get_container(name)
+            if container is None:
+                raise ContainerNotFoundError(name)
+            logs = container.logs(tail=tail).decode("utf-8", errors="replace")
+            print(logs)
+
+    # =========================================================================
+    # Internal helpers
+    # =========================================================================
+
+    def _get_container(self, name: str) -> Container | None:
+        """Get a container by name, or None if it doesn't exist."""
+        try:
+            return self.client.containers.get(name)
+        except NotFound:
+            return None
+
+    def _pull_image_if_needed(self, image: str) -> None:
+        """Pull a Docker image if not available locally."""
+        try:
+            self.client.images.get(image)
+            logger.debug("Image already available: %s", image)
+        except ImageNotFound:
+            logger.info("Pulling image: %s (this may take a while)...", image)
+            try:
+                self.client.images.pull(*image.rsplit(":", 1))
+                logger.info("Image pulled: %s", image)
+            except APIError as e:
+                raise ImagePullError(image, str(e)) from e

ai_shell/defaults.py

@@ -0,0 +1,157 @@
+"""Constants and configuration builders for augint-shell.
+
+Encodes all docker-compose.yml configuration as Python, so no compose file is needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from docker.types import Mount
+
+logger = logging.getLogger(__name__)
+
+# =============================================================================
+# Image defaults
+# =============================================================================
+DEFAULT_IMAGE = "svange/augint-shell"
+CONTAINER_PREFIX = "augint-shell"
+SHM_SIZE = "2g"
+
+# =============================================================================
+# Volume names (prefixed to avoid collisions)
+# =============================================================================
+UV_CACHE_VOLUME = "augint-shell-uv-cache"
+OLLAMA_DATA_VOLUME = "augint-shell-ollama-data"
+WEBUI_DATA_VOLUME = "augint-shell-webui-data"
+
+# =============================================================================
+# LLM defaults
+# =============================================================================
+OLLAMA_IMAGE = "ollama/ollama"
+WEBUI_IMAGE = "ghcr.io/open-webui/open-webui:main"
+DEFAULT_PRIMARY_MODEL = "qwen3.5:27b"
+DEFAULT_FALLBACK_MODEL = "qwen3-coder-next"
+DEFAULT_CONTEXT_SIZE = 32768
+DEFAULT_OLLAMA_PORT = 11434
+DEFAULT_WEBUI_PORT = 3000
+
+# =============================================================================
+# Container names
+# =============================================================================
+OLLAMA_CONTAINER = "augint-shell-ollama"
+WEBUI_CONTAINER = "augint-shell-webui"
+
+
+def sanitize_project_name(path: Path) -> str:
+    """Derive a safe container name suffix from a directory path.
+
+    Converts the directory basename to lowercase, replaces non-alphanumeric
+    characters with hyphens, and strips leading/trailing hyphens.
+    """
+    name = path.resolve().name.lower()
+    name = re.sub(r"[^a-z0-9-]", "-", name)
+    name = re.sub(r"-+", "-", name)
+    return name.strip("-") or "project"
+
+
+def dev_container_name(project_name: str) -> str:
+    """Build the dev container name for a project."""
+    return f"{CONTAINER_PREFIX}-{project_name}-dev"
+
+
+def build_dev_mounts(project_dir: Path, project_name: str) -> list[Mount]:
+    """Build the full mount list matching docker-compose.yml dev service.
+
+    Required mounts are always included. Optional mounts are skipped
+    if the source path doesn't exist on the host.
+    """
+    from docker.types import Mount
+
+    mounts: list[Mount] = []
+    home = Path.home()
+
+    # Required: project directory (rw, delegated)
+    mounts.append(
+        Mount(
+            target=f"/root/projects/{project_name}",
+            source=str(project_dir.resolve()),
+            type="bind",
+            read_only=False,
+            consistency="delegated",
+        )
+    )
+
+    # Optional bind mounts — skip if source doesn't exist
+    optional_binds: list[tuple[Path, str, bool]] = [
+        (home / ".codex", "/root/.codex", False),
+        (home / ".claude", "/root/.claude", False),
+        (home / ".claude.json", "/root/.claude.json", False),
+        (home / "projects" / "CLAUDE.md", "/root/projects/CLAUDE.md", True),
+        (home / ".ssh", "/root/.ssh", True),
+        (home / ".gitconfig", "/root/.gitconfig.windows", True),
+        (home / ".aws", "/root/.aws", False),
+    ]
+
+    for source, target, read_only in optional_binds:
+        if source.exists():
+            mounts.append(
+                Mount(
+                    target=target,
+                    source=str(source),
+                    type="bind",
+                    read_only=read_only,
+                )
+            )
+        else:
+            logger.debug("Skipping optional mount (not found): %s", source)
+
+    # Optional: Docker socket
+    docker_sock = Path("/var/run/docker.sock")
+    if docker_sock.exists():
+        mounts.append(
+            Mount(
+                target="/var/run/docker.sock",
+                source=str(docker_sock),
+                type="bind",
+                read_only=True,
+            )
+        )
+
+    # Named volume: uv cache (shared across all projects)
+    mounts.append(
+        Mount(
+            target="/root/.cache/uv",
+            source=UV_CACHE_VOLUME,
+            type="volume",
+        )
+    )
+
+    return mounts
+
+
+def build_dev_environment(extra_env: dict[str, str] | None = None) -> dict[str, str]:
+    """Build environment variables matching docker-compose.yml dev service.
+
+    Passes through AWS credentials, GitHub token, and sandbox flag from the host.
+    """
+    env: dict[str, str] = {
+        # AWS region (auth via SSO/OIDC, not static credentials)
+        "AWS_REGION": os.environ.get("AWS_REGION", "us-east-1"),
+        "AWS_PAGER": "",
+        # GitHub token
+        "GH_TOKEN": os.environ.get("GH_TOKEN", ""),
+        "GITHUB_TOKEN": os.environ.get("GH_TOKEN", ""),
+        # Sandbox mode for claude --dangerously-skip-permissions
+        "IS_SANDBOX": "1",
+    }
+
+    if extra_env:
+        env.update(extra_env)
+
+    return env

ai_shell/exceptions.py

@@ -0,0 +1,30 @@
+"""Custom exceptions for ai-shell."""
+
+
+class AiShellError(Exception):
+    """Base exception for ai-shell."""
+
+
+class DockerNotAvailableError(AiShellError):
+    """Docker daemon is not running or not installed."""
+
+
+class ImagePullError(AiShellError):
+    """Failed to pull Docker image."""
+
+    def __init__(self, image: str, reason: str) -> None:
+        self.image = image
+        self.reason = reason
+        super().__init__(f"Failed to pull {image}: {reason}")
+
+
+class ContainerNotFoundError(AiShellError):
+    """Container does not exist."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"Container '{name}' not found")
+
+
+class ConfigError(AiShellError):
+    """Invalid configuration."""

ai_shell/gpu.py

@@ -0,0 +1,75 @@
+"""NVIDIA GPU detection for Docker containers."""
+
+import logging
+import shutil
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+def detect_gpu() -> bool:
+    """Check if NVIDIA GPU and Docker GPU runtime are available.
+
+    Returns True if both nvidia-smi succeeds and Docker has GPU support.
+    Falls back to False with a warning if either check fails.
+    """
+    if not _check_nvidia_smi():
+        return False
+    if not _check_docker_gpu_runtime():
+        return False
+    return True
+
+
+def _check_nvidia_smi() -> bool:
+    """Check if nvidia-smi is available and reports a GPU."""
+    if not shutil.which("nvidia-smi"):
+        logger.debug("nvidia-smi not found in PATH")
+        return False
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", "--query-gpu=name", "--format=csv,noheader"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            logger.debug("GPU detected: %s", result.stdout.strip().split("\n")[0])
+            return True
+        logger.debug("nvidia-smi returned no GPUs")
+        return False
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as e:
+        logger.debug("nvidia-smi check failed: %s", e)
+        return False
+
+
+def _check_docker_gpu_runtime() -> bool:
+    """Check if Docker supports GPU via nvidia runtime."""
+    docker_path = shutil.which("docker")
+    if not docker_path:
+        logger.debug("docker not found in PATH")
+        return False
+    try:
+        result = subprocess.run(
+            ["docker", "info", "--format", "{{.Runtimes}}"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0 and "nvidia" in result.stdout.lower():
+            logger.debug("Docker nvidia runtime available")
+            return True
+        # Also check for default GPU support (newer Docker versions)
+        result2 = subprocess.run(
+            ["docker", "info", "--format", "{{json .}}"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result2.returncode == 0 and "nvidia" in result2.stdout.lower():
+            logger.debug("Docker nvidia support detected via docker info")
+            return True
+        logger.debug("Docker nvidia runtime not found")
+        return False
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as e:
+        logger.debug("Docker GPU runtime check failed: %s", e)
+        return False

augint_shell-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.3
+Name: augint-shell
+Version: 0.1.0
+Summary: Launch AI coding tools and local LLMs in Docker containers
+Author: svange
+Requires-Dist: docker>=7.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=14.0
+Requires-Dist: pytest>=7.4.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.8.0 ; extra == 'dev'
+Requires-Dist: python-semantic-release>=10.3.1 ; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0 ; extra == 'dev'
+Requires-Dist: bandit>=1.7.0 ; extra == 'dev'
+Requires-Dist: pip-audit>=2.7.0 ; extra == 'dev'
+Requires-Dist: pip-licenses>=5.0.0 ; extra == 'dev'
+Requires-Dist: pytest-html>=4.0.0 ; extra == 'dev'
+Requires-Python: >=3.12
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# augint-shell
+
+Launch AI coding tools and local LLMs in Docker containers.
+
+## Installation
+
+```bash
+pip install augint-shell
+```
+
+Or as a dev dependency:
+
+```bash
+uv add --dev augint-shell
+```
+
+## Quick Start
+
+```bash
+# Launch Claude Code in the current project
+ai-shell claude
+
+# Launch with extra args
+ai-shell claude -- --debug
+
+# Set up local LLM stack (first time)
+ai-shell llm setup
+
+# Launch opencode with local LLM
+ai-shell opencode
+```
+
+## Commands
+
+### AI Tools
+
+| Command | Description |
+|---|---|
+| `ai-shell claude` | Launch Claude Code |
+| `ai-shell claude-x` | Claude Code with skip-permissions |
+| `ai-shell codex` | Launch Codex |
+| `ai-shell opencode` | Launch opencode |
+| `ai-shell aider` | Launch aider with local LLM |
+| `ai-shell shell` | Bash shell in dev container |
+
+### LLM Stack
+
+| Command | Description |
+|---|---|
+| `ai-shell llm up` | Start Ollama + Open WebUI |
+| `ai-shell llm down` | Stop LLM stack |
+| `ai-shell llm pull` | Pull configured models |
+| `ai-shell llm setup` | First-time setup (up + pull + configure) |
+| `ai-shell llm status` | Show status and available models |
+| `ai-shell llm logs` | Tail LLM stack logs |
+| `ai-shell llm shell` | Shell into Ollama container |
+
+### Container Management
+
+| Command | Description |
+|---|---|
+| `ai-shell manage status` | Show dev container status |
+| `ai-shell manage stop` | Stop dev container |
+| `ai-shell manage clean` | Remove container and volumes |
+| `ai-shell manage logs` | Tail dev container logs |
+| `ai-shell manage pull` | Pull latest Docker image |
+
+## Configuration
+
+Optional `ai-shell.toml` in your project root:
+
+```toml
+[container]
+image = "svange/augint-shell"
+image_tag = "latest"
+extra_env = { MY_VAR = "value" }
+
+[llm]
+primary_model = "qwen3.5:27b"
+fallback_model = "qwen3-coder-next"
+context_size = 32768
+ollama_port = 11434
+webui_port = 3000
+
+[aider]
+model = "ollama_chat/qwen3.5:27b"
+```
+
+Global config at `~/.config/ai-shell/config.toml` is also supported.
+
+## How It Works
+
+- Pulls a pre-built Docker image from Docker Hub (`svange/augint-shell`)
+- Creates per-project containers named `augint-shell-{project}-dev`
+- Mounts your project directory, SSH keys, AWS credentials, and tool configs
+- Runs AI tools interactively inside the container
+- Supports concurrent instances across multiple projects
+
+## Requirements
+
+- Docker
+- Python >= 3.12

augint_shell-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ai_shell/__init__.py,sha256=7zyXMlfHkgdJMDt1C9RpHA516t35QyjEnkxiz7Jw3mk,149
+ai_shell/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ai_shell/cli/__main__.py,sha256=SnBm-z-FYBOs27r2SBpap0U9e0_osqkq5qeA_h8ZopU,1108
+ai_shell/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ai_shell/cli/commands/llm.py,sha256=IzWBeoZKCWFdrlXSNM_NWorPqo0MkXZwFhEn3mdTlsc,7144
+ai_shell/cli/commands/manage.py,sha256=fVeurwfcg5lEgxwqVy1n8gGO2LZnjtjUZ-zzsm5uS7w,3065
+ai_shell/cli/commands/tools.py,sha256=ijcWqEIJVZVCgktN4yI0ez2IfetTUuI8DRpxsok9xqI,3216
+ai_shell/config.py,sha256=inJh2CBQ9F2RGQuYrTqfGgzMBZEVYw-9pMn2C85ZoG0,4771
+ai_shell/container.py,sha256=f9kBf3rQ_Pqx8ohdBnMUksb4JGe9Aer-GAxSj_cpqUM,11408
+ai_shell/defaults.py,sha256=lBeWHQvPOUMBc147woEniqLMZXB5w3CPFqpWyei2D-I,5106
+ai_shell/exceptions.py,sha256=ipAfi_riLpW057prl1xjIskX4ouI5b2bUKhGdfocANs,744
+ai_shell/gpu.py,sha256=vETkk4jFxz0q4yBhAJy-uNjJW_BPhIv6ZtRpsC_SFhA,2554
+augint_shell-0.1.0.dist-info/WHEEL,sha256=bEhYrD-rjlF0iRRHiAnfJ0mEjMsRwm29hhDD7yRgWCY,80
+augint_shell-0.1.0.dist-info/entry_points.txt,sha256=Sz7xOQqBtBHyd7yHEqeOjzZBjhmzh_CIgGqKZwFfdmo,57
+augint_shell-0.1.0.dist-info/METADATA,sha256=4YmpXO9ni9wKbprtSnWs0dk8Ol5x6bBFDdSZSCX-vn8,3161
+augint_shell-0.1.0.dist-info/RECORD,,

augint_shell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.3
+Root-Is-Purelib: true
+Tag: py3-none-any

augint_shell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ai-shell = ai_shell.cli.__main__:main
+