dbagent-cli 0.1.0__py3-none-any.whl

dbagent/cli.py

@@ -0,0 +1,717 @@
+"""
+DB-Agent CLI: Main Terminal Entry Point.
+Seamless database CLI — ask questions in natural language, get results instantly.
+"""
+
+import os
+import sys
+import json
+from pathlib import Path
+from typing import Optional, List
+import typer
+from rich.prompt import Prompt, Confirm
+from rich.table import Table
+from prompt_toolkit import PromptSession
+from prompt_toolkit.history import FileHistory
+
+from dbagent import __version__
+from dbagent.config import ConfigManager
+from dbagent.connectors.factory import create_connector
+from dbagent.schema.formatter import SchemaFormatter
+from dbagent.schema.models import DatabaseSchema
+from dbagent.llm.factory import get_llm_provider
+from dbagent.agent.generator import ScriptGenerator
+from dbagent.agent.validator import ScriptValidator
+from dbagent.agent.pipeline import QueryPipeline, PipelineResult
+from dbagent.ui.console import (
+    console,
+    print_banner,
+    print_success,
+    print_error,
+    print_warning,
+    print_info,
+    print_code,
+    print_results_table,
+)
+from dbagent.ui.viewer import SchemaViewer
+
+app = typer.Typer(
+    name="db-agent",
+    help="DB-Agent: Universal Database CLI with AI — ask in plain English, get results instantly.",
+    add_completion=False,
+)
+
+config_mgr = ConfigManager()
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def resolve_db_url(db: Optional[str] = None) -> str:
+    """Resolve database connection URL from CLI arg, saved profiles, or user prompt."""
+    if db:
+        profile = config_mgr.get_profile(db)
+        if profile:
+            return profile["url"]
+        return db
+
+    env_db = os.getenv("DATABASE_URL")
+    if env_db:
+        return env_db
+
+    profiles = config_mgr.list_profiles()
+    if len(profiles) == 1:
+        only_prof = list(profiles.values())[0]
+        return only_prof["url"]
+
+    if profiles:
+        console.print("[cyan]Available Saved Profiles:[/cyan]")
+        for name, data in profiles.items():
+            console.print(f"  * [bold]{name}[/bold]: {data['url']}")
+        chosen = Prompt.ask("Enter profile name or full database connection URL")
+        prof = config_mgr.get_profile(chosen)
+        if prof:
+            return prof["url"]
+        return chosen
+
+    url = Prompt.ask(
+        "Enter database URL (e.g. postgresql://user:pass@localhost:5432/mydb, or sqlite:///app.db, or mongo URL)"
+    )
+    return url
+
+
+def _confirm_callback(sql: str, warnings: List[str]) -> bool:
+    """Rich prompt for confirming write/ddl queries."""
+    console.print("\n[bold yellow]Generated SQL (requires confirmation):[/bold yellow]")
+    print_code(sql, "sql", "Review Query")
+    if warnings:
+        for w in warnings:
+            print_warning(w)
+    return Confirm.ask("[bold yellow]Execute this query?[/bold yellow]", default=False)
+
+
+def _choice_callback(prompt_text: str, choices: List[str]) -> Optional[str]:
+    """Rich prompt for resolving ambiguous table matches."""
+    console.print(f"\n[bold cyan]{prompt_text}[/bold cyan]")
+    for i, c in enumerate(choices, 1):
+        console.print(f"  [bold]{i}[/bold]. {c}")
+    console.print(f"  [bold]{len(choices) + 1}[/bold]. All of the above")
+    choice = Prompt.ask("Enter number", default="1")
+    try:
+        idx = int(choice)
+        if idx == len(choices) + 1:
+            return choices  # All
+        if 1 <= idx <= len(choices):
+            return choices[idx - 1]
+    except (ValueError, IndexError):
+        pass
+    # Try as direct table name
+    if choice in choices:
+        return choice
+    return choices[0]
+
+
+def _display_pipeline_result(result: PipelineResult, show_sql: bool = True) -> None:
+    """Display a pipeline result with SQL and results table."""
+    if result.error:
+        print_error(f"Error: {result.error}")
+        if result.sql:
+            console.print(f"[dim]Generated SQL:[/dim]")
+            print_code(result.sql, "sql", "Failed Query")
+        if result.retries > 0:
+            console.print(f"[dim](Retried {result.retries} time(s))[/dim]")
+        return
+
+    if result.was_executed:
+        # Show SQL in dim/collapsed form
+        if show_sql and result.sql:
+            console.print(f"[dim]SQL:[/dim] [dim italic]{result.sql.strip()}[/dim italic]")
+            console.print("")
+
+        if result.has_results:
+            print_results_table(result.columns, result.rows, title="Results")
+        else:
+            print_info("Query executed successfully. No rows returned.")
+
+        if result.retries > 0:
+            console.print(f"[dim](Auto-corrected after {result.retries} retry(ies))[/dim]")
+    elif result.needs_confirmation and not result.was_executed:
+        # User declined or no callback — just show SQL
+        if result.sql:
+            print_code(result.sql, "sql", f"Generated {result.query_type.upper()} Query")
+            console.print("[dim]This query was not executed (requires confirmation).[/dim]")
+    elif result.sql:
+        print_code(result.sql, "sql", "Generated SQL")
+
+
+# ---------------------------------------------------------------------------
+# CLI Commands
+# ---------------------------------------------------------------------------
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-v", help="Show DB-Agent version"),
+):
+    """DB-Agent CLI entry point."""
+    if version:
+        console.print(f"DB-Agent version [bold cyan]{__version__}[/bold cyan]")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        print_banner()
+        console.print("[dim]Run [bold]db-agent --help[/bold] to see all available commands, or [bold]db-agent chat[/bold] to start interactive mode.[/dim]\n")
+
+
+# ---- ask (flagship seamless command) ----
+
+@app.command(name="ask")
+def ask_command(
+    prompt: str = typer.Argument(..., help="Natural language question (e.g. 'show recent users')"),
+    db: Optional[str] = typer.Option(None, "--db", "-d", help="Database connection URL or profile alias"),
+    provider: Optional[str] = typer.Option(None, "--provider", "-p", help="LLM provider: ollama, gemini, groq, openrouter, mock"),
+    model: Optional[str] = typer.Option(None, "--model", "-m", help="Specific model name"),
+    force: bool = typer.Option(False, "--force", "-f", help="Force execute even write/DDL queries without confirmation"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Maximum rows to return"),
+    no_execute: bool = typer.Option(False, "--no-exec", help="Generate SQL only, don't execute"),
+    show_sql: bool = typer.Option(True, "--sql/--no-sql", help="Show generated SQL alongside results"),
+):
+    """
+    Ask a question in plain English — get database results instantly.
+    Works like a database CLI: generates SQL, validates, executes, and returns results.
+    Write/DDL queries require confirmation unless --force is passed.
+    """
+    print_banner()
+    db_url = resolve_db_url(db)
+
+    try:
+        connector = create_connector(db_url)
+        success, msg = connector.test_connection()
+        if not success:
+            print_error(msg)
+            raise typer.Exit(1)
+    except Exception as e:
+        print_error(f"Connection failed: {str(e)}")
+        raise typer.Exit(1)
+
+    llm = get_llm_provider(provider_name=provider, model=model, config_mgr=config_mgr)
+    print_info(f"Database: [bold]{connector.engine.url.database or db_url}[/bold] ({connector.engine.dialect.name}) | AI: [bold]{llm.name}[/bold]")
+    console.print(f"[bold cyan]>[/bold cyan] {prompt}\n")
+
+    pipeline = QueryPipeline(
+        connector=connector,
+        llm=llm,
+        model=model,
+        auto_execute=not no_execute,
+        confirm_callback=_confirm_callback if not force else None,
+        choice_callback=_choice_callback,
+    )
+
+    with console.status("[bold cyan]Thinking...[/bold cyan]"):
+        result = pipeline.run(user_prompt=prompt, force=force)
+
+    _display_pipeline_result(result, show_sql=show_sql)
+
+    connector.close()
+
+
+# ---- connect ----
+
+@app.command(name="connect")
+def connect_command(
+    db: str = typer.Argument(..., help="Database connection URL or file path"),
+    alias: Optional[str] = typer.Option(None, "--alias", "-a", help="Save this database connection under an alias profile name"),
+    scan: bool = typer.Option(False, "--scan", "-s", help="Scan and display full schema after connecting"),
+):
+    """Connect to a database, verify credentials, and save it under an alias name instantly."""
+    print_banner()
+    db_url = resolve_db_url(db)
+
+    with console.status("[bold cyan]Testing connection credentials...[/bold cyan]"):
+        try:
+            connector = create_connector(db_url)
+            success, msg = connector.test_connection()
+            if not success:
+                print_error(msg)
+                raise typer.Exit(1)
+            print_success(msg)
+
+            if alias:
+                config_mgr.save_profile(name=alias, connection_url=db_url, description=f"Alias for {db_url}")
+                print_success(f"Saved connection profile as alias '[bold cyan]{alias}[/bold cyan]'!")
+                console.print(f"[dim]You can now use this alias in any command: [bold]db-agent ask 'your question' --db {alias}[/bold][/dim]\n")
+
+            if scan:
+                with console.status("[bold cyan]Scanning schema...[/bold cyan]"):
+                    schema = connector.inspect_schema(include_samples=True, max_samples=2)
+                    SchemaViewer.display_schema_summary(schema)
+        except Exception as e:
+            print_error(f"Connection error: {str(e)}")
+            raise typer.Exit(1)
+        finally:
+            if "connector" in locals():
+                connector.close()
+
+
+# ---- scan ----
+
+@app.command(name="scan")
+def scan_command(
+    db: Optional[str] = typer.Option(None, "--db", "-d", help="Database connection URL or profile name"),
+    alias: Optional[str] = typer.Option(None, "--alias", "-a", help="Save this database connection under an alias profile name"),
+    table: Optional[str] = typer.Option(None, "--table", "-t", help="Specific table to drill into"),
+    export: Optional[str] = typer.Option(None, "--export", "-e", help="Export schema to file (.json or .md)"),
+    no_samples: bool = typer.Option(False, "--no-samples", help="Skip fetching sample rows"),
+    counts: bool = typer.Option(False, "--counts", "-c", help="Calculate exact table row counts (slower on large DBs)"),
+):
+    """Scan and introspect database schema, tables, columns, constraints, and relationships."""
+    print_banner()
+    db_url = resolve_db_url(db)
+
+    with console.status("[bold cyan]Connecting and introspecting database schema...[/bold cyan]"):
+        try:
+            connector = create_connector(db_url)
+            success, msg = connector.test_connection()
+            if not success:
+                print_error(msg)
+                raise typer.Exit(1)
+
+            if alias:
+                config_mgr.save_profile(name=alias, connection_url=db_url, description=f"Alias for {db_url}")
+                print_success(f"Saved connection profile as alias '[bold cyan]{alias}[/bold cyan]'!")
+
+            target_tables = [table] if table else None
+            schema = connector.inspect_schema(
+                table_names=target_tables,
+                include_samples=not no_samples,
+                max_samples=3,
+                include_row_counts=counts,
+            )
+        except Exception as e:
+            print_error(f"Failed to scan database: {str(e)}")
+            raise typer.Exit(1)
+        finally:
+            if "connector" in locals():
+                connector.close()
+
+    print_success(f"Successfully introspected database [bold]{schema.database_name}[/bold] ({schema.dialect_name})")
+
+    if table:
+        tbl_model = schema.get_table(table)
+        if not tbl_model:
+            print_error(f"Table '{table}' not found in database.")
+            raise typer.Exit(1)
+        SchemaViewer.display_table_detail(tbl_model)
+    else:
+        SchemaViewer.display_schema_summary(schema)
+
+    if export:
+        out_path = Path(export)
+        if out_path.suffix.lower() == ".json":
+            out_path.write_text(schema.model_dump_json(indent=2), encoding="utf-8")
+        else:
+            out_path.write_text(SchemaFormatter.to_markdown(schema), encoding="utf-8")
+        print_success(f"Schema catalog exported to [bold]{out_path}[/bold]")
+
+
+# ---- generate (full explanatory mode) ----
+
+@app.command(name="generate")
+def generate_command(
+    prompt: str = typer.Argument(..., help="Natural language description of what script/query to generate"),
+    db: Optional[str] = typer.Option(None, "--db", "-d", help="Database connection URL or profile name"),
+    alias: Optional[str] = typer.Option(None, "--alias", "-a", help="Save this database connection under an alias profile name"),
+    type: str = typer.Option("auto", "--type", "-t", help="Script type: auto, sql, migration, etl, api, optimization"),
+    provider: Optional[str] = typer.Option(None, "--provider", "-p", help="LLM provider: ollama, gemini, groq, openrouter, mock"),
+    model: Optional[str] = typer.Option(None, "--model", "-m", help="Specific model name"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Save generated code directly to file path"),
+    run: bool = typer.Option(False, "--run", "-r", help="Immediately execute generated SQL query if safe"),
+):
+    """Generate dialect-specific SQL queries, migrations, ETL scripts, or APIs with full explanations."""
+    print_banner()
+    db_url = resolve_db_url(db)
+
+    with console.status("[bold cyan]Fetching relevant table schema on demand...[/bold cyan]"):
+        try:
+            connector = create_connector(db_url)
+            if alias:
+                config_mgr.save_profile(name=alias, connection_url=db_url, description=f"Alias for {db_url}")
+                print_success(f"Saved connection profile as alias '[bold cyan]{alias}[/bold cyan]'!")
+            schema = connector.inspect_targeted(user_prompt=prompt, max_tables=10, include_samples=True)
+        except Exception as e:
+            print_error(f"Introspection failed: {str(e)}")
+            raise typer.Exit(1)
+
+    llm = get_llm_provider(provider_name=provider, model=model, config_mgr=config_mgr)
+    print_info(f"Target Database: [bold]{schema.database_name}[/bold] ({schema.dialect_name}) | AI Provider: [bold]{llm.name}[/bold]")
+    console.print(f"[bold cyan]Prompt:[/bold cyan] {prompt}\n")
+
+    generator = ScriptGenerator(llm)
+    console.print("[bold green]Generated Script / Solution:[/bold green]\n")
+    try:
+        response = generator.generate_script(
+            schema=schema,
+            user_prompt=prompt,
+            script_type=type,
+            model=model,
+            stream_callback=lambda chunk: console.print(chunk, end=""),
+        )
+        console.print("\n")
+    except Exception as e:
+        print_error(f"AI Generation failed: {str(e)}")
+        raise typer.Exit(1)
+
+    code_block = generator.extract_code_block(response)
+
+    if output and code_block:
+        out_path = Path(output)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(code_block, encoding="utf-8")
+        print_success(f"Generated code saved to [bold]{out_path}[/bold]")
+
+    if run and code_block:
+        is_safe, warnings = ScriptValidator.analyze_safety(code_block)
+        if not is_safe:
+            for w in warnings:
+                print_warning(w)
+            if not Confirm.ask("Do you want to proceed with executing this query?"):
+                console.print("[dim]Execution cancelled.[/dim]")
+                return
+
+        with console.status("[bold cyan]Executing query...[/bold cyan]"):
+            cols, rows, err = connector.execute_query(code_block, limit=50)
+            if err:
+                print_error(f"Query execution error: {err}")
+            else:
+                print_results_table(cols, rows)
+
+    connector.close()
+
+
+# ---- chat (interactive REPL with auto-execute) ----
+
+@app.command(name="chat")
+def chat_command(
+    db: Optional[str] = typer.Option(None, "--db", "-d", help="Database connection URL or profile name"),
+    alias: Optional[str] = typer.Option(None, "--alias", "-a", help="Save this database connection under an alias profile name"),
+    provider: Optional[str] = typer.Option(None, "--provider", "-p", help="LLM provider: ollama, gemini, groq, openrouter"),
+    model: Optional[str] = typer.Option(None, "--model", "-m", help="Specific model name"),
+):
+    """Interactive database CLI — type questions in English, get results instantly. Auto-executes reads."""
+    print_banner()
+    db_url = resolve_db_url(db)
+
+    with console.status("[bold cyan]Connecting to database...[/bold cyan]"):
+        try:
+            connector = create_connector(db_url)
+            success, msg = connector.test_connection()
+            if not success:
+                print_error(msg)
+                raise typer.Exit(1)
+            if alias:
+                config_mgr.save_profile(name=alias, connection_url=db_url, description=f"Alias for {db_url}")
+                print_success(f"Saved connection profile as alias '[bold cyan]{alias}[/bold cyan]'!")
+            # Get table count for display
+            table_names = connector.get_table_names()
+        except Exception as e:
+            print_error(f"Connection failed: {str(e)}")
+            raise typer.Exit(1)
+
+    llm = get_llm_provider(provider_name=provider, model=model, config_mgr=config_mgr)
+
+    db_name = connector.engine.url.database or db_url
+    dialect = connector.engine.dialect.name
+    console.print(f"[bold green]Connected:[/bold green] {db_name} ({dialect}) - {len(table_names)} tables")
+    console.print(f"[bold cyan]AI:[/bold cyan] {llm.name}")
+    console.print("[dim]Type your question in plain English. Read queries auto-execute. Write queries ask for confirmation.[/dim]")
+    console.print("[dim]Commands: [bold]:tables[/bold] | [bold]:table <name>[/bold] | [bold]:explain[/bold] | [bold]:history[/bold] | [bold]:auto[/bold]/[bold]:noauto[/bold] | [bold]:run[/bold] | [bold]:export <file>[/bold] | [bold]:exit[/bold][/dim]\n")
+
+    history_file = config_mgr.config_dir / "chat_history.txt"
+    session = PromptSession(history=FileHistory(str(history_file)))
+
+    auto_execute = True
+    query_history: List[PipelineResult] = []
+    last_result: Optional[PipelineResult] = None
+
+    while True:
+        try:
+            user_input = session.prompt("db-agent> ").strip()
+            if not user_input:
+                continue
+
+            # --- REPL commands ---
+            if user_input.lower() in [":exit", ":quit", "exit", "quit", "q"]:
+                console.print("[bold cyan]Goodbye![/bold cyan]")
+                break
+
+            if user_input.lower() in [":tables", ":schema", "\\d", "\\dt"]:
+                with console.status("[bold cyan]Fetching schema...[/bold cyan]"):
+                    schema = connector.inspect_schema(include_samples=False, max_samples=0, include_row_counts=False)
+                SchemaViewer.display_schema_summary(schema)
+                continue
+
+            if user_input.startswith(":table "):
+                tname = user_input.split(" ", 1)[1].strip()
+                with console.status(f"[bold cyan]Inspecting {tname}...[/bold cyan]"):
+                    on_demand_schema = connector.inspect_schema(table_names=[tname], include_samples=True)
+                tmodel = on_demand_schema.get_table(tname)
+                if tmodel:
+                    SchemaViewer.display_table_detail(tmodel)
+                else:
+                    print_error(f"Table '{tname}' not found.")
+                continue
+
+            if user_input.lower() == ":explain":
+                if last_result and last_result.sql:
+                    print_code(last_result.sql, "sql", "Last Executed SQL")
+                    console.print(f"[dim]Query type: {last_result.query_type} | Intent: {last_result.intent} | Retries: {last_result.retries}[/dim]")
+                    if last_result.exact_tables:
+                        console.print(f"[dim]Tables (exact): {', '.join(last_result.exact_tables)}[/dim]")
+                    if last_result.fuzzy_tables:
+                        console.print(f"[dim]Tables (fuzzy): {', '.join(last_result.fuzzy_tables)}[/dim]")
+                else:
+                    print_warning("No previous query to explain.")
+                continue
+
+            if user_input.lower() == ":history":
+                if not query_history:
+                    print_warning("No query history in this session.")
+                    continue
+                for i, r in enumerate(query_history[-10:], 1):
+                    status = "[green]OK[/green]" if r.success else "[red]FAIL[/red]"
+                    sql_preview = (r.sql[:80] + "...") if len(r.sql) > 80 else r.sql
+                    console.print(f"  {i}. {status} [{r.query_type}] {sql_preview}")
+                continue
+
+            if user_input.lower() == ":auto":
+                auto_execute = True
+                print_success("Auto-execute enabled. Read queries will run automatically.")
+                continue
+
+            if user_input.lower() == ":noauto":
+                auto_execute = False
+                print_info("Auto-execute disabled. All queries will show SQL only. Use :run to execute.")
+                continue
+
+            if user_input.lower() == ":run":
+                if not last_result or not last_result.sql:
+                    print_warning("No generated SQL query to run.")
+                    continue
+                if last_result.was_executed:
+                    # Re-run the last query
+                    console.print("[dim]Re-executing last query...[/dim]")
+                cols, rows, err = connector.execute_query(last_result.sql, limit=100)
+                if err:
+                    print_error(f"Execution error: {err}")
+                else:
+                    print_results_table(cols, rows)
+                continue
+
+            if user_input.startswith(":export "):
+                file_target = user_input.split(" ", 1)[1].strip()
+                if not last_result or not last_result.sql:
+                    print_warning("No code block to export.")
+                    continue
+                p = Path(file_target)
+                p.parent.mkdir(parents=True, exist_ok=True)
+                p.write_text(last_result.sql, encoding="utf-8")
+                print_success(f"SQL saved to {p}")
+                continue
+
+            # --- Natural language query via pipeline ---
+            pipeline = QueryPipeline(
+                connector=connector,
+                llm=llm,
+                model=model,
+                auto_execute=auto_execute,
+                confirm_callback=_confirm_callback,
+                choice_callback=_choice_callback,
+            )
+
+            with console.status("[bold cyan]Thinking...[/bold cyan]"):
+                result = pipeline.run(user_prompt=user_input)
+
+            _display_pipeline_result(result, show_sql=True)
+
+            last_result = result
+            query_history.append(result)
+
+        except (KeyboardInterrupt, EOFError):
+            console.print("\n[bold cyan]Session closed.[/bold cyan]")
+            break
+        except Exception as e:
+            print_error(f"Error: {str(e)}")
+
+    connector.close()
+
+
+# ---- run (direct SQL execution) ----
+
+@app.command(name="run")
+def run_command(
+    query: str = typer.Argument(..., help="SQL query to execute directly"),
+    db: Optional[str] = typer.Option(None, "--db", "-d", help="Database connection URL or profile name"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Maximum rows to fetch"),
+    force: bool = typer.Option(False, "--force", "-f", help="Bypass safety confirmation"),
+):
+    """Directly execute a SQL query on the target database and format output as a rich table."""
+    db_url = resolve_db_url(db)
+    connector = create_connector(db_url)
+
+    is_safe, warnings = ScriptValidator.analyze_safety(query)
+    if not is_safe and not force:
+        for w in warnings:
+            print_warning(w)
+        if not Confirm.ask("Are you sure you want to execute this potentially modifying query?"):
+            console.print("[dim]Execution cancelled.[/dim]")
+            connector.close()
+            return
+
+    with console.status("[bold cyan]Executing query...[/bold cyan]"):
+        cols, rows, err = connector.execute_query(query, limit=limit)
+
+    connector.close()
+
+    if err:
+        print_error(f"Execution failed: {err}")
+        raise typer.Exit(1)
+
+    print_results_table(cols, rows)
+
+
+# ---- config ----
+
+@app.command(name="config")
+def config_command():
+    """Interactive wizard to configure AI providers and database connection profiles."""
+    print_banner()
+    console.print("[bold cyan]DB-Agent Configuration Wizard[/bold cyan]\n")
+
+    curr_provider = config_mgr.get_setting("default_provider", "ollama")
+    console.print(f"Current Default AI Provider: [bold green]{curr_provider}[/bold green]")
+    provider_choice = Prompt.ask(
+        "Select Default AI Provider",
+        choices=["ollama", "gemini", "groq", "openrouter", "keep"],
+        default="keep",
+    )
+    if provider_choice != "keep":
+        config_mgr.set_setting("default_provider", provider_choice)
+        print_success(f"Default provider updated to [bold]{provider_choice}[/bold]")
+
+    if provider_choice == "gemini" or Prompt.ask("Configure Google Gemini API key (Free Tier)?", choices=["y", "n"], default="n") == "y":
+        key = Prompt.ask("Enter GEMINI_API_KEY (leave blank to skip)", default="")
+        if key:
+            config_mgr.set_setting("gemini_api_key", key)
+            print_success("Gemini API key saved.")
+
+    if provider_choice == "groq" or Prompt.ask("Configure Groq API key (Free Tier)?", choices=["y", "n"], default="n") == "y":
+        key = Prompt.ask("Enter GROQ_API_KEY (leave blank to skip)", default="")
+        if key:
+            config_mgr.set_setting("groq_api_key", key)
+            print_success("Groq API key saved.")
+
+    if provider_choice == "openrouter" or Prompt.ask("Configure OpenRouter API key (Free Tier)?", choices=["y", "n"], default="n") == "y":
+        key = Prompt.ask("Enter OPENROUTER_API_KEY (leave blank to skip)", default="")
+        if key:
+            config_mgr.set_setting("openrouter_api_key", key)
+            print_success("OpenRouter API key saved.")
+
+    if Prompt.ask("\nAdd a new database connection profile?", choices=["y", "n"], default="n") == "y":
+        p_name = Prompt.ask("Profile Name (e.g. prod_pg, staging, local_dev)")
+        p_url = Prompt.ask("Connection URL (e.g. postgresql://user:pass@localhost:5432/dbname)")
+        p_desc = Prompt.ask("Description", default=f"{p_name} database")
+        config_mgr.save_profile(name=p_name, connection_url=p_url, description=p_desc)
+        print_success(f"Profile '[bold]{p_name}[/bold]' saved successfully!")
+
+
+# ---- profiles ----
+
+@app.command(name="profiles")
+def profiles_command():
+    """List all saved database connection profiles."""
+    profiles = config_mgr.list_profiles()
+    if not profiles:
+        console.print("[dim]No database profiles saved yet. Run [bold]db-agent config[/bold] to add one.[/dim]")
+        return
+
+    table = Table(title="[Profiles] Saved Database Profiles", show_header=True, header_style="bold cyan", border_style="dim")
+    table.add_column("Profile Name", style="bold white")
+    table.add_column("Connection URL", style="cyan")
+    table.add_column("Description", style="dim")
+
+    for name, p in profiles.items():
+        table.add_row(name, p["url"], p.get("description", ""))
+
+    console.print(table)
+
+
+# ---- models ----
+
+@app.command(name="models")
+def models_command():
+    """List available models across local Ollama and free cloud providers."""
+    print_banner()
+    console.print("[bold cyan]Supported Free & Standalone LLMs:[/bold cyan]\n")
+
+    ollama = get_llm_provider("ollama")
+    ollama_status = "[green]ONLINE (Ready)[/green]" if ollama.is_available() else "[red]OFFLINE (Run 'ollama serve')[/red]"
+    console.print(f"1. [bold white]Ollama (100% Local, Offline & Zero-Cost)[/bold white] - Status: {ollama_status}")
+    if ollama.is_available():
+        models = ollama.list_models()
+        console.print(f"   Installed Local Models: {', '.join(models) if models else 'None'}")
+    else:
+        console.print("   Recommended models: `ollama run qwen2.5-coder` or `ollama run llama3.2`")
+
+    gemini = get_llm_provider("gemini")
+    gemini_status = "[green]Configured[/green]" if gemini.is_available() else "[yellow]Not Configured (Free Key: aistudio.google.com)[/yellow]"
+    console.print(f"\n2. [bold white]Google Gemini (Free Tier)[/bold white] - Status: {gemini_status}")
+    console.print("   Available Models: `gemini-2.0-flash`, `gemini-1.5-flash`, `gemini-1.5-pro`")
+
+    groq = get_llm_provider("groq")
+    groq_status = "[green]Configured[/green]" if groq.is_available() else "[yellow]Not Configured (Free Key: console.groq.com)[/yellow]"
+    console.print(f"\n3. [bold white]Groq (Free Ultra-Fast Tier)[/bold white] - Status: {groq_status}")
+    console.print("   Available Models: `llama-3.3-70b-versatile`, `qwen-2.5-32b`")
+
+    openrouter = get_llm_provider("openrouter")
+    openrouter_status = "[green]Configured[/green]" if openrouter.is_available() else "[yellow]Not Configured (openrouter.ai)[/yellow]"
+    console.print(f"\n4. [bold white]OpenRouter (Free Community Models)[/bold white] - Status: {openrouter_status}")
+    console.print("   Available Models: `meta-llama/llama-3.3-70b-instruct:free`, `qwen/qwen-2.5-coder-32b-instruct:free`\n")
+
+
+# ---- setup ----
+
+@app.command(name="setup")
+def setup_command(
+    model: str = typer.Option("qwen2.5-coder:1.5b", "--model", "-m", help="Ollama model to install"),
+):
+    """Automatically download, install, start, and configure Ollama for 100% standalone offline AI."""
+    print_banner()
+    console.print("[bold cyan]DB-Agent Standalone AI Engine Setup[/bold cyan]\n")
+    console.print("[dim]This will ensure Ollama is installed, running, and has a local code model ready.[/dim]\n")
+
+    from dbagent.llm.auto_setup import ensure_ollama_ready
+
+    def _log(msg, level="info"):
+        if level == "success":
+            print_success(msg)
+        elif level == "warning":
+            print_warning(msg)
+        elif level == "error":
+            print_error(msg)
+        elif level == "progress":
+            console.print(f"[dim]{msg}[/dim]")
+        else:
+            print_info(msg)
+
+    success, message = ensure_ollama_ready(model=model, print_fn=_log)
+    if success:
+        config_mgr.set_setting("default_provider", "ollama")
+        print_success(message)
+        console.print("\n[bold green]You're all set![/bold green] DB-Agent is now 100% standalone and ready to run queries.\n")
+    else:
+        print_error(message)
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()