AI Commons Create Bot Technical Specification - Changelog

Version 2.0 - February 2025

This document tracks all corrections and updates made to the AI Commons Create Bot Technical Specification based on the comprehensive audit review.

Files Updated

• create-bot-technical-spec.html
• bot-configuration-guide.html

Update Type

Systematic correction of technical inaccuracies, expansion of implementation details, and clarification of behavior specifications.

Section 1: Basic Configuration

1. Name → Title Terminology Change

• Updated field labels and descriptions
• Corrected all table entries
• Updated validation behavior references

2. Title Field Whitespace Validation

Before: Documentation suggested whitespace-only titles might be accepted

After: Clarified that whitespace-only titles are NOT accepted; Create button is disabled for whitespace-only input

Section 7: Internet Search

3. Internet Search Provider Expansion

DuckDuckGo Provider:

• Trial tier (no API key required)
• Maximum 20 results
• Moderate safe search enabled by default

Firecrawl Provider:

• Business tier (requires API key)
• UI accepts 1-50 results
• Backend supports up to 100 results

Section 8: Bedrock Agent

4. Bedrock Agent Implementation Details

• Added invoke_agent API implementation details
• Documented trace collection enablement (captures tool invocations, reasoning steps, decision-making)
• Documented response assembly with trace-derived artifacts
• Added comparison table between Internet Search and Bedrock Agent

Section 9: Knowledge Base Configuration

5. Knowledge Base Source Options

Source Types Documented:

• File Upload: Direct document upload
• Amazon S3: S3 path prefixes with trailing slash requirement, maximum 4 sources
• Web Crawler: Maximum 10 URLs, regex patterns for include/exclude
• Existing KB: Read-only mode that disables source editing

6. Citation Display Behavior

Clarified that retrieval still occurs when OFF; control only affects display and storage of citations.

7. Read-Only Settings After Creation

Settings That Become Read-Only:

• Existing KB ID
• Embedding Model
• Parsing Method
• Chunking Strategy
• Analyzer Settings

Section 10: Quick Starters (NEW)

8. Quick Starters Section Added

• Created new dedicated section #10
• Documented field requirements (title required if kept, response optional)
• Runtime behavior: without response = live generation, with response = pre-seeded reply
• Updated all subsequent section numbers (Generation=#11, Advanced=#12, Guardrails=#13, Models=#14)

Section 11: Generation Settings

9-15. Generation Parameter Corrections

Model-Specific Behaviors Added:

• Amazon Nova: Top K clamped above 128
• Qwen: Stop sequences not used; reasoning_effort only when enabled
• GPT-OSS: Stop sequences not used; reasoning_effort always derived from budget
• Budget Overflow: Backend auto-raises maxTokens if budget ≥ maxTokens

Section 12: Advanced Settings

16-20. Parsing and Chunking Specifications

Parsing Methods:

• Removed "Custom Parser" (not available)
• Two active methods: Foundation Model Parsing, Default Parsing
• Added Analyzer control documentation

Fixed-Size Chunking:

• Max Tokens: 1-8,192 (Titan v2) or 1-512 (Cohere)
• Overlap: 1-99%

Hierarchical Chunking:

• Parent ≥ Child constraint
• Both must respect embedding model ceilings
• Overlap: 1-99%

Semantic Chunking:

• Max Tokens: 1-8,192 (Titan v2) or 1-512 (Cohere)
• Buffer: 0-1
• Breakpoint Percentile: 50-99

Section 13: Guardrails Configuration

22-27. Guardrails Corrections

Content Filter Categories (Exactly 5):

1. Hate
2. Insults
3. Sexual
4. Violence
5. Misconduct

Removed: Privacy category

Grounding Checks (2 Only):

• Contextual Grounding
• Relevance Check

Removed: Hallucination Detection

Sensitivity Levels:

• Content Filters: 0-3 (integers) where 0=off, 1=low, 2=medium, 3=high
• Grounding Checks: 0.0-0.99 (decimals) where 0=off, higher=stricter

Activation Rule:

Any non-zero value activates the guardrail

Section 14: Model Activation

28-30. Active Models Behavior

• Clarified Model Activation is an allowlist, not single selection
• Multiple models can be activated simultaneously
• Users choose among activated models
• Documented fallback: when selected model removed, falls back to first available model

Impact Summary

Breaking Changes

None. All changes are clarifications and corrections to existing behavior documentation.

New Sections Added

1. Quick Starters (Section #10)
2. Read-Only Settings After Creation (subsection in Knowledge Base)
3. Analyzer Control (subsection in Advanced Settings)
4. Model Removal Fallback Behavior (subsection in Model Activation)

Deprecated/Removed Items

• "Privacy" content filter category (not implemented)
• "Hallucination Detection" guardrail check (not a separate category)
• "Custom Parser" option (not available for selection)

Section Renumbering

Due to the addition of Quick Starters as Section #10:

• Generation Settings: #10 → #11
• Advanced Settings: #11 → #12
• Guardrails: #12 → #13
• Model Activation: #13 → #14

Related Documents

• Technical Specification
• Quick Reference Guide

Maintenance Notes

Last Updated: February 2025

Review Cycle: Quarterly or when significant platform changes occur

Maintained By: AI Commons Documentation Team

Future Documentation Updates Should Verify:

• Model availability and tier classifications
• Bedrock service limit changes
• New embedding model options
• Additional content filter categories
• Generation parameter defaults for new models