Metadata-Version: 2.5
Name: pisces-cli
Version: 0.1.2
Summary: AI-assisted,self healing human-governed Python security remediation patcher
Project-URL: Homepage, https://github.com/richochetclementine1315/pisces
Project-URL: Repository, https://github.com/richochetclementine1315/pisces
Project-URL: Issues, https://github.com/richochetclementine1315/pisces/issues
Author-email: Mrinmoy Matilal <mrinmoymatilal1315@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,cli,llm,patcher,python,scanner,security,static-analysis,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.28.0
Requires-Dist: bandit>=1.7.0
Requires-Dist: google-generativeai>=0.7.0
Requires-Dist: groq>=0.9.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.22.0
Requires-Dist: openai>=1.30.0
Requires-Dist: rich>=13.7.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.12.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://github.com/user-attachments/assets/66723bfc-b15b-44bb-8dfa-cc74ff298ade"
       width="280"
       height="100"
       alt="Pisces Banner">
</p>

<h1 align="center">PISCES</h1>

<p align="center">
  <b>AI-Assisted · Self-Healing · Human-Governed Python Security Remediation Patcher</b>
</p>

<p align="center">
  <a href="https://pypi.org/project/pisces-cli/">
    <img src="https://img.shields.io/pypi/v/pisces-cli?color=7c3aed&logo=pypi&logoColor=white&label=PyPI" alt="PyPI Version">
  </a>
  <a href="https://pypi.org/project/pisces-cli/">
    <img src="https://img.shields.io/pypi/pyversions/pisces-cli?color=0ea5e9&logo=python&logoColor=white" alt="Python Versions">
  </a>
  <a href="https://github.com/richochetclementine1315/pisces/actions/workflows/ci.yml">
    <img src="https://github.com/richochetclementine1315/pisces/actions/workflows/ci.yml/badge.svg" alt="CI Status">
  </a>
  <a href="https://github.com/richochetclementine1315/pisces/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-22c55e?logo=opensourceinitiative&logoColor=white" alt="License: MIT">
  </a>
  <a href="https://github.com/richochetclementine1315/pisces/blob/main/pyproject.toml">
    <img src="https://img.shields.io/badge/build-hatchling-f97316?logo=pypa&logoColor=white" alt="Build: Hatchling">
  </a>
  <img src="https://img.shields.io/badge/linter-ruff-db2777?logo=ruff&logoColor=white" alt="Linter: Ruff">
  <img src="https://img.shields.io/badge/type--checked-mypy-2563eb?logo=python&logoColor=white" alt="Type Checked: mypy">
</p>

## Overview

Pisces is a Python security CLI that detects common vulnerabilities, explains
findings with an LLM, proposes minimal patches, validates them with your test
suite, and rolls them back when validation fails. Source changes remain
human-approved by default.

## Key Features

- AST-first and regex-fallback security scanning.
- Seven built-in rules for secrets, command injection, unsafe subprocesses,
  unsafe deserialization, disabled TLS verification, code injection, and
  dangerous filesystem operations.
- Excludes `.venv`, `__pycache__`, and other irrelevant directories.
- LLM explanations with source snippets and AST context.
- Human-in-the-loop patch approval.
- Atomic patching, checkpoints, rollback, and self-healing retries.
- Local repair history and a debounced watch mode.
- OpenAI, Anthropic, Gemini, Groq, Ollama, and LM Studio support.

## ⚙️ How it Works

<p align="center">
  <img
    width="450"
    alt="How Pisces Works — Scan to History"
    src="https://github.com/user-attachments/assets/7f421fd1-c12a-48f6-bc34-46794d67e958"
  />
</p>

## ⚙️ The Repair State Machine

<p align="center">
  <img
    width="450"
    alt="How Pisces Works — Scan to History"
    src="https://github.com/user-attachments/assets/319ae541-a87e-4f91-a860-112660c77873"
  />
</p>

## Installation

Pisces requires Python 3.10 or newer.

```bash
pip install pisces-cli
```

## Quick Usage

```bash
pisces init
pisces config
pisces scan .
pisces explain path/to/file.py:42
pisces fix path/to/file.py:42
pisces history
```

Set the API key for the provider configured in `pisces.toml`, for example:

```bash
export GROQ_API_KEY="your-key"
```

On Windows PowerShell:

```powershell
$env:GROQ_API_KEY = "your-key"
```

Ollama and LM Studio use local endpoints and do not require an API key.

## Configuration

Run `pisces init` to create a project configuration:

```toml
[llm]
provider = "groq"
model = "llama-3.3-70b-versatile"

[repair]
max_attempts = 3
require_approval = true

[validation]
test_command = "pytest"

[scan]
exclude = [
    ".git",
    ".venv",
    "venv",
    "__pycache__",
    "node_modules",
    ".pisces",
    "dist",
    "build",
]
```

Do not put API keys in this file. Use environment variables instead.

## CLI Reference

| Command | Purpose |
|---|---|
| `pisces init [PATH]` | Initialize `pisces.toml` and `.pisces/`. |
| `pisces config [PATH] --show` | Configure or display project settings. |
| `pisces scan [TARGET] -o FILE -s LEVEL` | Scan a directory or Python file. |
| `pisces explain FILE:LINE` | Explain a cached finding with an LLM. |
| `pisces fix FILE:LINE` | Generate, approve, apply, and validate a patch. |
| `pisces watch [PATH]` | Update project context as files change. |
| `pisces history [PATH]` | Browse repair records and diffs. |
| `pisces --version` | Show the installed version. |

`pisces fix` also supports `--dry-run`, `--no-judge`, and
`--max-attempts N`. `pisces scan` returns exit code `1` when findings meet
the selected severity threshold.

## Built-in Security Rules

| Rule | ID | Severity | Detects |
|---|---|---|---|
| Hardcoded Secret | `S001` | HIGH | API keys, passwords, and tokens |
| Command Injection | `S002` | CRITICAL | Dynamic `shell=True` subprocess calls |
| Unsafe Subprocess | `S003` | HIGH | `shell=True` subprocess calls |
| Unsafe Deserialization | `S004` | HIGH | Unsafe pickle, marshal, or YAML loading |
| TLS Verify Disabled | `S005` | MEDIUM | Network calls using `verify=False` |
| Code Injection | `S006` | CRITICAL | Dynamic `eval()` or `exec()` |
| Dangerous Filesystem | `S007` | MEDIUM | Destructive operations on variable paths |

## Architecture and Workflow
<p align="center">
  <img
    width="680"
    alt="Pisces Security Remediation Workflow"
    src="https://github.com/user-attachments/assets/c463cbf3-73f8-4c5e-b251-f1acd6ab1b86"
  />
</p>

The workflow covers project initialization, deterministic security scanning, LLM-powered explanations and patch generation, human approval, checkpointing, test validation, rollback, and self-healing retries.

The deterministic scanner does not call an LLM. LLMs are used for explanations, patch generation, and optional patch judging. Source changes require human approval by default.

The deterministic scanner does not call an LLM. LLMs are used for explanations,
patch generation, and optional patch judging.

## Links

- **GitHub:** https://github.com/richochetclementine1315/pisces
- **Issues:** https://github.com/richochetclementine1315/pisces/issues
- **PyPI:** https://pypi.org/project/pisces-cli/

## License

MIT © [Mrinmoy Matilal](https://github.com/richochetclementine1315/pisces)
