Skip to main content

Aion

AI-powered calendar agent for Google Calendar.

Schedule, list, reschedule, and find free time — all from natural language in your terminal.

  aion > schedule gym tomorrow morning
  Finding optimal slot for 'gym'...
  Schedule 'gym' on February 19, 2026 at 07:00 for 60 min? [y/n]: y
  ✔ Created! 'gym' on 2026-02-19 at 07:00

Part of A.U.R.A (Autonomous Unified Reasoning Assistant).


Features

  • Natural language — "schedule dentist friday at 2pm for 45 min", "what's on tomorrow?"
  • Smart scheduling — ASP/Clingo constraint solver finds optimal slots avoiding conflicts
  • Google Calendar sync — reads and writes real events via Calendar API v3
  • Conflict detection — warns on overlaps, offers alternatives
  • User preferences — block time slots (lunch, sleep), set default morning/afternoon/evening
  • Timezone-aware — auto-detects your timezone from Google Calendar on login
  • Ollama NLU (optional) — local LLM fallback for complex commands, auto-installs on first run

Architecture

User Input
    │
    ▼
┌──────────────┐    ┌──────────────┐
│ Regex NLU    │───▶│ Ollama LLM   │  (optional fallback)
│ (intent.py)  │    │ (ollama.py)  │
└──────┬───────┘    └──────────────┘
       │
       ▼
┌──────────────┐    ┌──────────────┐
│ ASP Solver   │───▶│    Clingo    │  (constraint solving)
│ (solver.py)  │    │              │
└──────┬───────┘    └──────────────┘
       │
       ▼
┌──────────────┐
│ Google Cal   │  (httpx async)
│ (google_cal) │
└──────────────┘

Quick Start

pip install aion-agent
aion login
aion

That's it. aion login opens your browser for Google sign-in. Your timezone is auto-detected. No API keys or configuration needed.

On first run, Aion offers to install Ollama for smarter natural language understanding — this is optional.


Installation

From PyPI:

pip install aion-agent

From source:

git clone https://github.com/sheikhmunim/Aion.git
cd Aion
pip install -e .

Requires Python 3.10+.


Usage

Start the interactive CLI:

aion

Commands

Action Examples
Schedule schedule gym tomorrow morning, add meeting at 3pm for 90 min
List what's on today?, show my calendar this week, what tomorrow?
Delete cancel gym tomorrow, delete meeting
Update move gym to 3pm, reschedule meeting to friday
Free slots when am I free tomorrow?, free slots this week
Best time best time for a 2h study session
Preferences preferences — manage blocked times and defaults
Login/Logout login, logout
Help help
Quit quit or exit

Preferences

Block recurring time slots and set defaults:

aion > preferences
  ┌─────────────────────────────────────────────┐
  │ 1. Add a blocked time slot                  │
  │ 2. Remove a blocked slot                    │
  │ 3. Change default time preference           │
  │ 4. Back                                     │
  └─────────────────────────────────────────────┘

Blocked slots (e.g. lunch 12:00-13:00 on weekdays) are respected by the scheduler — it won't suggest times during those windows.


Configuration

Config lives at ~/.aion/config.json. All options can also be set via environment variables with AION_ prefix.

Key Env var Default Description
google_client_id AION_GOOGLE_CLIENT_ID Built-in OAuth client ID (override with your own if needed)
google_client_secret AION_GOOGLE_CLIENT_SECRET Built-in OAuth client secret
timezone AION_TIMEZONE UTC IANA timezone (auto-detected on login)
default_duration AION_DEFAULT_DURATION 60 Default event duration in minutes
ollama_url AION_OLLAMA_URL http://localhost:11434 Ollama server URL
ollama_model AION_OLLAMA_MODEL qwen2.5:3b Ollama model for NLU (reuses an existing pulled model if you have one)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check aion/

How it works

  1. Intent classification — Regex patterns match commands (schedule, list, delete, etc.) with confidence scores. Falls back to Ollama LLM for ambiguous input.

  2. Date parsing — Handles "today", "tomorrow", weekday names, "this/next week", specific dates like "March 5th", and common typos.

  3. Constraint solving — The ASP/Clingo solver models the day as 30-minute slots (6AM-10PM), marks busy times from existing events and user preferences, then finds optimal placements with time-of-day preferences.

  4. Google Calendar API — All reads/writes go through Calendar API v3 via httpx async. Token refresh is automatic.


Dependencies

Package Purpose
clingo ASP constraint solver
httpx Async HTTP client (Google Calendar + Ollama)
rich Terminal UI

Privacy

Aion runs entirely on your machine. No calendar data is sent to external servers. See PRIVACY.md for details.

License

MIT License. See LICENSE.

Metadata

Release files for aion-agent 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aion-agent 0.4.0
File Size Uploaded Provenance Actions
aion_agent-0.4.0.tar.gz 44.3 kB Without provenance Details for aion_agent-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aion-agent 0.4.0
File Interpreter ABI Platform Actions
aion_agent-0.4.0-py3-none-any.whl Python 3 none any Details for aion_agent-0.4.0-py3-none-any.whl

Total release size: 87.5 kB

Release files / aion_agent-0.4.0.tar.gz

Download URL aion_agent-0.4.0.tar.gz
Size 44.3 kB
Tags Source
SHA-256 checksum
How to use checksums
7dc40d9a7356447cde5439a78fdae104f3411502bfddc0bc5b201a1116822054
BLAKE2b-256 checksum
How to use checksums
5e01ccc8ce71ddc956bea89116664f22f7ad33f245dfa35625ba06ff6bfd6d56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / aion_agent-0.4.0-py3-none-any.whl

Download URL aion_agent-0.4.0-py3-none-any.whl
Size 43.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b20635baa69ff9b7c28ad09676dc0852f4d5ae4ea60fcbb15156e01d58c967a4
BLAKE2b-256 checksum
How to use checksums
d2090d6628af49be03e56655f892b8d3a93371cc6ba7e672a19e07e90cc628fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for aion-agent 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page