Metadata-Version: 2.5
Name: ragvidence
Version: 0.1.0
Summary: Evidence-first RAG retrieval diagnostics, built to run locally.
Project-URL: Homepage, https://ragvidence.medo-id.com
Project-URL: Documentation, https://ragvidence.medo-id.com/docs
Author: Medo
License: # RAGvidence Software License
        
        Version 1.0 — 8 October 2026
        
        Copyright © 2026 Medo. All rights reserved.
        
        This is proprietary software, not open-source software. “Licensor” means the seller identified on the product page or transaction receipt. “You” means the individual who obtained the software, or the organization identified on a valid order if the order expressly grants an organizational license.
        
        By downloading, installing, copying, or using RAGvidence, you agree to this license. If you do not agree, do not use the software.
        
        ## 1. Free license grant
        
        For a build designated **Free**, Licensor grants one individual a revocable, non-exclusive, non-transferable license to install and use the software on devices controlled by that individual for personal, educational, evaluation, and internal professional work.
        
        You may use reports and other output you generate, including in commercial work, subject to third-party rights and your responsibility to review confidential content.
        
        No account or paid activation is required for the Free edition.
        
        ## 2. Plus license grant
        
        For a build or entitlement designated **Plus**, and while the applicable purchase entitlement remains valid, Licensor grants the purchasing individual the Free rights plus access to the Plus features and updates expressly listed for that purchase.
        
        Unless the order expressly states otherwise, Plus is a single-user license. It is not a team, organization-wide, redistribution, resale, or hosted-service license. Price, billing period, included update period, support level, taxes, and refund eligibility are controlled by the checkout terms and receipt.
        
        ## 3. Restrictions
        
        Under either plan, you may not:
        
        - redistribute, publish, sublicense, sell, rent, lease, or share the software or a license credential;
        - remove copyright, license, attribution, or entitlement notices;
        - provide the software itself as a hosted or managed service to third parties;
        - bypass, tamper with, forge, or defeat an entitlement or plan check;
        - use the software or documentation to create a substantially identical competing product for redistribution;
        - use the software unlawfully or in violation of third-party rights.
        
        You may make reasonable backup copies for your own licensed use. You may inspect and modify source files delivered to you solely for your own licensed use, but modifications do not grant redistribution rights or transfer support obligations to Licensor.
        
        ## 4. Data, providers, and third-party components
        
        The software processes data locally by default. Features you configure to use external providers transmit selected source text, questions, or prompts to those providers. You are responsible for having authority to process that data and for reviewing each provider’s terms, security, retention, and training policies.
        
        Third-party components and downloaded models remain governed by their own licenses. See `THIRD_PARTY_NOTICES.md`. This license does not grant rights to third-party content, datasets, models, or services.
        
        ## 5. High-risk use and professional advice
        
        The software is a retrieval evaluation and debugging aid. It does not provide legal, financial, medical, audit, compliance, or other professional advice. It does not guarantee that retrieved evidence, generated answers, labels, or reports are accurate or complete. You are responsible for human review, testing, security controls, and decisions made using the software.
        
        ## 6. Confidentiality and exported reports
        
        Reports can contain source identifiers, metadata, and text previews. You are responsible for inspecting and redacting exported artifacts before sharing them and for complying with confidentiality, privacy, employment, and contractual obligations.
        
        ## 7. Updates, support, and availability
        
        Licensor may change or discontinue editions and future features. Only capabilities present in the delivered build and expressly included in the applicable order are licensed. Planned or roadmap items are not commitments. Support, if included, is limited to the scope stated at checkout or on the receipt.
        
        ## 8. Termination
        
        This license ends automatically if you materially violate it. On termination, you must stop using and delete the software and license credentials, except where applicable law requires otherwise. Sections intended by their nature to survive—including restrictions, disclaimers, liability limits, and third-party terms—remain effective.
        
        ## 9. Disclaimer of warranties
        
        To the maximum extent permitted by applicable law, the software is provided “as is” and “as available,” without warranties of merchantability, fitness for a particular purpose, non-infringement, uninterrupted operation, or error-free results. Some jurisdictions do not allow certain exclusions, so these exclusions apply only to the extent permitted.
        
        ## 10. Limitation of liability
        
        To the maximum extent permitted by applicable law, Licensor is not liable for indirect, incidental, special, consequential, exemplary, or punitive damages, or for loss of data, profit, revenue, business, goodwill, or opportunity arising from the software. Licensor’s aggregate liability relating to a paid license will not exceed the amount you paid for that license during the twelve months before the event giving rise to the claim. Nothing here excludes liability that cannot legally be excluded or limited.
        
        ## 11. Consumer rights and controlling terms
        
        Mandatory consumer rights remain unaffected. If checkout terms or a written order conflict with this license, the more specific checkout terms or order control only for that transaction. If any provision is unenforceable, the remaining provisions continue to apply.
        
        ## 12. Contact
        
        Use the contact or support channel identified on the product page or transaction receipt for license questions.
License-File: LICENSE.md
Keywords: bm25,debugging,embeddings,evaluation,rag,retrieval
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.12
Requires-Dist: bm25s<0.3,>=0.2.14
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: numpy<3,>=2
Requires-Dist: pydantic-settings<3,>=2.10
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: rich<15,>=14
Requires-Dist: typer<1,>=0.16
Provides-Extra: semantic
Requires-Dist: fastembed<1,>=0.7; extra == 'semantic'
Description-Content-Type: text/markdown

# RAGvidence

**Evidence-first RAG diagnostics, built to run locally.**

RAGvidence is a local, CLI-first toolkit for testing retrieval changes with reviewed evidence instead of judging generated answers by intuition.

It helps you answer questions such as:

- Did the retriever return **all** evidence required for the answer?
- Did a new chunk representation fix failures or introduce regressions?
- Is the first relevant result early enough at the real context depth `k`?
- Does lexical, semantic, or an existing application retriever work better on your data?

No account, telemetry, hosted database, or vendor-provided API key is required. BM25 works completely offline. Semantic retrieval can run locally or through a provider chosen by the user.

> RAGvidence evaluates retrieval evidence. It does not prove that a generated answer is correct, safe, or legally compliant.

## Install

### Customer release archive

Extract the release, open a terminal in its directory, and run:

```bash
uv sync --frozen
uv run ragvi health
uv run ragvi tutorial
```

During source-based use, prefix commands with `uv run`. After installing the CLI as a tool, use `ragvi` directly.

### Install a built wheel

```bash
uv tool install ./ragvidence-0.1.0-py3-none-any.whl
ragvi health
ragvi tutorial
```

Python 3.12 is pinned in `.python-version`; `uv` can install the required Python runtime automatically.

## First report

The tutorial writes a complete comparison to:

```text
workspaces/first-run/reports/tutorial.html
```

Open it in any browser. It contains the baseline, intervention, changed questions, diagnosis, ranked evidence, limitations, and reproducibility metadata.

Then follow [Getting started](docs/getting-started.md) to understand the experiment rather than only running it.

## Supported workflows

| Goal | Start here |
| --- | --- |
| Learn the workflow on bundled data | `ragvi tutorial` |
| Evaluate your own labeled dataset | [Bring your own data](docs/bring-your-own-data.md) |
| Compare BM25 and semantic retrieval | [User guide](docs/user-guide.md#semantic-retrieval) |
| Test an existing RAG retriever | [User guide](docs/user-guide.md#import-an-existing-retriever) |
| Generate optional answers for inspection | [User guide](docs/user-guide.md#optional-answer-inspection) |
| Understand each metric | [Interpreting results](docs/interpreting-results.md) |
| Recover a broken workspace | [Troubleshooting](docs/troubleshooting.md) |
| Review data and provider boundaries | [Privacy and providers](docs/privacy-and-providers.md) |

The complete CLI reference is in [Command reference](docs/command-reference.md).

## What is included

- Controlled body versus heading-context experiments
- BM25 lexical retrieval
- Optional local semantic retrieval with FastEmbed
- Ollama and OpenAI-compatible embedding adapters
- Import of ranked results from another RAG stack
- Evidence sufficiency, coverage, first relevant rank, reciprocal rank, and precision@k
- Explicit improvement and regression classification
- Evidence-backed diagnostic suggestions
- JSON, Markdown, and self-contained HTML reports
- Optional answer inspection using a user-selected model
- Recoverable local workspaces and deterministic installation verification

## Free and Plus

The current release contains the complete Free feature set. Plus is a separate paid entitlement for advanced features released in Plus builds; features are never advertised as available until they ship. See [Plans and editions](docs/plans.md) and [LICENSE.md](LICENSE.md).

The Free edition does not require activation. Plus activation will be issued after verified checkout and must never require placing payment credentials inside this CLI.

## Privacy and trust boundaries

- Workspaces, caches, `.env`, and generated reports are ignored by Git.
- BM25 performs no network requests.
- FastEmbed downloads a model, then performs inference locally.
- Remote providers receive source text and questions; the CLI displays a disclosure first.
- API keys are loaded from `.env` and are not included in run manifests or reports.
- HTML reports escape dataset content, contain no scripts, and use no remote assets.
- Reports include short source previews and may still contain confidential information. Review before sharing.

## Development and release verification

```bash
uv sync --frozen --dev
uv run ruff check src tests
uv run pytest
uv run ragvi verify
uv build
```

See [Security](SECURITY.md), [Support](SUPPORT.md), [Changelog](CHANGELOG.md), [Third-party notices](THIRD_PARTY_NOTICES.md), and the [resolved dependency inventory](THIRD_PARTY_LICENSES.md).

Copyright © 2026 Medo. Distributed under the proprietary Free or Plus license in [LICENSE.md](LICENSE.md).
