Instruction Augmentation (Semantic Directives)

export interface SemanticDirective {
    /**
     * Scope determines when this directive might be relevant. Supports:
     * - Simple: "chatapp#weather-app", "agent#sales-bot", "tool#calculator", "entity#{entityValue}"
     * - Compound: "agent#sales-bot#entity#{entityValue}"
     *
     * You don't set this value directly. Instead, you set the scopeType and scopeValue
     * from which the system will construct the scope.
     */
    scope: string;

    /**
     * The type of scope this semantic directive is associated with.
     * Supported types: 'chatapp', 'agent', 'tool', 'entity', 'agent-entity'
     */
    scopeType: InstructionAugmentationScopeType;

    /**
     * The value(s) for the scope. Type depends on scopeType:
     * - For 'chatapp', 'agent', 'tool', 'entity': string or number
     * - For 'agent-entity': {agent: string, entity: string}
     */
    scopeValue: string | number | Record<string, string | number>;

    /**
     * Unique identifier within the scope. Use descriptive names like
     * "return-policy-details" or "premium-customer-perks"
     */
    id: string;

    /**
     * Used internally to group semantic directives created by infrastructure-as-code.
     * Don't set this value directly - let the custom CloudFormation resource set it.
     */
    groupId?: string;

    /**
     * Description for the LLM selection process. Should clearly explain
     * when this directive is relevant to help the LLM make good decisions.
     */
    description: string;

    /**
     * Instructions to inject into the prompt when this directive is selected.
     * Keep focused and actionable for best LLM performance.
     */
    instructions: string;

    /** ISO 8601 timestamp of creation */
    createDate: string;

    /** User who created the directive */
    createdBy: string;

    /** User who last updated the directive */
    lastUpdatedBy: string;

    /** ISO 8601 timestamp of last update */
    lastUpdate: string;
}

// Chat app specific
'chatapp#ecommerce-store';

// Agent specific
'agent#customer-service-bot';

// Tool specific
'tool#weather-forecast-api';

// Entity specific, perhaps an account ID or company ID
'entity#123';

// Agent + Entity combination
'agent#sales-assistant#entity#123';

//INVALID:  Only agent + entity in that order currently supported
'chatapp#support-portal#tool#ticket-system';

siteFeatures: {
    entity: {
        enabled: true,
        attributeName: 'accountId', // Field in user.customData containing entity ID
        displayNameSingular: 'Account',
        // ... other entity config
    }
}

// In your authentication provider
return {
    authenticatedUser: {
        userId: 'user123',
        // ... other user fields
        customData: {
            accountId: '123', // This field name must match entity.attributeName
            email: 'user@company.com'
            // ... other custom data
        }
    }
};

// Configuration
const entityConfig = {
    attributeName: 'companyId',
};

// User data
const user = {
    customData: {
        companyId: 'acme-corp',
        email: 'user@acme.com'
    }
};

// Resulting entity scope: 'entity#acme-corp'
const entityScope = `entity#${user.customData[entityConfig.attributeName]}`;

// Directives that would match this user:
{
    scope: "entity#acme-corp", // Direct entity match
    id: "company-policies",
    description: "Company-specific policies and procedures",
    instructions: "Always reference Acme Corp policies when discussing procedures."
}

{
    scope: "agent#support-bot#entity#acme-corp", // Compound scope match
    id: "escalation-process",
    description: "Acme Corp specific escalation procedures",
    instructions: "For Acme Corp users, escalate to their dedicated account manager for priority issues."
}

export const siteFeatures: SiteFeatures = {
    instructionAugmentation: {
        enabled: true
    }
    // ... other features
};

POST /api/chat-admin/semantic-directive

{
    "semanticDirective": {
        "scope": "chatapp#weather-app",
        "id": "severe-weather-alerts",
        "description": "Safety instructions for severe weather conditions",
        "instructions": "When reporting severe weather, always emphasize safety precautions and recommend checking local authorities for emergency guidance.",
        "createdBy": "admin-user",
        "lastUpdatedBy": "admin-user"
    },
    "userId": "admin-user"
}

DELETE /api/chat-admin/semantic-directive

{
    "semanticDirective": {
        "scope": "chatapp#weather-app",
        "id": "severe-weather-alerts"
    },
    "userId": "admin-user"
}

POST /api/chat-admin/semantic-directive/search

{
    "scopes": ["chatapp#weather-app"],
    "createdBy": "admin-user",
    "directiveIds": ["severe-weather-alerts", "temperature-format"],
    "createdAfter": "2024-01-01T00:00:00Z",
    "createdBefore": "2024-12-31T23:59:59Z",
    "updatedAfter": "2024-06-01T00:00:00Z",
    "updatedBefore": "2024-06-30T23:59:59Z",
    "sortOrder": "desc",
    "limit": 50,
    "includeInstructions": true,
    "paginationToken": "eyJhbGciOiJIUzI1NiJ9..."
}

// In your SvelteKit client state
const siteAdminState = getSiteAdminState();

// Load all semantic directives
await siteAdminState.loadSemanticDirectives();

// Access directives
const directives = siteAdminState.semanticDirectives;

// Create or update directive
await siteAdminState.sendSiteAdminCommand({
    command: 'createOrUpdateSemanticDirective',
    request: {
        semanticDirective: {
            scope: 'chatapp#my-app',
            id: 'new-directive',
            description: 'Directive description',
            instructions: 'Specific instructions for the LLM',
            createdBy: userId,
            lastUpdatedBy: userId
        },
        userId: userId
    }
});

// Delete directive
await siteAdminState.sendSiteAdminCommand({
    command: 'deleteSemanticDirective',
    request: {
        semanticDirective: {
            scope: 'chatapp#my-app',
            id: 'directive-to-delete'
        },
        userId: userId
    }
});

// Search with filters
await siteAdminState.sendSiteAdminCommand({
    command: 'searchSemanticDirectives',
    request: {
        scopes: ['chatapp#my-app'],
        includeInstructions: true
    }
});

// 1. Scope-based queries (most efficient)
if (scopes?.length) {
    // Parallel queries across scopes on main table
    return searchByScopes(scopes);
}

// 2. Creator-based queries
if (createdBy) {
    // Use GSI1 for efficient creator lookup
    return searchByCreator(createdBy);
}

// 3. ID-based queries
if (directiveIds?.length) {
    // Parallel queries on GSI2
    return searchByDirectiveIds(directiveIds);
}

// 4. Full table scan (last resort)
return scanAllSemanticDirectives();

// Test directive creation
const directive = {
    scope: 'chatapp#test-app',
    id: 'test-directive',
    description: 'Test directive for unit testing',
    instructions: 'Test instructions for validation',
    createdBy: 'test-user',
    lastUpdatedBy: 'test-user'
};

// Validate directive structure
expect(directive.scope).toMatch(/^[a-z]+#[a-z-]+$/);
expect(directive.id).toMatch(/^[a-z-]+$/);
expect(directive.instructions.length).toBeGreaterThan(10);

// Test end-to-end directive flow
const query = "What's our return policy?";
const context = {
    chatAppId: 'ecommerce-store',
    agentId: 'shopping-assistant',
    userType: 'premium-customer'
};

const enhancedPrompt = await augmentPrompt(basePrompt, query, context);

// Verify directive was injected
expect(enhancedPrompt).toContain('premium customers get 60-day returns');

// Directive retrieval process
console.log('Retrieved directives for scope:', scope, directives);

// LLM selection decisions
console.log('Selected directives:', selectedDirectives);

// Prompt injection results
console.log('Enhanced prompt length:', enhancedPrompt.length);