[RAG Runtime] Deliver a dependency-free generic RAG package

[rica-v3]

Integration status

• [RAG API] Bootstrap the package and define generic contracts #2 / PR [RAG API] Define generic contracts and ports #5: package bootstrap, immutable contracts, typed failures, injected ports, locked verification, and repository engineering workflow — integrated
• [RAG Projection] Add revision-aware derived indexing and rebuilds #3 / PR [RAG Projection] Add revision-aware derived indexing and rebuilds #6: deterministic revision-aware projection, checkpoint/rebuild lifecycle, tests, and public integration documentation — integrated after Copilot review
• [RAG Retrieval] Implement semantic and deterministic hybrid retrieval #4 / PR [RAG Retrieval] Add deterministic semantic and hybrid retrieval #8: semantic retrieval, deterministic rank-only hybrid fusion, current-revision filtering, standalone host/user/agent guide, and final distribution verification — integrated after Copilot review with no comments

Boundary

This parent branch delivers the independently installable, Python 3.11+, runtime-dependency-free generic-rag package. It remains provider-neutral and has no story-writing-agents, SQLite/MySQL, vendor, credential, network, dynamic-loading, authorization, citation, or authoritative application-data dependency. Hosts explicitly inject and own every provider/resource and must reauthorize/revalidate/cite retrieved source data before user or agent use.

Verification

• all native children are closed and Project Done
• 139 tests on Python 3.11 and 3.14
• Ruff lint/format, strict mypy, and compileall
• wheel/sdist verification, sdist rebuild, clean installs, and isolated imports
• exact seven-module distribution, 7/7 module-index parity, 12 acyclic internal edges, empty package root
• executable independent-consumer retrieval example and local documentation links
• green parent push and pull-request CI at 0d5861e

Closes #1

[Copilot]

Pull request overview

This PR finalizes the standalone, dependency-free generic-rag Python package by delivering the full projection + retrieval runtime surface (contracts, ports, integrity helpers, retrieval workflows), plus the accompanying verification tests, CI checks, and public documentation needed for independent consumers.

Changes:

• Add deterministic projection-integrity helpers and bounded semantic + hybrid retrieval workflows (rank-only fusion, current-revision filtering, score-free hits).
• Expand contract/boundary verification with extensive unit tests and artifact/import probes to enforce “no deps / no side effects / exact exports / exact module inventory”.
• Publish end-to-end documentation (API reference + lifecycle/security guides) and formalize packaging/CI metadata for clean wheel/sdist installs.

Reviewed changes

Copilot reviewed 41 out of 42 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_retrieval_contracts.py	Adds contract tests for retrieval values (limits/query/hit/result invariants).
tests/test_projection_integrity.py	Adds golden + validation tests for extracted integrity hashing/token logic.
tests/test_ports.py	Adds contract tests for injected collaborator protocols and Borrowed semantics.
tests/test_package_boundaries.py	Enforces export surface, module inventory, dependency graph, and clean-import boundaries.
tests/test_errors.py	Verifies the public error hierarchy and __all__ surface.
tests/test_contract_values.py	Validates immutable value-object contracts (documents/fragments/embeddings).
tests/support/verify_artifacts.py	Verifies wheel/sdist contents, metadata, and safety constraints.
tests/support/clean_import_probe.py	Implements isolated-process import probe to detect forbidden side effects/imports.
src/generic_rag/retrieval.py	Implements bounded semantic retrieval + deterministic hybrid fusion (RRF rank-only).
src/generic_rag/py.typed	Marks the package as typed (PEP 561).
src/generic_rag/projection_integrity.py	Extracts deterministic integrity derivation/validation used by projection + retrieval.
src/generic_rag/ports.py	Defines the injected provider protocols and caller-owned Borrowed[T] wrapper.
src/generic_rag/errors.py	Defines the public error categories and exported surface.
src/generic_rag/__init__.py	Keeps the package root importable with an intentionally empty facade/export list.
README.md	Provides installation, host integration guidance, and verification commands.
PYTHON_MODULE_INDEX.md	Records the 7-module inventory, responsibilities, and dependency direction.
pyproject.toml	Defines packaging metadata, dependency groups, and tool configuration (ruff/mypy).
GITHUB_WORKFLOW.md	Documents the repo’s GitHub planning/traceability workflow policy.
docs/security-and-privacy.md	Documents the security/privacy boundary and host responsibilities.
docs/retrieval.md	Documents retrieval workflows, fusion semantics, outcomes, and a runnable example.
docs/projection.md	Documents projection lifecycle/state matrix and integrity algorithm usage.
docs/lifecycle.md	Documents explicit resource ownership and Borrowed lifecycle guarantees.
docs/api.md	Publishes the supported import surface, contracts, ports, and workflows.
DEPENDENCY_POLICY.md	Establishes the project’s dependency rules and lock-file expectations.
COMMIT_POLICY.md	Establishes commit hygiene and messaging requirements.
AGENTS.md	Documents the repository engineering workflow used by agents/contributors.
AGENT_TASK_RUNBOOK.md	Provides the step-by-step runbook for GitHub-tracked task execution.
.github/workflows/ci.yml	Adds CI to run tests/lint/type/build/import and artifact verification.
.codex/repository-engineering-kit.lock.json	Locks the repo-engineering kit installation details and managed assets.
.codex/agents/test_engineer.toml	Adds role guidance for test engineering in this repo.
.codex/agents/runtime_implementer.toml	Adds role guidance for production implementation in this repo.
.codex/agents/requirements_analyst.toml	Adds role guidance for requirements analysis in this repo.
.codex/agents/regression_diagnostician.toml	Adds role guidance for regression diagnosis in this repo.
.codex/agents/modularity_maintainer/PYTHON_MODULARITY_POLICY.md	Adds the Python modularity policy used to govern module boundaries/indexing.
.codex/agents/modularity_maintainer.toml	Adds role guidance for modularity/index ownership in this repo.
.codex/agents/documentation_maintainer.toml	Adds role guidance for documentation maintenance in this repo.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 42 changed files in this pull request and generated no new comments.