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
-
Intent classification — Regex patterns match commands (schedule, list, delete, etc.) with confidence scores. Falls back to Ollama LLM for ambiguous input.
-
Date parsing — Handles "today", "tomorrow", weekday names, "this/next week", specific dates like "March 5th", and common typos.
-
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.
-
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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aion_agent-0.4.1.tar.gz | 44.9 kB | Without provenance | Details for aion_agent-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aion_agent-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for aion_agent-0.4.1-py3-none-any.whl |
Total release size: 88.7 kB
Release files / aion_agent-0.4.1.tar.gz
| Download URL | aion_agent-0.4.1.tar.gz |
|---|---|
| Size | 44.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c4c70cac4e41f2f878967eb58f8534ed7bdf3de8b7f52b7820fed0b9b54d25e
|
|
BLAKE2b-256 checksum How to use checksums |
21ee271e0d3ec10258f014a4b9b344a2999611d08aafb2191db653ea31cf2174
|
| 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.1-py3-none-any.whl
| Download URL | aion_agent-0.4.1-py3-none-any.whl |
|---|---|
| Size | 43.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b7fbb9a570b6ffbfd1642abc25e0a22a3e07b689ef262e1445a0cb6988339d1a
|
|
BLAKE2b-256 checksum How to use checksums |
39e693a59d9de20f048642f80084273bcf050cc9d1497505a879646f1de92eb0
|
| 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.1
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.