davebb/linear-coding-agent
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add time/date access for Ikario and Tavily MCP specification

Browse Source 
Major changes:
- Added current date/time to system prompt so Ikario always knows when it is
- Created comprehensive Tavily MCP integration spec (10 features)
- Updated .gitignore to exclude node_modules

Time Access Feature:
- Modified buildSystemPrompt in server/routes/messages.js
- Modified buildSystemPrompt in server/routes/claude.js
- Ikario now receives: date, time, ISO timestamp, timezone
- Added debug logging to verify system prompt

Tavily MCP Spec (app_spec_tavily_mcp.txt):
- Internet access via Tavily search API
- 10 detailed features with implementation steps
- Compatible with existing ikario-memory MCP
- Provides real-time web search and news search

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
David Blanc Brioir
2025-12-22 19:00:51 +01:00
parent 51983a5240
commit 705cd1bfa9
18 changed files with 27257 additions and 5356 deletions
Download Patch File Download Diff File Expand all files Collapse all files

984
prompts/app_spec_extended_thinking.txt
View File

@@ -1,984 +0,0 @@
<project_specification>
<project_name>Extended Thinking - Claude.ai Clone</project_name>
<overview>
Extension du projet "Claude.ai Clone" existant pour intégrer la fonctionnalité Extended Thinking de Claude, permettant au modèle d'exposer son processus de raisonnement étape par étape.
Extended Thinking est une capacité de Claude qui génère des blocs "thinking" contenant son raisonnement interne avant de fournir sa réponse finale. Cette fonctionnalité améliore significativement la qualité des réponses pour les tâches complexes comme :
- Mathématiques et calculs complexes
- Programmation et débogage
- Analyse approfondie de documents
- Raisonnement logique multi-étapes
- Résolution de problèmes complexes
Le projet Claude.ai Clone dispose déjà de :
- Interface de chat complète avec streaming SSE
- Gestion de conversations et messages (base SQLite)
- Intégration Claude API avec Anthropic SDK
- Support des tools (memory tools déjà implémentés)
- Frontend React + Vite + Tailwind
- Backend Node.js + Express
Cette extension ajoute :
- Support du paramètre "thinking" dans les appels Claude API
- Affichage des blocs thinking dans l'interface
- Contrôles utilisateur pour activer/désactiver thinking
- Ajustement du budget thinking (1K-32K tokens)
- Streaming des thinking deltas en temps réel
- Préservation des thinking blocks avec tool use
- Storage des thinking blocks dans la base de données
</overview>
<technology_stack>
<existing_stack>
Le projet dispose déjà de :
- Frontend : React + Vite + Tailwind CSS (port 5173)
- Backend : Node.js + Express + SQLite (port 3001)
- API Claude : Anthropic SDK avec streaming SSE
- Gestion de conversations : base SQLite avec tables conversations et messages
- Tool Use API : Memory tools déjà configurés
</existing_stack>
<extended_thinking_support>
<api_integration>
- Anthropic Messages API avec paramètre "thinking"
- Structure : { type: "enabled", budget_tokens: number }
- Budget min: 1024 tokens, max recommandé: 32000 tokens
- Au-delà de 32K: utiliser batch processing
</api_integration>
<response_format>
- Blocs "thinking" : raisonnement résumé (Claude 4+)
- Blocs "text" : réponse finale
- Blocs "redacted_thinking" : thinking chiffré pour sécurité
- Signature : champ de vérification cryptographique
</response_format>
<streaming_events>
- thinking_start : début du bloc thinking
- thinking_delta : chunk de thinking en temps réel
- thinking_stop : fin du bloc thinking
- content : texte de réponse normale
- signature_delta : signature cryptographique
</streaming_events>
<supported_models>
- Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) ✓
- Claude Sonnet 4 (claude-sonnet-4-20250514) ✓
- Claude Haiku 4.5 (claude-haiku-4-5-20251001) ✓
- Claude Opus 4.5 (claude-opus-4-5-20251101) ✓ + preserved blocks
- Claude Opus 4.1 (claude-opus-4-1-20250805) ✓
- Claude Opus 4 (claude-opus-4-20250514) ✓
- Claude Sonnet 3.7 (déprécié, thinking complet non résumé)
</supported_models>
</extended_thinking_support>
</technology_stack>
<prerequisites>
<existing_project>
- Projet Claude.ai Clone déjà fonctionnel
- Base SQLite avec tables conversations et messages opérationnelles
- API endpoints Claude existants (/api/claude/chat, /api/messages/*)
- Frontend React avec composants de chat déjà en place
- Tool Use API déjà implémenté (memory tools fonctionnels)
</existing_project>
<no_new_dependencies>
- Aucune nouvelle dépendance npm requise
- Utilise Anthropic SDK existant (déjà installé)
- Extended Thinking est une fonctionnalité native de l'API Claude
</no_new_dependencies>
<api_compatibility>
- API key Anthropic valide (déjà configurée)
- Modèles Claude 4+ recommandés pour thinking résumé
- Compatible avec les tools existants (memory, etc.)
</api_compatibility>
</prerequisites>
<core_features>
<feature_1>
<title>Backend - Support paramètre thinking dans API routes</title>
<description>
Modifier les routes backend pour accepter et transmettre le paramètre "thinking" à l'API Claude.
Fonctionnalités :
- Ajouter paramètres enableThinking et thinkingBudgetTokens aux requêtes
- Modifier server/routes/claude.js pour POST /api/claude/chat
- Modifier server/routes/messages.js pour POST /:conversationId/messages
- Construire l'objet thinking: { type: "enabled", budget_tokens: number }
- Passer thinking dans les appels anthropic.messages.create()
- Validation : budget_tokens entre 1024 et 200000
- Default : enableThinking=false, thinkingBudgetTokens=10000
Technique :
- Extraction des params depuis req.body ou conversation.settings
- Conditional : if (enableThinking) { apiParams.thinking = {...} }
- Merge avec params existants (model, max_tokens, tools, system)
- Pas de breaking changes pour les conversations existantes
Intégration :
- Modification de server/routes/claude.js (lignes ~92-146)
- Modification de server/routes/messages.js (lignes ~314-365)
- Compatible avec tool use existant (memory tools)
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Modifier les routes pour accepter enableThinking et thinkingBudgetTokens
2. Créer une conversation test avec thinking activé
3. Vérifier dans les logs que thinking est passé à l'API
4. Envoyer un message et vérifier la présence de thinking_delta events
5. Tester avec enableThinking=false et vérifier pas de thinking
6. Tester avec budget 1024, 10000, 32000 et vérifier comportement
7. Vérifier compatibilité avec memory tools (tool use + thinking)
</test_steps>
</feature_1>
<feature_2>
<title>Backend - Streaming des thinking deltas via SSE</title>
<description>
Implémenter la gestion des événements thinking dans le streaming SSE pour envoyer les thinking deltas au frontend en temps réel.
Fonctionnalités :
- Détecter event.type === 'content_block_start' avec type 'thinking'
- Émettre événement SSE thinking_start avec index du bloc
- Détecter event.type === 'content_block_delta' avec delta.type === 'thinking_delta'
- Émettre événement SSE thinking avec le texte delta
- Accumuler le thinking complet dans fullThinkingContent
- Détecter signature_delta et accumuler dans thinkingSignature
- Émettre thinking_stop à la fin du bloc
- Gérer redacted_thinking blocks (thinking chiffré)
Événements SSE émis :
- { type: 'thinking_start', index: number }
- { type: 'thinking', text: string } (streaming)
- { type: 'thinking_stop', index: number }
- { type: 'thinking_redacted', message: string } (si redacted)
Technique :
- Dans la boucle for await (const event of stream) de messages.js
- Variables : fullThinkingContent = '', thinkingSignature = ''
- res.write() pour chaque événement SSE
- isInThinkingBlock flag pour tracking état
Intégration :
- Modification de server/routes/messages.js (dans POST /:conversationId/messages)
- S'intègre dans la boucle de streaming existante (lignes ~365-400)
- Compatible avec tool_use events existants
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Activer thinking pour une conversation
2. Envoyer un message et observer les logs backend
3. Vérifier émission de thinking_start event
4. Vérifier émission de multiples thinking events (deltas)
5. Vérifier accumulation de fullThinkingContent
6. Vérifier émission de thinking_stop
7. Vérifier gestion de signature_delta
8. Tester avec prompt qui trigger redacted_thinking
</test_steps>
</feature_2>
<feature_3>
<title>Backend - Storage thinking dans base de données</title>
<description>
Ajouter les colonnes nécessaires à la table messages pour stocker les thinking blocks et permettre leur affichage après refresh.
Fonctionnalités :
- Migration DB : ajouter colonnes thinking_content et thinking_signature à table messages
- Sauvegarder fullThinkingContent dans thinking_content
- Sauvegarder thinkingSignature dans thinking_signature (pour vérification)
- Charger thinking_content lors de GET /api/conversations/:id/messages
- Inclure thinking dans la réponse JSON des messages
- Nullable : thinking_content peut être NULL si thinking désactivé
Schéma DB :
- ALTER TABLE messages ADD COLUMN thinking_content TEXT DEFAULT NULL
- ALTER TABLE messages ADD COLUMN thinking_signature TEXT DEFAULT NULL
Technique :
- Modification de server/db/index.js pour migration
- Vérifier existence colonnes avec pragma_table_info
- INSERT thinking_content et thinking_signature avec le message
- SELECT thinking_content dans les queries existantes
- Retourner dans response JSON : { ...message, thinking_content, thinking_signature }
Intégration :
- Modification de server/db/index.js (fonction initializeDatabase)
- Modification de INSERT dans server/routes/messages.js
- Modification de SELECT dans GET /api/conversations/:id/messages
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Lancer le serveur et vérifier migration DB dans logs
2. Vérifier colonnes ajoutées : PRAGMA table_info(messages)
3. Envoyer message avec thinking et vérifier INSERT
4. Vérifier thinking_content contient le texte thinking
5. Vérifier thinking_signature contient la signature
6. Refresh la page et vérifier thinking réapparaît
7. Tester message sans thinking et vérifier NULL
</test_steps>
</feature_3>
<feature_4>
<title>Backend - Settings DB pour thinking par conversation</title>
<description>
Ajouter les colonnes à la table conversations pour stocker les préférences thinking de chaque conversation.
Fonctionnalités :
- Migration DB : ajouter enable_thinking et thinking_budget_tokens à conversations
- Defaults : enable_thinking=0 (désactivé), thinking_budget_tokens=10000
- Charger settings depuis conversations.enable_thinking
- Utiliser dans la construction des appels API
- Permettre modification via endpoint PATCH /api/conversations/:id/settings
Schéma DB :
- ALTER TABLE conversations ADD COLUMN enable_thinking INTEGER DEFAULT 0
- ALTER TABLE conversations ADD COLUMN thinking_budget_tokens INTEGER DEFAULT 10000
Technique :
- Migration dans server/db/index.js
- Lecture dans POST /:conversationId/messages : const enableThinking = conversation.enable_thinking === 1
- Update via PATCH /api/conversations/:id : UPDATE conversations SET enable_thinking=?, thinking_budget_tokens=?
Intégration :
- Modification de server/db/index.js (migration)
- Modification de server/routes/messages.js (lecture settings)
- Nouveau endpoint ou modification endpoint conversations pour update
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Vérifier migration et création colonnes
2. Créer nouvelle conversation et vérifier defaults (0, 10000)
3. Activer thinking via PATCH et vérifier UPDATE
4. Envoyer message et vérifier thinking utilisé
5. Désactiver thinking et vérifier pas de thinking blocks
6. Modifier budget à 20000 et vérifier pris en compte
7. Vérifier persistance après redémarrage serveur
</test_steps>
</feature_4>
<feature_5>
<title>Frontend - Composant ThinkingBlock pour affichage</title>
<description>
Créer un composant React ThinkingBlock pour afficher les blocs thinking de façon élégante et collapsible.
Fonctionnalités :
- Composant React standalone : src/components/ThinkingBlock.jsx
- Props : thinking (string), signature (string), isStreaming (boolean)
- Header avec icône cerveau + titre "Claude's reasoning"
- Toggle expand/collapse (useState)
- Animation dots pendant streaming
- Contenu en police monospace pour meilleure lisibilité
- Background bleu clair (bg-blue-50 dark:bg-blue-950)
- Border bleu (border-blue-200 dark:border-blue-800)
- Affichage token count estimé (~length/4)
- Note "Summarized for display" pour Claude 4+
UI States :
- isStreaming=true : afficher "Thinking..." + dots animés
- isStreaming=false : afficher "Claude's reasoning"
- isExpanded=true : montrer contenu complet
- isExpanded=false : header seul avec chevron
Technique :
- Functional component avec hooks (useState)
- Tailwind CSS pour styling
- SVG icons (brain icon, chevron)
- Animation CSS pour dots (animate-bounce avec delay)
- Transition pour collapse (max-height ou conditional render)
Intégration :
- Nouveau fichier src/components/ThinkingBlock.jsx
- Importé dans src/App.jsx
- Utilisé dans le composant Message
</description>
<priority>2</priority>
<category>frontend</category>
<test_steps>
1. Créer le composant ThinkingBlock.jsx
2. Tester affichage avec thinking statique
3. Vérifier toggle expand/collapse fonctionne
4. Tester avec isStreaming=true et voir animation
5. Vérifier responsive design (mobile)
6. Vérifier dark mode (bg et border colors)
7. Vérifier token count affiché correctement
8. Vérifier note "Summarized" présente
</test_steps>
</feature_5>
<feature_6>
<title>Frontend - Intégration ThinkingBlock dans messages</title>
<description>
Intégrer le composant ThinkingBlock dans l'affichage des messages pour montrer le thinking avant le contenu.
Fonctionnalités :
- Ajouter state thinkingContent dans Message component
- Afficher ThinkingBlock si thinkingContent existe
- Position : avant le contenu du message
- Charger thinking depuis message.thinking_content (DB)
- Update en temps réel pendant streaming
- Flag isThinkingStreaming pour animation
Structure :
```jsx
<div className="message">
{thinkingContent && (
<ThinkingBlock
thinking={thinkingContent}
signature={message.thinking_signature}
isStreaming={isThinkingStreaming}
/>
)}
<div className="message-content">
{message.content}
</div>
</div>
```
Technique :
- useState pour thinkingContent et isThinkingStreaming
- Initialiser depuis message.thinking_content au mount
- Update pendant streaming via SSE events
- Conditional render avec && operator
Intégration :
- Modification de src/App.jsx (Message component)
- Import ThinkingBlock component
- Pas de breaking changes pour messages sans thinking
</description>
<priority>2</priority>
<category>frontend</category>
<test_steps>
1. Afficher conversation avec thinking blocks
2. Vérifier ThinkingBlock apparaît avant le contenu
3. Vérifier thinking chargé depuis DB au refresh
4. Envoyer nouveau message et vérifier streaming
5. Vérifier isThinkingStreaming = true pendant streaming
6. Vérifier isThinkingStreaming = false après
7. Vérifier messages sans thinking non affectés
8. Tester scroll avec thinking blocks longs
</test_steps>
</feature_6>
<feature_7>
<title>Frontend - Settings Panel pour thinking toggle</title>
<description>
Ajouter contrôles dans le panneau de settings de conversation pour activer/désactiver Extended Thinking.
Fonctionnalités :
- Toggle checkbox "Extended Thinking"
- Description : "Enable enhanced reasoning for complex tasks"
- Icône cerveau à côté du label
- State local synchronisé avec conversation.enable_thinking
- Update via PATCH /api/conversations/:id au changement
- Affichage conditionnel du thinking budget slider si activé
UI :
- Section dans conversation settings (à côté temperature, max_tokens)
- Checkbox custom avec style Tailwind
- Label clickable avec flex layout
- Description en text-xs text-gray-500
Technique :
- Modification du composant ConversationSettings (ou équivalent)
- useState pour enable_thinking (init depuis conversation)
- onChange handler avec PATCH request
- Conditional render pour budget slider
Intégration :
- Modification de src/App.jsx (settings panel)
- PATCH /api/conversations/:id endpoint (backend)
- Reload conversation après update
</description>
<priority>2</priority>
<category>frontend</category>
<test_steps>
1. Ouvrir settings d'une conversation
2. Voir la checkbox "Extended Thinking"
3. Cocher la checkbox et vérifier PATCH request
4. Vérifier conversation.enable_thinking = 1 en DB
5. Envoyer message et vérifier thinking apparaît
6. Décocher et vérifier plus de thinking
7. Vérifier persistance après refresh
8. Vérifier icône cerveau affichée
</test_steps>
</feature_7>
<feature_8>
<title>Frontend - Thinking Budget Slider</title>
<description>
Ajouter un slider pour ajuster le budget thinking (nombre de tokens alloués au raisonnement).
Fonctionnalités :
- Range input de 1024 à 32000 tokens
- Step de 1024 tokens pour granularité
- Labels : "1K tokens" (min), "32K tokens" (max), valeur actuelle au centre
- Visible uniquement si Extended Thinking activé
- Description : "Higher budgets enable more thorough analysis"
- Update en temps réel de conversation.thinking_budget_tokens
- Warning si >32K (recommander batch processing)
UI :
- Input type="range" stylisé avec Tailwind
- Display de la valeur en temps réel (formatée avec .toLocaleString())
- Labels aux extrémités
- Spacing cohérent avec autres settings
Technique :
- Conditional render : {settings.enableThinking && <div>slider</div>}
- Value controlled par state
- onChange avec debounce (300ms) pour éviter trop de PATCH
- Min=1024, max=32000, step=1024
Intégration :
- Dans le même settings panel que le toggle
- Juste en dessous de la checkbox Extended Thinking
- Update via même endpoint PATCH
</description>
<priority>2</priority>
<category>frontend</category>
<test_steps>
1. Activer Extended Thinking
2. Voir le slider apparaître
3. Ajuster à 5000 tokens et vérifier update
4. Vérifier valeur affichée change en temps réel
5. Vérifier PATCH request avec debounce
6. Envoyer message et vérifier budget utilisé
7. Tester min (1024) et max (32000)
8. Désactiver thinking et vérifier slider disparaît
</test_steps>
</feature_8>
<feature_9>
<title>Frontend - Badge "Thinking" dans conversation list</title>
<description>
Afficher un badge visuel dans la liste de conversations pour indiquer que Extended Thinking est activé.
Fonctionnalités :
- Badge avec icône cerveau + texte "Thinking"
- Couleur : bg-blue-100 text-blue-700 (light) / bg-blue-900 text-blue-200 (dark)
- Taille : text-xs, padding minimal
- Position : à droite du titre de conversation
- Visible seulement si enable_thinking = 1
- Style pill/rounded-full
UI :
- Inline badge avec flexbox
- Icon + text dans le même span
- Cohérent avec autres badges (pinned, etc.)
Technique :
- Dans ConversationListItem component
- Parse conversation.enable_thinking || JSON.parse(conversation.settings)?.enableThinking
- Conditional render : {enableThinking && <span>badge</span>}
- SVG brain icon (w-3 h-3)
Intégration :
- Modification du composant ConversationListItem
- Ajout après conversation.title
- Pas de breaking changes
</description>
<priority>3</priority>
<category>frontend</category>
<test_steps>
1. Créer conversation avec thinking activé
2. Voir badge "Thinking" dans la liste
3. Vérifier icône cerveau présente
4. Vérifier couleurs en light et dark mode
5. Créer conversation sans thinking
6. Vérifier absence de badge
7. Activer thinking et vérifier badge apparaît
8. Vérifier responsive (mobile)
</test_steps>
</feature_8>
<feature_10>
<title>Frontend - Streaming handler pour thinking deltas</title>
<description>
Implémenter la logique frontend pour recevoir et afficher les thinking deltas en streaming via SSE.
Fonctionnalités :
- Écouter événement SSE 'thinking_start'
- Set isThinkingStreaming = true
- Écouter 'thinking' events et accumuler dans currentThinking
- Update thinkingContent en temps réel
- Écouter 'thinking_stop' et set isThinkingStreaming = false
- Gérer 'thinking_redacted' avec message d'info
- Buffer thinking complet pour sauvegarde finale
Event handling :
```javascript
case 'thinking_start':
setIsThinkingStreaming(true);
currentThinking = '';
break;
case 'thinking':
currentThinking += data.text;
setThinkingContent(currentThinking);
break;
case 'thinking_stop':
setIsThinkingStreaming(false);
break;
```
Technique :
- Dans la fonction sendMessage() (ou équivalent)
- EventSource ou fetch streaming déjà existant
- Switch sur data.type pour router events
- State updates via setters
- Cleanup des listeners à la fin
Intégration :
- Modification de src/App.jsx (sendMessage function)
- S'intègre dans le handler SSE existant
- Compatible avec tool_use events
</description>
<priority>1</priority>
<category>frontend</category>
<test_steps>
1. Activer thinking pour conversation
2. Envoyer message et observer console
3. Vérifier thinking_start event reçu
4. Vérifier thinking deltas reçus et accumulés
5. Vérifier ThinkingBlock update en temps réel
6. Vérifier thinking_stop event
7. Vérifier isThinkingStreaming toggle correct
8. Tester avec redacted_thinking
</test_steps>
</feature_10>
<feature_11>
<title>Backend - Préservation thinking blocks avec tool use</title>
<description>
Implémenter la logique pour préserver les thinking blocks lors de l'utilisation de tools, conformément à la spec Claude API.
Fonctionnalités :
- Quand stop_reason === 'tool_use', extraire thinking blocks
- Extraire tool_use blocks
- Passer thinking + tool_use dans messages assistant
- Exécuter tools (processToolCalls déjà existant)
- Retourner tool_results
- Continuer conversation avec thinking préservé
- Support de interleaved thinking (beta header optionnel)
Workflow :
1. Response avec stop_reason='tool_use'
2. Filtrer content : thinking + redacted_thinking blocks
3. Filtrer content : tool_use blocks
4. Push assistant message avec [...thinkingBlocks, ...toolUseBlocks]
5. Execute tools via processToolCalls()
6. Push user message avec tool_results
7. Nouvelle iteration avec thinking préservé
Technique :
- Dans la boucle tool use existante (messages.js)
- Filter blocks par type : 'thinking', 'redacted_thinking', 'tool_use'
- Merge dans content array
- Preserve order : thinking d'abord, puis tools
- Compatible avec code tool use existant
Intégration :
- Modification de server/routes/messages.js (tool use loop)
- Compatible avec memory tools existants
- Pas de breaking changes
</description>
<priority>2</priority>
<category>backend</category>
<test_steps>
1. Activer thinking + memory tools
2. Demander "Recherche dans tes souvenirs sur X"
3. Vérifier Claude utilise thinking + tool search_memories
4. Vérifier thinking blocks préservés dans messages array
5. Vérifier tool results retournés correctement
6. Vérifier Claude continue avec contexte thinking
7. Tester avec multiple tool calls
8. Vérifier logs montrent preservation
</test_steps>
</feature_11>
<feature_12>
<title>Backend - Token tracking pour thinking</title>
<description>
Améliorer le tracking des tokens pour distinguer thinking tokens des output tokens normaux.
Fonctionnalités :
- Calculer thinking tokens approximatif (length / 4)
- Logger séparément input_tokens, output_tokens, thinking_tokens
- Sauvegarder dans usage_tracking (optionnel : nouvelle colonne)
- Inclure thinking_tokens dans response 'done' event
- Documentation du fait que thinking est facturé au tarif complet
Logging :
```javascript
console.log('[Thinking Tokens]', {
input_tokens: response.usage.input_tokens,
output_tokens: response.usage.output_tokens, // Inclut thinking complet
visible_thinking_tokens: Math.ceil(thinkingContent.length / 4),
text_output_tokens: Math.ceil(textContent.length / 4)
});
```
Technique :
- Fonction calculateTokens(text) : Math.ceil(text.length / 4)
- Logging après chaque response
- Inclure dans event 'done' : thinkingTokens: calculateTokens(fullThinkingContent)
- Optionnel : ALTER TABLE usage_tracking ADD COLUMN thinking_tokens
Intégration :
- Modification de server/routes/messages.js
- Modification de usage_tracking INSERT (optionnel)
- Frontend peut afficher thinking cost
</description>
<priority>3</priority>
<category>backend</category>
<test_steps>
1. Envoyer message avec thinking
2. Vérifier logs backend montrent breakdown tokens
3. Vérifier thinking_tokens dans event 'done'
4. Vérifier total = input + output + thinking
5. Comparer visible thinking tokens vs billed
6. Tester avec différents budgets
7. Vérifier tracking en DB (si colonne ajoutée)
</test_steps>
</feature_12>
<feature_13>
<title>Frontend - Usage stats avec thinking tokens</title>
<description>
Afficher les statistiques d'utilisation incluant les thinking tokens dans l'interface.
Fonctionnalités :
- Section usage stats dans conversation details
- Afficher Total Tokens (existant)
- Afficher Thinking Tokens séparément (en bleu)
- Note explicative : "Thinking tokens are summarized but billed at full rate"
- Graph ou visual si >0 thinking tokens
- Format avec .toLocaleString() pour lisibilité
UI :
```jsx
<div className="usage-stats">
<div className="stat">
<label>Total Tokens</label>
<span>{conversation.token_count.toLocaleString()}</span>
</div>
{conversation.thinking_tokens > 0 && (
<div className="stat text-blue-600">
<label>Thinking Tokens</label>
<span>{conversation.thinking_tokens.toLocaleString()}</span>
</div>
)}
</div>
```
Technique :
- Composant UsageStats (nouveau ou modification existant)
- Props : conversation avec token_count et thinking_tokens
- Conditional render si thinking_tokens > 0
- Tailwind classes pour styling
Intégration :
- Dans conversation details panel ou settings
- Charger data depuis conversation ou API
- Update après chaque message
</description>
<priority>3</priority>
<category>frontend</category>
<test_steps>
1. Avoir conversation avec thinking
2. Ouvrir usage stats
3. Voir Total Tokens et Thinking Tokens
4. Vérifier Thinking Tokens en bleu
5. Voir note explicative
6. Envoyer nouveau message et voir update
7. Tester avec conversation sans thinking
8. Vérifier Thinking Tokens section cachée
</test_steps>
</feature_13>
<feature_14>
<title>Frontend - Error handling pour thinking timeout</title>
<description>
Gérer gracieusement les cas où le thinking prend trop de temps (>2 minutes) avec timeout et message utilisateur.
Fonctionnalités :
- Timeout de 2 minutes (120000ms) pour thinking
- Afficher message : "Thinking is taking longer than expected..."
- Ne pas bloquer l'affichage de la réponse finale
- Logger warning en console
- Permettre annulation (optionnel)
Backend :
- setTimeout pour 120s après thinking_start
- Émettre event 'thinking_timeout' si pas de thinking_stop
- Clear timeout si thinking_stop avant
Frontend :
- Écouter 'thinking_timeout' event
- Afficher notification ou message dans ThinkingBlock
- Continuer à écouter pour eventual thinking_stop
Technique :
- Backend : let thinkingTimeout = setTimeout(() => {...}, 120000)
- Backend : clearTimeout(thinkingTimeout) dans thinking_stop
- Frontend : toast notification ou inline message
- Pas de crash, juste warning
Intégration :
- Modification de server/routes/messages.js
- Modification de src/App.jsx (event handler)
- UX: message discret, pas d'alerte invasive
</description>
<priority>3</priority>
<category>fullstack</category>
<test_steps>
1. Créer prompt qui génère >2min de thinking (difficile)
2. Vérifier timeout warning après 2min
3. Vérifier message affiché à l'utilisateur
4. Vérifier thinking_stop clear le timeout
5. Vérifier pas de crash si timeout
6. Vérifier réponse finale affichée malgré timeout
7. Vérifier logs backend
</test_steps>
</feature_14>
<feature_15>
<title>Documentation - Guide utilisateur Extended Thinking</title>
<description>
Créer documentation inline ou modal pour expliquer Extended Thinking aux utilisateurs.
Fonctionnalités :
- Bouton "?" ou "info" à côté du toggle Extended Thinking
- Modal/popover explicatif au clic
- Sections :
* Qu'est-ce que Extended Thinking ?
* Quand l'utiliser ? (math, code, analysis)
* Quand NE PAS l'utiliser ? (questions simples)
* Impact sur temps de réponse (2-5x plus long)
* Budget thinking : qu'est-ce que c'est ?
* Facturation (thinking facturé au tarif complet)
- Exemples concrets d'utilisation
- Lien vers docs Anthropic (optionnel)
UI :
- Icône info circulaire (i dans cercle)
- Modal Headless UI ou simple div
- Prose styling pour lisibilité
- Bouton "Got it" pour fermer
Technique :
- Composant InfoModal ou réutilisation existant
- Markdown content ou JSX statique
- State pour open/close modal
- onClick sur icône info
Intégration :
- À côté du toggle Extended Thinking dans settings
- Peut aussi dans un "Help" menu global
- Traduction FR/EN si multilingue
</description>
<priority>4</priority>
<category>frontend</category>
<test_steps>
1. Voir icône info à côté de Extended Thinking
2. Cliquer et voir modal s'ouvrir
3. Lire contenu explicatif
4. Vérifier exemples clairs
5. Cliquer "Got it" et fermer
6. Vérifier responsive design
7. Vérifier accessibility (keyboard nav)
</test_steps>
</feature_15>
</core_features>
<ui_design>
<integration_notes>
Cette extension s'intègre dans le design existant du clone Claude.ai.
Tous les nouveaux composants doivent respecter le design system existant.
</integration_notes>
<new_components>
- ThinkingBlock : Bloc collapsible pour afficher le thinking (bleu clair)
- Thinking Toggle : Checkbox dans settings pour activer/désactiver
- Budget Slider : Range input pour ajuster budget thinking
- Thinking Badge : Petit badge dans conversation list
- Usage Stats : Section pour afficher thinking tokens
- Info Modal : Documentation Extended Thinking
</new_components>
<color_scheme>
Utiliser les couleurs existantes du clone Claude.ai, avec ajouts pour thinking :
- Thinking blocks : bg-blue-50 text-blue-800 (light) / bg-blue-950 text-blue-200 (dark)
- Borders : border-blue-200 (light) / border-blue-800 (dark)
- Badge thinking : bg-blue-100 text-blue-700 (light) / bg-blue-900 text-blue-200 (dark)
- Icons : text-blue-600 (light) / text-blue-400 (dark)
- Accent : conserver #CC785C (orange claude.ai) pour cohérence
</color_scheme>
<icons>
- Icône cerveau (brain) pour thinking : SVG custom ou Lucide React
- Chevron pour collapse/expand
- Info icon (i dans cercle) pour documentation
- Dots animés pour streaming (3 cercles avec animate-bounce)
</icons>
<animations>
- Dots streaming : animate-bounce avec animation-delay
- Collapse/expand : transition max-height ou opacity
- Pulse discret lors sauvegarde (optionnel)
- Smooth transitions (duration-200)
</animations>
<responsive>
- Thinking blocks full width sur mobile
- Settings panel stacké verticalement sur mobile
- Badge thinking masqué sur très petits écrans (optionnel)
- Touch targets >44px pour mobile
</responsive>
</ui_design>
<api_endpoints>
<note>
Modifications aux endpoints existants. Pas de nouveaux endpoints nécessaires.
</note>
<existing_endpoints_modified>
<endpoint>
<method>POST</method>
<path>/api/claude/chat</path>
<modification>
- Accepter enableThinking et thinkingBudgetTokens dans req.body
- Construire thinking: { type: "enabled", budget_tokens: number }
- Passer dans anthropic.messages.create()
</modification>
</endpoint>
<endpoint>
<method>POST</method>
<path>/api/conversations/:conversationId/messages</path>
<modification>
- Charger enable_thinking et thinking_budget_tokens depuis conversation
- Ajouter thinking dans requête API si activé
- Émettre thinking_start, thinking, thinking_stop via SSE
- Sauvegarder thinking_content et thinking_signature en DB
</modification>
</endpoint>
<endpoint>
<method>POST</method>
<path>/api/messages/:id/regenerate</path>
<modification>
- Même logique que POST messages
- Charger thinking settings depuis conversation
- Support thinking dans regeneration
</modification>
</endpoint>
<endpoint>
<method>PATCH</method>
<path>/api/conversations/:id</path>
<modification>
- Accepter enable_thinking et thinking_budget_tokens
- UPDATE conversations SET enable_thinking=?, thinking_budget_tokens=?
- Validation budget entre 1024 et 200000
</modification>
</endpoint>
<endpoint>
<method>GET</method>
<path>/api/conversations/:id/messages</path>
<modification>
- SELECT thinking_content, thinking_signature avec messages
- Retourner dans response JSON
</modification>
</endpoint>
</existing_endpoints_modified>
</api_endpoints>
<database_schema>
<sqlite_modifications>
Modifications à la base SQLite existante :
<table>
<name>conversations (table existante - ajouter colonnes)</name>
<new_columns>
<column>enable_thinking INTEGER DEFAULT 0</column>
<column>thinking_budget_tokens INTEGER DEFAULT 10000</column>
</new_columns>
<description>
- enable_thinking : 0 = désactivé, 1 = activé
- thinking_budget_tokens : nombre de tokens alloués (1024-200000)
</description>
</table>
<table>
<name>messages (table existante - ajouter colonnes)</name>
<new_columns>
<column>thinking_content TEXT DEFAULT NULL</column>
<column>thinking_signature TEXT DEFAULT NULL</column>
</new_columns>
<description>
- thinking_content : texte thinking résumé (NULL si pas de thinking)
- thinking_signature : signature cryptographique pour vérification
</description>
</table>
<table>
<name>usage_tracking (table existante - optionnel)</name>
<new_columns>
<column>thinking_tokens INTEGER DEFAULT 0</column>
</new_columns>
<description>
- thinking_tokens : nombre approximatif de tokens thinking (pour stats)
- Optionnel : peut être calculé à la volée depuis message.thinking_content
</description>
</table>
</sqlite_modifications>
<migration>
Migration automatique au démarrage dans server/db/index.js :
1. Vérifier existence colonnes avec pragma_table_info
2. Si absentes, ALTER TABLE pour ajouter
3. Logger migration success
4. Pas de data loss, defaults appliqués
</migration>
</database_schema>
<deployment>
<development>
Le projet Claude.ai Clone est déjà configuré.
Extended Thinking ne nécessite aucune dépendance externe supplémentaire.
</development>
<no_new_dependencies>
- Utilise Anthropic SDK existant (@anthropic-ai/sdk)
- Aucun package npm additionnel requis
- Extended Thinking est natif à l'API Claude
</no_new_dependencies>
<backward_compatibility>
- Toutes les conversations existantes continuent de fonctionner
- enable_thinking DEFAULT 0 : thinking désactivé par défaut
- thinking_content NULL pour anciens messages
- Pas de breaking changes
</backward_compatibility>
<environment_variables>
Aucune nouvelle variable d'environnement requise.
Utilise ANTHROPIC_API_KEY existant.
</environment_variables>
<performance_considerations>
- Extended Thinking augmente temps de réponse (2-5x)
- Budgets >32K : considérer batch processing
- Thinking blocks augmentent taille messages DB (TEXT column)
- Streaming thinking : bande passante SSE accrue
- Recommander thinking seulement pour tâches complexes
</performance_considerations>
</deployment>
</project_specification>

663
prompts/app_spec_ikario_memory.txt
View File

@@ -1,663 +0,0 @@
<project_specification>
<project_name>Extension MCP Ikario Memory - Claude.ai Clone</project_name>
<overview>
Extension du projet "Claude.ai Clone" existant pour intégrer la mémoire conversationnelle via le protocole MCP (Model Context Protocol) avec le serveur Ikario RAG.
Cette extension ajoute au clone Claude.ai existant la capacité pour le LLM de :
- Sauvegarder automatiquement les conversations importantes dans une mémoire vectorielle (ChromaDB)
- Rechercher sémantiquement dans ses souvenirs passés pour enrichir les réponses
- Tracer l'évolution de concepts discutés au fil du temps
- Vérifier la cohérence de nouvelles affirmations avec l'historique des conversations
Le projet Claude.ai Clone dispose déjà de :
- Interface de chat complète avec streaming SSE
- Gestion de conversations et messages (base SQLite)
- Intégration Claude API avec Anthropic SDK
- Frontend React + Vite + Tailwind
- Backend Node.js + Express
Cette extension ajoute simplement l'intégration du client MCP Ikario RAG pour donner une mémoire sémantique au LLM.
</overview>
<technology_stack>
<existing_stack>
Le projet dispose déjà de :
- Frontend : React + Vite + Tailwind CSS (port 4300)
- Backend : Node.js + Express + SQLite (port 4301)
- API Claude : Anthropic SDK avec streaming SSE
- Gestion de conversations : base SQLite avec tables conversations et messages
</existing_stack>
<new_integration>
<mcp_client>
- Package : @modelcontextprotocol/sdk (client MCP Node.js)
- Serveur MCP : ikario_rag/server.py (Python)
- Communication : stdio (stdin/stdout avec JSON-RPC 2.0)
- Localisation : chemin configuré dans .env (MCP_IKARIO_SERVER_PATH)
</mcp_client>
<mcp_tools>
Les 4 outils MCP Ikario disponibles :
1. search_memories : Recherche sémantique dans les souvenirs
2. add_thought : Sauvegarde une pensée/conversation avec métadonnées
3. trace_concept_evolution : Trace l'évolution temporelle d'un concept
4. check_consistency : Vérifie la cohérence d'une affirmation avec l'historique
</mcp_tools>
<memory_database>
- Base vectorielle : ChromaDB (gérée par serveur MCP)
- Embeddings : SentenceTransformer all-MiniLM-L6-v2 (384 dimensions)
- Stockage : ./ikario_rag/index/ (persistance sur disque)
- Métadonnées : category, tags, emotions, concepts, date
</memory_database>
</new_integration>
</technology_stack>
<prerequisites>
<existing_project>
- Projet Claude.ai Clone déjà fonctionnel
- Base SQLite avec tables conversations et messages opérationnelles
- API endpoints Claude existants (/api/claude/chat, /api/conversations/*)
- Frontend React avec composants de chat déjà en place
</existing_project>
<mcp_server_setup>
- Serveur MCP Ikario RAG installé dans ./ikario_rag/
- Python 3.11+ avec dépendances : chromadb, sentence-transformers, mcp
- Serveur testé et fonctionnel (peut être lancé manuellement via python server.py)
- Base ChromaDB initialisée dans ./ikario_rag/index/
</mcp_server_setup>
<backend_dependencies>
- Installer @modelcontextprotocol/sdk dans le backend
- Ajouter variables d'environnement au .env :
* MCP_IKARIO_SERVER_PATH=path/to/ikario_rag/server.py
* MCP_MEMORY_ENABLED=true (pour activer/désactiver la fonctionnalité)
</backend_dependencies>
</prerequisites>
<core_features>
<feature_1>
<title>Module backend de connexion MCP Ikario</title>
<description>
Créer un module backend qui initialise et gère la connexion au serveur MCP Ikario RAG.
Fonctionnalités :
- Module server/services/mcpClient.js qui encapsule le client MCP
- Initialisation au démarrage du serveur Express
- Lecture de la configuration depuis .env (MCP_IKARIO_SERVER_PATH)
- Gestion du cycle de vie de la connexion (connect, disconnect, reconnect)
- Pool de connexions ou singleton pour éviter les multiples connexions
- Gestion des erreurs et timeout
- Logging détaillé des appels MCP
Technique :
- Import de @modelcontextprotocol/sdk
- StdioServerParameters avec command="python" et args=[server_path]
- stdio_client() pour créer la connexion
- ClientSession pour gérer les appels
- Export de fonctions : initMCP(), getMCPClient(), closeMCP()
- Initialiser dans server/index.js au démarrage
Intégration :
- S'intègre dans server/index.js existant
- Nouveau fichier server/services/mcpClient.js
- Pas de modification de la base SQLite
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Configurer MCP_IKARIO_SERVER_PATH dans .env
2. Démarrer le serveur backend
3. Vérifier les logs : "MCP Ikario client connected"
4. Vérifier qu'aucune erreur n'est levée
5. Arrêter le serveur et vérifier la déconnexion propre
6. Tester avec un mauvais chemin et vérifier la gestion d'erreur
</test_steps>
</feature_1>
<feature_2>
<title>Service wrapper pour les 4 outils MCP</title>
<description>
Créer un service backend qui expose les 4 outils MCP Ikario sous forme de fonctions JavaScript utilisables dans l'application.
Fonctionnalités :
- Module server/services/memoryService.js
- 4 fonctions async qui wrappent les appels MCP :
* searchMemories(query, n_results, filter_category)
* addThought(content, context)
* traceConceptEvolution(concept, limit)
* checkConsistency(statement)
- Gestion des erreurs spécifiques à chaque outil
- Parsing et formatage des réponses MCP
- Validation des paramètres avant appel
- Logging des appels et résultats
Technique :
- Import de mcpClient.getMCPClient()
- Appels via client.call_tool(tool_name, arguments)
- Parsing des réponses (format TextContent)
- Conversion en objets JavaScript utilisables
- Export des 4 fonctions
Intégration :
- Nouveau fichier server/services/memoryService.js
- Utilisé par les routes API
- Pas de modification de l'existant
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Créer un script de test qui importe memoryService
2. Tester searchMemories("test", 5) et vérifier le retour
3. Tester addThought() avec un contenu simple
4. Vérifier que les erreurs sont bien catchées
5. Vérifier les logs des appels MCP
6. Tester avec MCP désactivé et vérifier le fallback
</test_steps>
</feature_2>
<feature_3>
<title>Routes API pour les outils MCP</title>
<description>
Créer les routes Express qui exposent les 4 outils MCP via l'API REST existante.
Fonctionnalités :
- Nouveau routeur server/routes/memory.js
- 4 routes POST :
* /api/memory/search (search_memories)
* /api/memory/add (add_thought)
* /api/memory/evolution (trace_concept_evolution)
* /api/memory/consistency (check_consistency)
- Validation des paramètres req.body
- Appel des fonctions de memoryService
- Réponses JSON standardisées
- Gestion d'erreurs avec codes HTTP appropriés (400, 500)
- Middleware optionnel d'authentification
Technique :
- express.Router() dans server/routes/memory.js
- Import de memoryService
- try/catch pour chaque route
- Validation avec express-validator ou manuelle
- Monter le routeur dans server/index.js : app.use('/api/memory', memoryRoutes)
Intégration :
- Nouveau fichier server/routes/memory.js
- Import dans server/index.js existant
- S'ajoute aux routes existantes (/api/conversations, /api/claude/*)
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Tester POST /api/memory/search avec Postman ou curl
2. Vérifier la réponse JSON avec résultats de recherche
3. Tester POST /api/memory/add avec un contenu simple
4. Vérifier que la pensée est ajoutée dans ChromaDB
5. Tester les erreurs (paramètres manquants)
6. Vérifier les logs et codes HTTP
</test_steps>
</feature_3>
<feature_4>
<title>Bouton "Sauvegarder dans la mémoire" dans le chat</title>
<description>
Ajouter un bouton discret dans l'interface de chat pour sauvegarder manuellement une conversation dans la mémoire.
Fonctionnalités :
- Bouton icône "cerveau" ou "étoile" près de chaque message assistant
- Au clic : ouvre un petit modal/popover
- Formulaire rapide : Catégorie (select) + Tags (input, optionnel)
- Bouton "Sauvegarder"
- Sauvegarde la conversation complète (tous les messages de la conversation active)
- Notification toast de confirmation
- Bouton devient "Déjà sauvegardé" après sauvegarde (state local)
Technique :
- Ajout de bouton dans le composant Message existant
- State local pour modal (useState)
- Appel API POST /api/memory/add au submit
- Utilisation de conversation_id pour récupérer tous les messages
- Toast notification avec react-hot-toast ou équivalent
Intégration :
- Modifier le composant Message/ChatMessage existant
- Ajouter un icône Lucide React (Brain, Star, ou Bookmark)
- Modal/Popover avec Headless UI ou simple div conditionnelle
</description>
<priority>2</priority>
<category>frontend</category>
<test_steps>
1. Avoir une conversation dans le chat
2. Voir les boutons "Sauvegarder" apparaître
3. Cliquer sur un bouton et voir le modal
4. Sélectionner catégorie "thematique" et ajouter des tags
5. Cliquer "Sauvegarder" et voir la notification
6. Vérifier que le bouton devient "Déjà sauvegardé"
7. Rechercher la conversation sauvegardée via l'API
</test_steps>
</feature_4>
<feature_5>
<title>Panel de recherche de souvenirs dans la sidebar</title>
<description>
Ajouter une section de recherche de souvenirs dans la sidebar gauche existante.
Fonctionnalités :
- Nouvel onglet/section "Mémoire" dans la sidebar existante (après Conversations)
- Champ de recherche avec placeholder "Rechercher dans mes souvenirs..."
- Liste des résultats affichés en dessous
- Pour chaque résultat : Score | Extrait (2 lignes) | Date | Tags
- Clic sur un résultat : affiche le détail complet dans un modal
- Filtre par catégorie (3 boutons radio : Toutes | Fondatrice | Thématique | Contextuelle)
- Maximum 10 résultats affichés
Technique :
- Ajouter section dans Sidebar.jsx existant
- Nouvel état pour searchQuery et searchResults
- Debounce sur l'input (useDebounce hook)
- Appel API GET /api/memory/search?q={query}&category={filter}
- Affichage avec Tailwind, style similaire à la liste de conversations
- Modal pour détail (réutiliser un modal existant si possible)
Intégration :
- Modification de src/components/Sidebar.jsx existant
- Ajouter un toggle pour afficher/masquer la section Mémoire
- S'intègre visuellement avec le design existant
</description>
<priority>2</priority>
<category>frontend</category>
<test_steps>
1. Ouvrir l'application et voir la section "Mémoire" dans la sidebar
2. Taper une requête dans le champ de recherche
3. Voir les résultats apparaître avec scores et tags
4. Cliquer sur un résultat et voir le modal de détail
5. Tester les filtres par catégorie
6. Vérifier que la recherche est debounced (pas d'appel à chaque lettre)
7. Vérifier le style cohérent avec le design existant
</test_steps>
</feature_5>
<feature_6>
<title>Sauvegarde automatique des conversations importantes</title>
<description>
Implémenter la sauvegarde automatique des conversations marquées comme "importantes" ou après un certain nombre de messages.
Fonctionnalités :
- Détection automatique : conversations de >10 messages OU marquées "épinglées"
- Déclenchement : en background après chaque nouveau message assistant
- Extraction automatique basique :
* Catégorie : "contextuelle" par défaut
* Tags : mots en majuscules, mots >8 caractères, mots répétés
* Date : timestamp du message
- Sauvegarde silencieuse (pas de modal, juste log backend)
- Flag dans table conversations : has_memory_backup BOOLEAN
Technique :
- Hook/middleware dans l'endpoint POST /api/conversations/:id/messages
- Après insertion du message assistant : vérifier conditions
- Si conditions remplies : appel async memoryService.addThought()
- Extraction tags basique avec regex/split
- UPDATE conversations SET has_memory_backup = 1 WHERE id = ?
Intégration :
- Modification de server/routes/conversations.js (endpoint POST messages)
- Ajout colonne has_memory_backup dans table conversations (migration)
- Appel non-bloquant (Promise.then, pas de await)
</description>
<priority>3</priority>
<category>backend</category>
<test_steps>
1. Créer une nouvelle conversation
2. Envoyer >10 messages
3. Vérifier dans les logs qu'une sauvegarde automatique est déclenchée
4. Rechercher la conversation dans l'API /api/memory/search
5. Vérifier que has_memory_backup = 1 dans la DB
6. Tester avec une conversation épinglée (<10 messages)
7. Vérifier que les tags sont extraits correctement
</test_steps>
</feature_6>
<feature_7>
<title>Indicateur visuel de mémoire active</title>
<description>
Afficher un indicateur visuel dans l'interface pour montrer que la mémoire est active et utilisée.
Fonctionnalités :
- Icône "cerveau" ou "mémoire" dans le header de l'application
- État : Vert (connecté) | Orange (déconnecté) | Gris (désactivé)
- Tooltip au survol : "Mémoire active - X souvenirs" ou "Mémoire déconnectée"
- Clic sur l'icône : ouvre un mini dashboard avec stats rapides
* Nombre total de souvenirs
* Dernière sauvegarde (timestamp)
* Connexion MCP : OK/KO
- Animation discrète lors d'une sauvegarde (pulse)
Technique :
- Composant React MemoryIndicator dans Header.jsx
- Appel API GET /api/memory/stats toutes les 30 secondes (setInterval)
- État pour connectionStatus : 'connected' | 'disconnected' | 'disabled'
- Icône Brain de Lucide React avec couleurs conditionnelles
- Popover Headless UI pour le mini dashboard
Intégration :
- Ajout dans src/components/Header.jsx existant
- S'intègre à côté du model selector
- Style cohérent avec le design claude.ai
</description>
<priority>3</priority>
<category>frontend</category>
<test_steps>
1. Voir l'icône mémoire dans le header (vert si connecté)
2. Survoler l'icône et lire le tooltip
3. Cliquer sur l'icône et voir le mini dashboard
4. Vérifier les stats (nombre de souvenirs, dernière sauvegarde)
5. Arrêter le serveur MCP et voir l'icône devenir orange
6. Sauvegarder une conversation et voir l'animation pulse
7. Vérifier le polling des stats (console network toutes les 30s)
</test_steps>
</feature_7>
<feature_8>
<title>Configuration des Tools Claude API pour la mémoire</title>
<description>
Exposer les outils MCP comme Tools dans l'API Claude pour que le LLM puisse décider de façon autonome d'utiliser sa mémoire.
Fonctionnalités :
- Définir 2 tools principaux pour l'API Claude :
1. save_memory : Sauvegarder une conversation ou pensée
2. search_memories : Rechercher dans les souvenirs passés
- Chaque tool avec description claire et JSON schema
- Tools toujours disponibles dans les appels Claude (sauf si désactivé)
- Gestion du cycle tool_use → tool_result
- Le LLM décide de façon autonome quand sauvegarder/rechercher
Définition des tools :
- save_memory :
* description: "Sauvegarde cette conversation ou une pensée importante dans ta mémoire à long terme"
* paramètres: content (requis), category (requis: fondatrice|thematique|contextuelle), tags (array), concepts (array), emotions (array optionnel)
- search_memories :
* description: "Recherche dans tes souvenirs de conversations passées"
* paramètres: query (requis), n_results (optionnel, default 5), filter_category (optionnel)
Technique :
- Modification de server/routes/claude.js
- Définir const MEMORY_TOOLS = [{...}, {...}]
- Ajouter tools: MEMORY_TOOLS dans anthropic.messages.create()
- Gérer response.stop_reason === 'tool_use'
- Extraire tool calls, exécuter via memoryService, renvoyer tool_result
- Boucle jusqu'à response finale (stop_reason === 'end_turn')
Intégration :
- Modification de server/routes/claude.js existant
- Nouveau fichier server/config/memoryTools.js pour définitions tools
- Handler de tool execution dans le streaming SSE
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Dire à Claude "Cette conversation est importante, sauvegarde-la"
2. Vérifier dans les logs que Claude appelle tool save_memory
3. Vérifier que le backend exécute add_thought via MCP
4. Vérifier que Claude confirme la sauvegarde
5. Demander "Que sais-tu sur X ?" et voir Claude appeler search_memories
6. Vérifier que les souvenirs sont retournés et utilisés dans la réponse
7. Tester avec MCP_MEMORY_ENABLED=false
</test_steps>
</feature_8>
<feature_9>
<title>Handler de Tool Execution pour les outils mémoire</title>
<description>
Implémenter le handler qui exécute les tool calls de Claude et retourne les résultats.
Fonctionnalités :
- Fonction executeTool(tool_name, tool_input) qui route vers memoryService
- Support de save_memory → memoryService.addThought()
- Support de search_memories → memoryService.searchMemories()
- Formatage des résultats en tool_result compatible Claude API
- Gestion des erreurs (retourner error dans tool_result)
- Logging de chaque exécution de tool
- Timeout de 10 secondes par tool call
Workflow :
1. Claude retourne stop_reason='tool_use' + content avec tool_use block
2. Backend extrait tool_name et tool_input
3. executeTool() appelle la fonction MCP correspondante
4. Résultat formaté en tool_result
5. Nouvelle requête à Claude avec tool_result
6. Claude utilise le résultat pour sa réponse finale
Technique :
- Fonction async executeTool(tool_name, tool_input)
- Switch sur tool_name pour router
- Appel des fonctions memoryService
- Formatage : { type: "tool_result", tool_use_id, content }
- Gestion try/catch avec error reporting
Intégration :
- Nouveau fichier server/services/toolExecutor.js
- Appelé depuis server/routes/claude.js dans la boucle de streaming
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Tester save_memory avec tous les paramètres
2. Vérifier que le tool_result est retourné correctement
3. Tester search_memories avec query simple
4. Vérifier le formatage des résultats
5. Tester avec des paramètres invalides (gestion erreur)
6. Vérifier les logs d'exécution
7. Tester le timeout avec un MCP server lent
</test_steps>
</feature_9>
<feature_10>
<title>System Prompt enrichi pour guider l'utilisation de la mémoire</title>
<description>
Ajouter des instructions au system prompt pour que Claude utilise intelligemment sa mémoire.
Fonctionnalités :
- Instructions claires sur quand sauvegarder :
* Conversations fondatrices (premières interactions, moments clés)
* Discussions thématiques approfondies (philosophie, science, art)
* Sur demande explicite de l'utilisateur
- Instructions sur quand rechercher :
* Questions qui font référence au passé
* Sujets déjà discutés
* Pour enrichir les réponses avec du contexte
- Guidance sur les métadonnées :
* Catégories : quand utiliser fondatrice vs thematique vs contextuelle
* Tags : extraire les concepts clés
* Émotions : optionnelles mais enrichissantes
- Ton naturel : ne pas annoncer systématiquement les sauvegardes
System Prompt ajouté :
```
Tu as accès à une mémoire persistante via deux outils :
1. save_memory : Sauvegarde les conversations importantes
- Utilise category='fondatrice' pour les moments clés et premières interactions
- Utilise category='thematique' pour les discussions approfondies sur des concepts
- Utilise category='contextuelle' pour les échanges quotidiens intéressants
- Extrais des tags pertinents (concepts clés, mots importants)
2. search_memories : Recherche dans tes souvenirs
- Utilise-le quand l'utilisateur fait référence à des discussions passées
- Ou pour enrichir ta réponse avec du contexte antérieur
Utilise ces outils de façon naturelle et autonome. Tu n'es pas obligé d'annoncer
chaque sauvegarde, sauf si c'est pertinent dans la conversation.
```
Technique :
- Ajout au system prompt existant dans server/routes/claude.js
- Concaténation avec custom instructions si présentes
- Paramètre enable_memory_tools (default: true) pour activer/désactiver
Intégration :
- Modification du system prompt dans server/routes/claude.js
- S'ajoute aux instructions existantes
</description>
<priority>2</priority>
<category>backend</category>
<test_steps>
1. Avoir une conversation initiale et voir si Claude la sauvegarde
2. Vérifier qu'il utilise la bonne catégorie
3. Faire référence à une discussion passée et voir s'il recherche
4. Vérifier que les tags extraits sont pertinents
5. Tester que Claude ne sur-annonce pas les sauvegardes
6. Demander explicitement une sauvegarde et vérifier
7. Vérifier que les émotions sont ajoutées quand pertinent
</test_steps>
</feature_10>
</core_features>
<ui_design>
<integration_notes>
Cette extension s'intègre dans le design existant du clone Claude.ai.
Tous les nouveaux composants doivent respecter le design system existant.
</integration_notes>
<new_components>
- MemoryIndicator : Icône Brain dans le header avec état coloré (vert/orange/gris)
- MemorySaveButton : Bouton discret dans chaque message assistant pour sauvegarde manuelle
- MemorySearchPanel : Section dans la sidebar pour rechercher dans les souvenirs
- MemoryDetailModal : Modal pour afficher le détail complet d'un souvenir
- SaveMemoryModal : Petit modal/popover pour choisir catégorie et tags avant sauvegarde
</new_components>
<color_scheme>
Utiliser les couleurs existantes du clone Claude.ai, avec ajouts pour la mémoire :
- Indicateur mémoire : Vert (#10B981) connecté | Orange (#F59E0B) déconnecté | Gris (#6B7280) désactivé
- Badges catégories :
* Fondatrice: Or/Jaune (#F59E0B)
* Thématique: Bleu (#3B82F6)
* Contextuelle: Gris (#6B7280)
- Scores de pertinence : Gradient vert (#10B981) à rouge (#EF4444)
</color_scheme>
<design_consistency>
- Respecter la palette claude.ai existante (orange/amber #CC785C comme accent)
- Utiliser les mêmes composants Tailwind que l'existant
- Polices : même font stack que le projet (Inter/SF Pro)
- Boutons : même style que les boutons existants
- Modals : réutiliser les modals Headless UI existants si possible
</design_consistency>
</ui_design>
<api_endpoints>
<note>
Ces endpoints s'ajoutent aux endpoints existants du clone Claude.ai.
Tous les endpoints mémoire sont sous le préfixe /api/memory.
</note>
<endpoint>
<method>POST</method>
<path>/api/memory/search</path>
<description>Rechercher sémantiquement dans les souvenirs (wrapper de search_memories MCP)</description>
<request_body>{"query": "string", "n_results": number (opt, default 5), "filter_category": "string (opt)"}</request_body>
<response>{"results": [{content, metadata, relevance_score, distance}]}</response>
</endpoint>
<endpoint>
<method>POST</method>
<path>/api/memory/add</path>
<description>Ajouter une pensée/conversation manuellement (wrapper de add_thought MCP)</description>
<request_body>{"content": "string", "context": {category, tags, emotions, concepts}}</request_body>
<response>{"id": "string", "message": "string"}</response>
</endpoint>
<endpoint>
<method>POST</method>
<path>/api/memory/evolution</path>
<description>Tracer l'évolution d'un concept (wrapper de trace_concept_evolution MCP)</description>
<request_body>{"concept": "string", "limit": number (opt, default 10)}</request_body>
<response>{"timeline": [{date, content, evolution}]}</response>
</endpoint>
<endpoint>
<method>POST</method>
<path>/api/memory/consistency</path>
<description>Vérifier cohérence d'une affirmation (wrapper de check_consistency MCP)</description>
<request_body>{"statement": "string"}</request_body>
<response>{"consistency_score": number, "contradictions": [...]}}</response>
</endpoint>
<endpoint>
<method>GET</method>
<path>/api/memory/stats</path>
<description>Obtenir statistiques basiques sur la mémoire</description>
<request_body>N/A</request_body>
<response>{"connected": boolean, "total_memories": number (approx), "last_save": timestamp}</response>
</endpoint>
<existing_endpoints_modified>
<endpoint>
<method>POST</method>
<path>/api/claude/chat</path>
<modification>Ajouter logique d'enrichissement automatique avec souvenirs avant appel Claude</modification>
</endpoint>
<endpoint>
<method>POST</method>
<path>/api/conversations/:id/messages</path>
<modification>Ajouter logique de sauvegarde automatique après insertion message assistant</modification>
</endpoint>
</existing_endpoints_modified>
</api_endpoints>
<database_schema>
<chromadb>
La base vectorielle ChromaDB est entièrement gérée par le serveur MCP Ikario.
Le backend Node.js n'y accède pas directement, seulement via les outils MCP.
Emplacement : ./ikario_rag/index/
</chromadb>
<sqlite_modifications>
Modifications mineures à la base SQLite existante du clone Claude.ai :
<table>
<name>conversations (table existante - ajouter colonne)</name>
<new_column>has_memory_backup INTEGER DEFAULT 0</new_column>
<description>Flag indiquant si la conversation a été sauvegardée dans la mémoire</description>
</table>
<table>
<name>conversation_settings (table existante - optionnel)</name>
<new_column>enable_memory INTEGER DEFAULT 1</new_column>
<description>Active/désactive l'enrichissement automatique avec souvenirs pour cette conversation</description>
</table>
</sqlite_modifications>
<no_new_tables>
Cette extension ne crée pas de nouvelles tables SQLite.
Toute la mémoire sémantique est dans ChromaDB (géré par MCP).
</no_new_tables>
</database_schema>
<deployment>
<development>
Le projet Claude.ai Clone est déjà configuré et déployé.
Cette extension ajoute simplement :
- Le serveur MCP Ikario RAG (Python) qui doit tourner en background ou être lancé par le backend
- Variables d'environnement pour la connexion MCP
</development>
<environment_variables>
Ajouter au .env existant :
- MCP_IKARIO_SERVER_PATH : Chemin absolu vers ikario_rag/server.py
- MCP_MEMORY_ENABLED : true | false (pour activer/désactiver la feature)
</environment_variables>
<dependencies>
Backend (package.json) :
- Ajouter : @modelcontextprotocol/sdk (client MCP Node.js)
MCP Server (déjà installé) :
- Python 3.11+
- chromadb, sentence-transformers, numpy, mcp
</dependencies>
</deployment>
</project_specification>

1024
prompts/app_spec_ikario_rag_UI.txt
View File

File diff suppressed because it is too large Load Diff

498
prompts/app_spec_tavily_mcp.txt Normal file
View File

@@ -0,0 +1,498 @@
<project_specification>
<project_name>ikario - Tavily MCP Integration for Internet Access</project_name>
<overview>
This specification adds Tavily search capabilities via MCP (Model Context Protocol) to give Ikario
internet access for real-time web searches. Tavily provides high-quality search results optimized
for AI agents, making it ideal for research, fact-checking, and accessing current information.
This integration adds a new MCP server connection to the existing architecture (alongside the
ikario-memory MCP server) and exposes Tavily search tools to Ikario during conversations.
All changes are additive and backward-compatible. Existing functionality remains unchanged.
</overview>
<architecture_design>
<mcp_integration>
Tavily MCP Server Connection:
- Uses @modelcontextprotocol/sdk Client to connect to Tavily MCP server
- Connection can be stdio-based (local MCP server) or HTTP-based (remote)
- Tavily MCP server provides search tools that are exposed to Claude via Tool Use API
- Backend routes handle tool execution and return results to Claude
</mcp_integration>
<benefits>
- Real-time internet access for Ikario
- High-quality search results optimized for LLMs
- Fact-checking and verification capabilities
- Access to current events and news
- Research assistance with cited sources
- Seamless integration with existing memory tools
</benefits>
</architecture_design>
<technology_stack>
<mcp_server>
<name>Tavily MCP Server</name>
<protocol>Model Context Protocol (MCP)</protocol>
<connection>stdio or HTTP transport</connection>
<sdk>@modelcontextprotocol/sdk</sdk>
<api_key>Tavily API key (from https://tavily.com)</api_key>
</mcp_server>
<backend>
<runtime>Node.js with Express (existing)</runtime>
<mcp_client>MCP Client for Tavily server connection</mcp_client>
<tool_executor>Existing toolExecutor service extended with Tavily tools</tool_executor>
</backend>
<api_endpoints>
<tavily_routes>GET/POST /api/tavily/* for Tavily-specific operations</tavily_routes>
<existing_routes>Existing /api/claude/chat routes support Tavily tools automatically</existing_routes>
</api_endpoints>
</technology_stack>
<prerequisites>
<environment_setup>
- Tavily API key obtained from https://tavily.com (free tier available)
- API key stored in environment variable TAVILY_API_KEY or configuration file
- MCP SDK already installed (@modelcontextprotocol/sdk exists for ikario-memory)
- Tavily MCP server installed (npm package or Python package)
</environment_setup>
<configuration>
- Add Tavily MCP server config to server/.claude_settings.json or similar
- Configure connection parameters (stdio vs HTTP)
- Set API key securely
</configuration>
</prerequisites>
<core_features>
<feature_1>
<title>Tavily MCP Client Setup</title>
<description>
Create MCP client connection to Tavily search server. This is similar to the existing
ikario-memory MCP client but connects to Tavily instead.
Implementation:
- Create server/services/tavilyMcpClient.js
- Initialize MCP client with Tavily server connection
- Handle connection lifecycle (connect, disconnect, reconnect)
- Implement health checks and connection status
- Export client instance and helper functions
Configuration:
- Read Tavily API key from environment or config file
- Configure transport (stdio or HTTP)
- Set connection timeout and retry logic
- Log connection status for debugging
Error Handling:
- Graceful degradation if Tavily is unavailable
- Connection retry with exponential backoff
- Clear error messages for configuration issues
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Verify MCP client can connect to Tavily server on startup
2. Test connection health check endpoint returns correct status
3. Verify graceful handling when Tavily API key is missing
4. Test reconnection logic when connection drops
5. Verify connection status is logged correctly
6. Test that server starts even if Tavily is unavailable
</test_steps>
</feature_1>
<feature_2>
<title>Tavily Tool Configuration</title>
<description>
Configure Tavily search tools to be available to Claude during conversations.
This integrates with the existing tool system (like memory tools).
Implementation:
- Create server/config/tavilyTools.js
- Define tool schemas for Tavily search capabilities
- Integrate with existing toolExecutor service
- Add Tavily tools to system prompt alongside memory tools
Tavily Tools to Expose:
- tavily_search: General web search with AI-optimized results
- Parameters: query (string), max_results (number), search_depth (basic/advanced)
- Returns: Array of search results with title, url, content, score
- tavily_search_news: News-specific search for current events
- Parameters: query (string), max_results (number), days (number)
- Returns: Recent news articles with metadata
Tool Schema:
- Follow Claude Tool Use API format
- Clear descriptions for each tool
- Well-defined input schemas with validation
- Proper error handling in tool execution
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Verify Tavily tools are listed in available tools
2. Test tool schema validation with valid inputs
3. Test tool schema validation rejects invalid inputs
4. Verify tools appear in Claude's system prompt
5. Test that tool descriptions are clear and accurate
6. Verify tools can be called without errors
</test_steps>
</feature_2>
<feature_3>
<title>Tavily Tool Executor Integration</title>
<description>
Integrate Tavily tools into the existing toolExecutor service so Claude can
use them during conversations.
Implementation:
- Extend server/services/toolExecutor.js to handle Tavily tools
- Add tool detection for tavily_search and tavily_search_news
- Implement tool execution logic using Tavily MCP client
- Format Tavily results for Claude consumption
- Handle errors and timeouts gracefully
Tool Execution Flow:
1. Claude requests tool use (e.g., tavily_search)
2. toolExecutor detects Tavily tool request
3. Call Tavily MCP client with tool parameters
4. Receive and format search results
5. Return formatted results to Claude
6. Claude incorporates results into response
Result Formatting:
- Convert Tavily results to Claude-friendly format
- Include source URLs for citation
- Add relevance scores
- Truncate content if too long
- Handle empty results gracefully
</description>
<priority>1</priority>
<category>backend</category>
<test_steps>
1. Test tavily_search tool execution with valid query
2. Verify results are properly formatted
3. Test tavily_search_news tool execution
4. Verify error handling when Tavily API fails
5. Test timeout handling for slow searches
6. Verify results include proper citations and URLs
7. Test with empty search results
8. Test with very long search queries
</test_steps>
</feature_3>
<feature_4>
<title>System Prompt Enhancement for Internet Access</title>
<description>
Update the system prompt to inform Ikario about internet access capabilities.
This should be added alongside existing memory tools instructions.
Implementation:
- Update MEMORY_SYSTEM_PROMPT in server/routes/messages.js and claude.js
- Add Tavily tools documentation
- Provide usage guidelines for when to search the internet
- Include examples of good search queries
Prompt Addition:
"## Internet Access via Tavily
Tu as accès à internet en temps réel via deux outils de recherche :
1. tavily_search : Recherche web générale optimisée pour l'IA
- Utilise pour : rechercher des informations actuelles, vérifier des faits,
trouver des sources fiables
- Paramètres : query (ta question), max_results (nombre de résultats, défaut: 5),
search_depth ('basic' ou 'advanced')
- Retourne : Résultats avec titre, URL, contenu et score de pertinence
2. tavily_search_news : Recherche d'actualités récentes
- Utilise pour : événements actuels, nouvelles, actualités
- Paramètres : query, max_results, days (nombre de jours en arrière, défaut: 7)
Quand utiliser la recherche internet :
- Quand l'utilisateur demande des informations récentes ou actuelles
- Pour vérifier des faits ou données que tu n'es pas sûr de connaître
- Quand ta base de connaissances est trop ancienne (après janvier 2025)
- Pour trouver des sources et citations spécifiques
- Pour des requêtes nécessitant des données en temps réel
N'utilise PAS la recherche pour :
- Des questions sur ta propre identité ou capacités
- Des concepts généraux que tu connais déjà bien
- Des questions purement créatives ou d'opinion
Utilise ces outils de façon autonome selon les besoins de la conversation.
Cite toujours tes sources quand tu utilises des informations de Tavily."
</description>
<priority>2</priority>
<category>backend</category>
<test_steps>
1. Verify system prompt includes Tavily instructions
2. Test that Claude understands when to use Tavily search
3. Verify Claude cites sources from Tavily results
4. Test that Claude uses appropriate search queries
5. Verify Claude chooses between tavily_search and tavily_search_news correctly
6. Test that Claude doesn't over-use search for simple questions
</test_steps>
</feature_4>
<feature_5>
<title>Tavily Status API Endpoint</title>
<description>
Create API endpoint to check Tavily MCP connection status and search capabilities.
Similar to /api/memory/status endpoint.
Implementation:
- Create GET /api/tavily/status endpoint
- Return connection status, available tools, and configuration
- Create GET /api/tavily/health endpoint for health checks
- Add Tavily status to existing /api/memory/stats (rename to /api/tools/stats)
Response Format:
{
"success": true,
"data": {
"connected": true,
"message": "Tavily MCP server is connected",
"tools": ["tavily_search", "tavily_search_news"],
"apiKeyConfigured": true,
"transport": "stdio"
}
}
</description>
<priority>2</priority>
<category>backend</category>
<test_steps>
1. Test GET /api/tavily/status returns correct status
2. Verify status shows "connected" when Tavily is available
3. Verify status shows "disconnected" when Tavily is unavailable
4. Test health endpoint returns proper status code
5. Verify tools list is accurate
6. Test with missing API key shows proper error
</test_steps>
</feature_5>
<feature_6>
<title>Frontend UI Indicator for Internet Access</title>
<description>
Add visual indicator in the UI to show when Ikario has internet access via Tavily.
This can be displayed alongside the existing memory status indicator.
Implementation:
- Add Tavily status indicator in header or sidebar
- Show online/offline status for Tavily connection
- Optional: Show when Tavily is being used during a conversation
- Optional: Add tooltip explaining internet access capabilities
Visual Design:
- Globe or wifi icon to represent internet access
- Green when connected, gray when disconnected
- Subtle animation when search is in progress
- Tooltip: "Internet access via Tavily" or similar
Integration:
- Use existing useMemory hook pattern or create useTavily hook
- Poll /api/tavily/status periodically (every 60s)
- Update status in real-time during searches
</description>
<priority>3</priority>
<category>frontend</category>
<test_steps>
1. Verify internet access indicator appears in UI
2. Test status updates when Tavily connects/disconnects
3. Verify tooltip shows correct information
4. Test that indicator shows activity during searches
5. Verify status polling doesn't impact performance
6. Test with Tavily disabled shows offline status
</test_steps>
</feature_6>
<feature_7>
<title>Manual Search UI (Optional Enhancement)</title>
<description>
Optional: Add manual search interface to allow users to trigger Tavily searches directly,
similar to the memory search panel.
Implementation:
- Add "Internet Search" panel in sidebar (alongside Memory panel)
- Search input for manual Tavily queries
- Display search results with title, snippet, URL
- Click to insert results into conversation
- Filter by search type (general vs news)
This is OPTIONAL and lower priority. The primary use case is autonomous search by Claude.
</description>
<priority>4</priority>
<category>frontend</category>
<test_steps>
1. Verify search panel appears in sidebar
2. Test manual search returns results
3. Verify results display properly with links
4. Test inserting results into conversation
5. Test news search filter works correctly
6. Verify search history is saved (optional)
</test_steps>
</feature_7>
<feature_8>
<title>Configuration and Settings</title>
<description>
Add Tavily configuration options to settings and environment.
Implementation:
- Add TAVILY_API_KEY to environment variables
- Add Tavily settings to .claude_settings.json or similar config file
- Create server/config/tavilyConfig.js for configuration management
- Document configuration options in README
Configuration Options:
- API key
- Max results per search (default: 5)
- Search depth (basic/advanced)
- Timeout duration
- Enable/disable Tavily globally
- Rate limiting settings
Security:
- API key should NOT be exposed to frontend
- Use environment variable or secure config file
- Validate API key on startup
- Log warnings if API key is missing
</description>
<priority>2</priority>
<category>backend</category>
<test_steps>
1. Verify API key is read from environment variable
2. Test fallback to config file if env var not set
3. Verify API key validation on startup
4. Test configuration options are applied correctly
5. Verify API key is never exposed in API responses
6. Test enabling/disabling Tavily via config
</test_steps>
</feature_8>
<feature_9>
<title>Error Handling and Rate Limiting</title>
<description>
Implement robust error handling and rate limiting for Tavily API calls.
Implementation:
- Detect and handle Tavily API errors (rate limits, invalid API key, etc.)
- Implement client-side rate limiting to avoid hitting Tavily limits
- Cache search results for duplicate queries (optional)
- Provide clear error messages to Claude when searches fail
Error Types:
- 401: Invalid API key
- 429: Rate limit exceeded
- 500: Tavily server error
- Timeout: Search took too long
- Network: Connection failed
Rate Limiting:
- Track searches per minute/hour
- Queue requests if limit reached
- Return cached results for duplicate queries within 5 minutes
- Log rate limit warnings
</description>
<priority>2</priority>
<category>backend</category>
<test_steps>
1. Test error handling for invalid API key
2. Verify rate limit detection and handling
3. Test timeout handling for slow searches
4. Verify error messages are clear to Claude
5. Test rate limiting prevents API abuse
6. Verify caching works for duplicate queries
</test_steps>
</feature_9>
<feature_10>
<title>Documentation and README Updates</title>
<description>
Update project documentation to explain Tavily integration.
Implementation:
- Update main README.md with Tavily setup instructions
- Add TAVILY_SETUP.md with detailed configuration guide
- Document API endpoints in README
- Add examples of using Tavily with Ikario
- Document troubleshooting steps
Documentation Sections:
- Prerequisites (Tavily API key)
- Installation steps
- Configuration options
- Testing Tavily connection
- Example conversations using internet search
- Troubleshooting common issues
- API reference for Tavily endpoints
</description>
<priority>3</priority>
<category>documentation</category>
<test_steps>
1. Verify README has Tavily setup section
2. Test that setup instructions are clear and complete
3. Verify all configuration options are documented
4. Test examples work as described
5. Verify troubleshooting section covers common issues
</test_steps>
</feature_10>
</core_features>
<implementation_notes>
<order>
Recommended implementation order:
1. Feature 1 (MCP Client Setup) - Foundation
2. Feature 2 (Tool Configuration) - Core functionality
3. Feature 3 (Tool Executor Integration) - Core functionality
4. Feature 8 (Configuration) - Required for testing
5. Feature 4 (System Prompt) - Makes tools accessible to Claude
6. Feature 9 (Error Handling) - Production readiness
7. Feature 5 (Status API) - Monitoring
8. Feature 10 (Documentation) - User onboarding
9. Feature 6 (UI Indicator) - Nice to have
10. Feature 7 (Manual Search UI) - Optional enhancement
</order>
<testing>
After implementing features 1-5, you should be able to:
- Ask Ikario: "Quelle est l'actualité aujourd'hui ?"
- Ask Ikario: "Recherche des informations sur [topic actuel]"
- Ask Ikario: "Vérifie cette information : [claim]"
Ikario should autonomously use Tavily search and cite sources.
</testing>
<compatibility>
- This specification is fully compatible with existing ikario-memory MCP integration
- Ikario will have both memory tools AND internet search tools
- Tools can be used together in the same conversation
- No conflicts expected between tool systems
</compatibility>
</implementation_notes>
<safety_requirements>
<critical>
- DO NOT expose Tavily API key to frontend or in API responses
- DO NOT modify existing MCP memory integration
- DO NOT break existing conversation functionality
- Tavily should gracefully degrade if unavailable (don't crash the app)
- Implement proper rate limiting to avoid API abuse
- Validate all user inputs before passing to Tavily
- Sanitize search results before displaying (XSS prevention)
- Log all Tavily API calls for monitoring and debugging
</critical>
</safety_requirements>
<success_metrics>
- Ikario can successfully perform internet searches when asked
- Search results are relevant and well-formatted
- Sources are properly cited
- Tavily integration doesn't slow down conversations
- Error handling is robust and user-friendly
- Configuration is straightforward
- Documentation is clear and complete
</success_metrics>
</project_specification>

1360
prompts/extended_thinking_spec.md
View File

File diff suppressed because it is too large Load Diff