Improving Convenience Function Discovery

[deekshas8]

Context

We need to decide on the best approach for organizing/documenting our convenience functions to make them easily discoverable.

Below are the some ideas I could come up with. Please add your comments on your preferred approach/make suggestions that have not been considered.

Current Approach

Note: lama guard and masking functions are added only as examples here.

import { ContentFilters, buildDocumentGroundingConfig, buildDpiMaskingConfigAnon } from '@sap-ai-sdk/orchestration';

const orchestrationClient = new OrchestrationClient({ llm, templating,
  filtering: {
    input: {
      filters: [
        ContentFilters.buildAzureContentSafety({ Hate: 4, SelfHarm: 2 }),
        ContentFilters.buildLamaGuardFilter()
      ]
    }
  },
  grounding: buildDocumentGroundingConfig({
    input_params: ['input'],
    output_param: 'output'
  }),
  masking: {
    masking_providers: [buildDpiMaskingConfigAnon()]
  }
});

Ideas

1. Namespace-style Organization (Current Approach: ContentFilters.buildX())

import { ContentFilters } from '@sap-ai-sdk/orchestration';
ContentFilters.buildAzureContentSafety({ Hate: 4, SelfHarm: 2 })

or with sub-paths
import { buildAzureContentSafety } from '@pkg/orchestration/utils';

or with namespaces
import { utils } from '@pkg/orchestration';
utils.buildAzureContentSafety({ Hate: 4, SelfHarm: 2 })

Pros:

• Groups related functions together
• Clear categorization

Cons:

• Object grouping generally not a common practice in modern JavaScript/TypeScript

• Impacts tree-shaking (excl. sub-path approach)

• Discovery relies on knowing the namespace/path

• (Object grouping) Inconsistent naming patterns between config properties and their corresponding namespaces. This makes it unintuitive to guess the namespace name from the config property

  filtering → ContentFilters       // Inconsistent
  grounding → Grounding           // Consistent
  masking → Masking              // Consistent

2. Named Function Imports

import { buildAzureContentSafety, buildLamaGuardFilter } from '@sap-ai-sdk/orchestration';

Pros:

• More consistent with modern JS practices
• Better tree-shaking
• Clearer dependencies
• Direct discovery through IDE autocomplete (type "build" to see all options)

Cons:

• May lead to many imports
• Could be harder to discover related functions (mitigated by build* prefix)

3. Factory Function Approach (Like resilience example in Cloud SDK)

// Option A: Extract components with configuration
const [azureFilter, lamaGuardFilter] = buildContentFilters({ 
  azure: { Hate: 4, SelfHarm: 2 },
  lamaGuard: {} 
});

// Option B: Direct usage
filtering: buildContentFilters({ 
  azure: { Hate: 4, SelfHarm: 2 },
  lamaGuard: {}
})

Pros:

• More concise
• Easier to discover available options

Cons:

• Less explicit about what's being created
• Configuration becomes nested (might be less discoverable)
• Hides complexity that should be visible

Additional: Enhanced TSDoc Documentation and Consistent Naming

Questions for Discussion

1. Which approach best balances discoverability with modern JS practices?
2. How important is tree-shaking in our use case?
3. How can we ensure good IDE support (especially VS Code intellisense) regardless of the chosen approach?
4. Which naming convention alignment approach would be most intuitive for users?
   • Would the build* prefix convention provide better discoverability than namespaces?

Decision

• Keep named function imports
• Improve our jsdoc documents to include @example for making convenience more discoverable
• Use consistent naming across convenience functions (e.g. buildAzureContentFilter, buildDocumentGrounding) so user discovers all functions through intellisense and can also intiutively guess which function is for which module. We should still pay attention to keeping them shorter
• (Option 3) We can consider this in the future if we feel it drastically reduces object nesting while keeping functionality consistent

[jjtang1985]

Independent to different options, I like the "Additional: Enhanced TSDoc Documentation and Consistent Naming" section 😃