feat(engine): scaffold the uv workspace with engine and code-rag packages

.gitattributes

@@ -0,0 +1,7 @@
+* text=auto eol=lf
+*.ps1 text eol=crlf
+*.pdf binary
+*.pptx binary
+*.docx binary
+*.png binary
+*.jpg binary

.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.import_linter_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Data, models and raw results
+data/
+research/**/results/raw/
+models/
+*.gguf
+*.safetensors
+
+# IDE and OS
+.idea/
+.vscode/
+.DS_Store

.python-version

@@ -0,0 +1 @@
+3.11

packages/code-rag/README.md

@@ -0,0 +1,10 @@
+# agentic-rag-code
+
+`agentic-rag-code` is the AST-aware code retrieval extension, imported as `agentic_rag_code`. It provides:
+
+- tree-sitter parsing for Python and TypeScript;
+- a symbol and call graph;
+- symbol-level chunking;
+- a code retriever that returns standard evidence packs.
+
+It depends only on the public ports and types of `agentic_rag`. The design is described in `docs/specs/2026-10-16-agentic-rag-design.md` (section 6).

packages/code-rag/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "agentic-rag-code"
+version = "0.0.0"
+description = "AST-aware code retrieval extension for the agentic-rag engine."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["agentic-rag"]
+
+[tool.uv.sources]
+agentic-rag = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentic_rag_code"]

packages/code-rag/src/agentic_rag_code/__init__.py

@@ -0,0 +1,5 @@
+"""AST-aware code retrieval extension for the agentic-rag engine."""
+
+from importlib.metadata import version
+
+__version__ = version("agentic-rag-code")

packages/code-rag/tests/test_code_rag_smoke.py

@@ -0,0 +1,5 @@
+import agentic_rag_code
+
+
+def test_version_is_exposed() -> None:
+    assert agentic_rag_code.__version__ == "0.0.0"

packages/engine/README.md

@@ -0,0 +1,12 @@
+# agentic-rag
+
+`agentic-rag` is the domain-agnostic RAG engine, imported as `agentic_rag`. It provides:
+
+- core types;
+- ports defined as `typing.Protocol`;
+- ingestion and retrieval pipelines;
+- the citation-bearing evidence pack;
+- evaluation metrics;
+- optional backend adapters, installed as extras.
+
+The architecture is described in `docs/specs/2026-10-16-agentic-rag-design.md` (section 5).

packages/engine/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "agentic-rag"
+version = "0.0.0"
+description = "Domain-agnostic, local-first RAG engine built on ports and adapters."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentic_rag"]

packages/engine/src/agentic_rag/__init__.py

@@ -0,0 +1,5 @@
+"""Domain-agnostic, local-first RAG engine built on ports and adapters."""
+
+from importlib.metadata import version
+
+__version__ = version("agentic-rag")

packages/engine/tests/test_engine_smoke.py

@@ -0,0 +1,5 @@
+import agentic_rag
+
+
+def test_version_is_exposed() -> None:
+    assert agentic_rag.__version__ == "0.0.0"

pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "agentic-rag-workspace"
+version = "0.0.0"
+description = "Workspace root for the Agentic-RAG engine, Code-RAG extension and research tooling."
+requires-python = ">=3.11"
+dependencies = ["agentic-rag", "agentic-rag-code"]
+
+[dependency-groups]
+dev = ["ruff", "mypy", "pytest", "pytest-cov", "import-linter"]
+
+[tool.uv]
+package = false
+
+[tool.uv.workspace]
+members = ["packages/*"]
+
+[tool.uv.sources]
+agentic-rag = { workspace = true }
+agentic-rag-code = { workspace = true }

research/README.md

@@ -0,0 +1,3 @@
+# Research
+
+This directory holds the research tooling for the AST-aware Code-RAG benchmark. None of it is a published package. Code that other code depends on lives in `packages/`.

research/benchmark/README.md

@@ -0,0 +1,7 @@
+# Benchmark
+
+This directory holds the benchmark runners and metrics:
+
+- retrieval metrics: Recall@K, Precision@K, MRR and nDCG;
+- the agent metric, Task Completion Rate;
+- system metrics: latency and VRAM per stage.

research/datasets/README.md

@@ -0,0 +1,3 @@
+# Datasets
+
+This directory holds the dataset build scripts and dataset cards. The data itself is fetched or generated into `data/`, which git ignores, and is never committed. Only scripts, checksums, manifests and cards are versioned.

research/experiments/README.md

@@ -0,0 +1,3 @@
+# Experiments
+
+Each experiment has its own folder containing a `config.yaml` and `results/*.json`. Results are metrics-only. Each result records the git SHA, the model hashes and the hardware it ran on.

research/report/README.md

@@ -0,0 +1,3 @@
+# Report
+
+This directory holds the sources of the public technical report that compares naive text RAG with AST-aware RAG on local small language models.

services/README.md

@@ -0,0 +1,3 @@
+# Services
+
+This directory holds the non-Python runtime services that the engine adapters talk to. The first one is the QVAC worker, `qvac-worker`. It is ported from BitPolito Academy in milestone E3.