PyPI - pisces-cli - Versions diffs - 0.1.0__tar.gz → 0.1.2__tar.gz - Mend

pisces-cli 0.1.0tar.gz → 0.1.2tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

pisces_cli-0.1.2/PKG-INFO ADDED Viewed

@@ -0,0 +1,232 @@
+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)

{pisces_cli-0.1.0 → pisces_cli-0.1.2}/PYPI_README.md RENAMED Viewed

@@ -11,6 +11,26 @@
   <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
@@ -24,13 +44,33 @@ human-approved by default.
 - Seven built-in rules for secrets, command injection, unsafe subprocesses,
   unsafe deserialization, disabled TLS verification, code injection, and
   dangerous filesystem operations.
-- Excludes `.venv`, `.venv-test`, `.venv310`, and other `.venv*` directories.
+- 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.
@@ -125,24 +165,17 @@ the selected severity threshold.
 | 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>
-```mermaid
-flowchart TD
-    A[pisces scan] --> B[Discover project Python files]
-    B --> C[Exclude .venv* and configured paths]
-    C --> D[AST plus regex scanner]
-    D --> E[Findings cache]
-    E --> F[pisces explain or pisces fix]
-    F --> G[LLM context and response]
-    G --> H{Fix approved?}
-    H -- No --> I[No source change]
-    H -- Yes --> J[Checkpoint and atomically apply patch]
-    J --> K[Run configured tests]
-    K --> L{Pass?}
-    L -- Yes --> M[Repair history]
-    L -- No --> N[Rollback and retry]
-    N --> G
-```
+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.

{pisces_cli-0.1.0 → pisces_cli-0.1.2}/pisces/__init__.py RENAMED Viewed

@@ -1,6 +1,6 @@
 from __future__ import annotations
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __email__ = "mrinmoymatilal1315@gmail.com"
 __author__ = "Mrinmoy-Matilal"
 __license__ = "MIT"

{pisces_cli-0.1.0 → pisces_cli-0.1.2}/pisces/init_cmd.py RENAMED Viewed

@@ -3,7 +3,7 @@
 # Can be run multiple times(idempotent).abs
 # creates pisces.toml and the .pisces/ state directory
 # NEVER destructively overwrites without --force
-# Adds .pisces to .gitignore if it exists.abs
+# Adds Pisces-generated files to .gitignore.
 from __future__ import annotations
 import json
@@ -150,10 +150,10 @@ def _create_dir(path: Path) -> None:
         return False
-def _init_context_json(path: Path, project_root: Path, *, force: bool) -> None:
+def _init_context_json(path: Path, project_root: Path, *, force: bool) -> bool:
     if path.exists() and not force:
         print_step_ok("context.json already exists - skipping")
-        return
+        return True
     print_step_running("Writing context.json ...")
     try:
@@ -162,32 +162,46 @@ def _init_context_json(path: Path, project_root: Path, *, force: bool) -> None:
             encoding="utf-8",
         )
         print_step_ok("context.json initialized")
+        return True
     except OSError as e:
         print_step_fail(f"Could not write context.json: {e}")
+        return False
 def _update_gitignore(project_root: Path) -> None:
-    """Ensure .pisces/ is listed in .gitignore."""
+    """Ensure Pisces-generated files are listed in .gitignore."""
     gitignore = project_root / ".gitignore"
-    entry = ".pisces/"
+    entries = (".pisces/", "pisces.toml")
     if not gitignore.exists():
-        print_step_running("No .ignore found - creating one ...")
+        print_step_running("No .gitignore found - creating one ...")
         try:
-            gitignore.write_text(f"# pisces state directory\n{entry}\n", encoding="utf-8")
-            print_step_ok(".gitignore created with .pisces/entry")
+            gitignore.write_text(
+                "# pisces generated files\n"
+                + "".join(f"{entry}\n" for entry in entries),
+                encoding="utf-8",
+            )
+            print_step_ok(".gitignore created with Pisces entries")
         except OSError as e:
-            print_warning(f"could not create .gitignore: {e}")
+            print_warning(f"Could not create .gitignore: {e}")
+        return
+    try:
+        content = gitignore.read_text(encoding="utf-8")
+    except OSError as e:
+        print_warning(f"Could not read .gitignore: {e}")
         return
-    content = gitignore.read_text(encoding="utf-8")
-    if entry in content or ".pisces" in content:
-        print_step_ok(".gitignore already contains .pisces entry - skipping")
+    existing_entries = {line.strip() for line in content.splitlines()}
+    missing_entries = [entry for entry in entries if entry not in existing_entries]
+    if not missing_entries:
+        print_step_ok(".gitignore already contains Pisces entries - skipping")
         return
     try:
         with gitignore.open("a", encoding="utf-8") as f:
-            f.write(f"\n# pisces state directory\n{entry}\n")
-        print_step_ok("Added .pisces/ to .gitignore")
+            f.write("\n# pisces generated files\n")
+            f.writelines(f"{entry}\n" for entry in missing_entries)
+        print_step_ok("Added Pisces entries to .gitignore")
     except OSError as e:
         print_warning(f"Could not update .gitignore: {e}")

{pisces_cli-0.1.0 → pisces_cli-0.1.2}/pisces/tui.py RENAMED Viewed

@@ -61,7 +61,7 @@ _BANNER_LINES = [
     ("  ╚═╝      ╚═╝ ╚══════╝  ╚═════╝  ╚══════╝ ╚══════╝ ", "bold blue"),
 ]
 _TAGLINE = "  AI-assisted Python Security · Detect · Patch · Validate · Self-Heal"
-_VERSION_LINE = "  v0.1.0  ·  MIT License  ·  pip install pisces"
+_VERSION_LINE = "  v0.1.2  ·  MIT License  ·  pip install pisces"
 def print_banner() -> None:

{pisces_cli-0.1.0 → pisces_cli-0.1.2}/pyproject.toml RENAMED Viewed

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 [project]
 name = "pisces-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "AI-assisted,self healing human-governed Python security remediation patcher"
-readme = "README.md"
+readme = "PYPI_README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
 authors = [

pisces_cli-0.1.2/tests/test_init_cmd.py ADDED Viewed

@@ -0,0 +1,34 @@
+from pathlib import Path
+from pisces.init_cmd import run_init
+def test_run_init_adds_generated_files_to_new_gitignore(tmp_path: Path) -> None:
+    assert run_init(tmp_path) == 0
+    gitignore = (tmp_path / ".gitignore").read_text(encoding="utf-8")
+    assert ".pisces/" in gitignore.splitlines()
+    assert "pisces.toml" in gitignore.splitlines()
+def test_run_init_adds_pisces_toml_to_existing_gitignore(tmp_path: Path) -> None:
+    (tmp_path / ".gitignore").write_text(".venv/\n", encoding="utf-8")
+    assert run_init(tmp_path) == 0
+    lines = (tmp_path / ".gitignore").read_text(encoding="utf-8").splitlines()
+    assert lines.count(".pisces/") == 1
+    assert lines.count("pisces.toml") == 1
+def test_run_init_does_not_duplicate_gitignore_entries(tmp_path: Path) -> None:
+    (tmp_path / ".gitignore").write_text(
+        "# pisces generated files\n.pisces/\npisces.toml\n",
+        encoding="utf-8",
+    )
+    assert run_init(tmp_path) == 0
+    content = (tmp_path / ".gitignore").read_text(encoding="utf-8")
+    assert content.count(".pisces/") == 1
+    assert content.count("pisces.toml") == 1

{pisces_cli-0.1.0 → pisces_cli-0.1.2}/uv.lock RENAMED Viewed

@@ -1408,7 +1408,7 @@ wheels = [
 [[package]]
 name = "pisces-cli"
-version = "0.1.0"
+version = "0.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },

pisces_cli-0.1.0/PKG-INFO DELETED Viewed

@@ -1,448 +0,0 @@
-Metadata-Version: 2.5
-Name: pisces-cli
-Version: 0.1.0
-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>
-<p align="center">
-  <a href="#-what-is-pisces">What is Pisces?</a> •
-  <a href="#-how-it-works">How it Works</a> •
-  <a href="#-installation">Installation</a> •
-  <a href="#-quick-start">Quick Start</a> •
-  <a href="#-commands">Commands</a> •
-  <a href="#-configuration">Configuration</a> •
-  <a href="#-supported-providers">LLM Providers</a> •
-  <a href="#-security-rules">Security Rules</a> •
-  <a href="#-contributing">Contributing</a>
-</p>
----
-## 🐟 What is Pisces?
-**Pisces** is an AI-powered, self-healing security CLI for Python codebases. It doesn't just *find* vulnerabilities — it *fixes* them, validates the fix against your test suite, and rolls back automatically if anything breaks.
-At its core, Pisces is a **three-stage pipeline**:
-| Stage | What happens |
-|---|---|
-| 🔍 **Detect** | 7 built-in AST + regex security rules scan your code |
-| 🤖 **Remediate** | An LLM generates a minimal, targeted patch |
-| ✅ **Validate** | Your own test suite verifies the fix works |
-The entire process is governed by a **Human-in-the-Loop (HITL)** approval gate — Pisces asks *you* before touching any source file.
----
-## ⚙️ How it Works
-```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│  pisces scan │ ──▶ │pisces explain│ ──▶ │  pisces fix  │ ──▶ │pisces history│
-│              │     │              │     │              │     │              │
-│ Runs 7 rules │     │ LLM analyses │     │ LLM patches  │     │ Audit trail  │
-│ on .py files │     │ the finding  │     │ Judge reviews│     │ of all fixes │
-│              │     │ with full    │     │ You approve  │     │              │
-│ Caches to    │     │ attack       │     │ Tests run    │     │ Full diff    │
-│ .pisces/cache│     │ scenario     │     │ Rollback if  │     │ Judge scores │
-└──────────────┘     └──────────────┘     │ tests fail   │     └──────────────┘
-                                          └──────────────┘
-```
-### The Repair State Machine
-```
-DETECTED ──▶ PROPOSED ──▶ JUDGED ──▶ AWAITING_APPROVAL
-                                            │
-                              ┌─────────────┴──────────────┐
-                              ▼                            ▼
-                           APPROVED                    REJECTED ✗
-                              │
-                        CHECKPOINTED
-                              │
-                           APPLIED
-                              │
-                         VALIDATING
-                         ┌────┴────┐
-                         ▼         ▼
-                     SUCCEEDED  FAILED ──▶ HEALING ──▶ PROPOSED (retry)
-                         ✓                                │
-                                                    ROLLED_BACK ✗
-                                               (all attempts exhausted)
-```
-### Atomicity Guarantee
-Pisces **never writes directly to your source file**. Every patch goes through:
-1. 📋 **Checkpoint** — `original.py` saved to `.pisces/history/<id>/`
-2. ✏️ **Write** — patch written to `file.py.tmp`
-3. 🔄 **Rename** — `.tmp → file.py` (atomic on all OSes)
-4. ↩️ **Rollback** — on any failure, `original.py` is restored
-### Architecture and Workflow
-```mermaid
-flowchart TD
-    A[Developer runs pisces init] --> B[pisces.toml and .pisces state]
-    B --> C[pisces scan TARGET]
-    C --> D[Discover project .py files]
-    D --> E[Exclude .venv* and configured directories]
-    E --> F[AST and regex security rules]
-    F --> G[Findings cache]
-    G --> H[pisces explain FILE:LINE]
-    H --> I[Source snippet and AST context]
-    I --> J[LLM explanation]
-    G --> K[pisces fix FILE:LINE]
-    K --> L[Generate minimal patch]
-    L --> M[LLM judge]
-    M --> N{Human approves?}
-    N -- No --> O[Stop without changing source]
-    N -- Yes --> P[Checkpoint original file]
-    P --> Q[Apply atomic patch]
-    Q --> R[Run configured test command]
-    R --> S{Tests pass?}
-    S -- Yes --> T[Save repair history]
-    S -- No --> U[Rollback and retry healing loop]
-    U --> L
-    B --> V[pisces watch]
-    V --> W[Debounced context updates]
-```
-The deterministic scanner does not call an LLM. LLMs are used only for
-explanations, patch generation, and optional patch judging. API credentials
-are read from environment variables and are never stored in `pisces.toml`.
----
-## 🚀 Installation
-### From PyPI (recommended)
-```bash
-pip install pisces-cli
-```
-### From Source
-```bash
-git clone https://github.com/richochetclementine1315/pisces.git
-cd pisces
-pip install -e ".[dev]"
-```
-### Requirements
-- **Python** ≥ 3.10
-- An API key for your chosen LLM provider (see [Supported Providers](#-supported-providers))
----
-## ⚡ Quick Start
-```bash
-# 1. Initialize Pisces in your project
-pisces init
-# 2. Set your LLM provider API key (example: Groq)
-export GROQ_API_KEY=your_key_here
-# 3. Configure provider & model
-pisces config
-# 4. Scan for vulnerabilities
-pisces scan .
-# 5. Get an AI explanation of a finding
-pisces explain auth.py:42
-# 6. Apply a self-healing patch (with HITL approval)
-pisces fix auth.py:42
-# 7. Review your repair history
-pisces history
-```
----
-## 📟 Commands
-### `pisces init` — Initialize Project
-```bash
-pisces init [PATH] [--force / -f]
-```
-Creates `pisces.toml`, `.pisces/` state directory, and updates `.gitignore`.
-| Option | Short | Default | Description |
-|---|---|---|---|
-| `PATH` | | `.` | Project root to initialize |
-| `--force` | `-f` | `False` | Overwrite existing `pisces.toml` |
----
-### `pisces config` — Configuration Wizard
-```bash
-pisces config [PATH] [--show / -s]
-```
-Interactive wizard that configures provider, model, HITL, and test command.
-| Option | Short | Default | Description |
-|---|---|---|---|
-| `PATH` | | `.` | Project root |
-| `--show` | `-s` | `False` | Print current config table and exit |
----
-### `pisces scan` — Security Scanner
-```bash
-pisces scan [TARGET] [--output FILE] [--min-severity LEVEL]
-```
-Scans Python files with 7 built-in security rules. Caches results for `explain` and `fix`.
-| Option | Short | Default | Description |
-|---|---|---|---|
-| `TARGET` | | `.` | Directory or `.py` file |
-| `--output FILE` | `-o` | `None` | Save findings as JSON |
-| `--min-severity` | `-s` | `LOW` | `CRITICAL` / `HIGH` / `MEDIUM` / `LOW` / `INFO` |
-**Exit code:** `1` if findings exist at/above threshold, `0` if clean — ideal for CI.
----
-### `pisces explain` — AI Vulnerability Analysis
-```bash
-pisces explain <file:line>
-```
-Sends the finding + ±20 lines of source + AST context to the LLM. Renders a **6-section structured report**:
-| Section | Content |
-|---|---|
-| 📋 Executive Summary | One-line verdict |
-| 🔍 Vulnerability Explained | Technical deep-dive |
-| ⚔️ Attack Scenario | Step-by-step exploitation |
-| 🎯 Root Cause | Exact line + mistake |
-| 🛠️ Recommended Fix | Corrected code with comments |
-| 📚 References | CWE, OWASP, CVE links |
----
-### `pisces fix` — Self-Healing Repair
-```bash
-pisces fix <file:line> [OPTIONS]
-```
-The full repair pipeline: generate → judge → approve → patch → test → heal.
-| Option | Short | Default | Description |
-|---|---|---|---|
-| `--dry-run` | | `False` | Show patch without modifying files |
-| `--no-judge` | | `False` | Skip adversarial LLM judge |
-| `--max-attempts N` | `-m` | from config | Max self-healing retries |
----
-### `pisces watch` — Live Context Watcher
-```bash
-pisces watch [PATH]
-```
-Watches `.py` files with 0.8s debouncing. Auto-updates `context.json` on every save. Press `Ctrl+C` to stop.
----
-### `pisces history` — Repair Audit Log
-```bash
-pisces history [PATH] [--detail ID] [--limit N]
-```
-| Option | Short | Default | Description |
-|---|---|---|---|
-| `--detail REPAIR_ID` | `-d` | `None` | Full detail + diff for one repair |
-| `--limit N` | `-n` | `20` | Records to show in list view |
----
-## 🔧 Configuration
-**`pisces.toml`** (project root — never put API keys here):
-```toml
-[llm]
-provider = "groq"                      # openai | anthropic | gemini | groq | ollama | lmstudio
-model    = "llama-3.3-70b-versatile"   # any model your provider supports
-[repair]
-max_attempts     = 3      # self-healing retry limit
-require_approval = true   # HITL — always ask before patching
-[validation]
-test_command = "pytest"   # command to validate patches
-[scan]
-exclude = [".git", ".venv", "__pycache__", "node_modules", ".pisces", "dist", "build"]
-```
----
-## 🤖 Supported Providers
-| Provider | Env Var | Default Model |
-|---|---|---|
-| `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
-| `anthropic` | `ANTHROPIC_API_KEY` | `claude-3-5-haiku-20241022` |
-| `gemini` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `gemini-2.0-flash` |
-| `groq` | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
-| `ollama` | *(none — local)* | `llama3.2` |
-| `lmstudio` | *(none — local)* | `local-model` |
----
-## 🛡️ Security Rules
-| Rule | ID | Severity | What it Detects |
-|---|---|---|---|
-| Hardcoded Secret | `S001` | HIGH | API keys, passwords, tokens in source code |
-| Command Injection | `S002` | CRITICAL | `subprocess` with f-strings/vars + `shell=True` |
-| Unsafe Subprocess | `S003` | HIGH | `shell=True` even with static strings |
-| Unsafe Deserialization | `S004` | HIGH | `pickle.load`, `yaml.load` without `SafeLoader` |
-| TLS Verify Disabled | `S005` | HIGH | `requests.get(..., verify=False)` |
-| Code Injection | `S006` | CRITICAL | `eval(var)`, `exec(var)` with user input |
-| Dangerous Filesystem | `S007` | MEDIUM | `shutil.rmtree(variable_path)` |
----
-## 🗂️ Project Layout
-```
-Pisces/
-├── pisces/
-│   ├── cli.py            # Typer CLI entrypoint — all commands
-│   ├── models.py         # Shared dataclasses (Finding, JudgeResult, RepairState…)
-│   ├── scanner.py        # 7 security rules (AST + regex)
-│   ├── scan_cmd.py       # `pisces scan` implementation
-│   ├── explain_cmd.py    # `pisces explain` implementation
-│   ├── fix_cmd.py        # `pisces fix` state machine
-│   ├── patch_engine.py   # Atomic patch apply, checkpoint, rollback
-│   ├── judge.py          # Adversarial LLM judge
-│   ├── history_cmd.py    # `pisces history` implementation
-│   ├── watcher.py        # `pisces watch` — watchdog integration
-│   ├── config_cmd.py     # `pisces config` wizard
-│   ├── config_manager.py # pisces.toml loader/writer
-│   ├── context_manager.py# context.json AST index
-│   ├── llm_client.py     # Multi-provider LLM client
-│   ├── ast_visitor.py    # AST walker for file intelligence
-│   └── tui.py            # Rich TUI primitives
-├── tests/
-│   ├── conftest.py
-│   ├── test_scanner.py
-│   ├── test_patch_engine.py
-│   ├── test_models.py
-│   ├── test_config_manager.py
-│   └── test_context_manager.py
-├── pyproject.toml
-├── pisces.toml
-└── README.md
-```
----
-## 🤝 Contributing
-Contributions are welcome! Please open an issue before submitting a PR.
-```bash
-git clone https://github.com/richochetclementine1315/pisces.git
-cd pisces
-pip install -e ".[dev]"
-pytest tests/ -v
-ruff check pisces/ tests/
-```
----
-## 📄 License
-MIT © [Mrinmoy Matilal](https://github.com/richochetclementine1315)
----