myorg-assistant/README.md

# 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