ragvidence 0.1.0__tar.gz

ragvidence-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# Optional. Core defaults are fastembed + BAAI/bge-small-en-v1.5.
+# Other values: ollama, openai_compatible.
+RAGVIDENCE_EMBEDDING_PROVIDER=fastembed
+RAGVIDENCE_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+RAGVIDENCE_EMBEDDING_BASE_URL=
+RAGVIDENCE_EMBEDDING_API_KEY=
+
+# Optional answer inspection: ollama or openai_compatible.
+RAGVIDENCE_GENERATION_PROVIDER=
+RAGVIDENCE_GENERATION_MODEL=
+RAGVIDENCE_GENERATION_BASE_URL=
+RAGVIDENCE_GENERATION_API_KEY=

ragvidence-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+.env
+.pytest_cache/
+__pycache__/
+*.py[cod]
+workspaces/
+.ragvidence-cache/
+dist/
+build/
+.ruff_cache/
+*.egg-info/
+.coverage
+htmlcov/
+*.log

ragvidence-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ragvidence-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable user-facing changes are documented here.
+
+## 0.1.0 — 2026-10-08
+
+### Added
+
+- Local BM25 body and heading-context experiments.
+- Optional semantic retrieval with FastEmbed, Ollama, and OpenAI-compatible endpoints.
+- Import path for existing retrievers.
+- Evidence sufficiency, coverage, rank, reciprocal-rank, and precision metrics.
+- Question-level regression classification and bounded diagnosis.
+- JSON, Markdown, and self-contained HTML reports.
+- Guided `ragvi tutorial` workflow.
+- Workspace backup and restore.
+- Health and deterministic verification commands.
+- Customer documentation, privacy boundaries, and Free/Plus license terms.
+
+### Known limits
+
+- Unanswerable questions are excluded from retrieval-success scoring; abstention is not evaluated.
+- The bundled teaching dataset is small, fictional, and English-focused.
+- Retrieval evaluation does not establish generated-answer correctness.

ragvidence-0.1.0/LICENSE.md

@@ -0,0 +1,74 @@
+# 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.

ragvidence-0.1.0/PKG-INFO

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

ragvidence-0.1.0/README.md

@@ -0,0 +1,111 @@
+# 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).

ragvidence-0.1.0/SECURITY.md

@@ -0,0 +1,31 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest released Free build and actively supported Plus builds. Upgrade before reporting behavior from an older release.
+
+## Report a vulnerability privately
+
+Do not publish exploitable details in a public issue or discussion. Contact the seller through the support channel shown on the product page or purchase receipt and include:
+
+- affected version and operating system;
+- minimal reproduction steps;
+- expected and observed behavior;
+- potential impact;
+- whether real credentials or private data were exposed.
+
+Do not include live API keys, customer documents, or unrelated personal information. Use synthetic data whenever possible.
+
+## Security boundaries
+
+- BM25 is offline and does not transmit data.
+- FastEmbed downloads model files and then runs locally.
+- Ollama and OpenAI-compatible endpoints are selected by the user.
+- Remote providers receive the text required for the requested operation.
+- `.env` values are not written to manifests or reports.
+- Exported reports may contain source identifiers and previews and must be reviewed before sharing.
+- The CLI is not a sandbox. Only run trusted releases and trusted custom templates.
+
+## Release integrity
+
+Official releases should publish SHA-256 checksums. Verify the downloaded artifact before installation and never install a package from an unofficial mirror or unexpected URL.

ragvidence-0.1.0/SUPPORT.md

@@ -0,0 +1,24 @@
+# Support
+
+## Before requesting help
+
+```bash
+ragvi --version
+ragvi health
+ragvi verify
+```
+
+Then check [Getting started](docs/getting-started.md) and [Troubleshooting](docs/troubleshooting.md).
+
+## What to include
+
+- product version;
+- operating system and Python version;
+- installation method;
+- exact command;
+- complete error text with credentials and private document content removed;
+- whether the bundled tutorial succeeds.
+
+Use the support channel listed on the product page or purchase receipt. Support scope and response targets, if any, are determined by the plan and checkout terms.
+
+Support does not include reviewing confidential corpora, designing a production architecture, operating third-party providers, or guaranteeing model/retrieval quality unless separately agreed in writing.

ragvidence-0.1.0/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,51 @@
+# Resolved dependency license inventory
+
+Generated from the locked Free and semantic runtime environment for version 0.1.0. Package metadata is informational; upstream license files remain authoritative.
+
+| Name               | Version   | License                                            | URL                                                                  |
+|--------------------|-----------|----------------------------------------------------|----------------------------------------------------------------------|
+| Jinja2             | 3.1.6     | BSD License                                        | https://github.com/pallets/jinja/                                    |
+| MarkupSafe         | 3.0.3     | BSD-3-Clause                                       | https://github.com/pallets/markupsafe/                               |
+| PyYAML             | 6.0.3     | MIT License                                        | https://pyyaml.org/                                                  |
+| Pygments           | 2.21.0    | BSD-2-Clause                                       | https://pygments.org                                                 |
+| annotated-doc      | 0.0.5     | MIT                                                | https://github.com/fastapi/annotated-doc                             |
+| annotated-types    | 0.8.0     | MIT                                                | https://github.com/annotated-types/annotated-types                   |
+| anyio              | 4.15.1    | MIT                                                | https://anyio.readthedocs.io/en/stable/versionhistory.html           |
+| bm25s              | 0.2.14    | MIT License                                        | https://github.com/xhluca/bm25s                                      |
+| certifi            | 2026.7.22 | Mozilla Public License 2.0 (MPL 2.0)               | https://github.com/certifi/python-certifi                            |
+| charset-normalizer | 3.5.1     | MIT                                                | https://github.com/jawah/charset_normalizer/blob/master/CHANGELOG.md |
+| click              | 8.5.0     | BSD-3-Clause                                       | https://github.com/pallets/click/                                    |
+| fastembed          | 0.8.1     | Apache Software License                            | https://github.com/qdrant/fastembed                                  |
+| filelock           | 4.0.4     | MIT                                                | https://github.com/tox-dev/py-filelock                               |
+| flatbuffers        | 25.12.19  | Apache Software License                            | https://google.github.io/flatbuffers/                                |
+| fsspec             | 2026.9.0  | BSD-3-Clause                                       | https://github.com/fsspec/filesystem_spec                            |
+| h11                | 0.16.0    | MIT License                                        | https://github.com/python-hyper/h11                                  |
+| hf-xet             | 1.6.0     | Apache-2.0                                         | https://github.com/huggingface/xet-core                              |
+| httpcore           | 1.0.9     | BSD-3-Clause                                       | https://www.encode.io/httpcore/                                      |
+| httpx              | 0.28.1    | BSD License                                        | https://github.com/encode/httpx                                      |
+| huggingface_hub    | 1.33.0    | Apache Software License                            | https://github.com/huggingface/huggingface_hub                       |
+| idna               | 3.20      | BSD-3-Clause                                       | https://github.com/kjd/idna                                          |
+| loguru             | 0.7.3     | MIT License                                        | https://github.com/Delgan/loguru                                     |
+| markdown-it-py     | 4.2.0     | MIT License                                        | https://github.com/executablebooks/markdown-it-py                    |
+| mdurl              | 0.1.2     | MIT License                                        | https://github.com/executablebooks/mdurl                             |
+| mmh3               | 5.3.0     | MIT License                                        | https://pypi.org/project/mmh3/                                       |
+| numpy              | 2.5.3     | BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0 | https://numpy.org                                                    |
+| onnxruntime        | 1.30.0    | MIT License                                        | https://onnxruntime.ai                                               |
+| packaging          | 26.3      | Apache-2.0 OR BSD-2-Clause                         | https://github.com/pypa/packaging                                    |
+| pillow             | 12.3.0    | MIT-CMU                                            | https://python-pillow.github.io                                      |
+| protobuf           | 7.36.2    | 3-Clause BSD License                               | https://developers.google.com/protocol-buffers/                      |
+| py_rust_stemmers   | 0.1.8     | UNKNOWN                                            | UNKNOWN                                                              |
+| pydantic           | 2.13.5    | MIT                                                | https://github.com/pydantic/pydantic                                 |
+| pydantic-settings  | 2.15.0    | MIT                                                | https://github.com/pydantic/pydantic-settings                        |
+| pydantic_core      | 2.46.5    | MIT                                                | https://github.com/pydantic                                          |
+| python-dotenv      | 1.2.3     | BSD-3-Clause                                       | https://github.com/theskumar/python-dotenv                           |
+| requests           | 2.34.2    | Apache Software License                            | https://github.com/psf/requests                                      |
+| rich               | 14.3.4    | MIT License                                        | https://github.com/Textualize/rich                                   |
+| scipy              | 1.18.1    | BSD License                                        | https://scipy.org/                                                   |
+| shellingham        | 1.5.4     | ISC License (ISCL)                                 | https://github.com/sarugaku/shellingham                              |
+| tokenizers         | 0.23.2    | Apache Software License                            | https://github.com/huggingface/tokenizers                            |
+| tqdm               | 4.70.1    | MPL-2.0 AND MIT                                    | https://tqdm.github.io                                               |
+| typer              | 0.27.2    | MIT                                                | https://github.com/fastapi/typer                                     |
+| typing-inspection  | 0.4.4     | MIT                                                | https://github.com/pydantic/typing-inspection                        |
+| typing_extensions  | 4.16.0    | PSF-2.0                                            | https://github.com/python/typing_extensions                          |
+| urllib3            | 2.8.0     | MIT                                                | https://github.com/urllib3/urllib3/blob/main/CHANGES.rst             |

ragvidence-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+This inventory covers direct runtime dependencies selected for RAGvidence v0.1.0. Exact resolved versions are recorded in `uv.lock`. Each dependency remains governed by its own license; consult the installed distribution and upstream project for the complete text.
+
+| Component | Role | License identified by upstream/package metadata |
+| --- | --- | --- |
+| BM25S | Local lexical retrieval | MIT |
+| Jinja2 | Escaped HTML templating | BSD-3-Clause |
+| NumPy | Vector operations | BSD-3-Clause and bundled component licenses |
+| Pydantic | Data validation | MIT |
+| Pydantic Settings | Reserved configuration boundary | MIT |
+| Rich | Terminal presentation | MIT |
+| Typer | CLI framework | MIT |
+| FastEmbed (optional) | Local ONNX embedding runtime | Apache-2.0 |
+| BAAI/bge-small-en-v1.5 (downloaded optionally) | Default English embedding model | MIT |
+
+FastEmbed installs transitive runtime dependencies whose versions and licenses may change when `uv.lock` is updated. The resolved inventory for this release is recorded in `THIRD_PARTY_LICENSES.md`. The `py-rust-stemmers` 0.1.8 package metadata does not declare a machine-readable license; its upstream repository license file must be checked manually before each commercial release.
+
+The default model is downloaded separately on first semantic use and is not redistributed inside the core archive.

ragvidence-0.1.0/docs/bring-your-own-data.md

@@ -0,0 +1,46 @@
+# Bring your own data
+
+Start with a small reviewed slice—roughly 10–50 source units and 10–30 questions. The value comes from trustworthy labels, not corpus size.
+
+## `sources.jsonl`
+
+One JSON object per retrievable unit:
+
+```json
+{"source_unit_id":"S-17","document_id":"manual-a","heading_path":["Device A","Reset"],"body":"Hold the button for eight seconds.","evidence_ids":["E-RESET-17"],"metadata":{"language":"en"}}
+```
+
+- `source_unit_id`: stable unique identifier for the retrievable unit.
+- `document_id`: stable source-document identifier.
+- `heading_path`: authentic source headings; never generated gold-answer text.
+- `body`: original text used in the body-only baseline.
+- `evidence_ids`: reviewed facts/passages represented by this unit.
+- `metadata`: optional information; not searched in v1.
+
+## `questions.jsonl`
+
+```json
+{"question_id":"Q-001","question":"How long is the reset?","split":"dev","answerable":true,"required_evidence_ids":["E-RESET-17"],"reference_answer":"Eight seconds.","tags":["procedure"]}
+```
+
+- Answerable questions require at least one evidence ID.
+- Unanswerable questions must use an empty evidence-ID list.
+- Use `dev` for diagnosis and intervention design.
+- Keep `heldout` questions untouched until the intervention is frozen.
+- A multi-evidence answer lists every required evidence ID.
+
+## Avoid label leakage
+
+Do not place reference answers, required-evidence IDs, grader notes or invented contextual hints into searchable text. Heading context must come from the source itself. If the intervention changes source boundaries, labels or `k`, it is no longer the controlled comparison used by the guided exercise.
+
+## Validation
+
+```bash
+uv run ragvi validate workspaces/my-experiment
+```
+
+Validation rejects malformed JSON, unknown fields, duplicate IDs, answerability contradictions and required evidence that does not exist in the sources.
+
+## Choosing `k`
+
+Use the depth your application would actually pass downstream. A large `k` can hide retrieval failures while increasing noise and context cost. Keep `k` frozen across a baseline/intervention comparison.