mirror of
https://github.com/meta-llama/llama-stack.git
synced 2025-12-11 19:56:03 +00:00
fix: UI bug fixes and comprehensive architecture documentation
- Fixed Agent Instructions overflow by adding vertical scrolling - Fixed duplicate chat content by skipping turn_complete events - Added comprehensive architecture documentation (4 files) - Added UI bug fixes documentation - Added Notion API upgrade analysis - Created documentation registry for Notion pages 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
This commit is contained in:
Antony Sallas
parent
3059423cd7
commit
5ef6ccf90e
8 changed files with 2603 additions and 1 deletions
354
docs/NOTION_API_UPGRADE_ANALYSIS.md
Normal file
354
docs/NOTION_API_UPGRADE_ANALYSIS.md
Normal file
|
|
@ -0,0 +1,354 @@
|
|||
# Notion API Upgrade Analysis (v2025-09-03)
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Notion released API version `2025-09-03` with **breaking changes** introducing first-class support for multi-source databases. This document analyzes the impact on the llama-stack project documentation system.
|
||||
|
||||
**Current Status:** ✅ No immediate action required
|
||||
**Recommendation:** Monitor announcements, prepare migration plan, stay on v2022-06-28
|
||||
|
||||
---
|
||||
|
||||
## Current Configuration
|
||||
|
||||
### API Version in Use
|
||||
```bash
|
||||
NOTION_VERSION="2022-06-28"
|
||||
NOTION_API_BASE="https://api.notion.com/v1"
|
||||
```
|
||||
|
||||
### Databases
|
||||
- **Llama Stack Database:** `299a94d48e1080f5bf20ef9b61b66daf`
|
||||
- **Documentation Database:** `1fba94d48e1080709d4df69e9c0f0532`
|
||||
- **Troubleshooting Database:** `1fda94d48e10804d843ee491d647b204`
|
||||
|
||||
### Primary Operations
|
||||
- Creating pages in databases (`POST /v1/pages`)
|
||||
- Publishing markdown documentation
|
||||
- Registry tracking
|
||||
|
||||
---
|
||||
|
||||
## Breaking Changes Overview
|
||||
|
||||
### What Changed
|
||||
|
||||
Notion introduced **multi-source databases** - allowing a single database to contain multiple linked data sources. This fundamentally changes how pages are created and queried.
|
||||
|
||||
**Key Concept Change:**
|
||||
```
|
||||
OLD: One database = one data source (implicit)
|
||||
NEW: One database = multiple data sources (explicit)
|
||||
```
|
||||
|
||||
### When Changes Take Effect
|
||||
|
||||
**Immediately** upon upgrading to `2025-09-03`. No grace period or compatibility mode.
|
||||
|
||||
---
|
||||
|
||||
## Detailed Impact Analysis
|
||||
|
||||
### 1. Page Creation (CRITICAL)
|
||||
|
||||
**Current Method (v2022-06-28):**
|
||||
```json
|
||||
{
|
||||
"parent": {
|
||||
"database_id": "299a94d48e1080f5bf20ef9b61b66daf"
|
||||
},
|
||||
"properties": {...},
|
||||
"children": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**New Method (v2025-09-03):**
|
||||
```json
|
||||
{
|
||||
"parent": {
|
||||
"data_source_id": "xxxx-xxxx-xxxx" // Must fetch first!
|
||||
},
|
||||
"properties": {...},
|
||||
"children": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**Migration Required:**
|
||||
1. Fetch data source IDs for each database
|
||||
2. Replace `database_id` with `data_source_id`
|
||||
3. Update all JSON templates
|
||||
4. Update upload scripts
|
||||
|
||||
### 2. Database Queries
|
||||
|
||||
**Current:**
|
||||
```bash
|
||||
POST /v1/databases/{database_id}/query
|
||||
```
|
||||
|
||||
**New:**
|
||||
```bash
|
||||
POST /v1/data_sources/{data_source_id}/query
|
||||
```
|
||||
|
||||
**Impact:** Query scripts need complete rewrite
|
||||
|
||||
### 3. Data Source ID Discovery
|
||||
|
||||
**New Required Step:**
|
||||
```bash
|
||||
# Must call before any operations
|
||||
curl -X GET "https://api.notion.com/v1/databases/299a94d48e1080f5bf20ef9b61b66daf" \
|
||||
-H "Authorization: Bearer $NOTION_BEARER_TOKEN" \
|
||||
-H "Notion-Version: 2025-09-03"
|
||||
|
||||
# Response includes data_sources array
|
||||
{
|
||||
"data_sources": [
|
||||
{"id": "actual-id-to-use-for-operations", ...}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Search API Changes
|
||||
|
||||
**Current:**
|
||||
```json
|
||||
{
|
||||
"filter": {
|
||||
"property": "object",
|
||||
"value": "database"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**New:**
|
||||
```json
|
||||
{
|
||||
"filter": {
|
||||
"property": "object",
|
||||
"value": "data_source" // Changed!
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Webhook Events
|
||||
|
||||
**Event Name Changes:**
|
||||
```
|
||||
database.created → data_source.created
|
||||
database.updated → data_source.updated
|
||||
database.deleted → data_source.deleted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### Low Risk Factors ✅
|
||||
- We control when to upgrade (explicit version in API calls)
|
||||
- Backward compatibility maintained for old versions
|
||||
- Simple migration path (mostly find/replace)
|
||||
- Limited scope (documentation publishing only)
|
||||
|
||||
### Medium Risk Factors ⚠️
|
||||
- **No deprecation timeline announced** - could become urgent without warning
|
||||
- **User-triggered failures** - if database owners add multi-source to our databases
|
||||
- **Multiple databases to migrate** - 3+ databases to update
|
||||
|
||||
### High Risk Factors ❌
|
||||
- None currently identified
|
||||
|
||||
---
|
||||
|
||||
## Migration Requirements
|
||||
|
||||
### Configuration Updates
|
||||
|
||||
**Add to .env:**
|
||||
```bash
|
||||
# Current
|
||||
NOTION_VERSION="2022-06-28"
|
||||
|
||||
# After migration
|
||||
NOTION_VERSION="2025-09-03"
|
||||
|
||||
# New variables needed
|
||||
LLAMA_STACK_DATA_SOURCE_ID="[to-be-fetched]"
|
||||
DOCS_DATA_SOURCE_ID="[to-be-fetched]"
|
||||
TROUBLESHOOTING_DATA_SOURCE_ID="[to-be-fetched]"
|
||||
```
|
||||
|
||||
### Script Updates
|
||||
|
||||
**Files requiring changes:**
|
||||
1. `scripts/upload_notion_with_gpg.sh`
|
||||
2. `docs/knowledge/upload_notion_validated.sh`
|
||||
3. All JSON templates in `docs/knowledge/*-notion.json`
|
||||
|
||||
**Required modifications:**
|
||||
- Add data source ID fetching logic
|
||||
- Replace `database_id` with `data_source_id` in all API calls
|
||||
- Update error handling for new response formats
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
**Files to update:**
|
||||
1. `docs/knowledge/notion-publishing-workflow.md`
|
||||
2. `docs/knowledge/notion-collaboration-guide.md`
|
||||
3. `docs/knowledge/doc_registry.md`
|
||||
4. Project README sections on Notion integration
|
||||
|
||||
---
|
||||
|
||||
## Migration Plan
|
||||
|
||||
### Phase 1: Discovery (When Ready)
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# fetch_data_source_ids.sh
|
||||
|
||||
DATABASES=(
|
||||
"299a94d48e1080f5bf20ef9b61b66daf:LLAMA_STACK"
|
||||
"1fba94d48e1080709d4df69e9c0f0532:DOCS"
|
||||
"1fda94d48e10804d843ee491d647b204:TROUBLESHOOTING"
|
||||
)
|
||||
|
||||
for db_info in "${DATABASES[@]}"; do
|
||||
db_id="${db_info%%:*}"
|
||||
db_name="${db_info##*:}"
|
||||
|
||||
echo "Fetching data source for $db_name..."
|
||||
curl -X GET "https://api.notion.com/v1/databases/$db_id" \
|
||||
-H "Authorization: Bearer $NOTION_BEARER_TOKEN" \
|
||||
-H "Notion-Version: 2025-09-03" | \
|
||||
jq -r ".data_sources[0].id" > "/tmp/${db_name}_data_source_id.txt"
|
||||
done
|
||||
```
|
||||
|
||||
### Phase 2: Update Configuration
|
||||
|
||||
```bash
|
||||
# Update .env with fetched IDs
|
||||
LLAMA_STACK_DATA_SOURCE_ID=$(cat /tmp/LLAMA_STACK_data_source_id.txt)
|
||||
DOCS_DATA_SOURCE_ID=$(cat /tmp/DOCS_data_source_id.txt)
|
||||
TROUBLESHOOTING_DATA_SOURCE_ID=$(cat /tmp/TROUBLESHOOTING_data_source_id.txt)
|
||||
```
|
||||
|
||||
### Phase 3: Update Scripts
|
||||
|
||||
```bash
|
||||
# Find all JSON templates
|
||||
find docs/knowledge -name "*-notion.json" -type f
|
||||
|
||||
# Update database_id to data_source_id
|
||||
sed -i 's/"database_id":/"data_source_id":/g' docs/knowledge/*-notion.json
|
||||
|
||||
# Update shell scripts
|
||||
# (Manual review and update required)
|
||||
```
|
||||
|
||||
### Phase 4: Test & Validate
|
||||
|
||||
1. Create test page in development database
|
||||
2. Verify page creation works
|
||||
3. Test query operations
|
||||
4. Validate search functionality
|
||||
5. Check webhook events (if used)
|
||||
|
||||
### Phase 5: Production Migration
|
||||
|
||||
1. Backup current .env configuration
|
||||
2. Apply all changes
|
||||
3. Test with single document
|
||||
4. Roll out to all operations
|
||||
5. Update documentation
|
||||
|
||||
---
|
||||
|
||||
## Timeline & Recommendations
|
||||
|
||||
### Immediate (Now)
|
||||
✅ Document analysis (this document)
|
||||
✅ Monitor Notion changelog
|
||||
✅ Create migration scripts (not execute)
|
||||
|
||||
### Short Term (3 Months)
|
||||
- Stay on v2022-06-28
|
||||
- No action required
|
||||
- Continue monitoring
|
||||
|
||||
### Medium Term (When Announced)
|
||||
- Execute migration when deprecation announced
|
||||
- Or when multi-source features needed
|
||||
- Or after 6+ months of stability
|
||||
|
||||
### Long Term
|
||||
- Periodic reviews of Notion API changes
|
||||
- Keep migration scripts updated
|
||||
- Document all configuration changes
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
### Stay on v2022-06-28 IF:
|
||||
✅ Current version works without issues
|
||||
✅ No deprecation timeline announced
|
||||
✅ No need for multi-source features
|
||||
✅ Prefer stability over new features
|
||||
|
||||
### Upgrade to v2025-09-03 IF:
|
||||
- Deprecation announced for v2022-06-28
|
||||
- Need multi-source database features
|
||||
- Databases modified by owners (forced upgrade)
|
||||
- 6+ months have passed (stability proven)
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Strategy
|
||||
|
||||
### Quarterly Checks
|
||||
1. Review Notion developer changelog
|
||||
2. Check for deprecation announcements
|
||||
3. Test current integration still works
|
||||
4. Update migration scripts if needed
|
||||
|
||||
### Triggers for Immediate Action
|
||||
🚨 Deprecation notice for v2022-06-28
|
||||
🚨 Database owners add multi-source
|
||||
🚨 Current version shows instability
|
||||
🚨 Critical security fixes in new version
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
### Official Documentation
|
||||
- Upgrade Guide: https://developers.notion.com/docs/upgrade-guide-2025-09-03
|
||||
- API Reference: https://developers.notion.com/reference
|
||||
- Changelog: https://developers.notion.com/changelog
|
||||
|
||||
### Internal Documentation
|
||||
- `docs/knowledge/notion-publishing-workflow.md`
|
||||
- `docs/knowledge/notion-collaboration-guide.md`
|
||||
- `docs/knowledge/doc_registry.md`
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**Current Recommendation:** **Do NOT upgrade yet**
|
||||
|
||||
**Rationale:**
|
||||
- No immediate benefit
|
||||
- No deprecation pressure
|
||||
- Current system stable
|
||||
- Migration effort not justified
|
||||
|
||||
**Next Review:** 3 months from now (or when Notion announces deprecation)
|
||||
|
||||
**Prepared By:** Claude Code
|
||||
**Date:** October 2025
|
||||
**Version:** 1.0
|
||||
Loading…
Add table
Add a link
Reference in a new issue