Feat/repo concierge

README.md

@@ -25,7 +25,7 @@ Every method can be used in one of two modes, and the distinction runs through t
 
 Each is independent and self-contained — pick the one that matches the problem you care about, and read that directory's `README.md` for the full walkthrough. They are numbered in a recommended order that mirrors the bootcamp progression — conventional numerical methods → LLM Processes → agents → agentic evaluation — but any one stands on its own, so jump straight to the problem you care about.
 
-**Start here → #0 [`getting_started/`](implementations/getting_started/)** — one CPI series, one month ahead. The smallest end-to-end loop: a `Predictor`, a `BacktestSpec` and `EvalSpec`, naive + AutoARIMA baselines, CRPS scoring. The place to learn the evaluation framework before picking a domain below.
+**Start here → #0 [`getting_started/`](implementations/getting_started/)** — one CPI series, one month ahead. The smallest end-to-end loop: a `Predictor`, a `BacktestSpec` and `EvalSpec`, naive + AutoARIMA baselines, CRPS scoring. The place to learn the evaluation framework before picking a domain below. Also includes [`99_repo_concierge.ipynb`](implementations/getting_started/99_repo_concierge.ipynb) — a lite-model repo guide for “how does this codebase work?” questions (`uv run adk run implementations/getting_started/concierge_agent` from the repo root).
 
 | #   | Implementation                                                       | The problem                                                                     | Concepts & techniques it demonstrates                                                                                                                                                                                                                                                                       |
 | --- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

implementations/README.md

@@ -32,6 +32,8 @@ YAML backtest and eval specs live under each use case in `specs/`. Each director
 
 Every domain use case (all except `getting_started`) also ships a `starter_agent/` module and a `99_starter_agent.ipynb` — a fresh, hackable **starter agent** that is the consistent "build your own" entry point for that use case (toggleable news search + code execution, two lightweight tool-usage skills, an interactive cell, and one scored forecast).
 
+`getting_started/` additionally ships a **`concierge_agent/`** module and **`99_repo_concierge.ipynb`** — a repo onboarding helper (not a forecaster) that answers questions about how the codebase works using a committed public-`main` knowledge digest. From the repository root: `uv run adk run implementations/getting_started/concierge_agent`. See [`getting_started/README.md`](getting_started/README.md) and the notebook for full usage.
+
 ---
 
 ## Relationship to `aieng-forecasting`

implementations/getting_started/99_repo_concierge.ipynb

@@ -0,0 +1,241 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Repo Concierge — ask questions about this codebase\n",
+        "\n",
+        "> **Note:** This agent uses a snapshot of the public `main` branch (not your local\n",
+        "> uncommitted changes or `data/` cache). Like any LLM, it can be wrong — verify\n",
+        "> important details against the repo or ask a facilitator.\n",
+        "\n",
+        "**Not sure how something works? Start here.**\n",
+        "\n",
+        "The repo concierge helps you **find your way** — it answers questions, points you\n",
+        "to the right notebooks and modules, and can quote short snippets so you know\n",
+        "where to dig deeper. Example questions:\n",
+        "\n",
+        "- *How do I create a new data service?*\n",
+        "- *How do I customize the way context is presented to an LLMP?*\n",
+        "- *What's the difference between `backtest()` and `evaluate()`?*\n",
+        "\n",
+        "It searches a committed **catalog** of the codebase (`search_repo_catalog` →\n",
+        "`fetch_repo_artifact`): full `aieng/forecasting`, reference implementations, and\n",
+        "notebooks (markdown + code cells). Domain `99_starter_agent.ipynb` notebooks are\n",
+        "for building forecasters; this one is your map of the repo.\n",
+        "\n",
+        "Live cells are gated by `RUN_AGENT` so `Run All` is safe and free; set it to `True`\n",
+        "to call the model."
+      ],
+      "id": "cell-00"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import warnings\n",
+        "from pathlib import Path\n",
+        "\n",
+        "from IPython.display import Markdown, display  # noqa: A004\n",
+        "\n",
+        "\n",
+        "warnings.filterwarnings(\"ignore\")\n",
+        "\n",
+        "from dotenv import load_dotenv\n",
+        "\n",
+        "\n",
+        "def find_repo_root(start: Path | None = None) -> Path:\n",
+        "    \"\"\"Walk upward until we find the workspace root.\"\"\"\n",
+        "    here = (start or Path.cwd()).resolve()\n",
+        "    for cand in (here, *here.parents):\n",
+        "        if (cand / \"pyproject.toml\").exists() and (cand / \"aieng-forecasting\").is_dir():\n",
+        "            return cand\n",
+        "    return Path.cwd().resolve().parents[1]\n",
+        "\n",
+        "\n",
+        "ROOT = find_repo_root()\n",
+        "load_dotenv(ROOT / \".env\", override=False)\n",
+        "\n",
+        "# ── Model selection ───────────────────────────────────\n",
+        "# Concierge uses the lite/default model only.\n",
+        "AGENT_MODEL = \"gemini-3.1-flash-lite-preview\"\n",
+        "\n",
+        "# ── Run guard ──────────────────────────────────────\n",
+        "RUN_AGENT = True\n",
+        "\n",
+        "from getting_started.concierge_agent import build_concierge_config\n",
+        "\n",
+        "\n",
+        "print(\"RUN_AGENT =\", RUN_AGENT, \"| model =\", AGENT_MODEL)"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-01"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "## 1. Meet the concierge\n",
+        "\n",
+        "The agent uses a **catalog + artifacts** knowledge pack shipped under `concierge_agent/context/` — no build step for participants.\n",
+        "\n",
+        "1. **`search_repo_catalog`** — search metadata (paths, summaries, domains); cheap, run first.\n",
+        "2. **`fetch_repo_artifact`** — fetch full content for a catalog path (Python modules, READMEs, notebooks with **markdown + code cells**).\n",
+        "\n",
+        "Maintainers regenerate the pack from public `main` with `scripts/build_concierge_context.py` when library code or notebooks change. The `repo-navigation` skill has reference guides (no scripts)."
+      ],
+      "id": "cell-02"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "config = build_concierge_config(model=AGENT_MODEL)\n",
+        "\n",
+        "print(\"Agent:\", config.name)\n",
+        "print(\"Search enabled:    \", config.context_retrieval.enabled)\n",
+        "print(\"Code-exec enabled: \", config.code_execution.enabled)\n",
+        "print(\"Skills loaded:     \", [p.name for p in config.skills_dirs])\n",
+        "print(\"Extra tools:       \", [getattr(t, \"__name__\", repr(t)) for t in config.extra_tools])\n",
+        "display(Markdown(\"### System instruction\\n\\n*Edit in `concierge_agent/agent.py`*\"))\n",
+        "display(Markdown(config.instruction))"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-03"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "## 2. Try a seed question\n",
+        "\n",
+        "Edit `QUESTION` below, or jump to the next section for a multi-turn conversation."
+      ],
+      "id": "cell-04"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from aieng.forecasting.methods.agentic import build_adk_agent\n",
+        "from aieng.forecasting.methods.agentic.adk_runner import AdkTextRunner, AdkTextRunnerConfig\n",
+        "\n",
+        "\n",
+        "QUESTION = \"How do I create a new data service?\"\n",
+        "\n",
+        "if RUN_AGENT:\n",
+        "    chat_agent = build_adk_agent(config)\n",
+        "    runner = AdkTextRunner(chat_agent, config=AdkTextRunnerConfig(app_name=\"repo_concierge_chat\"))\n",
+        "    reply = await runner.run_text_async(QUESTION)  # noqa: F704, PLE1142\n",
+        "    display(Markdown(reply))\n",
+        "else:\n",
+        "    print(\"RUN_AGENT is False — set it to True in the setup cell to ask the concierge.\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-05"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "QUESTION = \"How do I customize the way context is presented to an LLMP?\"\n",
+        "\n",
+        "if RUN_AGENT:\n",
+        "    reply = await runner.run_text_async(QUESTION)  # noqa: F704, F821, PLE1142\n",
+        "    display(Markdown(reply))\n",
+        "else:\n",
+        "    print(\"RUN_AGENT is False — set it to True to run this cell.\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-05b"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "QUESTION = \"What's the difference between backtest() and evaluate()?\"\n",
+        "\n",
+        "if RUN_AGENT:\n",
+        "    reply = await runner.run_text_async(QUESTION)  # noqa: F704, F821, PLE1142\n",
+        "    display(Markdown(reply))\n",
+        "else:\n",
+        "    print(\"RUN_AGENT is False — set it to True to run this cell.\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-05c"
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "QUESTION = \"Where should I go after getting_started if I want to build agents?\"\n",
+        "\n",
+        "if RUN_AGENT:\n",
+        "    reply = await runner.run_text_async(QUESTION)  # noqa: F704, F821, PLE1142\n",
+        "    display(Markdown(reply))\n",
+        "else:\n",
+        "    print(\"RUN_AGENT is False — set it to True to run this cell.\")"
+      ],
+      "execution_count": null,
+      "outputs": [],
+      "id": "cell-05d"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "---\n",
+        "## 3. Terminal mode — multi-turn conversations\n",
+        "\n",
+        "For extended back-and-forth, use the ADK CLI from the **repository root**:\n",
+        "\n",
+        "```bash\n",
+        "uv run adk run implementations/getting_started/concierge_agent\n",
+        "```\n",
+        "\n",
+        "That loads the same `repo_concierge` agent (`gemini-3.1-flash-lite-preview`) with\n",
+        "`search_repo_catalog`, `fetch_repo_artifact`, and the repo-navigation skill.\n",
+        "\n",
+        "**Alternative:** `uv run adk web implementations/getting_started/concierge_agent`\n",
+        "opens a browser UI (same agent). From `implementations/getting_started/`, you can\n",
+        "also use the shorter `uv run adk run concierge_agent`.\n",
+        "\n",
+        "---\n",
+        "\n",
+        "**Where next?** Forecasting starter agents live in each domain implementation's\n",
+        "`99_starter_agent.ipynb` (food, energy, BoC, S&P 500). This concierge helps you\n",
+        "navigate the repo — open one of those when you're ready to build and score a forecaster."
+      ],
+      "id": "cell-08"
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": ".venv",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.12.3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

implementations/getting_started/README.md

@@ -139,6 +139,33 @@ against [`cpi_gasoline_eval_2025.yaml`](specs/cpi_gasoline_eval_2025.yaml)
 — monthly origins from Jan 2025 through Mar 2026, all currently resolved.
 `max_runs: 5` — spend deliberately.
 
+### 6. Ask the repo concierge — `99_repo_concierge.ipynb`
+
+**Questions about how the repository works?** Open
+[`99_repo_concierge.ipynb`](99_repo_concierge.ipynb) — a lite-model **repo
+concierge** that answers onboarding questions, points you to the right notebooks
+and modules, and can quote snippets from the committed public-`main` catalog.
+
+- Notebook cells are gated by `RUN_AGENT` (safe `Run All`).
+- For longer conversations, run the ADK CLI from the **repository root**:
+
+  ```bash
+  uv run adk run implementations/getting_started/concierge_agent
+  ```
+
+  (`uv run adk web implementations/getting_started/concierge_agent` opens the same
+  agent in a browser.)
+
+  From `implementations/getting_started/`, the shorter `uv run adk run concierge_agent`
+  works too.
+
+This is different from each domain's `99_starter_agent.ipynb` — those are
+hackable **forecasting** agents; the concierge only explains the repo.
+
+Maintainers regenerate the catalog with
+`uv run python scripts/build_concierge_context.py` when library code,
+implementations, or notebooks change.
+
 ---
 
 ## Where to go next
@@ -166,9 +193,11 @@ what you're building:
 getting_started/                 # this directory
 ├── README.md
 ├── specs/                       # backtest and eval YAML
+├── concierge_agent/             # repo concierge ADK agent + catalog + artifacts
 ├── 00_environment_check.ipynb   # self-guided setup preflight — run this first
 ├── 01_cpi_data_exploration.ipynb
-└── 02_cpi_backtest_demo.ipynb
+├── 02_cpi_backtest_demo.ipynb
+└── 99_repo_concierge.ipynb      # ask questions about the repo (onboarding helper)
 ```
 
 Reference predictors live in the `aieng-forecasting` package under

implementations/getting_started/__init__.py

@@ -0,0 +1 @@
+"""Getting started reference implementation (notebooks + repo concierge agent)."""

implementations/getting_started/concierge_agent/__init__.py

@@ -0,0 +1,21 @@
+"""Repo concierge agent — onboarding helper for the agentic-forecasting codebase.
+
+Exports the :class:`AgentConfig` factory and the knowledge-search tool. Pair
+with ``99_repo_concierge.ipynb`` or ``adk run implementations/getting_started/concierge_agent``
+from the repository root.
+"""
+
+from getting_started.concierge_agent.agent import build_concierge_config
+from getting_started.concierge_agent.catalog import (
+    fetch_repo_artifact,
+    search_repo_catalog,
+)
+from getting_started.concierge_agent.knowledge import search_repo_knowledge
+
+
+__all__ = [
+    "build_concierge_config",
+    "fetch_repo_artifact",
+    "search_repo_catalog",
+    "search_repo_knowledge",
+]