Trackeep/docs/AI_ASSISTANT.md

AI Assistant Integration

Trackeep now includes an AI assistant powered by Mistral AI that can help you organize and interact with your personal data.

Features

• Context-Aware Conversations: The AI has access to your bookmarks, tasks, files, and notes to provide personalized assistance
• Chat Sessions: Create and manage multiple chat sessions for different topics
• Configurable Context: Choose which data types the AI can access in each conversation
• Smart Responses: Get help with finding information, organizing content, and planning tasks

Setup

1. Get a Mistral API Key:

   • Sign up at Mistral AI
   • Get your API key from the dashboard
   • Add it to your .env file: MISTRAL_API_KEY=your_key_here

2. Model Configuration:

   • Default model: mistral-small-latest (cost-effective and capable)
   • Can be changed via MISTRAL_MODEL environment variable

Usage

Accessing the AI Assistant

1. Navigate to /app/chat in your Trackeep instance
2. Click "New Chat" to start a conversation
3. The AI will greet you and offer to help with your data

Context Settings

Configure what data the AI can access:

• Bookmarks: Include saved links and articles
• Tasks: Include todo items and progress tracking
• Files: Include uploaded documents and media
• Notes: Include personal notes and documents

Example Interactions

Finding Content:

User: Show me all bookmarks about machine learning
AI: I found 3 bookmarks related to machine learning:
1. "Introduction to Neural Networks" - https://example.com/neural-nets
2. "ML Best Practices" - https://example.com/ml-guide  
3. "Deep Learning Course" - https://example.com/dl-course

Task Management:

User: What tasks do I have due this week?
AI: You have 2 tasks due this week:
1. "Complete project proposal" (High priority) - Due in 2 days
2. "Review documentation" (Medium priority) - Due in 5 days

Organization Help:

User: Help me organize my learning resources
AI: I can see you have 15 bookmarks, 8 files, and 5 notes related to learning. Would you like me to suggest a tagging system or help you create a study plan?

API Endpoints

Chat Operations

• POST /api/v1/chat/send - Send a message
• GET /api/v1/chat/sessions - List chat sessions
• GET /api/v1/chat/sessions/:id/messages - Get session messages
• DELETE /api/v1/chat/sessions/:id - Delete session

Request/Response Format

Send Message Request:

{
  "message": "Your message here",
  "session_id": "optional-session-id",
  "context": {
    "bookmarks": true,
    "tasks": true,
    "files": false,
    "notes": true
  }
}

Chat Response:

{
  "id": "chat-response-id",
  "message": "AI response here",
  "role": "assistant",
  "session_id": "session-id",
  "timestamp": "2024-01-27T16:30:00Z",
  "model": "mistral-small-latest",
  "token_usage": {
    "prompt_tokens": 150,
    "completion_tokens": 75,
    "total_tokens": 225
  },
  "context_used": ["bookmark:1", "task:3", "note:2"]
}

Data Privacy

• All AI requests are processed securely through Mistral's API
• User data is only shared with the AI when explicitly enabled via context settings
• Chat history is stored locally in your Trackeep database
• No data is shared with third parties beyond the AI service

Cost Management

The AI assistant uses mistral-small-latest which is optimized for cost:

• Approximately $0.60 per 1M input tokens
• Approximately $1.80 per 1M output tokens
• Typical conversations use 200-500 tokens total

To monitor costs:

• Check token usage in chat responses
• Review session history regularly
• Adjust context settings to limit data scope

Troubleshooting

Common Issues

"Mistral API key not configured":

• Add MISTRAL_API_KEY to your .env file
• Restart the backend server

"Failed to call AI" errors:

• Check your API key is valid
• Verify internet connectivity
• Check Mistral service status

Large response times:

• Reduce context scope (disable some data types)
• Consider breaking complex questions into smaller parts

Debug Mode

Set GIN_MODE=debug to see detailed API logs including:

• Token usage counts
• Context data being sent
• API response times

Future Enhancements

Planned improvements to the AI assistant:

• Voice input/output support
• Advanced context filtering (date ranges, tags)
• Integration with external services
• Custom prompt templates
• Multi-language support