Grasshopper2.Components.Descriptivenamespace

Abstraction over an LLM provider. Implementations wrap the actual HTTP + JSON dance for a specific service (Anthropic, OpenAI, Google, OpenRouter, ...) or for a development stand-in like the play-act backend.

Persistent storage for LLM-provider API keys. Implementations use the platform's native secret store: macOS Keychain on macOS, DPAPI-encrypted file on Windows. Keys are scoped to the current OS user account and to a specific AiProvider, so an Anthropic key and a Google key can coexist.

Lookup service that surfaces Grasshopper2 SDK information to the model during code generation. Implementations are expected to be fast and in-process -- the model calls these tools multiple times per generation and tool latency directly extends the user's wait time.

What the backend returned for a single turn. Either text (the model declined to call a tool) or a structured tool call. Exactly one of AiBackendResponse.Text and AiBackendResponse.ToolCall is populated.

Plain-English description of what the generated code does, surfaced to the user for confirmation before the component is wired up. Catches intent mismatch at the spec level, which is the only level non-programmers can validate at.

Outcome of compiling LLM source. On success carries the compiled AiComponentLogic; on failure carries diagnostics for the next round.

Custom attributes for AiComponent. Routes a double-click on the component body to the prompt-and-conversation flow.

Base class for the logic hosted inside an AiComponent.

Stores the AiComponent.UserPrompt, AiComponent.SourceCode, AiComponent.LastInteractionMessage, and the info field of the component nomen as an undo record. Parameters are not stored -- they are derived from SourceCode via AiComponent.PreProcess(Solution) and lazily rebuilt on the next solve after undo/redo.

A single diagnostic produced while compiling LLM-generated source.

A single search result from the SDK docs. Carries enough for the model to decide whether to use this symbol; the full content (with examples, pitfalls, etc.) lives in the doc body that IAiSdkDocs returns separately if asked.

Factory for the platform-appropriate IAiKeyStore. Picks WindowsDpapiKeyStore on Windows and MacKeychainKeyStore elsewhere (which in practice means macOS for Rhino).

A single message in an AI conversation. The shape varies by role: system/user/assistant text messages carry only AiMessage.Text; assistant tool-call messages carry only AiMessage.ToolCall; tool result messages carry AiMessage.ToolName plus the result in AiMessage.Text. Construct via the static factory methods.

Role of a single message in an AI conversation. Mirrors the standard system/user/assistant/tool roles used by all major LLM provider APIs.

One round of conversation history: a user prompt and the response it produced. Lets the user step back to a previous working version after a bad refinement, and gives the LLM context for follow-up requests without re-explaining from scratch.

The set of LLM providers the AI Component knows how to talk to. Each value has a corresponding IAiBackend implementation and is also used to scope per-provider entries in IAiKeyStore.

Per-provider strings used by the sign-in dialog and the right-click panel: human-readable name, the URL where the user manages their account / API keys / usage, and the dialog explanation text.

Output of the pre-compilation syntax scan. Empty AiSecurityReport.Violations means the source passes the static safety check; non-empty means it must be rejected and surfaced to the user.

A single banned-symbol occurrence found by the syntax-tree scan.

Definition of a tool that the model is allowed to invoke. The provider sends the name, description, and JSON Schema for the parameters on every call, and the model emits an AiToolCall matching one of the offered tools.

A single tool invocation emitted by the model. Carries the tool name and the raw JSON-encoded arguments to be parsed by the tool-specific handler.

The fixed set of tools exposed to the model during code generation. The model picks one per turn; the tool name drives the routing logic on the host side, replacing any need to parse prose. Two are terminal (AiTools.Compile delivers final code, AiTools.Abandon gives up); the rest progress the conversation.

IAiBackend implementation talking to Anthropic's Messages API directly over HTTPS. Supports tool use and prompt caching of the system block, which gives a ~10x cost reduction on cached input tokens once the cache is warm.

IAiBackend implementation talking to Google's Gemini generateContent endpoint. The same conversation loop, tools, and docs corpus that drive the Anthropic backend work here -- only the wire format and a few naming conventions differ (role "model" instead of "assistant", systemInstruction as a top-level field, functionCall / functionResponse parts, no tool-use ids needed for round-tripping). Gemini has a no-credit-card free tier that's adequate for tyre-kicking and light usage. Quality is below Claude Opus on code generation but Flash is adequate for simple components and trivial to test.

V1 stand-in for the real SDK docs. Holds a small hand-authored corpus of the Grasshopper2 surface area the model actually needs (parameter construction, IDataAccess patterns, the AiComponentLogic contract). Swap out for a JSON-loaded implementation once the corpus is big enough that hand-editing this file becomes painful.

Phase the conversation loop is currently in. Tracked on InteractionStatistics so the component's attributes can render different visual states (icon, colour, label).

Tracks what the AI conversation loop has been doing on a given AiComponent: the current phase plus running counters for each kind of event (model calls, docs lookups, clarifications, compilation attempts, various failure modes). Also owns the lifecycle handle for the current run -- the SolutionId identifying it and the CancellationToken that aborts it. The component's attributes class draws from this state. Every property setter fires InteractionStatistics.Changed on a real change. The owning component subscribes once and invalidates the canvas on Changed, so the drawing refreshes automatically as the loop progresses.

macOS implementation of IAiKeyStore. Stores each key in the user's login keychain via the /usr/bin/security command-line tool, under a per-provider service name. The key is encrypted at rest by the OS and gated by the user's login. Caveat: during Set/Delete the API key briefly appears as an argument in process listings. The keychain entry itself is properly encrypted. A future improvement would be P/Invoke to Security.framework's SecKeychain APIs directly, which avoids the argv exposure.

IAiBackend implementation talking the OpenAI Chat Completions wire format. The system/user/assistant message shape is flat (no nested content blocks like Anthropic, no separate systemInstruction like Gemini) and tool calls round-trip through an explicit tool_call_id. Forces tool_choice = "required" so the model cannot answer in prose -- the conversation loop expects every turn to be a tool invocation. This class is provider-neutral: OpenAI and DeepSeek both speak the same schema, differing only in endpoint URL and default model. The caller supplies those at construction.

Windows implementation of IAiKeyStore. Encrypts each key with DPAPI (current user scope, so other Windows accounts on the same machine cannot read it) and writes the ciphertext to a per-provider file under %APPDATA%\McNeel\Grasshopper2.