Metadata-Version: 2.5
Name: vinv
Version: 0.0.3
Summary: Vinv runs, tests, and finds issues in your services — with zero code changes.
Project-URL: Homepage, https://vinv.ai
Project-URL: Repository, https://github.com/VinvAI/VinvAI
Project-URL: Issues, https://github.com/VinvAI/VinvAI/issues
Project-URL: Changelog, https://github.com/VinvAI/VinvAI/blob/main/extension/CHANGELOG.md
Author-email: VinvAI <support@vinv.ai>
License: Apache-2.0
Keywords: ai,api-testing,claude,cursor,dead-code,fault-injection,mcp,observability,python,runtime-tracing,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: <3.15,>=3.12
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: einops>=0.7.0
Requires-Dist: huggingface-hub>=0.23.0
Requires-Dist: icontract<3.0.0,>=2.6.0
Requires-Dist: jsonschema<5.0.0,>=4.20.0
Requires-Dist: networkx<4.0.0,>=3.2.0
Requires-Dist: numpy<3.0.0,>=1.26.0
Requires-Dist: opentelemetry-api<1.30.0,>=1.27.0
Requires-Dist: opentelemetry-instrumentation<0.50.0,>=0.48b0
Requires-Dist: opentelemetry-sdk<1.30.0,>=1.27.0
Requires-Dist: pandas<2.3.0,>=2.0.0
Requires-Dist: pyarrow<24.0.0,>=23.0.1
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: pyyaml<7.0.0,>=6.0.1
Requires-Dist: scikit-learn<1.6.0,>=1.3.0
Requires-Dist: scipy<2.0.0,>=1.11.0
Requires-Dist: sentence-transformers<6.0.0,>=3.0.0
Requires-Dist: torch>=2.1.0
Description-Content-Type: text/markdown

<div align="center">

# `pip install vinv`

**Vinv runs, tests, and finds issues in your services — with zero code changes.**

[![PyPI](https://img.shields.io/pypi/v/vinv?style=flat-square&color=D71921&label=pypi)](https://pypi.org/project/vinv/)
[![Python](https://img.shields.io/pypi/pyversions/vinv?style=flat-square&color=D71921)](https://pypi.org/project/vinv/)
[![License](https://img.shields.io/badge/license-Apache--2.0-D71921?style=flat-square)](https://github.com/VinvAI/VinvAI/blob/main/LICENSE)
[![100% local](https://img.shields.io/badge/100%25%20local-no%20telemetry-D71921?style=flat-square)](https://github.com/VinvAI/VinvAI#privacy)

<sub>Python services & APIs · runs on your machine · no account, no API keys, no telemetry</sub>

</div>

---

Vinv watches a **real run** of your Python services and hands your AI coding agent the
actual execution evidence — traces, argument values, the failing frame — instead of
leaving it to guess from static text. Then it **won't let a fix land** until it passes
acceptance tests written *before* the fix that the agent never sees.

Your coding agent (Claude Code, Cursor, Copilot…) is the only LLM. **No new bill, no
provider keys.**

## Install

```bash
pip install vinv
```

Or run any engine with **zero install** via [uv](https://docs.astral.sh/uv/):

```bash
uvx --from vinv exerciser campaign ./my-service --budget 20
```

<sub>First run fetches a one-time ~500&nbsp;MB local embedding model. Python 3.12–3.14.</sub>

## What you get — Run · Test · Find · Prove

- **🏃 Run** — brings every service in your repo up under tracing with **zero edits** to your code: timings, arguments, return values, call trees, from the real run.
- **🧪 Test** — drives real requests through every endpoint (valid, boundary, negative, authenticated) and banks each response as a permanent regression case.
- **🔎 Find** — surfaces what actually broke or slowed down: server errors, crashes, latency hotspots, memory leaks, duplicate recomputation, and dead code — each tied to the exact source line. Plus **semantic code search**: ask by meaning, get ranked symbols with `def` bodies and line numbers.
- **✅ Prove** — hands that evidence to your coding agent, then verifies its fix against acceptance tests it never sees. A "faster" change that alters any output is auto-reverted.

## Dead code — zero setup

Not everything needs a run. `index deadcode <repo>` (or the `vinv_deadcode` MCP tool)
statically finds every function, class, and method **nothing references** — no tracing,
no index, no config — and reports each with its file and line. It even catches
**transitively-dead chains** (code whose only callers are themselves dead), and can date
each symbol from git to tell you whether it was *never wired up* or *lost its callers*.
The one Vinv feature that pays off before you run a thing — delete with confidence.

## Context beats model size

Vinv found **four bugs and one performance problem** in
[fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template)
(~44k★). Same five issues, same prompts, Vinv grading every run:

| Setup | Fixed |
|---|---|
| **Cheap commodity model + Vinv evidence** | **4 bugs + 1 optimization** |
| Frontier model, working blind | 1 bug |
| Cheap commodity model, working blind | nothing |

<sub>One trial per condition — a demonstration, not a benchmark. The evidence is what
moved, not the weights.</sub>

On the same template the optimization loop detected connection-pool starvation from live
traces alone, dispatched the fix, and **proved** it: sustained-load median
**75.6ms → 41.2ms, 45.4% faster** (95% CI [36.3%, 45.8%]), responses byte-identical.
Upstream on Hugging Face, it found and proved an allocation fast-path in
[smolagents](https://github.com/huggingface/smolagents) — **~37,000× less** transient
allocation, output byte-identical across 2,015 inputs
([PR #2572](https://github.com/huggingface/smolagents/pull/2572)).

## The engines

`pip install vinv` installs one package that ships every engine as a console script:

| Engine | Command | What it does |
|---|---|---|
| **exerciser** | `exerciser campaign <repo> --budget N` | **Start here.** Coverage-guided API exerciser + oracle swarm — generates valid/boundary/negative/authenticated/fault/concurrent requests, banks a permanent regression suite, and reports which technique paid. |
| **tracelens** | `tracelens run -- <cmd>` | Zero-edit runtime tracer — captures timings, arguments, return values, and call trees from a real run. |
| **index** | `index query <repo>` · `index deadcode <repo>` | Rust semantic code index — search code by meaning, plus a source-only dead-code report. |
| **identification** | `identification consolidate <repo>` | Joins traces to source — builds the API surface + call-graph map, tying runtime evidence to the exact function. |
| **bringup** | `bringup list/start <repo>` | Brings services up under tracing — enumerates every service, then starts one instrumented. |
| **handbook** | `handbook generate <repo>` | Renders the codebase-discovery task your coding agent runs to map the repo (services, entry points). Prompt-only — no LLM calls of its own. |
| **goal** | `goal create <context>` | Distills a working context into one standing goal for fix/optimize episodes. Prompt-only. |
| **embedder** | `vinv-embedder serve` | Local embedding sidecar ([CodeRankEmbed](https://huggingface.co/nomic-ai/CodeRankEmbed)) powering semantic search — runs on your machine, no cloud keys. |
| **contracts** | *(library)* | `lens_contracts` — the shared data contract every engine reads and writes. |

## Works with any MCP client

Vinv is also an **MCP server** — add it once, globally, and point Claude Code, Cursor, or
any MCP-compatible agent at it. It finds your open workspace automatically via MCP roots,
so a single config follows whatever repo you have open:

```bash
claude mcp add vinv -- npx -y vinv-mcp
```

Your agent gets the full tool set: `vinv_query` (semantic code search), `vinv_deadcode`
(unreferenced code), `vinv_index` (build/refresh the index), `rank_suspects` (fault
localization over real runs), runtime `values_of` / `slice` / `coverage_of`, and a
`vinv_session` tool that drives the whole verify/optimize loop from chat. The index
builds in the background on first use. See
[`vinv-mcp`](https://www.npmjs.com/package/vinv-mcp).

## Privacy

100% local. No telemetry, no analytics, no usage pings. Traces stay on your machine and
sensitive values are redacted. Apache-2.0.

---

<div align="center">
<sub><b><a href="https://vinv.ai">vinv.ai</a></b> · <a href="https://github.com/VinvAI/VinvAI">github.com/VinvAI/VinvAI</a> · Python first — TypeScript & Go next</sub>
</div>
