Skip to main content

Developer Guide

For an end user, SmartHopper is the open source AI plugin for Grasshopper3D — it brings Large Language Models directly into the parametric design workflow: generate content, manipulate components, automate tasks through natural language.

For a developer, however, SmartHopper is an ecosystem that connects AI providers to Grasshopper 3D through a set of tools. These tools are made available to the user as Grasshopper components, and information about the user's environment is passed to the providers as context.

These four ingredients are the core of SmartHopper:

Looking for usage docs?

This section is for people who want to change or extend SmartHopper's code. If you want to use the plugin, head to the User Guide. The Component Library and AI Tools Library document what ships today.

The big picture​

  • Providers translate SmartHopper's generic request format into each vendor's wire protocol and back. They are plugins: separate SmartHopper.Providers.* assemblies discovered at runtime and gated by signature, hash-integrity, and trust checks before use.
  • Tools are actions the AI can invoke — read the canvas, place components, generate scripts, search forums. The tool catalog serves the canvas assistant, the MCP server, and components that call tools directly.
  • Context providers inject lightweight facts (current file, selection, time, viewport) into requests so the AI knows what you're working on.
  • Components are the Grasshopper-facing surface: stateful async components that pick a provider/model, run AI calls off the UI thread, and expose metrics.

The whole request path runs through a single normalized pipeline — AICall — so every consumer (component, assistant, MCP client) gets the same validation, tool loop, metrics, and error handling. It's worth understanding before writing any extension code: see The AI call pipeline.

What do you want to build?​

I want to…Start here
Add support for a new AI serviceProvider architecture → Writing a provider
Add models or capabilities to a providerModels and capabilities
Add settings to a providerProvider settings
Give the assistant a new capabilityAI tools
Inject new facts into AI requestsAI context
Create a new canvas componentComponents
Understand how requests flowThe AI call pipeline
Decide which project a change belongs inProject structure and the module map

How the pieces compose​

A single concept ties providers, tools, context, and components together: interactions. An AI request is a list of typed interactions (AIInteractionText, AIInteractionImage, AIInteractionToolCall, AIInteractionToolResult…) with roles from AIAgent (System, User, Assistant, ToolCall, ToolResult, Context). Providers never see Grasshopper objects or JSON prompts — they see interactions, encode them to their wire format, and decode the response back into interactions. That is what makes tools and context work uniformly across every provider.

Where the code lives​

AreaProjectPath
Provider contracts, AICall types, capabilitiesSmartHopper.ProviderSdksrc/SmartHopper.ProviderSdk
Provider discovery, trust, orchestrationSmartHopper.Infrastructuresrc/SmartHopper.Infrastructure
AICall sessions, policies, tool managementSmartHopper.Infrastructuresrc/SmartHopper.Infrastructure/AICall
Component base classes, context providersSmartHopper.Coresrc/SmartHopper.Core
AI tool implementations, GhJSON, canvas utilsSmartHopper.Core.Grasshoppersrc/SmartHopper.Core.Grasshopper
End-user componentsSmartHopper.Componentssrc/SmartHopper.Components
Provider implementationsSmartHopper.Providers.<Name>src/SmartHopper.Providers.*
Menu/settings UISmartHopper.Menusrc/SmartHopper.Menu
TestsSmartHopper.*.Tests + SmartHopper.Components.Testsrc/

The full breakdown — including dependency rules and which project owns which concern — is in the module map.

Design rules worth internalizing​

A few principles run through the whole codebase; the extension pages reference them constantly:

  1. Providers are plugins, not code in the host. Components and the assistant never name a vendor. They ask ProviderManager for a provider by name, and the provider handles all wire encoding. Adding a provider never means touching SmartHopper.Components.
  2. One pipeline, many consumers. Request validation, model selection, tool loops, streaming, and metrics live in ConversationSession/AIRequestCall — not in components or tools. Don't re-orchestrate calls in feature code.
  3. Canvas mutation is consent-gated. Tools that change the document are AIMutatingTools; proposed edits go through CanvasChangeReviewService so the user reviews them first. Read-only tools are cheap; mutating tools carry obligations.
  4. Context is minimal and filtered. Every byte of context is paid for in tokens on every request. Keep providers small, stable, and let consumers filter with ContextFilter.
  5. UI on the UI thread. Component workers and tool code run on background threads. Anything touching the Rhino/Grasshopper UI must be marshalled back — the framework does this for component state; you must do it for custom UI calls.

How to contribute​

There are four ways to extend SmartHopper, one per ingredient:

  1. Add an AI Provider — connect a new AI service to the ecosystem. You write a SmartHopper.Providers.<Name> assembly with four small files; the host discovers, verifies, and loads it at runtime.
  2. Add an AI Tool — give the AI a new capability. One class in SmartHopper.Core.Grasshopper/AITools/ describing what the tool does plus its execute delegate; the tool manager picks it up automatically.
  3. Add a Component — expose an AI tool or any other function to the Grasshopper canvas. Subclass the right base, register your parameters, implement a three-phase worker.
  4. Add a Context — feed new environmental facts to providers. Implement the two-member IAIContextProvider contract and register it; it is injected into every request that admits it.

Contributing​

  • The SmartHopper repository contains extensive internal docs under /docs (the local source of truth for architecture) — the pages here are a curated, human-oriented distillation of them.
  • Targets: Rhino 8 / Grasshopper 1, .NET 7 (net7.0-windows, net7.0 on macOS).
  • Provider plugin SDK (SmartHopper.ProviderSdk) is MIT-licensed; the rest is LGPLv3.
  • Build with .\tools\Build-Solution.ps1 on Windows; run SmartHopper.ProviderSdk.Tests without a signing key via dotnet test -p:SignAssembly=false.