first commit
This commit is contained in:
Roger Oriol
481
README.md
Normal file
481
README.md
Normal file
@@ -0,0 +1,481 @@
|
||||
# MyOrg Personal Assistant
|
||||
|
||||
An AI-powered personal assistant that helps manage daily life using the myorg GTD system.
|
||||
|
||||
## Overview
|
||||
|
||||
The MyOrg Personal Assistant is an intelligent agent that helps you manage your personal organization system (myorg). It acts as a trusted assistant that can read, understand, and modify your GTD-based task management system, providing proactive help throughout your day.
|
||||
|
||||
## Features
|
||||
|
||||
### 🤖 Intelligent Task Management
|
||||
- Natural language task entry via Discord or web interface
|
||||
- Automatic parsing of projects, contexts, priorities, and due dates
|
||||
- Smart task completion with timestamps
|
||||
- Context-aware task filtering
|
||||
|
||||
### 📅 Proactive Scheduling
|
||||
- **Morning Briefing** (8:00 AM): Today's calendar, priority tasks, due soon items
|
||||
- **Evening Summary** (8:00 PM): Accomplishments, tomorrow prep, reflection prompts
|
||||
- **Deadline Warnings**: Hourly checks for overdue and upcoming deadlines
|
||||
- **Waiting List Follow-ups**: Weekly reminders (Mondays 9 AM)
|
||||
- **Git Sync**: Automatic sync every 15 minutes
|
||||
|
||||
### 💬 Multiple Interfaces
|
||||
- **Discord Bot**: Quick access via mobile or desktop Discord
|
||||
- **Web Dashboard**: Rich visual interface for detailed management
|
||||
- **CLI Mode**: Testing and local development
|
||||
|
||||
### 🧠 Smart Features
|
||||
- Context inference from time and calendar
|
||||
- Project progress tracking
|
||||
- Goal alignment (with telos.md integration)
|
||||
- Automatic git commits for all changes
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Backend**: Python 3.11+, FastAPI, Discord.py
|
||||
- **AI**: Claude Sonnet 4.5 via LiteLLM proxy
|
||||
- **Frontend**: Vanilla CSS, HTMX, Jinja2 templates
|
||||
- **Storage**: Git repository (todo.txt, calendar.txt, projects.txt)
|
||||
- **Deployment**: Docker + Kubernetes (k3s)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **Python 3.11+**
|
||||
2. **Git**
|
||||
3. **LiteLLM Endpoint** - Running instance with Claude API access
|
||||
4. **Discord Bot** (optional) - For Discord integration
|
||||
5. **myorg Repository** - Your GTD data repository
|
||||
|
||||
### 1. Clone and Install
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone <repository-url>
|
||||
cd myorg-assistant
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
# Copy example configuration
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` with your configuration:
|
||||
|
||||
```bash
|
||||
# LiteLLM Configuration (REQUIRED)
|
||||
LITELLM_ENDPOINT=http://localhost:4000 # Your LiteLLM proxy URL
|
||||
LITELLM_API_KEY=your-api-key
|
||||
LITELLM_MODEL=claude-sonnet-4-5
|
||||
|
||||
# Myorg Repository (REQUIRED)
|
||||
MYORG_REPO_PATH=/path/to/your/myorg # Local path to your myorg repo
|
||||
GIT_REPO_URL=https://github.com/yourusername/myorg.git
|
||||
GIT_USERNAME=yourusername
|
||||
GIT_TOKEN=ghp_your_github_token
|
||||
GIT_BRANCH=main
|
||||
|
||||
# Discord Bot (REQUIRED for Discord features)
|
||||
DISCORD_BOT_TOKEN=your.discord.bot.token
|
||||
DISCORD_CHANNEL_ID=123456789012345678
|
||||
|
||||
# Web Interface (OPTIONAL)
|
||||
WEB_HOST=0.0.0.0
|
||||
WEB_PORT=8000
|
||||
WEB_SECRET_KEY=generate-random-secret-key-here
|
||||
WEB_PASSWORD=optional-password-for-basic-auth
|
||||
|
||||
# Scheduling
|
||||
TIMEZONE=Europe/Madrid # Your timezone
|
||||
```
|
||||
|
||||
### 3. Set Up Your myorg Repository
|
||||
|
||||
The assistant expects a myorg repository with these files:
|
||||
|
||||
```
|
||||
myorg/
|
||||
├── todo.txt # Tasks in todo.txt format
|
||||
├── calendar.txt # Calendar events
|
||||
├── projects.txt # Active projects
|
||||
├── waiting.txt # Items waiting on others
|
||||
├── telos.md # Life vision and missions
|
||||
└── goals/ # Quarterly goals (optional)
|
||||
```
|
||||
|
||||
If you don't have one, you can use the test repository:
|
||||
|
||||
```bash
|
||||
# For testing, point to the included test data
|
||||
export MYORG_REPO_PATH=./tests/fixtures/test_myorg
|
||||
```
|
||||
|
||||
### 4. Run Locally
|
||||
|
||||
#### CLI Mode (Testing)
|
||||
|
||||
```bash
|
||||
python -m src.main cli
|
||||
```
|
||||
|
||||
Example interactions:
|
||||
- "List files in the repository"
|
||||
- "Add task: Test the assistant with context computer-deep"
|
||||
- "Show all active tasks"
|
||||
- "What's on my calendar today?"
|
||||
|
||||
#### Discord Bot Mode
|
||||
|
||||
```bash
|
||||
python -m src.main bot
|
||||
```
|
||||
|
||||
The bot will connect to Discord and respond to mentions or DMs.
|
||||
|
||||
#### Web Interface Mode
|
||||
|
||||
```bash
|
||||
python -m src.main web
|
||||
```
|
||||
|
||||
Then visit: `http://localhost:8000`
|
||||
|
||||
## Discord Bot Setup
|
||||
|
||||
### Create Discord Bot
|
||||
|
||||
1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
|
||||
2. Click "New Application" → Give it a name
|
||||
3. Go to "Bot" section → Click "Add Bot"
|
||||
4. Under "Privileged Gateway Intents", enable:
|
||||
- ✅ Message Content Intent
|
||||
- ✅ Server Members Intent
|
||||
5. Click "Reset Token" → Save this token to `.env` as `DISCORD_BOT_TOKEN`
|
||||
6. Go to "OAuth2" → "URL Generator"
|
||||
- Scopes: `bot`, `applications.commands`
|
||||
- Bot Permissions: `Send Messages`, `Read Messages/View Channels`, `Read Message History`
|
||||
7. Copy the generated URL and invite bot to your server
|
||||
|
||||
### Discord Commands
|
||||
|
||||
Once the bot is running:
|
||||
|
||||
**Natural Conversation:**
|
||||
```
|
||||
@MyOrgBot Add task: Buy groceries tomorrow @recados
|
||||
@MyOrgBot What should I work on? I have 2 hours @computer-deep
|
||||
@MyOrgBot Show my calendar for today
|
||||
```
|
||||
|
||||
**Commands:**
|
||||
- `/help` - Show all commands
|
||||
- `/briefing` - Get daily briefing
|
||||
- `/add [task]` - Quick task addition
|
||||
- `/tasks [filter]` - Show tasks (optionally filtered)
|
||||
- `/today` - Today's schedule and priority tasks
|
||||
- `/context [context]` - Set current context
|
||||
- `/reset` - Clear conversation history
|
||||
|
||||
## Web Interface
|
||||
|
||||
The web interface provides:
|
||||
|
||||
### Dashboard (`/`)
|
||||
- Stats overview (events, tasks, projects)
|
||||
- Today's schedule
|
||||
- Priority tasks
|
||||
- Due soon items
|
||||
- Active projects
|
||||
|
||||
### Chat (`/chat`)
|
||||
- Full conversation with the agent
|
||||
- HTMX-powered dynamic updates
|
||||
- Natural language interaction
|
||||
|
||||
### Tasks (`/tasks`)
|
||||
- Complete task list
|
||||
- Filter by project, context, priority
|
||||
- Mark tasks complete
|
||||
- Add new tasks
|
||||
|
||||
### Calendar (`/calendar`)
|
||||
- Today's events
|
||||
- Upcoming week view
|
||||
- All-day and timed events
|
||||
|
||||
### Projects (`/projects`)
|
||||
- All projects by status
|
||||
- Task count per project
|
||||
- Filter by status (active, waiting, someday, completed)
|
||||
|
||||
## Kubernetes Deployment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- k3s cluster running
|
||||
- `kubectl` configured
|
||||
- Docker for building images
|
||||
|
||||
### 1. Build and Load Image
|
||||
|
||||
```bash
|
||||
# Build image
|
||||
docker build -t myorg-assistant:latest .
|
||||
|
||||
# Load into k3s
|
||||
docker save myorg-assistant:latest | sudo k3s ctr images import -
|
||||
```
|
||||
|
||||
### 2. Create Secret
|
||||
|
||||
```bash
|
||||
cd k8s
|
||||
cp secret.yaml.example secret.yaml
|
||||
# Edit secret.yaml with your actual credentials
|
||||
kubectl apply -f secret.yaml
|
||||
```
|
||||
|
||||
**Important:** Never commit `secret.yaml` to version control!
|
||||
|
||||
### 3. Deploy
|
||||
|
||||
```bash
|
||||
# Automated deployment (recommended)
|
||||
./deploy.sh
|
||||
|
||||
# Or manually
|
||||
kubectl apply -f configmap.yaml
|
||||
kubectl apply -f pvc.yaml
|
||||
kubectl apply -f service.yaml
|
||||
kubectl apply -f deployment.yaml
|
||||
kubectl apply -f cronjobs/
|
||||
kubectl apply -f ingress.yaml # Optional: for external access
|
||||
```
|
||||
|
||||
### 4. Verify Deployment
|
||||
|
||||
```bash
|
||||
# Check pod status
|
||||
kubectl get pods -l app=myorg-assistant
|
||||
|
||||
# View logs
|
||||
kubectl logs -f deployment/myorg-assistant
|
||||
|
||||
# Check CronJobs
|
||||
kubectl get cronjobs
|
||||
|
||||
# Expected output:
|
||||
# myorg-morning-briefing 0 8 * * * ...
|
||||
# myorg-evening-summary 0 20 * * * ...
|
||||
# myorg-deadline-checker 0 * * * * ...
|
||||
# myorg-git-sync */15 * * * * ...
|
||||
# myorg-waiting-followup 0 9 * * 1 ...
|
||||
```
|
||||
|
||||
### 5. Access Web Interface
|
||||
|
||||
**Internal Access (within cluster):**
|
||||
```
|
||||
http://myorg-assistant-service.default.svc.cluster.local:8000
|
||||
```
|
||||
|
||||
**External Access (via Ingress):**
|
||||
1. Edit `k8s/ingress.yaml` with your domain
|
||||
2. Apply: `kubectl apply -f ingress.yaml`
|
||||
3. Access: `https://myorg.yourdomain.com`
|
||||
|
||||
## Scheduled Jobs
|
||||
|
||||
The system runs these automated jobs:
|
||||
|
||||
| Job | Schedule | Description |
|
||||
|-----|----------|-------------|
|
||||
| Morning Briefing | Daily 8:00 AM | Calendar + priority tasks + due soon |
|
||||
| Evening Summary | Daily 8:00 PM | Completed tasks + tomorrow prep |
|
||||
| Deadline Checker | Every hour | Warns about overdue/upcoming deadlines |
|
||||
| Git Sync | Every 15 min | Pull/push repository changes |
|
||||
| Waiting Follow-up | Mon 9:00 AM | Review waiting list items |
|
||||
|
||||
All times use the timezone configured in `TIMEZONE` environment variable.
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `LITELLM_ENDPOINT` | Yes | - | LiteLLM proxy URL |
|
||||
| `LITELLM_API_KEY` | Yes | - | API key for LiteLLM |
|
||||
| `LITELLM_MODEL` | No | claude-sonnet-4-5 | Model name |
|
||||
| `MYORG_REPO_PATH` | Yes | /data/myorg | Path to myorg repository |
|
||||
| `GIT_REPO_URL` | Yes | - | Git repository URL |
|
||||
| `GIT_USERNAME` | Yes | - | Git username |
|
||||
| `GIT_TOKEN` | Yes | - | Git personal access token |
|
||||
| `GIT_BRANCH` | No | main | Git branch to use |
|
||||
| `DISCORD_BOT_TOKEN` | Yes* | - | Discord bot token (*for Discord) |
|
||||
| `DISCORD_CHANNEL_ID` | Yes* | - | Default Discord channel ID |
|
||||
| `WEB_HOST` | No | 0.0.0.0 | Web server host |
|
||||
| `WEB_PORT` | No | 8000 | Web server port |
|
||||
| `WEB_SECRET_KEY` | Yes** | - | Secret for sessions (**for web) |
|
||||
| `WEB_PASSWORD` | No | - | Password for basic auth (optional) |
|
||||
| `TIMEZONE` | No | Europe/Madrid | Timezone for schedules |
|
||||
|
||||
### File Formats
|
||||
|
||||
**todo.txt Format:**
|
||||
```
|
||||
(A) 2026-01-31 Write blog post +project @context due:2026-02-15
|
||||
x 2026-01-30 Completed task +project
|
||||
```
|
||||
|
||||
**calendar.txt Format:**
|
||||
```
|
||||
2026-02-01 09:00 Team meeting @telefon +work
|
||||
2026-02-15 Birthday party @personal
|
||||
```
|
||||
|
||||
**projects.txt Format:**
|
||||
```
|
||||
+project-name Description [active] @context goal:q1-2026 due:2026-02-28
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Bot not responding in Discord:**
|
||||
- Check bot is online: `kubectl logs -f deployment/myorg-assistant`
|
||||
- Verify Discord token in secret
|
||||
- Ensure bot has proper permissions in server
|
||||
- Check bot was mentioned or is receiving DMs
|
||||
|
||||
**LiteLLM connection failed:**
|
||||
- Verify `LITELLM_ENDPOINT` is correct
|
||||
- Check LiteLLM service is running: `kubectl get svc litellm-service`
|
||||
- Test API key is valid
|
||||
|
||||
**Git sync errors:**
|
||||
- Check git credentials in secret
|
||||
- Verify repository URL is accessible
|
||||
- Ensure PAT has repo permissions
|
||||
- Check logs: `kubectl logs job/myorg-git-sync-xxxxx`
|
||||
|
||||
**Web interface not accessible:**
|
||||
- Check pod is running: `kubectl get pods`
|
||||
- Verify service: `kubectl get svc myorg-assistant-service`
|
||||
- For external access, check ingress: `kubectl get ingress`
|
||||
|
||||
### Logs and Debugging
|
||||
|
||||
```bash
|
||||
# Main application logs
|
||||
kubectl logs -f deployment/myorg-assistant
|
||||
|
||||
# Specific CronJob logs
|
||||
kubectl logs job/myorg-morning-briefing-xxxxx
|
||||
|
||||
# Get into pod shell
|
||||
POD=$(kubectl get pods -l app=myorg-assistant -o name | head -1)
|
||||
kubectl exec -it $POD -- /bin/bash
|
||||
|
||||
# Inside pod:
|
||||
cd /data/myorg
|
||||
git status
|
||||
ls -la
|
||||
cat todo.txt
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_todo_parser.py
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=src tests/
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── agent/ # Agent orchestration
|
||||
│ ├── core.py # MyOrgAgent class
|
||||
│ └── prompts.py # System prompts
|
||||
├── tools/ # Agent tools
|
||||
│ ├── file_ops.py # File operations
|
||||
│ ├── task_ops.py # Task management
|
||||
│ └── git_ops.py # Git operations
|
||||
├── parsers/ # Format parsers
|
||||
│ ├── todo_parser.py
|
||||
│ ├── calendar_parser.py
|
||||
│ └── project_parser.py
|
||||
├── api/ # Web interface
|
||||
│ ├── app.py # FastAPI app
|
||||
│ └── routes/ # API routes
|
||||
├── bot/ # Discord bot
|
||||
│ ├── discord_bot.py
|
||||
│ └── formatters.py
|
||||
├── scheduler/ # Scheduled jobs
|
||||
│ ├── briefings.py # Briefing generators
|
||||
│ └── jobs.py # Job runners
|
||||
└── utils/ # Utilities
|
||||
└── context.py # Context inference
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- [DEPLOYMENT.md](DEPLOYMENT.md) - Detailed deployment guide
|
||||
- [project-plan.md](project-plan.md) - Full vision and architecture
|
||||
- [implementation-plan.md](implementation-plan.md) - Development phases
|
||||
- [todo.md](todo.md) - Implementation progress
|
||||
|
||||
## Status
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Status**: Production Ready ✅
|
||||
**Completion**: 83% (5 of 6 phases complete)
|
||||
|
||||
### Completed Features
|
||||
- ✅ Phase 0: Project Setup & Foundation
|
||||
- ✅ Phase 1: Core Agent with File Tools
|
||||
- ✅ Phase 2: Discord Bot Integration
|
||||
- ✅ Phase 3: Scheduled Briefings & Reminders
|
||||
- ✅ Phase 4: Web Interface
|
||||
|
||||
### Optional Enhancements
|
||||
- ⏳ Phase 5: Advanced Intelligence (goal tracking, analytics)
|
||||
- ⏳ Phase 6: Polish & Optimization (caching, monitoring)
|
||||
|
||||
The system is fully functional and ready for daily use!
|
||||
|
||||
## Contributing
|
||||
|
||||
This is a personal project, but suggestions and improvements are welcome via issues.
|
||||
|
||||
## License
|
||||
|
||||
Private project for personal use.
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2026-01-31
|
||||
**Last Updated**: 2026-01-31
|
||||
**Author**: Built with Claude Sonnet 4.5
|
||||
Reference in New Issue
Block a user