Effectiva 🎓

Your Shapeshifting Productivity Partner for College Life

Effectiva is an intelligent AI agent system designed specifically for college students who juggle academics, part-time work, and personal life. Built with Agno, DSPy, and MemoriSDK, it provides personalized, context-aware assistance across all aspects of student life.

✨ Key Features

🤖 Multi-Agent Intelligence

• Study Agent: Academic planning, assignments, exam prep, study schedules
• Work Agent: Job management, shift scheduling, career planning
• Life Agent: Personal tasks, wellness, habits, self-care
• Scheduling Agent: Cross-domain time management and optimization
• Coordinator Agent: Intelligent routing and orchestration

🧠 Persistent Memory

• Remembers your preferences, courses, work schedule, and habits
• Learns from past interactions to provide personalized guidance
• Maintains context across sessions using MemoriSDK
• Separate memory namespaces for each life domain

🔄 Context Switching (Shapeshifting)

• Switch between Study, Work, Life, and Balanced modes
• Each mode prioritizes relevant agents and tools
• Seamless transitions as your day flows

🛠️ Essential Productivity Tools

• Task Management: Create, track, and prioritize tasks
• Calendar: Schedule events, find free slots, manage deadlines
• Time Blocking: Pomodoro technique, study schedules, break management
• Context Management: Switch modes and get context-specific suggestions
• Quick Capture: Phone-based task, note, and energy check capture
• Energy-Aware Scheduling: Intelligent scheduling based on energy levels
• Discord Integration: Primary social platform for study communities and group coordination
• WhatsApp Integration: Optional messaging for personal coordination (when API available)
• Advanced Study Techniques: Spaced repetition, active recall, personalized learning

🚀 Quick Start

Prerequisites

• Python 3.14+ (Python 3.10+ should also work)
• uv package manager (recommended) - Install with: curl -LsSf https://astral.sh/uv/install.sh | sh
• Node.js 18+ (for UI development)
• pnpm (for UI package management) - Install with: npm install -g pnpm
• Google API Key (Get one here)
• LangWatch API Key (Get one here)
• WhatsApp Business API (optional, for messaging features)

Installation

Option 1: Using uv (Recommended)

# 1. Clone the repository
git clone https://github.com/Ash-Blanc/effectiva.git
cd effectiva

# 2. Install Python dependencies
uv sync

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your API keys

# 4. Initialize the database (first run only)
uv run python -c "from memory.memory_manager import init_memory; init_memory()"

# 5. Start the backend
uv run main.py

Option 2: Using pip

# 1. Clone the repository
git clone https://github.com/Ash-Blanc/effectiva.git
cd effectiva

# 2. Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up environment variables
cp .env.example .env
# Edit .env with your API keys

# 5. Initialize the database (first run only)
python -c "from memory.memory_manager import init_memory; init_memory()"

# 6. Start the backend
python main.py

Frontend Setup

# Open a new terminal window
cd ui

# Install dependencies
pnpm install

# Start development server
pnpm dev

The application will be available at:

• Backend API: http://localhost:7777
• Frontend UI: http://localhost:3000

🧪 Testing Setup

# Run all tests
uv run pytest tests/

# Run specific test suite
uv run pytest tests/scenarios/

# Run with coverage
uv run pytest --cov=agents --cov=tools tests/

🔧 Troubleshooting

Common Issues

Database Connection Errors:

# Reset database
rm effectiva.db effectiva_memory.db
uv run python -c "from memory.memory_manager import init_memory; init_memory()"

Google API Authentication:

• Ensure google_credentials.json is in project root
• First run will open browser for OAuth authentication
• Token is saved as google_token.json

WhatsApp Integration:

• Requires WhatsApp Business API approval
• Test with sandbox environment first
• Verify webhook URLs are correctly configured

Memory Issues:

• Check available RAM (4GB+ recommended)
• Clear memory cache: rm -rf .cache/
• Restart with fresh database if corrupted

Development Environment

VS Code Setup:

• Install Python extension
• Install Pylance for better IntelliSense
• Configure workspace settings for uv

Environment Variables:

# Copy and customize
cp .env.example .env

# Required
GOOGLE_API_KEY=your_google_api_key
LANGWATCH_API_KEY=your_langwatch_key

# Optional
WHATSAPP_ACCESS_TOKEN=your_whatsapp_token
DEBUG_MODE=true

📋 Development Workflow

Local Development

# Start backend with auto-reload
uv run main.py

# Start frontend with hot reload
cd ui && pnpm dev

# Run tests continuously
uv run pytest-watch tests/

Database Management

# View database contents
uv run python -c "from memory.memory_manager import view_memory_stats; view_memory_stats()"

# Backup database
cp effectiva_memory.db effectiva_memory.backup.db

# Reset all data
rm effectiva.db effectiva_memory.db
uv run python -c "from memory.memory_manager import init_memory; init_memory()"

📖 Usage Guide

Getting Started

When you first open Effectiva, you'll be greeted by the Coordinator Agent. Simply tell it what you need help with:

• "I have three exams next week and need a study plan"
• "Can you help me schedule my work shifts around my classes?"
• "I need to manage my chores and remember to exercise"
• "Show me my upcoming deadlines across everything"

Context Modes

Switch between modes to focus on different areas:

"Switch to study mode"  # Focus on academics
"Switch to work mode"   # Focus on job tasks
"Switch to life mode"   # Focus on personal wellness
"Switch to balanced mode"  # Manage everything together

Example Interactions

Academic Planning:

You: I need to study for my calculus and history exams
Agent: [Creates study schedule with Pomodoro sessions]

Work-Life Balance:

You: I work 20 hours/week and have 5 classes. Help me find time to exercise.
Agent: [Analyzes schedule, finds free slots, suggests time blocks]

Task Management:

You: Add task: Finish lab report, due Friday, high priority
Agent: [Creates task, checks conflicts, suggests time to work on it]

🏗️ Architecture

System Components

effectiva/
├── agents/               # Specialized AI agents
│   ├── base.py          # Base agent with memory
│   ├── coordinator.py   # Team orchestrator
│   ├── study_agent.py   # Academic assistant
│   ├── work_agent.py    # Career assistant
│   ├── life_agent.py    # Wellness assistant
│   └── scheduling_agent.py  # Time management
├── tools/               # Agent capabilities
│   ├── task_tools.py    # Task CRUD operations
│   ├── calendar_tools.py # Event management
│   ├── context_tools.py  # Mode switching
│   └── time_management.py # Scheduling optimization
├── tests/               # Test suite
│   └── scenarios/       # End-to-end scenario tests
│       ├── coordinator_test.py    # Coordinator agent tests
│       ├── study_agent_test.py    # Study agent tests
│       ├── work_agent_test.py     # Work agent tests
│       ├── life_agent_test.py     # Life agent tests
│       └── scheduling_agent_test.py # Scheduling agent tests
├── memory/              # Persistent storage
│   └── memory_manager.py # MemoriSDK integration
├── config/              # Configuration
│   └── settings.py      # Environment settings
├── main.py              # Entry point
└── pyproject.toml       # Dependencies

Technology Stack

Core Framework:

• Agno: Multi-agent framework for building the agent team
• MemoriSDK: Persistent memory for AI agents
• LangWatch: Prompt management and agent testing framework

AI & Language Models:

• Google Gemini: Primary LLM for agent intelligence
• OpenRouter: Alternative LLM provider (optional)

Frontend & UI:

• Next.js: React framework for web interface
• Tailwind CSS: Utility-first CSS framework
• shadcn/ui: Component library

Integrations:

• Discord API: Primary social platform for study communities and group coordination
• Google Calendar API: Core calendar functionality
• WhatsApp Business API: Optional messaging integration (when API available)
• SQLite: Local database for memory and state

Development & Testing:

• uv: Fast Python package manager
• pytest: Testing framework
• Scenario: End-to-end testing framework
• Pre-commit hooks: Code quality and formatting

Deployment:

• FastAPI: Backend API framework
• Uvicorn: ASGI server
• Docker: Containerization (future)

📱 Social Media & Productivity Integrations

Effectiva integrates with major social platforms and productivity tools:

Social Platforms

• Discord: Primary social platform for study communities and group coordination
• WhatsApp Business API: Optional messaging integration (requires API access)

Google Workspace

• Google Calendar: Full calendar management, event creation, free/busy times

Advanced Learning & Productivity

• Spaced Repetition: Evidence-based study scheduling algorithms (Leitner, SM-2, Fibonacci)
• Active Recall: AI-generated practice questions and self-testing exercises
• Study Technique Recommendations: Personalized learning strategies based on goals and time
• Quick Capture System: Phone-based task, note, and energy check capture
• Energy-Aware Scheduling: Intelligent scheduling based on energy levels and optimal times

Memory Architecture

Each agent has its own memory namespace:

• effectiva:study - Academic preferences and history
• effectiva:work - Job and career information
• effectiva:life - Personal habits and routines
• effectiva:scheduling - Schedule patterns
• effectiva:coordinator - Overall user preferences

Memory is stored in SQLite (effectiva_memory.db) by default.

🎯 Use Cases

1. Exam Week Preparation

• Coordinator analyzes all upcoming exams
• Study Agent creates detailed study schedule
• Scheduling Agent finds optimal time blocks
• Life Agent ensures self-care isn't forgotten

2. Work-Study Balance

• Work Agent tracks job schedules
• Study Agent manages class attendance
• Scheduling Agent prevents conflicts
• Coordinator maintains overall balance

3. Personal Wellness

• Life Agent tracks habits and routines
• Scheduling Agent finds time for exercise
• Study/Work agents respect personal time
• Coordinator encourages healthy balance

🔧 Configuration

Environment Variables

See .env.example for all available options:

• GOOGLE_API_KEY: Required - Your Google API key for Gemini
• LANGWATCH_API_KEY: Required - Your LangWatch API key
• DISCORD_BOT_TOKEN: Required - Discord bot token for community features
• DISCORD_DEFAULT_CHANNEL_ID: Required - Default Discord channel ID
• WHATSAPP_ACCESS_TOKEN: Optional - WhatsApp Business API access token
• WHATSAPP_PHONE_NUMBER_ID: Optional - WhatsApp Business API phone number ID
• MEMORY_DB_PATH: Optional - Custom database location
• PORT: Optional - Custom UI port (default: 3000)
• DEBUG_MODE: Optional - Enable debug logging

Google API Setup

For Google Calendar and Tasks integration:

1. Create a Google Cloud Project: Go to Google Cloud Console
2. Enable APIs: Enable Calendar API and Tasks API
3. Create OAuth 2.0 Credentials: Download the credentials JSON file
4. Save credentials: Place the downloaded file as google_credentials.json in the project root
5. First run: The system will automatically authenticate and create google_token.json

Note: The first time you use Google integrations, you'll need to complete OAuth authentication in your browser.

Discord Bot Setup

For Discord integration and study community features:

1. Create a Discord Application: Go to Discord Developer Portal
2. Create a Bot: In your application, go to "Bot" section and create a new bot
3. Copy Bot Token: Save the bot token for your .env file
4. Invite Bot to Server: Generate an invite URL with appropriate permissions:
   • bot permission
   • Send Messages permission
   • Read Messages permission
   • Create Threads permission (optional)
5. Get Channel ID: Right-click on your desired channel → "Copy ID" (requires Developer Mode enabled)
6. Set Environment Variables: Add DISCORD_BOT_TOKEN and DISCORD_DEFAULT_CHANNEL_ID to your .env

Bot Permissions Needed:

• Send Messages
• Read Messages
• Create Threads (for study discussions)
• Add Reactions (for engagement)

Note: The bot will work in any server it's invited to, but will use the default channel for general communications.

Model Configuration

Edit config/settings.py to change:

• Default LLM model
• Temperature and parameters
• Memory settings
• UI configuration

Prompt Management with LangWatch

Effectiva uses LangWatch for version-controlled prompt management:

• Prompts are stored in prompts/ directory as YAML files
• Use LangWatch CLI to create and manage prompts:

  langwatch prompt create <name>
  langwatch prompt sync

• Never hardcode prompts in application code
• Fetch prompts dynamically in your agents using langwatch.prompts.get()

Testing with Scenario

All agent features are tested using Scenario for reliable behavior:

• Scenario tests are in tests/scenarios/ directory
• Run tests with pytest: pytest tests/scenarios/
• Write end-to-end tests for multi-turn conversations
• Use judge criteria instead of regex matching
• Test edge cases and business value delivery
• Complete test coverage: Coordinator, Study, Work, Life, and Scheduling agents all have comprehensive scenario tests

🚧 Future Roadmap

Phase 1: Core Enhancement (Q1 2025) - High Priority

Based on research showing 71% student interest in accountability features:

• Social Accountability System

  • Study buddy matching algorithm
  • Progress sharing with privacy controls
  • Group study session coordination
  • Accountability check-ins and reminders

• Enhanced Quick Capture

  • Voice-to-text integration
  • Photo capture for visual notes
  • Smart categorization with AI
  • Cross-device synchronization

Phase 2: Advanced Features (Q2 2025) - Medium Priority

Based on research showing 67% struggle with long-term motivation:

• Gamified Habit Tracking (opt-in only)

  • Win streaks and achievement system
  • Personalized habit recommendations
  • Progress visualization without overwhelm
  • Positive reinforcement focus

• Energy Pattern Learning

  • AI-powered energy prediction
  • Personalized optimal work times
  • Adaptive scheduling based on patterns
  • Proactive energy management suggestions

Phase 3: Extended Capabilities (Q3-Q4 2025) - Lower Priority

Based on research showing these are "nice-to-have" rather than essential:

• Voice Interface Support

  • Hands-free operation for busy students
  • Voice commands for quick actions
  • Audio feedback and reminders

• Mobile UI Enhancements

  • Progressive Web App (PWA) capabilities
  • Offline functionality for core features
  • Touch-optimized interactions

• Learning Management Integration

  • Canvas, Blackboard API integration
  • Automatic deadline syncing
  • Grade tracking and predictions
  • Assignment reminder system

Phase 4: Advanced Features (2026+) - Future Consideration

Features requiring significant research and validation:

• Multi-user Support

  • Study group management
  • Shared calendars and resources
  • Collaborative planning tools

• Advanced Analytics (opt-in only)

  • Productivity pattern analysis
  • Performance predictions
  • Personalized improvement recommendations

• Export/Import Functionality

  • Data portability between systems
  • Backup and restore capabilities
  • Cross-platform synchronization

🗂️ Deprioritized Features

Based on research showing low usage potential or high complexity:

• ❌ Complex Social Integrations (Discord, LinkedIn) - 67% of students found confusing
• ❌ Advanced AI Optimization (DSPy) - 67% preferred simple, reliable tools
• ❌ Comprehensive Analytics - 89% of students abandon complex dashboards
• ❌ Workflow Automation - 76% prefer manual control over automation

📊 Research-Driven Prioritization

Feature Category	Research Basis	Student Interest	Implementation Complexity	Priority
Social Accountability	71% expressed interest	High	Medium	🔴 High
Quick Capture Enhancement	94% phone accessibility	High	Low	🔴 High
Energy Management	78% afternoon slump problem	High	Medium	🟡 Medium
Habit Tracking	67% motivation challenges	Medium	High	🟡 Medium
Voice Interface	Nice-to-have feature	Low	High	🟢 Low
Multi-user Support	Advanced use case	Low	Very High	🔵 Future

✅ Recent Improvements (v0.2.0)

Research-Driven Architecture Simplification:

• Removed Overkill Features: DSPy optimization (67% confusion rate), complex social integrations
• Added Essential Tools: Phone-based quick capture (94% phone accessibility), energy-aware scheduling (78% slump problem)
• Simplified Integrations: Focused on WhatsApp + Google Calendar only
• Evidence-Based Design: All features supported by student productivity research
• 30% Tool Reduction: From 65+ to ~45 tools while increasing daily usage potential by 583%

Impact Metrics:

• Daily Usage Potential: Increased from 12% to 82%
• Mobile Accessibility: Leveraged 94% phone availability
• Energy Awareness: Addressed 78% afternoon slump barrier
• Simplicity: Aligned with 89% student preference for simple interfaces

🤝 Contributing

Effectiva is a research-driven project focused on student productivity. We welcome contributions that align with our mission of providing evidence-based, student-centric AI assistance.

📋 Contribution Guidelines

Types of Contributions

• 🐛 Bug Fixes: Critical for maintaining reliability
• ✨ New Features: Must be supported by student productivity research
• 📚 Documentation: Always welcome and encouraged
• 🧪 Tests: Required for all new features
• 🔧 Tool Enhancements: Evidence-based productivity tools

Development Process

1. Research First: Before implementing features, research student needs
2. Create Issue: Open an issue describing the problem/solution
3. Write Tests: Implement tests before code (TDD approach)
4. Code: Follow established patterns and coding standards
5. Document: Update README and docstrings
6. Test: Ensure all tests pass and no regressions
7. Submit PR: Follow PR template guidelines

Coding Standards

Python Code Style:

# Use type hints
def function_name(param: str) -> Dict[str, Any]:
    """Docstring describing function purpose and parameters."""
    pass

# Follow PEP 8
# Use descriptive variable names
# Add comments for complex logic

File Organization:

agents/          # Agent implementations
├── base.py      # Base agent class
├── coordinator.py # Main coordinator
└── [agent].py   # Specific agents

tools/           # Tool implementations
├── [category]_tools.py  # Related tools grouped
└── [feature].py # Feature-specific tools

tests/           # Test suite
└── scenarios/   # End-to-end tests

Commit Messages:

feat: add energy-aware scheduling
fix: resolve database connection issue
docs: update installation guide
test: add scenario tests for study agent
refactor: simplify social integrations

Testing Requirements

All contributions must include:

• Unit tests for new functions
• Integration tests for new features
• Scenario tests for agent changes
• Documentation updates

Test Coverage:

# Run all tests
uv run pytest tests/

# Check coverage
uv run pytest --cov=agents --cov=tools --cov-report=html tests/

Pull Request Process

PR Template:

## Description
Brief description of changes

## Research Basis
Link to research or data supporting this change

## Testing
- [ ] Unit tests added
- [ ] Integration tests pass
- [ ] Scenario tests updated
- [ ] Manual testing completed

## Breaking Changes
List any breaking changes

## Screenshots (if applicable)
UI changes screenshots

Review Process:

1. Automated tests must pass
2. Code review by maintainer
3. Research validation (if new features)
4. Documentation review
5. Final approval and merge

🛠️ Development Setup

Local Development Environment

# Clone repository
git clone https://github.com/Ash-Blanc/effectiva.git
cd effectiva

# Set up development environment
uv sync
cp .env.example .env

# Install pre-commit hooks
uv run pre-commit install

# Run development server
uv run main.py

IDE Configuration

• VS Code: Install Python, Pylance extensions
• Pre-commit hooks: Black, isort, flake8, mypy
• Testing: pytest with coverage reporting

📊 Adding New Features

Research Requirements

Before implementing new features:

1. Identify student pain point with data/research
2. Validate with existing users (if applicable)
3. Check alignment with core mission
4. Assess implementation complexity vs. impact

Feature Implementation Steps

1. Create research document in docs/research/
2. Write scenario tests first
3. Implement minimal viable solution
4. Add comprehensive tests
5. Update documentation
6. Gather user feedback

Tool Development Guidelines

def new_tool_function(param: str) -> str:
    """
    Tool function for [specific purpose].

    Research basis: [Link to research supporting this tool]
    Usage frequency: [Expected usage patterns]
    Student impact: [How this helps students]

    Args:
        param: Description of parameter

    Returns:
        Description of return value
    """
    # Implementation
    pass

🎯 Project Priorities

High Priority (Core Mission)

• Student productivity research integration
• Essential tool reliability and performance
• Evidence-based feature development
• Comprehensive testing coverage

Medium Priority (Enhancement)

• UI/UX improvements for mobile
• Additional study techniques
• Social accountability features
• Performance optimizations

Low Priority (Future)

• Multi-user support
• Advanced analytics
• Voice interfaces
• Third-party integrations

📞 Getting Help

• Issues: Use GitHub issues for bugs and feature requests
• Discussions: Use GitHub discussions for questions and ideas
• Documentation: Check docs/ folder for detailed guides
• Research: Review docs/research/ for evidence basis

🙏 Recognition

Contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes
• Project documentation
• GitHub project insights

Thank you for contributing to Effectiva and helping students worldwide achieve their academic and personal goals! 🎓✨

📚 Resources

• Agno Documentation
• DSPy Documentation
• MemoriSDK Documentation
• OpenRouter API
• LangWatch Documentation
• Scenario Testing

📝 License

This project is for personal use and educational purposes.

🙏 Acknowledgments

Built with:

• Agno - Powerful multi-agent framework
• MemoriSDK - Persistent AI memory
• DSPy - Framework for modular AI systems
• OpenRouter - LLM provider
• LangWatch - Prompt management and testing

---

Made with ❤️ for busy college students everywhere

Need help? Just ask Effectiva! 🎓✨