seekdb-cli 0.1.0__tar.gz

seekdb_cli-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: seekdb-cli
+Version: 0.1.0
+Summary: AI-Agent-friendly database CLI for seekdb / OceanBase
+Author: David Zhang
+License: MIT
+Project-URL: Homepage, https://github.com/oceanbase/seekdb-ecology-plugins
+Project-URL: Repository, https://github.com/oceanbase/seekdb-ecology-plugins
+Project-URL: Issues, https://github.com/oceanbase/seekdb-ecology-plugins/issues
+Keywords: seekdb,database,cli,ai-agent,oceanbase
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: pymysql>=1.0
+Requires-Dist: pyseekdb>=0.1
+Requires-Dist: openai>=1.0
+
+# seekdb-cli
+
+Command-line client for seekdb / OceanBase, built for AI agents. Default JSON output, stateless invocations, and a consistent error format make it easy for agents to run SQL, inspect schema, manage vector collections, and use in-database AI models reliably.
+
+## Why seekdb-cli
+
+- **Agent-friendly**: Any agent that can run shell commands can use seekdb-cli via the `seekdb` command; output is JSON by default, and the `seekdb ai-guide` command provides a self-description of seekdb-cli usage for agents.
+- **Safety**: Row limits, write guards, and masking reduce risk when agents or scripts operate on live data.
+- **Unified interface**: One CLI for remote and embedded, SQL and vector collections, plus in-database AI, without interactive prompts or session state.
+
+## Features
+
+- **JSON by default**: All commands emit structured JSON; use `--format table|csv|jsonl` for human-readable output.
+- **Row limits**: LIMIT required when result exceeds 100 rows.
+- **Write safeguards**: Writes require `--write`; DELETE/UPDATE without WHERE and DROP/TRUNCATE are disallowed.
+- **Sensitive-field masking**: Columns such as phone, email, password, id_card are auto-masked in query results.
+- **Operation history**: All commands are logged to `~/.seekdb/sql-history.jsonl`; for **SQL execution**, the SQL text is logged with sensitive literals redacted.
+- **Database AI**: Manage models and endpoints via DBMS_AI_SERVICE; use AI_COMPLETE for completion.
+
+## Requirements
+
+- Python 3.11+
+- seekdb / OceanBase (or any MySQL-protocol–compatible server)
+
+## Installation
+
+```bash
+pip install seekdb-cli
+```
+
+After installation, the `seekdb` command is available.
+
+## Connection
+
+Set the DSN via environment variable or global option (**global options must appear before the subcommand**):
+
+```bash
+# Remote
+export SEEKDB_DSN="seekdb://user:pass@host:port/database"
+
+# Embedded (local directory, no separate server)
+export SEEKDB_DSN="embedded:./seekdb.db"
+export SEEKDB_DSN="embedded:./data?database=mydb"
+
+# Or pass per invocation
+seekdb --dsn "seekdb://root:@127.0.0.1:2881/test" status
+```
+
+## Common commands
+
+| Command | Description |
+|--------|-------------|
+| `seekdb status` | Connection status and version |
+| `seekdb schema tables` | List all tables |
+| `seekdb schema describe <table>` | Table structure (columns, types, indexes) |
+| `seekdb schema dump` | Output DDL for all tables (to stdout) |
+| `seekdb table profile <table>` | Table data profile (row count, nulls, distinct, min/max, candidate JOIN keys and time columns) |
+| `seekdb sql "<stmt>"` | Execute SQL (read-only by default; use `--write` for writes; `--with-schema` adds table schema; `--no-truncate` keeps large fields intact) |
+| `seekdb relations infer [--table <t>]` | Infer JOIN relationships between tables |
+| `seekdb collection list \| create \| delete \| info` | Vector collection management |
+| `seekdb query <coll> --text "<query>" [--mode semantic\|fulltext\|hybrid]` | Search a collection |
+| `seekdb get <coll> [--ids ...] [--limit n]` | Get documents by ID or condition |
+| `seekdb add <coll> (--file \| --stdin \| --data)` | Add data to a collection |
+| `seekdb export <coll> --output <path>` | Export collection data |
+| `seekdb ai model list \| create \| delete` | AI model management (DBMS_AI_SERVICE) |
+| `seekdb ai model endpoint create \| delete` | Create or delete AI model endpoints |
+| `seekdb ai complete "<prompt>" --model <name>` | In-database AI completion (AI_COMPLETE) |
+| `seekdb ai-guide` | Print structured guide for AI agents (JSON) |
+
+## Option order
+
+`--dsn` and `--format` are global options and must appear **before** the subcommand:
+
+```bash
+seekdb --format table sql "SELECT * FROM t LIMIT 5"
+seekdb --dsn "seekdb://root:@127.0.0.1:2881/test" schema tables
+```

seekdb_cli-0.1.0/README.md

@@ -0,0 +1,77 @@
+# seekdb-cli
+
+Command-line client for seekdb / OceanBase, built for AI agents. Default JSON output, stateless invocations, and a consistent error format make it easy for agents to run SQL, inspect schema, manage vector collections, and use in-database AI models reliably.
+
+## Why seekdb-cli
+
+- **Agent-friendly**: Any agent that can run shell commands can use seekdb-cli via the `seekdb` command; output is JSON by default, and the `seekdb ai-guide` command provides a self-description of seekdb-cli usage for agents.
+- **Safety**: Row limits, write guards, and masking reduce risk when agents or scripts operate on live data.
+- **Unified interface**: One CLI for remote and embedded, SQL and vector collections, plus in-database AI, without interactive prompts or session state.
+
+## Features
+
+- **JSON by default**: All commands emit structured JSON; use `--format table|csv|jsonl` for human-readable output.
+- **Row limits**: LIMIT required when result exceeds 100 rows.
+- **Write safeguards**: Writes require `--write`; DELETE/UPDATE without WHERE and DROP/TRUNCATE are disallowed.
+- **Sensitive-field masking**: Columns such as phone, email, password, id_card are auto-masked in query results.
+- **Operation history**: All commands are logged to `~/.seekdb/sql-history.jsonl`; for **SQL execution**, the SQL text is logged with sensitive literals redacted.
+- **Database AI**: Manage models and endpoints via DBMS_AI_SERVICE; use AI_COMPLETE for completion.
+
+## Requirements
+
+- Python 3.11+
+- seekdb / OceanBase (or any MySQL-protocol–compatible server)
+
+## Installation
+
+```bash
+pip install seekdb-cli
+```
+
+After installation, the `seekdb` command is available.
+
+## Connection
+
+Set the DSN via environment variable or global option (**global options must appear before the subcommand**):
+
+```bash
+# Remote
+export SEEKDB_DSN="seekdb://user:pass@host:port/database"
+
+# Embedded (local directory, no separate server)
+export SEEKDB_DSN="embedded:./seekdb.db"
+export SEEKDB_DSN="embedded:./data?database=mydb"
+
+# Or pass per invocation
+seekdb --dsn "seekdb://root:@127.0.0.1:2881/test" status
+```
+
+## Common commands
+
+| Command | Description |
+|--------|-------------|
+| `seekdb status` | Connection status and version |
+| `seekdb schema tables` | List all tables |
+| `seekdb schema describe <table>` | Table structure (columns, types, indexes) |
+| `seekdb schema dump` | Output DDL for all tables (to stdout) |
+| `seekdb table profile <table>` | Table data profile (row count, nulls, distinct, min/max, candidate JOIN keys and time columns) |
+| `seekdb sql "<stmt>"` | Execute SQL (read-only by default; use `--write` for writes; `--with-schema` adds table schema; `--no-truncate` keeps large fields intact) |
+| `seekdb relations infer [--table <t>]` | Infer JOIN relationships between tables |
+| `seekdb collection list \| create \| delete \| info` | Vector collection management |
+| `seekdb query <coll> --text "<query>" [--mode semantic\|fulltext\|hybrid]` | Search a collection |
+| `seekdb get <coll> [--ids ...] [--limit n]` | Get documents by ID or condition |
+| `seekdb add <coll> (--file \| --stdin \| --data)` | Add data to a collection |
+| `seekdb export <coll> --output <path>` | Export collection data |
+| `seekdb ai model list \| create \| delete` | AI model management (DBMS_AI_SERVICE) |
+| `seekdb ai model endpoint create \| delete` | Create or delete AI model endpoints |
+| `seekdb ai complete "<prompt>" --model <name>` | In-database AI completion (AI_COMPLETE) |
+| `seekdb ai-guide` | Print structured guide for AI agents (JSON) |
+
+## Option order
+
+`--dsn` and `--format` are global options and must appear **before** the subcommand:
+
+```bash
+seekdb --format table sql "SELECT * FROM t LIMIT 5"
+seekdb --dsn "seekdb://root:@127.0.0.1:2881/test" schema tables
+```

seekdb_cli-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seekdb-cli"
+version = "0.1.0"
+description = "AI-Agent-friendly database CLI for seekdb / OceanBase"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "David Zhang"}
+]
+keywords = ["seekdb", "database", "cli", "ai-agent", "oceanbase"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+]
+
+dependencies = [
+    "click>=8.0",
+    "pymysql>=1.0",
+    "pyseekdb>=0.1",
+    "openai>=1.0",
+]
+
+[project.scripts]
+seekdb = "seekdb_cli.main:cli"
+
+[project.urls]
+Homepage = "https://github.com/oceanbase/seekdb-ecology-plugins"
+Repository = "https://github.com/oceanbase/seekdb-ecology-plugins"
+Issues = "https://github.com/oceanbase/seekdb-ecology-plugins/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

seekdb_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

seekdb_cli-0.1.0/src/seekdb_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

seekdb_cli-0.1.0/src/seekdb_cli/commands/ai.py

@@ -0,0 +1,306 @@
+"""seekdb ai command — use database AI (DBMS_AI_SERVICE, AI_COMPLETE)."""
+
+from __future__ import annotations
+
+import json
+
+import click
+import pymysql
+
+from seekdb_cli import output
+from seekdb_cli.connection import get_connection
+from seekdb_cli.logger import log_operation
+
+# OceanBase AI model types (for CREATE_AI_MODEL)
+AI_MODEL_TYPES = ("dense_embedding", "completion", "rerank")
+
+
+@click.group("ai")
+@click.pass_context
+def ai_cmd(ctx: click.Context) -> None:
+    """AI model management and completion (via database DBMS_AI_SERVICE)."""
+
+
+# ---------------------------------------------------------------------------
+# seekdb ai model ...
+# ---------------------------------------------------------------------------
+
+@ai_cmd.group("model")
+@click.pass_context
+def model_group(ctx: click.Context) -> None:
+    """Manage AI models registered in the database (DBMS_AI_SERVICE)."""
+
+
+@model_group.command("list")
+@click.pass_context
+def model_list(ctx: click.Context) -> None:
+    """List all registered AI models (from oceanbase.DBA_OB_AI_MODELS)."""
+    fmt: str = ctx.obj["format"]
+    dsn: str | None = ctx.obj["dsn"]
+
+    try:
+        conn = get_connection(dsn)
+    except Exception as exc:
+        log_operation("ai model list", ok=False, error_code="CONNECTION_ERROR")
+        output.error("CONNECTION_ERROR", str(exc), fmt=fmt)
+        return
+
+    timer = output.Timer()
+    try:
+        with timer, conn.cursor() as cur:
+            cur.execute(
+                "SELECT MODEL_ID, NAME, TYPE, MODEL_NAME "
+                "FROM oceanbase.DBA_OB_AI_MODELS ORDER BY NAME"
+            )
+            rows = cur.fetchall()
+            # DictCursor: keys may be uppercase from view
+            result = []
+            for r in rows:
+                row = dict(r)
+                result.append({
+                    "name": row.get("NAME") or row.get("name"),
+                    "type": row.get("TYPE") or row.get("type"),
+                    "model_name": row.get("MODEL_NAME") or row.get("model_name"),
+                    "model_id": row.get("MODEL_ID") or row.get("model_id"),
+                })
+
+        log_operation("ai model list", ok=True, time_ms=timer.elapsed_ms)
+        output.success(result, time_ms=timer.elapsed_ms, fmt=fmt)
+    except pymysql.err.ProgrammingError as exc:
+        log_operation("ai model list", ok=False, error_code="SQL_ERROR")
+        output.error(
+            "SQL_ERROR",
+            str(exc) + ". Ensure the database supports DBA_OB_AI_MODELS (OceanBase AI).",
+            fmt=fmt,
+        )
+    except pymysql.err.Error as exc:
+        log_operation("ai model list", ok=False, error_code="SQL_ERROR")
+        output.error("SQL_ERROR", str(exc), fmt=fmt)
+    finally:
+        conn.close()
+
+
+@model_group.command("create")
+@click.argument("name")
+@click.option(
+    "--type",
+    "model_type",
+    type=click.Choice(AI_MODEL_TYPES),
+    required=True,
+    help="Model type: dense_embedding, completion, or rerank.",
+)
+@click.option(
+    "--model",
+    "provider_model_name",
+    required=True,
+    help="Provider model name (e.g. BAAI/bge-m3, THUDM/GLM-4-9B-0414).",
+)
+@click.pass_context
+def model_create(
+    ctx: click.Context,
+    name: str,
+    model_type: str,
+    provider_model_name: str,
+) -> None:
+    """Register an AI model via DBMS_AI_SERVICE.CREATE_AI_MODEL. Create an endpoint separately to use it."""
+    fmt: str = ctx.obj["format"]
+    dsn: str | None = ctx.obj["dsn"]
+
+    try:
+        conn = get_connection(dsn)
+    except Exception as exc:
+        log_operation("ai model create", ok=False, error_code="CONNECTION_ERROR")
+        output.error("CONNECTION_ERROR", str(exc), fmt=fmt)
+        return
+
+    config = json.dumps({"type": model_type, "model_name": provider_model_name})
+    timer = output.Timer()
+    try:
+        with timer, conn.cursor() as cur:
+            cur.execute(
+                "CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(%s, %s)",
+                (name, config),
+            )
+            conn.commit()
+
+        log_operation("ai model create", ok=True, time_ms=timer.elapsed_ms)
+        output.success(
+            {"name": name, "type": model_type, "model_name": provider_model_name},
+            time_ms=timer.elapsed_ms,
+            fmt=fmt,
+        )
+    except pymysql.err.Error as exc:
+        log_operation("ai model create", ok=False, error_code="SQL_ERROR")
+        output.error("SQL_ERROR", str(exc), fmt=fmt)
+    finally:
+        conn.close()
+
+
+@model_group.command("delete")
+@click.argument("name")
+@click.pass_context
+def model_delete(ctx: click.Context, name: str) -> None:
+    """Drop an AI model via DBMS_AI_SERVICE.DROP_AI_MODEL. Drop endpoints first if any."""
+    fmt: str = ctx.obj["format"]
+    dsn: str | None = ctx.obj["dsn"]
+
+    try:
+        conn = get_connection(dsn)
+    except Exception as exc:
+        log_operation("ai model delete", ok=False, error_code="CONNECTION_ERROR")
+        output.error("CONNECTION_ERROR", str(exc), fmt=fmt)
+        return
+
+    timer = output.Timer()
+    try:
+        with timer, conn.cursor() as cur:
+            cur.execute("CALL DBMS_AI_SERVICE.DROP_AI_MODEL(%s)", (name,))
+            conn.commit()
+
+        log_operation("ai model delete", ok=True, time_ms=timer.elapsed_ms)
+        output.success({"deleted": name}, time_ms=timer.elapsed_ms, fmt=fmt)
+    except pymysql.err.Error as exc:
+        log_operation("ai model delete", ok=False, error_code="SQL_ERROR")
+        output.error("SQL_ERROR", str(exc), fmt=fmt)
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# seekdb ai model endpoint ...
+# ---------------------------------------------------------------------------
+
+@model_group.group("endpoint")
+@click.pass_context
+def endpoint_group(ctx: click.Context) -> None:
+    """Create or delete AI model endpoints (DBMS_AI_SERVICE)."""
+
+
+@endpoint_group.command("create")
+@click.argument("endpoint_name")
+@click.argument("ai_model_name")
+@click.option("--url", required=True, help="API URL (e.g. https://api.siliconflow.cn/v1/chat/completions).")
+@click.option("--access-key", required=True, help="API key for the service.")
+@click.option("--provider", default="siliconflow", help="Provider name (siliconflow, openai, dashscope, etc.).")
+@click.pass_context
+def endpoint_create(
+    ctx: click.Context,
+    endpoint_name: str,
+    ai_model_name: str,
+    url: str,
+    access_key: str,
+    provider: str,
+) -> None:
+    """Create an AI model endpoint via DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT."""
+    fmt: str = ctx.obj["format"]
+    dsn: str | None = ctx.obj["dsn"]
+
+    try:
+        conn = get_connection(dsn)
+    except Exception as exc:
+        log_operation("ai model endpoint create", ok=False, error_code="CONNECTION_ERROR")
+        output.error("CONNECTION_ERROR", str(exc), fmt=fmt)
+        return
+
+    config = json.dumps({
+        "ai_model_name": ai_model_name,
+        "url": url,
+        "access_key": access_key,
+        "provider": provider,
+    })
+    timer = output.Timer()
+    try:
+        with timer, conn.cursor() as cur:
+            cur.execute(
+                "CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT(%s, %s)",
+                (endpoint_name, config),
+            )
+            conn.commit()
+
+        log_operation("ai model endpoint create", ok=True, time_ms=timer.elapsed_ms)
+        output.success(
+            {"endpoint": endpoint_name, "ai_model": ai_model_name, "provider": provider},
+            time_ms=timer.elapsed_ms,
+            fmt=fmt,
+        )
+    except pymysql.err.Error as exc:
+        log_operation("ai model endpoint create", ok=False, error_code="SQL_ERROR")
+        output.error("SQL_ERROR", str(exc), fmt=fmt)
+    finally:
+        conn.close()
+
+
+@endpoint_group.command("delete")
+@click.argument("endpoint_name")
+@click.pass_context
+def endpoint_delete(ctx: click.Context, endpoint_name: str) -> None:
+    """Drop an AI model endpoint via DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT."""
+    fmt: str = ctx.obj["format"]
+    dsn: str | None = ctx.obj["dsn"]
+
+    try:
+        conn = get_connection(dsn)
+    except Exception as exc:
+        log_operation("ai model endpoint delete", ok=False, error_code="CONNECTION_ERROR")
+        output.error("CONNECTION_ERROR", str(exc), fmt=fmt)
+        return
+
+    timer = output.Timer()
+    try:
+        with timer, conn.cursor() as cur:
+            cur.execute(
+                "CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT(%s)",
+                (endpoint_name,),
+            )
+            conn.commit()
+
+        log_operation("ai model endpoint delete", ok=True, time_ms=timer.elapsed_ms)
+        output.success({"deleted": endpoint_name}, time_ms=timer.elapsed_ms, fmt=fmt)
+    except pymysql.err.Error as exc:
+        log_operation("ai model endpoint delete", ok=False, error_code="SQL_ERROR")
+        output.error("SQL_ERROR", str(exc), fmt=fmt)
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# seekdb ai complete ...
+# ---------------------------------------------------------------------------
+
+@ai_cmd.command("complete")
+@click.argument("prompt")
+@click.option("--model", "model_name", required=True, help="Registered completion model name (from ai model list).")
+@click.pass_context
+def ai_complete(ctx: click.Context, prompt: str, model_name: str) -> None:
+    """Run text completion using the database AI_COMPLETE function."""
+    fmt: str = ctx.obj["format"]
+    dsn: str | None = ctx.obj["dsn"]
+
+    try:
+        conn = get_connection(dsn)
+    except Exception as exc:
+        log_operation("ai complete", ok=False, error_code="CONNECTION_ERROR")
+        output.error("CONNECTION_ERROR", str(exc), fmt=fmt)
+        return
+
+    timer = output.Timer()
+    try:
+        with timer, conn.cursor() as cur:
+            cur.execute(
+                "SELECT AI_COMPLETE(%s, %s) AS response",
+                (model_name, prompt),
+            )
+            row = cur.fetchone()
+        response_text = (row.get("response") or row.get("RESPONSE") or "") if row else ""
+
+        log_operation("ai complete", ok=True, time_ms=timer.elapsed_ms)
+        output.success(
+            {"model": model_name, "response": response_text},
+            time_ms=timer.elapsed_ms,
+            fmt=fmt,
+        )
+    except pymysql.err.Error as exc:
+        log_operation("ai complete", ok=False, error_code="AI_ERROR")
+        output.error("AI_ERROR", str(exc), fmt=fmt)
+    finally:
+        conn.close()