Gegmara

Gegmara, planner that understands you.

Comment

Gegmara (გეგმარა) — In-Depth Project Overview

Executive Summary

Gegmara (გეგმარა) is a full-stack adaptive planning system that learns from your habits to optimize scheduling decisions. It ingests calendar data, tracks performance, learns task durations, detects conflicts, and provides proactive recommendations, while measuring weekly adherence via the Binary Goal Adherence Score (B-GAS). A demo dataset (user “Dan”) enables immediate evaluation of features without manual bootstrapping.

Goals & Philosophy

  • Adaptive Planning: Plans should evolve with your real behavior, not static assumptions.
  • Data-Driven Decisions: Use historical outcomes to inform future scheduling (duration, timing, adherence).
  • Proactive Guidance: Warn early (duration mismatches, conflicts), recommend alternatives, and auto-adjust when confident.
  • Lightweight & Explainable: Simple, transparent algorithms (EMA, thresholds) that are easy to reason about.

Architecture Overview

  • Backend: Django 6 + Django REST Framework (DRF), Token Auth, SQLite (dev)
  • Apps & Services:
    • planner/ — Models, serializers, views, URLs, signals, services
    • Services: BGASUpdateService, CalendarImportService, Duration recommendation logic
    • Management commands: populate_demo_user, process_bgas_daily, generate_weekly_stats
  • Frontend: Placeholder folder (frontend/) — API-first design ready for UI integration
  • Docs: POSTMAN_API_GUIDE.md, FEATURE_INVENTORY.md, and this PROJECT_OVERVIEW.md (Gegmara branding)

Data Model (Key Entities)

  • TaskCategory — Name, mental_demand_rating, estimated_duration_locked
  • Task — Title, description, start_time, end_time, is_completed, is_physical_load, category
  • PerformanceSlot — Per-task performance metrics (actual and estimated durations, sample_count)
  • CategoryPerformance — Learned per-category metrics (estimated duration EMA, duration sample count, B-GAS EMA)
  • ScheduleAdherenceRecord — Records completion adherence events
  • UserWeeklyStats — Persisted weekly analytics snapshots (completion, B-GAS, worst activity, duration accuracy)

Relationships:

  • User 1—* Task
  • TaskCategory 1—* Task
  • Task 1—* PerformanceSlot
  • User 1—* UserWeeklyStats
  • TaskCategory 1—* CategoryPerformance

Core Algorithms

1) Duration Learning (EMA)

  • Track actual_duration_minutes from completed tasks
  • For category-level learning:
    • estimated_duration_minutes_new = 0.8 * old + 0.2 * actual
    • Increment duration_sample_count
  • Confidence levels from duration_sample_count:
    • <3: Very Low, 3–5: Low, 6–10: Medium, 10+: High

2) Duration Warning & Override

  • On task creation, if allocated time < 80% of learned estimate and override_duration_warning != true:
    • Block request with 400 and duration_warning payload (includes recommended_duration, actual_available_time, confidence)
  • If override_duration_warning: true — allow creation (explicit user intent)

3) Auto-Duration Adjustment

  • If auto_adjust_duration: true and confidence ≥ Low (≥3 samples):
    • Extend end_time to match learned estimated_duration_minutes for the category/time slot

4) B-GAS (Binary Goal Adherence Score)

  • Per completion: +2; per non-completion: -2
  • EMA blending: new_bgas = 0.8 * old_bgas + 0.2 * latest_score
  • Updated instantly via post_save signals (completion), or via daily batch fallback

5) Weekly Statistics

  • Computed (on-demand) and stored (via command)
  • Metrics:
    • bgas_average, completion_rate, incomplete_rate
    • worst_activity (lowest performance category), worst_activity_incomplete
    • Duration metrics: avg_planned_duration_minutes, avg_estimated_duration_minutes, duration_accuracy_rate, tasks_with_estimates_count
  • Duration accuracy: % tasks where |planned - estimate| / estimate ≤ 20%

End-to-End Flows

A) Calendar Import → Tasks → Learning

  1. User uploads .ics (CalendarImportService)
  2. System parses events → creates Tasks with categories
  3. Initializes PerformanceSlot entries
  4. As tasks are completed, signals update:
    • ScheduleAdherenceRecord created
    • CategoryPerformance EMA duration & B-GAS updated
    • PerformanceSlot actual duration recorded

B) Task Creation with Smart Checks

  1. Client calls POST /tasks/ with start_time, end_time, category
  2. Serializer validates:
    • Conflict detection (overlaps) → 400 with details
    • Duration check (allocated vs. learned):
      • If mismatch >20% → 400 unless override_duration_warning: true
      • Otherwise, create
  3. Optional auto_adjust_duration: true — end time auto-extended using learned estimates

C) Duration Recommendation

  1. Client calls POST /duration-recommendation/ with category_id, start_time
  2. Service looks up learned estimates (category + time patterns)
  3. Returns recommended_duration_minutes, confidence, sample_count, message

D) Weekly Analytics

  1. GET /weekly-statistics/?weeks=N — compute live metrics
  2. GET /weekly-stats/ — retrieve persisted snapshots
  3. Use to monitor adherence, performance, and duration accuracy over time

API Surface (Highlights)

  • Auth: POST /auth/register, POST /auth/login
  • Calendar: POST /import-calendar, GET /import-status, DELETE /import-calendar/delete
  • Categories: GET/POST /categories, GET/PATCH /categories/{id}
  • Tasks: GET/POST /tasks, GET/PATCH/DELETE /tasks/{id}
  • Conflicts: POST /schedule-check
  • Duration: POST /duration-recommendation
  • Analytics: GET /recurring-task-suggestions, GET /weekly-statistics, GET /weekly-stats

See POSTMAN_API_GUIDE.md and postman_collection.json for request/response examples.

Demo Data (User: Dan)

  • Period: Sept 14 — Dec 28, 2025
  • Tasks: 668 total (≈466 completed, ≈202 future/incomplete)
  • Weekly Stats: 15 weeks persisted
  • Categories: Populated from import (Work, Personal, Deep Work, etc.)
  • Duration Samples: 466+ (robust learning across categories)

Use demo to test:

  • Conflict detection
  • Duration warning + override
  • Auto-adjustment
  • Duration recommendation
  • Weekly analytics

Setup & Running

Requirements

  • Python 3.10+
  • Django 6, DRF (see requirements.txt)

Commands

bash

From backend/DjangoPlanner

python manage.py migrate python manage.py populate_demo_user python manage.py generate_weekly_stats python manage.py runserver

Authentication

  • Login and capture token
  • Use Authorization: Token {token} for all endpoints

Testing & Validation

  • Postman collection updated and JSON-validated
  • Smoke tests via demo user confirm endpoints:
    • Conflict detection returns 409/400 appropriately
    • Duration recommendation returns estimates + confidence
    • Duration warnings block under-allocated tasks unless overridden
    • Auto-adjust extends end times based on learned duration
    • Weekly stats compute/persist correctly

Design Choices & Rationale

  • EMA over static averages — responsive to change, smooths noise
  • Threshold-based warnings — transparent decision rules (80%/20%)
  • Signals for consistency — guarantees learning updates on completion
  • Separate calculated vs stored stats — flexibility for real-time vs historical queries
  • Confidence gating for auto-adjust — avoid overfitting with limited samples

Extensibility & Future Work

  • Time-of-day specific duration models (slot-specific EMA)
  • Personalized REI weighting (mental vs physical load split)
  • Calendar writeback (auto-reschedule recommendations into calendar)
  • Notification system (Slack/Email) for conflicts and warnings
  • Celery/APScheduler for scheduled commands (daily/weekly tasks)
  • Multi-user collaboration (shared calendars, team metrics)

Quick Reference

  • Core learning: EMA (80% old, 20% new)
  • Duration warning threshold: 20%
  • Confidence levels: 3/5/10 samples
  • B-GAS: +2/-2, EMA blended
  • Weekly metrics: completion, incomplete, worst activity, duration accuracy

Files of Interest

  • planner/serializers.py — validation, smart fields, override/auto-adjust
  • planner/views.py — endpoints, helpful error messages
  • planner/services.py — BGAS updates, calendar duration sync
  • planner/management/commands/* — demo data & analytics
  • postman_collection.json — up-to-date API collection
  • POSTMAN_API_GUIDE.md — endpoint usage and examples
  • FEATURE_INVENTORY.md — feature checklist and architecture

Conclusion

This system turns raw schedules into adaptive plans using simple, explainable learning. It balances proactive guardrails (conflicts, warnings) with user control (override, auto-adjust), and provides clear analytics to measure adherence and improvement over time. With the demo user and comprehensive API docs, it’s ready for immediate exploration and frontend integration.

Share this project:

Updates

Submission history