doc: Add comprehensive documentation

fix: Typo in `Server.tactic_invocations`

docs/_toc.yml

@@ -5,7 +5,8 @@ parts:
   chapters:
   - file: setup
   - file: goal
-  - file: proof_search
+  - file: agent-search
+  - file: data
   - file: drafting
 - caption: API Documentation
   chapters:

docs/agent-search.ipynb

@@ -0,0 +1,155 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "ec3abb52-d7cd-471f-b3b7-2d9681c79360",
+   "metadata": {},
+   "source": [
+    "# Search\n",
+    "\n",
+    "Pantograph supports basic proof search. In this case, Pantograph treats goals as nodes on an and-or tree. The user supplies an agent which should provide two functions:\n",
+    "\n",
+    "1. *Tactic*: Which tactic should be used on a goal?\n",
+    "2. *Guidance*: What is the search priority on a goal?\n",
+    "\n",
+    "The user agent should inherit from `pantograph.search.Agent`. Here is a brute force agent example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "959458f5-02e4-4f73-ae28-16a756aebed9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from typing import Optional\n",
+    "import collections\n",
+    "from pantograph import Server\n",
+    "from pantograph.search import Agent\n",
+    "from pantograph.expr import GoalState, Tactic"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "8b402602-3ae5-43e4-9a62-2fa9e2c039fa",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class DumbAgent(Agent):\n",
+    "\n",
+    "    def __init__(self):\n",
+    "        super().__init__()\n",
+    "\n",
+    "        self.goal_tactic_id_map = collections.defaultdict(lambda : 0)\n",
+    "        self.intros = [\n",
+    "            \"intro\",\n",
+    "        ]\n",
+    "        self.tactics = [\n",
+    "            \"intro h\",\n",
+    "            \"cases h\",\n",
+    "            \"apply Or.inl\",\n",
+    "            \"apply Or.inr\",\n",
+    "        ]\n",
+    "        self.no_space_tactics = [\n",
+    "            \"assumption\",\n",
+    "        ]\n",
+    "\n",
+    "    def next_tactic(\n",
+    "            self,\n",
+    "            state: GoalState,\n",
+    "            goal_id: int,\n",
+    "    ) -> Optional[Tactic]:\n",
+    "        key = (state.state_id, goal_id)\n",
+    "        i = self.goal_tactic_id_map[key]\n",
+    "\n",
+    "        target = state.goals[goal_id].target\n",
+    "        if target.startswith('∀'):\n",
+    "            tactics = self.intros\n",
+    "        elif ' ' in target:\n",
+    "            tactics = self.tactics\n",
+    "        else:\n",
+    "            tactics = self.no_space_tactics\n",
+    "\n",
+    "        if i >= len(tactics):\n",
+    "            return None\n",
+    "\n",
+    "        self.goal_tactic_id_map[key] = i + 1\n",
+    "        return tactics[i]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "665db9d0-5fff-4b26-9cea-32d06a6e1e04",
+   "metadata": {},
+   "source": [
+    "Execute the search with `agent.search`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "1c7961d1-b1fa-498c-ab75-16feb784ca2c",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "SearchResult(n_goals_root=1, duration=0.7717759609222412, success=True, steps=16)"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "server = Server()\n",
+    "agent = DumbAgent()\n",
+    "goal_state = server.goal_start(\"∀ (p q: Prop), Or p q -> Or q p\")\n",
+    "agent.search(server=server, goal_state=goal_state, verbose=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "141e0116-cbb6-4957-aaea-2a1100f80ece",
+   "metadata": {},
+   "source": [
+    "## Automatic and Manual Modes\n",
+    "\n",
+    "The agent chooses one goal and executes a tactic on this goal. What happens to the other goals that are not chosen? By default, the server runs in automatic mode. In automatic mode, all other goals are automatically inherited by a child state, so a user agent could declare a proof finished when there are no more goals remaining in the current goal state.\n",
+    "\n",
+    "Some users may wish to handle sibling goals manually. For example, Aesop's treatment of metavariable coupling is not automatic. To do this, pass the flag `options={ \"automaticMode\" : False }` to the `Server` constructor."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2090e538-d196-4923-937c-b83fedf1d9a2",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/data.ipynb

@@ -0,0 +1,167 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "fe7a3037-5c49-4097-9a5d-575b958cc7f8",
+   "metadata": {},
+   "source": [
+    "# Data Extraction"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "fc68ad1d-e64c-48b7-9461-50d872d30473",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from pathlib import Path\n",
+    "from pantograph.server import Server"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fd13c644-d731-4f81-964e-584bbd43e51c",
+   "metadata": {},
+   "source": [
+    "## Tactic Invocation\n",
+    "\n",
+    "Pantograph can extract tactic invocation data from a Lean file. A **tactic\n",
+    "invocation** is a tuple containing the before and after goal states, and the\n",
+    "tactic which converts the \"before\" state to the \"after\" state.\n",
+    "\n",
+    "To extract tactic invocation data, use `server.tactic_invocations(file_name)`\n",
+    "and supply the file name of the input Lean file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "a0a2a661-e357-4b80-92d1-4172670ab061",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "$PWD: /home/aniva/Projects/atp/PyPantograph/examples/Example\n",
+      "==== #0 ====\n",
+      "/-- Ensure that Aesop is running -/\n",
+      "example : α → α :=\n",
+      "  by aesop\n",
+      "\n",
+      "\n",
+      "==== #1 ====\n",
+      "example : ∀ (p q: Prop), p ∨ q → q ∨ p := by\n",
+      "  intro p q h\n",
+      "  -- Here are some comments\n",
+      "  cases h\n",
+      "  . apply Or.inr\n",
+      "    assumption\n",
+      "  . apply Or.inl\n",
+      "    assumption\n",
+      "\n",
+      "==== Invocations ====\n",
+      "α : Sort ?u.7\n",
+      "⊢ α → α\n",
+      "aesop\n",
+      "\n",
+      "\n",
+      "⊢ ∀ (p q : Prop), p ∨ q → q ∨ p\n",
+      "intro p q h\n",
+      "p q : Prop\n",
+      "h : p ∨ q\n",
+      "⊢ q ∨ p\n",
+      "\n",
+      "p q : Prop\n",
+      "h : p ∨ q\n",
+      "⊢ q ∨ p\n",
+      "cases h\n",
+      "case inl\n",
+      "p q : Prop\n",
+      "h✝ : p\n",
+      "⊢ q ∨ p\n",
+      "case inr p q : Prop h✝ : q ⊢ q ∨ p\n",
+      "\n",
+      "case inl\n",
+      "p q : Prop\n",
+      "h✝ : p\n",
+      "⊢ q ∨ p\n",
+      "apply Or.inr\n",
+      "case inl.h\n",
+      "p q : Prop\n",
+      "h✝ : p\n",
+      "⊢ p\n",
+      "\n",
+      "case inl.h\n",
+      "p q : Prop\n",
+      "h✝ : p\n",
+      "⊢ p\n",
+      "assumption\n",
+      "\n",
+      "\n",
+      "case inr\n",
+      "p q : Prop\n",
+      "h✝ : q\n",
+      "⊢ q ∨ p\n",
+      "apply Or.inl\n",
+      "case inr.h\n",
+      "p q : Prop\n",
+      "h✝ : q\n",
+      "⊢ q\n",
+      "\n",
+      "case inr.h\n",
+      "p q : Prop\n",
+      "h✝ : q\n",
+      "⊢ q\n",
+      "assumption\n",
+      "\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "project_path = Path(os.getcwd()).parent.resolve() / 'examples/Example'\n",
+    "print(f\"$PWD: {project_path}\")\n",
+    "server = Server(imports=['Example'], project_path=project_path)\n",
+    "units, invocations = server.tactic_invocations(project_path / \"Example.lean\")\n",
+    "for i, u in enumerate(units):\n",
+    "    print(f\"==== #{i} ====\")\n",
+    "    print(u)\n",
+    "print(\"==== Invocations ====\")\n",
+    "for i in invocations:\n",
+    "    print(f\"{i.before}\\n{i.tactic}\\n{i.after}\\n\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "51f5398b-5416-4dc1-81cd-6d2514758232",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}