chore: import upstream snapshot with attribution

examples/notebooks/romeo_juliet_extraction.ipynb

@@ -0,0 +1,257 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "header"
+      },
+      "source": [
+        "# Romeo and Juliet Text Extraction with LangExtract\n",
+        "\n",
+        "This notebook demonstrates extracting characters, emotions, and relationships from Shakespeare's Romeo and Juliet using LangExtract.\n",
+        "\n",
+        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google/langextract/blob/main/examples/notebooks/romeo_juliet_extraction.ipynb)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "setup_header"
+      },
+      "source": [
+        "## Setup"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "install"
+      },
+      "outputs": [],
+      "source": [
+        "# Install LangExtract\n",
+        "%pip install -q langextract"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "api_key"
+      },
+      "outputs": [],
+      "source": [
+        "# Set up your Gemini API key\n",
+        "# Get your key from: https://aistudio.google.com/app/apikey\n",
+        "import os\n",
+        "from getpass import getpass\n",
+        "\n",
+        "if 'GEMINI_API_KEY' not in os.environ:\n",
+        "    os.environ['GEMINI_API_KEY'] = getpass('Enter your Gemini API key: ')"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "define_header"
+      },
+      "source": [
+        "## Define Extraction Task"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "setup_extraction"
+      },
+      "outputs": [],
+      "source": [
+        "import langextract as lx\n",
+        "import textwrap\n",
+        "\n",
+        "# Define the extraction task\n",
+        "prompt = textwrap.dedent(\"\"\"\\\n",
+        "    Extract characters, emotions, and relationships in order of appearance.\n",
+        "    Use exact text for extractions. Do not paraphrase or overlap entities.\n",
+        "    Provide meaningful attributes for each entity to add context.\"\"\")\n",
+        "\n",
+        "# Provide a high-quality example\n",
+        "examples = [\n",
+        "    lx.data.ExampleData(\n",
+        "        text=\"ROMEO. But soft! What light through yonder window breaks? It is the east, and Juliet is the sun.\",\n",
+        "        extractions=[\n",
+        "            lx.data.Extraction(\n",
+        "                extraction_class=\"character\",\n",
+        "                extraction_text=\"ROMEO\",\n",
+        "                attributes={\"emotional_state\": \"wonder\"}\n",
+        "            ),\n",
+        "            lx.data.Extraction(\n",
+        "                extraction_class=\"emotion\",\n",
+        "                extraction_text=\"But soft!\",\n",
+        "                attributes={\"feeling\": \"gentle awe\"}\n",
+        "            ),\n",
+        "            lx.data.Extraction(\n",
+        "                extraction_class=\"relationship\",\n",
+        "                extraction_text=\"Juliet is the sun\",\n",
+        "                attributes={\"type\": \"metaphor\"}\n",
+        "            ),\n",
+        "        ]\n",
+        "    )\n",
+        "]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "extract_header"
+      },
+      "source": [
+        "## Extract from Sample Text"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "simple_extraction"
+      },
+      "outputs": [],
+      "source": [
+        "# Simple extraction from a short text\n",
+        "input_text = \"Lady Juliet gazed longingly at the stars, her heart aching for Romeo\"\n",
+        "\n",
+        "result = lx.extract(\n",
+        "    text_or_documents=input_text,\n",
+        "    prompt_description=prompt,\n",
+        "    examples=examples,\n",
+        "    model_id=\"gemini-3.5-flash\",\n",
+        ")\n",
+        "\n",
+        "# Display results\n",
+        "print(f\"Extracted {len(result.extractions)} entities:\\n\")\n",
+        "for extraction in result.extractions:\n",
+        "    print(f\"• {extraction.extraction_class}: '{extraction.extraction_text}'\")\n",
+        "    if extraction.attributes:\n",
+        "        for key, value in extraction.attributes.items():\n",
+        "            print(f\"  - {key}: {value}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "viz_header"
+      },
+      "source": [
+        "## Interactive Visualization"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "visualization"
+      },
+      "outputs": [],
+      "source": [
+        "# Save results to JSONL\n",
+        "lx.io.save_annotated_documents([result], output_name=\"romeo_juliet.jsonl\", output_dir=\".\")\n",
+        "\n",
+        "# Generate interactive visualization\n",
+        "html_content = lx.visualize(\"romeo_juliet.jsonl\")\n",
+        "\n",
+        "# Display in notebook\n",
+        "print(\"Interactive visualization (hover over highlights to see attributes):\")\n",
+        "html_content"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "save_viz"
+      },
+      "outputs": [],
+      "source": [
+        "# Save visualization to file (for downloading)\n",
+        "with open(\"romeo_juliet_visualization.html\", \"w\") as f:\n",
+        "    # Handle both Jupyter (HTML object) and non-Jupyter (string) environments\n",
+        "    if hasattr(html_content, 'data'):\n",
+        "        f.write(html_content.data)\n",
+        "    else:\n",
+        "        f.write(html_content)\n",
+        "\n",
+        "print(\"✓ Visualization saved to romeo_juliet_visualization.html\")\n",
+        "print(\"You can download this file from the Files panel on the left.\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "experiment_header"
+      },
+      "source": [
+        "## Try Your Own Text\n",
+        "\n",
+        "Experiment with your own Shakespeare quotes or any literary text!"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "experiment"
+      },
+      "outputs": [],
+      "source": [
+        "# Try your own text\n",
+        "your_text = \"\"\"\n",
+        "JULIET: O Romeo, Romeo! wherefore art thou Romeo?\n",
+        "Deny thy father and refuse thy name;\n",
+        "Or, if thou wilt not, be but sworn my love,\n",
+        "And I'll no longer be a Capulet.\n",
+        "\"\"\"\n",
+        "\n",
+        "custom_result = lx.extract(\n",
+        "    text_or_documents=your_text,\n",
+        "    prompt_description=prompt,\n",
+        "    examples=examples,\n",
+        "    model_id=\"gemini-3.5-flash\",\n",
+        ")\n",
+        "\n",
+        "print(\"Extractions from your text:\\n\")\n",
+        "for e in custom_result.extractions:\n",
+        "    print(f\"• {e.extraction_class}: '{e.extraction_text}'\")\n",
+        "    if e.attributes:\n",
+        "        for key, value in e.attributes.items():\n",
+        "            print(f\"  - {key}: {value}\")"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "name": "Romeo and Juliet Text Extraction with LangExtract",
+      "provenance": []
+    },
+    "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.13.5"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}