softgnn-advisor 0.1.0__tar.gz

softgnn_advisor-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to SoftGNN Advisor will be documented here.
+
+The format loosely follows [Keep a Changelog](https://keepachangelog.com/), and this project uses alpha milestone versions during early development.
+
+---
+
+## v0.1.0-alpha — Developer Preview
+
+### Added
+
+- Code/test graph foundation for PR impact analysis.
+- Runtime test mapping from pytest execution to source functions.
+- PR scan workflow for impacted targets and missing runtime coverage.
+- Semantic pytest generation for selected targets.
+- Transactional generated-test patching with rollback.
+- Generated block markers for safe rewrites.
+- Pytest verification loop.
+- Bounded repair loop for generated tests.
+- Runtime coverage refresh after successful generation.
+- PR scan confirmation after runtime refresh.
+- LLM provider abstraction.
+- Native Gemini provider.
+- OpenAI-compatible provider.
+- Template fallback provider.
+- Structured JSON parsing and validation for LLM-generated tests.
+- Safety validation for generated code patterns and test paths.
+- CLI flags for generation strategy, provider config, repair, runtime refresh, and rollback policy.
+- Internal tests for provider config and LLM schema validation.
+
+### Verified
+
+- Gemini generated semantic tests for `FUNC:is_edge_index_sorted`.
+- Patch workflow produced `6 passed` on the demo repo.
+- Runtime refresh persisted `336` runtime edges.
+- PR scan confirmation completed successfully.
+
+### Notes
+
+- This is an alpha/developer preview.
+- Generated tests should be reviewed before commit.
+- Production-code fixes are not enabled in v0.1.
+- Multi-agent testing swarm is roadmap, not v0.1 scope.

softgnn_advisor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minh Quang Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

softgnn_advisor-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include ROADMAP.md
+recursive-include softgnn_advisor *.py *.md *.json *.yaml *.toml

softgnn_advisor-0.1.0/PKG-INFO

@@ -0,0 +1,430 @@
+Metadata-Version: 2.4
+Name: softgnn-advisor
+Version: 0.1.0
+Summary: Graph-guided, runtime-proven, LLM-assisted PR test generation for Python projects
+License: MIT
+Project-URL: Homepage, https://github.com/minhquang0407/softgnn-advisor
+Project-URL: Repository, https://github.com/minhquang0407/softgnn-advisor
+Project-URL: Issues, https://github.com/minhquang0407/softgnn-advisor/issues
+Keywords: testing,graph,llm,code-intelligence,pytest,gnn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy
+Requires-Dist: gitpython>=3.1
+Requires-Dist: thefuzz[speedup]
+Requires-Dist: unidecode
+Requires-Dist: tqdm
+Requires-Dist: python-igraph
+Requires-Dist: requests
+Requires-Dist: pytest
+Requires-Dist: pytest-cov
+Provides-Extra: gnn
+Requires-Dist: torch>=2.0; extra == "gnn"
+Requires-Dist: torch-geometric; extra == "gnn"
+Requires-Dist: sentence-transformers>=2.0; extra == "gnn"
+Requires-Dist: scikit-learn; extra == "gnn"
+Provides-Extra: llm
+Requires-Dist: google-generativeai>=0.8; extra == "llm"
+Requires-Dist: openai>=1.0; extra == "llm"
+Provides-Extra: all
+Requires-Dist: softgnn-advisor[gnn]; extra == "all"
+Requires-Dist: softgnn-advisor[llm]; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+
+# SoftGNN Advisor
+
+### Graph-guided, runtime-proven, LLM-assisted PR testing
+
+**Know what changed. Know what tests hit it. Generate what is missing.**
+
+[![Tests](https://github.com/minhquang0407/softgnn-advisor/actions/workflows/tests.yml/badge.svg)](https://github.com/minhquang0407/softgnn-advisor/actions/workflows/tests.yml)
+[![Release](https://img.shields.io/github/v/tag/minhquang0407/softgnn-advisor?label=release)](https://github.com/minhquang0407/softgnn-advisor/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![LLM](https://img.shields.io/badge/LLM-Gemini%20%7C%20OpenAI--compatible-8A2BE2)](#configure-an-llm-provider)
+
+</div>
+
+---
+
+## Install
+
+Recommended for CLI use:
+
+```bash
+pipx install softgnn-advisor
+```
+
+Or install into your current environment:
+
+```bash
+pip install softgnn-advisor
+```
+
+Optional extras:
+
+```bash
+pip install "softgnn-advisor[llm]"   # Gemini / OpenAI-compatible generation
+pip install "softgnn-advisor[gnn]"   # PyTorch Geometric ranking
+pip install "softgnn-advisor[all]"   # full stack
+```
+
+Then run:
+
+```bash
+softgnn setup /path/to/your-repo --project my-app
+softgnn apply --project my-app
+```
+
+For local development from source:
+
+```bash
+git clone https://github.com/minhquang0407/softgnn-advisor.git
+cd softgnn-advisor
+python -m venv .venv
+.venv\Scripts\activate  # Windows
+pip install -e ".[all]"
+softgnn --help
+```
+
+---
+
+## What is SoftGNN?
+
+SoftGNN Advisor is an experimental CLI that combines a **code graph**, **runtime test graph**, and **LLM test generation** to help you understand PR impact and generate missing pytest tests.
+
+Most AI testing tools stop at:
+
+```text
+read changed file -> ask LLM for tests -> run pytest
+```
+
+SoftGNN aims for a stronger loop:
+
+```text
+scan PR -> find impacted code -> map tests that actually execute it -> generate missing tests -> verify -> refresh runtime proof
+```
+
+> **Core thesis:** a generated test is not truly useful until it passes pytest and proves it hits the intended code.
+
+---
+
+## The pipeline
+
+```mermaid
+flowchart LR
+    A[PR Diff] --> B[Code Graph]
+    B --> C[Impact Scan]
+    C --> D[Missing Runtime Coverage]
+    D --> E[LLM Semantic Test Generation]
+    E --> F[Schema + Safety Validation]
+    F --> G[Transactional Patch]
+    G --> H[Pytest Verify]
+    H --> I[Runtime Test Mapping]
+    I --> J[PR Scan Confirmation]
+
+    H -- failure --> K[LLM Repair]
+    K --> F
+```
+
+---
+
+## Why it is different
+
+| Capability | Naive LLM test generation | SoftGNN Advisor |
+|---|---:|---:|
+| Reads changed code | ✅ | ✅ |
+| Generates pytest tests | ✅ | ✅ |
+| Validates structured LLM output | ❌ | ✅ |
+| Patches transactionally | ❌ | ✅ |
+| Rolls back failed generated tests | ❌ | ✅ |
+| Maps tests to functions at runtime | ❌ | ✅ |
+| Confirms PR coverage after generation | ❌ | ✅ |
+| Supports Gemini/OpenAI-compatible LLMs | varies | ✅ |
+
+---
+
+## Features
+
+- **PR impact scanning** between Git revisions.
+- **Code graph extraction** from Python source files.
+- **Runtime test mapping** from pytest execution to source functions.
+- **Missing runtime coverage detection** for impacted functions.
+- **LLM-assisted semantic pytest generation**.
+- **Native Gemini provider** and **OpenAI-compatible provider**.
+- **Structured JSON validation** before writing tests.
+- **Safety validation** against unsafe generated code patterns.
+- **Transactional patching** with generated block markers.
+- **Pytest verification** and bounded generated-test repair loop.
+- **Runtime refresh** after successful generation.
+- **PR scan confirmation** after runtime refresh.
+
+---
+
+## Verified demo
+
+On a local `social-link-prediction` repo, SoftGNN used Gemini to generate behavior tests for:
+
+```text
+FUNC:is_edge_index_sorted
+```
+
+Result:
+
+```text
+pytest: 6 passed
+runtime mode: per-test
+runtime edges: 336
+persisted: True
+missing coverage before: 0
+missing coverage after: 0
+```
+
+Fallback without an LLM produced only a shallow smoke test:
+
+```python
+assert callable(is_edge_index_sorted)
+```
+
+Gemini-assisted generation produced behavior checks for sorted edges, unsorted source order, unsorted target order, single-edge input, and invalid-shape errors.
+
+Read the full demo: [docs/examples/social-link-demo.md](docs/examples/social-link-demo.md)
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/minhquang0407/softgnn-advisor.git
+cd softgnn-advisor
+python -m venv .venv
+```
+
+Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+```
+
+Linux/macOS:
+
+```bash
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+> PyTorch / PyTorch Geometric installs can be platform-specific. If installation fails, follow the official PyTorch and PyG installation guides for your environment.
+
+---
+
+## Configure an LLM provider
+
+### Gemini
+
+```powershell
+$env:SOFTGNN_LLM_PROVIDER="gemini"
+$env:SOFTGNN_LLM_MODEL="gemini-3-flash"
+$env:SOFTGNN_LLM_API_KEY="YOUR_GEMINI_API_KEY"
+```
+
+If your API account uses another model ID:
+
+```powershell
+$env:SOFTGNN_LLM_MODEL="gemini-2.5-flash"
+```
+
+### OpenAI-compatible endpoint
+
+```powershell
+$env:SOFTGNN_LLM_PROVIDER="openai-compatible"
+$env:SOFTGNN_LLM_BASE_URL="http://localhost:11434/v1"
+$env:SOFTGNN_LLM_MODEL="qwen2.5-coder:7b"
+$env:SOFTGNN_LLM_API_KEY="optional-if-your-endpoint-needs-it"
+```
+
+Generation strategies:
+
+```text
+template  -> deterministic templates only
+llm       -> require configured LLM unless fallback is allowed
+auto      -> try LLM first, fallback to templates when unavailable
+```
+
+---
+
+## Quickstart
+
+After setup, a single command runs the full workflow:
+
+```powershell
+python softgnn.py setup C:\repo\my-app
+python softgnn.py apply --project my-app
+```
+
+`apply` does everything automatically:
+
+```text
+detect changes (git / filesystem snapshot / full-scan)
+run pr-scan
+rank missing coverage targets
+generate tests (LLM or template)
+patch test files
+run pytest
+repair if failing
+rollback if still failing
+run runtime map
+run post-scan confirmation
+```
+
+Nothing is modified unless pytest passes.
+
+Want to review proposed tests before patching? Use `plan` first:
+
+```powershell
+python softgnn.py setup C:\repo\my-app
+python softgnn.py plan --project my-app   # review output
+python softgnn.py apply --project my-app  # apply reviewed plan
+```
+
+Template-only generation (no LLM):
+
+```powershell
+python softgnn.py apply --project my-app --strategy template
+```
+
+Advanced commands are still available (`prepare`, `pr-scan`, `generate-tests`, `test-map`).
+
+Mental model:
+
+```text
+setup/prepare need the repo path once
+everyday commands use --project
+```
+
+Daily commands after setup:
+
+| Goal | Command |
+|---|---|
+| Generate + verify tests | `python softgnn.py apply --project my-app` |
+| Review before patching | `python softgnn.py plan --project my-app` |
+| Inspect change impact | `python softgnn.py scan --project my-app` |
+| Runtime test map | `python softgnn.py map --project my-app` |
+| Health check | `python softgnn.py doctor --project my-app` |
+| Impact of one symbol | `python softgnn.py impact --project my-app FUNC:foo` |
+| Developer triage | `python softgnn.py triage --project my-app "bug description"` |
+
+More details: [docs/quickstart.md](docs/quickstart.md)
+
+The full guide covers:
+
+```text
+simple CLI workflow
+plan cache and apply-from-plan
+Git PR workflow
+no-Git filesystem snapshot workflow
+first-run full-scan workflow
+explicit target workflow
+runtime coverage mapping
+patch/verify/repair/rollback flow
+```
+
+---
+
+## Safety model
+
+SoftGNN is conservative by default:
+
+```text
+writes tests/ only
+wraps generated code in markers
+validates LLM output before patching
+runs pytest before accepting generated tests
+rolls back failed generated edits by default
+never requires committing API keys
+```
+
+Generated test blocks are marked:
+
+```python
+# <softgnn-generated target="FUNC:example" start>
+...
+# <softgnn-generated target="FUNC:example" end>
+```
+
+Recommended workflow:
+
+```text
+run on a feature branch
+start with --mode plan
+use --mode patch after review
+inspect git diff before commit
+```
+
+---
+
+## CLI highlights
+
+```powershell
+python softgnn.py pr-scan --project social-link --repo-path "C:\path\to\repo" --base main --head HEAD
+```
+
+```powershell
+python softgnn.py test-map --project social-link --repo-path "C:\path\to\repo" --mode per-test --persist
+```
+
+```powershell
+python softgnn.py generate-tests --project social-link --repo-path "C:\path\to\repo" --mode plan --generation-strategy auto
+```
+
+---
+
+## Project status
+
+Current release: **v0.1.0-alpha**
+
+This is a developer preview. Generated tests should be reviewed before commit. Production-code fixes are intentionally out of scope for v0.1.
+
+---
+
+## Roadmap
+
+Short version:
+
+```text
+M4  Runtime-Proven Test Generation
+M5  Graph Impact Report / Dashboard
+M6  Learned Test Prioritization / GNN Ranking
+M7  Multi-Agent Quality Swarm
+M8  Large-scale repo automation
+M9  Controlled production-code fixes
+```
+
+Read more:
+
+- [ROADMAP.md](ROADMAP.md)
+- [docs/future-milestones.md](docs/future-milestones.md)
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+