T3Lab Assistant - Detailed Guide & LLM Configuration

T3Lab Assistant is an AI chat assistant integrated directly into Autodesk Revit as a dockable panel. It allows engineers and architects to control Revit using natural language (Vietnamese or English). It translates your instructions into safe Revit API transactions and executes them in your active model.

---

1. Cloud API vs. Local LLM (Recommended Setup)

While the assistant supports both Cloud APIs and Local LLMs (offline), we highly recommend using Cloud APIs (such as Claude, OpenAI GPT, or DeepSeek) for the best and most reliable experience.

Technical Comparison

Feature	Cloud API (Claude / GPT / DeepSeek)	Local LLM (Ollama / LM Studio)
Context Window	Large (128k – 200k tokens). Can easily read your Revit model context, chat history, and tools catalog without losing track.	Small by default (2048 – 4096 tokens if num_ctx is not set). Easily gets overloaded, causing it to lose context.
Tool Schema Handling	Tool definitions (schemas) are sent via a separate API channel (out-of-band), keeping the prompt small and clean.	Definitions of all ~110 Revit tools must be written directly into the prompt text (~15k – 25k tokens), overflowing the default local context by 5x to 10x.
Tool Selection	Large cloud models (Claude 3.5 Sonnet, GPT-4o) are highly accurate at choosing the right tool out of 110+ options.	Small local models (7B - 8B) get confused or make mistakes when presented with too many tool choices.
Response Speed	Fast and nearly instantaneous.	The first response can be noticeably slow because the model needs to reload into memory with a larger context window.
Privacy & Internet	Requires a stable internet connection. Pay-as-you-go based on API key usage.	Works completely offline. Zero cost and maximum data privacy since your model data never leaves your computer.

The "Blindfolded" Model: Why Local LLMs Failed (Before v1.1)

In earlier versions, when running offline via Ollama or LM Studio, the assistant would often reply with general chat but fail to trigger any Revit tools.

Why did this happen?

1. The system instructions and 110 tool definitions generated a massive prompt (~15k - 25k tokens).
2. Since no explicit num_ctx size was set, Ollama ran at its default limit (2048 - 4096 tokens) and silently cut off (truncated) the beginning of the prompt to fit into memory.
3. The truncated part contained the most important instructions: "You are T3Lab Assistant, use these tools to modify Revit...". Without this context, the local LLM behaved like a basic chatbot and was completely "blind" to Revit's APIs.

---

2. Optimizations for Local LLMs (v1.1+)

To make offline models work reliably on personal computers, we implemented three key optimizations:

A. Dynamic Context Window Sizing (num_ctx)

The assistant now uses a dynamic sizing helper _num_ctx_for() in ollama_provider.py:

• General Chat: Uses a minimal context window of 8,192 tokens to save computer resources.
• Tool Execution: Automatically doubles or quadruples the context size up to 16,384 or 32,768 tokens based on the actual request size.
• Custom Environment Variables: Advanced users can control these limits via:
  • T3LAB_OLLAMA_NUM_CTX_MIN (Default: 8192)
  • T3LAB_OLLAMA_NUM_CTX_MAX (Default: 32768)

[!WARNING] VRAM & RAM Performance Tip: When Ollama loads a model with a larger context (16k - 32k), the first query after starting or reloading Revit will take longer to load. This is because the local engine must allocate an extra 1.5GB – 2GB of VRAM/RAM (for 7B-8B models). If your machine is lagging or running out of memory, you can limit VRAM consumption by setting the system environment variable: T3LAB_OLLAMA_NUM_CTX_MAX = 16384 or 8192.

B. Filtered Essential Tool Catalog (ESSENTIAL_TOOL_NAMES)

Instead of sending all 110+ Revit tools to a small local model, we filter the catalog down to 39 essential tools (e.g. selection, reading parameters, editing parameters, showing/hiding, PDF/DWG export, joining geometry).

• Local Providers (Ollama / LM Studio): Only receive these 39 core tools. This fits comfortably in the context window and improves tool selection accuracy to over 90%.
• Cloud Providers (Claude / GPT / DeepSeek): Continue to receive all 110+ tools to take advantage of their advanced reasoning capabilities.

C. Unified Agentic Workflow

The filtered tool list is applied automatically to both the Native Agent (_run_native_agent) and the Legacy JSON Catalog fallback paths whenever a local engine (ollama or lmstudio) is detected.

---

3. List of the 39 Essential Tools (Available for Local LLMs)

Local models have access to these core functions to perform standard operations:

Querying the Model

• revit_get_active_view: Get details of the active view.
• revit_get_selected_elements: Read selected elements.
• revit_get_project_info: Read project name, number, and location.
• revit_list_views / revit_list_sheets: List views and sheets in the project.
• revit_get_element_info / get_all_parameters: Retrieve parameters and geometric data for an element ID.
• get_current_view_elements: Get elements visible in the active view.
• list_levels / list_worksets: Get all levels (elevations) and worksets.

Creating Elements

• create_level: Create a new level.
• create_view / create_sheet: Generate new views or sheets.
• create_text_note / create_dimension: Add text notes or dimension chains.
• place_wall: Draw a straight wall using coordinate inputs.
• create_point_based_element: Place point-based families (Doors, Windows, Furniture, Fixtures).

Modifying Elements

• set_parameter / bulk_set_parameter: Change parameter values on one or more elements.
• move_elements / copy_elements / rotate_element: Move, copy, or rotate elements.
• delete_element: Safe element deletion.
• operate_element: Select, hide, unhide, or isolate elements in the view.
• color_elements: Color-code elements based on a parameter rule.
• join_geometry: Join or unjoin intersecting element geometries.

Automation & Exports

• export_sheets_pdf: Export sheets to PDF files.
• export_dwg / export_image: Export drawings to DWG files or high-res PNG images.
• show_assistant_pane: Show or hide the T3Lab Assistant panel.

---

4. How to Configure the Assistant

A. Setting Up Cloud API (Recommended)

1. Open Revit, go to the T3Lab tab > Support panel > click T3Lab Assistant.
2. Click the Settings (Gear Icon) in the top-right corner of the chat window.
3. Select your provider and enter your API Key:
   • Anthropic (Claude): Paste your key starting with sk-ant-... (Recommended model: claude-3-5-sonnet).
   • OpenAI (GPT): Paste your key starting with sk-... (Recommended model: gpt-4o).
   • DeepSeek: Paste your key starting with sk-... (Recommended model: deepseek-chat or deepseek-coder).
4. Click Save. The assistant will connect instantly.

B. Setting Up Local LLM (Offline)

1. Install Ollama: Download and install Ollama from ollama.com.
2. Download a Model: Open your terminal (PowerShell or Command Prompt) and run:

   ollama run qwen2.5-coder:7b
   # Or Llama 3.1
   ollama run llama3.1
   

3. Configure Revit:
   • Open the T3Lab Assistant Settings panel.
   • Select Ollama (or LM Studio) as your provider.
   • Default API Endpoint: http://localhost:11434 (Ollama) or http://localhost:1234 (LM Studio).
   • Enter the exact name of the model you downloaded (e.g. qwen2.5-coder:7b).
4. Tune Environment Variables (Optional):
   • If you want to limit VRAM usage to prevent system slowdowns:
     • Search for "Environment Variables" in Windows.
     • Add a system variable: T3LAB_OLLAMA_NUM_CTX_MAX and set its value to 16384 or 8192.
     • Restart Revit to apply.