feat: Phase 0 Step 0.1 — monorepo and build system

.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Lint + type-check + unit tests (Ubuntu + macOS, per Step 0.1 AC)
+  # ---------------------------------------------------------------------------
+  lint-test:
+    name: Lint & Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-14]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install Python dependencies
+        run: uv sync --all-packages
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Mypy (strict)
+        run: uv run mypy packages/ apps/gateway/
+
+      - name: Pytest
+        run: uv run pytest tests/ packages/ -x -q --tb=short
+
+  # ---------------------------------------------------------------------------
+  # Secrets scan — blocks if a real credential is planted in a PR
+  # ---------------------------------------------------------------------------
+  secrets-scan:
+    name: Secrets scan (gitleaks)
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # ---------------------------------------------------------------------------
+  # Logging gates — schema + PII + event-registry (Step 0.7b)
+  # Placeholder: test file scaffolded in Step 0.7b; this job always passes
+  # until that step adds real tests.
+  # ---------------------------------------------------------------------------
+  log-gates:
+    name: Log schema + PII gates
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv sync --all-packages
+      - run: uv run pytest tests/logs/ -v || true   # non-blocking until 0.7b
+
+  # ---------------------------------------------------------------------------
+  # Dependency CVE audit
+  # ---------------------------------------------------------------------------
+  audit:
+    name: pip-audit
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - run: uv sync --all-packages
+      - run: uv run pip-audit

.github/workflows/commitlint.yml

@@ -0,0 +1,32 @@
+name: Commitlint
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  commitlint:
+    name: Check commit messages
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Lint commits
+        run: |
+          pnpm dlx commitlint \
+            --from ${{ github.event.pull_request.base.sha }} \
+            --to   ${{ github.event.pull_request.head.sha }} \
+            --verbose

.github/workflows/release-please.yml

@@ -0,0 +1,22 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          release-type: python
+          # Bump version in all package pyproject.toml files
+          extra-files: |
+            packages/core/pyproject.toml
+            apps/gateway/pyproject.toml

.gitleaks.toml

@@ -0,0 +1,20 @@
+[extend]
+useDefault = true
+
+[[rules]]
+description = "AgentContextOS API key"
+id = "rag-api-key"
+regex = '''rag_[a-zA-Z0-9]{32,}'''
+tags = ["api-key", "rag"]
+
+[allowlist]
+description = "Global allowlist"
+regexes = [
+    '''EXAMPLE_KEY''',
+    '''test_[a-z0-9_]{8,}''',
+    '''dummy_[a-z0-9_]{4,}''',
+]
+paths = [
+    '''^tests/fixtures/''',
+    '''^docs/''',
+]

.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+repos:
+  # Python linting + formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Python type checking
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.7
+          - pydantic-mypy
+        args: [--strict]
+        files: ^packages/|^apps/gateway/
+
+  # General hygiene
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: no-commit-to-branch
+        args: [--branch, main]
+
+  # Secrets scanning
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks
+
+  # JS/TS formatting
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types_or: [javascript, typescript, json, yaml, markdown]
+        exclude: ^pnpm-lock\.yaml|^\.pnpm-store/
+
+  # Conventional commit enforcement
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.29.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]

.python-version

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

Makefile

@@ -0,0 +1,88 @@
+.DEFAULT_GOAL := help
+PYTHON        := uv run python
+PYTEST        := uv run pytest
+RUFF          := uv run ruff
+MYPY          := uv run mypy
+
+.PHONY: help bootstrap lint fmt test test-contract test-logs schemas dev dev-full docker clean audit
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+	  | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# ---------------------------------------------------------------------------
+# Setup
+# ---------------------------------------------------------------------------
+bootstrap: ## Install all deps and pre-commit hooks (run once after clone)
+	@command -v uv   >/dev/null 2>&1 || (echo "uv not found — see scripts/bootstrap.sh" && exit 1)
+	@command -v pnpm >/dev/null 2>&1 || (echo "pnpm not found — npm i -g pnpm" && exit 1)
+	uv sync --all-packages
+	pnpm install
+	uv run pre-commit install
+	uv run pre-commit install --hook-type commit-msg
+	@echo "\033[32m✓ Bootstrap complete. Run 'make dev' to start the local stack.\033[0m"
+
+# ---------------------------------------------------------------------------
+# Quality gates
+# ---------------------------------------------------------------------------
+lint: ## Run ruff + mypy on all Python packages
+	$(RUFF) check .
+	$(RUFF) format --check .
+	$(MYPY) packages/ apps/gateway/
+
+fmt: ## Auto-fix ruff lint + format in-place
+	$(RUFF) check --fix .
+	$(RUFF) format .
+
+# ---------------------------------------------------------------------------
+# Testing
+# ---------------------------------------------------------------------------
+test: ## Run the full test suite (unit + contract)
+	$(PYTEST) tests/ packages/ -x -q
+
+test-contract: ## Run SPI conformance suites only
+	$(PYTEST) tests/contract/ -v -m contract
+
+test-logs: ## Run logging schema + PII + registry gates
+	$(PYTEST) tests/logs/ -v
+
+# ---------------------------------------------------------------------------
+# Schemas
+# ---------------------------------------------------------------------------
+schemas: ## Generate JSON Schema + Proto artifacts → dist/schemas/
+	@mkdir -p dist/schemas
+	$(PYTHON) -m rag_core.gen_schemas dist/schemas/
+	@echo "\033[32m✓ Schemas written to dist/schemas/\033[0m"
+
+# ---------------------------------------------------------------------------
+# Local dev stack
+# ---------------------------------------------------------------------------
+dev: ## Start core local stack (postgres, redis, qdrant)
+	docker compose --profile core up -d
+	@echo "\033[32m✓ Core stack running. Postgres=5432, Redis=6379, Qdrant=6333\033[0m"
+
+dev-full: ## Start core + full observability stack
+	docker compose --profile core --profile observability up -d
+	@echo "\033[32m✓ Full stack running. Grafana=3001, Jaeger=16686, Prometheus=9090\033[0m"
+
+dev-down: ## Stop all local stack services
+	docker compose --profile core --profile observability down
+
+docker: ## Build all Docker images
+	docker compose build
+
+# ---------------------------------------------------------------------------
+# Security
+# ---------------------------------------------------------------------------
+audit: ## Run pip-audit for dependency CVEs
+	uv run pip-audit
+
+# ---------------------------------------------------------------------------
+# Cleanup
+# ---------------------------------------------------------------------------
+clean: ## Remove build artefacts, caches, and __pycache__
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null; true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null; true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null; true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null; true
+	rm -rf dist/ .pytest_cache/ htmlcov/ .coverage

README.md

@@ -2,10 +2,57 @@
 
 **One-stop RAG platform for enterprise AI** — pluggable retrieval, multi-tenancy, agent loops, full observability.
 
+## Quick start
+
+```bash
+# Prerequisites: uv, pnpm, docker
+./scripts/bootstrap.sh   # or: make bootstrap
+
+make dev        # start postgres + redis + qdrant
+make dev-full   # + otel-collector, jaeger, prometheus, grafana, loki
+
+make lint       # ruff + mypy
+make test       # full test suite
+make help       # all targets
+```
+
 ## Repository layout
 
 ```
 AgentContextOS/
+├── packages/
+│   └── core/              # Domain types, errors, plugin SPIs (Step 0.2–0.3)
+├── apps/
+│   ├── gateway/           # FastAPI HTTP/gRPC gateway (Phase 3)
+│   └── admin-ui/          # Next.js operator GUI (Phase 3)
+├── tests/
+│   ├── contract/          # SPI conformance suites (Step 0.3)
+│   ├── eval/              # Golden set, baselines, thresholds (Phase 5)
+│   └── logs/              # Log schema + PII gates (Step 0.7b)
+├── proto/                 # Protobuf definitions (Step 0.2)
+├── infra/
+│   ├── otel/              # OTel collector config
+│   └── prometheus/        # Prometheus scrape config
+├── docs/
+│   ├── adr/               # Architecture Decision Records
+│   ├── architecture/      # HLD + architecture diagram
+│   └── research/          # RAG problems catalog
+├── scripts/
+│   └── bootstrap.sh       # One-shot setup for a fresh clone
+├── docker-compose.yml     # Local dev stack (core + observability profiles)
+├── rag.yaml               # Platform config contract (Step 0.4)
+├── pyproject.toml         # Python uv workspace root
+├── pnpm-workspace.yaml    # JS/TS pnpm workspace
+└── Makefile               # All developer commands
+```
+
+## Documentation
+
+- [High-Level Design](docs/architecture/RAG-Platform-HLD.md) — architecture, components, KPIs
+- [Execution Plan](planning/README.md) — 8-phase build plan with testable steps
+- [Logging Standard](planning/LOGGING-STANDARD.md) — mandatory structured-logging contract
+- [GUI Specification](planning/GUI-SPECIFICATION.md) — operator dashboard spec
+- [ADR-0001](docs/adr/ADR-0001-monorepo-and-tech-stack.md) — monorepo and tech stack decisions
 ├── docs/
 │   ├── architecture/          # Design documents
 │   │   ├── RAG-Platform-HLD.md          — High-Level Design (architecture, components, KPIs)

apps/admin-ui/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@ragplatform/admin-ui",
+  "version": "0.1.0",
+  "private": true,
+  "description": "AgentContextOS operator GUI — implemented in Phase 3 Step 3.10 / Step 3.11",
+  "scripts": {
+    "dev": "echo 'Admin UI scaffolded in Phase 3 Step 3.10'",
+    "build": "echo 'Admin UI scaffolded in Phase 3 Step 3.10'",
+    "lint": "echo 'Admin UI scaffolded in Phase 3 Step 3.10'"
+  }
+}