[RAG API] Define generic contracts and ports

[rica-v3]

Summary

• add the standalone generic-rag 0.1.0 package with immutable provider-neutral values, typed failures, synchronous collaborator protocols, and caller-owned Borrowed resources
• keep the package root empty and imports side-effect-free, with no runtime dependencies, algorithms, adapters, providers, storage, network, or application concepts
• add a uv lock, commit-pinned CI, 53 contract/boundary tests, clean artifact and install probes, public API/lifecycle/privacy documentation, and a four-module Python index

Boundary

This child establishes contracts only. Projection/chunking remains in #3 and retrieval/fusion/composition remains in #4. Public imports come from generic_rag.errors, generic_rag.contracts, and generic_rag.ports; the root has no re-exports.

Verification

• requirements and binding modularity analysis: complete
• final modularity review after tests and docs: approved
• Python 3.11.16: 53/53 tests passed from the built wheel
• Python 3.14.2: 53/53 tests passed from the same built wheel
• Ruff lint and format: passed
• strict mypy across source and tests: passed
• compileall: passed
• wheel and sdist build plus safe artifact verification: passed
• sdist rebuild, offline no-dependency wheel install, dependency check, metadata and py.typed verification: passed
• isolated checkout-excluded imports for all four modules: passed
• source/index parity: 4/4, acyclic
• GitHub push CI: https://github.com/Kims-DeveloperGroup/generic-rag/actions/runs/32810261949

Dependency policy

• [project].dependencies is empty
• uv 0.12.5 generated the committed universal lock; it was not hand-edited
• direct development/build constraints are setuptools 83-84, build 1.x, Ruff 0.16.x, and mypy 2.x
• every resolved direct and transitive development package was checked for current maintenance, Python compatibility, license, size, and GitHub Advisory Database coverage; no advisory affects the locked versions

Refs #2

[Copilot]

Pull request overview

Introduces the initial generic-rag Python distribution as a provider-neutral “contracts-only” foundation: immutable validated value objects, typed public error categories, and synchronous collaborator protocols with explicit caller-owned borrowing. The change also establishes packaging, verification, and boundary/architecture enforcement so downstream projection (#3) and retrieval (#4) work can depend on stable public contracts.

Changes:

• Add generic_rag public modules (errors, contracts, ports) plus an intentionally empty package root, with strict runtime validation and closed string enums.
• Add comprehensive contract/boundary test suite including clean-import and artifact verification probes.
• Add packaging (pyproject.toml, py.typed), CI workflow, and supporting documentation/policies including the Python module index.

Reviewed changes

Copilot reviewed 33 out of 34 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_retrieval_contracts.py	Contract tests for retrieval values (query/hit/result/outcomes) and invariants (bounded, score-free, rank/dedup rules).
tests/test_projection_contracts.py	Contract tests for projection identity/checkpoint/receipt and outcome/count/checkpoint invariants.
tests/test_ports.py	Contract tests for runtime-checkable protocols and the Borrowed lifecycle/no-op semantics, plus deterministic witnesses.
tests/test_package_boundaries.py	Boundary tests: exact module inventory/exports, internal dependency graph, forbidden imports/operations, clean isolated imports, module-index parity.
tests/test_errors.py	Tests for public exception exports and hierarchy invariants.
tests/test_contract_values.py	Contract tests for core immutable value objects (documents/fragments/embeddings) and runtime type exactness.
tests/support/verify_artifacts.py	Wheel/sdist structural verification (no deps, no shipped tests, expected file set, safe archive member rules, metadata checks).
tests/support/clean_import_probe.py	Isolated import probe with audit-hook and patched APIs to forbid I/O, process, network, or thread actions at import time.
src/generic_rag/py.typed	Declares the package as typed (PEP 561 marker).
src/generic_rag/ports.py	Defines collaborator Protocols (Embedder, index reader/writer, lexical retriever) and Borrowed[T] context manager contract.
src/generic_rag/errors.py	Defines public error categories and exported surface (__all__).
src/generic_rag/contracts.py	Implements frozen/slotted validated contract dataclasses and closed StrEnum outcomes for projection and retrieval.
src/generic_rag/init.py	Establishes an import-only root with no re-exports (__all__ = ()).
README.md	Project overview, usage example, boundary statements, planned issues linkage, and local verification commands.
PYTHON_MODULE_INDEX.md	Module inventory/index documenting responsibilities, exports, dependencies, side effects, and verification references.
pyproject.toml	Packaging metadata, empty runtime dependencies, setuptools config, Ruff/Mypy configuration, and dependency groups.
GITHUB_WORKFLOW.md	GitHub workflow policy defining planning gate, metadata, branching/PR rules, and traceability requirements.
docs/security-and-privacy.md	Documents security/privacy boundary and caller responsibilities for sensitive data and provider effects.
docs/lifecycle.md	Documents explicit caller-owned lifecycle model and Borrowed[T] semantics.
docs/api.md	Public API reference: exports, invariants, value rules, outcomes, ports, and non-goals for 0.1.0.
DEPENDENCY_POLICY.md	Dependency governance for Python packaging and lockfile discipline.
COMMIT_POLICY.md	Commit structure and hygiene rules for coherent reviewable history.
AGENTS.md	Repository engineering workflow and gates used by contributors/agents.
AGENT_TASK_RUNBOOK.md	Operational runbook for planning gate, branch/worktree model, and traceability verification steps.
.github/workflows/ci.yml	CI matrix with pinned actions, uv-based locked env setup, tests, lint/format/type/compile checks, and artifact/import verification.
.codex/repository-engineering-kit.lock.json	Locks repository-engineering kit installation/profiles and managed file provenance.
.codex/agents/test_engineer.toml	Defines test specialist role and expectations.
.codex/agents/runtime_implementer.toml	Defines runtime implementation specialist role and constraints.
.codex/agents/requirements_analyst.toml	Defines read-only requirements analyst role and modularity gate classification responsibilities.
.codex/agents/regression_diagnostician.toml	Defines read-only regression diagnostician role and boundary impact reporting.
.codex/agents/modularity_maintainer/PYTHON_MODULARITY_POLICY.md	Python modularity policy governing boundaries, index requirements, and compatibility rules.
.codex/agents/modularity_maintainer.toml	Defines modularity maintainer role, modes, and index/policy workflow.
.codex/agents/documentation_maintainer.toml	Defines documentation maintainer role and constraints.

---

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