By Mike Levin

Late Night Refactoring Session

It’s Saturday night now. I had something of a nap. And I want to get this little core piece done before tomorrow. I don’t want to be stuck on stuff like this through the whole weekend. It’s a bit of refactoring, but it makes the LLM chatbot integration and full situational awareness by the LLM of the use of the app through the plugins. I lay out the situation for Claude and ask for a plan.

Global vs Plugin Scope Challenge

I already integrated the local Ollama LLM into what you would call the global scope in Python, but now that I’ve extracted both the Linear Workflows and the CRUD Database apps into a plugin system, the LLM integration stopped working. Technically, the communication-wiring of the chat feature (WebSockets and stuff) works everywhere. And the all areas of the program have the chat window working, plus “scripted” (fake) LLM streaming working.

The Core Issue: Global Context and Plugins

But the ability genuine LLM output stopped working because the part that pumps the Ollama data-stream into the websockets is in a global context – not shared by plugins! So, it’s the story of dependency-injection.

[Pumps a lot of context into Claude]

Claude’s Three-Point Plan

There’s copious prior articles on this if you want full context. I’m not going to repeat it here, but I did gather it up and plop it in, spelling out the 2 different ways I inject dependencies from global to plugins, asking for a plan to unify.

Claude 3.7 Sonnet:

<think> Let’s analyze the current state and form a plan:

1. The issue with pipeline_operation decorator is one of the specific technical problems, but the fundamental issue is that there’s a mix of dependency patterns:
   • Some code uses global imports
   • Some code uses dependency injection
   • The BaseCrud class calls global functions that use global objects
   • The Pipulate class seems to be a central coordination point
2. We need a clear “one true way” system architecture:
   • Make Pipulate the central coordination class
   • Have Pipulate handle all chat functionality
   • Make BaseCrud take a Pipulate instance directly
   • Use dependency injection consistently
3. Let’s organize the solution into clear steps:
   1. Understand the role of each component and their relationships
   2. Move chat functionality into Pipulate
   3. Have BaseCrud take a Pipulate instance
   4. Update all CRUD apps (internal and plugin) to use this pattern
   5. Ensure all necessary methods are exposed through Pipulate

For clarity, we should focus on explaining the architecture in a story-telling way and then provide specific code changes. </think>

A Coherent Plan for “The One True Way”

Let me tell the story of how your system should work with a clear, consistent architecture:

The Story

1. Pipulate is the Central Hub:
   • Pipulate handles chat communication and serves as a central coordinator
   • All plugins receive a reference to the Pipulate instance
   • No direct imports of chat functionality
2. BaseCrud Uses Pipulate Directly:
   • BaseCrud takes a Pipulate instance as a constructor parameter
   • When BaseCrud needs to communicate, it calls methods on its Pipulate instance
   • No global chatq function calls
3. All Plugins Use Dependency Injection:
   • Both Workflows and CRUD apps receive their dependencies
   • Everything flows through the object graph, not through imports

The Implementation Plan

Step 1: Enhance Pipulate with Chat Functionality

class Pipulate:
    def __init__(self, pipeline_table, chat_instance=None):
        self.pipeline_table = pipeline_table
        self.chat = chat_instance  # Store reference to chat
        
    async def stream(self, message, verbatim=True, role="user", spaces_before=None, spaces_after=None):
        """Replace chatq functionality"""
        try:
            # Add to conversation history
            conversation_history = append_to_conversation(message, role)
            
            if verbatim:
                if spaces_before and self.chat:
                    await self.chat.broadcast("<br>" * spaces_before)
                    
                # Stream the verbatim message
                if self.chat:
                    await self.chat.broadcast(message)
                    
                if spaces_after and self.chat:
                    await self.chat.broadcast("<br>" * spaces_after)
                    
                response_text = message
            else:
                # Process through LLM
                response_text = ""
                if spaces_before and self.chat:
                    await self.chat.broadcast("<br>" * spaces_before)
                    
                async for chunk in chat_with_llm(MODEL, conversation_history):
                    if self.chat:
                        await self.chat.broadcast(chunk)
                    response_text += chunk
                    
                if spaces_after and self.chat:
                    await self.chat.broadcast("<br>" * spaces_after)
                    
            # Add response to conversation
            append_to_conversation(response_text, "assistant")
            return message
            
        except Exception as e:
            logger.error(f"Error in stream: {e}")
            traceback.print_exc()
            raise

Step 2: Update Pipulate Initialization

# Initialize chat first
chat = Chat(app, id_suffix="")

# Then initialize pipulate with chat
pipulate = Pipulate(pipeline_table=pipeline, chat_instance=chat)

Step 3: Modify BaseCrud to Use Pipulate

class BaseCrud:
    def __init__(self, name, table, toggle_field=None, sort_field=None, sort_dict=None, pipulate=None):
        self.name = name
        self.table = table
        self.toggle_field = toggle_field
        self.sort_field = sort_field
        self.item_name_field = 'name'
        self.sort_dict = sort_dict or {'id': 'id', sort_field: sort_field}
        
        # Require pipulate
        self.pipulate = pipulate
        if not self.pipulate:
            raise ValueError("pipulate instance is required for BaseCrud")
            
    async def toggle_item(self, request, item_id: int):
        try:
            # Existing code for toggling
            # ...
            
            # Use pipulate instead of global chatq
            action_details = f"The {self.name} item '{item_name}' is now {status_text}."
            asyncio.create_task(self.pipulate.stream(action_details, verbatim=True))
            
            return self.render_item(updated_item)
        except Exception as e:
            # Error handling

Step 4: Update ProfileApp to Use Pipulate

class ProfileApp(BaseCrud):
    def __init__(self, table, pipulate):
        super().__init__(
            name=table.name, 
            table=table, 
            toggle_field='active', 
            sort_field='priority',
            pipulate=pipulate
        )
        # Rest of initialization

# Update initialization code
profile_app = ProfileApp(table=profiles, pipulate=pipulate)

Step 5: Remove Global chatq Function

Now that everything uses pipulate.stream(), you can remove the global chatq function. Any code that was using it directly should be updated to use pipulate.stream() instead.

The Benefits

1. Clarity: One clear path for all chat communication
2. Consistency: All components follow the same pattern
3. Modularity: Components connect through well-defined interfaces
4. Testability: Dependencies can be mocked easily

This approach maintains the flexibility of your plugin system while ensuring all components have access to the functionality they need without relying on global state.

Thinking Required

OMG, this is going to take thought. There’s different kinds of work. There’s kinds of work you can breeze through because shortcuts and heuristics. That’s most things, most of the time. Otherwise, we’d always be collapsing in exhaustion, because really thinking is expensive energy-wise. It’s interesting how much we learn about ourselves as AI advances. One-shot replies become reflective chain-of-reasoning becomes search becomes research, becomes very expensive computationally, energy-footprint and time required.

Me: Okay, I like this plan. Can you draw a mini schema of the core server.py app with its Pipulate helper class, and a todo.py CRUD App plugin with its various conventional classes and a hello_world.py Workflow plugin with its various conventional classes?

[I removed all these M.C. Escher-esque ASCII diagrams and changed my request]

The results of this prompt were hilarious, but would ultimately be too confusing to include here, even for humor value. I don’t know if the challenge was really that hard, or Claude was expressing something about the architecture, haha!

Me: I think this ASCII art is a rabbit hole. Instead, how about we do a Python code sort of schematic. Look at all the important functions and classes and put them in a very simplified Python-looking function calls and class instantiations that gets the architecture components, relationships and dependencies down. Keep in mind you’re going to do two. One that represents the way it is now. And another that shows what we’re moving to.

Claude: <think> This is a great suggestion. Let me create simplified Python-like schematics to represent the current architecture and the target architecture. I’ll focus on key class instantiations, function calls, and dependencies.

For the current architecture, it seems:

1. Components in server.py are directly imported in plugins
2. There’s a mixture of dependency injection and direct imports
3. Chat functionality is accessed via global functions like chatq()

For the target architecture:

1. All dependencies will be passed via constructors (dependency injection)
2. No direct imports of server.py components in plugins
3. All chat functionality will flow through the Pipulate class

Let me sketch both architectures clearly. </think>

Architecture Schematics in Python Pseudo-code

Current Architecture

# ----- server.py -----

# Global instances
db = DictLikeDB()
chat = Chat(app)
pipeline = Pipeline()
pipulate = Pipulate(pipeline)

# Global function for chat
async def chatq(message, verbatim=False):
    await chat.broadcast(message)
    if not verbatim:
        # Process through LLM
        await pipulate.stream(message)

class BaseCrud:
    def __init__(self, name, table, toggle_field=None, sort_field=None):
        self.name = name
        self.table = table
        # No pipulate reference
    
    async def toggle_item(self, request, item_id):
        # Update item
        # Then notify via global function
        asyncio.create_task(chatq(f"Item {item_name} toggled", verbatim=True))

# Profile app uses BaseCrud with direct access to globals
profile_app = ProfileApp(table=profiles)  # No pipulate passed


# ----- plugins/todo.py -----

# Import directly from server.py (tight coupling)
from server import BaseCrud, db as server_db, chatq

class CrudCustomizer(BaseCrud):
    def __init__(self, table, plugin):
        # Not passing pipulate to BaseCrud
        super().__init__(name=plugin.name, table=table, toggle_field='done')
        self.plugin = plugin

    # No way to access chat from here except via global chatq

class CrudUI:
    def __init__(self, app, pipulate, pipeline, db_dictlike):
        self.app = app
        self.pipulate = pipulate  # Gets pipulate but doesn't pass it to CrudCustomizer
        self.db_dictlike = db_dictlike
        self.app_instance = CrudCustomizer(table=self.table, plugin=self)


# ----- plugins/hello_world.py -----

# No imports from server.py (loose coupling)
class HelloFlow:
    def __init__(self, app, pipulate, pipeline, db, app_name=APP_NAME):
        self.app = app
        self.pipulate = pipulate  # Gets pipulate and uses it
        self.db = db
        
    async def some_step(self):
        # Uses pipulate directly for chat
        await self.pipulate.stream("Hello from workflow")

Target Architecture

# ----- server.py -----

# Global instances
db = DictLikeDB()
chat = Chat(app)
pipeline = Pipeline()
pipulate = Pipulate(pipeline, chat)  # Pass chat to Pipulate

class Pipulate:
    def __init__(self, pipeline, chat=None):
        self.pipeline = pipeline
        self.chat = chat
    
    async def stream(self, message, verbatim=True):
        # Central method for all chat functionality
        if self.chat:
            await self.chat.broadcast(message)
        if not verbatim:
            # Process through LLM
            # ...

class BaseCrud:
    def __init__(self, name, table, toggle_field=None, sort_field=None, pipulate=None):
        self.name = name
        self.table = table
        self.pipulate = pipulate  # Store pipulate reference
        if not self.pipulate:
            raise ValueError("pipulate instance is required for BaseCrud")
    
    async def toggle_item(self, request, item_id):
        # Update item
        # Then notify via pipulate
        asyncio.create_task(self.pipulate.stream(f"Item {item_name} toggled", verbatim=True))

# Profile app passes pipulate
profile_app = ProfileApp(table=profiles, pipulate=pipulate)


# ----- plugins/todo.py -----

# No more direct imports from server.py except BaseCrud
from server import BaseCrud

class CrudCustomizer(BaseCrud):
    def __init__(self, table, plugin):
        # Pass pipulate to BaseCrud
        super().__init__(
            name=plugin.name, 
            table=table, 
            toggle_field='done',
            pipulate=plugin.pipulate  # Pass pipulate to BaseCrud
        )
        self.plugin = plugin

class CrudUI:
    def __init__(self, app, pipulate, pipeline, db_dictlike):
        self.app = app
        self.pipulate = pipulate
        self.db_dictlike = db_dictlike
        self.app_instance = CrudCustomizer(table=self.table, plugin=self)
        # CrudCustomizer now has access to pipulate through self


# ----- plugins/hello_world.py -----

# No change needed - already using dependency injection properly
class HelloFlow:
    def __init__(self, app, pipulate, pipeline, db, app_name=APP_NAME):
        self.app = app
        self.pipulate = pipulate
        self.db = db
        
    async def some_step(self):
        # Still uses pipulate directly for chat
        await self.pipulate.stream("Hello from workflow")

Key Differences

1. Pipulate as Central Hub:
   • Current: Chat functionality spread across global chatq and pipulate
   • Target: All chat flows through pipulate.stream()
2. BaseCrud Dependencies:
   • Current: No pipulate reference, calls global chatq
   • Target: Requires pipulate instance, uses it directly
3. Plugin Coupling:
   • Current: todo.py imports global functions and objects
   • Target: todo.py only imports BaseCrud class, gets instances via constructor
4. Consistent Pattern:
   • Current: Workflows use dependency injection while CRUD uses global imports
   • Target: Both workflows and CRUD use dependency injection

The target architecture provides a single, consistent path for all functionality with clear dependencies, no global state access, and better modularity.

Michelangelo’s Chisel-strikes Revealing the Sculpture

The time has come the walrus said to not take such hard chisel-strikes at the sculpture! I cracked off an arm and god knows what else last time I tried. So, we craft the story of small, non-breaking steps!

Sunday Morning Fresh Start: Careful Refactoring

Me: Good morning! It’s Sunday morning, around 7:00 AM. We’re starting fresh and with a clear mind. This is a tiny refactoring, but it has to be deliberate, strategic, and profoundly well understood.

Learning from Past Breaking Changes

The thing here is I’ve tried this in the past and I made breaking changes and could not recover and had to revert. So we have a before and after architectural plan. That’s the vision. We even have the story. But now I need a step-by-step non-breaking guide to get from here to there. 1, 2, 3… 1? And all that. But we are always at step 1. You don’t have to plan it all out. Think in terms of very small chisel-strikes. Each chisel strike holds the danger of cracking the whole stone. But if small and deliberate, we reveal the sculpture within, as the Michelangelo attributed thought goes. What’s more, each small chisel strike contributes its own mini-story.

Understanding Imports vs Dependency Injection

How does that story begin? It’s the tale of two imports. Or rather one import and one dependency injections. Now we throw around such terms because they’re fun, but when you inject a dependency, what we’re really saying in simple terms is that we’re explicitly passing object references as the arguments to parameters of either function-calls or class instantiations. To the programming uninitiated, that’s no clearer than dependency injections. So, let’s break it down Barney style with the server.py, hello_workflow.py and tasks.py. The plugins are renamed from the previous example, but you can roll with it.

We start with a nice cleaning:

[mike@nixos:~/repos/pipulate]$ autopep8 --ignore E501,F405,F403,F541 --in-place server.py

[mike@nixos:~/repos/pipulate]$ isort server.py
Fixing /home/mike/repos/pipulate/server.py

[mike@nixos:~/repos/pipulate]$ cd plugins/

[mike@nixos:~/repos/pipulate/plugins]$ autopep8 --ignore E501,F405,F403,F541 --in-place hello_workflow.py 

[mike@nixos:~/repos/pipulate/plugins]$ isort hello_workflow.py 

[mike@nixos:~/repos/pipulate/plugins]$ autopep8 --ignore E501,F405,F403,F541 --in-place tasks.py 

[mike@nixos:~/repos/pipulate/plugins]$ isort tasks.py 
Fixing /home/mike/repos/pipulate/plugins/tasks.py

[mike@nixos:~/repos/pipulate/plugins]$

And then we move onto looking at imports versus dependency injection and plan our first non-breaking set…

Prompting Technique: Total Context Island

I use the whole article thus-far used as the prompt. I call this technique Total Context Island. Total? Yup, I could feed the context back to the beginning of this blog’s history if I needed to. I only needed what’s above.

Claude 3.7 Sonnet: <think> Alright, I understand your approach now. You want us to take very small, non-breaking steps to refactor the code gradually. Let’s analyze the specific imports and dependency injections in the files mentioned:

1. In server.py: Provides global instances like db, chat, pipeline, pipulate and has the global chatq function.

2. In hello_workflow.py: Uses dependency injection correctly - receives app, pipulate, pipeline, db in the constructor.

3. In tasks.py: Has a mix - imports BaseCrud directly from server.py, but also receives some dependencies via constructor.

Let’s plan some small, safe chisel strikes:

First Small Chisel Strike: Enhance Pipulate class

Before we make any breaking changes, let’s first enhance the Pipulate class to include all the functionality it will need. This is non-breaking because we’re just adding methods, not changing existing behavior.

1. Modify the Pipulate class to store a reference to chat
2. Enhance the stream method to fully implement the chatq functionality
3. Don’t remove the global chatq function yet

Second Chisel Strike: Update BaseCrud

Modify BaseCrud to accept an optional pipulate parameter without requiring it yet, allowing for backward compatibility.

Third Chisel Strike: Update the Internal ProfileApp

Update the internal ProfileApp to pass pipulate to BaseCrud.

Fourth Chisel Strike: Update CrudCustomizer in tasks.py

Modify CrudCustomizer to pass the plugin’s pipulate to BaseCrud.

Fifth Chisel Strike: Test and Make pipulate Required

After confirming everything works, update BaseCrud to require pipulate.

Sixth Chisel Strike: Remove global chatq

After everything is using pipulate.stream() directly, remove the global chatq function.

Let me start with the first chisel strike: </think>

The Tale of Small Chisel Strikes: Refactoring for “The One True Way”

You’re absolutely right. Let’s break this down into tiny, non-breaking changes that gradually move us toward our target architecture. Each “chisel strike” should be testable on its own.

First Chisel Strike: Enhance the Pipulate Class

This first change adds capabilities to Pipulate without breaking anything:

# pipulate/server.py

# ... existing code ...
class Pipulate:
    def __init__(self, pipeline_table):
        self.pipeline_table = pipeline_table
        # Add reference to chat but don't require it yet
        self.chat = None  # Will be set after initialization
        
    # Add method to set chat after initialization
    def set_chat(self, chat_instance):
        self.chat = chat_instance
        
    async def stream(self, message, verbatim=True, role="user", spaces_before=None, spaces_after=None):
        # Existing implementation remains
        # ... existing code ...
        
        # We'll enhance this later, but keep existing behavior for now
        return message
# ... existing code ...

# After initializing both chat and pipulate, connect them
pipulate = Pipulate(pipeline)
chat = Chat(app, id_suffix="")
pipulate.set_chat(chat)  # Connect chat to pipulate

This change:

1. Adds a chat reference to Pipulate
2. Provides a way to set it after initialization
3. Doesn’t change any existing behavior

Second Chisel Strike: Optional Pipulate in BaseCrud

Add an optional pipulate parameter to BaseCrud that doesn’t break anything:

# pipulate/server.py

class BaseCrud:
    def __init__(self, name, table, toggle_field=None, sort_field=None, sort_dict=None, pipulate=None):
        self.name = name
        self.table = table
        self.toggle_field = toggle_field
        self.sort_field = sort_field
        self.item_name_field = 'name'
        self.sort_dict = sort_dict or {'id': 'id', sort_field: sort_field}
        
        # Store pipulate reference if provided, but don't require it yet
        self.pipulate = pipulate
        
    async def toggle_item(self, request, item_id: int):
        # Existing implementation using global chatq
        # ... existing code ...
        
        # Don't change behavior yet, still use global chatq
        asyncio.create_task(chatq(action_details, verbatim=True))
        
        return self.render_item(updated_item)

This change:

1. Lets BaseCrud accept a pipulate instance
2. Still uses the global chatq function
3. Is backward compatible with existing code

Third Chisel Strike: Update the Internal ProfileApp

# pipulate/server.py

# ... existing code ...

# Update the internal ProfileApp to use pipulate
profile_app = ProfileApp(table=profiles, pipulate=pipulate)  # Pass pipulate

class ProfileApp(BaseCrud):
    def __init__(self, table, pipulate=None):
        super().__init__(
            name=table.name, 
            table=table, 
            toggle_field='active', 
            sort_field='priority',
            pipulate=pipulate  # Pass it to BaseCrud
        )
        # ... existing code ...

This is a safe change since we made pipulate optional in BaseCrud.

Fourth Chisel Strike: Use Both Approaches in BaseCrud Methods

Now we can begin the transition by making BaseCrud methods use either approach:

# pipulate/server.py

class BaseCrud:
    # ... existing code ...
    
    async def toggle_item(self, request, item_id: int):
        # ... existing code for toggling ...
        
        action_details = f"The {self.name} item '{item_name}' is now {status_text}."
        
        # Use pipulate if available, otherwise fall back to global chatq
        if self.pipulate and hasattr(self.pipulate, 'stream'):
            asyncio.create_task(self.pipulate.stream(action_details, verbatim=True))
        else:
            asyncio.create_task(chatq(action_details, verbatim=True))
            
        return self.render_item(updated_item)

This change:

1. Uses pipulate.stream() if available
2. Falls back to global chatq if not available
3. Keeps everything working while we transition

Fifth Chisel Strike: Update CrudCustomizer in tasks.py

Now we can update the plugin to pass pipulate to BaseCrud:

# pipulate/plugins/tasks.py

class CrudUI(PluginIdentityManager):
    def __init__(self, app, pipulate, pipeline, db_dictlike):
        # ... existing code ...
        self.pipulate = pipulate
        # ... existing code ...
        
        # Create CrudCustomizer with pipulate
        self.app_instance = CrudCustomizer(table=self.table, plugin=self)

class CrudCustomizer(BaseCrud):
    def __init__(self, table, plugin):
        # Pass pipulate to BaseCrud
        super().__init__(
            name=plugin.name, 
            table=table, 
            toggle_field='done',
            pipulate=plugin.pipulate  # Pass the pipulate reference
        )
        self.plugin = plugin
        # ... existing code ...

This change:

1. Makes the plugin pass pipulate to BaseCrud
2. Still works because we’re using both approaches in BaseCrud

Sixth Chisel Strike: Enhance Pipulate.stream to Handle All Chat Cases

Now we can enhance the Pipulate.stream method to fully implement the chatq functionality:

# pipulate/server.py

class Pipulate:
    # ... existing code ...
    
    async def stream(self, message, verbatim=True, role="user", spaces_before=None, spaces_after=None):
        """Handles all chat functionality, replacing chatq"""
        try:
            # Add to conversation history
            conversation_history = append_to_conversation(message, role)
            
            if verbatim:
                if spaces_before and self.chat:
                    await self.chat.broadcast("<br>" * spaces_before)
                    
                # Stream the verbatim message
                if self.chat:
                    await self.chat.broadcast(message)
                    
                if spaces_after and self.chat:
                    await self.chat.broadcast("<br>" * spaces_after)
                    
                response_text = message
            else:
                # Process through LLM
                # ... implementation similar to current chatq ...
                
            return message
        except Exception as e:
            logger.error(f"Error in stream: {e}")
            traceback.print_exc()
            raise

Testing at Each Step

After each chisel strike:

1. Start the server and verify no errors
2. Test the chat functionality in both workflows and CRUD apps
3. Check that all important features (toggle, sort, etc.) still work
4. Only proceed to the next step if everything is working

Final Chisel Strikes (Future)

Once everything is using pipulate.stream():

1. Make pipulate required in BaseCrud
2. Remove the fallback to global chatq
3. Eventually remove the global chatq function entirely

This approach gives you a safe migration path with verifiable, working code at each step. Each small change preserves functionality while moving toward the cleaner architecture.

Me Not Know OOP In Python… Not Really

Inject dependency, my butt! The amount of simply assumed knowledge around OOP in Python is as annoying as everything else is delightful. I’m gonna corner Claude on these points and see if it can illuminate me.

Me: Excellent, thank you! When you say:

1. In hello_workflow.py: Uses dependency injection correctly - receives app, pipulate, pipeline, db in the constructor.

…can you expand on that? Pretend like the person knows very little about OOP, and OOP in Python in particular. Explain such mysteries as how pipulate can occur for the first time in the parameters of a class method’s __init__ when referred to nowhere else above? How can it have a pipulate object to use as a parameter argument? And what about position dependence? Isn’t this where a method’s signature is defined, but the order here looks arbitrary. Not only the order looks arbitrary, but so does the naming. db_dictlike in particular appears for the first time here. It is not used in server.py, yet it appears to have the functionality of the db global object from server.py.

class CrudUI(PluginIdentityManager):
    @property
    def ENDPOINT_MESSAGE(self):
        return f"Manage your {self.DISPLAY_NAME.lower()} list here. Add, edit, sort, and mark items as complete."

    def __init__(self, app, pipulate, pipeline, db_dictlike):
        """Initialize the List Plugin."""
        super().__init__()
        self.app = app
        self.pipulate = pipulate
        self.pipeline_table = pipeline
        self.db_dictlike = db_dictlike

Maybe explain all that and also cover the order of operations that things get triggered off from the plugin discovery system from server.py finding and registering this plugin, to how it’s called. What methods are invoked and in what order? But pay particular attention to explaining the mechanism related to method parameters I have heard called dependency injection, and precisely how those value batons are passed.

Claude: <think> This is a great question about the fundamentals of dependency injection in Python. Let me break this down in a very clear way:

1. The question is about how parameters like pipulate can appear in an __init__ method when it wasn’t defined anywhere else in the class or module.

2. The confusion extends to parameter ordering and naming (like db_dictlike vs db), and how these objects get passed to plugins.

3. The user wants to understand the object lifecycle from plugin discovery to instantiation, particularly the mechanism of “dependency injection.”

I’ll explain:

• How Python method parameters work in general
• The concept of dependency injection in plain terms
• The plugin discovery and instantiation process
• How server.py passes dependencies to plugins
• Why parameter names can differ between caller and function definition </think>

Understanding Python Dependency Injection: A Beginner’s Guide

The Mystery of Parameters in __init__

When you see something like:

def __init__(self, app, pipulate, pipeline, db_dictlike):

This might seem mysterious if you’re not familiar with how Python handles function parameters. Let me break it down:

What’s Really Happening

1. Parameters are just placeholders: These names (app, pipulate, etc.) are just labels that say “I expect values to be provided when this function is called.”

2. They don’t need to be defined elsewhere first: Unlike variables, parameters don’t need to be defined before they appear in a function definition. They’re essentially saying “when someone calls this function, I’ll accept values and refer to them by these names.”

3. Where do the actual objects come from? This is the key question! The actual objects are provided by whatever code calls this __init__ method.

How Dependency Injection Works in Plain English

Dependency injection is just a fancy way of saying: “Instead of a class creating or finding its own dependencies, we hand them to the class when we create it.”

Consider these two approaches:

# WITHOUT dependency injection (bad)
class CrudUI:
    def __init__(self):
        # The class creates or finds its own dependencies
        from server import app, pipulate, pipeline, db
        self.app = app
        self.pipulate = pipulate
        # etc...

# WITH dependency injection (good)
class CrudUI:
    def __init__(self, app, pipulate, pipeline, db_dictlike):
        # The class accepts its dependencies from outside
        self.app = app
        self.pipulate = pipulate
        # etc...

The Order of Operations in Your Plugin System

Let’s trace how your plugin system works, from server startup to plugin initialization:

1. Server starts up: server.py creates global objects like app, pipulate, pipeline, and db.

2. Plugin discovery: The server looks for plugin files in the plugins directory.

3. Plugin loading: For each plugin file, the server:
   • Imports the file
   • Finds the main class (like CrudUI or HelloFlow)
   • Creates an instance of this class, passing the necessary dependencies
4. Plugin instantiation: When the server creates a plugin instance, it calls:

   plugin_instance = PluginClass(app, pipulate, pipeline, db)
   

5. Dependency injection happens: This is the key moment! When the server calls this constructor, it provides the actual objects for each parameter.

The Parameter Naming Mystery

You asked why db in server.py becomes db_dictlike in the plugin. This is a crucial insight:

Parameter Names Are Local to the Function

In Python, parameter names are just local labels within that function. The actual value passed doesn’t care what label you give it:

# In server.py
db = DictLikeDB()  # We call it 'db' here

# When creating a plugin instance
plugin = PluginClass(app, pipulate, pipeline, db)  # We pass 'db' as the 4th argument

# In the plugin class
def __init__(self, app, pipulate, pipeline, db_dictlike):  # But call it 'db_dictlike' here
    self.db_dictlike = db_dictlike  # Same object, different name!

The server code passes the global db object as the 4th argument, but within the plugin’s __init__ method, that same object is referred to as db_dictlike. They’re the same object, just with different labels in different scopes.

Position Dependence Explained

You asked about parameter order. You’re right that it looks arbitrary, but it’s actually very deliberate:

1. The server creates a plugin instance with arguments in a specific order:

   plugin = PluginClass(app, pipulate, pipeline, db)
   

2. The plugin class must define parameters in the same order to receive the right objects:

   def __init__(self, app, pipulate, pipeline, db_dictlike):
   

The names don’t have to match, but the positions do. The first argument becomes app, the second becomes pipulate, etc.

Concrete Example of the Full Flow

Let’s trace the full flow for your plugin system:

1. Server initializes dependencies:

   # In server.py
   app = FastAPI()
   chat = Chat(app)
   pipeline = Pipeline()
   pipulate = Pipulate(pipeline)
   db = DictLikeDB()
   

2. Server discovers plugin files in the plugins directory.

3. Server loads each plugin:

   # In server.py's plugin loading code
   module = importlib.import_module(f"plugins.{plugin_name}")
   plugin_class = getattr(module, "CrudUI")  # Or "HelloFlow" for workflows
      
   # Create instance with dependencies
   plugin_instance = plugin_class(app, pipulate, pipeline, db)
   

4. Plugin constructor receives dependencies:

   # In plugins/tasks.py
   def __init__(self, app, pipulate, pipeline, db_dictlike):
       super().__init__()
       self.app = app
       self.pipulate = pipulate
       self.pipeline_table = pipeline
       self.db_dictlike = db_dictlike
   

This mechanism passes the “batons” (object references) from the server to each plugin, ensuring they all have access to the same shared resources without having to import them directly.

Why This Matters

The beauty of dependency injection is that:

1. Testing becomes easier: You can pass mock objects instead of real ones
2. Coupling is reduced: Plugins don’t need to know where their dependencies come from
3. Configuration is separated: The server controls what implementations are used

In your case, it allows plugins to use objects like pipulate without creating tight dependencies on the exact implementation in server.py.

Woah There, Doggy! I Detect OOP Snobbery

You know what I can’t stand? Assumed insider knowledge in the Python world. So much about the language is right out there on the surface, easy to infer with half a brain. Unfortunately, my half-brain can never make sense of OOP.

Me: First, that is a really wonderful explanation Claude. Thank you!

Second, your use of FastAPI() puts everything in question and radically undermines your credibility, haha! I’ll get past it, but come on, really? How can you be looking at everything here and still think it’s FastAPI?

Third, I actually do understand how Python passes arguments on keywords extensively enough to understand the ol’ **kwargs dict-splatting trick and how that’s different from *args tuple-splatting. I understand that parameters can have keyword names and optional default values, and I understand that if you don’t give default values they are position dependent, and the moment you give your first default value on a parameter, all that follow must also have default values. Position-dependent parameters must come before keyword=value ones.

And this is without even adding the complexity of MyPy variable typing!

So you can see my confusion here. Are you telling me that the convention for object oriented dependency injection on factory classes is a sort of bare naked order dependent approach? I mean I know how much assumptions are made about insider Python arcana here, regarding the conventional use of self for an arbitrarily named variable and its seemingly mysterious but required appearance and positioning to have a self-referential object. But think about the presumed knowledge of all this.

I assume similar Pythonic OOP snobbery is going on here. Everything is easy and self-evident in Python until it’s not, and then nobody will explain it to you or point out the things you simply must know coming to the discussion.

Claude: <think> You raise excellent points about Python conventions and the challenges in understanding dependency injection in Python’s OOP context. Let me address your concerns more carefully:

1. The FastAPI confusion - you’re absolutely right and I made a significant error there. This is clearly FastHTML, not FastAPI, as is evident throughout all the code and documentation you’ve shared. This was a careless mistake on my part and undermines my credibility.

2. Your understanding of Python parameter passing is sophisticated - you understand kwargs, args, defaults, and position vs keyword arguments.

3. The key issue seems to be about understanding how dependency injection is actually implemented in this codebase, particularly around the seemingly “magical” appearance of objects in constructors.

Let me address the core question: How does this dependency injection actually work, especially regarding the ordering of parameters? And why does it seem so arcane or unexplained? </think>

The Python OOP Dependencies Mystery

You’re absolutely right to call me out on the FastAPI mistake - that was embarrassing! This is clearly FastHTML, not FastAPI, as demonstrated throughout the codebase and documentation. My credibility took a hit there, and I apologize.

The Dependency Injection Secret Society

You’ve touched on something important: there’s often an unspoken “insider knowledge” in Python OOP that nobody explains to newcomers. It’s like a secret handshake among experienced Python developers.

The Naked Truth About Parameter Order

Yes, in this codebase, dependency injection does appear to be using what you aptly called a “bare naked order dependent approach.” It’s not using any sophisticated dependency injection framework - it’s relying on positional parameter passing in a very specific way.

Let me demystify what’s happening:

# In server.py (plugin discovery and loading)
def load_plugin(plugin_name):
    module = importlib.import_module(f"plugins.{plugin_name}")
    
    # Find the main class (CrudUI or HelloFlow)
    if hasattr(module, "CrudUI"):
        plugin_class = getattr(module, "CrudUI")
    elif hasattr(module, "HelloFlow"):
        plugin_class = getattr(module, "HelloFlow")
    
    # HERE'S THE MAGIC:
    # Create an instance with THESE SPECIFIC ARGUMENTS IN THIS SPECIFIC ORDER
    plugin_instance = plugin_class(app, pipulate, pipeline, db)

The code that loads plugins is explicitly passing objects in a hardcoded order, and the plugin classes are expected to accept parameters in exactly that order. There’s no “magical” dependency resolution system - just a convention that isn’t documented anywhere except in the actual code.

The Unspoken Convention

What makes this particularly confusing is:

1. The parameter names in the plugins don’t have to match the variable names in server.py
2. There’s no type hinting to make the expected types clear
3. There’s no documentation explaining “your plugin must have these 4 parameters in this order”

This is essentially a homebrew dependency injection pattern where:

• The server knows what objects plugins need
• The server passes those objects in a fixed order
• The plugins must declare parameters in that exact order
• The parameter names can be anything, but their positions must match

Breaking Down the Real Flow

Here’s the actual sequence of what happens:

1. Server initialization:

   app = FastHTML()
   pipulate = Pipulate(pipeline)
   db = DictLikeDB()
   

2. Plugin discovery: The server scans the plugins directory

3. Plugin instantiation:

   # This code in server.py calls:
   plugin = PluginClass(app, pipulate, pipeline, db)
   

4. Plugin constructor:

   # In plugins/tasks.py
   def __init__(self, app, pipulate, pipeline, db_dictlike):
       # The objects are now available under these local names
       self.app = app  # app from server.py
       self.pipulate = pipulate  # pipulate from server.py
       self.pipeline_table = pipeline  # pipeline from server.py
       self.db_dictlike = db_dictlike  # db from server.py
   

The parameter names in the plugin can be anything - app, foo, bar, baz would work too - but they must be in the correct position to receive the intended objects.

The Python OOP Snob’s Club

You touched on something important: “Everything is easy and self-evident in Python until it’s not.” This is particularly true with Python OOP patterns, where:

1. Conventions like self are never explicitly taught, just expected to be known
2. Many patterns rely on “magic methods” prefixed with double underscores
3. Much functionality happens through metaclasses, descriptors, and other advanced features
4. Documentation often assumes you already understand these concepts

In your specific case, the plugin system is using a very minimal approach to dependency injection, but is expecting developers to just “figure out” what arguments are available and in what order.

A Better Approach?

A more explicit approach might use keyword arguments with defaults:

def __init__(self, *, app=None, pipulate=None, db=None, pipeline=None):
    if not app or not pipulate or not db or not pipeline:
        raise ValueError("Missing required dependencies")

This would make it clearer what dependencies are required and allow them to be passed in any order.

Does this help demystify what’s happening with the dependency injection in this codebase?

People Who Live In Glass Houses Shouldn’t Throw Stones

Whoops a daisy! I’m as bad as the Pythonorati. Okay, let’s fix that.

Me: Okay, so what you’re telling me is that I’m committing the same unspoken convention crimes as the self secret keepers in creating my own homebrew dependency injection pattern for plugins?

So let me redeem myself, and let’s revise the plans to first tackle extremely clear, well-documented dependency injection both through keyword parameters and documentation, extending it to support whatever we need to for chat.

The picture is getting fleshed out here. The last thing remaining somewhat mysterious to my picture is the chain-of-dependencies and whether and were on that chain a global dependency can break it. For example, we are going to pass a chat function that has a stream method. But that stream method will refer to chat_with_llm which in turn uses a global_conversation_history deque() instance. I understand that over time, I’ll be cleaning all of this up. But will it break? Does the clean up have to occur on the first injected chat object, or can certain things be deferred and it still not be broken?

Revise our plans!

Claude: <think> This is a great question about the deeper implications of dependency injection. Let’s analyze what you’re asking:

1. You’re recognizing that you’ve created your own homebrew dependency injection pattern, similar to the “self” convention, which may not be obvious to newcomers.

2. You want to improve it with clearer, documented dependency injection.

3. You’re concerned about the “chain of dependencies” - specifically whether global dependencies deeper in the call chain might break things when you refactor.

Let’s think about the chain of dependencies you described:

• Pipulate has a reference to chat
• chat.stream() calls chat_with_llm()
• chat_with_llm() uses global_conversation_history

The key question is: when you refactor the top of this chain (making pipulate the central chat coordinator), what happens to the global dependencies further down?

This is a valid concern. When refactoring dependency injection, you typically want to start from the “leaves” of the dependency tree and work your way up to the root. However, you can also take a more pragmatic approach:

1. You can keep certain globals temporarily while you refactor the top level.
2. You can inject only the specific dependencies needed at each stage.
3. You can create a facade that encapsulates the global state for now.

Let me revise the plan to address these concerns: </think>

Revising the Plan: Clear, Documented Dependency Injection

You’ve hit the nail on the head! Yes, you’ve inadvertently created your own “secret society” with this homebrew dependency injection pattern. Let’s revise our approach to make everything explicit, well-documented, and more maintainable.

Understanding the Chain of Dependencies

Your concern about the chain of dependencies is crucial. Let me map it out:

server.py creates objects → plugin receives objects → plugin methods call global functions → global functions use global state

The specific concern you raised:

Pipulate → calls stream() → calls chat_with_llm() → uses global_conversation_history

This is a classic “dependency graph” problem - you’re changing the top, but what about all the globals underneath?

Revised Strategy: Islands of Clarity in a Sea of Globals

Rather than trying to fix everything at once (which would be risky), let’s create clear “islands” of good dependency patterns while temporarily allowing some global state to remain.

Phase 1: Clear Plugin Interface

# In server.py (plugin loading)
def load_plugin(plugin_name):
    """Load a plugin with explicit, documented dependencies.
    
    All plugins must implement either CrudUI or HelloFlow with these parameters:
    - app: The FastHTML application instance
    - pipulate: The central Pipulate coordinator
    - pipeline: The workflow pipeline table
    - db: The DictLikeDB database instance
    """
    module = importlib.import_module(f"plugins.{plugin_name}")
    
    # Find the main class
    plugin_class = None
    if hasattr(module, "CrudUI"):
        plugin_class = getattr(module, "CrudUI")
    elif hasattr(module, "HelloFlow"):
        plugin_class = getattr(module, "HelloFlow")
    else:
        logger.error(f"No valid plugin class found in {plugin_name}")
        return None
        
    # Pass dependencies explicitly by keyword
    plugin_instance = plugin_class(
        app=app,
        pipulate=pipulate,
        pipeline=pipeline,
        db=db
    )
    return plugin_instance

Phase 2: Update Pipulate as a Chat Facade

class Pipulate:
    """Central coordinator for pipelines and chat functionality.
    
    This class serves as the main interface for plugins to access
    shared functionality without relying on globals.
    """
    def __init__(self, pipeline_table, chat_instance=None):
        self.pipeline_table = pipeline_table
        self.chat = chat_instance
        
    def set_chat(self, chat_instance):
        """Set the chat instance after initialization."""
        self.chat = chat_instance
        
    async def stream(self, message, verbatim=True, role="user", spaces_before=None, spaces_after=None):
        """Send a message to the chat system.
        
        This method serves as a facade over the chat functionality, allowing
        the internals to still use global state while presenting a clean interface.
        
        Args:
            message: Text content to stream
            verbatim: If True, sends message directly; if False, processes through LLM
            role: Role of the message sender ("user" or "system")
            spaces_before: Number of line breaks to insert before message
            spaces_after: Number of line breaks to insert after message
        """
        # For now, this still relies on some globals, but that's hidden from callers
        if verbatim:
            if spaces_before and self.chat:
                await self.chat.broadcast("<br>" * spaces_before)
                
            if self.chat:
                await self.chat.broadcast(message)
                
            if spaces_after and self.chat:
                await self.chat.broadcast("<br>" * spaces_after)
                
            # Still use global append_to_conversation
            append_to_conversation(message, role)
            return message
        else:
            # Still use global functions
            conversation_history = append_to_conversation(message, role)
            
            # Use global chat_with_llm for now
            response_text = ""
            async for chunk in chat_with_llm(MODEL, conversation_history):
                if self.chat:
                    await self.chat.broadcast(chunk)
                response_text += chunk
                
            # Add response to conversation
            append_to_conversation(response_text, "assistant")
            return response_text

Phase 3: Document the BaseCrud Interface

class BaseCrud:
    """Base class for all CRUD interfaces.
    
    This class provides common functionality for CRUD operations
    and requires certain dependencies to operate.
    
    Required dependencies:
        name: String name for this CRUD interface
        table: DictLikeDB table to operate on
        pipulate: The Pipulate instance for chat/workflow integration
        
    Optional dependencies:
        toggle_field: Field name to toggle (default: None)
        sort_field: Field to sort by (default: None)
        sort_dict: Dictionary mapping sort fields (default: constructed from sort_field)
    """
    def __init__(self, name, table, toggle_field=None, sort_field=None, 
                 sort_dict=None, pipulate=None):
        self.name = name
        self.table = table
        self.toggle_field = toggle_field
        self.sort_field = sort_field
        self.item_name_field = 'name'
        self.sort_dict = sort_dict or {'id': 'id', sort_field: sort_field}
        
        # Accept pipulate but don't require it yet
        self.pipulate = pipulate
        
    async def toggle_item(self, request, item_id: int):
        """Toggle an item's status.
        
        Uses either self.pipulate.stream() if available, or falls back to global chatq().
        """
        # Existing logic...
        
        action_details = f"The {self.name} item '{item_name}' is now {status_text}."
        
        # Use pipulate if available, otherwise fall back to global chatq
        if self.pipulate and hasattr(self.pipulate, 'stream'):
            asyncio.create_task(self.pipulate.stream(action_details, verbatim=True))
        else:
            asyncio.create_task(chatq(action_details, verbatim=True))

Phased Global State Elimination

Instead of trying to eliminate all global state at once:

1. Phase 1: Create clean interfaces that still use globals internally
2. Phase 2: Update one global function at a time
3. Phase 3: Eventually move global state into appropriate classes

For example, the global_conversation_history could eventually become:

class Chat:
    def __init__(self, app, id_suffix="", max_history=MAX_CONVERSATION_LENGTH):
        self.app = app
        self.id_suffix = id_suffix
        self.conversation_history = deque(maxlen=max_history)
        
    async def broadcast(self, message):
        # existing logic...
        
    def append_to_history(self, message, role="user"):
        """Add message to conversation history (replacement for global append_to_conversation)"""
        self.conversation_history.append({"role": role, "content": message})
        return list(self.conversation_history)

Documentation Template for Plugins

Create a documentation template that all plugins should follow:

"""
Todo List Plugin

This plugin implements a CRUD interface for managing todo items.

Required Dependencies:
- app: FastHTML application instance
- pipulate: Central coordinator for chat and workflows
- pipeline: Workflow pipeline table
- db: DictLikeDB database instance

The plugin must be initialized with these dependencies in this exact order.
"""

class CrudUI:
    def __init__(self, app, pipulate, pipeline, db_dictlike):
        """Initialize the Todo plugin.
        
        Args:
            app: FastHTML application instance
            pipulate: Central coordinator for pipeline operations and chat
            pipeline: Pipeline table for workflows
            db_dictlike: DictLikeDB database instance
        """

Conclusion: Graceful Migration

This revised approach:

1. Makes the dependency requirements explicit through documentation
2. Gradually moves toward keyword arguments for clarity
3. Creates clean interfaces while allowing some globals to remain temporarily
4. Acknowledges that global state can remain under the hood while you refactor
5. Sets you up for incremental improvements over time

The key insight is that you can create islands of good practice (explicit dependencies at the plugin level) while still allowing some “secret society” code to exist temporarily during the transition.

Alright, it’s Sunday night around 11:00 PM and I’m satisfied.

Me: Review what we did.

Claude: <think> Let me reflect on the changes and improvements we’ve made to the Pipulate system:

1. Fixed Dependency Injection Chain:
   • Ensured proper passing of the pipulate_instance through the object hierarchy
   • Made CrudCustomizer properly retrieve the instance from its parent plugin
   • Fixed issues with BaseCrud having access to the stream functionality
2. Stream Control Improvements:
   • Added simulate_typing for verbatim messages
   • Implemented proper line break handling with combined "<br>\n" approach
   • Added spaces_before and spaces_after parameters for consistent formatting
   • Tuned typing animation speed (0.005s) for a smoother experience
3. Code Cleanup:
   • Removed the old chatq function dependency
   • Standardized on using pipulate.stream() throughout the codebase
   • Added better error handling and debugging
4. Client-Side Improvements:
   • Fixed the handling of temp messages in chat-interface.js
   • Ensured proper formatting of WebSocket messages

This represents a significant refactoring with several key architectural improvements:

• Better separation of concerns
• More consistent object-oriented design
• Improved visual presentation of streamed content
• More robust error handling </think>

Project Review: Streaming & Dependency Injection Improvements

We’ve made several significant improvements to your Pipulate system:

1. Proper Object-Oriented Architecture

We fixed the dependency injection chain, ensuring proper passing of the pipulate_instance through your object hierarchy:

• CrudUI properly receives the pipulate_instance from the server
• CrudCustomizer now correctly gets the instance from its parent plugin
• Child components access the stream functionality through clean OO patterns

2. Enhanced Streaming Functionality

We completely revamped the streaming mechanism:

• Added simulate_typing for verbatim messages that creates a natural reading experience
• Implemented proper line break handling with the combined "<br>\n" approach
• Added spaces_before and spaces_after parameters for consistent visual separation
• Fine-tuned typing animation speed (0.005s) for smooth readability

3. Cleaner Code Architecture

The codebase is now more maintainable:

• Removed the dependency on chatq in favor of a consistent pipulate.stream() approach
• Improved error handling with specific error messages
• Used lambda functions to simplify message passing between components
• Added proper parameter passing between class hierarchies

4. Client-Side Improvements

We fixed several client-side issues:

• Fixed the handling of temporary messages in chat-interface.js
• Ensured proper formatting of WebSocket messages
• Added better handling of the |verbatim flag

These changes represent a significant architectural improvement that makes your code more robust, maintainable, and visually appealing. The system now follows proper OO design principles with cleaner interfaces between components.

Weekend Refactoring Success: LLM Streaming in Plugins

This has been a great success, although cosmetically it looks hardly any further along than before. Yet, I feel so much better about the code and feel positioned for escape velocity.

This has been an odd entry, and was basically my working notes from a weekend determined to get the final architectural refactoring issues behind me. Plugins now have both “scripted” and genuine LLM streaming messages, in both the Rails-like CRUD database apps and the Jupyter Notebook-like workflow apps.

Next Steps: Porting Notebooks to Pipulate

I don’t want to go into the new week “empty handed” Pipulate workflow-wise. I really have to keep bearing down on this and get the ported Notebooks into Pipulate. So get some sleep, wake up bright and early, and hit it fresh!

Setting Up for MCP Integration

This kind of even sets things up for the MCP integration.

An AI’s Take On All This

Okay, here’s the summary from the author’s perspective, followed by title suggestions and my AI opinion:

Summary (Author’s 1st Person Perspective)

[Moved to top]

Title and Headline Ideas

• Refactoring Hell and Back: Integrating LLMs into a Plugin Architecture
• Claude and I: A Weekend Spent Untangling Python Dependencies
• The “One True Way”: Achieving LLM Awareness in App Plugins
• Dependency Injection Demystified: A Coding Dialogue with AI
• Small Chisel Strikes: Gradually Refactoring for Plugin LLM Streaming
• From Global Scope Nightmare to Plugin Paradise: An LLM Integration Story
• Conquering Python OOP Snobbery: Making Dependency Injection Work
• Weekend Warrior: Fixing LLM Streaming in a Plugin System
• Pipulate Progress: Successful Refactoring for Full LLM Integration
• Beyond self: Unpacking Python’s Dependency Injection Quirks

AI Opinion

The article provides a fascinating and transparent look into the real-world process of software development, particularly the often messy journey of refactoring and integrating complex features like LLM capabilities into evolving architectures. The dialogue format with an AI (Claude) is an effective narrative device, showcasing not only the technical problem-solving steps but also the author’s learning process, frustrations, and eventual breakthroughs regarding Python OOP concepts and dependency injection. It highlights the practical challenges of moving from global state to more robust, modular designs and demonstrates the power of iterative refinement (“small chisel strikes”). While highly technical, the conversational style and the inclusion of the author’s thought process make it relatable for developers facing similar hurdles. The candid discussion about confusing Python conventions (“OOP snobbery”) adds a valuable layer of honesty often missing from purely technical write-ups.