Spaces:

kgdrathan
/

explainer-env

Sleeping

App Files Files Community

kgdrathan commited on Apr 26

Commit

43f41de

verified ·

1 Parent(s): eb1ebe6

Upload folder using huggingface_hub

Browse files

Files changed (27) hide show

README.md +99 -36
client.py +8 -2
constants.py +24 -0
models.py +42 -16
notes.html +305 -0
openenv_explainer_env.egg-info/PKG-INFO +11 -1
openenv_explainer_env.egg-info/SOURCES.txt +4 -0
openenv_explainer_env.egg-info/requires.txt +11 -1
pyproject.toml +13 -3
research/__init__.py +11 -0
research/retrieval.py +179 -0
research/router.py +381 -0
research/types.py +62 -0
rewards/README.md +75 -70
rewards/__init__.py +1 -6
rewards/exploration.py +170 -67
rewards/generation.py +145 -77
rewards/sandbox.py +161 -3
rewards/sources.py +26 -313
server/app.py +1 -1
server/explainer_env_environment.py +235 -52
tests/test_client_server.py +16 -3
tests/test_docker.py +7 -0
tests/test_environment.py +54 -12
tests/test_models.py +22 -2
tests/test_rewards.py +64 -3
uv.lock +0 -0

README.md CHANGED Viewed

@@ -11,26 +11,65 @@ tags:
   - openenv
 ---
-# Research → Interactive Explainer Environment
-An OpenEnv RL environment that trains small language models to create interactive educational content. Given a research topic, the agent:
-1. **Explores** — searches HuggingFace Papers (ML topics) or Wikipedia (general topics) for relevant content
-2. **Generates** — produces a **Marimo** reactive notebook or **Manim** math animation explaining the topic
-The agent learns *what* to search, *when to stop exploring*, and how to produce high-quality interactive explanations.
-## Episode Flow
 ```
-reset() → topic + tier assigned
-  ↓
-explore × 0..3 → search queries, accumulate research context
-  ↓
-generate × 1 → produce marimo/manim code → episode ends
 ```
-Each step returns a per-step reward. See [rewards/README.md](rewards/README.md) for the full reward breakdown.
 ## Quick Start
@@ -49,7 +88,12 @@ with ExplainerEnv(base_url='http://localhost:8000').sync() as sc:
     print(f'Topic: {result.observation.topic}, Tier: {result.observation.tier}')
     # Explore
-    result = sc.step(ExplainerAction(action_type='explore', query=result.observation.topic))
     print(f'Explore reward: {result.reward:.3f}')
     # Generate
@@ -62,30 +106,9 @@ with ExplainerEnv(base_url='http://localhost:8000').sync() as sc:
 "
 ```
-## LLM-as-Judge (Optional Eval)
-For final evaluation of explanation quality, an optional LLM judge scores outputs on clarity, accuracy, engagement, completeness, and appropriateness.
-**Not used during training** — too slow and non-deterministic for RL rewards. Training uses 12 fast heuristic reward components instead.
-```bash
-# Configure (any OpenAI-compatible endpoint)
-export JUDGE_API_URL="http://localhost:11434/v1"  # e.g. ollama
-export JUDGE_MODEL="llama3"
-# Usage
-python -c "
-from rewards.llm_judge import judge_explainability, is_available
-if is_available():
-    score, details = judge_explainability(code='...', topic='Linear Regression', tier='beginner')
-    print(f'Score: {score:.2f}, Rationale: {details.get(\"rationale\", \"\")}')"
-```
-See [rewards/README.md](rewards/README.md) for full configuration details.
 ## Concurrent WebSocket Sessions
-The server supports multiple concurrent WebSocket connections for parallel training rollouts:
 ```python
 from client import ExplainerEnv
@@ -95,7 +118,11 @@ from concurrent.futures import ThreadPoolExecutor
 def run_episode(client_id: int):
     with ExplainerEnv(base_url="http://localhost:8000").sync() as sc:
         result = sc.reset()
-        result = sc.step(ExplainerAction(action_type="explore", query=result.observation.topic))
         result = sc.step(ExplainerAction(
             action_type="generate", format="marimo",
             code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    return\n",
@@ -105,3 +132,39 @@ def run_episode(client_id: int):
 with ThreadPoolExecutor(max_workers=4) as executor:
     results = list(executor.map(run_episode, range(4)))
 ```

   - openenv
 ---
+# Research -> Interactive Explainer Environment
+An OpenEnv RL environment that trains small language models to create interactive educational content. Given a STEM topic, the agent explores with explicit research tools, generates a **Marimo** reactive notebook or **Manim** math animation, and gets one repair attempt if lint/build validation fails.
+## Episode Flow
+```
+reset() --> topic + tier assigned
+  |
+explore x 0..3 --> choose research tools + queries
+  |
+generate x 1 --> produce marimo/manim code
+  |
+repair x 0..1 --> fix lint/build errors if needed --> episode ends
+```
+## Actions
+**Explore** -- search for information relevant to the assigned topic:
+```python
+ExplainerAction(
+    action_type="explore",
+    tool="search_arxiv",
+    query="merge sort divide and conquer visual explanation",
+    intent="find examples and visual intuition",
+)
+```
+Available tools: `search_wikipedia`, `search_hf_papers`, `search_arxiv`, `search_scholar`, `fetch_docs`, and `search_hf_hub`.
+**Generate** -- produce educational code using accumulated research:
+```python
+ExplainerAction(
+    action_type="generate",
+    format="marimo",      # or "manim"
+    code="import marimo...",
+    narration="...",       # manim only
+)
 ```
+**Repair** -- revise generated code using lint/build feedback:
+```python
+ExplainerAction(
+    action_type="repair",
+    format="marimo",
+    code="import marimo...",
+    repair_notes="fixed the reported Marimo validation error",
+)
 ```
+## Reward System
+Multi-component rewards across exploration, generation, and repair. See [rewards/README.md](rewards/README.md) for the full breakdown.
+**Exploration** (per-step): tool choice, query quality, source quality, coverage delta, novelty, diversity, gated by information sufficiency. Step cost of -0.05 forces the agent to justify each search.
+**Generation/repair**: keyword coverage, format match, structural quality (via `marimo check` CLI or manim scene analysis), narration (manim only), context usage, and repair success.
+Key design: `marimo check` CLI catches 5 breaking rules (MB001-MB005) in ~100ms. Code that doesn't parse scores 0. Code that doesn't execute gets quality * 0.4.
 ## Quick Start
     print(f'Topic: {result.observation.topic}, Tier: {result.observation.tier}')
     # Explore
+    result = sc.step(ExplainerAction(
+        action_type='explore',
+        tool='search_wikipedia',
+        query=result.observation.topic,
+        intent='overview',
+    ))
     print(f'Explore reward: {result.reward:.3f}')
     # Generate
 "
 ```
 ## Concurrent WebSocket Sessions
+The server supports multiple concurrent WebSocket connections for parallel GRPO training rollouts:
 ```python
 from client import ExplainerEnv
 def run_episode(client_id: int):
     with ExplainerEnv(base_url="http://localhost:8000").sync() as sc:
         result = sc.reset()
+        result = sc.step(ExplainerAction(
+            action_type="explore",
+            tool="search_wikipedia",
+            query=result.observation.topic,
+        ))
         result = sc.step(ExplainerAction(
             action_type="generate", format="marimo",
             code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    return\n",
 with ThreadPoolExecutor(max_workers=4) as executor:
     results = list(executor.map(run_episode, range(4)))
 ```
+## API Endpoints
+| Endpoint | Method | Description |
+|---|---|---|
+| `/reset` | POST | Start new episode, get topic assignment |
+| `/step` | POST | Submit action, get observation + reward |
+| `/state` | GET | Current episode state |
+| `/schema` | GET | Action/Observation JSON schemas |
+| `/ws` | WebSocket | Low-latency session for training |
+| `/docs` | GET | Interactive API docs |
+## Task Bank
+26 tasks across 4 categories (ML, Math, Algorithms, Statistics), 3 difficulty levels (easy, medium, hard), and 3 audience tiers (beginner, intermediate, advanced). Each task specifies keywords for reward scoring and an optional preferred output format.
+## File Structure
+```
+explainer_env/
+├── server/
+│   ├── explainer_env_environment.py  # Environment logic (reset/step/state)
+│   ├── app.py                        # FastAPI server (create_app)
+│   └── Dockerfile                    # Multi-stage Docker build
+├── rewards/
+│   ├── exploration.py                # Explore-phase reward components
+│   ├── generation.py                 # Generate/repair reward components
+│   ├── sources.py                    # Compatibility wrapper for research tools
+│   ├── sandbox.py                    # Code validation (marimo check, AST, execution)
+│   └── README.md                     # Reward system documentation
+├── research/                          # Research tools, structured results, retrieval
+├── models.py                         # ExplainerAction, ExplainerObservation
+├── task_bank.py                      # 26 curated STEM tasks
+├── client.py                         # ExplainerEnv WebSocket client
+└── openenv.yaml                      # OpenEnv manifest
+```

client.py CHANGED Viewed

@@ -6,7 +6,10 @@ from openenv.core import EnvClient
 from openenv.core.client_types import StepResult
 from openenv.core.env_server.types import State
-from .models import ExplainerAction, ExplainerObservation
 class ExplainerEnv(
@@ -20,7 +23,10 @@ class ExplainerEnv(
         ...     result = sc.reset()
         ...     # Explore phase
         ...     result = sc.step(ExplainerAction(
-        ...         action_type="explore", query="attention mechanism transformers"
         ...     ))
         ...     # Generate phase
         ...     result = sc.step(ExplainerAction(

 from openenv.core.client_types import StepResult
 from openenv.core.env_server.types import State
+try:
+    from .models import ExplainerAction, ExplainerObservation
+except ImportError:  # pragma: no cover - supports direct test execution
+    from models import ExplainerAction, ExplainerObservation
 class ExplainerEnv(
         ...     result = sc.reset()
         ...     # Explore phase
         ...     result = sc.step(ExplainerAction(
+        ...         action_type="explore",
+        ...         tool="search_arxiv",
+        ...         query="attention mechanism transformers",
+        ...         intent="visual intuition and equations",
         ...     ))
         ...     # Generate phase
         ...     result = sc.step(ExplainerAction(

constants.py ADDED Viewed

	@@ -0,0 +1,24 @@

+"""Shared limits and scoring helpers for explainer episodes."""
+MAX_EXPLORE_STEPS = 3
+MAX_REPAIR_STEPS = 1
+AVAILABLE_TOOLS = (
+    "search_wikipedia",
+    "search_hf_papers",
+    "search_arxiv",
+    "search_scholar",
+    "fetch_docs",
+    "search_hf_hub",
+)
+MAX_EXPLORE_REWARD = 0.8
+MAX_GENERATE_REWARD = 1.0
+SUCCESS_SCORE_THRESHOLD = 0.3
+def normalized_episode_score(total_reward: float) -> float:
+    """Normalize an episode's accumulated reward to the required [0, 1] range."""
+    max_possible = MAX_EXPLORE_STEPS * MAX_EXPLORE_REWARD + MAX_GENERATE_REWARD
+    score = total_reward / max_possible if max_possible > 0 else 0.0
+    return min(max(score, 0.0), 1.0)

models.py CHANGED Viewed

@@ -1,10 +1,4 @@
-"""
-Data models for the Research → Interactive Explainer environment.
-Two-phase episode:
-  1. Explore: agent searches for papers/resources (1-3 steps)
-  2. Generate: agent produces marimo/manim code (1 step, ends episode)
-"""
 from typing import Literal
@@ -12,31 +6,54 @@ from openenv.core.env_server.types import Action, Observation
 from pydantic import Field
 class ExplainerAction(Action):
-    """Action: agent either explores (searches) or generates (produces code)."""
-    action_type: Literal["explore", "generate"] = Field(
-        ..., description="'explore' to search for papers, 'generate' to produce code"
     )
     # -- explore fields --
     query: str = Field(
         default="",
-        description="Search query for arXiv/HF papers (used when action_type='explore')",
     )
-    # -- generate fields --
     format: Literal["marimo", "manim"] | None = Field(
         default=None,
-        description="Output format (required when action_type='generate')",
     )
     code: str = Field(
         default="",
-        description="Complete Python source code (required when action_type='generate')",
     )
     narration: str = Field(
         default="",
-        description="Narration script (required when format='manim')",
     )
@@ -55,7 +72,7 @@ class ExplainerObservation(Observation):
     )
     # -- per-step feedback --
-    phase: Literal["explore", "generate", "done"] = Field(
         default="explore", description="Current episode phase"
     )
     feedback: str = Field(default="", description="Feedback on the last action")
@@ -69,3 +86,12 @@ class ExplainerObservation(Observation):
     explore_steps_left: int = Field(
         default=3, description="Remaining explore steps before forced generate"
     )

+"""Data models for the Research -> Interactive Explainer environment."""
 from typing import Literal
 from pydantic import Field
+ResearchTool = Literal[
+    "search_wikipedia",
+    "search_hf_papers",
+    "search_arxiv",
+    "search_scholar",
+    "fetch_docs",
+    "search_hf_hub",
+]
 class ExplainerAction(Action):
+    """Action: agent explores, generates, or repairs an artifact."""
+    action_type: Literal["explore", "generate", "repair"] = Field(
+        ...,
+        description="'explore' to research, 'generate' to produce code, 'repair' to fix code",
     )
     # -- explore fields --
+    tool: ResearchTool | None = Field(
+        default=None,
+        description="Research tool to call when action_type='explore'",
+    )
     query: str = Field(
         default="",
+        description="Research query used when action_type='explore'",
+    )
+    intent: str = Field(
+        default="",
+        description="Brief goal for the research call, e.g. equations or visual intuition",
     )
+    # -- generate / repair fields --
     format: Literal["marimo", "manim"] | None = Field(
         default=None,
+        description="Output format (required for generate/repair)",
     )
     code: str = Field(
         default="",
+        description="Complete Python source code (required for generate/repair)",
     )
     narration: str = Field(
         default="",
+        description="Narration script (used when format='manim')",
+    )
+    repair_notes: str = Field(
+        default="",
+        description="Short explanation of what changed when action_type='repair'",
     )
     )
     # -- per-step feedback --
+    phase: Literal["explore", "generate", "repair", "done"] = Field(
         default="explore", description="Current episode phase"
     )
     feedback: str = Field(default="", description="Feedback on the last action")
     explore_steps_left: int = Field(
         default=3, description="Remaining explore steps before forced generate"
     )
+    repair_attempts_left: int = Field(
+        default=1, description="Remaining repair attempts after failed generation"
+    )
+    last_errors: str = Field(
+        default="", description="Latest lint/build errors available for repair"
+    )
+    available_tools: list[str] = Field(
+        default_factory=list, description="Research tools available during explore"
+    )

notes.html ADDED Viewed

	@@ -0,0 +1,305 @@

+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/favicon.ico" />
+    <!-- Preload is necessary because we show these images when we disconnect from the server,
+    but at that point we cannot load these images from the server -->
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/gradient-yHQUC_QB.png" as="image" />
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/noise-60BoTA8O.png" as="image" />
+    <!-- Preload the fonts -->
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/Lora-VariableFont_wght-CZceb_kH.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/PTSans-Regular-Bam3NpBI.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/PTSans-Bold-C_DwAp7Z.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/FiraMono-Regular-CEsLFVD9.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/FiraMono-Medium-D5MAsWEG.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
+    <link rel="preload" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/FiraMono-Bold-C6PDArdf.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <meta name="description" content="a marimo app" />
+    <link rel="apple-touch-icon" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/apple-touch-icon.png" />
+    <link rel="manifest" crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/manifest.json" />
+    <script data-marimo="true">
+      function __resizeIframe(obj) {
+        const scrollbarHeight = 20; // Max between windows, mac, and linux
+        function setHeight() {
+          // Guard against race condition where iframe isn't ready
+          if (!obj.contentWindow?.document?.documentElement) {
+            return;
+          }
+          const element = obj.contentWindow.document.documentElement;
+          // If there is no vertical scrollbar, we don't need to resize the iframe
+          if (element.scrollHeight === element.clientHeight) {
+            return;
+          }
+          // Create a new height that includes the scrollbar height if it's visible
+          const hasHorizontalScrollbar = element.scrollWidth > element.clientWidth;
+          const newHeight = element.scrollHeight + (hasHorizontalScrollbar ? scrollbarHeight : 0);
+          // Only update the height if it's different from the current height
+          if (obj.style.height !== `${newHeight}px`) {
+            obj.style.height = `${newHeight}px`;
+          }
+        }
+        // Resize the iframe to the height of the content and bottom scrollbar height
+        setHeight();
+        // Resize the iframe when the content changes
+        const resizeObserver = new ResizeObserver((_entries) => {
+          setHeight();
+        });
+        // Only observe if iframe content is ready
+        if (obj.contentWindow?.document?.body) {
+          resizeObserver.observe(obj.contentWindow.document.body);
+        }
+      }
+    </script>
+    <marimo-filename hidden>notes.py</marimo-filename>
+    <!-- TODO(Trevor): Legacy, required by VS Code plugin. Remove when plugin is updated (see marimo/server/_templates/template.py) -->
+    <marimo-version data-version="{{ version }}" hidden></marimo-version>
+    <marimo-user-config data-config="{{ user_config }}" hidden></marimo-user-config>
+    <marimo-server-token data-token="{{ server_token }}" hidden></marimo-server-token>
+    <!-- /TODO -->
+    <title>notes</title>
+    <script type="module" crossorigin crossorigin="anonymous" src="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/index-BjiE1T38.js"></script>
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/preload-helper-D2MJg03u.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/chunk-LvLJmgfZ.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/react-Bj1aDYRI.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/compiler-runtime-B3qBwwSJ.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/jsx-runtime-BqBOg78p.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useEventListener-BR0C1MaI.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/defaultLocale-JieDVWC_.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/precisionRound-CU2C3Vxx.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/defaultLocale-BLne0bXb.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/vega-loader.browser-DXARUlxo.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/utils-Bq5kLQ87.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/clsx-Dz_KRrWq.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/cn-DCUzRj2J.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/badge-ChrPsdTW.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/button-D9nb17Rw.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/react-dom-CSu739Rf.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/fullscreen-BDxedMYP.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/menu-items-CwUpDHG7.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-BoOh2kN5.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/createLucideIcon-D5guW7EU.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/check-BH35Ndha.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/x-C-6liIBr.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/select-5i7URBEn.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/tooltip-Gcwqb_SK.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/use-toast-BDYuj3zG.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useEvent-D91BmmQi.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/invariant-BUdrueMv.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/isObject-DvLSfCY5.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/_baseFor-DKD1r8uL.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/merge-_9WLTEyt.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/zod-H_cgTO0M.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/utils-DIGrmLDO.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/Deferred-DxQeE5uh.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/uuid-DXdzqzcr.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/DeferredRequestRegistry-DjHgMr3S.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/constants-DMpttj8Q.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/session-nmTRerwF.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/config-ChCHm539.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/requests-DIwGYs0l.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useLifecycle-DieWOfXE.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useNonce-DfoVjkkH.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useTheme-DEcgJENn.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/arrays-DYDL-3-i.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/strings-md4mFbOQ.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/once-DRroIaBz.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/capabilities-C_FLIcjP.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/createReducer-1ePoj7v6.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/paths-CXng2XQv.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-BrR4M-k3.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-HlsDto3K.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-CHcznzB-.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-DGxytjtv.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-DZ2qbK2N.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-CEysMnMQ.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-Ds4ite_2.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-CRPTyqAT.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dist-C9ZB41s2.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/stex-jWatZkll.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/toDate-B5A0DFEz.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/purify.es-DC4RGS9t.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/cjs-BRGiG41H.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/isSymbol-BT6B8Bon.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/now-CsYTPAhW.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/debounce-DhnxH9Rh.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/database-zap-BUVn5HoR.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/main-B0OX4z33.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/cells-CJlo_hG2.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/ErrorBoundary-DzYV_VeY.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/kbd-CGShmG7L.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useInstallPackage-afgh7PwB.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/alert-dialog-BGBdrcqJ.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dialog-EekxpBBM.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useDebounce-BDIglWmG.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/numbers-OHL_xBiC.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/SSRProvider-D3zWcDme.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/context-DGqo1TbK.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useNumberFormatter-wQU1z0W_.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/usePress-CtfZXGno.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/input-DyPS_GiK.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/ImperativeModal-BBqcKmmk.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/cell-link-BA7Demf0.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/multi-map-rafH3cg3.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/alert-cDholnQq.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/chevron-right-CG5QYXYk.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dropdown-menu-D1A3cFC8.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/links-C-rLiK3d.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useRunCells-B531RIUE.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/copy-B5qyZn5s.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/copy-Dk_3y0H-.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/copy-icon-C67c9EwB.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/RenderHTML-BT9obKLc.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/datasource-BKDU-4D5.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/state-C5AUgyZT.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/sparkles-CZ5WmLPA.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/MarimoErrorOutput-BBD405a6.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/spinner-Bhir8k53.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/html-to-image-Cz8lDF-Y.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/focus-BX3gXJxx.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useAsyncData-dS4Ne6pU.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/LazyAnyLanguageCodeMirror-0gZO1asr.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/micromark-factory-space-WzovnJik.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/chunk-5FQGJX7Z-B4RvNAGm.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/markdown-renderer-CeHY2KoQ.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/command-DbT_zkRP.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/popover-UExmgBsf.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/errors-CZb6hI2x.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/download-mzsKQgiy.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/table-23NNA1s9.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useIframeCapabilities-CryCjoyY.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/error-banner-CTBwdcdk.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/formats-BvyJSIqk.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/en-US-BqRooSzc.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/isValid-bmSEa3HX.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/dates-DhByPWH5.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/maps-C48Oksn0.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/extends-Co37_JfG.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/emotion-is-prop-valid.esm-DYxi7n2b.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useDateFormatter-BEz9SEXo.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/react-icons.esm-BUYTQ32a.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/table-6NxtGaCm.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/ellipsis-pk06Lq82.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/message-circle-CWm2KnSx.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/react-resizable-panels.browser.esm-Bcm5njwd.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/JsonOutput-DXnOS_Hk.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/chart-no-axes-column-nqk474t8.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/square-function-D1dlJvD8.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/spec-Cq8FVoTf.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/ellipsis-vertical-gxgNyR5G.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/refresh-cw-DHwG4Mac.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/tree-actions-oMCx6WNc.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/components-BiBOcq1x.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/column-preview-DzN2QumC.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/icons-BRopQwI3.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/floating-outline-BMB4_phA.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useAddCell-CqBbGhrY.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/objectWithoutPropertiesLoose-smPWkHxB.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/esm-G1JMtvxe.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/eye-off-BT-KOYV5.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/plus-BgB18UzY.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/readonly-python-code-Ccd8HM-7.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/file-headphone-B3fuktN0.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/file-HTLbeC2b.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/image-DQHXdEQn.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/file-icons-BNrh8MRG.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/switch-DlgpDZMk.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/events-Qeh-bHlj.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/globals-xVhZei_S.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/share-BXN2Sd1t.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/blob-CTort_or.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/memoize-Tp7rARFe.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/get-C-qh_et5.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/_baseSet-CxV9N1bc.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/state-DHlRrwyY.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/label-DTR8T0AE.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/textarea-BXPC1-kb.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/radio-group-BtBoRbGH.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/refresh-ccw-C-n2VFP5.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/trash-2-D280Xiwg.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/form-CPDlIjdV.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/renderShortcut-CkNNAheg.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/field-B8kJgr2A.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/RSPContexts-BeHIgT4C.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useBoolean-CLFdHewv.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/useDeepCompareMemoize-D0WTlCXt.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/types-W8WWuumF.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/fileToBase64-Bzn96tYq.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/pathUtils-CSrNy17a.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/prop-types-BFRDxSKF.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/es-YQvzKo5h.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/hasIn-DiS_ryrS.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/flatten-Dl4V1ub3.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/pick-DqWUNly1.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/code-xml-CZN6vNxu.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/square-Dj2Cf4ne.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/triangle-alert-DBoAWWKA.js">
+    <link rel="modulepreload" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/bundle.esm-DU-4isVC.js">
+    <link rel="stylesheet" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/cells-jmgGt1lS.css">
+    <link rel="stylesheet" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/markdown-renderer-DdDKmWlR.css">
+    <link rel="stylesheet" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/JsonOutput-B7vuddcd.css">
+    <link rel="stylesheet" crossorigin crossorigin="anonymous" href="https://cdn.jsdelivr.net/npm/@marimo-team/frontend@0.23.3/dist/assets/index-BYLYJcAY.css">
+<script data-marimo="true">
+    Object.defineProperty(window, "__MARIMO_STATIC__", {
+        value: Object.freeze({
+            files: Object.freeze({}),
+            modelNotifications: Object.freeze([]),
+        }),
+        writable: false,
+        configurable: false,
+    });
+</script>
+<script data-marimo="true">
+    Object.defineProperty(window, "__MARIMO_EXPORT_CONTEXT__", {
+        value: Object.freeze({
+            trusted: true,
+            notebookCode: "import marimo\n\n__generated_with = \"0.23.3\"\napp = marimo.App()\n\n\n@app.cell\ndef _():\n    import marimo as mo\n    import numpy as np\n\n    # Remove and warn if matplotlib is missing.\n    try:\n        import matplotlib.pyplot as plt\n    except ModuleNotFoundError:\n        plt = None\n        mo.notification(\"Matplotlib is not installed. Plots will be skipped or limited.\", kind=\"warning\")\n\n    from sklearn.datasets import make_regression\n    from sklearn.linear_model import LinearRegression\n\n    return LinearRegression, make_regression, mo, np, plt\n\n\n@app.cell\ndef _(mo):\n    mo.md(\"# Linear Regression: A Beginner's Guide\")\n    mo.md(\n        \"Linear regression is a fundamental technique in machine learning used to model the relationship between a dependent variable and one or more independent variables.\"\n    )\n    mo.md(\n        \"In this notebook, we'll explore what linear regression is, how it works mathematically, how to fit a model using scikit-learn, and how to implement it from scratch using gradient descent.\"\n    )\n    return\n\n\n@app.cell\ndef _(LinearRegression, make_regression, mo, np, plt):\n    mo.md(\"## What is Linear Regression?\")\n    mo.md(\n        \"Linear regression aims to find the 'best fit' line through data points. This line is defined by weights (coefficients) and a bias term.\"\n    )\n\n    # Create sample data\n    X, y = make_regression(n_samples=100, n_features=1, noise=10, random_state=42)\n\n    # Fit sklearn linear regression\n    lin_reg = LinearRegression()\n    lin_reg.fit(X, y)\n\n    # Calculate predictions\n    y_pred = lin_reg.predict(X)\n\n    if plt is not None:\n        # Sort the data for a prettier line plot\n        sorted_idx = np.argsort(X[:, 0])\n        X_sorted = X[sorted_idx]\n        y_pred_sorted = y_pred[sorted_idx]\n        y_sorted = y[sorted_idx]\n\n        # Plot\n        fig, ax = plt.subplots(figsize=(10, 6))\n        ax.scatter(X, y, alpha=0.6, label=\"Data points\")\n        ax.plot(X_sorted, y_pred_sorted, color=\"red\", linewidth=2, label=\"Fitted line\")\n        ax.set_xlabel(\"X\")\n        ax.set_ylabel(\"y\")\n        ax.legend()\n        ax.grid(True, alpha=0.3)\n        ax.set_title(\"Linear Regression Example\")\n\n        mo.display(fig)\n    else:\n        mo.notification(\"Skipping plot: matplotlib is not available.\", kind=\"error\")\n    return X, lin_reg, y, y_pred\n\n\n@app.cell\ndef _(lin_reg, mo):\n    mo.md(\"## Mathematical Foundation\")\n    mo.md(\"The linear regression model can be expressed as:\")\n    mo.md(\"$$y = Xw + b$$\")\n    mo.md(\"Where:\")\n    mo.md(\"- $y$ is the target variable\")\n    mo.md(\"- $X$ is the matrix of input features\")\n    mo.md(\"- $w$ is the vector of weights\")\n    mo.md(\"- $b$ is the bias term\")\n\n    mo.md(\"In our example:\")\n    mo.md(f\"- Weights (w): {lin_reg.coef_[0]:.2f}\")\n    mo.md(f\"- Bias (b): {lin_reg.intercept_:.2f}\")\n    return\n\n\n@app.cell\ndef _(mo, np, y, y_pred):\n    mo.md(\"## Loss Function: Mean Squared Error (MSE)\")\n    mo.md(\n        \"The goal of linear regression is to minimize the error between predicted and actual values. The most common loss function is Mean Squared Error:\"\n    )\n    mo.md(\"$$\\\\text{MSE} = \\\\frac{1}{n} \\\\sum_{i=1}^{n} (y_i - \\\\hat{y}_i)^2$$\")\n    mo.md(\"Where:\")\n    mo.md(\"- $y_i$ is the actual value\")\n    mo.md(\"- $\\\\hat{y}_i$ is the predicted value\")\n    mo.md(\"- $n$ is the number of samples\")\n\n    # Calculate MSE\n    mse = np.mean((y - y_pred) ** 2)\n    mo.md(f\"In our example, the MSE is approximately: {mse:.2f}\")\n    return\n\n\n@app.cell\ndef _(X, mo, np, y):\n    mo.md(\"## How Does It Work? Gradient Descent\")\n    mo.md(\n        \"To minimize the MSE, we can use an optimization algorithm called gradient descent. This algorithm iteratively adjusts the weights and bias to reduce the loss function.\"\n    )\n\n    # Simple implementation of gradient descent\n    def gradient_descent(X, y, learning_rate=0.01, iterations=1000):\n        m = len(X)\n        w = np.random.randn(1)\n        b = 0.0\n\n        # Reshape X\n        x_vec = X.ravel()\n        for i in range(iterations):\n            y_pred = x_vec * w + b\n\n            # Compute gradients\n            dw = (-2 / m) * np.sum(x_vec * (y - y_pred))\n            db = (-2 / m) * np.sum(y - y_pred)\n\n            w -= learning_rate * dw\n            b -= learning_rate * db\n\n        return w, b\n\n    w_gd, b_gd = gradient_descent(X, y)\n    y_pred_gd = X.ravel() * w_gd + b_gd\n\n    mse_gd = np.mean((y - y_pred_gd) ** 2)\n\n    mo.md(\"Using gradient descent (learning rate=0.01, 1000 iterations):\")\n    mo.md(f\"- Weights (w): {w_gd[0]:.2f}\")\n    mo.md(f\"- Bias (b): {b_gd:.2f}\")\n    mo.md(f\"- MSE: {mse_gd:.2f}\")\n    return (y_pred_gd,)\n\n\n@app.cell\ndef _(X, mo, np, plt, y, y_pred, y_pred_gd):\n    mo.md(\"## Visualizing the Process\")\n    if plt is not None:\n        fig, ax = plt.subplots(figsize=(10, 6))\n        ax.scatter(X, y, alpha=0.6, label=\"Data points\")\n\n        # For clean lines, sort the X for both predictions\n        sorted_idx = np.argsort(X[:, 0])\n        X_sorted = X[sorted_idx]\n        y_pred_sorted = y_pred[sorted_idx]\n        y_pred_gd_sorted = y_pred_gd[sorted_idx]\n\n        ax.plot(X_sorted, y_pred_sorted, color=\"red\", linewidth=2, label=\"Sklearn fit\")\n        ax.plot(X_sorted, y_pred_gd_sorted, color=\"green\", linewidth=2, linestyle=\"--\", label=\"Gradient descent\")\n        ax.set_xlabel(\"X\")\n        ax.set_ylabel(\"y\")\n        ax.legend()\n        ax.grid(True, alpha=0.3)\n        ax.set_title(\"Comparison: Sklearn vs Gradient Descent\")\n        mo.display(fig)\n    else:\n        mo.notification(\"Skipping plot: matplotlib is not available.\", kind=\"error\")\n    return\n\n\n@app.cell\ndef _(mo):\n    mo.md(\"## Key Takeaways\")\n    mo.md(\"1. Linear regression models the relationship between variables using a linear equation.\")\n    mo.md(\"2. The parameters (weights and bias) are learned by minimizing the loss function.\")\n    mo.md(\"3. Mean Squared Error (MSE) is a common loss function.\")\n    mo.md(\"4. Gradient descent is commonly used to optimize parameters.\")\n    mo.md(\"5. Even simple models like linear regression can be very effective!\")\n\n    mo.md(\"---\")\n    mo.md(\"**Try modifying the data, learning rate, or number of iterations above to see how the model changes!**\")\n    return\n\n\nif __name__ == \"__main__\":\n    app.run()\n",
+        }),
+        writable: false,
+        configurable: false,
+    });
+</script>
+</head>
+  <body>
+    <div id="root"></div>
+    <!-- This is a portal for the data editor to render in -->
+    <div id="portal" data-testid="glide-portal" style="position: fixed; left: 0; top: 0; z-index: 9999"></div>
+    <script data-marimo="true">
+      Object.defineProperty(window, "__MARIMO_MOUNT_CONFIG__", {
+        value: Object.freeze({
+            "filename": "notes.py",
+            "cwd": "",
+            "lspWorkspace": null,
+            "mode": "read",
+            "version": "0.23.3",
+            "serverToken": "static",
+            "config": {"ai": {"custom_providers": {}, "models": {"custom_models": [], "displayed_models": []}}, "completion": {"activate_on_typing": true, "copilot": false, "signature_hint_on_typing": false}, "diagnostics": {"sql_linter": true}, "display": {"cell_output": "below", "code_editor_font_size": 14, "dataframes": "rich", "default_table_max_columns": 50, "default_table_page_size": 10, "default_width": "medium", "reference_highlighting": true, "theme": "light"}, "formatting": {"line_length": 79}, "keymap": {"overrides": {}, "preset": "default"}, "language_servers": {"pylsp": {"enable_flake8": false, "enable_mypy": true, "enable_pydocstyle": false, "enable_pyflakes": false, "enable_pylint": false, "enable_ruff": true, "enabled": false}}, "mcp": {"mcpServers": {}, "presets": []}, "package_management": {"manager": "uv"}, "runtime": {"auto_instantiate": false, "auto_reload": "off", "default_csv_encoding": "utf-8", "default_sql_output": "auto", "on_cell_change": "autorun", "output_max_bytes": 8000000, "reactive_tests": true, "show_tracebacks": false, "std_stream_max_bytes": 1000000, "watcher_on_save": "lazy"}, "save": {"autosave": "after_delay", "autosave_delay": 1000, "format_on_save": false}, "server": {"browser": "default", "follow_symlink": false}, "snippets": {"custom_paths": [], "include_default_snippets": true}},
+            "configOverrides": {},
+            "appConfig": {"sql_output": "auto", "width": "compact"},
+            "view": {"showAppCode": true},
+            "notebook": {"cells": [{"code": "import marimo as mo\nimport numpy as np\n\n# Remove and warn if matplotlib is missing.\ntry:\n    import matplotlib.pyplot as plt\nexcept ModuleNotFoundError:\n    plt = None\n    mo.notification(\"Matplotlib is not installed. Plots will be skipped or limited.\", kind=\"warning\")\n\nfrom sklearn.datasets import make_regression\nfrom sklearn.linear_model import LinearRegression", "code_hash": "6311d2d636bfb7b8a25160e81c78d21d", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "Hbol", "name": "_"}, {"code": "mo.md(\"# Linear Regression: A Beginner's Guide\")\nmo.md(\n    \"Linear regression is a fundamental technique in machine learning used to model the relationship between a dependent variable and one or more independent variables.\"\n)\nmo.md(\n    \"In this notebook, we'll explore what linear regression is, how it works mathematically, how to fit a model using scikit-learn, and how to implement it from scratch using gradient descent.\"\n)", "code_hash": "ae6176c366881e7b334d536a6a4860a5", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "MJUe", "name": "_"}, {"code": "mo.md(\"## What is Linear Regression?\")\nmo.md(\n    \"Linear regression aims to find the 'best fit' line through data points. This line is defined by weights (coefficients) and a bias term.\"\n)\n\n# Create sample data\nX, y = make_regression(n_samples=100, n_features=1, noise=10, random_state=42)\n\n# Fit sklearn linear regression\nlin_reg = LinearRegression()\nlin_reg.fit(X, y)\n\n# Calculate predictions\ny_pred = lin_reg.predict(X)\n\nif plt is not None:\n    # Sort the data for a prettier line plot\n    sorted_idx = np.argsort(X[:, 0])\n    X_sorted = X[sorted_idx]\n    y_pred_sorted = y_pred[sorted_idx]\n    y_sorted = y[sorted_idx]\n\n    # Plot\n    fig, ax = plt.subplots(figsize=(10, 6))\n    ax.scatter(X, y, alpha=0.6, label=\"Data points\")\n    ax.plot(X_sorted, y_pred_sorted, color=\"red\", linewidth=2, label=\"Fitted line\")\n    ax.set_xlabel(\"X\")\n    ax.set_ylabel(\"y\")\n    ax.legend()\n    ax.grid(True, alpha=0.3)\n    ax.set_title(\"Linear Regression Example\")\n\n    mo.display(fig)\nelse:\n    mo.notification(\"Skipping plot: matplotlib is not available.\", kind=\"error\")", "code_hash": "170ff6c75442add92b65232c51558154", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "vblA", "name": "_"}, {"code": "mo.md(\"## Mathematical Foundation\")\nmo.md(\"The linear regression model can be expressed as:\")\nmo.md(\"$$y = Xw + b$$\")\nmo.md(\"Where:\")\nmo.md(\"- $y$ is the target variable\")\nmo.md(\"- $X$ is the matrix of input features\")\nmo.md(\"- $w$ is the vector of weights\")\nmo.md(\"- $b$ is the bias term\")\n\nmo.md(\"In our example:\")\nmo.md(f\"- Weights (w): {lin_reg.coef_[0]:.2f}\")\nmo.md(f\"- Bias (b): {lin_reg.intercept_:.2f}\")", "code_hash": "59a3865c53fa126bd4cf2f338bb8a1d3", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "bkHC", "name": "_"}, {"code": "mo.md(\"## Loss Function: Mean Squared Error (MSE)\")\nmo.md(\n    \"The goal of linear regression is to minimize the error between predicted and actual values. The most common loss function is Mean Squared Error:\"\n)\nmo.md(\"$$\\\\text{MSE} = \\\\frac{1}{n} \\\\sum_{i=1}^{n} (y_i - \\\\hat{y}_i)^2$$\")\nmo.md(\"Where:\")\nmo.md(\"- $y_i$ is the actual value\")\nmo.md(\"- $\\\\hat{y}_i$ is the predicted value\")\nmo.md(\"- $n$ is the number of samples\")\n\n# Calculate MSE\nmse = np.mean((y - y_pred) ** 2)\nmo.md(f\"In our example, the MSE is approximately: {mse:.2f}\")", "code_hash": "de9208afe44eff71d520ff697cad4770", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "lEQa", "name": "_"}, {"code": "mo.md(\"## How Does It Work? Gradient Descent\")\nmo.md(\n    \"To minimize the MSE, we can use an optimization algorithm called gradient descent. This algorithm iteratively adjusts the weights and bias to reduce the loss function.\"\n)\n\n# Simple implementation of gradient descent\ndef gradient_descent(X, y, learning_rate=0.01, iterations=1000):\n    m = len(X)\n    w = np.random.randn(1)\n    b = 0.0\n\n    # Reshape X\n    x_vec = X.ravel()\n    for i in range(iterations):\n        y_pred = x_vec * w + b\n\n        # Compute gradients\n        dw = (-2 / m) * np.sum(x_vec * (y - y_pred))\n        db = (-2 / m) * np.sum(y - y_pred)\n\n        w -= learning_rate * dw\n        b -= learning_rate * db\n\n    return w, b\n\nw_gd, b_gd = gradient_descent(X, y)\ny_pred_gd = X.ravel() * w_gd + b_gd\n\nmse_gd = np.mean((y - y_pred_gd) ** 2)\n\nmo.md(\"Using gradient descent (learning rate=0.01, 1000 iterations):\")\nmo.md(f\"- Weights (w): {w_gd[0]:.2f}\")\nmo.md(f\"- Bias (b): {b_gd:.2f}\")\nmo.md(f\"- MSE: {mse_gd:.2f}\")", "code_hash": "df993a47fd4bb8dc97b0a17617769ede", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "PKri", "name": "_"}, {"code": "mo.md(\"## Visualizing the Process\")\nif plt is not None:\n    fig, ax = plt.subplots(figsize=(10, 6))\n    ax.scatter(X, y, alpha=0.6, label=\"Data points\")\n\n    # For clean lines, sort the X for both predictions\n    sorted_idx = np.argsort(X[:, 0])\n    X_sorted = X[sorted_idx]\n    y_pred_sorted = y_pred[sorted_idx]\n    y_pred_gd_sorted = y_pred_gd[sorted_idx]\n\n    ax.plot(X_sorted, y_pred_sorted, color=\"red\", linewidth=2, label=\"Sklearn fit\")\n    ax.plot(X_sorted, y_pred_gd_sorted, color=\"green\", linewidth=2, linestyle=\"--\", label=\"Gradient descent\")\n    ax.set_xlabel(\"X\")\n    ax.set_ylabel(\"y\")\n    ax.legend()\n    ax.grid(True, alpha=0.3)\n    ax.set_title(\"Comparison: Sklearn vs Gradient Descent\")\n    mo.display(fig)\nelse:\n    mo.notification(\"Skipping plot: matplotlib is not available.\", kind=\"error\")", "code_hash": "306bc2687366587cb56a645ff49a1445", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "Xref", "name": "_"}, {"code": "mo.md(\"## Key Takeaways\")\nmo.md(\"1. Linear regression models the relationship between variables using a linear equation.\")\nmo.md(\"2. The parameters (weights and bias) are learned by minimizing the loss function.\")\nmo.md(\"3. Mean Squared Error (MSE) is a common loss function.\")\nmo.md(\"4. Gradient descent is commonly used to optimize parameters.\")\nmo.md(\"5. Even simple models like linear regression can be very effective!\")\n\nmo.md(\"---\")\nmo.md(\"**Try modifying the data, learning rate, or number of iterations above to see how the model changes!**\")", "code_hash": "87605417fa79512c613421afe7a9f671", "config": {"column": null, "disabled": false, "hide_code": false}, "id": "SFPL", "name": "_"}], "metadata": {"marimo_version": "0.23.3"}, "version": "1"},
+            "session": {"cells": [{"code_hash": "6311d2d636bfb7b8a25160e81c78d21d", "console": [{"mimetype": "application/vnd.marimo+traceback", "name": "stderr", "text": "\u003Cspan class=\"codehilite\"\u003E\u003Cdiv class=\"highlight\"\u003E\u003Cpre\u003E\u003Cspan\u003E\u003C/span\u003E\u003Cspan class=\"gt\"\u003ETraceback (most recent call last):\u003C/span\u003E\n  File \u003Cspan class=\"nb\"\u003E\u0026quot;/var/folders/44/xrn2r2n539lcfpfq4mb99p48hlq2mb/T/marimo_89694/__marimo__cell_Hbol_.py\u0026quot;\u003C/span\u003E, line \u003Cspan class=\"m\"\u003E6\u003C/span\u003E, in \u003Cspan class=\"n\"\u003E\u0026lt;module\u0026gt;\u003C/span\u003E\n\u003Cspan class=\"w\"\u003E    \u003C/span\u003E\u003Cspan class=\"kn\"\u003Eimport\u003C/span\u003E\u003Cspan class=\"w\"\u003E \u003C/span\u003E\u003Cspan class=\"nn\"\u003Ematplotlib.pyplot\u003C/span\u003E\u003Cspan class=\"w\"\u003E \u003C/span\u003E\u003Cspan class=\"k\"\u003Eas\u003C/span\u003E\u003Cspan class=\"w\"\u003E \u003C/span\u003E\u003Cspan class=\"nn\"\u003Eplt\u003C/span\u003E\n\u003Cspan class=\"gr\"\u003EModuleNotFoundError\u003C/span\u003E: \u003Cspan class=\"n\"\u003ENo module named \u0026#39;matplotlib\u0026#39;\u003C/span\u003E\n\n\u003Cspan class=\"gt\"\u003EDuring handling of the above exception, another exception occurred:\u003C/span\u003E\n\n\u003Cspan class=\"gt\"\u003ETraceback (most recent call last):\u003C/span\u003E\n  File \u003Cspan class=\"nb\"\u003E\u0026quot;/Users/mmt10913/Personal/hackathons/openenv-hackathon/explainer_env/.venv/lib/python3.12/site-packages/marimo/_runtime/executor.py\u0026quot;\u003C/span\u003E, line \u003Cspan class=\"m\"\u003E138\u003C/span\u003E, in \u003Cspan class=\"n\"\u003Eexecute_cell\u003C/span\u003E\n\u003Cspan class=\"w\"\u003E    \u003C/span\u003E\u003Cspan class=\"n\"\u003Eexec\u003C/span\u003E\u003Cspan class=\"p\"\u003E(\u003C/span\u003E\u003Cspan class=\"n\"\u003Ecell\u003C/span\u003E\u003Cspan class=\"o\"\u003E.\u003C/span\u003E\u003Cspan class=\"n\"\u003Ebody\u003C/span\u003E\u003Cspan class=\"p\"\u003E,\u003C/span\u003E \u003Cspan class=\"n\"\u003Eglbls\u003C/span\u003E\u003Cspan class=\"p\"\u003E)\u003C/span\u003E\n  File \u003Cspan class=\"nb\"\u003E\u0026quot;/var/folders/44/xrn2r2n539lcfpfq4mb99p48hlq2mb/T/marimo_89694/__marimo__cell_Hbol_.py\u0026quot;\u003C/span\u003E, line \u003Cspan class=\"m\"\u003E9\u003C/span\u003E, in \u003Cspan class=\"n\"\u003E\u0026lt;module\u0026gt;\u003C/span\u003E\n\u003Cspan class=\"w\"\u003E    \u003C/span\u003E\u003Cspan class=\"n\"\u003Emo\u003C/span\u003E\u003Cspan class=\"o\"\u003E.\u003C/span\u003E\u003Cspan class=\"n\"\u003Enotification\u003C/span\u003E\u003Cspan class=\"p\"\u003E(\u003C/span\u003E\u003Cspan class=\"s2\"\u003E\u0026quot;Matplotlib is not installed. Plots will be skipped or limited.\u0026quot;\u003C/span\u003E\u003Cspan class=\"p\"\u003E,\u003C/span\u003E \u003Cspan class=\"n\"\u003Ekind\u003C/span\u003E\u003Cspan class=\"o\"\u003E=\u003C/span\u003E\u003Cspan class=\"s2\"\u003E\u0026quot;warning\u0026quot;\u003C/span\u003E\u003Cspan class=\"p\"\u003E)\u003C/span\u003E\n\u003Cspan class=\"w\"\u003E    \u003C/span\u003E\u003Cspan class=\"pm\"\u003E^^^^^^^^^^^^^^^\u003C/span\u003E\n\u003Cspan class=\"gr\"\u003EAttributeError\u003C/span\u003E: \u003Cspan class=\"n\"\u003Emodule \u0026#39;marimo\u0026#39; has no attribute \u0026#39;notification\u0026#39;\u003C/span\u003E\n\u003C/pre\u003E\u003C/div\u003E\n\u003C/span\u003E", "type": "stream"}], "id": "Hbol", "outputs": [{"ename": "exception", "evalue": "module 'marimo' has no attribute 'notification'", "traceback": null, "type": "error"}]}, {"code_hash": "ae6176c366881e7b334d536a6a4860a5", "console": [], "id": "MJUe", "outputs": [{"ename": "exception", "evalue": "An ancestor raised an exception (AttributeError): ", "traceback": null, "type": "error"}]}, {"code_hash": "170ff6c75442add92b65232c51558154", "console": [], "id": "vblA", "outputs": [{"ename": "multiple-defs", "evalue": "The variable 'X_sorted' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'ax' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'fig' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'sorted_idx' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'y_pred_sorted' was defined by another cell", "traceback": [], "type": "error"}]}, {"code_hash": "59a3865c53fa126bd4cf2f338bb8a1d3", "console": [], "id": "bkHC", "outputs": [{"ename": "exception", "evalue": "An ancestor raised an exception (AttributeError): ", "traceback": null, "type": "error"}]}, {"code_hash": "de9208afe44eff71d520ff697cad4770", "console": [], "id": "lEQa", "outputs": [{"ename": "exception", "evalue": "An ancestor raised an exception (AttributeError): ", "traceback": null, "type": "error"}]}, {"code_hash": "df993a47fd4bb8dc97b0a17617769ede", "console": [], "id": "PKri", "outputs": [{"ename": "exception", "evalue": "An ancestor raised an exception (AttributeError): ", "traceback": null, "type": "error"}]}, {"code_hash": "306bc2687366587cb56a645ff49a1445", "console": [], "id": "Xref", "outputs": [{"ename": "multiple-defs", "evalue": "The variable 'X_sorted' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'ax' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'fig' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'sorted_idx' was defined by another cell", "traceback": [], "type": "error"}, {"ename": "multiple-defs", "evalue": "The variable 'y_pred_sorted' was defined by another cell", "traceback": [], "type": "error"}]}, {"code_hash": "87605417fa79512c613421afe7a9f671", "console": [], "id": "SFPL", "outputs": [{"ename": "exception", "evalue": "An ancestor raised an exception (AttributeError): ", "traceback": null, "type": "error"}]}], "metadata": {"marimo_version": "0.23.3", "script_metadata_hash": null}, "version": "1"},
+            "runtimeConfig": null,
+        }),
+        writable: false,
+        configurable: false,
+      });
+    </script>
+<marimo-code hidden="">
+    import%20marimo%0A%0A__generated_with%20%3D%20%220.23.3%22%0Aapp%20%3D%20marimo.App()%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20import%20marimo%20as%20mo%0A%20%20%20%20import%20numpy%20as%20np%0A%0A%20%20%20%20%23%20Remove%20and%20warn%20if%20matplotlib%20is%20missing.%0A%20%20%20%20try%3A%0A%20%20%20%20%20%20%20%20import%20matplotlib.pyplot%20as%20plt%0A%20%20%20%20except%20ModuleNotFoundError%3A%0A%20%20%20%20%20%20%20%20plt%20%3D%20None%0A%20%20%20%20%20%20%20%20mo.notification(%22Matplotlib%20is%20not%20installed.%20Plots%20will%20be%20skipped%20or%20limited.%22%2C%20kind%3D%22warning%22)%0A%0A%20%20%20%20from%20sklearn.datasets%20import%20make_regression%0A%20%20%20%20from%20sklearn.linear_model%20import%20LinearRegression%0A%0A%20%20%20%20return%20LinearRegression%2C%20make_regression%2C%20mo%2C%20np%2C%20plt%0A%0A%0A%40app.cell%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(%22%23%20Linear%20Regression%3A%20A%20Beginner's%20Guide%22)%0A%20%20%20%20mo.md(%0A%20%20%20%20%20%20%20%20%22Linear%20regression%20is%20a%20fundamental%20technique%20in%20machine%20learning%20used%20to%20model%20the%20relationship%20between%20a%20dependent%20variable%20and%20one%20or%20more%20independent%20variables.%22%0A%20%20%20%20)%0A%20%20%20%20mo.md(%0A%20%20%20%20%20%20%20%20%22In%20this%20notebook%2C%20we'll%20explore%20what%20linear%20regression%20is%2C%20how%20it%20works%20mathematically%2C%20how%20to%20fit%20a%20model%20using%20scikit-learn%2C%20and%20how%20to%20implement%20it%20from%20scratch%20using%20gradient%20descent.%22%0A%20%20%20%20)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_(LinearRegression%2C%20make_regression%2C%20mo%2C%20np%2C%20plt)%3A%0A%20%20%20%20mo.md(%22%23%23%20What%20is%20Linear%20Regression%3F%22)%0A%20%20%20%20mo.md(%0A%20%20%20%20%20%20%20%20%22Linear%20regression%20aims%20to%20find%20the%20'best%20fit'%20line%20through%20data%20points.%20This%20line%20is%20defined%20by%20weights%20(coefficients)%20and%20a%20bias%20term.%22%0A%20%20%20%20)%0A%0A%20%20%20%20%23%20Create%20sample%20data%0A%20%20%20%20X%2C%20y%20%3D%20make_regression(n_samples%3D100%2C%20n_features%3D1%2C%20noise%3D10%2C%20random_state%3D42)%0A%0A%20%20%20%20%23%20Fit%20sklearn%20linear%20regression%0A%20%20%20%20lin_reg%20%3D%20LinearRegression()%0A%20%20%20%20lin_reg.fit(X%2C%20y)%0A%0A%20%20%20%20%23%20Calculate%20predictions%0A%20%20%20%20y_pred%20%3D%20lin_reg.predict(X)%0A%0A%20%20%20%20if%20plt%20is%20not%20None%3A%0A%20%20%20%20%20%20%20%20%23%20Sort%20the%20data%20for%20a%20prettier%20line%20plot%0A%20%20%20%20%20%20%20%20sorted_idx%20%3D%20np.argsort(X%5B%3A%2C%200%5D)%0A%20%20%20%20%20%20%20%20X_sorted%20%3D%20X%5Bsorted_idx%5D%0A%20%20%20%20%20%20%20%20y_pred_sorted%20%3D%20y_pred%5Bsorted_idx%5D%0A%20%20%20%20%20%20%20%20y_sorted%20%3D%20y%5Bsorted_idx%5D%0A%0A%20%20%20%20%20%20%20%20%23%20Plot%0A%20%20%20%20%20%20%20%20fig%2C%20ax%20%3D%20plt.subplots(figsize%3D(10%2C%206))%0A%20%20%20%20%20%20%20%20ax.scatter(X%2C%20y%2C%20alpha%3D0.6%2C%20label%3D%22Data%20points%22)%0A%20%20%20%20%20%20%20%20ax.plot(X_sorted%2C%20y_pred_sorted%2C%20color%3D%22red%22%2C%20linewidth%3D2%2C%20label%3D%22Fitted%20line%22)%0A%20%20%20%20%20%20%20%20ax.set_xlabel(%22X%22)%0A%20%20%20%20%20%20%20%20ax.set_ylabel(%22y%22)%0A%20%20%20%20%20%20%20%20ax.legend()%0A%20%20%20%20%20%20%20%20ax.grid(True%2C%20alpha%3D0.3)%0A%20%20%20%20%20%20%20%20ax.set_title(%22Linear%20Regression%20Example%22)%0A%0A%20%20%20%20%20%20%20%20mo.display(fig)%0A%20%20%20%20else%3A%0A%20%20%20%20%20%20%20%20mo.notification(%22Skipping%20plot%3A%20matplotlib%20is%20not%20available.%22%2C%20kind%3D%22error%22)%0A%20%20%20%20return%20X%2C%20lin_reg%2C%20y%2C%20y_pred%0A%0A%0A%40app.cell%0Adef%20_(lin_reg%2C%20mo)%3A%0A%20%20%20%20mo.md(%22%23%23%20Mathematical%20Foundation%22)%0A%20%20%20%20mo.md(%22The%20linear%20regression%20model%20can%20be%20expressed%20as%3A%22)%0A%20%20%20%20mo.md(%22%24%24y%20%3D%20Xw%20%2B%20b%24%24%22)%0A%20%20%20%20mo.md(%22Where%3A%22)%0A%20%20%20%20mo.md(%22-%20%24y%24%20is%20the%20target%20variable%22)%0A%20%20%20%20mo.md(%22-%20%24X%24%20is%20the%20matrix%20of%20input%20features%22)%0A%20%20%20%20mo.md(%22-%20%24w%24%20is%20the%20vector%20of%20weights%22)%0A%20%20%20%20mo.md(%22-%20%24b%24%20is%20the%20bias%20term%22)%0A%0A%20%20%20%20mo.md(%22In%20our%20example%3A%22)%0A%20%20%20%20mo.md(f%22-%20Weights%20(w)%3A%20%7Blin_reg.coef_%5B0%5D%3A.2f%7D%22)%0A%20%20%20%20mo.md(f%22-%20Bias%20(b)%3A%20%7Blin_reg.intercept_%3A.2f%7D%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_(mo%2C%20np%2C%20y%2C%20y_pred)%3A%0A%20%20%20%20mo.md(%22%23%23%20Loss%20Function%3A%20Mean%20Squared%20Error%20(MSE)%22)%0A%20%20%20%20mo.md(%0A%20%20%20%20%20%20%20%20%22The%20goal%20of%20linear%20regression%20is%20to%20minimize%20the%20error%20between%20predicted%20and%20actual%20values.%20The%20most%20common%20loss%20function%20is%20Mean%20Squared%20Error%3A%22%0A%20%20%20%20)%0A%20%20%20%20mo.md(%22%24%24%5C%5Ctext%7BMSE%7D%20%3D%20%5C%5Cfrac%7B1%7D%7Bn%7D%20%5C%5Csum_%7Bi%3D1%7D%5E%7Bn%7D%20(y_i%20-%20%5C%5Chat%7By%7D_i)%5E2%24%24%22)%0A%20%20%20%20mo.md(%22Where%3A%22)%0A%20%20%20%20mo.md(%22-%20%24y_i%24%20is%20the%20actual%20value%22)%0A%20%20%20%20mo.md(%22-%20%24%5C%5Chat%7By%7D_i%24%20is%20the%20predicted%20value%22)%0A%20%20%20%20mo.md(%22-%20%24n%24%20is%20the%20number%20of%20samples%22)%0A%0A%20%20%20%20%23%20Calculate%20MSE%0A%20%20%20%20mse%20%3D%20np.mean((y%20-%20y_pred)%20**%202)%0A%20%20%20%20mo.md(f%22In%20our%20example%2C%20the%20MSE%20is%20approximately%3A%20%7Bmse%3A.2f%7D%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_(X%2C%20mo%2C%20np%2C%20y)%3A%0A%20%20%20%20mo.md(%22%23%23%20How%20Does%20It%20Work%3F%20Gradient%20Descent%22)%0A%20%20%20%20mo.md(%0A%20%20%20%20%20%20%20%20%22To%20minimize%20the%20MSE%2C%20we%20can%20use%20an%20optimization%20algorithm%20called%20gradient%20descent.%20This%20algorithm%20iteratively%20adjusts%20the%20weights%20and%20bias%20to%20reduce%20the%20loss%20function.%22%0A%20%20%20%20)%0A%0A%20%20%20%20%23%20Simple%20implementation%20of%20gradient%20descent%0A%20%20%20%20def%20gradient_descent(X%2C%20y%2C%20learning_rate%3D0.01%2C%20iterations%3D1000)%3A%0A%20%20%20%20%20%20%20%20m%20%3D%20len(X)%0A%20%20%20%20%20%20%20%20w%20%3D%20np.random.randn(1)%0A%20%20%20%20%20%20%20%20b%20%3D%200.0%0A%0A%20%20%20%20%20%20%20%20%23%20Reshape%20X%0A%20%20%20%20%20%20%20%20x_vec%20%3D%20X.ravel()%0A%20%20%20%20%20%20%20%20for%20i%20in%20range(iterations)%3A%0A%20%20%20%20%20%20%20%20%20%20%20%20y_pred%20%3D%20x_vec%20*%20w%20%2B%20b%0A%0A%20%20%20%20%20%20%20%20%20%20%20%20%23%20Compute%20gradients%0A%20%20%20%20%20%20%20%20%20%20%20%20dw%20%3D%20(-2%20%2F%20m)%20*%20np.sum(x_vec%20*%20(y%20-%20y_pred))%0A%20%20%20%20%20%20%20%20%20%20%20%20db%20%3D%20(-2%20%2F%20m)%20*%20np.sum(y%20-%20y_pred)%0A%0A%20%20%20%20%20%20%20%20%20%20%20%20w%20-%3D%20learning_rate%20*%20dw%0A%20%20%20%20%20%20%20%20%20%20%20%20b%20-%3D%20learning_rate%20*%20db%0A%0A%20%20%20%20%20%20%20%20return%20w%2C%20b%0A%0A%20%20%20%20w_gd%2C%20b_gd%20%3D%20gradient_descent(X%2C%20y)%0A%20%20%20%20y_pred_gd%20%3D%20X.ravel()%20*%20w_gd%20%2B%20b_gd%0A%0A%20%20%20%20mse_gd%20%3D%20np.mean((y%20-%20y_pred_gd)%20**%202)%0A%0A%20%20%20%20mo.md(%22Using%20gradient%20descent%20(learning%20rate%3D0.01%2C%201000%20iterations)%3A%22)%0A%20%20%20%20mo.md(f%22-%20Weights%20(w)%3A%20%7Bw_gd%5B0%5D%3A.2f%7D%22)%0A%20%20%20%20mo.md(f%22-%20Bias%20(b)%3A%20%7Bb_gd%3A.2f%7D%22)%0A%20%20%20%20mo.md(f%22-%20MSE%3A%20%7Bmse_gd%3A.2f%7D%22)%0A%20%20%20%20return%20(y_pred_gd%2C)%0A%0A%0A%40app.cell%0Adef%20_(X%2C%20mo%2C%20np%2C%20plt%2C%20y%2C%20y_pred%2C%20y_pred_gd)%3A%0A%20%20%20%20mo.md(%22%23%23%20Visualizing%20the%20Process%22)%0A%20%20%20%20if%20plt%20is%20not%20None%3A%0A%20%20%20%20%20%20%20%20fig%2C%20ax%20%3D%20plt.subplots(figsize%3D(10%2C%206))%0A%20%20%20%20%20%20%20%20ax.scatter(X%2C%20y%2C%20alpha%3D0.6%2C%20label%3D%22Data%20points%22)%0A%0A%20%20%20%20%20%20%20%20%23%20For%20clean%20lines%2C%20sort%20the%20X%20for%20both%20predictions%0A%20%20%20%20%20%20%20%20sorted_idx%20%3D%20np.argsort(X%5B%3A%2C%200%5D)%0A%20%20%20%20%20%20%20%20X_sorted%20%3D%20X%5Bsorted_idx%5D%0A%20%20%20%20%20%20%20%20y_pred_sorted%20%3D%20y_pred%5Bsorted_idx%5D%0A%20%20%20%20%20%20%20%20y_pred_gd_sorted%20%3D%20y_pred_gd%5Bsorted_idx%5D%0A%0A%20%20%20%20%20%20%20%20ax.plot(X_sorted%2C%20y_pred_sorted%2C%20color%3D%22red%22%2C%20linewidth%3D2%2C%20label%3D%22Sklearn%20fit%22)%0A%20%20%20%20%20%20%20%20ax.plot(X_sorted%2C%20y_pred_gd_sorted%2C%20color%3D%22green%22%2C%20linewidth%3D2%2C%20linestyle%3D%22--%22%2C%20label%3D%22Gradient%20descent%22)%0A%20%20%20%20%20%20%20%20ax.set_xlabel(%22X%22)%0A%20%20%20%20%20%20%20%20ax.set_ylabel(%22y%22)%0A%20%20%20%20%20%20%20%20ax.legend()%0A%20%20%20%20%20%20%20%20ax.grid(True%2C%20alpha%3D0.3)%0A%20%20%20%20%20%20%20%20ax.set_title(%22Comparison%3A%20Sklearn%20vs%20Gradient%20Descent%22)%0A%20%20%20%20%20%20%20%20mo.display(fig)%0A%20%20%20%20else%3A%0A%20%20%20%20%20%20%20%20mo.notification(%22Skipping%20plot%3A%20matplotlib%20is%20not%20available.%22%2C%20kind%3D%22error%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(%22%23%23%20Key%20Takeaways%22)%0A%20%20%20%20mo.md(%221.%20Linear%20regression%20models%20the%20relationship%20between%20variables%20using%20a%20linear%20equation.%22)%0A%20%20%20%20mo.md(%222.%20The%20parameters%20(weights%20and%20bias)%20are%20learned%20by%20minimizing%20the%20loss%20function.%22)%0A%20%20%20%20mo.md(%223.%20Mean%20Squared%20Error%20(MSE)%20is%20a%20common%20loss%20function.%22)%0A%20%20%20%20mo.md(%224.%20Gradient%20descent%20is%20commonly%20used%20to%20optimize%20parameters.%22)%0A%20%20%20%20mo.md(%225.%20Even%20simple%20models%20like%20linear%20regression%20can%20be%20very%20effective!%22)%0A%0A%20%20%20%20mo.md(%22---%22)%0A%20%20%20%20mo.md(%22**Try%20modifying%20the%20data%2C%20learning%20rate%2C%20or%20number%20of%20iterations%20above%20to%20see%20how%20the%20model%20changes!**%22)%0A%20%20%20%20return%0A%0A%0Aif%20__name__%20%3D%3D%20%22__main__%22%3A%0A%20%20%20%20app.run()%0A
+</marimo-code>
+<marimo-code-hash hidden="">a84b1545db77625ca9cf9d6dc8c1e9c1</marimo-code-hash>
+</body>
+</html>

openenv_explainer_env.egg-info/PKG-INFO CHANGED Viewed

@@ -3,12 +3,22 @@ Name: openenv-explainer_env
 Version: 0.1.0
 Summary: Interactive Explainer OpenEnv
 Requires-Python: >=3.10
-Requires-Dist: openenv-core[core]>=0.2.2
 Requires-Dist: marimo>=0.10.0
 Requires-Dist: manim>=0.18.0
 Requires-Dist: wikipedia-api>=0.14.1
 Requires-Dist: huggingface-hub>=1.12.0
 Requires-Dist: httpx>=0.28.1
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

 Version: 0.1.0
 Summary: Interactive Explainer OpenEnv
 Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.3
 Requires-Dist: marimo>=0.10.0
 Requires-Dist: manim>=0.18.0
 Requires-Dist: wikipedia-api>=0.14.1
 Requires-Dist: huggingface-hub>=1.12.0
 Requires-Dist: httpx>=0.28.1
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: sympy
+Requires-Dist: scikit-learn
+Requires-Dist: networkx
+Requires-Dist: plotly
+Requires-Dist: trafilatura
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_explainer_env.egg-info/SOURCES.txt CHANGED Viewed

@@ -14,6 +14,10 @@ openenv_explainer_env.egg-info/dependency_links.txt
 openenv_explainer_env.egg-info/entry_points.txt
 openenv_explainer_env.egg-info/requires.txt
 openenv_explainer_env.egg-info/top_level.txt
 rewards/__init__.py
 rewards/exploration.py
 rewards/generation.py

 openenv_explainer_env.egg-info/entry_points.txt
 openenv_explainer_env.egg-info/requires.txt
 openenv_explainer_env.egg-info/top_level.txt
+research/__init__.py
+research/retrieval.py
+research/router.py
+research/types.py
 rewards/__init__.py
 rewards/exploration.py
 rewards/generation.py

openenv_explainer_env.egg-info/requires.txt CHANGED Viewed

@@ -1,9 +1,19 @@
-openenv-core[core]>=0.2.2
 marimo>=0.10.0
 manim>=0.18.0
 wikipedia-api>=0.14.1
 huggingface-hub>=1.12.0
 httpx>=0.28.1
 [dev]
 pytest>=8.0.0

+openenv-core[core]>=0.2.3
 marimo>=0.10.0
 manim>=0.18.0
 wikipedia-api>=0.14.1
 huggingface-hub>=1.12.0
 httpx>=0.28.1
+nbformat>=5.10.4
+numpy
+matplotlib
+pandas
+scipy
+sympy
+scikit-learn
+networkx
+plotly
+trafilatura
 [dev]
 pytest>=8.0.0

pyproject.toml CHANGED Viewed

@@ -8,12 +8,22 @@ version = "0.1.0"
 description = "Interactive Explainer OpenEnv"
 requires-python = ">=3.10"
 dependencies = [
-    "openenv-core[core]>=0.2.2",
     "marimo>=0.10.0",
     "manim>=0.18.0",
     "wikipedia-api>=0.14.1",
     "huggingface-hub>=1.12.0",
     "httpx>=0.28.1",
 ]
 [project.optional-dependencies]
@@ -27,8 +37,8 @@ server = "explainer_env.server.app:main"
 [tool.setuptools]
 include-package-data = true
-packages = ["explainer_env", "explainer_env.server", "explainer_env.rewards"]
-package-dir = { "explainer_env" = ".", "explainer_env.server" = "server", "explainer_env.rewards" = "rewards" }
 [dependency-groups]
 dev = []

 description = "Interactive Explainer OpenEnv"
 requires-python = ">=3.10"
 dependencies = [
+    "openenv-core[core]>=0.2.3",
     "marimo>=0.10.0",
     "manim>=0.18.0",
     "wikipedia-api>=0.14.1",
     "huggingface-hub>=1.12.0",
     "httpx>=0.28.1",
+    "nbformat>=5.10.4",
+    "numpy",
+    "matplotlib",
+    "pandas",
+    "scipy",
+    "sympy",
+    "scikit-learn",
+    "networkx",
+    "plotly",
+    "trafilatura",
 ]
 [project.optional-dependencies]
 [tool.setuptools]
 include-package-data = true
+packages = ["explainer_env", "explainer_env.server", "explainer_env.rewards", "explainer_env.research"]
+package-dir = { "explainer_env" = ".", "explainer_env.server" = "server", "explainer_env.rewards" = "rewards", "explainer_env.research" = "research" }
 [dependency-groups]
 dev = []

research/__init__.py ADDED Viewed

	@@ -0,0 +1,11 @@

+"""Research tools for the explainer environment."""
+from .router import AVAILABLE_TOOLS, run_research_tool
+from .types import ResearchChunk, ResearchResult
+__all__ = [
+    "AVAILABLE_TOOLS",
+    "ResearchChunk",
+    "ResearchResult",
+    "run_research_tool",
+]

research/retrieval.py ADDED Viewed

	@@ -0,0 +1,179 @@

+"""Small retrieval helpers: tokenization, BM25, chunking, optional embeddings."""
+from __future__ import annotations
+import math
+import os
+import re
+from collections import Counter
+from .types import ResearchChunk
+SECTION_MAX_CHARS = 900
+MAX_RETURNED_CHUNKS = 5
+BM25_CANDIDATES_FOR_EMBEDDINGS = 12
+_BM25_K1 = 1.5
+_BM25_B = 0.75
+_STOP_WORDS = frozenset({
+    "the",
+    "a",
+    "an",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "have",
+    "has",
+    "had",
+    "do",
+    "does",
+    "did",
+    "will",
+    "would",
+    "could",
+    "should",
+    "to",
+    "of",
+    "in",
+    "for",
+    "on",
+    "with",
+    "at",
+    "by",
+    "from",
+    "as",
+    "and",
+    "but",
+    "or",
+    "this",
+    "that",
+    "these",
+    "those",
+    "it",
+    "its",
+})
+def tokenize(text: str) -> list[str]:
+    """Lowercase alphanumeric tokenization, stop words removed."""
+    return [
+        word
+        for word in re.findall(r"\w+", text.lower())
+        if word not in _STOP_WORDS and len(word) > 1
+    ]
+def trim_text(text: str, max_chars: int = SECTION_MAX_CHARS) -> str:
+    text = re.sub(r"\s+", " ", text).strip()
+    return text[:max_chars].strip()
+def chunk_markdown(text: str, fallback_title: str) -> list[tuple[str, str]]:
+    """Split markdown-ish text into titled chunks."""
+    chunks: list[tuple[str, str]] = []
+    heading = fallback_title
+    lines: list[str] = []
+    for line in text.splitlines():
+        if line.startswith("#"):
+            body = "\n".join(lines).strip()
+            if body:
+                chunks.append((heading, body))
+            heading = line.lstrip("#").strip() or fallback_title
+            lines = []
+        else:
+            lines.append(line)
+    body = "\n".join(lines).strip()
+    if body:
+        chunks.append((heading, body))
+    return chunks
+def bm25_rank(query: str, chunks: list[ResearchChunk], top_k: int) -> list[ResearchChunk]:
+    """Rank chunks against query using BM25."""
+    if not chunks:
+        return []
+    query_terms = tokenize(query)
+    if not query_terms:
+        ranked = chunks[:top_k]
+        for idx, chunk in enumerate(ranked, start=1):
+            chunk.rank = idx
+        return ranked
+    doc_tokens = [tokenize(f"{chunk.title} {chunk.text}") for chunk in chunks]
+    doc_lengths = [len(tokens) for tokens in doc_tokens]
+    avgdl = sum(doc_lengths) / max(len(doc_lengths), 1)
+    n_docs = len(chunks)
+    df = {
+        term: sum(1 for tokens in doc_tokens if term in tokens)
+        for term in set(query_terms)
+    }
+    scored: list[ResearchChunk] = []
+    for idx, chunk in enumerate(chunks):
+        tf_counts = Counter(doc_tokens[idx])
+        dl = doc_lengths[idx]
+        score = 0.0
+        for term in query_terms:
+            if df.get(term, 0) == 0:
+                continue
+            idf = math.log((n_docs - df[term] + 0.5) / (df[term] + 0.5) + 1.0)
+            tf = tf_counts.get(term, 0)
+            score += idf * tf * (_BM25_K1 + 1) / (
+                tf + _BM25_K1 * (1 - _BM25_B + _BM25_B * dl / max(avgdl, 1))
+            )
+        chunk.score = score
+        scored.append(chunk)
+    scored.sort(key=lambda chunk: chunk.score, reverse=True)
+    ranked = _maybe_embedding_rerank(query, scored[:BM25_CANDIDATES_FOR_EMBEDDINGS])
+    ranked = ranked[:top_k]
+    for idx, chunk in enumerate(ranked, start=1):
+        chunk.rank = idx
+    return ranked
+def _maybe_embedding_rerank(query: str, chunks: list[ResearchChunk]) -> list[ResearchChunk]:
+    """Optionally rerank a small BM25 shortlist with a tiny local embedding model."""
+    if os.getenv("EMBEDDINGS_ENABLED", "").lower() not in {"1", "true", "yes"}:
+        return chunks
+    try:
+        from fastembed import TextEmbedding
+    except Exception:
+        return chunks
+    try:
+        model_name = os.getenv("EMBEDDING_MODEL", "BAAI/bge-small-en-v1.5")
+        model = TextEmbedding(model_name=model_name)
+        vectors = list(model.embed([query] + [chunk.text for chunk in chunks]))
+    except Exception:
+        return chunks
+    if len(vectors) != len(chunks) + 1:
+        return chunks
+    query_vec = vectors[0]
+    rescored: list[ResearchChunk] = []
+    for chunk, vec in zip(chunks, vectors[1:]):
+        chunk.score = _cosine(query_vec, vec)
+        rescored.append(chunk)
+    rescored.sort(key=lambda chunk: chunk.score, reverse=True)
+    return rescored
+def _cosine(a, b) -> float:
+    numerator = sum(float(x) * float(y) for x, y in zip(a, b))
+    a_norm = math.sqrt(sum(float(x) * float(x) for x in a))
+    b_norm = math.sqrt(sum(float(y) * float(y) for y in b))
+    if a_norm == 0 or b_norm == 0:
+        return 0.0
+    return numerator / (a_norm * b_norm)

research/router.py ADDED Viewed

	@@ -0,0 +1,381 @@

+"""Explicit research tools used by the explore phase."""
+from __future__ import annotations
+import asyncio
+import html
+import re
+import xml.etree.ElementTree as ET
+from typing import Callable, Awaitable
+import httpx
+import wikipediaapi
+try:
+    from .. import constants as _constants
+except ImportError:  # pragma: no cover - supports direct test execution
+    import constants as _constants
+from .retrieval import bm25_rank, chunk_markdown, trim_text
+from .types import ResearchChunk, ResearchResult
+AVAILABLE_TOOLS = _constants.AVAILABLE_TOOLS
+MAX_SOURCE_RESULTS = 5
+MAX_RETURNED_CHUNKS = 5
+async def run_research_tool(tool: str, query: str, intent: str = "") -> ResearchResult:
+    """Run a named research tool and return structured chunks."""
+    tool = tool.strip()
+    query = query.strip()
+    if tool not in _TOOL_RUNNERS:
+        return ResearchResult(tool=tool or "(missing)", query=query, error="Unknown research tool")
+    if not query:
+        return ResearchResult(tool=tool, query=query, error="Empty query")
+    return await _TOOL_RUNNERS[tool](query, intent)
+async def search_wikipedia(query: str, intent: str = "") -> ResearchResult:
+    try:
+        wiki = wikipediaapi.AsyncWikipedia(
+            user_agent="ExplainerEnv/1.0 (hackathon project)",
+            language="en",
+        )
+        search_results = await wiki.search(query, limit=MAX_SOURCE_RESULTS)
+        titles = list(search_results.pages) if search_results and search_results.pages else []
+        chunks: list[ResearchChunk] = []
+        for title in titles:
+            page = wiki.page(title)
+            if not await page.exists():
+                continue
+            summary = await page.summary
+            sections = await page.sections
+            docs: list[tuple[str, str]] = []
+            if summary:
+                docs.append((title, summary))
+            docs.extend(_flatten_wikipedia_sections(sections))
+            for section_title, text in docs:
+                snippet = trim_text(text)
+                if snippet:
+                    chunks.append(
+                        ResearchChunk(
+                            source="wikipedia",
+                            tool="search_wikipedia",
+                            title=f"{title} - {section_title}",
+                            url=f"https://en.wikipedia.org/wiki/{title.replace(' ', '_')}",
+                            text=snippet,
+                            metadata={"page": title},
+                        )
+                    )
+        ranked = bm25_rank(f"{query} {intent}", chunks, MAX_RETURNED_CHUNKS)
+        return ResearchResult("search_wikipedia", query, ranked, raw_count=len(chunks))
+    except Exception as exc:
+        return ResearchResult("search_wikipedia", query, error=str(exc))
+async def search_hf_papers(query: str, intent: str = "") -> ResearchResult:
+    try:
+        async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client:
+            resp = await client.get(
+                "https://huggingface.co/api/papers/search",
+                params={"q": query, "limit": MAX_SOURCE_RESULTS},
+                headers={"User-Agent": "ExplainerEnv/1.0"},
+            )
+            resp.raise_for_status()
+            papers = resp.json() or []
+            chunks: list[ResearchChunk] = []
+            for paper in papers[:MAX_SOURCE_RESULTS]:
+                paper_id = paper.get("id", "")
+                title = paper.get("title", "Untitled")
+                url = f"https://huggingface.co/papers/{paper_id}" if paper_id else ""
+                text_chunks = [("Abstract", paper.get("summary", ""))]
+                if paper_id:
+                    md_resp = await client.get(
+                        f"https://huggingface.co/papers/{paper_id}.md",
+                        headers={"User-Agent": "ExplainerEnv/1.0"},
+                    )
+                    if md_resp.status_code == 200 and md_resp.text.strip():
+                        text_chunks = chunk_markdown(md_resp.text, "Abstract")
+                for section_title, text in text_chunks:
+                    snippet = trim_text(text)
+                    if snippet:
+                        chunks.append(
+                            ResearchChunk(
+                                source="hf_papers",
+                                tool="search_hf_papers",
+                                title=f"{title} - {section_title}",
+                                url=url,
+                                text=snippet,
+                                metadata={"paper_id": paper_id},
+                            )
+                        )
+        ranked = bm25_rank(f"{query} {intent}", chunks, MAX_RETURNED_CHUNKS)
+        return ResearchResult("search_hf_papers", query, ranked, raw_count=len(chunks))
+    except Exception as exc:
+        return ResearchResult("search_hf_papers", query, error=str(exc))
+async def search_arxiv(query: str, intent: str = "") -> ResearchResult:
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            resp = await client.get(
+                "https://export.arxiv.org/api/query",
+                params={
+                    "search_query": f"all:{query}",
+                    "start": 0,
+                    "max_results": MAX_SOURCE_RESULTS,
+                    "sortBy": "relevance",
+                    "sortOrder": "descending",
+                },
+                headers={"User-Agent": "ExplainerEnv/1.0"},
+            )
+            resp.raise_for_status()
+        root = ET.fromstring(resp.text)
+        ns = {"atom": "http://www.w3.org/2005/Atom", "arxiv": "http://arxiv.org/schemas/atom"}
+        chunks: list[ResearchChunk] = []
+        for entry in root.findall("atom:entry", ns):
+            title = _xml_text(entry, "atom:title", ns) or "Untitled"
+            summary = _xml_text(entry, "atom:summary", ns)
+            url = _xml_text(entry, "atom:id", ns)
+            published = _xml_text(entry, "atom:published", ns)
+            authors = [
+                _xml_text(author, "atom:name", ns)
+                for author in entry.findall("atom:author", ns)
+            ]
+            categories = [
+                cat.attrib.get("term", "")
+                for cat in entry.findall("atom:category", ns)
+                if cat.attrib.get("term")
+            ]
+            snippet = trim_text(summary)
+            if snippet:
+                chunks.append(
+                    ResearchChunk(
+                        source="arxiv",
+                        tool="search_arxiv",
+                        title=html.unescape(title),
+                        url=url,
+                        text=html.unescape(snippet),
+                        metadata={
+                            "published": published,
+                            "authors": [a for a in authors if a],
+                            "categories": categories,
+                        },
+                    )
+                )
+        ranked = bm25_rank(f"{query} {intent}", chunks, MAX_RETURNED_CHUNKS)
+        return ResearchResult("search_arxiv", query, ranked, raw_count=len(chunks))
+    except Exception as exc:
+        return ResearchResult("search_arxiv", query, error=str(exc))
+async def search_scholar(query: str, intent: str = "") -> ResearchResult:
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            resp = await client.get(
+                "https://api.semanticscholar.org/graph/v1/paper/search",
+                params={
+                    "query": query,
+                    "limit": MAX_SOURCE_RESULTS,
+                    "fields": "title,abstract,url,year,citationCount,venue,authors",
+                },
+                headers={"User-Agent": "ExplainerEnv/1.0"},
+            )
+            resp.raise_for_status()
+            papers = resp.json().get("data", [])
+        chunks: list[ResearchChunk] = []
+        for paper in papers:
+            abstract = paper.get("abstract") or ""
+            snippet = trim_text(abstract)
+            if not snippet:
+                continue
+            chunks.append(
+                ResearchChunk(
+                    source="semantic_scholar",
+                    tool="search_scholar",
+                    title=paper.get("title", "Untitled"),
+                    url=paper.get("url", ""),
+                    text=snippet,
+                    metadata={
+                        "year": paper.get("year"),
+                        "venue": paper.get("venue"),
+                        "citation_count": paper.get("citationCount", 0),
+                    },
+                )
+            )
+        ranked = bm25_rank(f"{query} {intent}", chunks, MAX_RETURNED_CHUNKS)
+        return ResearchResult("search_scholar", query, ranked, raw_count=len(chunks))
+    except Exception as exc:
+        return ResearchResult("search_scholar", query, error=str(exc))
+async def fetch_docs(query: str, intent: str = "") -> ResearchResult:
+    urls = _select_doc_urls(query)
+    if not urls:
+        return ResearchResult("fetch_docs", query, error="No allowed documentation target matched query")
+    chunks: list[ResearchChunk] = []
+    async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client:
+        for title, url in urls[:MAX_SOURCE_RESULTS]:
+            try:
+                resp = await client.get(url, headers={"User-Agent": "ExplainerEnv/1.0"})
+                resp.raise_for_status()
+                text = _extract_page_text(resp.text)
+            except Exception:
+                continue
+            for section_title, body in chunk_markdown(text, title):
+                snippet = trim_text(body)
+                if snippet:
+                    chunks.append(
+                        ResearchChunk(
+                            source="docs",
+                            tool="fetch_docs",
+                            title=f"{title} - {section_title}",
+                            url=url,
+                            text=snippet,
+                            metadata={"doc": title},
+                        )
+                    )
+    ranked = bm25_rank(f"{query} {intent}", chunks, MAX_RETURNED_CHUNKS)
+    return ResearchResult("fetch_docs", query, ranked, raw_count=len(chunks))
+async def search_hf_hub(query: str, intent: str = "") -> ResearchResult:
+    try:
+        from huggingface_hub import HfApi
+    except Exception as exc:
+        return ResearchResult("search_hf_hub", query, error=f"huggingface_hub unavailable: {exc}")
+    def _load() -> list[ResearchChunk]:
+        api = HfApi()
+        chunks: list[ResearchChunk] = []
+        for model in api.list_models(search=query, limit=2):
+            text = " ".join(str(x) for x in [model.modelId, model.pipeline_tag, model.tags] if x)
+            chunks.append(
+                ResearchChunk(
+                    source="hf_hub_model",
+                    tool="search_hf_hub",
+                    title=model.modelId,
+                    url=f"https://huggingface.co/{model.modelId}",
+                    text=trim_text(text),
+                    metadata={"downloads": getattr(model, "downloads", None)},
+                )
+            )
+        for dataset in api.list_datasets(search=query, limit=2):
+            dataset_id = getattr(dataset, "id", "")
+            text = " ".join(str(x) for x in [dataset_id, getattr(dataset, "tags", None)] if x)
+            chunks.append(
+                ResearchChunk(
+                    source="hf_hub_dataset",
+                    tool="search_hf_hub",
+                    title=dataset_id,
+                    url=f"https://huggingface.co/datasets/{dataset_id}",
+                    text=trim_text(text),
+                    metadata={"downloads": getattr(dataset, "downloads", None)},
+                )
+            )
+        return chunks
+    try:
+        chunks = await asyncio.to_thread(_load)
+        ranked = bm25_rank(f"{query} {intent}", chunks, MAX_RETURNED_CHUNKS)
+        return ResearchResult("search_hf_hub", query, ranked, raw_count=len(chunks))
+    except Exception as exc:
+        return ResearchResult("search_hf_hub", query, error=str(exc))
+_TOOL_RUNNERS: dict[str, Callable[[str, str], Awaitable[ResearchResult]]] = {
+    "search_wikipedia": search_wikipedia,
+    "search_hf_papers": search_hf_papers,
+    "search_arxiv": search_arxiv,
+    "search_scholar": search_scholar,
+    "fetch_docs": fetch_docs,
+    "search_hf_hub": search_hf_hub,
+}
+_SKIP_SECTIONS = frozenset({
+    "references",
+    "external links",
+    "see also",
+    "further reading",
+    "notes",
+    "citations",
+    "bibliography",
+    "sources",
+})
+_DOC_URLS = {
+    "marimo": [
+        ("marimo CLI", "https://docs.marimo.io/cli/"),
+        ("marimo lint rules", "https://docs.marimo.io/guides/lint_rules/"),
+    ],
+    "manim": [
+        ("Manim quickstart", "https://docs.manim.community/en/stable/tutorials/quickstart.html"),
+        ("Manim reference", "https://docs.manim.community/en/stable/reference.html"),
+    ],
+    "numpy": [("NumPy user guide", "https://numpy.org/doc/stable/user/")],
+    "scipy": [("SciPy user guide", "https://docs.scipy.org/doc/scipy/tutorial/")],
+    "sklearn": [("scikit-learn user guide", "https://scikit-learn.org/stable/user_guide.html")],
+    "pandas": [("pandas user guide", "https://pandas.pydata.org/docs/user_guide/")],
+    "pytorch": [("PyTorch docs", "https://pytorch.org/docs/stable/index.html")],
+    "plotly": [("Plotly Python docs", "https://plotly.com/python/")],
+}
+def _flatten_wikipedia_sections(sections, max_depth: int = 2, depth: int = 0) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    for section in sections:
+        if section.title.lower() in _SKIP_SECTIONS:
+            continue
+        if section.text.strip():
+            result.append((section.title, section.text.strip()))
+        if depth < max_depth and section.sections:
+            result.extend(_flatten_wikipedia_sections(section.sections, max_depth, depth + 1))
+    return result
+def _xml_text(node, path: str, ns: dict[str, str]) -> str:
+    found = node.find(path, ns)
+    return found.text.strip() if found is not None and found.text else ""
+def _select_doc_urls(query: str) -> list[tuple[str, str]]:
+    lower = query.lower()
+    selected: list[tuple[str, str]] = []
+    for key, urls in _DOC_URLS.items():
+        if key in lower or key.replace("sklearn", "scikit-learn") in lower:
+            selected.extend(urls)
+    if not selected and any(term in lower for term in ("notebook", "animation", "plot", "chart", "lint")):
+        selected.extend(_DOC_URLS["marimo"])
+        selected.extend(_DOC_URLS["manim"])
+        selected.extend(_DOC_URLS["plotly"])
+    return selected
+def _extract_page_text(markup: str) -> str:
+    try:
+        import trafilatura
+        extracted = trafilatura.extract(markup, output_format="markdown")
+        if extracted:
+            return extracted
+    except Exception:
+        pass
+    text = re.sub(r"<(script|style).*?</\1>", " ", markup, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"<[^>]+>", " ", text)
+    return html.unescape(re.sub(r"\s+", " ", text))

research/types.py ADDED Viewed

	@@ -0,0 +1,62 @@

+"""Typed research results shared by exploration tools and rewards."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+@dataclass
+class ResearchChunk:
+    """A ranked passage returned by a research tool."""
+    source: str
+    tool: str
+    title: str
+    url: str
+    text: str
+    score: float = 0.0
+    rank: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    @property
+    def snippet(self) -> str:
+        return self.text
+@dataclass
+class ResearchResult:
+    """Structured response from a research tool."""
+    tool: str
+    query: str
+    chunks: list[ResearchChunk] = field(default_factory=list)
+    error: str = ""
+    raw_count: int = 0
+    @property
+    def ok(self) -> bool:
+        return not self.error and bool(self.chunks)
+    @property
+    def text(self) -> str:
+        return "\n\n".join(chunk.text for chunk in self.chunks)
+    @property
+    def sources(self) -> set[str]:
+        return {chunk.source for chunk in self.chunks}
+    def render(self) -> str:
+        """Render compact context for the agent."""
+        if self.error:
+            return f"{self.tool} error: {self.error}"
+        if not self.chunks:
+            return f"No results for {self.tool}: {self.query}"
+        parts = []
+        for chunk in self.chunks:
+            url = f"\nURL: {chunk.url}" if chunk.url else ""
+            parts.append(
+                f"[{chunk.rank}] {chunk.source}: {chunk.title}{url}\n{chunk.text}"
+            )
+        return "\n\n---\n\n".join(parts)

rewards/README.md CHANGED Viewed

@@ -1,107 +1,112 @@
 # Rewards
-Multi-component reward system for the two-phase explore → generate episode.
 ## Episode Flow
 ```
-reset() → [explore × 0..3] → generate × 1 → done
 ```
-Each step returns a per-step reward. The agent learns both *what* to explore and *when to stop*.
 ## Exploration Rewards (`exploration.py`)
-Per-step reward for each `explore` action. Gated by information need — once the agent has enough info, further exploration yields diminishing returns.
 | Component | Weight | Range | Description |
 |---|---|---|---|
-| `query_relevance` | 0.40 | 0–1 | Topic + keyword overlap with search query |
-| `result_novelty` | 0.30 | 0–1 | New words vs. already-seen content |
-| `research_breadth` | 0.10 | 0–1 | Number of sources gathered (target >= 2) |
-| `content_sufficiency` | 0.20 | 0–1 | Keyword coverage across task + research (gates reward) |
-| `step_cost` | -0.05 | flat | Per-step penalty — exploration must justify itself |
-**Gating mechanism**: `info_need = 1 - sufficiency`. Raw reward is scaled by `0.3 + 0.7 * info_need`, so high sufficiency → low reward for more exploration. This teaches the agent to stop when it has enough.
 ## Generation Rewards (`generation.py`)
-Single reward on the `generate` action that ends the episode.
 | Component | Weight | Range | Description |
 |---|---|---|---|
-| `code_valid` | 0.15 | 0/1 | AST parses without errors |
-| `code_runs` | 0.15 | 0/1 | Sandbox execution succeeds (marimo export / manim render) |
-| `coverage` | 0.15 | 0–1 | Fraction of task keywords in generated code |
-| `format_match` | 0.10 | 0.3/1.0 | Chosen format matches task's preferred format (1.0 if task has no preference) |
-| `structure` | 0.15* | 0–1 | Structural quality (cells/scenes, UI elements, viz) |
-| `narration` | 0.10* | 0–1 | Narration quality (manim only; words, scene markers) |
-| `context_usage` | 0.20 | 0–1 | Code references terms from exploration research |
-*For marimo format, narration weight (0.10) is redistributed to structure (→ 0.25 total).
-**Skip penalty**: Generating without any exploration incurs -0.1 penalty.
-## Search Sources (`sources.py`)
-All search calls are **async** (httpx + wikipediaapi.AsyncWikipedia). Content is retrieved at section/chunk level and ranked using **BM25** to surface the most relevant parts.
-| Source | Library | Use Case | Retrieval |
-|---|---|---|---|
-| HuggingFace Papers | httpx → `huggingface.co/api/papers/search` + `papers/{id}.md` | ML/AI topics (semantic search) | Search → top paper → read markdown → BM25 chunk ranking |
-| Wikipedia | `wikipediaapi.AsyncWikipedia` | Math, algorithms, general topics | Search → top page → section tree → BM25 section ranking |
-**Routing**: ML-related queries (detected by keyword heuristic) → HF Papers. Everything else → Wikipedia. Agent can override with prefix: `hf: query` or `wiki: query`. No explicit routing reward — bad routing leads to weak content → low novelty/relevance naturally.
-**Top 1 result** by default from each source, with top-3 BM25-ranked sections/chunks returned.
-## Sandbox (`sandbox.py`)
-| Check | Tool | Timeout |
-|---|---|---|
-| `ast_parses` | Python `ast.parse` | — |
-| `run_marimo` | `marimo export html` | 15s |
-| `run_manim` | `manim render -ql` | 30s |
-## LLM-as-Judge (`llm_judge.py`)
-**Eval-only** — not used in the training loop (too slow, non-deterministic for RL reward signals).
-### What it scores
-5 dimensions on a 1-10 scale, normalized to 0-1:
-| Dimension | Description |
-|---|---|
-| Clarity | Is the concept explained clearly for the target tier? |
-| Accuracy | Is the content technically correct? |
-| Engagement | Does the code create an engaging, interactive experience? |
-| Completeness | Does it cover the key aspects of the topic? |
-| Appropriateness | Is the depth appropriate for the audience tier? |
-### Configuration
-Set environment variables:
-- `JUDGE_API_URL` (required) — OpenAI-compatible endpoint (e.g. vLLM, ollama, OpenAI)
-- `JUDGE_API_KEY` (optional) — Bearer token for the API
-- `JUDGE_MODEL` (optional, default: `gpt-4o-mini`) — Model to use for judging
-### Usage
-```python
-from rewards.llm_judge import judge_explainability, is_available
-if is_available():
-    score, details = judge_explainability(
-        code="import marimo as mo\n...",
-        topic="Linear Regression",
-        tier="beginner",
-        fmt="marimo",
-    )
-    print(f"Explainability score: {score:.2f}")
-    print(f"Rationale: {details.get('rationale', '')}")
-```
-### What's used during training instead
-During GRPO training, the 12 heuristic reward components above provide the learning signal. They are deterministic, fast (<1ms per step), and decomposable for debugging. The LLM-as-judge is reserved for final evaluation and human-interpretable quality assessment.

 # Rewards
+Multi-component reward system for the explore -> generate -> repair episode.
 ## Episode Flow
 ```
+reset() --> [explore x 0..3] --> generate x 1 --> [repair x 0..1] --> done
 ```
+Each step returns a per-step reward. The agent learns what tool to use, what to retrieve, when to stop exploring, and how to repair broken artifacts.
 ## Exploration Rewards (`exploration.py`)
+Per-step reward for each `explore` action. Gated by information need -- once the agent has enough info, further exploration yields diminishing returns.
 | Component | Weight | Range | Description |
 |---|---|---|---|
+| `tool_choice` | 0.15 | 0-1 | Tool fits task difficulty and query intent |
+| `query_relevance` | 0.20 | 0-1 | Topic, keyword, and intent overlap |
+| `source_quality` | 0.20 | 0-1 | Retrieved chunks have useful metadata, content, and relevance |
+| `coverage_delta` | 0.20 | 0-1 | Newly covered missing concepts/keywords |
+| `result_novelty` | 0.15 | 0-1 | New normalized terms vs. previous context |
+| `diversity` | 0.10 | 0-1 | Useful new source/tool diversity |
+| `step_cost` | -0.05 | flat | Per-step penalty -- exploration must justify itself |
+**Gating mechanism**: `info_need = 1 - sufficiency`. Raw reward is scaled by `0.3 + 0.7 * info_need`, so high sufficiency -> low reward for more exploration. This teaches the agent to stop when it has enough.
 ## Generation Rewards (`generation.py`)
+Reward on `generate` and `repair` actions. Uses **multiplicative gates** instead of additive weights for code validity.
+### Gates (multiplicative)
+| Condition | Effect |
+|---|---|
+| Code doesn't parse (AST fails) | total = 0 |
+| Code doesn't execute | total = quality * 0.4 |
+| Code executes successfully | total = quality * 1.0 |
+### Quality components
 | Component | Weight | Range | Description |
 |---|---|---|---|
+| `coverage` | 0.20 | 0-1 | Fraction of task keywords in generated code |
+| `format_match` | 0.10 | 0.3/1.0 | Chosen format matches task's preferred format |
+| `structure` | 0.20* | 0-1 | Structural quality (cells/scenes, UI, viz, `marimo check`) |
+| `narration` | 0.15* | 0-1 | Narration quality (manim only; words, scene markers) |
+| `context_usage` | 0.35 | 0-1 | Code references terms from exploration research |
+*For marimo format, narration weight (0.15) is redistributed to structure (-> 0.35 total).
+### Marimo structure scoring
+Additive scoring for good patterns:
+- `import marimo` / `marimo.App()` / `@app.cell` count
+- UI elements (`mo.ui.*`, `mo.md(`, etc.)
+- Visualization libraries (`matplotlib`, `plotly`, etc.)
+- Tier-appropriate cell count
+Then `marimo check` CLI validates against 5 breaking rules (MB001-MB005). Per-violation penalties:
+| Rule | Penalty | What it catches |
+|---|---|---|
+| MB001 | -0.30 | Unparsable cells |
+| MB002 | -0.35 | Duplicate variable definitions across cells |
+| MB003 | -0.40 | Cycle dependencies between cells |
+| MB004 | -0.20 | Invalid setup cell dependencies |
+| MB005 | -0.25 | Syntax errors within cells |
+Clean code (no violations) gets +0.1 bonus.
+**Skip penalty**: Generating without any exploration incurs -0.1 penalty.
+### Repair scoring
+If generation fails lint/build validation, the observation enters `repair` and exposes structured errors. One repair attempt is allowed:
+| Condition | Effect |
+|---|---|
+| First generation succeeds | Full eligible generation reward; episode ends |
+| Repair succeeds | Base generation reward * 0.8, plus a small bonus for fixing prior error codes |
+| Repair fails | Base generation reward * 0.3; episode ends |
+| Code repeated unchanged | Additional penalty |
+## Search Sources (`sources.py`)
+All search calls are **async** (httpx + wikipediaapi.AsyncWikipedia). Content is retrieved at section/chunk level and ranked using **BM25** to surface the most relevant parts.
+| Source | Library | Use Case | Retrieval |
+|---|---|---|---|
+| Wikipedia | `wikipediaapi.AsyncWikipedia` | Fundamentals | Search 3-5 pages -> section tree -> global BM25 ranking |
+| HuggingFace Papers | httpx -> `huggingface.co/api/papers/search` | ML/AI research | Search 3-5 papers -> markdown chunks -> global BM25 ranking |
+| arXiv | httpx -> arXiv Atom API | Math, algorithms, ML, statistics papers | Search 3-5 papers -> abstracts -> global BM25 ranking |
+| Semantic Scholar | httpx -> Graph API | Scholarly metadata and abstracts | Search 3-5 papers -> abstracts -> global BM25 ranking |
+| Docs | httpx + trafilatura | API/library/code details | Fetch allowlisted docs -> chunk -> global BM25 ranking |
+| HF Hub | `huggingface_hub.HfApi` | Model cards, datasets, Spaces | Search Hub entities -> metadata/card snippets |
+Agents choose tools explicitly. Each tool fetches multiple candidates, chunks them, and returns the top 3-5 chunks globally. Optional small local embeddings can rerank the BM25 shortlist when `EMBEDDINGS_ENABLED=1`.
+## Sandbox (`sandbox.py`)
+Validation follows a fast-to-slow pipeline. Each stage gates the next.
+| Check | Tool | Timeout | Purpose |
+|---|---|---|---|
+| `ast_parses` | Python `ast.parse` | ~0ms | Catch syntax errors |
+| `check_marimo` | `marimo check --format json --select MB` | 8s | Catch structural violations |
+| `run_marimo` | `marimo export html` | 7s | Full execution test |
+| `run_manim` | `manim render -ql` | 30s | Full render test |
+`check_marimo` runs in ~100-200ms and catches MB001-MB005. If it fails, `run_marimo` is skipped (saves ~15s per broken submission).

rewards/__init__.py CHANGED Viewed

@@ -2,15 +2,10 @@
 from .exploration import compute_explore_reward
 from .generation import compute_generate_reward
-from .sandbox import run_marimo, run_manim
-from .sources import search, search_hf_papers, search_wikipedia
 __all__ = [
     "compute_explore_reward",
     "compute_generate_reward",
-    "run_marimo",
-    "run_manim",
     "search",
-    "search_hf_papers",
-    "search_wikipedia",
 ]

 from .exploration import compute_explore_reward
 from .generation import compute_generate_reward
+from .sources import search
 __all__ = [
     "compute_explore_reward",
     "compute_generate_reward",
     "search",
 ]

rewards/exploration.py CHANGED Viewed

@@ -1,51 +1,67 @@
-"""Reward components for the exploration phase.
-During exploration, the agent searches for papers/resources relevant to the
-task topic. Rewards measure query quality, result relevance, research breadth,
-and exploration efficiency (knowing when to stop).
-"""
 from __future__ import annotations
-def query_relevance(query: str, topic: str, keywords_csv: str) -> float:
-    """Score how relevant the search query is to the task (0-1)."""
     if not query or not query.strip():
         return 0.0
-    query_lower = query.strip().lower()
     score = 0.0
     if topic.lower() in query_lower:
-        score += 0.4
     keywords = [k.strip().lower() for k in keywords_csv.split(",") if k.strip()]
     if keywords:
         hits = sum(1 for kw in keywords if kw in query_lower)
-        score += 0.4 * (hits / len(keywords))
     if len(query_lower.split()) >= 3:
-        score += 0.2
-    return min(1.0, score)
-def result_novelty(
-    new_content: str, accumulated_context: list[str]
-) -> float:
-    """Score how much new information this result adds (0-1).
-    Penalises repeated searches that return content already seen.
-    """
     if not new_content or not new_content.strip():
         return 0.0
-    if not accumulated_context:
         return 1.0
-    new_words = set(new_content.lower().split())
     seen_words: set[str] = set()
-    for ctx in accumulated_context:
-        seen_words.update(ctx.lower().split())
     if not new_words:
         return 0.0
@@ -57,82 +73,169 @@ def result_novelty(
 def research_breadth(accumulated_context: list[str], min_sources: int = 2) -> float:
     """Score whether the agent gathered enough sources (0-1)."""
     n = len(accumulated_context)
-    if n >= min_sources:
-        return 1.0
-    return n / min_sources
 def content_sufficiency(
-    task_content: str,
-    keywords_csv: str,
-    accumulated_context: list[str],
 ) -> float:
-    """Measure how much of the task's keywords are already covered (0-1).
-    Combines the task's own content with accumulated research. When this is
-    high (>0.8), further exploration has diminishing value — the agent already
-    has enough information.
-    """
     keywords = [k.strip().lower() for k in keywords_csv.split(",") if k.strip()]
     if not keywords:
-        return 1.0  # no keywords to cover
-    # Build combined text from task content + all research so far
-    combined = task_content.lower()
     for ctx in accumulated_context:
-        combined += " " + ctx.lower()
-    hits = sum(1 for kw in keywords if kw in combined)
-    return hits / len(keywords)
-# -- Weights --
-W_QUERY = 0.40
-W_NOVELTY = 0.30
-W_BREADTH = 0.10
-W_SUFFICIENCY_GATE = 0.20  # gates reward by remaining information need
-# Flat cost per explore step — agent must expect enough gain to justify it
-STEP_COST = 0.05
 def compute_explore_reward(
     query: str,
-    result_text: str,
     topic: str,
     keywords_csv: str,
     task_content: str,
     accumulated_context: list[str],
 ) -> tuple[float, dict]:
-    """Compute per-step exploration reward. Returns (total, components).
-    Reward is gated by (1 - sufficiency): once the agent has enough info,
-    further exploration is nearly unrewarded. A flat step cost penalises
-    unnecessary searches.
-    """
-    q_rel = query_relevance(query, topic, keywords_csv)
-    novelty = result_novelty(result_text, accumulated_context)
-    breadth = research_breadth(accumulated_context)
     sufficiency = content_sufficiency(task_content, keywords_csv, accumulated_context)
-    # Information need: how much value exploration still has
     info_need = max(0.0, 1.0 - sufficiency)
-    # Raw reward from query + novelty + breadth
-    raw = W_QUERY * q_rel + W_NOVELTY * novelty + W_BREADTH * breadth
-    # Gate by info need: high sufficiency → low reward for exploring more
-    # Also add direct sufficiency-gate component so agent sees the signal
-    total = raw * (0.3 + 0.7 * info_need) + W_SUFFICIENCY_GATE * info_need - STEP_COST
     total = max(0.0, total)
     components = {
         "query_relevance": round(q_rel, 3),
         "result_novelty": round(novelty, 3),
-        "research_breadth": round(breadth, 3),
         "content_sufficiency": round(sufficiency, 3),
         "info_need": round(info_need, 3),
         "step_cost": STEP_COST,
         "explore_total": round(total, 4),
     }
     return total, components

+"""Reward components for the exploration phase."""
 from __future__ import annotations
+try:
+    from ..research.retrieval import tokenize
+    from ..research.types import ResearchResult
+except ImportError:  # pragma: no cover - supports direct test execution
+    from research.retrieval import tokenize
+    from research.types import ResearchResult
+# Weights. Keep the reward explainable: each component maps to a visible skill.
+W_TOOL_CHOICE = 0.15
+W_QUERY = 0.20
+W_SOURCE_QUALITY = 0.20
+W_COVERAGE_DELTA = 0.20
+W_NOVELTY = 0.15
+W_DIVERSITY = 0.10
+# Flat per-step penalty — the agent must expect enough gain to justify each search
+STEP_COST = 0.05
+# ---------------------------------------------------------------------------
+# Individual scorers
+# ---------------------------------------------------------------------------
+def query_relevance(query: str, topic: str, keywords_csv: str, intent: str = "") -> float:
+    """Score how relevant and specific the search query is to the task (0-1)."""
     if not query or not query.strip():
         return 0.0
+    query_lower = f"{query} {intent}".strip().lower()
     score = 0.0
     if topic.lower() in query_lower:
+        score += 0.35
     keywords = [k.strip().lower() for k in keywords_csv.split(",") if k.strip()]
     if keywords:
         hits = sum(1 for kw in keywords if kw in query_lower)
+        score += 0.35 * (hits / len(keywords))
     if len(query_lower.split()) >= 3:
+        score += 0.15
+    if any(term in query_lower for term in ("equation", "intuition", "visual", "example", "code")):
+        score += 0.15
+    return min(1.0, score)
+def result_novelty(new_content: str, previous_context: list[str]) -> float:
+    """Score how much new information this result adds (0-1)."""
     if not new_content or not new_content.strip():
         return 0.0
+    if not previous_context:
         return 1.0
+    new_words = set(tokenize(new_content))
     seen_words: set[str] = set()
+    for ctx in previous_context:
+        seen_words.update(tokenize(ctx))
     if not new_words:
         return 0.0
 def research_breadth(accumulated_context: list[str], min_sources: int = 2) -> float:
     """Score whether the agent gathered enough sources (0-1)."""
     n = len(accumulated_context)
+    return 1.0 if n >= min_sources else n / min_sources
 def content_sufficiency(
+    task_content: str, keywords_csv: str, accumulated_context: list[str],
 ) -> float:
+    """Fraction of task keywords covered in task content + research (0-1)."""
     keywords = [k.strip().lower() for k in keywords_csv.split(",") if k.strip()]
     if not keywords:
+        return 1.0
+    combined = _normalized_text(task_content)
     for ctx in accumulated_context:
+        combined += " " + _normalized_text(ctx)
+    return sum(1 for kw in keywords if _normalized_text(kw) in combined) / len(keywords)
+def tool_choice_score(tool: str, difficulty: str, query: str, intent: str = "") -> float:
+    """Reward selecting a tool that fits the task/source need."""
+    text = f"{query} {intent}".lower()
+    codeish = any(term in text for term in ("api", "code", "library", "plot", "chart", "lint", "marimo", "manim"))
+    paperish = any(term in text for term in ("paper", "research", "recent", "citation", "state of the art"))
+    hubish = any(term in text for term in ("model", "dataset", "space", "hugging face", "hf hub"))
+    if codeish:
+        return 1.0 if tool == "fetch_docs" else 0.65
+    if hubish:
+        return 1.0 if tool == "search_hf_hub" else 0.65
+    if difficulty == "hard" or paperish:
+        return 1.0 if tool in {"search_arxiv", "search_hf_papers", "search_scholar"} else 0.55
+    if difficulty == "medium":
+        return 1.0 if tool in {"search_wikipedia", "search_arxiv", "search_scholar"} else 0.75
+    return 1.0 if tool in {"search_wikipedia", "fetch_docs"} else 0.65
+def source_quality(result: ResearchResult) -> float:
+    """Measure whether retrieved chunks are usable, not whether the source is trusted."""
+    if result.error or not result.chunks:
+        return 0.0
+    scores = []
+    for chunk in result.chunks:
+        metadata = 0.0
+        if chunk.title:
+            metadata += 0.35
+        if chunk.url:
+            metadata += 0.35
+        if chunk.metadata:
+            metadata += 0.30
+        word_count = len(tokenize(chunk.text))
+        content = min(1.0, word_count / 80)
+        relevance = 1.0 if chunk.score > 0 else 0.5
+        scores.append(0.35 * metadata + 0.45 * content + 0.20 * relevance)
+    return min(1.0, sum(scores) / max(len(scores), 1))
+def coverage_delta(
+    keywords_csv: str,
+    task_content: str,
+    previous_context: list[str],
+    new_content: str,
+) -> float:
+    """Score newly covered keywords/concepts added by this result."""
+    keywords = [k.strip().lower() for k in keywords_csv.split(",") if k.strip()]
+    if not keywords:
+        return 1.0
+    before = _normalized_text(task_content + " " + " ".join(previous_context))
+    after = before + " " + _normalized_text(new_content)
+    missing_before = [kw for kw in keywords if _normalized_text(kw) not in before]
+    if not missing_before:
+        return 0.0
+    newly_covered = sum(1 for kw in missing_before if _normalized_text(kw) in after)
+    return newly_covered / len(missing_before)
+def diversity_score(tool: str, used_tools: set[str], result: ResearchResult) -> float:
+    """Reward useful source diversity without rewarding empty calls."""
+    if result.error or not result.chunks:
+        return 0.0
+    if tool not in used_tools:
+        return 1.0
+    unique_urls = {chunk.url for chunk in result.chunks if chunk.url}
+    return 0.5 if len(unique_urls) > 1 else 0.25
+# ---------------------------------------------------------------------------
+# Gating
+# ---------------------------------------------------------------------------
+def _exploration_gate(sufficiency: float) -> float:
+    """Multiplier based on information need.
+    High sufficiency → low multiplier (exploration has little value).
+    Low sufficiency  → high multiplier (exploration has high value).
+    Range: [0.3, 1.0].
+    """
+    info_need = max(0.0, 1.0 - sufficiency)
+    return 0.3 + 0.7 * info_need
+# ---------------------------------------------------------------------------
+# Main reward function
+# ---------------------------------------------------------------------------
 def compute_explore_reward(
     query: str,
+    tool: str,
+    intent: str,
+    result: ResearchResult,
     topic: str,
     keywords_csv: str,
     task_content: str,
+    difficulty: str,
+    previous_context: list[str],
     accumulated_context: list[str],
+    used_tools: set[str] | None = None,
 ) -> tuple[float, dict]:
+    """Compute per-step exploration reward. Returns (total, components)."""
+    used_tools = used_tools or set()
+    result_text = result.text
+    t_choice = tool_choice_score(tool, difficulty, query, intent)
+    q_rel = query_relevance(query, topic, keywords_csv, intent)
+    src_quality = source_quality(result)
+    delta = coverage_delta(keywords_csv, task_content, previous_context, result_text)
+    novelty = result_novelty(result_text, previous_context)
+    diversity = diversity_score(tool, used_tools, result)
     sufficiency = content_sufficiency(task_content, keywords_csv, accumulated_context)
     info_need = max(0.0, 1.0 - sufficiency)
+    raw = (
+        W_TOOL_CHOICE * t_choice
+        + W_QUERY * q_rel
+        + W_SOURCE_QUALITY * src_quality
+        + W_COVERAGE_DELTA * delta
+        + W_NOVELTY * novelty
+        + W_DIVERSITY * diversity
+    )
+    gate = _exploration_gate(sufficiency)
+    total = raw * gate + 0.10 * info_need - STEP_COST
     total = max(0.0, total)
     components = {
+        "tool_choice": round(t_choice, 3),
         "query_relevance": round(q_rel, 3),
+        "source_quality": round(src_quality, 3),
+        "coverage_delta": round(delta, 3),
         "result_novelty": round(novelty, 3),
+        "diversity": round(diversity, 3),
+        "research_breadth": round(research_breadth(accumulated_context), 3),
         "content_sufficiency": round(sufficiency, 3),
         "info_need": round(info_need, 3),
         "step_cost": STEP_COST,
         "explore_total": round(total, 4),
     }
     return total, components
+def _normalized_text(text: str) -> str:
+    return " ".join(tokenize(text))

rewards/generation.py CHANGED Viewed

@@ -2,19 +2,56 @@
 After exploration, the agent generates marimo/manim code. Rewards measure
 code quality, execution success, keyword coverage, format match, structural
-quality, and narration (manim only).
 """
 from __future__ import annotations
 from typing import TYPE_CHECKING
-from .sandbox import ast_parses
 if TYPE_CHECKING:
     from ..task_bank import Task
 # ---------------------------------------------------------------------------
 # Individual scorers
 # ---------------------------------------------------------------------------
@@ -28,8 +65,7 @@ def keyword_coverage(code: str, keywords_csv: str) -> float:
     if not keywords:
         return 0.0
     code_lower = code.lower()
-    hits = sum(1 for kw in keywords if kw in code_lower)
-    return hits / len(keywords)
 def format_match(chosen_format: str, task: Task) -> float:
@@ -43,8 +79,14 @@ def format_match(chosen_format: str, task: Task) -> float:
 def marimo_structure(code: str, task: Task) -> float:
-    """Score structural quality of a marimo notebook (0-1)."""
     score = 0.0
     if "import marimo" in code or "from marimo" in code:
         score += 0.2
     if "marimo.App" in code or "mo.App" in code:
@@ -54,22 +96,28 @@ def marimo_structure(code: str, task: Task) -> float:
         score += 0.2
     elif cell_count >= 1:
         score += 0.1
     ui_patterns = ["mo.ui.", "mo.md(", "mo.Html", "mo.accordion", "mo.callout"]
-    ui_hits = sum(1 for p in ui_patterns if p in code)
-    score += min(0.2, ui_hits * 0.05)
     viz_patterns = ["plt.", "px.", "altair", "matplotlib", "plotly", "mo.ui.slider"]
-    viz_hits = sum(1 for p in viz_patterns if p in code)
-    if task.data_available and viz_hits > 0:
-        score += 0.2
-    elif viz_hits > 0:
-        score += 0.1
-    if task.tier == "advanced" and cell_count >= 6:
-        score += 0.1
-    elif task.tier == "intermediate" and cell_count >= 4:
         score += 0.1
-    elif task.tier == "beginner" and cell_count >= 2:
         score += 0.1
-    return min(1.0, score)
 def manim_structure(code: str, task: Task) -> float:
@@ -83,37 +131,24 @@ def manim_structure(code: str, task: Task) -> float:
         score += 0.2
     if "def construct" in code:
         score += 0.1
     anim_patterns = [
-        "self.play(",
-        "self.wait(",
-        "Create(",
-        "FadeIn(",
-        "FadeOut(",
-        "Transform(",
-        "Write(",
-        "MoveToTarget",
-        "Indicate(",
         "ReplacementTransform(",
     ]
     anim_hits = sum(1 for p in anim_patterns if p in code)
     score += min(0.3, anim_hits * 0.05)
     math_patterns = ["MathTex(", "Tex(", "Axes(", "NumberPlane(", "Graph("]
-    math_hits = sum(1 for p in math_patterns if p in code)
-    if math_hits > 0:
-        score += 0.1
-    if task.tier == "advanced" and anim_hits >= 6:
-        score += 0.1
-    elif task.tier == "intermediate" and anim_hits >= 4:
-        score += 0.1
-    elif task.tier == "beginner" and anim_hits >= 2:
         score += 0.1
-    return min(1.0, score)
-def structure_score(code: str, fmt: str, task: Task) -> float:
-    if fmt == "marimo":
-        return marimo_structure(code, task)
-    return manim_structure(code, task)
 def narration_score(narration: str, fmt: str) -> float:
@@ -122,15 +157,14 @@ def narration_score(narration: str, fmt: str) -> float:
         return 1.0
     if not narration or not narration.strip():
         return 0.0
-    score = 0.0
     words = narration.split()
     if len(words) >= 30:
         score += 0.4
     elif len(words) >= 10:
         score += 0.2
     scene_markers = ["scene", "step", "first", "next", "then", "finally", "now"]
-    marker_hits = sum(1 for m in scene_markers if m in narration.lower())
-    score += min(0.3, marker_hits * 0.1)
     if len(words) >= 50:
         score += 0.3
     elif len(words) >= 20:
@@ -139,35 +173,25 @@ def narration_score(narration: str, fmt: str) -> float:
 def context_usage(code: str, accumulated_context: list[str]) -> float:
-    """Score whether the generated code incorporates research findings (0-1).
-    Higher score if the code references terms found during exploration.
-    """
     if not accumulated_context:
-        return 0.5  # no exploration context to compare against
     context_words: set[str] = set()
     for ctx in accumulated_context:
-        context_words.update(
-            w.lower() for w in ctx.split() if len(w) > 3
-        )
     if not context_words:
         return 0.5
-    code_words = set(w.lower() for w in code.split() if len(w) > 3)
     overlap = code_words & context_words
     return min(1.0, len(overlap) / max(len(context_words), 1) * 5)
-# -- Weights for generation reward --
-W_CODE_VALID = 0.15
-W_CODE_RUNS = 0.15
-W_COVERAGE = 0.15
-W_FORMAT = 0.10
-W_STRUCTURE = 0.15
-W_NARRATION = 0.10
-W_CONTEXT_USE = 0.20  # rewards using exploration findings
 def compute_generate_reward(
@@ -178,33 +202,36 @@ def compute_generate_reward(
     exec_success: bool,
     accumulated_context: list[str],
 ) -> tuple[float, dict]:
-    """Compute the generation-phase reward. Returns (total, components)."""
     c_valid = 1.0 if ast_parses(code) else 0.0
     c_runs = 1.0 if exec_success else 0.0
     c_coverage = keyword_coverage(code, task.keywords)
     c_format = format_match(fmt, task)
-    c_struct = structure_score(code, fmt, task)
     c_narr = narration_score(narration, fmt)
     c_ctx = context_usage(code, accumulated_context)
-    # Redistribute narration weight to structure for marimo
-    if fmt == "marimo":
-        w_struct = W_STRUCTURE + W_NARRATION
-        w_narr = 0.0
-    else:
-        w_struct = W_STRUCTURE
-        w_narr = W_NARRATION
-    total = (
-        W_CODE_VALID * c_valid
-        + W_CODE_RUNS * c_runs
-        + W_COVERAGE * c_coverage
-        + W_FORMAT * c_format
-        + w_struct * c_struct
-        + w_narr * c_narr
-        + W_CONTEXT_USE * c_ctx
     )
     components = {
         "code_valid": round(c_valid, 3),
         "code_runs": round(c_runs, 3),
@@ -216,3 +243,44 @@ def compute_generate_reward(
         "generate_total": round(total, 4),
     }
     return total, components

 After exploration, the agent generates marimo/manim code. Rewards measure
 code quality, execution success, keyword coverage, format match, structural
+quality, narration (manim only), and context usage.
+Scoring model:
+  quality = weighted sum of (coverage, format, structure, narration, context)
+  total   = quality × gate
+Gates (multiplicative):
+  - code doesn't parse  → total = 0
+  - code doesn't run    → total = quality × 0.4
+  - code runs           → total = quality × 1.0
 """
 from __future__ import annotations
+import hashlib
+import re
 from typing import TYPE_CHECKING
+from .sandbox import ast_parses, check_marimo
 if TYPE_CHECKING:
     from ..task_bank import Task
+# ---------------------------------------------------------------------------
+# Component weights
+# ---------------------------------------------------------------------------
+_WEIGHTS = {
+    "coverage": 0.20,
+    "format": 0.10,
+    "structure": 0.20,
+    "narration": 0.15,
+    "context": 0.35,
+}
+GATE_RUNS_FAIL = 0.4  # quality multiplier when code doesn't execute
+def _get_weights(fmt: str) -> dict[str, float]:
+    """Return component weights for the given format.
+    Marimo has no narration — its weight is redistributed to structure.
+    """
+    w = dict(_WEIGHTS)
+    if fmt == "marimo":
+        w["structure"] += w.pop("narration")
+    return w
 # ---------------------------------------------------------------------------
 # Individual scorers
 # ---------------------------------------------------------------------------
     if not keywords:
         return 0.0
     code_lower = code.lower()
+    return sum(1 for kw in keywords if kw in code_lower) / len(keywords)
 def format_match(chosen_format: str, task: Task) -> float:
 def marimo_structure(code: str, task: Task) -> float:
+    """Score structural quality of a marimo notebook (0-1).
+    Additive scoring for good patterns, penalties from ``marimo check``
+    for breaking violations (duplicate defs, cycles, etc.).
+    """
     score = 0.0
+    # Positive signals
     if "import marimo" in code or "from marimo" in code:
         score += 0.2
     if "marimo.App" in code or "mo.App" in code:
         score += 0.2
     elif cell_count >= 1:
         score += 0.1
     ui_patterns = ["mo.ui.", "mo.md(", "mo.Html", "mo.accordion", "mo.callout"]
+    score += min(0.2, sum(0.05 for p in ui_patterns if p in code))
     viz_patterns = ["plt.", "px.", "altair", "matplotlib", "plotly", "mo.ui.slider"]
+    if any(p in code for p in viz_patterns):
+        score += 0.2 if task.data_available else 0.1
+    tier_thresholds = {"advanced": 6, "intermediate": 4, "beginner": 2}
+    if cell_count >= tier_thresholds.get(task.tier, 2):
         score += 0.1
+    # Marimo check: penalize breaking violations, bonus for clean code
+    passed, _, violations = check_marimo(code)
+    if passed:
         score += 0.1
+    else:
+        penalty = {"MB002": 0.35, "MB003": 0.4, "MB005": 0.25, "MB001": 0.3, "MB004": 0.2}
+        for v in violations:
+            score -= penalty.get(v, 0.15)
+    return max(0.0, min(1.0, score))
 def manim_structure(code: str, task: Task) -> float:
         score += 0.2
     if "def construct" in code:
         score += 0.1
     anim_patterns = [
+        "self.play(", "self.wait(", "Create(", "FadeIn(", "FadeOut(",
+        "Transform(", "Write(", "MoveToTarget", "Indicate(",
         "ReplacementTransform(",
     ]
     anim_hits = sum(1 for p in anim_patterns if p in code)
     score += min(0.3, anim_hits * 0.05)
     math_patterns = ["MathTex(", "Tex(", "Axes(", "NumberPlane(", "Graph("]
+    if any(p in code for p in math_patterns):
         score += 0.1
+    tier_thresholds = {"advanced": 6, "intermediate": 4, "beginner": 2}
+    if anim_hits >= tier_thresholds.get(task.tier, 2):
+        score += 0.1
+    return min(1.0, score)
 def narration_score(narration: str, fmt: str) -> float:
         return 1.0
     if not narration or not narration.strip():
         return 0.0
     words = narration.split()
+    score = 0.0
     if len(words) >= 30:
         score += 0.4
     elif len(words) >= 10:
         score += 0.2
     scene_markers = ["scene", "step", "first", "next", "then", "finally", "now"]
+    score += min(0.3, sum(0.1 for m in scene_markers if m in narration.lower()))
     if len(words) >= 50:
         score += 0.3
     elif len(words) >= 20:
 def context_usage(code: str, accumulated_context: list[str]) -> float:
+    """Score whether the generated code incorporates research findings (0-1)."""
     if not accumulated_context:
+        return 0.5
     context_words: set[str] = set()
     for ctx in accumulated_context:
+        context_words.update(_tokens(ctx))
     if not context_words:
         return 0.5
+    code_words = set(_tokens(code))
     overlap = code_words & context_words
     return min(1.0, len(overlap) / max(len(context_words), 1) * 5)
+# ---------------------------------------------------------------------------
+# Main reward function
+# ---------------------------------------------------------------------------
 def compute_generate_reward(
     exec_success: bool,
     accumulated_context: list[str],
 ) -> tuple[float, dict]:
+    """Compute the generation-phase reward. Returns (total, components).
+    ``code_valid`` and ``code_runs`` act as gates: broken code gets the
+    quality score heavily discounted rather than losing a single 0.15 component.
+    """
     c_valid = 1.0 if ast_parses(code) else 0.0
     c_runs = 1.0 if exec_success else 0.0
     c_coverage = keyword_coverage(code, task.keywords)
     c_format = format_match(fmt, task)
+    c_struct = (marimo_structure if fmt == "marimo" else manim_structure)(code, task)
     c_narr = narration_score(narration, fmt)
     c_ctx = context_usage(code, accumulated_context)
+    w = _get_weights(fmt)
+    quality = (
+        w["coverage"] * c_coverage
+        + w["format"] * c_format
+        + w["structure"] * c_struct
+        + w.get("narration", 0.0) * c_narr
+        + w["context"] * c_ctx
     )
+    # Apply gates
+    if c_valid == 0.0:
+        total = 0.0
+    elif c_runs == 0.0:
+        total = quality * GATE_RUNS_FAIL
+    else:
+        total = quality
     components = {
         "code_valid": round(c_valid, 3),
         "code_runs": round(c_runs, 3),
         "generate_total": round(total, 4),
     }
     return total, components
+def adjust_repair_reward(
+    base_reward: float,
+    *,
+    repair_success: bool,
+    previous_error_codes: list[str],
+    new_error_codes: list[str],
+    previous_code: str,
+    repaired_code: str,
+) -> tuple[float, dict]:
+    """Discount repaired code but reward fixing the specific prior failure."""
+    repeated = _fingerprint(previous_code) == _fingerprint(repaired_code)
+    fixed_prior = bool(previous_error_codes) and not (
+        set(previous_error_codes) & set(new_error_codes)
+    )
+    if repair_success:
+        reward = base_reward * 0.8 + (0.1 if fixed_prior else 0.0)
+    else:
+        reward = base_reward * 0.3
+    if repeated:
+        reward -= 0.15
+    reward = max(0.0, min(1.0, reward))
+    return reward, {
+        "repair_success": 1.0 if repair_success else 0.0,
+        "fixed_prior_errors": 1.0 if fixed_prior else 0.0,
+        "repeated_code": 1.0 if repeated else 0.0,
+        "repair_total": round(reward, 4),
+    }
+def _tokens(text: str) -> list[str]:
+    return [w for w in re.findall(r"\w+", text.lower()) if len(w) > 3]
+def _fingerprint(code: str) -> str:
+    normalized = re.sub(r"\s+", "", code)
+    return hashlib.sha256(normalized.encode()).hexdigest()

rewards/sandbox.py CHANGED Viewed

@@ -1,11 +1,45 @@
 """Sandbox execution for marimo and manim code."""
 import ast
 import subprocess
 import tempfile
 from pathlib import Path
 def ast_parses(code: str) -> bool:
     """Check whether the code is valid Python (AST-parseable)."""
     try:
@@ -34,19 +68,78 @@ def extract_scene_class(code: str) -> str | None:
     return None
-def run_marimo(code: str, timeout: int = 15) -> tuple[bool, str]:
-    """Try exporting a marimo notebook to HTML. Returns (success, message)."""
     with tempfile.NamedTemporaryFile(suffix=".py", mode="w", delete=False) as f:
         f.write(code)
         f.flush()
         tmp = f.name
     try:
         result = subprocess.run(
-            ["marimo", "export", "html", tmp],
             capture_output=True,
             text=True,
             timeout=timeout,
         )
         if result.returncode == 0:
             return True, "marimo export succeeded"
         return False, result.stderr[:500]
@@ -81,3 +174,68 @@ def run_manim(code: str, timeout: int = 30) -> tuple[bool, str]:
             return False, "manim not installed"
         except subprocess.TimeoutExpired:
             return False, "manim render timed out"

 """Sandbox execution for marimo and manim code."""
 import ast
+import json
 import subprocess
 import tempfile
+from dataclasses import dataclass, field
+from typing import Any
 from pathlib import Path
+@dataclass
+class SandboxResult:
+    """Structured lint/build result returned to the environment."""
+    fmt: str
+    parses: bool
+    check_passed: bool
+    exec_success: bool
+    message: str
+    errors: list[dict[str, Any]] = field(default_factory=list)
+    @property
+    def error_codes(self) -> list[str]:
+        codes: list[str] = []
+        for error in self.errors:
+            code = error.get("code")
+            if code and code not in codes:
+                codes.append(str(code))
+        return codes
+    def render_errors(self) -> str:
+        if not self.errors:
+            return self.message
+        lines = []
+        for error in self.errors:
+            code = error.get("code", "error")
+            message = error.get("message", "")
+            lines.append(f"{code}: {message}".strip())
+        return "\n".join(lines)
 def ast_parses(code: str) -> bool:
     """Check whether the code is valid Python (AST-parseable)."""
     try:
     return None
+# ---------------------------------------------------------------------------
+# Marimo validation via `marimo check` CLI
+# ---------------------------------------------------------------------------
+def check_marimo(code: str, timeout: int = 8) -> tuple[bool, str, list[str]]:
+    """Run ``marimo check`` on code. Returns (passed, message, rule_codes).
+    Catches breaking rules MB001-MB005: unparsable cells, duplicate
+    definitions, cycle dependencies, setup cell issues, syntax errors.
+    Runs in ~100-200ms — much faster than full ``marimo export html``.
+    """
     with tempfile.NamedTemporaryFile(suffix=".py", mode="w", delete=False) as f:
         f.write(code)
         f.flush()
         tmp = f.name
     try:
         result = subprocess.run(
+            ["marimo", "check", "--format", "json", "--select", "MB", tmp],
             capture_output=True,
             text=True,
             timeout=timeout,
         )
+        data = json.loads(result.stdout)
+        issues = data.get("issues", [])
+        if not issues:
+            return True, "marimo check passed", []
+        codes = list({i["code"] for i in issues})
+        first_msg = issues[0].get("message", "unknown error")
+        fix_hint = issues[0].get("fix", "")
+        msg = f"{first_msg}\n{fix_hint}".strip() if fix_hint else first_msg
+        return False, msg, codes
+    except FileNotFoundError:
+        return False, "marimo not installed", ["MARIMO_MISSING"]
+    except subprocess.TimeoutExpired:
+        return False, "marimo check timed out", ["MARIMO_TIMEOUT"]
+    except (json.JSONDecodeError, KeyError):
+        return False, "marimo check output unparseable", ["MARIMO_CHECK_PARSE"]
+    finally:
+        Path(tmp).unlink(missing_ok=True)
+# ---------------------------------------------------------------------------
+# Full execution
+# ---------------------------------------------------------------------------
+def run_marimo(code: str, timeout: int = 15, *, skip_check: bool = False) -> tuple[bool, str]:
+    """Export a marimo notebook to HTML, optionally running static checks first.
+    Runs ``marimo check`` first (fast static analysis). If that fails,
+    returns immediately without the expensive export step.
+    """
+    check_timeout = min(8, max(1, timeout // 2))
+    if not skip_check:
+        passed, msg, _violations = check_marimo(code, timeout=check_timeout)
+        if not passed:
+            return False, msg
+    with tempfile.NamedTemporaryFile(suffix=".py", mode="w", delete=False) as f:
+        f.write(code)
+        f.flush()
+        tmp = f.name
+    try:
+        result = subprocess.run(
+            ["marimo", "export", "html", tmp],
+            capture_output=True,
+            text=True,
+            timeout=max(1, timeout - check_timeout),
+        )
         if result.returncode == 0:
             return True, "marimo export succeeded"
         return False, result.stderr[:500]
             return False, "manim not installed"
         except subprocess.TimeoutExpired:
             return False, "manim render timed out"
+def validate_code(fmt: str, code: str) -> SandboxResult:
+    """Validate code and return parseable feedback for generation/repair."""
+    if not ast_parses(code):
+        return SandboxResult(
+            fmt=fmt,
+            parses=False,
+            check_passed=False,
+            exec_success=False,
+            message="Code has syntax errors and cannot be parsed.",
+            errors=[{"code": "PY_SYNTAX", "message": "Code has syntax errors."}],
+        )
+    if fmt == "marimo":
+        check_passed, check_msg, codes = check_marimo(code)
+        if not check_passed:
+            return SandboxResult(
+                fmt=fmt,
+                parses=True,
+                check_passed=False,
+                exec_success=False,
+                message=check_msg,
+                errors=[{"code": code, "message": check_msg} for code in codes],
+            )
+        exec_success, exec_msg = run_marimo(code, skip_check=True)
+        return SandboxResult(
+            fmt=fmt,
+            parses=True,
+            check_passed=True,
+            exec_success=exec_success,
+            message=exec_msg,
+            errors=[] if exec_success else [{"code": "MARIMO_EXPORT", "message": exec_msg}],
+        )
+    if fmt == "manim":
+        scene = extract_scene_class(code)
+        if scene is None:
+            return SandboxResult(
+                fmt=fmt,
+                parses=True,
+                check_passed=False,
+                exec_success=False,
+                message="No Scene subclass found in code",
+                errors=[{"code": "MANIM_NO_SCENE", "message": "No Scene subclass found."}],
+            )
+        exec_success, exec_msg = run_manim(code)
+        return SandboxResult(
+            fmt=fmt,
+            parses=True,
+            check_passed=True,
+            exec_success=exec_success,
+            message=exec_msg,
+            errors=[] if exec_success else [{"code": "MANIM_RENDER", "message": exec_msg}],
+        )
+    return SandboxResult(
+        fmt=fmt,
+        parses=True,
+        check_passed=False,
+        exec_success=False,
+        message=f"Unknown format: {fmt}",
+        errors=[{"code": "UNKNOWN_FORMAT", "message": f"Unknown format: {fmt}"}],
+    )

rewards/sources.py CHANGED Viewed

@@ -1,321 +1,34 @@
-"""Async search sources for the exploration phase.
-Two backends:
-  - HuggingFace Papers: ML-focused semantic search via huggingface_hub
-  - Wikipedia: general topics via wikipediaapi (section-level + BM25 RAG)
-The agent's query is routed to the most appropriate source, or the agent
-can specify a source prefix (e.g. "wiki: merge sort", "hf: attention").
-All external calls use async I/O (httpx / wikipediaapi.AsyncWikipedia).
 """
 from __future__ import annotations
-import math
-import re
-from collections import Counter
-import httpx
-import wikipediaapi
-HF_MAX_RESULTS = 1
-WIKI_TOP_SECTIONS = 3
-# BM25 parameters
-_BM25_K1 = 1.5
-_BM25_B = 0.75
-# ---------------------------------------------------------------------------
-# BM25 scoring (pure Python, no external deps)
-# ---------------------------------------------------------------------------
-_STOP_WORDS = {
-    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
-    "have", "has", "had", "do", "does", "did", "will", "would", "could",
-    "should", "may", "might", "shall", "can", "need", "dare", "ought",
-    "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
-    "into", "through", "during", "before", "after", "and", "but", "or",
-    "not", "no", "nor", "so", "yet", "both", "either", "neither",
-    "this", "that", "these", "those", "it", "its", "he", "she", "they",
-}
-def _tokenize(text: str) -> list[str]:
-    """Lowercase alphanumeric tokenization, stop words removed."""
-    return [w for w in re.findall(r"\w+", text.lower()) if w not in _STOP_WORDS and len(w) > 1]
-def _bm25_rank(
-    query: str, documents: list[tuple[str, str]], top_k: int = 3
-) -> list[tuple[float, str, str]]:
-    """Rank (title, text) documents against query using BM25.
-    Returns top_k results sorted by score descending.
-    """
-    if not documents:
-        return []
-    query_terms = _tokenize(query)
-    if not query_terms:
-        return [(0.0, t, txt) for t, txt in documents[:top_k]]
-    # Precompute document token stats
-    doc_tokens = [_tokenize(f"{title} {text}") for title, text in documents]
-    doc_lengths = [len(t) for t in doc_tokens]
-    avgdl = sum(doc_lengths) / max(len(doc_lengths), 1)
-    n_docs = len(documents)
-    # Document frequency per query term
-    df: dict[str, int] = {}
-    for term in set(query_terms):
-        df[term] = sum(1 for tokens in doc_tokens if term in tokens)
-    # Score each document
-    scored: list[tuple[float, str, str]] = []
-    for i, (title, text) in enumerate(documents):
-        tf_counts = Counter(doc_tokens[i])
-        dl = doc_lengths[i]
-        score = 0.0
-        for term in query_terms:
-            if term not in df or df[term] == 0:
-                continue
-            idf = math.log((n_docs - df[term] + 0.5) / (df[term] + 0.5) + 1.0)
-            tf = tf_counts.get(term, 0)
-            numerator = tf * (_BM25_K1 + 1)
-            denominator = tf + _BM25_K1 * (1 - _BM25_B + _BM25_B * dl / max(avgdl, 1))
-            score += idf * numerator / denominator
-        scored.append((score, title, text))
-    scored.sort(key=lambda x: x[0], reverse=True)
-    return scored[:top_k]
-# ---------------------------------------------------------------------------
-# Wikipedia section flattening
-# ---------------------------------------------------------------------------
-_SKIP_SECTIONS = {
-    "references", "external links", "see also", "further reading",
-    "notes", "citations", "bibliography", "sources",
-}
-def _flatten_sections(
-    sections: list[wikipediaapi.WikipediaPageSection],
-    max_depth: int = 2,
-    _depth: int = 0,
-) -> list[tuple[str, str]]:
-    """Flatten Wikipedia section tree into (title, text) pairs."""
-    result: list[tuple[str, str]] = []
-    for section in sections:
-        if section.title.lower() in _SKIP_SECTIONS:
-            continue
-        if section.text.strip():
-            result.append((section.title, section.text.strip()))
-        if _depth < max_depth and section.sections:
-            result.extend(
-                _flatten_sections(section.sections, max_depth, _depth + 1)
-            )
-    return result
-# ---------------------------------------------------------------------------
-# Wikipedia (async, section-level BM25)
-# ---------------------------------------------------------------------------
-async def search_wikipedia(
-    query: str, top_sections: int = WIKI_TOP_SECTIONS
-) -> str:
-    """Search Wikipedia and return the most relevant sections via BM25.
-    Flow: search(query) -> top page -> get sections -> BM25 rank -> top-k.
-    """
-    try:
-        wiki = wikipediaapi.AsyncWikipedia(
-            user_agent="ExplainerEnv/1.0 (hackathon project)",
-            language="en",
-        )
-        # Search for the top page
-        search_results = await wiki.search(query, limit=1)
-        if not search_results or not search_results.pages:
-            return f"No Wikipedia results for: {query}"
-        # pages is a dict keyed by title
-        title = next(iter(search_results.pages))
-        page = wiki.page(title)
-        # Check page exists
-        exists = await page.exists()
-        if not exists:
-            return f"No Wikipedia article found for: {query}"
-        # Get summary + sections
-        summary = await page.summary
-        sections = await page.sections
-        # Build document list: summary as first doc, then flattened sections
-        docs: list[tuple[str, str]] = []
-        if summary:
-            docs.append((title, summary))
-        docs.extend(_flatten_sections(sections))
-        if not docs:
-            return f"Wikipedia article '{title}' has no content."
-        # BM25 rank sections against query
-        ranked = _bm25_rank(query, docs, top_k=top_sections)
-        parts = []
-        for score, sec_title, sec_text in ranked:
-            # Truncate long sections to keep total size reasonable
-            trimmed = sec_text[:800] if len(sec_text) > 800 else sec_text
-            parts.append(f"## {sec_title}\n{trimmed}")
-        return f"Wikipedia: {title}\n\n" + "\n\n---\n\n".join(parts)
-    except Exception as e:
-        return f"Wikipedia search error: {e}"
-# ---------------------------------------------------------------------------
-# HuggingFace Papers (async, httpx + read_paper)
-# ---------------------------------------------------------------------------
-async def search_hf_papers(
-    query: str, max_results: int = HF_MAX_RESULTS
 ) -> str:
-    """Search HuggingFace Papers (semantic search) and read top result's content.
-    Flow: search(query) -> top paper ID -> read_paper(id) -> BM25 chunk.
-    """
-    try:
-        async with httpx.AsyncClient(timeout=15.0) as client:
-            # 1. Search for papers
-            resp = await client.get(
-                "https://huggingface.co/api/papers/search",
-                params={"q": query, "limit": max_results},
-                headers={"User-Agent": "ExplainerEnv/1.0"},
-            )
-            resp.raise_for_status()
-            papers = resp.json()
-            if not papers:
-                return f"No HF papers found for: {query}"
-            paper = papers[0]
-            paper_id = paper.get("id", "")
-            title = paper.get("title", "Untitled")
-            summary = paper.get("summary", "")
-            if not paper_id:
-                # No paper ID — return just the search result
-                return f"Title: {title}\nAbstract: {summary[:600]}"
-            # 2. Read paper markdown content
-            md_resp = await client.get(
-                f"https://huggingface.co/papers/{paper_id}.md",
-                headers={"User-Agent": "ExplainerEnv/1.0"},
-                follow_redirects=True,
-            )
-            if md_resp.status_code == 200 and md_resp.text.strip():
-                md_content = md_resp.text
-                # Chunk markdown by headings
-                chunks = _chunk_markdown(md_content)
-                if chunks:
-                    ranked = _bm25_rank(query, chunks, top_k=3)
-                    parts = [f"Title: {title}\nPaper ID: {paper_id}\n"]
-                    for _score, sec_title, sec_text in ranked:
-                        trimmed = sec_text[:800] if len(sec_text) > 800 else sec_text
-                        parts.append(f"## {sec_title}\n{trimmed}")
-                    return "\n\n---\n\n".join(parts)
-            # Fallback: return abstract only
-            return (
-                f"Title: {title}\n"
-                f"Paper ID: {paper_id}\n"
-                f"Abstract: {summary[:600]}"
-            )
-    except Exception as e:
-        return f"HF Papers search error: {e}"
-def _chunk_markdown(md_text: str) -> list[tuple[str, str]]:
-    """Split markdown text into (heading, body) chunks."""
-    chunks: list[tuple[str, str]] = []
-    current_heading = "Introduction"
-    current_lines: list[str] = []
-    for line in md_text.split("\n"):
-        if line.startswith("#"):
-            # Save previous chunk
-            body = "\n".join(current_lines).strip()
-            if body:
-                chunks.append((current_heading, body))
-            # Start new chunk
-            current_heading = line.lstrip("#").strip() or "Section"
-            current_lines = []
-        else:
-            current_lines.append(line)
-    # Save last chunk
-    body = "\n".join(current_lines).strip()
-    if body:
-        chunks.append((current_heading, body))
-    return chunks
-# ---------------------------------------------------------------------------
-# Router
-# ---------------------------------------------------------------------------
-# Keywords that suggest ML/AI topics (used when category is not available)
-_ML_KEYWORDS = {
-    "neural", "network", "transformer", "attention", "embedding", "gradient",
-    "backpropagation", "cnn", "rnn", "lstm", "gpt", "bert", "diffusion",
-    "reinforcement", "generative", "discriminative", "autoencoder", "vae",
-    "gan", "fine-tuning", "pretraining", "tokenizer", "llm", "rlhf",
-    "classification", "regression", "clustering", "deep learning",
-    "machine learning", "optimization", "sgd", "adam", "batch normalization",
-}
-def _is_ml_topic(query: str) -> bool:
-    """Heuristic: does the query look like an ML/AI topic?"""
-    query_lower = query.lower()
-    return any(kw in query_lower for kw in _ML_KEYWORDS)
-async def search(query: str, category_hint: str = "") -> str:
-    """Route a search query to the best source.
-    The agent can override by prefixing the query:
-      - "hf: attention mechanism"    -> HF Papers only
-      - "wiki: merge sort"           -> Wikipedia only
-    Otherwise, uses keyword heuristic to route ML topics to HF Papers
-    and everything else to Wikipedia.
-    """
-    query = query.strip()
-    # Explicit source prefix
-    lower = query.lower()
-    if lower.startswith("hf:"):
-        return await search_hf_papers(query[3:].strip())
-    if lower.startswith("wiki:"):
-        return await search_wikipedia(query[5:].strip())
-    # Auto-route based on keyword heuristic
-    if _is_ml_topic(query) or _is_ml_topic(category_hint):
-        hf = await search_hf_papers(query)
-        if "error" in hf.lower() or "no hf papers" in hf.lower():
-            return await search_wikipedia(query)
-        return hf
-    # Default: Wikipedia
-    return await search_wikipedia(query)

+"""Compatibility wrapper for the structured research tool layer.
+New code should use ``explainer_env.research.run_research_tool`` directly.
 """
 from __future__ import annotations
+try:
+    from ..research import run_research_tool
+except ImportError:  # pragma: no cover - supports direct test execution
+    from research import run_research_tool
+async def search(
+    query: str,
+    category_hint: str = "",
+    difficulty: str = "easy",
+    tool: str | None = None,
 ) -> str:
+    """Run a research tool and render its result as text."""
+    selected_tool = tool or _default_tool(query, category_hint, difficulty)
+    result = await run_research_tool(selected_tool, query, category_hint)
+    return result.render()
+def _default_tool(query: str, category_hint: str, difficulty: str) -> str:
+    text = f"{query} {category_hint}".lower()
+    if any(term in text for term in ("api", "code", "plot", "marimo", "manim")):
+        return "fetch_docs"
+    if any(term in text for term in ("model", "dataset", "hugging face", "hf hub")):
+        return "search_hf_hub"
+    if difficulty == "hard":
+        return "search_arxiv"
+    return "search_wikipedia"

server/app.py CHANGED Viewed

@@ -58,7 +58,7 @@ def main(host: str = "0.0.0.0", port: int = 8000):
     This function enables running the server without Docker:
         uv run --project . server
         uv run --project . server --port 8001
-        python -m openspiel_env.server.app
     Args:
         host: Host address to bind to (default: "0.0.0.0")

     This function enables running the server without Docker:
         uv run --project . server
         uv run --project . server --port 8001
+        python -m explainer_env.server.app
     Args:
         host: Host address to bind to (default: "0.0.0.0")

server/explainer_env_environment.py CHANGED Viewed

@@ -1,10 +1,11 @@
 """
-Research → Interactive Explainer Environment (multi-step, async).
 Episode flow:
   1. reset() → agent gets a topic + tier
-  2. step(explore) × 1..MAX_EXPLORE → agent searches, gets papers back
-  3. step(generate) × 1 → agent produces marimo/manim code → episode ends
 Each step returns a per-step reward. The final generate step also includes
 a generation reward that accounts for how well the code uses the research.
@@ -20,22 +21,22 @@ from openenv.core.env_server.interfaces import Environment
 from openenv.core.env_server.types import State
 try:
     from ..models import ExplainerAction, ExplainerObservation
     from ..rewards.exploration import compute_explore_reward
-    from ..rewards.generation import compute_generate_reward
-    from ..rewards.sandbox import ast_parses, run_manim, run_marimo
-    from ..rewards.sources import search as search_sources
     from ..task_bank import ALL_TASKS, EASY_TASKS, HARD_TASKS, MEDIUM_TASKS, Task
 except ImportError:
     from models import ExplainerAction, ExplainerObservation
     from rewards.exploration import compute_explore_reward
-    from rewards.generation import compute_generate_reward
-    from rewards.sandbox import ast_parses, run_manim, run_marimo
-    from rewards.sources import search as search_sources
     from task_bank import ALL_TASKS, EASY_TASKS, HARD_TASKS, MEDIUM_TASKS, Task
-MAX_EXPLORE_STEPS = 3
 class ExplainerEnvironment(Environment):
     """
@@ -56,7 +57,16 @@ class ExplainerEnvironment(Environment):
         self._current_task: Task | None = None
         self._difficulty_pool: list[Task] = EASY_TASKS
         self._accumulated_context: list[str] = []
         self._explore_steps: int = 0
     # ------------------------------------------------------------------
     # Sync interface (fallback — OpenEnv prefers async when overridden)
@@ -78,6 +88,14 @@ class ExplainerEnvironment(Environment):
                 done=True,
                 reward=-1.0,
             )
         try:
             if action.action_type == "explore":
@@ -85,6 +103,8 @@ class ExplainerEnvironment(Environment):
                 return asyncio.run(self._handle_explore(action, task))
             elif action.action_type == "generate":
                 return self._handle_generate(action, task)
             else:
                 return self._make_obs(
                     task,
@@ -121,12 +141,22 @@ class ExplainerEnvironment(Environment):
                 done=True,
                 reward=-1.0,
             )
         try:
             if action.action_type == "explore":
                 return await self._handle_explore(action, task)
             elif action.action_type == "generate":
                 return self._handle_generate(action, task)
             else:
                 return self._make_obs(
                     task,
@@ -154,20 +184,40 @@ class ExplainerEnvironment(Environment):
             episode_id=episode_id or str(uuid4()), step_count=0
         )
         self._accumulated_context = []
         self._explore_steps = 0
-        difficulty = kwargs.get("difficulty", None)
-        if difficulty == "medium":
-            pool = MEDIUM_TASKS
-        elif difficulty == "hard":
-            pool = HARD_TASKS
-        elif difficulty == "easy":
-            pool = EASY_TASKS
         else:
-            pool = self._difficulty_pool
-        rng = random.Random(seed) if seed is not None else random.Random()
-        self._current_task = rng.choice(pool) if pool else rng.choice(ALL_TASKS)
         t = self._current_task
         return ExplainerObservation(
@@ -177,17 +227,31 @@ class ExplainerEnvironment(Environment):
             keywords=t.keywords,
             data_available=t.data_available,
             phase="explore",
-            feedback="Research phase: search for relevant papers before generating.",
             search_results="",
             explored_context="",
             explore_steps_left=MAX_EXPLORE_STEPS,
             done=False,
             reward=0.0,
         )
     async def _handle_explore(self, action: ExplainerAction, task: Task) -> ExplainerObservation:
-        """Process an explore action: search HF Papers/Wikipedia, score query."""
         if self._explore_steps >= MAX_EXPLORE_STEPS:
             return self._make_obs(
                 task,
                 phase="generate",
@@ -197,6 +261,8 @@ class ExplainerEnvironment(Environment):
         self._explore_steps += 1
         query = action.query.strip()
         if not query:
             return self._make_obs(
@@ -206,39 +272,68 @@ class ExplainerEnvironment(Environment):
                 reward=0.0,
             )
-        # Search HF Papers / Wikipedia (async, routed by keyword heuristic)
-        results_text = await search_sources(query, category_hint=task.topic)
-        self._accumulated_context.append(results_text)
         # Compute per-step exploration reward
         reward, components = compute_explore_reward(
             query=query,
-            result_text=results_text,
             topic=task.topic,
             keywords_csv=task.keywords,
             task_content=task.content,
             accumulated_context=self._accumulated_context,
         )
         steps_left = MAX_EXPLORE_STEPS - self._explore_steps
-        if steps_left > 0:
             phase = "explore"
-            hint = f"{steps_left} explore step(s) left. Continue researching or generate."
         else:
             phase = "generate"
-            hint = "Max explore steps reached. You must now generate."
         return self._make_obs(
             task,
             phase=phase,
-            feedback=f"{hint}\nReward: {components}",
             search_results=results_text,
             reward=reward,
-            metadata={"step": self._state.step_count, "phase": "explore", **components},
         )
     def _handle_generate(self, action: ExplainerAction, task: Task) -> ExplainerObservation:
-        """Process a generate action: run sandbox, compute generation reward."""
         fmt = action.format or "marimo"
         code = action.code
         narration = action.narration
@@ -251,17 +346,7 @@ class ExplainerEnvironment(Environment):
             skip_penalty = 0.0
             penalty_msg = ""
-        # Sandbox execution
-        parses = ast_parses(code)
-        exec_success = False
-        exec_msg = ""
-        if parses:
-            if fmt == "marimo":
-                exec_success, exec_msg = run_marimo(code)
-            elif fmt == "manim":
-                exec_success, exec_msg = run_manim(code)
-        else:
-            exec_msg = "Code has syntax errors and cannot be parsed."
         # Generation reward
         reward, components = compute_generate_reward(
@@ -269,35 +354,129 @@ class ExplainerEnvironment(Environment):
             fmt=fmt,
             narration=narration,
             task=task,
-            exec_success=exec_success,
             accumulated_context=self._accumulated_context,
         )
         reward = max(0.0, reward + skip_penalty)
         # Feedback
         parts = []
         if penalty_msg:
             parts.append(penalty_msg)
-        if not parses:
             parts.append("SYNTAX ERROR: code does not parse.")
-        elif not exec_success:
-            parts.append(f"EXECUTION FAILED: {exec_msg}")
         else:
-            parts.append(f"EXECUTION OK: {exec_msg}")
         parts.append(
             f"Reward: {', '.join(f'{k}={v}' for k, v in components.items())}"
         )
         return self._make_obs(
             task,
-            phase="done",
             feedback="\n".join(parts),
             reward=reward,
-            done=True,
             metadata={
                 "step": self._state.step_count,
                 "phase": "generate",
                 "explore_steps_used": self._explore_steps,
                 **components,
             },
         )
@@ -311,6 +490,7 @@ class ExplainerEnvironment(Environment):
         reward: float = 0.0,
         done: bool = False,
         search_results: str = "",
         metadata: dict | None = None,
     ) -> ExplainerObservation:
         """Helper to build a consistent observation."""
@@ -325,6 +505,9 @@ class ExplainerEnvironment(Environment):
             search_results=search_results,
             explored_context="\n---\n".join(self._accumulated_context),
             explore_steps_left=MAX_EXPLORE_STEPS - self._explore_steps,
             done=done,
             reward=reward,
             metadata=metadata or {},

 """
+Research -> Interactive Explainer Environment (multi-step, async).
 Episode flow:
   1. reset() → agent gets a topic + tier
+  2. step(explore) × 0..MAX_EXPLORE → agent calls research tools
+  3. step(generate) × 1 → agent produces marimo/manim code
+  4. step(repair) × 0..MAX_REPAIR → agent fixes lint/build errors if needed
 Each step returns a per-step reward. The final generate step also includes
 a generation reward that accounts for how well the code uses the research.
 from openenv.core.env_server.types import State
 try:
+    from ..constants import MAX_EXPLORE_STEPS, MAX_REPAIR_STEPS
     from ..models import ExplainerAction, ExplainerObservation
+    from ..research import AVAILABLE_TOOLS, run_research_tool
     from ..rewards.exploration import compute_explore_reward
+    from ..rewards.generation import adjust_repair_reward, compute_generate_reward
+    from ..rewards.sandbox import validate_code
     from ..task_bank import ALL_TASKS, EASY_TASKS, HARD_TASKS, MEDIUM_TASKS, Task
 except ImportError:
+    from constants import MAX_EXPLORE_STEPS, MAX_REPAIR_STEPS
     from models import ExplainerAction, ExplainerObservation
+    from research import AVAILABLE_TOOLS, run_research_tool
     from rewards.exploration import compute_explore_reward
+    from rewards.generation import adjust_repair_reward, compute_generate_reward
+    from rewards.sandbox import validate_code
     from task_bank import ALL_TASKS, EASY_TASKS, HARD_TASKS, MEDIUM_TASKS, Task
 class ExplainerEnvironment(Environment):
     """
         self._current_task: Task | None = None
         self._difficulty_pool: list[Task] = EASY_TASKS
         self._accumulated_context: list[str] = []
+        self._used_tools: set[str] = set()
         self._explore_steps: int = 0
+        self._repair_steps: int = 0
+        self._phase: str = "explore"
+        self._done: bool = False
+        self._last_code: str = ""
+        self._last_format: str = "marimo"
+        self._last_narration: str = ""
+        self._last_errors: str = ""
+        self._last_error_codes: list[str] = []
     # ------------------------------------------------------------------
     # Sync interface (fallback — OpenEnv prefers async when overridden)
                 done=True,
                 reward=-1.0,
             )
+        if self._done:
+            return self._make_obs(
+                task,
+                phase="done",
+                feedback="Episode is already done. Call reset() to start a new one.",
+                reward=0.0,
+                done=True,
+            )
         try:
             if action.action_type == "explore":
                 return asyncio.run(self._handle_explore(action, task))
             elif action.action_type == "generate":
                 return self._handle_generate(action, task)
+            elif action.action_type == "repair":
+                return self._handle_repair(action, task)
             else:
                 return self._make_obs(
                     task,
                 done=True,
                 reward=-1.0,
             )
+        if self._done:
+            return self._make_obs(
+                task,
+                phase="done",
+                feedback="Episode is already done. Call reset() to start a new one.",
+                reward=0.0,
+                done=True,
+            )
         try:
             if action.action_type == "explore":
                 return await self._handle_explore(action, task)
             elif action.action_type == "generate":
                 return self._handle_generate(action, task)
+            elif action.action_type == "repair":
+                return self._handle_repair(action, task)
             else:
                 return self._make_obs(
                     task,
             episode_id=episode_id or str(uuid4()), step_count=0
         )
         self._accumulated_context = []
+        self._used_tools = set()
         self._explore_steps = 0
+        self._repair_steps = 0
+        self._phase = "explore"
+        self._done = False
+        self._last_code = ""
+        self._last_format = "marimo"
+        self._last_narration = ""
+        self._last_errors = ""
+        self._last_error_codes = []
+        # Allow selecting a specific task by topic name
+        topic = kwargs.get("topic", None)
+        if topic:
+            match = next((t for t in ALL_TASKS if t.topic == topic), None)
+            if match:
+                self._current_task = match
+            else:
+                # Fallback to random if topic not found
+                rng = random.Random(seed) if seed is not None else random.Random()
+                self._current_task = rng.choice(ALL_TASKS)
         else:
+            difficulty = kwargs.get("difficulty", None)
+            if difficulty == "medium":
+                pool = MEDIUM_TASKS
+            elif difficulty == "hard":
+                pool = HARD_TASKS
+            elif difficulty == "easy":
+                pool = EASY_TASKS
+            else:
+                pool = self._difficulty_pool
+            rng = random.Random(seed) if seed is not None else random.Random()
+            self._current_task = rng.choice(pool) if pool else rng.choice(ALL_TASKS)
         t = self._current_task
         return ExplainerObservation(
             keywords=t.keywords,
             data_available=t.data_available,
             phase="explore",
+            feedback=(
+                "Research phase: choose a tool and query relevant to the topic. "
+                f"Available tools: {', '.join(AVAILABLE_TOOLS)}."
+            ),
             search_results="",
             explored_context="",
             explore_steps_left=MAX_EXPLORE_STEPS,
+            repair_attempts_left=MAX_REPAIR_STEPS,
+            available_tools=list(AVAILABLE_TOOLS),
             done=False,
             reward=0.0,
         )
     async def _handle_explore(self, action: ExplainerAction, task: Task) -> ExplainerObservation:
+        """Process an explore action: call a research tool and score the result."""
+        if self._phase not in {"explore", "generate"}:
+            return self._make_obs(
+                task,
+                phase=self._phase,
+                feedback=f"Cannot explore during phase '{self._phase}'.",
+                reward=0.0,
+            )
         if self._explore_steps >= MAX_EXPLORE_STEPS:
+            self._phase = "generate"
             return self._make_obs(
                 task,
                 phase="generate",
         self._explore_steps += 1
         query = action.query.strip()
+        intent = action.intent.strip()
+        tool = action.tool or "search_wikipedia"
         if not query:
             return self._make_obs(
                 reward=0.0,
             )
+        previous_context = list(self._accumulated_context)
+        used_tools = set(self._used_tools)
+        result = await run_research_tool(tool, query, intent)
+        results_text = result.render()
+        if result.ok:
+            self._accumulated_context.append(result.text)
+            self._used_tools.add(tool)
         # Compute per-step exploration reward
         reward, components = compute_explore_reward(
             query=query,
+            tool=tool,
+            intent=intent,
+            result=result,
             topic=task.topic,
             keywords_csv=task.keywords,
             task_content=task.content,
+            difficulty=task.difficulty,
+            previous_context=previous_context,
             accumulated_context=self._accumulated_context,
+            used_tools=used_tools,
         )
         steps_left = MAX_EXPLORE_STEPS - self._explore_steps
+        if steps_left > 1:
             phase = "explore"
+            hint = f"Research going well — {steps_left} more steps available. Keep searching or move to generation."
+        elif steps_left == 1:
+            phase = "explore"
+            hint = "Last research step available. Search for any missing context, or proceed to generate."
         else:
             phase = "generate"
+            hint = "Research phase complete. Time to generate your explanation."
+        self._phase = phase
         return self._make_obs(
             task,
             phase=phase,
+            feedback=f"{hint}\nTool: {tool}\nReward: {components}",
             search_results=results_text,
             reward=reward,
+            metadata={
+                "step": self._state.step_count,
+                "phase": "explore",
+                "tool": tool,
+                "source_count": len(result.chunks),
+                "error": result.error,
+                **components,
+            },
         )
     def _handle_generate(self, action: ExplainerAction, task: Task) -> ExplainerObservation:
+        """Process a generate action: run sandbox, maybe open repair phase."""
+        if self._phase not in {"explore", "generate"}:
+            return self._make_obs(
+                task,
+                phase=self._phase,
+                feedback=f"Cannot generate during phase '{self._phase}'.",
+                reward=0.0,
+            )
         fmt = action.format or "marimo"
         code = action.code
         narration = action.narration
             skip_penalty = 0.0
             penalty_msg = ""
+        sandbox = validate_code(fmt, code)
         # Generation reward
         reward, components = compute_generate_reward(
             fmt=fmt,
             narration=narration,
             task=task,
+            exec_success=sandbox.exec_success,
             accumulated_context=self._accumulated_context,
         )
         reward = max(0.0, reward + skip_penalty)
+        self._last_code = code
+        self._last_format = fmt
+        self._last_narration = narration
+        self._last_errors = sandbox.render_errors()
+        self._last_error_codes = sandbox.error_codes
         # Feedback
         parts = []
         if penalty_msg:
             parts.append(penalty_msg)
+        if not sandbox.parses:
             parts.append("SYNTAX ERROR: code does not parse.")
+        elif not sandbox.exec_success:
+            parts.append(f"EXECUTION FAILED: {sandbox.render_errors()}")
         else:
+            parts.append(f"EXECUTION OK: {sandbox.message}")
         parts.append(
             f"Reward: {', '.join(f'{k}={v}' for k, v in components.items())}"
         )
+        done = sandbox.exec_success or self._repair_steps >= MAX_REPAIR_STEPS
+        phase = "done" if done else "repair"
+        self._phase = phase
+        self._done = done
+        if not done:
+            parts.append("Repair phase: submit one revised artifact using the error feedback.")
         return self._make_obs(
             task,
+            phase=phase,
             feedback="\n".join(parts),
             reward=reward,
+            done=done,
+            last_errors="" if sandbox.exec_success else sandbox.render_errors(),
             metadata={
                 "step": self._state.step_count,
                 "phase": "generate",
                 "explore_steps_used": self._explore_steps,
+                "sandbox_message": sandbox.message,
+                "error_codes": sandbox.error_codes,
+                **components,
+            },
+        )
+    def _handle_repair(self, action: ExplainerAction, task: Task) -> ExplainerObservation:
+        """Process one repair attempt after a failed generate action."""
+        if self._phase != "repair":
+            return self._make_obs(
+                task,
+                phase=self._phase,
+                feedback="Repair is only available after a failed generate step.",
+                reward=0.0,
+                done=self._done,
+            )
+        if self._repair_steps >= MAX_REPAIR_STEPS:
+            self._phase = "done"
+            self._done = True
+            return self._make_obs(
+                task,
+                phase="done",
+                feedback="No repair attempts left.",
+                reward=0.0,
+                done=True,
+            )
+        self._repair_steps += 1
+        fmt = action.format or self._last_format or "marimo"
+        code = action.code
+        narration = action.narration or self._last_narration
+        previous_code = self._last_code
+        previous_errors = list(self._last_error_codes)
+        sandbox = validate_code(fmt, code)
+        base_reward, components = compute_generate_reward(
+            code=code,
+            fmt=fmt,
+            narration=narration,
+            task=task,
+            exec_success=sandbox.exec_success,
+            accumulated_context=self._accumulated_context,
+        )
+        repair_reward, repair_components = adjust_repair_reward(
+            base_reward,
+            repair_success=sandbox.exec_success,
+            previous_error_codes=previous_errors,
+            new_error_codes=sandbox.error_codes,
+            previous_code=previous_code,
+            repaired_code=code,
+        )
+        components.update(repair_components)
+        self._last_code = code
+        self._last_format = fmt
+        self._last_narration = narration
+        self._last_errors = sandbox.render_errors()
+        self._last_error_codes = sandbox.error_codes
+        self._phase = "done"
+        self._done = True
+        status = "REPAIR OK" if sandbox.exec_success else "REPAIR FAILED"
+        feedback = (
+            f"{status}: {sandbox.message if sandbox.exec_success else sandbox.render_errors()}\n"
+            f"Reward: {', '.join(f'{k}={v}' for k, v in components.items())}"
+        )
+        return self._make_obs(
+            task,
+            phase="done",
+            feedback=feedback,
+            reward=repair_reward,
+            done=True,
+            last_errors="" if sandbox.exec_success else sandbox.render_errors(),
+            metadata={
+                "step": self._state.step_count,
+                "phase": "repair",
+                "explore_steps_used": self._explore_steps,
+                "repair_steps_used": self._repair_steps,
+                "sandbox_message": sandbox.message,
+                "error_codes": sandbox.error_codes,
                 **components,
             },
         )
         reward: float = 0.0,
         done: bool = False,
         search_results: str = "",
+        last_errors: str | None = None,
         metadata: dict | None = None,
     ) -> ExplainerObservation:
         """Helper to build a consistent observation."""
             search_results=search_results,
             explored_context="\n---\n".join(self._accumulated_context),
             explore_steps_left=MAX_EXPLORE_STEPS - self._explore_steps,
+            repair_attempts_left=MAX_REPAIR_STEPS - self._repair_steps,
+            last_errors=self._last_errors if last_errors is None else last_errors,
+            available_tools=list(AVAILABLE_TOOLS),
             done=done,
             reward=reward,
             metadata=metadata or {},

tests/test_client_server.py CHANGED Viewed

@@ -42,7 +42,12 @@ def run_tests(base_url: str):
         print(f"  reset: topic={obs.topic!r}, phase={obs.phase}")
         # --- explore ---
-        action = ExplainerAction(action_type="explore", query=obs.topic)
         result = sc.step(action)
         assert not result.done
         assert result.observation.explore_steps_left == 2
@@ -55,6 +60,12 @@ def run_tests(base_url: str):
             code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    mo.md('hi')\n    return\n",
         )
         result = sc.step(action)
         assert result.done
         assert isinstance(result.reward, (int, float))
         print(f"  generate: reward={result.reward:.3f}, done={result.done}")
@@ -75,13 +86,15 @@ def main():
     if args.url:
         run_tests(args.url)
     else:
         proc = subprocess.Popen(
-            ["uv", "run", "server"],
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
         )
         try:
-            url = "http://localhost:8000"
             if not wait_for_server(url):
                 stderr = proc.stderr.read().decode() if proc.stderr else ""
                 print(f"FAIL: server did not start\n{stderr}", file=sys.stderr)

         print(f"  reset: topic={obs.topic!r}, phase={obs.phase}")
         # --- explore ---
+        action = ExplainerAction(
+            action_type="explore",
+            tool="search_wikipedia",
+            query=obs.topic,
+            intent="overview",
+        )
         result = sc.step(action)
         assert not result.done
         assert result.observation.explore_steps_left == 2
             code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    mo.md('hi')\n    return\n",
         )
         result = sc.step(action)
+        if not result.done:
+            result = sc.step(ExplainerAction(
+                action_type="repair",
+                format="marimo",
+                code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    mo.md('hi')\n    return\n",
+            ))
         assert result.done
         assert isinstance(result.reward, (int, float))
         print(f"  generate: reward={result.reward:.3f}, done={result.done}")
     if args.url:
         run_tests(args.url)
     else:
+        port = "8010"
         proc = subprocess.Popen(
+            ["uv", "run", "uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", port],
+            cwd=str(Path(__file__).resolve().parents[1]),
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
         )
         try:
+            url = f"http://localhost:{port}"
             if not wait_for_server(url):
                 stderr = proc.stderr.read().decode() if proc.stderr else ""
                 print(f"FAIL: server did not start\n{stderr}", file=sys.stderr)

tests/test_docker.py CHANGED Viewed

@@ -76,10 +76,17 @@ def run_tests(base_url: str):
         print(f"  reset: topic={result.observation.topic!r}")
         action = ExplainerAction(
             format="marimo",
             code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    return\n",
         )
         result = sc.step(action)
         assert isinstance(result.reward, (int, float))
         print(f"  step:  reward={result.reward:.3f}, done={result.done}")

         print(f"  reset: topic={result.observation.topic!r}")
         action = ExplainerAction(
+            action_type="generate",
             format="marimo",
             code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    return\n",
         )
         result = sc.step(action)
+        if not result.done:
+            result = sc.step(ExplainerAction(
+                action_type="repair",
+                format="marimo",
+                code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    return\n",
+            ))
         assert isinstance(result.reward, (int, float))
         print(f"  step:  reward={result.reward:.3f}, done={result.done}")

tests/test_environment.py CHANGED Viewed

@@ -29,7 +29,12 @@ def test_reset_deterministic_with_seed():
 def test_explore_step():
     env = ExplainerEnvironment()
     env.reset(seed=1)
-    action = ExplainerAction(action_type="explore", query="gradient descent optimization")
     obs = env.step(action)
     assert obs.done is False
     assert obs.explore_steps_left == 2
@@ -40,7 +45,7 @@ def test_explore_step():
 def test_explore_empty_query():
     env = ExplainerEnvironment()
     env.reset(seed=1)
-    action = ExplainerAction(action_type="explore", query="")
     obs = env.step(action)
     assert obs.reward == 0.0
     assert "Empty query" in obs.feedback
@@ -50,7 +55,11 @@ def test_explore_max_steps():
     env = ExplainerEnvironment()
     env.reset(seed=1)
     for i in range(3):
-        obs = env.step(ExplainerAction(action_type="explore", query=f"search {i}"))
     assert obs.phase == "generate"
     assert obs.explore_steps_left == 0
@@ -59,17 +68,20 @@ def test_explore_then_generate():
     env = ExplainerEnvironment()
     env.reset(seed=1)
     # Explore
-    obs = env.step(ExplainerAction(action_type="explore", query="gradient descent"))
     assert obs.done is False
-    assert obs.explored_context != ""
     # Generate
     obs = env.step(ExplainerAction(
         action_type="generate",
         format="marimo",
         code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    return\n",
     ))
-    assert obs.done is True
-    assert obs.phase == "done"
     assert isinstance(obs.reward, (int, float))
@@ -81,13 +93,14 @@ def test_generate_without_explore_penalty():
         format="marimo",
         code="x = 1",
     ))
-    assert obs.done is True
     assert "penalty" in obs.feedback.lower() or "without" in obs.feedback.lower()
 def test_step_without_reset():
     env = ExplainerEnvironment()
-    action = ExplainerAction(action_type="explore", query="test")
     obs = env.step(action)
     assert obs.done is True
     assert obs.reward == -1.0
@@ -96,7 +109,11 @@ def test_step_without_reset():
 def test_generate_reward_in_metadata():
     env = ExplainerEnvironment()
     env.reset(seed=1)
-    env.step(ExplainerAction(action_type="explore", query="gradient descent"))
     obs = env.step(ExplainerAction(
         action_type="generate",
         format="marimo",
@@ -120,7 +137,11 @@ def test_step_increments_count():
     env = ExplainerEnvironment()
     env.reset(seed=1)
     assert env.state.step_count == 0
-    env.step(ExplainerAction(action_type="explore", query="test"))
     assert env.state.step_count == 1
     env.step(ExplainerAction(action_type="generate", format="marimo", code="x=1"))
     assert env.state.step_count == 2
@@ -134,10 +155,30 @@ def test_bad_code_does_not_crash():
         format="marimo",
         code=")))syntax error(((",
     ))
-    assert obs.done is True
     assert "SYNTAX ERROR" in obs.feedback
 if __name__ == "__main__":
     tests = [
         test_reset_returns_observation,
@@ -152,6 +193,7 @@ if __name__ == "__main__":
         test_state_episode_id_changes,
         test_step_increments_count,
         test_bad_code_does_not_crash,
     ]
     passed = 0
     for t in tests:

 def test_explore_step():
     env = ExplainerEnvironment()
     env.reset(seed=1)
+    action = ExplainerAction(
+        action_type="explore",
+        tool="search_wikipedia",
+        query="gradient descent optimization",
+        intent="beginner explanation",
+    )
     obs = env.step(action)
     assert obs.done is False
     assert obs.explore_steps_left == 2
 def test_explore_empty_query():
     env = ExplainerEnvironment()
     env.reset(seed=1)
+    action = ExplainerAction(action_type="explore", tool="search_wikipedia", query="")
     obs = env.step(action)
     assert obs.reward == 0.0
     assert "Empty query" in obs.feedback
     env = ExplainerEnvironment()
     env.reset(seed=1)
     for i in range(3):
+        obs = env.step(ExplainerAction(
+            action_type="explore",
+            tool="search_wikipedia",
+            query=f"search {i}",
+        ))
     assert obs.phase == "generate"
     assert obs.explore_steps_left == 0
     env = ExplainerEnvironment()
     env.reset(seed=1)
     # Explore
+    obs = env.step(ExplainerAction(
+        action_type="explore",
+        tool="search_wikipedia",
+        query="gradient descent",
+    ))
     assert obs.done is False
+    assert obs.search_results != ""
     # Generate
     obs = env.step(ExplainerAction(
         action_type="generate",
         format="marimo",
         code="import marimo as mo\napp = mo.App()\n@app.cell\ndef _():\n    return\n",
     ))
+    assert obs.phase in ("repair", "done")
     assert isinstance(obs.reward, (int, float))
         format="marimo",
         code="x = 1",
     ))
+    assert obs.done is False
+    assert obs.phase == "repair"
     assert "penalty" in obs.feedback.lower() or "without" in obs.feedback.lower()
 def test_step_without_reset():
     env = ExplainerEnvironment()
+    action = ExplainerAction(action_type="explore", tool="search_wikipedia", query="test")
     obs = env.step(action)
     assert obs.done is True
     assert obs.reward == -1.0
 def test_generate_reward_in_metadata():
     env = ExplainerEnvironment()
     env.reset(seed=1)
+    env.step(ExplainerAction(
+        action_type="explore",
+        tool="search_wikipedia",
+        query="gradient descent",
+    ))
     obs = env.step(ExplainerAction(
         action_type="generate",
         format="marimo",
     env = ExplainerEnvironment()
     env.reset(seed=1)
     assert env.state.step_count == 0
+    env.step(ExplainerAction(
+        action_type="explore",
+        tool="search_wikipedia",
+        query="test",
+    ))
     assert env.state.step_count == 1
     env.step(ExplainerAction(action_type="generate", format="marimo", code="x=1"))
     assert env.state.step_count == 2
         format="marimo",
         code=")))syntax error(((",
     ))
+    assert obs.done is False
+    assert obs.phase == "repair"
     assert "SYNTAX ERROR" in obs.feedback
+def test_repair_ends_episode():
+    env = ExplainerEnvironment()
+    env.reset(seed=1)
+    env.step(ExplainerAction(
+        action_type="generate",
+        format="marimo",
+        code="x = 1",
+    ))
+    obs = env.step(ExplainerAction(
+        action_type="repair",
+        format="marimo",
+        code="x = 2",
+        repair_notes="attempted fix",
+    ))
+    assert obs.done is True
+    assert obs.phase == "done"
+    assert obs.metadata["phase"] == "repair"
 if __name__ == "__main__":
     tests = [
         test_reset_returns_observation,
         test_state_episode_id_changes,
         test_step_increments_count,
         test_bad_code_does_not_crash,
+        test_repair_ends_episode,
     ]
     passed = 0
     for t in tests:

tests/test_models.py CHANGED Viewed

@@ -9,9 +9,16 @@ from models import ExplainerAction, ExplainerObservation
 def test_action_explore():
-    a = ExplainerAction(action_type="explore", query="attention mechanism")
     assert a.action_type == "explore"
     assert a.query == "attention mechanism"
     assert a.code == ""
     assert a.format is None
@@ -38,12 +45,24 @@ def test_action_generate_manim():
     assert a.narration != ""
 def test_observation_defaults():
     obs = ExplainerObservation()
     assert obs.topic == ""
     assert obs.tier == "beginner"
     assert obs.phase == "explore"
     assert obs.explore_steps_left == 3
     assert obs.done is False
@@ -72,6 +91,7 @@ if __name__ == "__main__":
     test_action_explore()
     test_action_generate_marimo()
     test_action_generate_manim()
     test_observation_defaults()
     test_observation_full()
-    print("PASS: test_models (5/5)")

 def test_action_explore():
+    a = ExplainerAction(
+        action_type="explore",
+        tool="search_arxiv",
+        query="attention mechanism",
+        intent="visual intuition",
+    )
     assert a.action_type == "explore"
+    assert a.tool == "search_arxiv"
     assert a.query == "attention mechanism"
+    assert a.intent == "visual intuition"
     assert a.code == ""
     assert a.format is None
     assert a.narration != ""
+def test_action_repair():
+    a = ExplainerAction(
+        action_type="repair",
+        format="marimo",
+        code="x = 1",
+        repair_notes="fixed syntax",
+    )
+    assert a.action_type == "repair"
+    assert a.repair_notes == "fixed syntax"
 def test_observation_defaults():
     obs = ExplainerObservation()
     assert obs.topic == ""
     assert obs.tier == "beginner"
     assert obs.phase == "explore"
     assert obs.explore_steps_left == 3
+    assert obs.repair_attempts_left == 1
     assert obs.done is False
     test_action_explore()
     test_action_generate_marimo()
     test_action_generate_manim()
+    test_action_repair()
     test_observation_defaults()
     test_observation_full()
+    print("PASS: test_models (6/6)")

tests/test_rewards.py CHANGED Viewed

@@ -6,10 +6,13 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 from rewards.exploration import (
     compute_explore_reward,
     query_relevance,
     research_breadth,
     result_novelty,
 )
 from rewards.generation import (
     compute_generate_reward,
@@ -20,6 +23,7 @@ from rewards.generation import (
     narration_score,
 )
 from rewards.sandbox import ast_parses
 from task_bank import ALL_TASKS
 MARIMO_TASK = next(t for t in ALL_TASKS if t.topic == "Linear Regression")
@@ -53,19 +57,73 @@ def test_research_breadth():
     assert research_breadth(["a", "b"], min_sources=2) == 1.0
 def test_explore_reward_integration():
     reward, comp = compute_explore_reward(
         query="linear regression least squares",
-        result_text="Linear regression minimizes squared error...",
         topic="Linear Regression",
         keywords_csv="linear regression,least squares,MSE",
         task_content="Linear regression is a method for modeling the relationship between variables.",
         accumulated_context=["first search result"],
     )
     assert reward > 0.1
     assert "query_relevance" in comp
-    assert "result_novelty" in comp
-    assert "research_breadth" in comp
     assert "content_sufficiency" in comp
@@ -195,6 +253,9 @@ if __name__ == "__main__":
         test_query_relevance,
         test_result_novelty,
         test_research_breadth,
         test_explore_reward_integration,
         test_keyword_coverage,
         test_format_match,

 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 from rewards.exploration import (
+    coverage_delta,
     compute_explore_reward,
     query_relevance,
     research_breadth,
     result_novelty,
+    source_quality,
+    tool_choice_score,
 )
 from rewards.generation import (
     compute_generate_reward,
     narration_score,
 )
 from rewards.sandbox import ast_parses
+from research.types import ResearchChunk, ResearchResult
 from task_bank import ALL_TASKS
 MARIMO_TASK = next(t for t in ALL_TASKS if t.topic == "Linear Regression")
     assert research_breadth(["a", "b"], min_sources=2) == 1.0
+def test_tool_choice_score():
+    assert tool_choice_score("search_arxiv", "hard", "recent research paper") == 1.0
+    assert tool_choice_score("fetch_docs", "easy", "marimo plotting api") == 1.0
+def test_source_quality():
+    result = ResearchResult(
+        tool="search_arxiv",
+        query="linear regression",
+        chunks=[
+            ResearchChunk(
+                source="arxiv",
+                tool="search_arxiv",
+                title="A paper",
+                url="https://arxiv.org/abs/1",
+                text="linear regression least squares optimization " * 10,
+                score=1.0,
+                metadata={"year": 2024},
+            )
+        ],
+    )
+    assert source_quality(result) > 0.7
+def test_coverage_delta():
+    assert coverage_delta(
+        "linear regression,MSE",
+        "linear regression",
+        [],
+        "mean squared error MSE",
+    ) > 0.0
 def test_explore_reward_integration():
+    result = ResearchResult(
+        tool="search_wikipedia",
+        query="linear regression least squares",
+        chunks=[
+            ResearchChunk(
+                source="wikipedia",
+                tool="search_wikipedia",
+                title="Linear regression",
+                url="https://example.test",
+                text="Linear regression minimizes squared error with least squares.",
+                score=1.0,
+                metadata={"page": "Linear regression"},
+            )
+        ],
+    )
     reward, comp = compute_explore_reward(
         query="linear regression least squares",
+        tool="search_wikipedia",
+        intent="beginner explanation",
+        result=result,
         topic="Linear Regression",
         keywords_csv="linear regression,least squares,MSE",
         task_content="Linear regression is a method for modeling the relationship between variables.",
+        difficulty="easy",
+        previous_context=[],
         accumulated_context=["first search result"],
+        used_tools=set(),
     )
     assert reward > 0.1
+    assert "tool_choice" in comp
     assert "query_relevance" in comp
+    assert "source_quality" in comp
+    assert "coverage_delta" in comp
     assert "content_sufficiency" in comp
         test_query_relevance,
         test_result_novelty,
         test_research_breadth,
+        test_tool_choice_score,
+        test_source_quality,
+        test_coverage_delta,
         test_explore_reward_integration,
         test_keyword_coverage,
         test_format_match,

uv.lock CHANGED Viewed

The diff for this file is too large to render. See raw diff