feat: bootstrap offline RAG lab

.env.example

@@ -0,0 +1,5 @@
+RAG_MODE=mock
+EMBEDDING_PROVIDER=mock
+
+# This workshop repository intentionally requires no external API keys,
+# secrets, or network access for standard local development.

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# TODO: Replace @ORG placeholders with the actual organization or team slug when available.
+* @ORG/rag-eval-maintainers
+/tests/ @ORG/rag-eval-maintainers
+/.github/ @ORG/release-maintainers

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,19 @@
+name: Bug report
+about: Report a bug in the workshop lab
+title: ""
+labels: [bug]
+body:
+  - type: textarea
+    attributes:
+      label: Describe the bug
+      description: What happened and what was expected?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Reproduction steps
+      description: Include minimal commands or code to reproduce the issue.
+  - type: textarea
+    attributes:
+      label: Environment
+      description: Include Python version, OS, and relevant setup notes.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,19 @@
+name: Feature request
+about: Suggest an improvement or new workshop feature
+title: ""
+labels: [enhancement]
+body:
+  - type: textarea
+    attributes:
+      label: Problem
+      description: What problem does this feature solve?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Proposed solution
+      description: Describe the feature and any design constraints.
+  - type: textarea
+    attributes:
+      label: Scope
+      description: Note whether this is focused on retrieval, chunking, embeddings, MCP tooling, or docs.

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Related issue
+
+## Summary
+
+## Tests
+
+## Mock/offline verification
+
+## Scope check
+
+## Secrets check

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+
+      - name: Run Ruff
+        run: ruff check .
+
+      - name: Run pytest
+        run: pytest -q

.gitignore

@@ -0,0 +1,22 @@
+**/__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.venv/
+venv/
+env/
+.venv*/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.env.local
+.env.*
+!.env.example
+.DS_Store
+build/
+dist/
+.idea/
+.vscode/
+*.log

CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- being respectful and welcoming
+- assuming good intent
+- being constructive in feedback
+- focusing on the technical problem rather than the individual
+
+## Enforcement
+
+Project maintainers are expected to enforce this Code of Conduct fairly and consistently.
+
+## Contact
+
+If you need to report an issue, contact the maintainers through a private channel or the repository security policy.

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to Agentic RAG Lab
+
+Thank you for helping improve this workshop-focused repository.
+
+## Local setup
+
+- Use Python 3.12.
+- Create a virtual environment:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+## Testing
+
+Run the local test suite before opening a PR:
+
+```bash
+pytest -q
+ruff check .
+```
+
+## Branching and commits
+
+- Use a feature branch such as `feat/add-chunker-optimizer`
+- Keep commit messages clear and scoped
+- Keep the repository offline-first and deterministic
+
+## Pull request expectations
+
+- Add or update tests for changed behavior
+- Validate the offline/mock workflow
+- Do not add paid APIs or cloud dependencies to core examples
+- Avoid broad refactors not related to the change
+
+## Working on chunking
+
+When modifying chunking, check:
+
+- chunk size validation
+- overlap validation
+- deterministic ordering
+- empty-document handling
+- metadata preservation
+
+## Working on retrieval
+
+When modifying retrieval, check:
+
+- query validation
+- top-k boundaries
+- ordering by relevance
+- empty-index handling
+- deterministic output
+
+## Working on MCP integration
+
+Keep retrieval independent from the MCP transport layer.
+
+- validate JSON input
+- return structured output
+- do not couple the implementation to external services
+- prefer small integration tests over broad mock-heavy tests
+
+## Offline-first policy
+
+This project should never depend on paid APIs or external services for core examples. If a new dependency is needed, prefer local, minimal packages and document the reason clearly.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Workshop contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,154 @@
-# agentic-rag-lab
+# Agentic RAG Lab
+
+A small, deterministic, offline-first playground for retrieval fundamentals. The project teaches the core pieces of a retrieval pipeline without relying on external APIs, paid services, or hosted runtimes.
+
+## Purpose
+
+This repository is intentionally focused on the foundations of retrieval-augmented generation:
+
+- deterministic document loading
+- text chunking
+- consistent mock embeddings
+- FAISS-backed vector indexing
+- top-k retrieval
+- an MCP-compatible retrieval tool layer
+- reproducible, local tests
+
+The goal is to make workshop participants comfortable with the mechanics behind retrieval before they move on to larger agent frameworks or hosted vector services.
+
+## Architecture
+
+Documents
+  ↓
+Loader
+  ↓
+Chunker
+  ↓
+Mock Embeddings
+  ↓
+FAISS
+  ↓
+Retriever
+  ↓
+MCP Retrieval Tool
+
+## Requirements
+
+- Python 3.12
+- Local package installation with pip
+- No API keys or external services required
+
+## Setup
+
+Linux/macOS:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+python -m pip install -e .
+```
+
+Windows:
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+python -m pip install -e .
+```
+
+## Test
+
+```bash
+pytest -q
+```
+
+## Run Example
+
+```bash
+python examples/rag_demo.py
+```
+
+## No API Key Required
+
+This repository is offline-first and intentionally uses deterministic mock embeddings rather than paid external embedding providers. The examples and tests are designed to run entirely on local fixtures. No secret, credential, or hosted service is required for standard execution.
+
+## Architecture Explanation
+
+### Documents
+The loader reads UTF-8 text files from a directory and converts them into a lightweight `Document` model. It sorts files deterministically, filters unsupported file types, and preserves metadata such as source and filename.
+
+### Loader
+The loader is purposely small and explicit. It is responsible for turning raw files into consistent `Document` objects without performing any network access.
+
+### Chunker
+The chunker splits a document into overlapping or contiguous text units. It validates chunk size and overlap to avoid invalid configurations and always produces non-empty chunks.
+
+### Mock Embeddings
+The embeddings layer derives fixed-length vectors deterministically from string content using `hashlib.sha256`. This keeps retrieval reproducible across runs and avoids Python hash randomization.
+
+### FAISS
+FAISS provides an in-memory vector index for local search. This project uses an `IndexFlatL2` index. Distances are lower-is-better, and the retriever converts them to a "score" using the negative distance so higher scores indicate stronger matches.
+
+### Retriever
+The retriever combines a query embedding with a vector store and returns ordered retrieval results. Query strings must be non-empty; results are sorted by relevance and can be bounded by `top_k`.
+
+### MCP Retrieval Tool
+The MCP integration is intentionally thin and keeps retrieval logic independent from the transport layer. The MCP handler validates input, invokes the retriever, and returns JSON-compatible structured results.
+
+## Why these design decisions?
+
+### Why mock embeddings?
+Mock embeddings keep the workshop reproducible, deterministic, and fully offline. They teach the mechanics of retrieval without requiring any external model access.
+
+### Why FAISS?
+FAISS is a widely used local vector indexing library and works well for a small educational lab. It keeps the focus on indexing and retrieval behavior without adding cloud dependencies.
+
+### Why deterministic tests?
+The tests are designed to be local, stable, and machine-independent. That makes the repository suitable for workshop environments and CI without depending on randomness or external systems.
+
+### Why retrieval is independent from MCP?
+Separation keeps the retrieval logic reusable and testable outside the MCP layer. The MCP tool simply adapts the same retrieve interface to structured JSON payloads.
+
+### Why the repository does not use LangChain or LlamaIndex?
+Those frameworks are useful in larger systems, but they hide the mechanics that this workshop is meant to teach. This lab keeps the implementation explicit and understandable.
+
+### Why external APIs are optional rather than required?
+The repository is designed to work entirely offline. This reduces setup friction for contributors and ensures that learner exercises are repeatable regardless of network access or account setup.
+
+## Contributor Guide
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, branch workflow, and contribution expectations.
+
+## Project Structure
+
+```text
+agentic-rag-lab/
+├── src/
+│   └── rag/
+│       ├── __init__.py
+│       ├── loaders.py
+│       ├── chunkers.py
+│       ├── embeddings.py
+│       ├── vectorstore.py
+│       ├── retriever.py
+│       └── mcp_retrieval.py
+├── tests/
+├── fixtures/
+├── schemas/
+├── examples/
+├── .github/
+├── .env.example
+├── .gitignore
+├── CONTRIBUTING.md
+├── CODE_OF_CONDUCT.md
+├── LICENSE
+├── README.md
+├── SECURITY.md
+├── pyproject.toml
+├── requirements.txt
+└── .github/workflows/ci.yml
+```