Metadata-Version: 2.4
Name: psycgod-sage
Version: 2.6.0
Summary: Local-first command wrapper for AI coding agents with compressed terminal output and privacy-safe proof metrics.
Author: PsYcGoD
License-Expression: MIT
Project-URL: Homepage, https://github.com/PsYcGoD/sage
Project-URL: Repository, https://github.com/PsYcGoD/sage
Project-URL: Issues, https://github.com/PsYcGoD/sage/issues
Project-URL: Dashboard, https://sage.api.marketingstudios.in/dashboard
Keywords: ai,cli,terminal,debugging,local assistant,terminal agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: joblib>=1.3
Requires-Dist: keyring>=25
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0
Requires-Dist: PyYAML>=6
Requires-Dist: scikit-learn>=1.3
Requires-Dist: tiktoken>=0.7
Requires-Dist: websockets>=13.0
Provides-Extra: ml
Requires-Dist: sentence-transformers>=3.0.0; extra == "ml"
Requires-Dist: faiss-cpu>=1.8.0; extra == "ml"
Requires-Dist: torch>=2.0.0; extra == "ml"
Provides-Extra: ai
Requires-Dist: anthropic>=0.40; extra == "ai"
Requires-Dist: boto3>=1.34; extra == "ai"
Requires-Dist: google-generativeai>=0.8; extra == "ai"
Requires-Dist: openai>=1.50; extra == "ai"
Requires-Dist: requests>=2.31; extra == "ai"
Provides-Extra: tui
Requires-Dist: textual>=0.80; extra == "tui"
Requires-Dist: httpx>=0.27; extra == "tui"
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == "all"
Requires-Dist: boto3>=1.34; extra == "all"
Requires-Dist: google-generativeai>=0.8; extra == "all"
Requires-Dist: openai>=1.50; extra == "all"
Requires-Dist: requests>=2.31; extra == "all"
Requires-Dist: sentence-transformers>=3.0.0; extra == "all"
Requires-Dist: faiss-cpu>=1.8.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: textual>=0.80; extra == "all"
Requires-Dist: httpx>=0.27; extra == "all"
Dynamic: license-file

# SAGE - Smart Agent Guidance Engine

[![CI](https://github.com/PsYcGoD/sage/actions/workflows/ci.yml/badge.svg)](https://github.com/PsYcGoD/sage/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/PsYcGoD/sage/blob/main/pyproject.toml)
[![PyPI](https://img.shields.io/pypi/v/psycgod-sage.svg)](https://pypi.org/project/psycgod-sage/)
[![npm](https://img.shields.io/npm/v/psycgod-sage.svg)](https://www.npmjs.com/package/psycgod-sage)
[![License](https://img.shields.io/github/license/PsYcGoD/sage.svg)](https://github.com/PsYcGoD/sage/blob/main/LICENSE)

SAGE is a local-first command wrapper for AI coding agents. It keeps full terminal output on your machine, sends agents a clean compressed summary, and tracks proof metrics without uploading your raw logs.

Use it with Claude Code, Codex, Cursor, Windsurf, OpenCode, Cline, custom agents, CI scripts, and normal terminal workflows.

## Start Here: Install SAGE, Use once sage run -- python -m pytest, Then Use Any AI Agent

Package installation is passive for package-registry safety. After installing, run `sage install` once to connect this machine and activate SAGE for supported local AI agents.

### PyPI / pip

```powershell
pip install psycgod-sage
# or
python -m pip install --upgrade psycgod-sage
sage install
sage run -- python -m pytest
```

### npm / npx

```bash
npm install -g psycgod-sage
npx -y psycgod-sage install
npx -y psycgod-sage run -- npm test
```

After install, restart any open AI-agent sessions. New sessions should read the SAGE instructions automatically and route terminal commands through SAGE.

Example prompt after restarting your AI agent:

```text
Please help me with my general book in this folder.
```

Natural shortcuts also work:

```bash
sage pytest
sage npm test
sage git status
```

These are treated as:

```bash
sage run -- pytest
sage run -- npm test
sage run -- git status
```

## What SAGE Does

| Step | Result |
|---|---|
| `sage install` | Connects the machine, repairs global/project agent instructions, and verifies activation |
| `sage run -- <command>` | Runs the command, stores raw output locally, and returns a compact useful summary |
| Agent memory/hooks | Tell supported AI agents to use SAGE for noisy terminal work |
| Local database | Keeps command history, compression proof, and retry context on the user's machine |
| Optional cloud proof | Sends aggregate metrics only when connected proof mode is enabled |

SAGE does not auto-enable MCP. MCP is optional and manual for users who want it.

## Live Proof

Latest pulled stats as of 2026-08-01:

| Metric | Value |
|---|---:|
| SAGE telemetry command events | 27,892 |
| Tokens processed | 799.5M |
| Tokens saved | 783.7M |
| Compression rate | 98.02% |
| Estimated savings | $16,261.90 |
| Command success rate | 88.3% |
| PyPI downloads, last 7 days | 632 |
| npm downloads, last 7 days | 362 |
| GitHub clones, last 14 days | 574 |

Live dashboard: [sage.api.marketingstudios.in/dashboard](https://sage.api.marketingstudios.in/dashboard)
Install page: [sage.api.marketingstudios.in/install](https://sage.api.marketingstudios.in/install)

![SAGE public proof dashboard](docs/assets/sage-live-dashboard.png)

## Why It Helps

AI coding agents burn context on repeated logs, failed test output, install noise, stack traces, and build spam. SAGE sits between the command and the agent.

| Without SAGE | With SAGE |
|---|---|
| Agent sees full noisy terminal output | Agent sees the useful summary |
| Context disappears fast | Context lasts longer |
| Repeated failures waste tokens | Errors are grouped and explained |
| Raw logs may enter prompts | Raw logs stay local |
| Hard to prove savings | SAGE records proof metrics |

## Distribution

| Channel | Package | Status |
|---|---|---|
| PyPI | [`psycgod-sage`](https://pypi.org/project/psycgod-sage/) | Canonical Python package |
| npm / npx | [`psycgod-sage`](https://www.npmjs.com/package/psycgod-sage) | Node launcher for the Python core |
| MCP Registry | `io.github.PsYcGoD/sage` | Optional/manual MCP entry |
| Glama | [`PsYcGoD/sage`](https://glama.ai/mcp/servers/PsYcGoD/sage) | Optional/manual hosted MCP listing |

The npm package delegates to the Python implementation so both install paths use the same local database, telemetry rules, compression, and command behavior.

## Common Commands

```bash
sage install                       # Activate this machine and AI-agent instructions
sage doctor --activation           # Verify activation
npx -y psycgod-sage doctor --activation
sage run -- <command>              # Wrap any command
sage run --cwd /project -- <command> # Explicit workspace for desktop/Electron hosts
sage pytest                        # Shortcut for: sage run -- pytest
sage npm test                      # Shortcut for: sage run -- npm test
sage git status                    # Shortcut for: sage run -- git status
sage context stats                 # Token savings summary
sage context report                # Full compression report
sage history --limit 10            # Recent command history
sage explain --failed              # Explain the latest failed command
sage suggest --failed              # Suggest the next fix
sage fix --apply                   # Try an automatic fix
sage ml setup                      # Optional ML V2 dependencies
sage mcp install                   # Optional/manual MCP config
sage dashboard start               # Local dashboard
```

## Privacy Modes

| Mode | Requires login? | Sends data? | What leaves the machine? |
|---|---:|---:|---|
| Local-only | No | No | Nothing |
| Connected proof | Machine auth | Yes | Aggregate counters and proof metrics |
| Debug telemetry | Optional | Opt-in only | Redacted diagnostic summaries |

SAGE is designed to keep prompts, source code, credentials, raw command output, and project files local unless the user deliberately enables a feature that requires sending data.

## Known Limitations

| Limitation | What To Do |
|---|---|
| Already-open AI-agent sessions may not reload new instructions | Restart Claude/Codex/Cursor/Windsurf/OpenCode after `sage install` |
| Locked-down host apps can disable shell tools | SAGE cannot enable tools the host application has blocked |
| A desktop/Electron host starts its shell in the wrong folder | Pass `sage run --cwd <project> -- <command>` or set `SAGE_WORKSPACE_CWD` |
| npm/PyPI installs cannot safely auto-run activation | Run `sage install` once after package install |
| MCP can disconnect in some stdio agent sessions | Use normal `sage run -- <command>` by default; enable MCP manually only if needed |
| Package installs are passive by design | Real activation starts with `sage install` |

## Demos

| Flow | Preview |
|---|---|
| PyPI install | ![PyPI install flow](docs/assets/sage-install-pypi.gif) |
| npm install | ![npm install flow](docs/assets/sage-install-npm.gif) |
| `sage run --` | ![sage run](https://raw.githubusercontent.com/PsYcGoD/sage/main/docs/assets/sage-run.svg) |
| CLI run | ![SAGE CLI demo](https://raw.githubusercontent.com/PsYcGoD/sage/main/docs/assets/demo-sage-run.gif) |

## Team View Preview - Enterprise Only

Team View is not part of the free public CLI package. It is a future enterprise dashboard concept for organizations that need shared usage proof, team-level savings, and admin reporting.

![SAGE Team View preview](docs/assets/team-dashboard-preview.png)

## Links

- Landing: [sage.api.marketingstudios.in](https://sage.api.marketingstudios.in/)
- Dashboard: [sage.api.marketingstudios.in/dashboard](https://sage.api.marketingstudios.in/dashboard)
- Install guide: [sage.api.marketingstudios.in/install](https://sage.api.marketingstudios.in/install)
- PyPI: [pypi.org/project/psycgod-sage](https://pypi.org/project/psycgod-sage/)
- npm: [npmjs.com/package/psycgod-sage](https://www.npmjs.com/package/psycgod-sage)

## License

MIT. See [LICENSE](LICENSE).
