{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Agent Skills Lab · Build, Select, Compose, and Test Skills\n",
    "\n",
    "StatsPAI Summer Bootcamp 配套 notebook。配合知识页 `/courses/summer-bootcamp/topics/agent-skills`。\n",
    "\n",
    "把一段**可复用的研究流程**封装成 Skill（名称 + 何时用 + 步骤 + 脚本 + 测试），让 Agent 可发现、可组合、可测试地反复执行——而不是每次重写 prompt。\n",
    "\n",
    "> 依赖：`pandas`（读 registry）。无需联网、无需大模型。\n",
    "> 三条红线：技能要有测试；组合要算可靠性；上下文用渐进式披露，别一次性塞满。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. 读入技能清单（registry）"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "execution_count": null,
   "source": [
    "import json, pandas as pd\n",
    "reg = json.load(open('skill_registry.json'))\n",
    "print(pd.DataFrame(reg).T[['when_to_use','pass_rate']].to_string())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. 技能选择：按任务描述匹配（像工具发现，但更高层）"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "execution_count": null,
   "source": [
    "def select(task, reg):\n",
    "    tok = set(task.lower().split())\n",
    "    scored = {n: len(tok & set(v['when_to_use'].split())) for n, v in reg.items()}\n",
    "    return max(scored, key=scored.get), scored\n",
    "best, scores = select('estimate an event study for a staggered treatment in panel data', reg)\n",
    "print('scores:', scores)\n",
    "print('selected:', best)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. 组合成流水线（带前置 gate）"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "execution_count": null,
   "source": [
    "def clean_panel(s): s['clean']=True; return s\n",
    "def event_study(s):\n",
    "    assert s.get('clean'), 'needs clean panel'\n",
    "    s['coefs']=[0.01,0.04,0.12]; return s\n",
    "def make_table(s):\n",
    "    assert 'coefs' in s, 'needs estimates'\n",
    "    s['table']='outputs/event_study.tex'; return s\n",
    "state={'panel':'firm-year.csv'}\n",
    "for skill in (clean_panel, event_study, make_table): state=skill(state)\n",
    "print('artifacts:', {k: state[k] for k in ('clean','coefs','table')})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. 流水线可靠性 = 各技能通过率之积"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "execution_count": null,
   "source": [
    "import math\n",
    "rates = {n: v['pass_rate'] for n, v in reg.items() if n in ('clean_panel','event_study','make_table')}\n",
    "R = math.prod(rates.values())\n",
    "print('per-skill:', rates)\n",
    "print(f'pipeline reliability = {R:.3f}  (failure = {1-R:.3f})')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. 渐进式披露：只在触发时加载技能正文（上下文经济）"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "execution_count": null,
   "source": [
    "cost = {'clean_panel':{'index':40,'body':1200},'event_study':{'index':45,'body':1500},'make_table':{'index':38,'body':900}}\n",
    "idx = sum(c['index'] for c in cost.values())\n",
    "prog = idx + cost['event_study']['body']\n",
    "allin = idx + sum(c['body'] for c in cost.values())\n",
    "print('index-only:', idx, '| progressive:', prog, '| load-all:', allin)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. 技能测试：技能和代码一样需要测试"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "execution_count": null,
   "source": [
    "def event_study_skill(n):\n",
    "    if n < 2: raise ValueError('need >= 2 periods')\n",
    "    return {'ok': True, 'periods': n}\n",
    "res = []\n",
    "for tc in [5,3,1,8,0]:\n",
    "    try: event_study_skill(tc); res.append(True)\n",
    "    except Exception: res.append(False)\n",
    "print('results:', res, '| pass rate:', sum(res)/len(res))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. 接下来\n",
    "- 把每个技能落成真目录：`SKILL.md`（何时用 + 步骤）+ `scripts/` + `tests/` + `examples/`。\n",
    "- 技能调用真工具：pandas 清洗、StatsPAI `event_study` 估计、`etable` 出表。\n",
    "- 组合时显式写 gate 与回退；为每个技能维护测试用例与通过率。\n",
    "\n",
    "**作业**见同目录 `agent_skills_assignment.md`。"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.x"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}