Skip to content

feat: add escapeTemplatePlaceholders option #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jerome-benoit merged 8 commits into from
Jan 27, 2026
Merged

feat: add escapeTemplatePlaceholders option #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3759bea
feat: add escapeTemplatePlaceholders option to prevent orchestration …
jerome-benoit Jan 27, 2026
baf7447
fix: resolve lint ordering issues for escaping utilities
jerome-benoit Jan 27, 2026
4220853
fix: escape all Jinja2 delimiters ({{, {%, {#})
jerome-benoit Jan 27, 2026
8965e30
feat!: change escapeTemplatePlaceholders default to true
jerome-benoit Jan 27, 2026
a75f41a
chore: harmonize docs, tests, and move publish simulation to release …
jerome-benoit Jan 27, 2026
90e1292
chore: harmonize escapeTemplatePlaceholders JSDoc comment
jerome-benoit Jan 27, 2026
bf37961
chore: harmonize test names for template placeholder escaping
jerome-benoit Jan 27, 2026
5d191a3
chore: harmonize documentation format and fix anchor links
jerome-benoit Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 0 additions & 43 deletions .github/workflows/check-pr.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,46 +75,3 @@ jobs:
run: npm run build
- name: Check build outputs
run: npm run check-build

publish-check:
name: Publish Simulation
runs-on: ubuntu-latest
needs: [format-check, type-check, test, build]
if: github.event_name == 'pull_request'
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: 24
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Build package
run: npm run build
- name: Determine npm tag for dry-run
id: tag
run: |
VERSION=$(node -p "require('./package.json').version")
if [[ "$VERSION" =~ -alpha ]]; then
echo "tag=alpha" >> $GITHUB_OUTPUT
elif [[ "$VERSION" =~ -beta ]]; then
echo "tag=beta" >> $GITHUB_OUTPUT
elif [[ "$VERSION" =~ -rc ]]; then
echo "tag=next" >> $GITHUB_OUTPUT
elif [[ "$VERSION" =~ -canary ]]; then
echo "tag=canary" >> $GITHUB_OUTPUT
elif [[ "$VERSION" =~ - ]]; then
echo "tag=next" >> $GITHUB_OUTPUT
else
echo "tag=latest" >> $GITHUB_OUTPUT
fi
echo "Detected version: $VERSION, using tag: $(cat $GITHUB_OUTPUT | grep tag | cut -d= -f2)"
- name: Simulate npm publish
run: npm publish --dry-run --tag ${{ steps.tag.outputs.tag }}
- name: Check publishable files
run: |
echo "📦 Checking package contents:"
npm pack --dry-run 2>/dev/null | head -20 || true
echo "✅ Package can be published successfully"
2 changes: 2 additions & 0 deletions .github/workflows/npm-publish-npm-packages.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,5 +59,7 @@ jobs:
echo "tag=latest" >> $GITHUB_OUTPUT
echo "Publishing as 'latest' tag for stable version $VERSION"
fi
- name: Simulate npm publish
run: npm publish --dry-run --tag ${{ steps.tag.outputs.tag }}
- name: Publish to npm
run: npm publish --provenance --access public --tag ${{ steps.tag.outputs.tag }}
21 changes: 12 additions & 9 deletions API_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1040,15 +1040,16 @@ Model-specific configuration options.

**Properties:**

| Property | Type | Default | Description |
| ------------------ | ---------------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `modelVersion` | `string` | `'latest'` | Specific model version |
| `includeReasoning` | `boolean` | - | Whether to include assistant reasoning parts in SAP prompt conversion (may contain internal reasoning) |
| `modelParams` | `ModelParams` | - | Model generation parameters |
| `masking` | `MaskingModule` | - | Data masking configuration (DPI) |
| `filtering` | `FilteringModule` | - | Content filtering configuration |
| `responseFormat` | `ResponseFormatConfig` | - | Response format specification |
| `tools` | `ChatCompletionTool[]` | - | Tool definitions in SAP AI SDK format |
| Property | Type | Default | Description |
| ---------------------------- | ---------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `modelVersion` | `string` | `'latest'` | Specific model version |
| `includeReasoning` | `boolean` | - | Whether to include assistant reasoning parts in SAP prompt conversion (may contain internal reasoning) |
| `escapeTemplatePlaceholders` | `boolean` | `true` | Escape template delimiters (`{{`, `{%`, `{#`) in message content to prevent conflicts with SAP orchestration templating |
| `modelParams` | `ModelParams` | - | Model generation parameters |
| `masking` | `MaskingModule` | - | Data masking configuration (DPI) |
| `filtering` | `FilteringModule` | - | Content filtering configuration |
| `responseFormat` | `ResponseFormatConfig` | - | Response format specification |
| `tools` | `ChatCompletionTool[]` | - | Tool definitions in SAP AI SDK format |

**Example:**

Expand Down Expand Up @@ -1079,6 +1080,8 @@ const settings: SAPAISettings = {
};
```

> **Note:** The `escapeTemplatePlaceholders` option is enabled by default to prevent SAP AI Core orchestration API errors when content contains template syntax (`{{variable}}`, `{% if %}`, `{# comment #}`). Set to `false` only if you intentionally use SAP orchestration templating features. See [Troubleshooting - Problem: Template Placeholder Conflicts](./TROUBLESHOOTING.md#problem-template-placeholder-conflicts) for details.

Comment on lines +1083 to +1084
Copy link

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While the escapeTemplatePlaceholders property is documented in this table, the new exported utility functions escapeOrchestrationPlaceholders and unescapeOrchestrationPlaceholders (exported from src/index.ts) should also be documented in the API Reference. Consider adding them to the Utility Functions section with their signatures, parameters, return values, and usage examples to maintain consistency with the existing documentation pattern.

Copilot uses AI. Check for mistakes.
---

### `ModelParams`
Expand Down
72 changes: 61 additions & 11 deletions TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,18 @@ Provider.

## Quick Reference

| Issue | Section |
| --------------------- | --------------------------------------------------------------------- |
| 401 Unauthorized | [Authentication Issues](#problem-authentication-failed-or-401-errors) |
| 403 Forbidden | [Authentication Issues](#problem-403-forbidden) |
| 404 Not Found | [Model and Deployment Issues](#problem-404-modeldeployment-not-found) |
| 400 Bad Request | [API Errors](#problem-400-bad-request) |
| 429 Rate Limit | [API Errors](#problem-429-rate-limit-exceeded) |
| 500-504 Server Errors | [API Errors](#problem-500502503504-server-errors) |
| Tools not called | [Tool Calling Issues](#problem-tools-not-being-called) |
| Stream issues | [Streaming Issues](#problem-streaming-not-working-or-incomplete) |
| Slow responses | [Performance Issues](#problem-slow-response-times) |
| Issue | Section |
| --------------------- | ---------------------------------------------------------------------------------- |
| 401 Unauthorized | [Authentication Issues](#problem-authentication-failed-or-401-errors) |
| 403 Forbidden | [Authentication Issues](#problem-403-forbidden) |
| 404 Not Found | [Model and Deployment Issues](#problem-404-modeldeployment-not-found) |
| 400 Bad Request | [API Errors](#problem-400-bad-request) |
| 400 Template errors | [Problem: Template Placeholder Conflicts](#problem-template-placeholder-conflicts) |
| 429 Rate Limit | [API Errors](#problem-429-rate-limit-exceeded) |
| 500-504 Server Errors | [API Errors](#problem-500502503504-server-errors) |
| Tools not called | [Tool Calling Issues](#problem-tools-not-being-called) |
| Stream issues | [Streaming Issues](#problem-streaming-not-working-or-incomplete) |
| Slow responses | [Performance Issues](#problem-slow-response-times) |

## Common Problems (Top 5)

Expand Down Expand Up @@ -60,6 +61,7 @@ below.
- [API Errors](#api-errors)
- [Parsing SAP Error Metadata (v3.0.0+)](#parsing-sap-error-metadata-v300)
- [Problem: 400 Bad Request](#problem-400-bad-request)
- [Problem: Template Placeholder Conflicts](#problem-template-placeholder-conflicts)
- [Problem: 429 Rate Limit Exceeded](#problem-429-rate-limit-exceeded)
- [Problem: 500/502/503/504 Server Errors](#problem-500502503504-server-errors)
- [Model and Deployment Issues](#model-and-deployment-issues)
Expand Down Expand Up @@ -165,6 +167,54 @@ request, incompatible features
- Check API Reference for valid parameter ranges
- Enable verbose logging to see exact request

### Problem: Template Placeholder Conflicts

**Symptoms:** HTTP 400 with error messages like:

- `"Unused parameters: [...]"`
- Template parsing errors when message content contains `{{`, `{%`, or `{#`

**Cause:** SAP AI Core's orchestration API uses template syntax
(`{{variable}}`, `{{?variable}}`, `{% if %}`, `{# comment #}`) for prompt templating. When tool results or
message content contains these patterns, the API incorrectly interprets them as template directives.

**Solutions:**

The `escapeTemplatePlaceholders` option is **enabled by default**,
which should prevent this issue. If you still encounter it, verify that you
haven't explicitly disabled escaping:

```typescript
// Escaping is enabled by default - no configuration needed
const provider = createSAPAIProvider();

// If you need to disable escaping (e.g., to use SAP orchestration templating)
const provider = createSAPAIProvider({
defaultSettings: {
escapeTemplatePlaceholders: false, // Opt-out of automatic escaping
},
});
```

**How it works:**

The option inserts a zero-width space (U+200B) between template opening delimiters
(`{{` becomes `{\u200B{`, `{%` becomes `{\u200B%`, `{#` becomes `{\u200B#`),
breaking the pattern while keeping content visually unchanged. JSON structures
with `}}` (closing braces) are preserved.

**Manual escaping utilities:**

```typescript
import { escapeOrchestrationPlaceholders, unescapeOrchestrationPlaceholders } from "@jerome-benoit/sap-ai-provider";

const escaped = escapeOrchestrationPlaceholders("Use {{?question}} to prompt");
// Result: "Use {\u200B{?question}} to prompt"

const restored = unescapeOrchestrationPlaceholders(escaped);
// Result: "Use {{?question}} to prompt"
```

### Problem: 429 Rate Limit Exceeded

**Solutions:**
Expand Down
Loading
Loading