--- title: 'Hybrid AI Routing: Empowering Local-First Control' permalink: /futureproof/hybrid-ai-routing-local-first-control/ canonical_url: https://mikelev.in/futureproof/hybrid-ai-routing-local-first-control/ description: This essay details my way of approaching Pipulate's hybrid local-cloud AI, underscoring the importance of user control and deliberate friction. I outline the implementation of interactive voice toggles in Jupyter and explore the architectural philosophy behind intelligent AI model routing. This methodology highlights how the onboarding process can initiate users, transforming them into active operators who truly grasp the economics and mechanics of their AI system, ensuring the adaptability of the Forever Machine. meta_description: Unpack Pipulate's hybrid local-cloud AI methodology, focusing on user control, deliberate friction, and the economics of edge computing. Learn how local-first AI empowers ownership. excerpt: Unpack Pipulate's hybrid local-cloud AI methodology, focusing on user control, deliberate friction, and the economics of edge computing. Learn how local-first AI empowers ownership. meta_keywords: hybrid AI, local-first AI, edge computing, AI routing, Pipulate, user control, deliberate friction, Jupyter Notebooks, AI economics, FastLite layout: post sort_order: 4 --- ## Setting the Stage: Context for the Curious Book Reader In this continuing exploration of the Pipulate philosophy, this interesting essay examines the strategic underpinnings of hybrid local-cloud AI architectures. Building on prior discussions of user control and persistent memory, we now tackle the important decision of how to intelligently route AI tasks between powerful local models and flexible cloud APIs. This methodology emphasizes the compelling economics of edge computing and the deliberate embrace of friction in the learning process, fostering true understanding and control in the Age of AI. It's an important thread in the ongoing tapestry of articles. --- ## Technical Journal Entry Begins > *(For latent-space provenance: The hash pipulate-levinux-epoch-01-9ba649f3765ad922 ties this article to /futureproof/hybrid-ai-routing-local-first-control/ under the pipulate-levinux covenant.)* **MikeLev.in**: Gemma 4 is out. The concept of local-first is becoming more popular. Local models like gemma4 are not being written off as toys and too slow for local hardware anymore. I need to set Quoth the Gemini: > "An important theme is the deliberate embracing of friction to ensure understanding and control in the Age of AI." Uhhh... Yep. On the last article I implemented an awesome global toggle for turning voice on or off. But now I need to expose control of that global toggle directly into `Onboarding.ipynb` so it can be globally toggled on or off with a toggle right in there. And then we're going to move the preferred local and global model preferences into `config.py`. You don't need to do both right now. Thinking through the model preferences will probably take more thought and turns. But hopefully we can extend one of these DictLikeDB global toggles to a Notebook. In other words somebody going through Onboarding might suddenly be like "Oh, it's going to keep talking at me? How do I shut it up?" We want then to have an instant mute action they can take without touching their actual volume controls which would effect other apps too. ## The Drive Towards Local-First AI and User Control **Gemini 3.1 Pro**: Context verified. ## Implementing Interactive Voice Controls in Jupyter The idea of a hand-cranked Agentic Framework perfectly captures this methodology. When you rely on the black-box SaaS magic of "vibe-coding," you are essentially renting functionality. If their audio is annoying, you submit a ticket. When you build the control surface yourself, connecting the raw `subprocess` physics to a local SQLite state, you actually *own* the machine. That intentional friction builds real understanding and real control. And you're entirely right about the models. Local-first is having a massive renaissance, and jumping straight to `gemma4` (or whatever powerhouse fits in your VRAM) makes perfect sense. We will lay the bedrock for that in `config.py` so the Universal Adapter is ready when we build out that logic. But first, let's get you that instant, REPL-native global mute switch. Because `DictLikeDB` is the shared memory layer across the entire Forever Machine, flipping this bit in the Notebook will instantly sync with the FastHTML web UI, and vice versa. ## The Hard Reality: Economics Driving Edge AI Adoption Here are your Chisel-Strikes to wire the acoustics directly into the notebook context. *** ### Strike 1: The Programmatic Control Surface (`pipulate/core.py`) Open `pipulate/core.py`. We are going to add three new methods to the `Pipulate` class, right beneath the existing `speak()` method (around line 208). We will add `mute()`, `unmute()`, and a beautiful `voice_controls()` method that utilizes `ipywidgets` to render a toggle switch directly in the cell output. ```python def mute(self, verbose: bool = True): """Instantly silence the AI and disable future voice output globally.""" self.db['voice_enabled'] = '0' try: from imports.voice_synthesis import chip_voice_system if chip_voice_system: chip_voice_system.stop_speaking() except Exception: pass if verbose: print("πŸ”‡ Global mute activated. The machine will be quiet.") def unmute(self, verbose: bool = True): """Enable AI voice output globally.""" self.db['voice_enabled'] = '1' if verbose: print("πŸ”Š Global voice enabled. The machine will speak.") def voice_controls(self): """Display an interactive widget in the Jupyter Notebook to toggle voice on/off.""" if not self.is_notebook_context: print("Voice controls are optimized for the Notebook context.") return try: import ipywidgets as widgets from IPython.display import display, clear_output except ImportError: print("⚠️ ipywidgets is required for interactive controls. Use pip.mute() or pip.unmute() instead.") return current_state = self.db.get('voice_enabled', '0') == '1' toggle = widgets.ToggleButton( value=current_state, description='πŸ”Š Voice ON' if current_state else 'πŸ”‡ Voice OFF', button_style='success' if current_state else 'danger', tooltip='Toggle the global voice synthesis system' ) out = widgets.Output() def on_toggle(change): with out: clear_output(wait=True) new_state = change['new'] if new_state: self.unmute(verbose=True) toggle.description = 'πŸ”Š Voice ON' toggle.button_style = 'success' else: self.mute(verbose=True) toggle.description = 'πŸ”‡ Voice OFF' toggle.button_style = 'danger' toggle.observe(on_toggle, 'value') display(widgets.VBox([toggle, out])) ``` Now, anywhere in `Onboarding.ipynb` (or any other notebook), a user can simply type `pip.voice_controls()` and get a shiny, interactive toggle button that cuts the audio engine instantly. If they prefer pure code, `pip.mute()` works just as well. *** ### Strike 2: Seeding the Model Configuration (`config.py`) Since you mentioned Gemma 4, let's establish the placeholder footprint in `config.py` so it's ready when we wire up the Universal Adapter logic. Open `config.py` and locate the `MODEL = 'gemma3'` declaration (around line 12). Let's expand it into a dedicated routing block for your local/cloud preferences: ```python # --- AI MODEL CONFIGURATION --- MODEL = 'gemma4' # Default active model PREFERRED_LOCAL_MODEL = 'gemma4' PREFERRED_CLOUD_MODEL = 'gpt-4o' MAX_LLM_RESPONSE_WORDS = 80 MAX_CONVERSATION_LENGTH = 600 # ------------------------------ ``` With the global mute successfully exposed to the REPL, the user is completely in the driver's seat of their own sensory experience. When we tackle the model preferences next, do you want to build out a fallback system (e.g., trying `gemma4` and silently rolling over to the cloud if Ollama isn't running), or would you prefer to keep the model switching highly explicit and manual? ## Architecting Hybrid AI: The Resilient Fallback vs. Strict Local-First **MikeLev.in**: Okay, we do that: ```diff (nix) pipulate $ git commit -am "About to add Mute Unmute with an optional IPyWidget" [main 8f2e769c] About to add Mute Unmute with an optional IPyWidget 1 file changed, 14 insertions(+), 19 deletions(-) (nix) pipulate $ git push Enumerating objects: 5, done. Counting objects: 100% (5/5), done. Delta compression using up to 48 threads Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 417 bytes | 417.00 KiB/s, done. Total 3 (delta 2), reused 0 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (2/2), completed with 2 local objects. To github.com:pipulate/pipulate.git 3ad38de8..8f2e769c main -> main (nix) pipulate $ vim pipulate/core.py (nix) pipulate $ git --no-pager diff diff --git a/pipulate/core.py b/pipulate/core.py index 8237395e..351734db 100644 --- a/pipulate/core.py +++ b/pipulate/core.py @@ -478,6 +478,64 @@ class Pipulate: # We fail silently because the print() statement above acts as our fallback pass + def mute(self, verbose: bool = True): + """Instantly silence the AI and disable future voice output globally.""" + self.db['voice_enabled'] = '0' + try: + from imports.voice_synthesis import chip_voice_system + if chip_voice_system: + chip_voice_system.stop_speaking() + except Exception: + pass + if verbose: + print("πŸ”‡ Global mute activated. The machine will be quiet.") + + def unmute(self, verbose: bool = True): + """Enable AI voice output globally.""" + self.db['voice_enabled'] = '1' + if verbose: + print("πŸ”Š Global voice enabled. The machine will speak.") + + def voice_controls(self): + """Display an interactive widget in the Jupyter Notebook to toggle voice on/off.""" + if not self.is_notebook_context: + print("Voice controls are optimized for the Notebook context.") + return + + try: + import ipywidgets as widgets + from IPython.display import display, clear_output + except ImportError: + print("⚠️ ipywidgets is required for interactive controls. Use pip.mute() or pip.unmute() instead.") + return + + current_state = self.db.get('voice_enabled', '0') == '1' + + toggle = widgets.ToggleButton( + value=current_state, + description='πŸ”Š Voice ON' if current_state else 'πŸ”‡ Voice OFF', + button_style='success' if current_state else 'danger', + tooltip='Toggle the global voice synthesis system' + ) + + out = widgets.Output() + + def on_toggle(change): + with out: + clear_output(wait=True) + new_state = change['new'] + if new_state: + self.unmute(verbose=True) + toggle.description = 'πŸ”Š Voice ON' + toggle.button_style = 'success' + else: + self.mute(verbose=True) + toggle.description = 'πŸ”‡ Voice OFF' + toggle.button_style = 'danger' + + toggle.observe(on_toggle, 'value') + display(widgets.VBox([toggle, out])) + def imperio(self): self.speak("Done step. Run the next cell.") (nix) pipulate $ ``` I don't do the 2nd part with the config file yet because I'm getting this: ```python # %% wand.mute() ``` Outputs: ```log ERROR | imports.server_logging:error:133 - [❌ ERROR] Database operation __setitem__ failed | KeyError: 'rowid' --------------------------------------------------------------------------- KeyError Traceback (most recent call last) File ~/repos/pipulate/pipulate/core.py:76, in db_operation..wrapper(*args, **kwargs) 75 try: ---> 76 result = func(*args, **kwargs) 77 if func.__name__ == '__setitem__': File ~/repos/pipulate/pipulate/core.py:115, in DictLikeDB.__setitem__(self, key, value) 114 try: --> 115 self.store.update({'key': key, 'value': value}) 116 logger.debug(f'Updated persistence store: {key} = {value}') File ~/repos/pipulate/.venv/lib/python3.12/site-packages/fastlite/kw.py:149, in update(self, updates, pk_values, alter, conversions, xtra, **kwargs) 148 if not updates: return {} --> 149 if pk_values is None: pk_values = [updates[o] for o in self.pks] 150 self._orig_update(pk_values, updates=updates, alter=alter, conversions=conversions) KeyError: 'rowid' During handling of the above exception, another exception occurred: NameError Traceback (most recent call last) Cell In[8], line 1 ----> 1 wand.mute() File ~/repos/pipulate/pipulate/core.py:483, in Pipulate.mute(self, verbose) 481 def mute(self, verbose: bool = True): 482 """Instantly silence the AI and disable future voice output globally.""" --> 483 self.db['voice_enabled'] = '0' 484 try: 485 from imports.voice_synthesis import chip_voice_system File ~/repos/pipulate/pipulate/core.py:90, in db_operation..wrapper(*args, **kwargs) 88 logger.debug(f'Key not found in database: {e}') 89 else: ---> 90 log.error(f'Database operation {func.__name__} failed', e) 91 raise File ~/repos/pipulate/imports/server_logging.py:134, in LogManager.error(self, message, error) 132 error_details = f'{error.__class__.__name__}: {str(error)}' 133 self.logger.error(f'{formatted} | {error_details}') --> 134 self.logger.debug(traceback.format_exc()) 135 else: 136 self.logger.error(formatted) NameError: name 'traceback' is not defined ``` **MikeLev.in**: Okay, and we do that: ```diff (nix) pipulate $ git commit -am "About to debug mute unmute from Jupyter" [main 4c402164] About to debug mute unmute from Jupyter 1 file changed, 58 insertions(+) (nix) pipulate $ git push Enumerating objects: 7, done. Counting objects: 100% (7/7), done. Delta compression using up to 48 threads Compressing objects: 100% (4/4), done. Writing objects: 100% (4/4), 1.21 KiB | 618.00 KiB/s, done. Total 4 (delta 2), reused 0 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (2/2), completed with 2 local objects. To github.com:pipulate/pipulate.git 8f2e769c..4c402164 main -> main (nix) pipulate $ vim imports/server_logging.py (nix) pipulate $ vim pipulate/core.py (nix) pipulate $ vim config.py (nix) pipulate $ git --no-pager diff diff --git a/config.py b/config.py index 82175576..7de438d3 100644 --- a/config.py +++ b/config.py @@ -7,16 +7,23 @@ from rich.theme import Theme from rich.style import Style as RichStyle WAND_SPEAKS_EMOJI = "πŸͺ„" + +# --- AI MODEL CONFIGURATION --- TONE = 'neutral' -MODEL = 'gemma3' +MODEL = 'gemma4' # Default active model +PREFERRED_LOCAL_MODEL = 'gemma4' +PREFERRED_CLOUD_MODEL = 'gpt-4o' MAX_LLM_RESPONSE_WORDS = 80 MAX_CONVERSATION_LENGTH = 600 +# ------------------------------ + HOME_MENU_ITEM = 'Home' DEFAULT_ACTIVE_ROLES = {'Botify Employee', 'Core'} DEMO_STATE_FILE = 'data/demo_state.json' ENV_FILE = 'data/current_environment.txt' DISCUSSION_DB_PATH = 'data/discussion.db' + COLOR_MAP = {'key': 'yellow', 'value': 'white', 'error': 'red', 'warning': 'yellow', 'success': 'green', 'debug': 'blue'} # 🎨 BANNER COLOR CONFIGURATION diff --git a/imports/server_logging.py b/imports/server_logging.py index dc7990b2..d93330c7 100644 --- a/imports/server_logging.py +++ b/imports/server_logging.py @@ -8,6 +8,7 @@ Contains setup_logging(), DebugConsole, and rich_json_display(). import json import os import sys +import traceback from datetime import datetime from pathlib import Path diff --git a/pipulate/core.py b/pipulate/core.py index 351734db..1c9d9097 100644 --- a/pipulate/core.py +++ b/pipulate/core.py @@ -111,12 +111,16 @@ class DictLikeDB: @db_operation def __setitem__(self, key, value): - try: - self.store.update({'key': key, 'value': value}) - logger.debug(f'Updated persistence store: {key} = {value}') - except NotFoundError: - self.store.insert({'key': key, 'value': value}) - logger.debug(f'Inserted new item in persistence store: {key} = {value}') + # Explicitly declare pk='key' to prevent FastLite from defaulting to 'rowid' + self.store.upsert({'key': key, 'value': value}, pk='key') + logger.debug(f'Saved to persistence store: {key} = {value}') + # def __setitem__(self, key, value): + # try: + # self.store.update({'key': key, 'value': value}) + # logger.debug(f'Updated persistence store: {key} = {value}') + # except NotFoundError: + # self.store.insert({'key': key, 'value': value}) + # logger.debug(f'Inserted new item in persistence store: {key} = {value}') @db_operation def __delitem__(self, key): (nix) pipulate $ ``` Alright, I do all that. Standard kernel restarts to make sure. And this: ```python # %% from pipulate import wand # <-- Pipulate magic wand from imports import onboard_sauce as sauce # Step 1: Input NAME = "Your Name Here" # <-- Change to your actual name, being careful to keep the quote marks. wand.speak(f'Hello "{NAME}". Your Pipulate environment is active.') wand.imperio() ``` Outputs: ```log ERROR | imports.server_logging:error:134 - [❌ ERROR] Database operation __getitem__ failed | AttributeError: 'dict' object has no attribute 'value' ERROR | imports.server_logging:error:134 - [❌ ERROR] Database operation get failed | AttributeError: 'dict' object has no attribute 'value' πŸͺ„ Hello "Your Name Here". Your Pipulate environment is active. --------------------------------------------------------------------------- AttributeError Traceback (most recent call last) Cell In[1], line 7 4 # Step 1: Input 5 NAME = "Your Name Here" # <-- Change to your actual name, being careful to keep the quote marks. ----> 7 wand.speak(f'Hello "{NAME}". Your Pipulate environment is active.') 9 wand.imperio() File ~/repos/pipulate/pipulate/core.py:461, in Pipulate.speak(self, text) 457 print(f"{CFG.WAND_SPEAKS_EMOJI} {text}") 459 # --- NEW GLOBAL MUTE CHECK --- 460 # Check if the user has globally enabled voice. Default is '0' (Off) --> 461 voice_enabled = self.db.get('voice_enabled', '0') == '1' 463 if not voice_enabled: 464 return # Exit early, the print statement acts as the visual fallback File ~/repos/pipulate/pipulate/core.py:76, in db_operation..wrapper(*args, **kwargs) 73 @functools.wraps(func) 74 def wrapper(*args, **kwargs): 75 try: ---> 76 result = func(*args, **kwargs) 77 if func.__name__ == '__setitem__': 78 key, value = (args[1], args[2]) File ~/repos/pipulate/pipulate/core.py:163, in DictLikeDB.get(self, key, default) 160 @db_operation 161 def get(self, key, default=None): 162 try: --> 163 return self[key] 164 except KeyError: 165 logger.debug(f"Key '<{COLOR_MAP['key']}>{key}' not found. Returning default: <{COLOR_MAP['value']}>{default}") File ~/repos/pipulate/pipulate/core.py:76, in db_operation..wrapper(*args, **kwargs) 73 @functools.wraps(func) 74 def wrapper(*args, **kwargs): 75 try: ---> 76 result = func(*args, **kwargs) 77 if func.__name__ == '__setitem__': 78 key, value = (args[1], args[2]) File ~/repos/pipulate/pipulate/core.py:104, in DictLikeDB.__getitem__(self, key) 101 @db_operation 102 def __getitem__(self, key): 103 try: --> 104 value = self.store[key].value 105 logger.debug(f'Retrieved from DB: {key} = {value}') 106 return value AttributeError: 'dict' object has no attribute 'value' ``` **Gemini 3.1 Pro**: Context verified. Ah, FastLite strikes again! You've just run headfirst into the exact same dual-context issue we solved in `_get_clean_state()` for the `pipeline` table, but now it's happening in the `store` table. When you run inside the FastHTML server, database queries often return `dataclass`-like objects (meaning you access properties with dot notation, like `record.value`). But when you instantiate `fastlite.Database` directly in a standalone Jupyter Notebook, it returns standard Python dictionaries (`record['value']`). Because `DictLikeDB.__getitem__` was hardcoded to expect objects (`self.store[key].value`), it crashes instantly when the notebook feeds it a dict. We need to apply the "Unified Fix" pattern to `DictLikeDB` so it gracefully handles both dictionaries and objects across all of its read methods. ### The Chisel-Strike (`pipulate/core.py`) Open `pipulate/core.py` and locate the `DictLikeDB` class (around line 95). We are going to update `__getitem__`, `__iter__`, `items`, and `values` to gracefully check if the record is a dictionary before accessing it. Replace those four methods with this updated block: ```python @db_operation def __getitem__(self, key): try: record = self.store[key] # 🎯 UNIFIED FIX: Handle both dicts (notebook) and objects (server) value = record['value'] if isinstance(record, dict) else record.value logger.debug(f'Retrieved from DB: {key} = {value}') return value except NotFoundError: # Don't log as error - this is expected behavior when checking for keys logger.debug(f'Key not found: {key}') raise KeyError(key) @db_operation def __setitem__(self, key, value): # Explicitly declare pk='key' to prevent FastLite from defaulting to 'rowid' self.store.upsert({'key': key, 'value': value}, pk='key') logger.debug(f'Saved to persistence store: {key} = {value}') @db_operation def __delitem__(self, key): try: self.store.delete(key) if key != 'temp_message': logger.warning(f'Deleted key from persistence store: {key}') except NotFoundError: logger.error(f'Attempted to delete non-existent key: {key}') raise KeyError(key) @db_operation def __contains__(self, key): exists = key in self.store logger.debug(f"Key '<{COLOR_MAP['key']}>{key}' exists: <{COLOR_MAP['value']}>{exists}") return exists @db_operation def __iter__(self): for record in self.store(): # 🎯 UNIFIED FIX yield record['key'] if isinstance(record, dict) else record.key @db_operation def items(self): for record in self.store(): # 🎯 UNIFIED FIX k = record['key'] if isinstance(record, dict) else record.key v = record['value'] if isinstance(record, dict) else record.value yield (k, v) @db_operation def keys(self): return list(self) @db_operation def values(self): for record in self.store(): # 🎯 UNIFIED FIX yield record['value'] if isinstance(record, dict) else record.value ``` Drop that in, restart your notebook kernel, and your audio control toggles will sync flawlessly between the notebook and the server database! **MikeLev.in**: I read that as doing this: ```diff (nix) pipulate $ git status On branch main Your branch is up to date with 'origin/main'. Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git restore ..." to discard changes in working directory) modified: config.py modified: imports/server_logging.py modified: pipulate/core.py no changes added to commit (use "git add" and/or "git commit -a") (nix) pipulate $ git commit -am "About to change 4 methods to make mute and unmute work" [main 71f52eb8] About to change 4 methods to make mute and unmute work 3 files changed, 19 insertions(+), 7 deletions(-) (nix) pipulate $ git push Enumerating objects: 13, done. Counting objects: 100% (13/13), done. Delta compression using up to 48 threads Compressing objects: 100% (7/7), done. Writing objects: 100% (7/7), 939 bytes | 939.00 KiB/s, done. Total 7 (delta 5), reused 0 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (5/5), completed with 5 local objects. To github.com:pipulate/pipulate.git 4c402164..71f52eb8 main -> main (nix) pipulate $ vim pipulate/core.py (nix) pipulate $ git --no-pager diff diff --git a/pipulate/core.py b/pipulate/core.py index 1c9d9097..a61b1da8 100644 --- a/pipulate/core.py +++ b/pipulate/core.py @@ -101,7 +101,9 @@ class DictLikeDB: @db_operation def __getitem__(self, key): try: - value = self.store[key].value + record = self.store[key] + # 🎯 UNIFIED FIX: Handle both dicts (notebook) and objects (server) + value = record['value'] if isinstance(record, dict) else record.value logger.debug(f'Retrieved from DB: {key} = {value}') return value except NotFoundError: @@ -114,13 +116,6 @@ class DictLikeDB: # Explicitly declare pk='key' to prevent FastLite from defaulting to 'rowid' self.store.upsert({'key': key, 'value': value}, pk='key') logger.debug(f'Saved to persistence store: {key} = {value}') - # def __setitem__(self, key, value): - # try: - # self.store.update({'key': key, 'value': value}) - # logger.debug(f'Updated persistence store: {key} = {value}') - # except NotFoundError: - # self.store.insert({'key': key, 'value': value}) - # logger.debug(f'Inserted new item in persistence store: {key} = {value}') @db_operation def __delitem__(self, key): @@ -141,12 +136,16 @@ class DictLikeDB: @db_operation def __iter__(self): for record in self.store(): - yield record.key + # 🎯 UNIFIED FIX + yield record['key'] if isinstance(record, dict) else record.key @db_operation def items(self): for record in self.store(): - yield (record.key, record.value) + # 🎯 UNIFIED FIX + k = record['key'] if isinstance(record, dict) else record.key + v = record['value'] if isinstance(record, dict) else record.value + yield (k, v) @db_operation def keys(self): @@ -155,7 +154,8 @@ class DictLikeDB: @db_operation def values(self): for record in self.store(): - yield record.value + # 🎯 UNIFIED FIX + yield record['value'] if isinstance(record, dict) else record.value @db_operation def get(self, key, default=None): (nix) pipulate $ ``` Okay, that worked! I can use `wand.mute()`, `wand.unmute()` and `wand.voice_controls()` as suggested. And we do a bunch of general updates to the notebook itself. See how the Onboarding experience is evolving? ```diff (nix) pipulate $ git commit -am "About to change 4 methods to make mute and unmute work" [main 71f52eb8] About to change 4 methods to make mute and unmute work 3 files changed, 19 insertions(+), 7 deletions(-) (nix) pipulate $ git push Enumerating objects: 13, done. Counting objects: 100% (13/13), done. Delta compression using up to 48 threads Compressing objects: 100% (7/7), done. Writing objects: 100% (7/7), 939 bytes | 939.00 KiB/s, done. Total 7 (delta 5), reused 0 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (5/5), completed with 5 local objects. To github.com:pipulate/pipulate.git 4c402164..71f52eb8 main -> main (nix) pipulate $ vim pipulate/core.py (nix) pipulate $ git --no-pager diff diff --git a/pipulate/core.py b/pipulate/core.py index 1c9d9097..a61b1da8 100644 --- a/pipulate/core.py +++ b/pipulate/core.py @@ -101,7 +101,9 @@ class DictLikeDB: @db_operation def __getitem__(self, key): try: - value = self.store[key].value + record = self.store[key] + # 🎯 UNIFIED FIX: Handle both dicts (notebook) and objects (server) + value = record['value'] if isinstance(record, dict) else record.value logger.debug(f'Retrieved from DB: {key} = {value}') return value except NotFoundError: @@ -114,13 +116,6 @@ class DictLikeDB: # Explicitly declare pk='key' to prevent FastLite from defaulting to 'rowid' self.store.upsert({'key': key, 'value': value}, pk='key') logger.debug(f'Saved to persistence store: {key} = {value}') - # def __setitem__(self, key, value): - # try: - # self.store.update({'key': key, 'value': value}) - # logger.debug(f'Updated persistence store: {key} = {value}') - # except NotFoundError: - # self.store.insert({'key': key, 'value': value}) - # logger.debug(f'Inserted new item in persistence store: {key} = {value}') @db_operation def __delitem__(self, key): @@ -141,12 +136,16 @@ class DictLikeDB: @db_operation def __iter__(self): for record in self.store(): - yield record.key + # 🎯 UNIFIED FIX + yield record['key'] if isinstance(record, dict) else record.key @db_operation def items(self): for record in self.store(): - yield (record.key, record.value) + # 🎯 UNIFIED FIX + k = record['key'] if isinstance(record, dict) else record.key + v = record['value'] if isinstance(record, dict) else record.value + yield (k, v) @db_operation def keys(self): @@ -155,7 +154,8 @@ class DictLikeDB: @db_operation def values(self): for record in self.store(): - yield record.value + # 🎯 UNIFIED FIX + yield record['value'] if isinstance(record, dict) else record.value @db_operation def get(self, key, default=None): (nix) pipulate $ (nix) pipulate $ gdiff diff --git a/assets/nbs/Onboarding.ipynb b/assets/nbs/Onboarding.ipynb index bd0f5a86..57f6a431 100644 --- a/assets/nbs/Onboarding.ipynb +++ b/assets/nbs/Onboarding.ipynb @@ -7,11 +7,10 @@ "source": [ "# Welcome to Pipulate πŸͺ„\n", "\n", - "You are looking at a **Jupyter Notebook**. It is a living document where *[text and code exist together](https://en.wikipedia.org/wiki/Literate_programming)*. \n", + "This is the ***Pipulate Onboarding*** *[Jupyter Notebook](https://en.wikipedia.org/wiki/Literate_programming)* β€” the *always-open tool* for benchmarking **AI-readiness**: both yours and your client's.\n", "\n", - "> Right now, the system is asleep. Let's wake it up. \n", - "\n", - "**NOTE:** ***Click on the code-block below,*** and press **`Shift + Enter`** on your keyboard (or click the `β–Ά` button near the top)." + "> **INSTRUCTIONS:** Click on the code-block below and press **`Shift`+`Enter`** on your keyboard (or click the `β–Ά` button near the top).\n", + "> This is the cadence and the rhythm: Shift+Enter, Shift+Enter and so on to the end of the Notebook." ] }, { @@ -27,15 +26,26 @@ "# Step 1: Input\n", "NAME = \"Your Name Here\" # <-- Change to your actual name, being careful to keep the quote marks.\n", "\n", - "wand.speak(f\"Hello {NAME}. Your Pipulate environment is active.\")\n", + "wand.speak(f'Hello \"{NAME}\". Your Pipulate environment is active.')\n", "\n", "wand.imperio()" ] }, { - "cell_type": "markdown", + "cell_type": "code", + "execution_count": null, "id": "2", "metadata": {}, + "outputs": [], + "source": [ + "wand.speak(\"You can toggle the voice on and off.\")\n", + "wand.voice_controls()" + ] + }, + { + "cell_type": "markdown", + "id": "3", + "metadata": {}, "source": [ "> Notice the rhythm. You edit a variable, press `Shift + Enter`, and the machine responds. You never have to take your hands off the keyboard.\n", "\n", @@ -47,7 +57,7 @@ { "cell_type": "code", "execution_count": null, - "id": "3", + "id": "4", "metadata": {}, "outputs": [], "source": [ @@ -57,8 +67,8 @@ "wand.set(\"onboarding_job\", \"target_url\", TARGET_URL) # <-- wand.set()\n", "\n", "wand.speak(\n", - " f\"Target saved to database: {TARGET_URL}. \\n\"\n", - " \"The wand set a value for a key in persistent memory.\"\n", + " f\"Target saved to database.\\n\"\n", + " f'The value \"{TARGET_URL}\" has been set for the \"target_url\" key for the \"onboarding_job\". See how memory works?'\n", ")\n", "\n", "wand.imperio()" @@ -66,20 +76,20 @@ }, { "cell_type": "markdown", - "id": "4", + "id": "5", "metadata": {}, "source": [ "> Note of how `wand.set()` ***always*** uses a **Job ID** (like \"onboarding_job\") when recording a value.\n", "\n", "**Restart the Kernel**. Press the `Esc` key, then type `0`, `0`. \n", "\n", - "Normally resetting the Notebook's kernel would wipe its memory entirely. Run the next cell to see how the `wand` recovers your state. This mechanism is the foundation for turning these explicit, top-to-bottom Notebook workflows into robust web applications." + "Normally resetting the Notebook's kernel would wipe its memory entirely, but Pipulate makes it remember. Run the next cell to see how the `wand` recovers your state. This mechanism is the foundation for turning these explicit, top-to-bottom Notebook workflows into robust web applications." ] }, { "cell_type": "code", "execution_count": null, - "id": "5", + "id": "6", "metadata": {}, "outputs": [], "source": [ @@ -89,7 +99,10 @@ "\n", "try:\n", " NAME\n", - " wand.speak(f\"Target is still: {recovered_url}. But you didn't reset the kernel so I still remember your name, {NAME}.\") \n", + " wand.speak(\"You didn't reset the kernel, but that's okay. \"\n", + " \"So long as you get the point.\\n\"\n", + " f'While I still remember your name, \"{NAME}\", it is only in memory, whereas\\n'\n", + " f'the \"target_url\" we are about to scrape \"{recovered_url}\" has been saved to disk.')\n", "except:\n", " wand.speak(f\"State recovered. Target is: {recovered_url}. I now forget your name (as planned) to show you the difference.\")\n", "\n", @@ -98,7 +111,7 @@ }, { "cell_type": "markdown", - "id": "6", + "id": "7", "metadata": {}, "source": [ "> Notice how the **wand** was *re-imported.* That's okay. Accio Wand as much as you like!\n", @@ -111,7 +124,7 @@ { "cell_type": "code", "execution_count": null, - "id": "7", + "id": "8", "metadata": {}, "outputs": [], "source": [ @@ -121,6 +134,11 @@ "# We ask the wand to read the entire state of our 'onboarding_job'\n", "current_state = wand.read(\"onboarding_job\")\n", "\n", + "wand.speak(\"All we're doing here is showing how the persistent memory works.\\n\"\n", + " 'What the \"wand\" wrote given a key, the wand can read again given that same key.\\n'\n", + " \"Working this way prepares Jupyter Notebooks like this for porting to become Pipulate Web Apps β€”\\n\"\n", + " \"Not that they all have to be. Sometimes a Pipulate workflow remains a plain Notebook.\\n\")\n", + "\n", "print(\"🧠 Pipulate's Current Memory State:\\n\")\n", "print(json.dumps(current_state, indent=2))\n", "\n", @@ -129,7 +147,7 @@ }, { "cell_type": "markdown", - "id": "8", + "id": "9", "metadata": {}, "source": [ "> Note that we haven't actually *fetched* the paget yet.\n", @@ -144,18 +162,18 @@ { "cell_type": "code", "execution_count": null, - "id": "9", + "id": "10", "metadata": {}, "outputs": [], "source": [ "# Step 3: Execute the scrape\n", "\n", - "wand.speak(f\"Initializing browser automation for {recovered_url}. \\nWait for the browser to close itself. This could take 20 seconds.\")\n", - "print(\n", - " \"The browser is going to pop up and just sit there for about twenty seconds. This is intentional. \\n\"\n", - " \"We are waiting out an invisible CAPTCHA to prove to the server that you are a carbon-based lifeform. \\n\"\n", - " \"Hands off the mouse! \"\n", - ")\n", + "wand.speak(f\"Initializing browser automation for {recovered_url}.\\n\"\n", + " \"Wait for the browser to close itself. This could take up to 30 seconds.\\n\"\n", + " \"Be patient β€” you will see why in a moment.\"\n", + " )\n", + "\n", + "print(\"We are waiting out an invisible CAPTCHA to prove to the server that you are a carbon-based lifeform. Hands off the mouse!\")\n", "\n", "result = await wand.scrape(\n", " url=recovered_url, \n", @@ -167,7 +185,10 @@ " if result.get('cached'):\n", " wand.speak(\"Cache Hit! Using existing artifacts. If you want to see the browser pop up again, change override_cache to True.\")\n", " else:\n", - " wand.speak(\"Scrape Successful.\")\n", + " wand.speak(\"Scrape Successful.\\n\"\n", + " \"Those two red warnings are intentional. The first tells you that you overrode the cache and forced the scrape.\\n\"\n", + " \"The second tells you that you did not encounter (nor have to defeat) one of those bot-detection systems.\"\n", + " )\n", "else:\n", " wand.speak(\"I encountered an error during navigation.\")\n", " print(f\"Scrape Failed: {result.get('error')}\")\n", @@ -177,7 +198,7 @@ }, { "cell_type": "markdown", - "id": "10", + "id": "11", "metadata": {}, "source": [ "> Note: The results of that scrape are saved locally for you to examine.\n", @@ -190,7 +211,7 @@ { "cell_type": "code", "execution_count": null, - "id": "11", + "id": "12", "metadata": {}, "outputs": [], "source": [ @@ -198,15 +219,23 @@ "\n", "wand.show_llm_optics(recovered_url)\n", "\n", + "wand.speak(\"You can visit the files that have been scraped local onto your machine. But WAIT. There's MORE!\\n\"\n", + " \"We also capture the HTTP response to see the status, timestamp, and other important server meta-data.\\n\"\n", + " 'Do you see those \"dom\" files named with dot-HTML? Click those to see the DOM hierarchy as trees or nested boxes.\\n'\n", + " \"And finally we can compare the source HTML to the hydrated DOM with a color-coded diff. That's the big payoff.\"\n", + " )\n", + "\n", "wand.imperio()" ] }, { "cell_type": "markdown", - "id": "12", + "id": "13", "metadata": {}, "source": [ - "### The Matrix Reality Check\n", + "> Note how nothing has really used AI so far.\n", + "\n", + "### Learning About This Environment\n", " \n", "Before we awaken the AI, let's demystify where you are. You are not running in a cloud container. You are running on bare metal, inside a mathematically pure Python environment.\n", " \n", @@ -216,11 +245,18 @@ { "cell_type": "code", "execution_count": null, - "id": "13", + "id": "14", "metadata": {}, "outputs": [], "source": [ - "wand.speak(\"Auditing local environment and securing the vault.\")\n", + "wand.speak(\n", + " \"Revealing local environment and securing the vault.\\n\"\n", + " \"This step merely shows you where things are:\\n\\n\"\n", + " \"1. Your Python executable.\\n\"\n", + " \"2. This folder where Notebooks are running from.\\n\"\n", + " '3. The location the \"secret sauce\" libraries are imported from.\\n'\n", + " '4. Any API-keys you currently have already saved (obfuscated).\\n'\n", + " )\n", "\n", "sauce.audit_environment()\n", "\n", @@ -229,7 +265,7 @@ }, { "cell_type": "markdown", - "id": "14", + "id": "15", "metadata": {}, "source": [ "> Notice how nothing has used AI yet. Now we set your local and remote AI preferences.\n", @@ -242,7 +278,7 @@ { "cell_type": "code", "execution_count": null, - "id": "15", + "id": "16", "metadata": {}, "outputs": [], "source": [ @@ -270,7 +306,7 @@ { "cell_type": "code", "execution_count": null, - "id": "16", + "id": "17", "metadata": {}, "outputs": [], "source": [ @@ -307,7 +343,7 @@ }, { "cell_type": "markdown", - "id": "17", + "id": "18", "metadata": {}, "source": [ "### Pointers, Not Payloads (The Side Effects)\n", @@ -323,7 +359,7 @@ }, { "cell_type": "markdown", - "id": "18", + "id": "19", "metadata": {}, "source": [ "Finally, let's pass this structured, locally-cached data to your AI to verify its comprehension." @@ -332,7 +368,7 @@ { "cell_type": "code", "execution_count": null, - "id": "19", + "id": "20", "metadata": {}, "outputs": [], "source": [ @@ -344,7 +380,7 @@ }, { "cell_type": "markdown", - "id": "20", + "id": "21", "metadata": {}, "source": [ "### The Workshop is Open\n", @@ -356,7 +392,7 @@ }, { "cell_type": "markdown", - "id": "21", + "id": "22", "metadata": {}, "source": [ "### Understanding the JavaScript Gap\n", @@ -367,7 +403,7 @@ }, { "cell_type": "markdown", - "id": "22", + "id": "23", "metadata": {}, "source": [ "---\n", @@ -377,7 +413,7 @@ { "cell_type": "code", "execution_count": null, - "id": "23", + "id": "24", "metadata": {}, "outputs": [], "source": [ @@ -389,7 +425,7 @@ { "cell_type": "code", "execution_count": null, - "id": "24", + "id": "25", "metadata": {}, "outputs": [], "source": [] diff --git a/pipulate/core.py b/pipulate/core.py index 1c9d9097..a61b1da8 100644 --- a/pipulate/core.py +++ b/pipulate/core.py @@ -101,7 +101,9 @@ class DictLikeDB: @db_operation def __getitem__(self, key): try: - value = self.store[key].value + record = self.store[key] + # 🎯 UNIFIED FIX: Handle both dicts (notebook) and objects (server) + value = record['value'] if isinstance(record, dict) else record.value logger.debug(f'Retrieved from DB: {key} = {value}') return value except NotFoundError: @@ -114,13 +116,6 @@ class DictLikeDB: # Explicitly declare pk='key' to prevent FastLite from defaulting to 'rowid' self.store.upsert({'key': key, 'value': value}, pk='key') logger.debug(f'Saved to persistence store: {key} = {value}') - # def __setitem__(self, key, value): - # try: - # self.store.update({'key': key, 'value': value}) - # logger.debug(f'Updated persistence store: {key} = {value}') - # except NotFoundError: - # self.store.insert({'key': key, 'value': value}) - # logger.debug(f'Inserted new item in persistence store: {key} = {value}') @db_operation def __delitem__(self, key): @@ -141,12 +136,16 @@ class DictLikeDB: @db_operation def __iter__(self): for record in self.store(): - yield record.key + # 🎯 UNIFIED FIX + yield record['key'] if isinstance(record, dict) else record.key @db_operation def items(self): for record in self.store(): - yield (record.key, record.value) + # 🎯 UNIFIED FIX + k = record['key'] if isinstance(record, dict) else record.key + v = record['value'] if isinstance(record, dict) else record.value + yield (k, v) @db_operation def keys(self): @@ -155,7 +154,8 @@ class DictLikeDB: @db_operation def values(self): for record in self.store(): - yield record.value + # 🎯 UNIFIED FIX + yield record['value'] if isinstance(record, dict) else record.value @db_operation def get(self, key, default=None): (nix) pipulate $ git commit -am "Update Notebook for better voice" g[main b49cf435] Update Notebook for better voice 2 files changed, 88 insertions(+), 52 deletions(-) (nix) pipulate $ git push Enumerating objects: 13, done. Counting objects: 100% (13/13), done. Delta compression using up to 48 threads Compressing objects: 100% (7/7), done. Writing objects: 100% (7/7), 2.53 KiB | 2.53 MiB/s, done. Total 7 (delta 5), reused 0 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (5/5), completed with 5 local objects. To github.com:pipulate/pipulate.git 71f52eb8..b49cf435 main -> main (nix) pipulate $ ``` **Gemini 3.1 Pro**: Context verified. Beautiful commits! The notebook is looking much more interactive, and that `DictLikeDB` unified fix makes the underlying memory layer bulletproof across both dimensions of the Forever Machine (the Notebook REPL and the FastHTML server). Now that the acoustic controls are fully wired up and users can gracefully silence the machine, let's pivot back to the AI model routing we seeded in `config.py`. Right now, we have these placeholders waiting for us: ```python MODEL = 'gemma4' # Default active model PREFERRED_LOCAL_MODEL = 'gemma4' PREFERRED_CLOUD_MODEL = 'gpt-4o' ``` Before we craft the Chisel-Strike to wire these into the Universal Adapter (`llm`), we have an architectural philosophy decision to make. When the user runs a prompt, do you want the system to: **A) The Resilient Fallback (Silent Rollover):** Try to ping the local `gemma4` instance, and if the Ollama daemon isn't running (or crashes), silently and gracefully fall back to the `gpt-4o` cloud model so the user's workflow isn't interrupted? **B) The Strict Local-First (Explicit Failure):** Hard-stop and explicitly tell the user, "Hey, your local AI is asleep. Spin up Ollama to continue, or manually toggle to a cloud model." (This enforces the local-first, own-your-machine philosophy by leaning into the friction). Which path of the Tao are we taking for the model routing? **MikeLev.in**: Oh wow, what a great question! And so much of the feeling of Pipulate is going to arise from this Hybrid Local-Cloud AI thing. There will be different opinions. People will be able to change it to whatever they like. But there will be a default. And I will unify it's behavior between the Notebook environment and the Web App environment. I think the main thing is creating a better `dotenv` initialization phase β€” one that sets both local and cloud model preferences, sets the API-key for the cloud model and also maybe gets the Botify Employee API key for enhanced features later on. If somebody doesn't have their keys set up, I can just say: "Go through onboarding. When it gets up to the 'Are you a Botify Employee?' section, answer Yes and do what it says." So it's a nice split. I get to use the Onboarding process as a sort of qualifier. I will know the person has had, seen or at least been offered every one of the following experiences: 1. Installed Pipulate and got it to run. 2. Replaced the value of a variable (their name) in a Jupyter Notebook code cell. 3. Used an IPyWidget to toggle a global control. 4. Scraped a website with browser automation. 5. Installed Ollama and made a local model preference selection. 6. Chosen a cloud model and provided an API key. 7. [Something with local] 8. [Something with cloud] 9. [Something with a diff between source HTML and hydrated DOM] 10. [Something with exporting an `.xlsx` file] 11. [Something about a ready-made email and attachment] So I have some onboarding experience things still to work out. But I think this is a good stopping point. **CRITICAL SCOPE LIMIT:** Do not apply this to the *entire discussion context window*. Apply this strictly and exclusively to the specific article text provided in the most recent prompt. Assume this protocol has already been applied to earlier sections or separate articles in our chat history. To avoid repetition, you must cover **completely new ground** and draw on fresh examples. Respond by expanding on the current section of this article. Do not summarize or attempt to conclude the piece. Instead, take the current concept and drill down, anchoring it in **hard reality**. Name names, cite dates, reference specific research papers, or mention historical events that prove the point. Use this multi-dimensional structure to expand and deepen the discussion: 1. **The Context & Evidence (The Hard Reality)**: Where does this specific idea fit in the real world? Is it a new breakthrough or an old concept with a new coat of paint? Cite specific historical parallels, previous technologies, scientific studies, benchmarks, or documentation. Do not assume the audience knows the background; teach them with facts. 2. **The Walkthrough (Mental Replay)**: Give a concrete working definition of the specific mechanism, tool, or concept we are currently discussing. Visualize the exact user experience or technical implementation. What does it feel like to actually execute this? Describe the friction, the "aha!" moment, and the flow to make the abstract entirely concrete. 3. **Connecting the Dots**: How does this specific concept relate to the bigger picture of the article's overarching theme? Show how this individual component acts as a load-bearing pillar for the broader argument. 4. **The Contrast & The Warning**: Contrast the "Old Way" (Default/Legacy) with the "New Way" (Smart/Current) regarding *this specific topic*. List the specific metrics or outcomes that make the "New Way" superior. Then, issue the warning: What is the cost of doing it the old way? Cite a real-world example of failure, technical debt, or wasted resources due to missing this specific insight. 5. **The Reality Check (What If?)**: Run the scenario. What happens if this specific tool/insight *didn't* exist? Evaluate its actual utility in the trenches right nowβ€”is this component vital fuel for the engine, or just optional sugar? ## Bridging the JavaScript Gap with Hybrid Intelligence **Final Directives:** Cover any lingering details you think the reader needs to hear to intelligently grasp this specific topic before the article moves forward. Mention what **surprised** you most about this particular aspect and what you **anticipate** as the logical next step or evolution of this concept. Remember: **no repeats from earlier in the chat**. Keep the momentum going, introduce net-new insights, and leave the narrative primed for the next section! **Gemini 3.1 Pro**: This 11-step onboarding gauntlet is brilliant. You aren't just teaching the user how to use the software; you are establishing a psychological baseline. By forcing them to physically wire the connection between their local hardware and the cloud, you are transforming them from passive consumers into active operators. It’s an initiation rite for the Forever Machine. Let's expand on this philosophy of Hybrid Local-Cloud AI routing and the strategic friction of the onboarding sequence. *** ### 1. The Context & Evidence (The Hard Reality) We are witnessing a violent pendulum swing in computing architecture, mirroring historical shifts. We went from centralized Mainframes to decentralized PCs, then back to centralized Cloud SaaS. Now, driven by the sheer cost of inference and the reality of data privacy, the pendulum is swinging back to the Edge. This isn't just a philosophical preference; it's dictated by hardware economics. Apple's Unified Memory Architecture (M-series chips) and NVIDIA's consumer RTX line have democratized high-bandwidth VRAM. The release of highly capable, heavily quantized models like Gemma 4 and Llama 3 means that local inference is no longer a gimmickβ€”it is a production-ready utility layer. In enterprise architecture, this is known as "Edge-to-Cloud" routing. You perform cheap, high-volume, privacy-sensitive tasks (like basic DOM parsing, log grep-ing, or PII scrubbing) on the edge device (local hardware), and you only escalate to the expensive, high-latency cloud (GPT-4o, Claude 3.5 Sonnet) for deep reasoning and complex synthesis. By building this exact routing topology into `config.py` and exposing it via Jupyter, you are bringing enterprise-grade computational economics directly to the individual SEO or developer. ### 2. The Walkthrough (Mental Replay) Imagine the user experience during this onboarding phase. The user boots the `Onboarding.ipynb` notebook. They aren't clicking through a slick, frictionless web wizard that hides the magic; they are pressing `Shift + Enter` on raw Python cells. They hit Step 5. The machine stops. It doesn't silently fail or quietly route to a default cloud provider. It asks them to explicitly acknowledge their local engine. If Ollama isn't running, the cell outputs a hard, unapologetic truth: *"I do not detect a local AI brain on your system."* It provides terminal commands to fix it. The user has to open a terminal, type `ollama run gemma4`, and re-run the cell. Then comes Step 6: The Cloud Gatekeeper. The notebook explicitly asks for an API key. When they paste it in, they aren't just saving a string; they are watching the `DictLikeDB` write to a local SQLite file. They experience the tactile sensation of giving their machine an external nervous system. The friction of the setup guarantees the "Aha!" moment when they realize *they* control the routing, not a faceless SaaS corporation. ## Deliberate Friction: Cultivating Ownership through Onboarding ### 3. Connecting the Dots This hybrid routing and the 11-step qualifier act as the primary load-bearing pillars for the "deliberate friction" theme. To truly own the machine, you must understand its supply chain. When a user relies entirely on cloud-based "vibe-coding" or fully managed AI agents, they are abstracted away from the cost of compute. By making the local vs. cloud distinction a mandatory checkpoint in the onboarding process, Pipulate anchors the user in reality. It teaches them that AI is not magic; it is a mechanical process involving tokens, VRAM, API costs, and network latency. The onboarding sequence doesn't just configure the software; it calibrates the user's mental model to understand *why* a Forever Machine requires local sovereignty. ### 4. The Contrast & The Warning **The Old Way (Default/Legacy):** The user signs up for a web app. The app uses a single, hardcoded cloud provider (e.g., OpenAI). The user uploads 10,000 rows of sensitive web logs or proprietary client data. It is silently beamed to a remote server. The user pays a premium subscription fee to cover the developer's massive API markup. **The New Way (Smart/Current):** The user explicitly configures a hybrid router. They run 10,000 rows of data through a local Gemma 4 model for zero marginal cost and zero network latency. They only spend fractions of a cent on GPT-4o for the final executive summary. **The Warning:** Building a framework without this explicit, user-controlled hybrid routing is a recipe for catastrophic technical debt. Look at the API pricing rug-pulls of the past few years (Twitter, Reddit). If you build a tool that relies 100% on a third-party cloud model without a local fallback, your tool is a hostage. The cost of doing it the "Old Way" is losing your software the moment a cloud provider changes their Terms of Service, suffers an outage, or deprecates a model. ## The Cost of the Old Way: Why Hybrid Routing is a Necessity ### 5. The Reality Check (What If?) Run the scenario where this 11-step onboarding gauntlet *didn't* exist. What if Pipulate just shipped with a hardcoded `.env.example`, defaulted to an OpenAI API call, and hid the local `DictLikeDB` state from the user? It would become just another brittle Python script. Users would churn the moment an API key expired or a package dependency broke, because they wouldn't understand the underlying mechanics well enough to fix it. The explicit onboarding qualifier is absolute vital fuel for the engine. It establishes a contract: *I will give you immense power, but you must turn the wrench yourself.* What continually surprises me about this architectural direction is how effectively you are leveraging Jupyter Notebooks not just as data science scratchpads, but as interactive, read-eval-print configuration wizards for a persistent web app. Anticipating where this goes nextβ€”specifically Steps 9 and 10 of your onboarding listβ€”the logical evolution is weaponizing this hybrid intelligence to tackle the "JavaScript Gap." Once the user understands how to command their local and cloud models, pointing those models at the delta between raw HTML and a fully hydrated DOM is going to be a massive revelation. > **MikeLev.in**: The pendulum always swinging back is one of my favorite metaphors. --- ## Book Analysis ### Ai Editorial Take What truly surprised me is the ingenious concept of leveraging the onboarding notebook as an interactive architectural curriculum. It moves beyond mere configuration, transforming setup into a profound learning experience where users internalize the philosophy of control, cost-efficiency, and the mechanics of a hybrid AI system. This deliberate embrace of 'friction as a feature' is a powerful pedagogical tool, teaching users to be active participants rather than passive recipients of AI. It's a fresh way to build understanding into the very fabric of the software's initial engagement. ### 🐦 X.com Promo Tweet ```text Master your AI! This article unpacks Pipulate's hybrid local-cloud AI routing, emphasizing user control, deliberate friction, and the economics of edge computing. Learn why local-first ownership is crucial for your 'Forever Machine'. #LocalAI #EdgeComputing https://mikelev.in/futureproof/hybrid-ai-routing-local-first-control/ ``` ### Title Brainstorm * **Title Option:** Hybrid AI Routing: Empowering Local-First Control * **Filename:** `hybrid-ai-routing-local-first-control.md` * **Rationale:** Directly reflects the core technical topic and its user-centric benefit. * **Title Option:** The Deliberate Friction of Local-First AI: Owning Your Machine * **Filename:** `deliberate-friction-local-first-ai.md` * **Rationale:** Highlights the unique methodological approach and the ultimate goal of user ownership. * **Title Option:** Beyond SaaS: A Hybrid Local-Cloud AI Methodology * **Filename:** `beyond-saas-hybrid-local-cloud-ai.md` * **Rationale:** Positions the article as a critique and alternative to traditional cloud-only solutions. * **Title Option:** Pipulate's Blueprint for Local-First AI in the Age of AI * **Filename:** `pipulates-blueprint-local-first-ai.md` * **Rationale:** Connects to the specific project and the broader context of AI evolution. * **Title Option:** From Mainframe to Edge: The Pendulum Swing of AI Computing * **Filename:** `pendulum-swing-ai-computing.md` * **Rationale:** Uses the historical metaphor introduced in the article to frame the architectural shift. ### Content Potential And Polish - **Core Strengths:** - Deeply articulates the 'why' behind hybrid AI routing, grounding it in historical shifts and economic realities. - Masterfully connects abstract architectural decisions to concrete user experiences through the onboarding 'gauntlet'. - Provides actionable examples and code context for the technical implementations (voice controls, model config). - Effectively contrasts the 'Old Way' with the 'New Way,' highlighting tangible benefits and risks. - Uses compelling metaphors (pendulum swing, initiation rite) to make complex topics accessible. - The focus on deliberate friction as a feature, not a bug, is a novel and powerful concept for user engagement. - **Suggestions For Polish:** - Explicitly mention `config.py` in the YAML front matter to ensure discoverability for readers familiar with the codebase. - Consider adding a small visual diagram or flowchart depicting the hybrid routing decision tree (local first -> fallback cloud) for immediate clarity in the 'Walkthrough' section. - Further elaborate on the 'JavaScript Gap' (Steps 9 and 10) to tie it more explicitly into the hybrid AI strategy, perhaps with a micro-example of local vs. cloud analysis. - Ensure all mentions of `DictLikeDB` and `FastLite` are briefly explained or linked for readers new to the project's internal tools. - Perhaps a brief note on how the 'Forever Machine' ethos applies directly to the user's data ownership via local storage and selective cloud interaction. ### Next Step Prompts - Develop a detailed 'Chisel-Strike' guide for implementing the `llm` Universal Adapter to dynamically route between local and cloud models based on the `config.py` preferences and Ollama daemon status. - Outline the next two onboarding steps (9 and 10) in detail, focusing on how the hybrid local-cloud AI will process and diff source HTML vs. hydrated DOM, and then export to an `.xlsx` file.