Add jupyter notebooks for Colab

Author: KenOcheltree

docs/examples/notebooks/compositionality_with_generative_slots.ipynb

@@ -0,0 +1,309 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "IByYhgKy9WCo"
+   },
+   "source": [
+    "# Compositionality with Generative Slots\n",
+    "This Jupyter notebook runs on Colab demonstrates GEnerative Slots, a function whose implementation is provided by an LLM. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "ZIu6B1Ht927Z"
+   },
+   "source": [
+    "## Install Ollama\n",
+    "\n",
+    "Before we get started with Mellea, we download and install ollama."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "VDaTfltQY3Fl"
+   },
+   "outputs": [],
+   "source": [
+    "!curl -fsSL https://ollama.com/install.sh | sh\n",
+    "!nohup ollama serve &"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "jEl3nAk696mI"
+   },
+   "source": [
+    "## Install Mellea\n",
+    "We run `uv pip install .` to install Mellea."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "9EurAUSz_1yl"
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "!git clone https://github.com/generative-computing/mellea.git --quiet\n",
+    "os.chdir(\"mellea\")\n",
+    "!uv pip install . -qq"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "NU7bZqKA0djW"
+   },
+   "source": [
+    "## Import Mellea and Create Summarizer Library\n",
+    "Form a Summarizer library that contains a set of functions for summarizing various types of documents."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mellea import generative\n",
+    "\n",
+    "# The Summarizer Library\n",
+    "@generative\n",
+    "def summarize_meeting(transcript: str) -> str:\n",
+    "    \"\"\"Summarize the meeting transcript into a concise paragraph of main points.\"\"\"\n",
+    "\n",
+    "@generative\n",
+    "def summarize_contract(contract_text: str) -> str:\n",
+    "    \"\"\"Produce a natural language summary of contract obligations and risks.\"\"\"\n",
+    "\n",
+    "@generative\n",
+    "def summarize_short_story(story: str) -> str:\n",
+    "    \"\"\"Summarize a short story, with one paragraph on plot and one paragraph on braod themes.\"\"\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Create Decision Aide Library\n",
+    "Form a Decision Aides library that aids in decision making for particular situations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# The Decision Aides Library\n",
+    "@generative\n",
+    "def propose_business_decision(summary: str) -> str:\n",
+    "    \"\"\"Given a structured summary with clear recommendations, propose a business decision.\"\"\"\n",
+    "\n",
+    "@generative\n",
+    "def generate_risk_mitigation(summary: str) -> str:\n",
+    "    \"\"\"If the summary contains risk elements, propose mitigation strategies.\"\"\"\n",
+    "\n",
+    "@generative\n",
+    "def generate_novel_recommendations(summary: str) -> str:\n",
+    "    \"\"\"Provide a list of novel recommendations that are similar in plot or theme to the short story summary.\"\"\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "## Specify Contract Functions\n",
+    "To help us compose these libraries, we introduce a set of contracts that gate function composition and then use those contracts to short-circuit non-sensical compositions of library components:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "P1-mChhly4Ow"
+   },
+   "outputs": [],
+   "source": [
+    "# Compose the libraries.\n",
+    "from typing import Literal  # noqa: E402\n",
+    "\n",
+    "@generative\n",
+    "def has_structured_conclusion(summary: str) -> Literal[\"yes\", \"no\"]:\n",
+    "    \"\"\"Determine whether the summary contains a clearly marked conclusion or recommendation.\"\"\"\n",
+    "\n",
+    "@generative\n",
+    "def contains_actionable_risks(summary: str) -> Literal[\"yes\", \"no\"]:\n",
+    "    \"\"\"Check whether the summary contains references to business risks or exposure.\"\"\"\n",
+    "\n",
+    "@generative\n",
+    "def has_theme_and_plot(summary: str) -> Literal[\"yes\", \"no\"]:\n",
+    "    \"\"\"Check whether the summary contains both a plot and thematic elements.\"\"\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Start a Mellea Session\n",
+    "We initialize a backend running Ollama using the granite3.3-chat model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "-0GPZ3_ty4Ow"
+   },
+   "outputs": [],
+   "source": [
+    "from mellea import start_session  # noqa: E402\n",
+    "\n",
+    "m = start_session()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Provide a meeting transcript with sample data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "AQGDkbeby4Ox"
+   },
+   "outputs": [],
+   "source": [
+    "transcript = \"\"\"Meeting Transcript: Market Risk Review -- Self-Sealing Stembolts Division\n",
+    "Date: December 1, 3125\n",
+    "Attendees:\n",
+    "\n",
+    "Karen Rojas, VP of Product Strategy\n",
+    "\n",
+    "Derek Madsen, Director of Global Procurement\n",
+    "\n",
+    "Felicia Zheng, Head of Market Research\n",
+    "\n",
+    "Tom Vega, CFO\n",
+    "\n",
+    "Luis Tran, Engineering Liaison\n",
+    "\n",
+    "Karen Rojas:\n",
+    "Thanks, everyone, for making time on short notice. As you've all seen, we've got three converging market risks we need to address: tariffs on micro-carburetors, increased adoption of the self-interlocking leafscrew, and, believe it or not, the \"hipsterfication\" of the construction industry. I need all on deck and let's not waste time. Derek, start.\n",
+    "\n",
+    "Derek Madsen:\n",
+    "Right. As of Monday, the 25% tariff on micro-carburetors sourced from the Pan-Alpha Centauri confederacy is active. We tried to pre-purchase a three-month buffer, but after that, our unit cost rises by $1.72. That's a 9% increase in the BOM cost of our core model 440 stembolt. Unless we find alternative suppliers or pass on the cost, we're eating into our already narrow margin.\n",
+    "\n",
+    "Tom Vega:\n",
+    "We cannot absorb that without consequences. If we pass the cost downstream, we risk losing key mid-tier OEM clients. And with the market already sniffing around leafscrew alternatives, this makes us more vulnerable.\n",
+    "\n",
+    "Karen:\n",
+    "Lets pause there. Felicia, give us the quick-and-dirty on the leafscrew.\n",
+    "\n",
+    "Felicia Zheng:\n",
+    "It's ugly. Sales of the self-interlocking leafscrew—particularly in modular and prefab construction—are up 38% year-over-year. It's not quite a full substitute for our self-sealing stembolts, but they are close enough in function that some contractors are making the switch. Their appeal? No micro-carburetors, lower unit complexity, and easier training for install crews. We estimate we've lost about 12% of our industrial segment to the switch in the last two quarters.\n",
+    "\n",
+    "Karen:\n",
+    "Engineering, Luis; your take on how real that risk is?\n",
+    "\n",
+    "Luis Tran:\n",
+    "Technically, leafscrews are not as robust under high-vibration loads. But here's the thing: most of the modular prefab sites don not need that level of tolerance. If the design spec calls for durability over 10 years, we win. But for projects looking to move fast and hit 5-year lifespans? The leafscrew wins on simplicity and cost.\n",
+    "\n",
+    "Tom:\n",
+    "So they're eating into our low-end. That's our volume base.\n",
+    "\n",
+    "Karen:\n",
+    "Exactly. Now let's talk about this last one: the “hipsterfication” of construction. Felicia?\n",
+    "\n",
+    "Felicia:\n",
+    "So this is wild. We're seeing a cultural shift in boutique and residential construction—especially in markets like Beckley, West Sullivan, parts of Osborne County, where clients are requesting \"authentic\" manual fasteners. They want hand-sealed bolts, visible threads, even mismatched patinas. It's an aesthetic thing. Function is almost secondary. Our old manual-seal line from the 3180s? People are hunting them down on auction sites.\n",
+    "\n",
+    "Tom:\n",
+    "Well, I'm glad I don't have to live in the big cities... nothing like this would ever happen in downt-to-earth places Brooklyn, Portland, or Austin.\n",
+    "\n",
+    "Luis:\n",
+    "We literally got a request from a design-build firm in Keough asking if we had any bolts “pre-distressed.”\n",
+    "\n",
+    "Karen:\n",
+    "Can we spin this?\n",
+    "\n",
+    "Tom:\n",
+    "If we keep our vintage tooling and market it right, maybe. But that's niche. It won't offset losses in industrial and prefab.\n",
+    "\n",
+    "Karen:\n",
+    "Not yet. But we may need to reframe it as a prestige line—low volume, high margin. Okay, action items. Derek, map alternative micro-carburetor sources. Felicia, get me a forecast on leafscrew erosion by sector. Luis, feasibility of reviving manual seal production. Tom, let's scenario-plan cost pass-through vs. feature-based differentiation.\n",
+    "\n",
+    "Let's reconvene next week with hard numbers. Thanks, all.\"\"\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Summarize the Meeting\n",
+    "Use the contracts to short-circuit non-sensical compositions of library components."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "mV-zS1wDy4Oz"
+   },
+   "outputs": [],
+   "source": [
+    "summary = summarize_meeting(m, transcript=transcript)\n",
+    "\n",
+    "if contains_actionable_risks(m, summary=summary) == \"yes\":\n",
+    "    mitigation = generate_risk_mitigation(m, summary=summary)\n",
+    "    print(f\"Mitigation: {mitigation}\")\n",
+    "else:\n",
+    "    print(\"Summary does not contain actionable risks.\")\n",
+    "if has_structured_conclusion(m, summary=summary) == \"yes\":\n",
+    "    decision = propose_business_decision(m, summary=summary)\n",
+    "    print(f\"Decision: {decision}\")\n",
+    "else:\n",
+    "    print(\"Summary lacks a structured conclusion.\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "gpuType": "T4",
+   "provenance": []
+  },
+  "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.13.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}