pandexai 0.0.1 → 0.1.0

package/SKILL.md

@@ -0,0 +1,22 @@
+# PandexAI
+
+PandexAI is an AI-native data profiling CLI. It runs inside AI coding CLIs
+(Claude Code, Cursor, etc.) to handle deterministic data work as real code,
+and hands the AI clean, structured output to reason over.
+
+## Core rule: judgment vs execution
+
+- Execution (deterministic): anything that computes numbers from data MUST
+  run as real Python/pandas code in scripts/. Never let the AI estimate or
+  guess statistics, column types, null counts, or any other figure that a
+  script can compute exactly.
+- Judgment (AI): interpreting results, flagging likely issues, suggesting
+  next steps, and writing human-readable summaries is the AI's job.
+
+This split exists so PandexAI's numbers are always trustworthy: they come
+from real computation, not a language model's guess.
+
+## Available commands
+
+- scan - profiles a CSV file (columns, types, null %, unique counts, basic
+  stats). See commands/scan.md for exact instructions.

package/bin/pandex.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+const { execSync, spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command !== "init") {
+  console.log("Usage: npx pandex init");
+  process.exit(1);
+}
+
+const cwd = process.cwd();
+const venvDir = path.join(cwd, ".pandex", "venv");
+
+function findPython() {
+  for (const name of ["python3", "python"]) {
+    const result = spawnSync(name, ["--version"], { stdio: "ignore" });
+    if (result.status === 0) return name;
+  }
+  return null;
+}
+
+console.log("Setting up PandexAI...");
+
+const pythonCmd = findPython();
+if (!pythonCmd) {
+  console.error("ERROR: No Python installation found on your PATH.");
+  console.error("PandexAI needs Python 3 to run its data profiling scripts.");
+  console.error("Install Python from https://python.org and try again.");
+  process.exit(1);
+}
+console.log(`Found Python: ${pythonCmd}`);
+
+if (!fs.existsSync(venvDir)) {
+  console.log("Creating virtual environment at .pandex/venv ...");
+  const venvResult = spawnSync(pythonCmd, ["-m", "venv", venvDir], { stdio: "inherit" });
+  if (venvResult.status !== 0) {
+    console.error("ERROR: Failed to create virtual environment.");
+    process.exit(1);
+  }
+} else {
+  console.log(".pandex/venv already exists, skipping creation.");
+}
+
+const isWindows = process.platform === "win32";
+const venvPython = isWindows
+  ? path.join(venvDir, "Scripts", "python.exe")
+  : path.join(venvDir, "bin", "python");
+
+console.log("Installing pandas into the virtual environment...");
+const installResult = spawnSync(venvPython, ["-m", "pip", "install", "--quiet", "pandas"], { stdio: "inherit" });
+if (installResult.status !== 0) {
+  console.error("ERROR: Failed to install pandas.");
+  process.exit(1);
+}
+
+const packageRoot = path.join(__dirname, "..");
+const filesToCopy = ["SKILL.md", "commands", "scripts"];
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+console.log("Copying PandexAI files into your project...");
+for (const item of filesToCopy) {
+  const src = path.join(packageRoot, item);
+  const dest = path.join(cwd, item);
+  if (fs.existsSync(src)) {
+    copyRecursive(src, dest);
+  }
+}
+
+console.log("");
+console.log("PandexAI is ready. Try: /pandex scan <your-file.csv> inside your AI CLI.");

package/commands/scan.md

@@ -0,0 +1,21 @@
+# scan
+
+Profiles a CSV file: column types, null percentage, unique counts, and
+basic stats (mean/median/min/max for numeric columns, top value counts for
+categorical columns).
+
+## How to run this command
+
+1. Run: python scripts/profile.py <path-to-csv>
+   (use the project's .pandex/venv Python interpreter, not the system one)
+2. The script prints a JSON object with the profiling results.
+3. Do NOT recompute, estimate, or guess any of these numbers yourself.
+   Present the JSON results to the user in a clear, readable summary, and
+   flag anything that looks like a data quality issue (e.g. high null %,
+   suspicious types, low-cardinality columns that might be categorical).
+
+## Example
+
+user runs: /pandex scan sales.csv
+-> python scripts/profile.py sales.csv
+-> present the resulting JSON as a readable summary

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "pandexai",
-  "version": "0.0.1",
-  "description": "PandexAI — AI-native data profiling CLI. Placeholder release, full version coming soon.",
+  "version": "0.1.0",
+  "description": "PandexAI - AI-native data profiling CLI. Run pandex init inside your project to get started.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jahirulanik/pandexai.git"
   },
-  "keywords": ["pandas", "data", "cli", "ai"]
-}
+  "keywords": ["pandas", "data", "cli", "ai"],
+  "bin": {
+    "pandex": "./bin/pandex.js"
+  },
+  "files": [
+    "bin",
+    "SKILL.md",
+    "commands",
+    "scripts"
+  ]
+}

package/scripts/profile.py

@@ -0,0 +1,58 @@
+import sys
+import json
+import pandas as pd
+
+
+def profile_csv(path):
+    df = pd.read_csv(path)
+    result = {
+        "file": path,
+        "row_count": len(df),
+        "column_count": len(df.columns),
+        "columns": {}
+    }
+
+    for col in df.columns:
+        series = df[col]
+        col_info = {
+            "dtype": str(series.dtype),
+            "null_count": int(series.isnull().sum()),
+            "null_percent": round(float(series.isnull().mean() * 100), 2),
+            "unique_count": int(series.nunique())
+        }
+
+        if pd.api.types.is_numeric_dtype(series):
+            col_info["mean"] = _safe_float(series.mean())
+            col_info["median"] = _safe_float(series.median())
+            col_info["min"] = _safe_float(series.min())
+            col_info["max"] = _safe_float(series.max())
+        else:
+            top_values = series.value_counts().head(5)
+            col_info["top_values"] = {str(k): int(v) for k, v in top_values.items()}
+
+        result["columns"][col] = col_info
+
+    return result
+
+
+def _safe_float(value):
+    try:
+        if pd.isna(value):
+            return None
+        return round(float(value), 4)
+    except (TypeError, ValueError):
+        return None
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print(json.dumps({"error": "Usage: python profile.py <path-to-csv>"}))
+        sys.exit(1)
+
+    csv_path = sys.argv[1]
+    try:
+        profile = profile_csv(csv_path)
+        print(json.dumps(profile, indent=2))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)