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:
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 service | Provider architecture → Writing a provider |
| Add models or capabilities to a provider | Models and capabilities |
| Add settings to a provider | Provider settings |
| Give the assistant a new capability | AI tools |
| Inject new facts into AI requests | AI context |
| Create a new canvas component | Components |
| Understand how requests flow | The AI call pipeline |
| Decide which project a change belongs in | Project 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
| Area | Project | Path |
|---|---|---|
| Provider contracts, AICall types, capabilities | SmartHopper.ProviderSdk | src/SmartHopper.ProviderSdk |
| Provider discovery, trust, orchestration | SmartHopper.Infrastructure | src/SmartHopper.Infrastructure |
| AICall sessions, policies, tool management | SmartHopper.Infrastructure | src/SmartHopper.Infrastructure/AICall |
| Component base classes, context providers | SmartHopper.Core | src/SmartHopper.Core |
| AI tool implementations, GhJSON, canvas utils | SmartHopper.Core.Grasshopper | src/SmartHopper.Core.Grasshopper |
| End-user components | SmartHopper.Components | src/SmartHopper.Components |
| Provider implementations | SmartHopper.Providers.<Name> | src/SmartHopper.Providers.* |
| Menu/settings UI | SmartHopper.Menu | src/SmartHopper.Menu |
| Tests | SmartHopper.*.Tests + SmartHopper.Components.Test | src/ |
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:
- Providers are plugins, not code in the host. Components and the assistant never name a vendor. They ask
ProviderManagerfor a provider by name, and the provider handles all wire encoding. Adding a provider never means touchingSmartHopper.Components. - 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. - Canvas mutation is consent-gated. Tools that change the document are
AIMutatingTools; proposed edits go throughCanvasChangeReviewServiceso the user reviews them first. Read-only tools are cheap; mutating tools carry obligations. - 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. - 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:
- 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. - Add an AI Tool — give the AI a new capability. One class in
SmartHopper.Core.Grasshopper/AITools/describing what the tool does plus itsexecutedelegate; the tool manager picks it up automatically. - 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.
- Add a Context — feed new environmental facts to providers. Implement the two-member
IAIContextProvidercontract 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.0on macOS). - Provider plugin SDK (
SmartHopper.ProviderSdk) is MIT-licensed; the rest is LGPLv3. - Build with
.\tools\Build-Solution.ps1on Windows; runSmartHopper.ProviderSdk.Testswithout a signing key viadotnet test -p:SignAssembly=false.