> For the complete documentation index, see [llms.txt](https://docs.openbrim.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbrim.org/developers/llm-guides/ai-export.md). # Export ## Overview This guide covers the **Export object** and its critical role in managing dependencies and scope when working with object instances. **Prerequisites:** Read `creating-instances.md` first **What you'll learn:** * Why Export exists and what goes in it * **The Dependency Rule** (critical!) * Instance scope (inside component vs in instance) * Why missing parameters = 0 * Complex nested instances * Debugging export issues * Best practices *** ## What is the Export Object? The `` object controls **what is accessible** when someone creates an instance of your component. **Purpose:** * Define the **public interface** of your component * Hide implementation details * Control what other components can access ### Basic Structure ```xml

... ``` *** ## The Dependency Rule ⚠️ CRITICAL **The most important rule when using Export:** > **Any parameter referenced by an exported parameter must also be exported (or be a `Role="Input"` parameter).** ### Why This Rule Exists When you create an instance, exported parameters are **copied** to the instance. They **lose access** to non-exported parameters. **Missing parameters evaluate to 0, breaking calculations.** ### The Problem **Component definition:** ```xml

``` **Inside the component - works fine:** ```xml

``` **In an instance - breaks:** ```xml

``` ### The Fix **Move all dependencies inside Export:** ```xml

``` **Now works in instances:** ```xml

``` *** ## Instance Scope and Isolation Understanding how scope works is critical for Export. ### Two Different Contexts | Context | Can Access | Cannot Access | | -------------------- | ----------------------- | ----------------------- | | **Inside component** | Everything in component | Nothing | | **In instance** | Inputs + Exports only | Non-exported parameters | ### Inside the Component Parameters inside Export **CAN** access parameters outside Export: ```xml

``` ### In an Instance Exported parameters are **copied** and **isolated**: ```xml

``` **The parameters work inside the component but fail in instances!** ### Why This Happens 1. Instance is created 2. System copies inputs and exports to instance 3. Exported parameters **no longer have access** to the original component's internal parameters 4. Missing parameters → evaluate to **0** 5. Calculations break *** ## Chain of Dependencies **All levels of dependency must be exported.** ### Wrong: Incomplete Dependency Chain ```xml

``` **In instance:** ```xml

``` ### Right: Complete Dependency Chain ```xml

``` **In instance:** ```xml

``` *** ## What to Put in Export ### ✅ Put in Export **Calculated results users need:** ```xml

``` **Analysis results:** ```xml

``` **Nested objects for external access:** ```xml

``` **Status/flags:** ```xml

``` ### ❌ Keep Outside Export **Geometry:** ```xml ``` **Intermediate calculations (if not needed externally):** ```xml

``` **BUT:** If exported parameters reference them, they **must** be in Export! **Implementation details:** ```xml

``` *** ## Complex Nested Instances When instances contain instances, Export becomes crucial. ### Example: House Using Cube **Cube component:** ```xml

``` **House component:** ```xml

``` **Instance of House:** ```xml

``` **Access nested values:** ```xml

``` ### What If House\_Base Wasn't Exported? **House without exporting House\_Base:** ```xml

``` **Instance:** ```xml

``` **Problems:** ```xml

``` *** ## Common Mistakes ### ❌ Mistake 1: Missing Simple Dependency ```xml

``` **Instance:** ```xml

``` **Fix:** ```xml

``` ### ❌ Mistake 2: Partial Dependency Chain ```xml

``` **In instance:** ```xml

``` **Fix:** ```xml

``` ### ❌ Mistake 3: Not Exporting Nested Object ```xml

``` **Instance:** ```xml

``` **Fix:** ```xml

``` ### ❌ Mistake 4: Over-Exporting (Anti-pattern) ```xml

``` **Problems:** * ❌ Cluttered interface * ❌ Exposes implementation details * ❌ Hard to refactor * ❌ Confusing for users **✅ Better - Export only what final results depend on:** ```xml

``` **In this example:** * ❌ `debug_flag`, `temp_var` - NOT exported (not used by exported results) * ✅ `load_factor`, `resistance_factor`, `material_strength` - Exported (used by `capacity` and `demand`) * ✅ `capacity`, `demand` - Exported (used by `utilization`) * ✅ `utilization`, `passes` - Exported (final results) **In this example:** * ❌ `load_factor`, `resistance_factor`, `material_strength` - NOT exported (internal only) * ✅ `capacity`, `demand` - Exported (needed by `utilization`) * ✅ `utilization`, `passes` - Exported (final results) ## Debugging Export Issues ### Problem: Calculation works in component but returns 0 or wrong value in instance **Diagnosis:** Missing dependency **Steps:** 1. Find the exported parameter with wrong value 2. Look at its formula 3. Check each parameter referenced: * Is it inside Export? ✅ * Does it have `Role="Input"`? ✅ * If neither → **That's the problem** 4. Move missing dependency inside Export **Example:** ```xml

``` ### Problem: Can't access nested object **Diagnosis:** Nested object not in Export **Steps:** 1. Find where nested object is defined 2. Check if it's inside `` 3. If outside → move it inside Export **Example:** ```xml

``` ### Problem: Value is infinity or NaN **Diagnosis:** Division by zero - missing parameter evaluates to 0 **Steps:** 1. Find the division operation 2. Check if denominator is: * Inside Export ✅ * Has `Role="Input"` ✅ * If neither → **That's the problem** **Example:** ```xml

``` ### Problem: Instance seems to have old/wrong values **Diagnosis:** Dependencies changed but not updated in Export **Steps:** 1. Check if all dependencies are in Export 2. Verify formulas are correct 3. Check if intermediate values need to be exported *** ## Best Practices ### 1. Always Export Dependencies **Rule:** If parameter X references parameter Y, both must be exported (or Y must be input). ```xml

``` ### 2. Test with Instances Always create test instances: ```xml

``` **If test fails → fix Export dependencies** ### 3. Minimize Export Surface Only export what's truly needed: ```xml

``` ### 4. Document Exported Parameters ```xml

``` ### 5. Group Related Exports ```xml

... ...

``` ### 6. Trace Dependency Chains When exporting calculated values, trace all dependencies: ```xml

``` ### 7. Use Meaningful Export Names ```xml

``` *** ## Summary ### Critical Rules 1. **Dependency Rule:** Exported parameters must only reference: * Other exported parameters * Input parameters (`Role="Input"`) 2. **Missing Parameters = 0:** Non-exported parameters evaluate to 0 in instances 3. **Scope Isolation:** Instances cannot access non-exported parameters 4. **Test with Instances:** Working inside ≠ working in instances 5. **Export Nested Objects:** For external access, nested instances must be in Export ### Quick Checklist When creating Export: * [ ] All dependencies inside Export or are inputs? * [ ] Nested objects that need external access inside Export? * [ ] Tested with actual instance? * [ ] Exported parameters have descriptions? * [ ] Only exporting what's needed (not over-exporting)? *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.openbrim.org/developers/llm-guides/ai-export.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.