Metadata-Version: 2.4
Name: sage-ai-cli
Version: 0.1.0
Summary: SageCLI - AI Engineering Agent for Machine Learning & Deep Learning
Author-email: zaheerjklabs <zaheerjklabs@gmail.com>
License: MIT
Keywords: ai,cli,machine-learning,deep-learning,agent,engineering
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: prompt-toolkit>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# SageCLI

```text
 ███████╗    █████╗     ██████╗    ███████╗
 ██╔════╝   ██╔══██╗   ██╔════╝    ██╔════╝
 ███████╗   ███████║   ██║  ███╗   █████╗
 ╚════██║   ██╔══██║   ██║   ██║   ██╔══╝
 ███████║   ██║  ██║   ╚██████╔╝   ███████╗
 ╚══════╝   ╚═╝  ╚═╝    ╚═════╝    ╚══════╝

              S A G E C L I
        AI ENGINEERING AGENT
```

> **Build • Train • Debug • Evaluate • Deploy**

SageCLI is a terminal-native autonomous AI coding agent designed specifically for **Machine Learning, Deep Learning, and AI Engineering**. Running directly inside your terminal, SageCLI autonomously inspects repositories and datasets, plans modular architectures, writes and executes code, runs tests, self-debugs tracebacks, computes metrics, and sets up inference endpoints.

---

## 🚀 Autonomous Agent Workflow

```text
User Prompt
    ↓
Context / Repository & Dataset Ingestion
    ↓
Planning & Architecture Phase
    ↓
Code Generation (PyTorch, Scikit-Learn, LightGBM, FastAPI)
    ↓
Execution & Pipeline Run
    ↓
Automated Testing & Autonomous Traceback Debugging
    ↓
Model Evaluation & Metric Tracking
    ↓
Documentation & Git Checkpoints
```

---

## 🛠️ Key Capabilities

* **First-Run Interactive Setup Wizard (`sage setup`)**: Multi-provider auto-detection, masked credential entry, model selection, mode choice, and live connection verification.
* **Provider-Agnostic Engine**: Native tool-calling support for:
  * **Google Gemini** (`gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`)
  * **OpenAI** (`gpt-4o`, `gpt-4o-mini`, `o3-mini`, `o1`)
  * **Anthropic Claude** (`claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-haiku`)
  * **Groq** (`llama-3.3-70b-versatile`, `deepseek-r1-distill-llama-70b`)
  * **OpenRouter** (`deepseek/deepseek-r1`, etc.)
  * **Ollama (Local)** (`llama3.2`, `deepseek-r1`, `qwen2.5-coder`)
  * **Custom OpenAI-compatible endpoints** (vLLM, LocalAI, LM Studio)
* **ML/DL Engineering Tool Suite**:
  * `inspect_dataset`: Deep EDA on CSV, Parquet, JSON, NumPy, Excel files (shapes, missing values, statistics, class distribution).
  * `read_file` / `write_file` / `patch_file` / `list_directory`: Surgical and sandboxed workspace file operations.
  * `execute_command`: Shell command and Python script execution with timeouts and security checks.
  * `run_tests`: Pytest runner with failure analysis and traceback extraction.
  * `git_checkpoint` / `git_diff` / `git_rollback`: Version control safety and rollback support.
* **Self-Healing & Autonomous Debugging**: When scripts fail with errors (e.g., shape mismatches, missing modules, runtime exceptions), SageCLI intercepts the stderr/stack trace, diagnoses the cause, patches the code, and re-executes until verified.
* **Execution Modes**:
  * `Safe` (Default) — Requests user approval before running write or shell operations.
  * `Auto` — Autonomously executes safe workspace steps, prompting only for destructive actions.
  * `Plan` — Generates comprehensive plans and diffs without modifying files on disk.
* **State & Memory Management**: Persists conversation history, task memory, dataset metadata, and ML experiment metrics in `.sage/` (automatically added to `.gitignore`).

---

## 📦 Installation

### From PyPI
```bash
pip install sage-ai-cli
```

### From Source (Development)
```bash
# Clone the repository
git clone https://github.com/zaheerjklabs/SageCLI.git
cd SageCLI

# Install in editable mode
pip install -e .
```

---

## ⚡ Quickstart

### 1. Launch SageCLI
```bash
sage
```
On first launch, the interactive setup wizard will guide you through provider selection and credential validation.

### 2. Interactive Engineering Prompt
```text
sage ❯ Build a customer churn prediction system using data/raw/customers.csv with XGBoost and a FastAPI endpoint.
```

SageCLI will:
1. 🔍 **Inspect** `data/raw/customers.csv` and report feature distributions.
2. 📐 **Plan** modular components (`src/data.py`, `src/model.py`, `src/train.py`, `src/app.py`).
3. 💻 **Implement** clean preprocessing, feature engineering, and model training.
4. ⚡ **Execute** the pipeline and self-debug any runtime errors.
5. 📊 **Evaluate** ROC-AUC, Precision/Recall, and log metrics.
6. 🚀 **Deliver** test suites and a FastAPI inference service.

---

## 🎮 Interactive Slash Commands (`/`)

SageCLI provides an intuitive, Claude Code-inspired command palette with autocompletion and instant dropdown help:

| Command | Action | Description |
| :--- | :--- | :--- |
| `/help` | Detailed help manual | View all commands, shortcuts, and capabilities |
| `/setup` | Setup wizard | Interactive multi-provider and API key configuration |
| `/config` | View/edit settings | Show active configuration or update with `/config set <key> <val>` |
| `/mode <safe\|auto\|plan>` | Switch execution mode | `Safe` (confirm writes), `Auto` (full autonomous), `Plan` (read-only) |
| `/model [name]` | Switch LLM model | Switch model or view recommended options |
| `/provider [name]` | Switch AI provider | `gemini`, `openai`, `anthropic`, `groq`, `openrouter`, `ollama` |
| `/doctor` | Environment diagnostics | Inspect Python, GPU/CUDA, Git repo, disk space, and API latency |
| `/cost` / `/usage` | Token & cost tracking | Display session token usage and estimated USD cost breakdown |
| `/context` | Workspace summary | Review detected directory tree, datasets, and ML stack |
| `/memory` | Session task memory | Display or reset active task history and persistent state |
| `/dataset <path>` | EDA & Data Profiling | Analyze dataset shape, missing values, statistics, and distributions |
| `/diff` | Git diff | View uncommitted code modifications |
| `/checkpoint <msg>` | Git checkpoint | Create an immediate snapshot commit |
| `/rollback` | Git rollback | Revert workspace changes safely |
| `/compact` | Memory compaction | Compact session history to save token context window |
| `/ascii` | Toggle ASCII mode | Switch between Unicode and pure ASCII terminal glyphs |
| `/demo` | Status language demo | Preview SageCLI's branded status symbols and styling |
| `/clear` | Clear screen | Clear terminal view while preserving session state |
| `/exit` / `/quit` | Exit | Exit SageCLI session |

---

## 🏗️ Architecture

```text
src/sagecli/
├── __init__.py           # Package version and brand definitions
├── __main__.py           # python -m sagecli entry point
├── cli.py                # Typer application, CLI flags, and interactive REPL
├── config.py             # Multi-provider hierarchical configuration
├── security.py           # Secret masking, sandboxing, and safety checks
├── wizard.py             # First-run interactive setup wizard
├── core/
│   ├── agent.py          # Autonomous agent execution loop
│   ├── state.py          # Project memory, task history, and metrics in .sage/
│   ├── context.py        # Workspace scanner, dataset detector, and environment specs
│   └── orchestrator.py   # Multi-role prompt engineering for ML/DL pipelines
├── llm/
│   ├── base.py           # Provider interface and message models
│   ├── factory.py        # Dynamic provider factory
│   ├── gemini_provider.py# Google Gemini provider
│   ├── openai_provider.py# OpenAI / Groq / OpenRouter / Ollama provider
│   └── anthropic_provider.py # Anthropic Claude provider
├── tools/
│   ├── base.py           # Tool base class and schemas
│   ├── registry.py       # Tool registry and permission dispatcher
│   ├── file_ops.py       # Read, write, patch, list files
│   ├── shell_ops.py      # Terminal command and script execution
│   ├── dataset_ops.py    # Exploratory data analysis & schema inspection
│   ├── test_eval_ops.py  # Pytest execution and failure parser
│   └── git_ops.py        # Git checkpoints, diffs, and rollbacks
└── ui/
    ├── banner.py         # Startup banner, splash, metadata table
    ├── console.py        # Branded visual language formatters
    ├── logo.py           # ASCII logo and responsive renderers
    ├── prompts.py        # Interactive prompt_toolkit session
    ├── symbols.py        # Unicode & ASCII symbols
    └── theme.py          # SageCLI palette and Rich styles
```

---

## 🧪 Testing

Run the full automated test suite with:

```bash
python3 -m pytest -v
```
